核心用法
youdotcom-cli 是 You.com 官方推出的 schema 驱动 JSON CLI 工具，专为 OpenClaw、Claude Code、Codex、Cursor 等 bash 环境 AI Agent 设计。通过 bunx @youdotcom-oss/api@latest 即可零安装运行，无需本地依赖。
三大核心命令：
- search：基础搜索，支持
livecrawl参数在单次调用中同时完成搜索+页面内容抓取（5秒内返回完整 Markdown） - deep-search：多步深度研究，提供 low（30s）、medium（60s）、high（300s）三档推理深度，输出带内联引用的合成答案
- contents：针对已知 URL 进行多格式内容提取（markdown/html/metadata）
典型工作流：快速查询用 search + livecrawl（<5s），研究分析用 deep-search medium（<60s），综合报告用 deep-search high（<300s）。所有输出均为纯净 JSON，可直接管道到 jq 处理，无 .data 包装层。
显著优点
1. 性能优势：相比内置搜索 API，通过 simultaneous livecrawl 将「搜索+抓取」两步合并为单次 API 调用，显著降低延迟
2. 可验证性：所有结果附带 citation URL，deep-search 提供内联引用与完整来源列表
3. Agent 原生设计：JSON-only 输入（--json 必需）、stdout/stderr 分离、退出码规范（0/1/2）、schema 自发现（--schema 参数），完美适配自动化脚本
4. 轻量无依赖：通过 bunx/npx 运行，无需全局安装，Bun 版本每 24 小时自动检查更新
5. 灵活部署：支持环境变量预设（YDC_API_KEY、YDC_CLIENT）与单命令覆盖
潜在缺点与局限性
- 运行时依赖：强制要求 Node.js 18+ 或 Bun 1.0+，无纯静态二进制版本
- API 密钥成本：You.com API 为付费服务，高频调用需考虑配额与计费
- 深度研究超时：high effort 模式最长 300s，需配合
timeout/gtimeout避免进程挂起 - 平台差异：macOS 需额外安装 coreutils 获取
gtimeout，增加跨平台复杂度 - npx 缓存问题：官方明确提示 npx 存在缓存缺陷，可能无法获取最新版本，推荐 bunx
适合人群
- 构建 bash-based AI Agent 的开发者（OpenClaw、Claude Code、Codex、Cursor 等环境）
- 需要「搜索+即时内容提取」一体化能力的自动化工作流
- 追求可验证引用、厌恶幻觉的研究型 AI 应用
- 熟悉 jq、管道操作、JSON schema 的技术用户
常规风险
1. API 密钥泄露：YDC_API_KEY 以环境变量或命令行参数传递，在多用户环境或日志中可能暴露
2. 超时处理不当：deep-search high 模式 300s 超时需外部 timeout 命令，遗漏将导致进程阻塞
3. 退出码误判：错误信息输出到 stderr，脚本若仅检查 stdout 可能误判成功状态
4. 速率限制：高频并行调用可能触发 API 限流，需实现重试逻辑（文档提供 3 次重试示例）
5. 内容可靠性：虽提供引用，但 source credibility 取决于抓取网页本身，非 You.com 背书