You.com Web Search & Research CLI

核心用法

You.com CLI (@youdotcom-oss/api) 是专为 bash 环境 AI Agent 设计的搜索与内容提取工具，通过 schema-driven JSON 接口实现程序化调用。三大核心命令：

• `search`：极速网页搜索（<5s），支持 livecrawl 参数在单次调用中同时获取搜索结果和完整页面内容，无需二次请求
• `deep-search`：多步推理深度研究，30-300s 可调，生成带内联引用的综合答案
• `contents`：指定 URL 直接提取内容，支持 markdown/html/metadata 多格式输出

所有命令强制 --json 参数传递结构化输入，支持 --schema 发现可用字段，输出直返 JSON（无 .data 包装），天然适配 jq 管道处理。

显著优点

1. 性能优势：相比内置搜索 API，同时执行搜索与实时爬取，省去串行请求时间；底层基础设施专为 Agent 高并发优化
2. 可验证引用：每条结果附带 URL 引用，deep-search 生成内联标注 [1] 式学术引用
3. 轻量无依赖：bunx/npx 直接运行，无需全局安装，24小时自动检查更新
4. Agent 原生设计：stdout/stderr 分离、退出码规范（0/1/2）、mailto 错误报告支持 --client 标识追踪
5. Schema 驱动：程序化发现参数，动态构建查询，降低硬编码维护成本

潜在缺点与局限

• 运行环境依赖：强制 Node.js 18+ 或 Bun 1.0+，环境缺失时需安装运行时
• API Key 成本：You.com Platform 需注册获取 YDC_API_KEY，存在速率限制与配额消耗
• 深度搜索耗时：high effort 模式最长 300s，需配合 timeout/gtimeout 避免阻塞
• npx 缓存陷阱：官方明确提示 npx 有缓存缺陷，推荐 bunx 确保获取最新版本
• 无内置重试：需自行实现退避重试逻辑处理 429/网络抖动

适合人群

• 使用 OpenClaw、Claude Code、Codex、Cursor 等 bash-based AI Agent 的开发者
• 需要可验证来源的自动化研究/报告生成工作流
• 追求单次调用获取搜索+全文内容的低延迟场景
• 熟悉 jq 与管道处理的 CLI 重度用户

常规风险

• API Key 泄露：环境变量或脚本硬编码密钥需妥善保管，避免提交至版本控制
• 超时失控：deep-search high 模式 300s 上限，生产环境务必包裹 timeout 命令
• 内容合规：livecrawl 抓取任意网页可能触及版权或敏感内容，需结合 safesearch 参数与业务合规审查
• 供应商锁定：深度绑定 You.com API 定价与可用性，建议抽象封装便于迁移
• Schema 变更：依赖 --schema 发现的动态查询可能因上游字段调整而失效，关键生产查询建议显式指定字段

核心功能与用法

youdotcom-cli 是一套面向 bash 环境 AI Agent（OpenClaw、Claude Code、Codex、Cursor 等）的 You.com API 命令行工具集。Skill 本身为纯 Markdown 文档，提供完整的 CLI 使用指南与代码示例，无本地可执行代码。

三大核心工具

| 工具 | 场景 | 特性 |

|------|------|------|

| `search` | 快速搜索 | <5s 响应，支持 `livecrawl` 实时抓取内容 |

| `deep-search` | 深度研究 | 30-300s 多级推理，带内联引用 |

| `contents` | 内容提取 | 多格式输出（markdown/html/metadata） |

Schema 驱动设计

所有命令通过 --json 接收结构化参数，支持 --schema 发现可用字段：

bunx @youdotcom-oss/api@latest search --schema | jq '.properties | keys'

关键优势：Livecrawl

单次 API 调用同时完成搜索与内容提取，无需二次抓取：

bunx @youdotcom-oss/api@latest search --json '{
  "query": "AI developments",
  "livecrawl": "web",
  "livecrawl_formats": "markdown"
}' --client OpenClaw

深度研究分级

| effort | 耗时 | 适用场景 |

|--------|------|----------|

| low | <30s | 快速验证 |

| medium | <60s | 默认平衡（推荐） |

| high | <300s | 综合深度分析 |

显著优点

1. 性能优化：专为 Agent 工作负载设计的基础设施，并发搜索+爬取
2. 引用可验证：所有结果附带 citation URL，支持研究级溯源
3. 管道友好：纯 JSON stdout，无包装层，直接适配 jq/grep/awk
4. 零本地依赖：通过 bunx/npx 直接运行，无需全局安装
5. 跨平台：支持 Node.js 18+ 或 Bun，含 Linux/macOS 超时处理方案

局限性与注意事项

1. 外部依赖必需要求：必须安装 Bun/Node.js 并配置 YDC_API_KEY
2. curl\|bash 安装模式：Bun 安装脚本使用远程管道执行（行业标准做法，来源可信）
3. @latest 版本浮动：默认使用最新版，生产环境建议锁定具体版本号
4. 网络依赖：所有功能依赖 You.com 官方 API 可用性
5. 耗时操作需超时：deep-search high 可能运行 5 分钟，需配合 timeout/gtimeout

适合人群

• AI Agent 开发者：需为 bash 环境 Agent 添加网页搜索能力
• 自动化脚本编写者：需要结构化 JSON 输出的命令行搜索工具
• 研究人员：需要带引用的深度研究（deep-search）与内容溯源
• CI/CD 集成场景：轻量级 CLI 适合流水线自动化

安全风险与缓解

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 远程脚本安装 (curl\|bash) | 低 | Bun 官方标准做法，域名可信 |

| 外部 npm 包依赖 | 低 | @youdotcom-oss/api 为 You.com 官方维护 |

| API Key 管理 | 信息级 | 遵循 envvar 最佳实践，无硬编码 |

| 网络通信 | 低 | 仅连接 you.com/bun.sh 官方服务，TLS 1.3 |

关键建议：生产环境使用 @1.2.0 等固定版本替代 @latest，降低供应链风险。