volcengine-knowledge-search · diff
git:20260810.b6aad39 to git:20260907.d15b8eb
55 added, 133 removed. Audit A to A.
---
name: volcengine-knowledge-search
- description: "火山引擎官方文档检索与全文获取技能：对火山引擎官方文档站（www.volcengine.com/docs）做语义检索并抓取正文。Use when 用户咨询火山引擎产品的概念、用法、计费规则、部署步骤、最佳实践、服务条款/协议等可在官方文档中找到解释的问题，或用户直接给出火山引擎官方文档链接（www.volcengine.com/docs/...）需要取全文时。"
+ description: "使用 ve docs search/fetch 检索火山引擎官方文档并获取全文。Use when 用户咨询火山引擎产品的概念、用法、计费规则、部署步骤、最佳实践或服务条款，或提供 www.volcengine.com/docs/、docs.volcengine.com/docs/ 链接需要阅读正文时。"
license: MIT
metadata:
openclaw:
requires:
bins:
- - python3
+ - ve
+ install:
+ - kind: node
+ package: "@volcengine/cli"
+ bins: [ve]
---
- # volcengine-knowledge-search 火山引擎文档检索技能
-
- 火山引擎官方文档综合查询技能，提供 **search（检索）** 与 **fetch（全文获取）** 两个能力。火山引擎文档是火山最权威的官方数据，覆盖全产品使用全链路。接口为公开文档服务，**无需 AK/SK 鉴权**，脚本用 **Python3 标准库**实现（仅依赖 `python3`，无需 curl/jq）。
-
- > 脚本会在本地把上游响应 **解析 + 裁剪 + 清洗成干净 markdown 文本**再输出（search 每条只回摘要、fetch 按页返回），避免把「整篇正文 × N、单行几十~上百 KB」的原始 JSON 灌进上下文。所以**脚本输出可直接阅读/引用，不需要你再解析 JSON**。
-
- ## 什么时候用
-
- - 用户咨询火山引擎产品的概念、用法、计费规则、部署步骤、最佳实践、服务条款/协议等可在官方文档中找到解释的问题
- - 用户给出一条火山引擎官方文档链接（`https://www.volcengine.com/docs/...`），需要取该文档全文
- - 用户消息里出现「火山」「火山引擎」「volcengine」且属于查官方文档 / 读文档全文的场景
-
- ## 命令速查
+ # volcengine-knowledge-search 火山引擎文档检索
- 脚本位于 `scripts/volcengine_docs.py`，命令均相对本 skill 目录根执行。
+ 通过 `ve docs search` 检索官方文档，通过 `ve docs fetch` 获取正文。请求、响应解析、正文清洗和分页由 CLI 处理；本 skill 负责场景判断、query 改写、二次检索和来源引用。
- | 子命令 | 用途 | 形式 |
- |--------|------|------|
- | `search` | 关键词检索文档 | `search "<关键词>" [返回数量] [产品编码1,产品编码2...]` |
- | `fetch` | 取单篇文档全文(分页) | `fetch "<火山引擎文档链接>" [start_index] [max_length]` |
+ ## 准备
- ### search
+ 首次使用时确认本机具备两个子命令：
```bash
- python3 scripts/volcengine_docs.py search "tos 怎么计费" 3
- ```
-
- 参数：
-
- | 参数 | 必填 | 说明 |
- |------|------|------|
- | 查询关键词 | 是 | 完整的自然语言问题/描述,贴近文档正式表述;**不是**关键词堆砌或英文缩写(见下方「如何写好 query」) |
- | 返回数量 | 否 | 检索返回文档数，默认 10 |
- | 产品编码 | 否 | 逗号分隔，限定仅查某几个产品；编码取自上一次返回的 `ServiceCodes` |
-
- **输出**：已整理好的 markdown 文本，每条命中一段：
-
- ```text
- ## 1. <标题>
- <纯净URL>
- ServiceCodes: <产品编码,逗号分隔>
-
- <正文摘要，默认前 600 字，已清掉 HTML 标签>
- ---
+ ve docs search --help
+ ve docs fetch --help
```
- 直接阅读/引用即可，无需再解析 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 什么价格、如何接入」。
-
- ```bash
- # 坏 query:直接用短英文营销词,语义稀疏 → 召回空 / 命中 DataFinder、RTC 等完全无关产品
- python3 scripts/volcengine_docs.py search "Coding Plan" 5
+ 若 `ve` 未安装或缺少子命令，加载 `volcengine-cli` skill，按其「Install or upgrade the ve CLI」章节安装最新版，再检查能力。文档命令访问公开服务，**无需登录、AK/SK、profile 或地域配置**；安装后直接使用，无需执行资源管理的身份初始化流程。
- # 好 query:补全产品全称(火山方舟)+ 能力(AI 编程订阅套餐)+ 方向(价格 计费)
- python3 scripts/volcengine_docs.py search "火山方舟 Coding Plan AI 编程订阅套餐 价格 计费规则" 5
- # → 5 条结果全部命中 ark 产品:套餐概览 / 接入三方工具 / 限时邀请活动 / 常见问题 / 模型价格
- ```
+ ## 选择流程
- 同一需求,只因 query 表述不同,召回质量天差地别。**遇到简称、英文缩写、营销名,先补成「产品全称 + 能力描述 + 具体方向」再搜。**
+ 1. **用户提供具体文章链接**：直接 `fetch`，读取与问题相关的正文。
+ 2. **用户提出问题**：补全产品名和具体方向后 `search`，首次检索不带产品过滤。根据标题、摘要和产品编码判断相关性。
+ 3. **结果过宽或不相关**：改写 query；只有结果中已确认目标产品的 `ServiceCodes` 时，才使用该编码二次检索。不要把无关命中的编码用作过滤条件。
+ 4. **需要完整步骤、限制条件、精确计费规则或全文总结**：对相关结果的 URL 执行 `fetch`，按需续读；用户要求全文时，读到没有续读提示或 `has_more=false`。
- ### fetch
+ ## search：检索文档
```bash
- python3 scripts/volcengine_docs.py fetch "https://www.volcengine.com/docs/6349/162514?lang=zh"
+ ve docs search "对象存储 TOS 如何计费" --limit 3 --output text
```
- 脚本会自动剥离 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 目录根执行。
+ 搜索文本是**位置参数**，用引号包住完整问题。用 `--output text` 获取可直接阅读的 Markdown：每条包含标题、纯净 URL、`ServiceCodes` 和正文摘要。CLI 默认输出 JSON；需要程序化处理时显式用 `--output json`，结果在 `documents` 数组中，字段为 `title`、`url`、`service_codes`、`snippet`。
- ### 示例 1 · 产品概念 / 计费咨询（最常见，search 直接答）
+ | 参数 | 用途 |
+ | --- | --- |
+ | `--limit N` | 返回文档数，正整数；一般先取 3 条 |
+ | `--service-code CODE` | 限定产品，编码取自已确认相关的结果；多个产品重复传此选项 |
+ | `--snippet-length N` | 每条摘要的最大 Unicode 字符数，正整数；用它控制上下文体积 |
- > 用户：「火山引擎 TOS 是什么？怎么计费？」
+ ### 改写 query
- 直接检索，用脚本输出的摘要组织回答，末尾附官方链接：
+ 语义检索需要贴近文档表述。将口语、简称或营销名补成**产品全称 + 能力描述 + 具体问题**，例如把「Coding Plan 多少钱」改写为「火山方舟 Coding Plan AI 编程订阅套餐如何计费」。首搜跑偏时，换全称、近义描述或功能描述再搜。
```bash
- python3 scripts/volcengine_docs.py search "对象存储 TOS 是什么 计费方式" 3
+ ve docs search "火山方舟 Coding Plan AI 编程订阅套餐如何计费" --limit 3 --output text
```
- ### 示例 2 · 报错 / 故障排查（search 报错关键词）
-
- > 用户：「调用火山 OpenAPI 返回 SignatureDoesNotMatch 是什么原因？」
-
- 把报错码 + 场景作为关键词检索，从结果里定位排查文档：
+ 先宽搜，确认相关结果的 `ServiceCodes` 为 `tos` 后，按产品精搜：
```bash
- python3 scripts/volcengine_docs.py search "OpenAPI SignatureDoesNotMatch 签名错误 排查" 3
+ ve docs search "跨区域复制如何配置" --limit 5 --snippet-length 300 --output text
+ ve docs search "对象存储 TOS 跨区域复制如何配置" --limit 3 --service-code tos --output text
```
- ### 示例 3 · 用户直接给了文档链接（跳过 search，直接 fetch）
+ 多个产品编码使用 `--service-code <code-a> --service-code <code-b>`，每个编码单独传递。
- > 用户：「帮我读一下 https://www.volcengine.com/docs/6349/74820 这篇，讲了啥」
+ ## fetch：获取正文
- 不需要检索，直接取全文，再用脚本输出的 markdown 正文总结（长文用 `start_index` 翻页）：
+ 支持 `https://www.volcengine.com/docs/...` 和 `https://docs.volcengine.com/docs/...`。CLI 会去掉 URL 的 query 和 fragment，text 输出依次为标题、纯净 URL、当前页正文及续读提示。
```bash
- python3 scripts/volcengine_docs.py fetch "https://www.volcengine.com/docs/6349/74820"
+ ve docs fetch "https://www.volcengine.com/docs/6349/162514?lang=zh" --output text
```
- ### 示例 4 · 首次检索太宽 → 带产品编码二次缩范围
-
- > 用户：「跨区域复制怎么做？」（问法宽泛，可能命中多个产品）
+ | 参数 | 用途 |
+ | --- | --- |
+ | `--start-index N` | 从第 N 个 Unicode 字符开始，索引从 0 起 |
+ | `--max-length N` | 当前页最多返回的 Unicode 字符数，正整数；默认 5000 |
- 先宽泛检索，看首次结果里目标文档的 `ServiceCodes`（如对象存储是 `tos`），原样带上做二次检索：
+ 长文末尾会提示下一页的 `--start-index`。用**同一个 URL 和返回的索引**继续读，避免漏读或重复。以下示例先取 300 字，若续读提示为 `--start-index 300`，再读取下一页：
```bash
- python3 scripts/volcengine_docs.py search "跨区域复制 怎么配置" 5
- python3 scripts/volcengine_docs.py search "跨区域复制 怎么配置" 3 tos
+ ve docs fetch "https://www.volcengine.com/docs/6349/162514" --max-length 300 --output text
+ ve docs fetch "https://www.volcengine.com/docs/6349/162514" --start-index 300 --max-length 300 --output text
```
- ### 示例 5 · 要完整步骤 → 先 search 定位，再 fetch 取全文
-
- > 用户：「给我用 TOS Browser 上传文件的完整步骤」
-
- 第 1 步检索找到最匹配的一篇，从输出里每条的 URL 行取链接；第 2 步对该链接 `fetch` 取全文，再整理成步骤：
-
- ```bash
- python3 scripts/volcengine_docs.py search "TOS Browser 上传文件 步骤" 3
- python3 scripts/volcengine_docs.py fetch "https://www.volcengine.com/docs/6349/162514"
- ```
+ 程序化分页使用 `--output json`，读取 `content`、`start_index`、`next_start_index`、`remaining_characters`、`has_more` 和 `has_content`。`has_more=true` 时用 `next_start_index` 续读；结束时该字段为 `null`。
- ## 结果处理规则
+ ### 导航页与空正文
- 0. **stdout 是预览 + 落盘**：脚本把 stdout 限制在 ~4KB（`VOLC_PREVIEW_BYTES`），避免长输出打断任务。若结果超限，stdout 末尾会给 `…完整 N 字节已保存到：<临时文件路径>`，此时用 **Read 工具读该文件**（大文件用 `offset/limit` 分段，**不要 `cat` 整个文件**）获取全文；未超限则直接全量打印。
- 1. **优先用脚本输出的 markdown 文本回答**，它已解析裁剪好，无需再解析 JSON 或额外提炼。
- 2. **回答末尾必须附官方文档链接**作为来源，格式 `[文档标题](纯净URL)`，每条结果都要标注。
- 3. **链接用脚本输出里的纯净 URL**（已剥离 `?lang=zh` 等参数），禁止使用带参数的 URL。
- 4. 多个结果按相关性排序，最多展示 3 条最相关的，每条都带链接。
+ - `/docs/{产品编号}/{文档ID}` 是具体文章路径。
+ - `/docs/{产品编号}` 是产品文档导航页，没有单篇文章正文。识别到这种链接时，按产品名和用户关心的方向 `search`，从结果定位具体文章再 `fetch`，并向用户说明链接类型。
+ - `has_content=false` 表示没有取得正文，不能据此编造内容。检查链接是否为导航页、过期或错误地址，再用 `search` 定位替代文档。
- ## 常见问题
+ ## 结果与错误处理
- - **请求超时 / 失败**：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/...` 形式的官方文档链接。
+ - **按证据回答**：摘要足以支撑的概念问题可以直接回答；精确规则和完整步骤先取正文。部分页面不能表述为已读完整篇。
+ - **引用来源**：使用 CLI 返回的纯净 URL，格式为 `[文档标题](URL)`。优先展示最多 3 条最相关来源，每个结论都能对应到已读取的内容。
+ - **控制输出**：search 用 `--limit` 和 `--snippet-length`，fetch 用 `--max-length` 和 `--start-index`。CLI 不提供旧脚本的临时文件预览机制，续读依赖分页参数。
+ - **正常空结果**：退出码为 0 且 `documents` 为空时，改写 query 或放宽产品过滤；这不代表服务故障。
+ - **参数错误**：按对应子命令的 `--help` 修正参数；数量和长度必须为正数，起始索引非负。
+ - **请求失败**：非零退出时读取 stderr，区分网络问题和上游业务错误。超时或 `DownstreamError` 等暂时性故障可重试一两次；持续失败时说明失败原因，不把失败当成无结果。公开文档请求失败无需补充云账号凭据。