volcengine-knowledge-search 火山引擎文档检索技能

火山引擎官方文档综合查询技能，提供 search（检索） 与 fetch（全文获取） 两个能力。火山引擎文档是火山最权威的官方数据，覆盖全产品使用全链路。接口为公开文档服务，无需 AK/SK 鉴权，脚本用 Python3 标准库实现（仅依赖 python3，无需 curl/jq）。

脚本会在本地把上游响应 解析 + 裁剪 + 清洗成干净 markdown 文本再输出（search 每条只回摘要、fetch 按页返回），避免把「整篇正文 × N、单行几十~上百 KB」的原始 JSON 灌进上下文。所以脚本输出可直接阅读/引用，不需要你再解析 JSON。

什么时候用

• 用户咨询火山引擎产品的概念、用法、计费规则、部署步骤、最佳实践、服务条款/协议等可在官方文档中找到解释的问题
• 用户给出一条火山引擎官方文档链接（https://www.volcengine.com/docs/...），需要取该文档全文
• 用户消息里出现「火山」「火山引擎」「volcengine」且属于查官方文档 / 读文档全文的场景

命令速查

脚本位于 scripts/volcengine_docs.py，{skill_dir} 为本 skill 目录。

search

python3 {skill_dir}/scripts/volcengine_docs.py search "tos 怎么计费" 3

参数：

输出：已整理好的 markdown 文本，每条命中一段：

## 1. \x3C标题>
\x3C纯净URL>
ServiceCodes: \x3C产品编码,逗号分隔>

\x3C正文摘要，默认前 600 字，已清掉 HTML 标签>
---

直接阅读/引用即可，无需再解析 JSON。摘要字数可用环境变量 VOLC_SEARCH_SNIPPET 调整。ServiceCodes 行用于二次精搜（见示例 4）。

如何写好 query —— 这是「向量语义检索」,不是关键词精确匹配

本接口底层是向量库语义检索（embedding 召回）,而非倒排索引的关键词精确匹配。query 写得好不好,直接决定召回质量。把握一个核心:让 query 在语义上尽量贴近目标文档里的正式表述。

写 query 的要点:

• 用完整的自然语言描述,而非孤立短词。 例如查产品订阅价格,写「火山方舟 Coding Plan AI 编程订阅套餐 价格 计费」,而不是只写「Coding Plan」。短词/单个英文缩写语义太稀疏,极易召回跑偏(实测只搜「Coding Plan」会召回 DataFinder、RTC 等完全无关文档)。
• 补全产品全称与上下文。 用户常用简称、营销名、口语词(如「方舟」「豆包编程」「code plan」);先在 query 里补上官方全称 + 所属产品 + 具体方向(如「火山方舟大模型服务 模型推理 计费规则」),让向量更聚焦。
• 优先用「问题 / 描述」句式,而非命令式。 向量更亲近文档正文的陈述语气,「TOS 跨区域复制如何配置」优于「配 TOS 复制」。
• 首搜跑偏就换语义等价的说法重写,而不是重试同一句。 同一概念可能有多种表述,换近义描述(中英、全称/简称、功能动词)往往能召回到正确文档。
• 专有新名词(新产品、新功能、营销活动名)召回差时,把它「翻译」成它实际属于的产品 + 能力描述再搜,定位到正确产品后,可用返回的 ServiceCodes 带产品编码二次精搜(见示例 4)。

真实对比(实测):用户问「火山引擎 Coding Plan 什么价格、如何接入」。

# 坏 query:直接用短英文营销词,语义稀疏 → 召回空 / 命中 DataFinder、RTC 等完全无关产品
python3 {skill_dir}/scripts/volcengine_docs.py search "Coding Plan" 5

# 好 query:补全产品全称(火山方舟)+ 能力(AI 编程订阅套餐)+ 方向(价格 计费)
python3 {skill_dir}/scripts/volcengine_docs.py search "火山方舟 Coding Plan AI 编程订阅套餐 价格 计费规则" 5
# → 5 条结果全部命中 ark 产品:套餐概览 / 接入三方工具 / 限时邀请活动 / 常见问题 / 模型价格

同一需求,只因 query 表述不同,召回质量天差地别。遇到简称、英文缩写、营销名,先补成「产品全称 + 能力描述 + 具体方向」再搜。

fetch

python3 {skill_dir}/scripts/volcengine_docs.py fetch "https://www.volcengine.com/docs/6349/162514?lang=zh"

脚本会自动剥离 URL 的 query / fragment 参数（如 ?lang=zh），只用纯净路径请求。输出是整理好的 markdown 文本：首行 # 标题、次行纯净链接、空行后是正文。

分页：正文按 max_length（默认 5000 字符）截断，未读完时结尾追加一行 【续读】还有 N 字。…加参数 start_index=M 继续读。。要续读就用同一 URL 再调一次并带上提示里的 start_index。单页字数可用 VOLC_FETCH_MAX 调整。

先看链接结构再决定能不能 fetch：

• https://www.volcengine.com/docs/{产品编号}/{文档ID}（两级，如 docs/6349/162514）才是具体文章，fetch 能取到正文。
• https://www.volcengine.com/docs/{产品编号}（只有一级编号，如 docs/6459）是某个产品的文档中心首页 / 栏目导航页，不是文章。对它 fetch 会返回一段提示 JSON（{"info": "该链接无正文…", "CleanUrl": …}，退出码 0），表示没有正文可取。遇到这种链接不要反复重试 fetch，按下面的兜底处理。

一级导航页链接的兜底策略：

1. 用 search 检索该产品名 / 用户真正关心的具体方向，从结果里定位到两级的具体文章链接，再对其 fetch。
2. 向用户说明：该链接是产品文档导航首页而非具体文章，并主动询问想深入了解哪个具体方向，再帮其定位。

决策逻辑

1. 用户直接给了文档链接 → 直接走 fetch，无需先检索。
2. 用户提问类需求 → 先把用户原话改写成贴近文档表述的自然语言 query(向量检索,见「如何写好 query」),再走 search（默认不带 ServiceCodes），用脚本输出的摘要直接回答。
3. 首次检索匹配度不高 → 取返回结果里的 ServiceCodes，带上对应产品编码做二次检索缩小范围。
4. 需要某篇文档完整正文 → 先 search 找到链接，再 fetch 取全文。

常见使用示例

下面每个场景对应一种典型用户提问，演示「怎么选命令 + 怎么回答」。命令里的 {skill_dir} 换成本 skill 目录。

示例 1 · 产品概念 / 计费咨询（最常见，search 直接答）

用户：「火山引擎 TOS 是什么？怎么计费？」

直接检索，用脚本输出的摘要组织回答，末尾附官方链接：

python3 {skill_dir}/scripts/volcengine_docs.py search "对象存储 TOS 是什么 计费方式" 3

示例 2 · 报错 / 故障排查（search 报错关键词）

用户：「调用火山 OpenAPI 返回 SignatureDoesNotMatch 是什么原因？」

把报错码 + 场景作为关键词检索，从结果里定位排查文档：

python3 {skill_dir}/scripts/volcengine_docs.py search "OpenAPI SignatureDoesNotMatch 签名错误 排查" 3

示例 3 · 用户直接给了文档链接（跳过 search，直接 fetch）

用户：「帮我读一下 https://www.volcengine.com/docs/6349/74820 这篇，讲了啥」

不需要检索，直接取全文，再用脚本输出的 markdown 正文总结（长文用 start_index 翻页）：

python3 {skill_dir}/scripts/volcengine_docs.py fetch "https://www.volcengine.com/docs/6349/74820"

示例 4 · 首次检索太宽 → 带产品编码二次缩范围

用户：「跨区域复制怎么做？」（问法宽泛，可能命中多个产品）

先宽泛检索，看首次结果里目标文档的 ServiceCodes（如对象存储是 tos），原样带上做二次检索：

python3 {skill_dir}/scripts/volcengine_docs.py search "跨区域复制 怎么配置" 5
python3 {skill_dir}/scripts/volcengine_docs.py search "跨区域复制 怎么配置" 3 tos

示例 5 · 要完整步骤 → 先 search 定位，再 fetch 取全文

用户：「给我用 TOS Browser 上传文件的完整步骤」

第 1 步检索找到最匹配的一篇，从输出里每条的 URL 行取链接；第 2 步对该链接 fetch 取全文，再整理成步骤：

python3 {skill_dir}/scripts/volcengine_docs.py search "TOS Browser 上传文件 步骤" 3
python3 {skill_dir}/scripts/volcengine_docs.py fetch "https://www.volcengine.com/docs/6349/162514"

结果处理规则

0. stdout 是预览 + 落盘：脚本把 stdout 限制在 ~4KB（VOLC_PREVIEW_BYTES），避免长输出打断任务。若结果超限，stdout 末尾会给 …完整 N 字节已保存到：\x3C临时文件路径>，此时用 Read 工具读该文件（大文件用 offset/limit 分段，不要 cat 整个文件）获取全文；未超限则直接全量打印。
1. 优先用脚本输出的 markdown 文本回答，它已解析裁剪好，无需再解析 JSON 或额外提炼。
2. 回答末尾必须附官方文档链接作为来源，格式 [文档标题](纯净URL)，每条结果都要标注。
3. 链接用脚本输出里的纯净 URL（已剥离 ?lang=zh 等参数），禁止使用带参数的 URL。
4. 多个结果按相关性排序，最多展示 3 条最相关的，每条都带链接。

常见问题

• 请求超时 / 失败：urllib 超时 15 秒，网络层失败时返回 {"error": ...} 并以非零退出码结束；可重试或换关键词。
• search 输出 {"info": "无结果或后端抖动…", "backend_error": …}：火山文档后端偶发抖动（DownstreamError / DocList 空，非脚本问题），退出码仍为 0，重试一两次即可恢复；backend_error 非空基本就是后端抖动。
• fetch 输出 {"info": "该链接无正文…"}：多半是传入了 docs/{产品编号} 这种只有一级编号的导航首页链接（不是具体文章，没有正文可取），不是后端抖动，重试无用。按 fetch 小节的「一级导航页链接的兜底策略」处理：改用 search 定位两级具体文章，并向用户说明这是导航首页。
• 检索结果不准 / 召回完全跑偏：本接口是向量语义检索,跑偏多半是 query 太短、太英文缩写、太营销口语(如只搜「Coding Plan」会召回无关产品)。先按「如何写好 query」把 query 重写成完整自然语言描述 + 产品全称,再用首次返回的 ServiceCodes 做带产品编码的二次检索（见示例 4）。换语义等价说法重写,比重复同一句重试有效得多。
• fetch 报错：确认链接是 https://www.volcengine.com/docs/... 形式的官方文档链接。