Volcengine Ark Web Search

概述

当任务需要获取最新的公开网页信息，且运行时必须通过 Volcengine ARK Responses API（而非模型内置的浏览能力）完成时，请使用本技能。配套脚本将 ARK responses 封装为 web_search 工具，输出默认适配中文场景，并适用于可重复的自动化流程或本地 agent 工作流。

默认的 Markdown 输出结构已稳定为以下三个部分：

• 标题（title）
• 摘要（summary）
• 来源（sources）

适用场景

• 用户询问今日新闻、近期动态、当前公共报道或实时事实核查内容。
• 你需要最新网页结果，但必须经由 Volcengine ARK 路由，且已配置 ARK_API_KEY。
• 你需要一个可复用的本地命令，以便在脚本、cron 任务或其他技能中共享调用。
• 答案应优先采用中文输出，明确标注日期，并附带来源链接。
• 你需要在回答前比对或验证公开网页信息。

不适用场景

• ARK_API_KEY 未配置。
• 任务本身是静态的，无需获取当前网页信息。
• 你需要的是浏览器自动化、登录态会话或面向特定网站的交互操作，而非通用搜索。
• 必须使用其他供应商的服务。

快速开始

1. 确认已设置 ARK_API_KEY 环境变量。
2. 运行配套脚本。
3. 对返回结果进行摘要，明确标注日期并附上来源链接。

基础用法：

python3 scripts/ark_web_search.py "What are today's AI news headlines?"

中文查询：

python3 scripts/ark_web_search.py "今天有什么热点新闻"

指定模型：

python3 scripts/ark_web_search.py "OpenAI latest announcements" 
  --model doubao-seed-1-6-250615

结构化 JSON 输出：

python3 scripts/ark_web_search.py "latest semiconductor policy news" 
  --format json

延长超时时间并启用快速重试：

python3 scripts/ark_web_search.py "OpenAI latest news" 
  --timeout 90 
  --retries 2

仅预演（dry run），不发起网络请求：

python3 scripts/ark_web_search.py "today's EV market news" 
  --dry-run

核心工作流

1. 必要时将用户请求重写为直接的搜索问题；优先显式写出关键实体、主题和时间范围。
2. 除非任务明确要求原始透传行为，否则使用默认系统提示词（system prompt）。
3. 执行 scripts/ark_web_search.py。
4. 若脚本返回足够有效信号，则默认以中文生成摘要；仅当用户明确要求其他语言时例外。
5. 对于“今天”“最近”等相对时间表述，在最终答案中须转换为绝对日期。

输出要求

• 优先采用简洁摘要加链接的形式。
• 默认 Markdown 输出需保持结构稳定、便于快速浏览：标题 → 摘要 → 来源。
• 当搜索结果稀疏或存在冲突时，需如实保留不确定性，不可强行断言。
• 若存在可用来源，必须予以列出。
• 尽可能将相对时间表述（如“上周”“本月”）转换为具体日期。
• 若 API 返回结果不足以支撑回答，应明确说明，切勿编造事实。

相关文件

• scripts/ark_web_search.py：封装 ARK Responses API 的 web_search 调用器，支持 dry-run、流式响应（streaming）及来源链接自动提取。
• references/ark-responses-api.md：关于请求格式、模型漂移（model drift）、工具命名变更（tool naming drift）及维护参考的说明文档。

维护说明

• 建议通过 --model 参数或 ARK_MODEL 环境变量覆盖默认模型；ARK 可用模型列表会随时间变化。
• --timeout 表示单次尝试的超时时间；请配合 --retries 实现瞬时故障下的快速重试。
• 部分 ARK 环境会在携带 search_context_size 字段时返回 HTTP 400 错误；本脚本检测到该错误后将自动剔除该字段并重试。
• 默认系统提示词要求模型仅输出摘要正文；标题与来源部分由脚本统一添加，以保障输出结构稳定性。
• Volcengine 官方文档历史上曾同时出现 web_search 和 web_search_preview 两种工具名；本技能默认使用 web_search，仅当目标环境官方文档明确要求时才可变更。
• 若上游 API 变更导致响应解析失败，请更新 scripts/ark_web_search.py 中的归一化逻辑，并同步维护 references/ark-responses-api.md 文档。