用途
you-web-search 是一个网页搜索技能，通过 You.com 的 Search API 获取当前、高质量的网络信息。相比基础 WebSearch，它提供相关性排序、引用提取、结构化结果以及可选的实时网页抓取能力。
主要能力
- 高质量结果：带相关性排序与引用提取。
- 零配置可用：keyless 层级无需密钥、钱包或注册。
- 实时网页抓取：在 keyed 层级启用 livecrawl=web 时可获取新鲜内容。
- 结构化结果格式：包含标题、URL、摘要片段和发布日期。
- 可选 livecrawl 控制：通过 YOUCOM_LIVECRAWL 环境变量在需要整页抓取时启用。
- 自动回退：任何 You.com 调用失败都会回退到内置 WebSearch，保证运行不空手而归。
认证模式
| 模式 | 触发条件 | 端点 | 限制 |
|---|---|---|---|
| keyless | 未设置 YDC_API_KEY | https://api.you.com/v1/agents/search | 每 IP 每天 100 次搜索，无 livecrawl |
| keyed | 已设置 YDC_API_KEY | https://api.you.com/v1/search | 按套餐限额，可用 livecrawl |
使用方式
技能按三个阶段执行：
- 执行搜索：先检测 YDC_API_KEY 是否设置以确定认证模式（缺失密钥不是错误，会走 keyless 层级）。两种模式通过 ./secretcurl 调用同一 REST 契约；keyed 模式在辅助脚本内替换 {YDC_API_KEY} 占位符，keyless 模式不发送密钥头。请求参数包括 query、count（默认 10）、safesearch=strict、freshness（默认 week，可用 YOUCOM_FRESHNESS 覆盖）。livecrawl 仅 keyed 层级支持，keyless 端点会返回 402。
- 格式化结果：解析响应中的 web 与 news 结果，提取标题、URL、摘要、日期；应用质量过滤（排除缺失或占位标题、跳过无有效 URL 的结果、过滤低质内容、对同域近似结果去重），并按统一格式输出。
- 交付与记录：通过 ./notify 发送格式化结果，包含查询、结果数量、来源归属、实际使用的认证模式、回退原因（如发生）以及 livecrawl 信息。技能为只读，日志条目由工作流的只读守卫写入，不应自行追加到 memory/logs/。
环境变量
- YDC_API_KEY（可选）：You.com API 密钥。未设置时使用免费 keyless 层级（每 IP 每天 100 次搜索，无 livecrawl）；设置后使用 keyed Search API，按套餐限额并支持 livecrawl。密钥可在 https://you.com/platform 获取。
- YOUCOM_FRESHNESS（可选）：新鲜度过滤（day、week、month、year 或日期范围）。
- YOUCOM_LIVECRAWL（可选，仅 keyed）：需要整页内容时传递给 livecrawl（web、news 或 all）；keyless 层级忽略。
适用场景
- 研究任务、事实核查、时事追踪、具体查询。
- 与其他技能配合：digest（每日摘要的网络信号）、article（文章生成的研究支持）、github-trending（趋势仓库评估的上下文）、token-pick（市场研究与催化剂发现）、mention-radar（超越 X/Twitter 的网页提及检测）。
- 调度建议：按需手动执行；低频自动搜索（每天或更低）以尊重配额；避免高于每小时的频率，keyless 层级每 IP 每天上限 100 次。
限制与错误处理
- keyless 401：keyless 模式不发送密钥，401 并非凭证问题。部分区域会因非 ASCII 地区名（如 Île-de-France）触发服务端问题，国家/语言参数无法规避；设置 YDC_API_KEY 使用 keyed 端点不受影响。
- 速率限制（429）：keyless 模式通常是每 IP 每天 100 次上限，建议设置 YDC_API_KEY；keyed 模式建议检查套餐配额。
- 需要付费（402）：请求需要 keyed 层级（如无密钥使用 livecrawl），建议设置 YDC_API_KEY。
- 无效密钥（keyed 模式 401/403）：提示检查 YDC_API_KEY。
- 服务器错误（5xx）：瞬时问题，回退并记录原因。
- 网络失败：回退并记录 reason=NETWORK。
- 响应格式异常：200 但 jq 无法解析，回退并记录 reason=PARSE。
- 空结果：200 但零结果，回退并记录 reason=EMPTY；若 WebSearch 也为空，建议优化查询或使用更宽泛的词。
- 每次运行只回退一次；必须如实报告结果来自 You.com 还是 WebSearch 回退，不得将回退结果冒充为 You.com 结果。
- 约束：不在日志或通知中暴露凭证；始终标注来源；优雅处理 429；验证 URL 真实可访问；过滤低质或离题结果；任何 You.com 失败都回退到 WebSearch 并记录 youcom fallback=websearch reason=<REASON>。