volcengine-documentation

Files (2)

• SKILL.md
• volcengine_docs.py · scripts/

SKILL.md (first lines)

# volcengine-documentation 火山引擎文档技能

## 功能描述
火山引擎文档综合查询技能，支持**文档检索**和**内容获取**两个核心功能，火山引擎文档是火山最权威的官方数据，涵盖全产品使用全链路。

## 决策逻辑（必看）
### 触发判断规则
1. **用户提供文档链接**：直接调用 `fetch` 接口获取完整内容，无需先检索。

### search 和 fetch 配合规则
1. **用户提问类需求**：优先调用 `search` 接口（默认不携带ServiceCodes参数），返回5条结果，优先使用返回的Content内容回答。
2. **二次检索优化**：如果第一次搜索结果匹配度不高，可根据第一次返回结果中的ServiceCodes字段，携带对应产品编码参数执行二次检索，缩小范围获取更精准结果。
3. **需要完整文档内容**：先调用 `search` 找到对应文档链接，再调用 `fetch` 获取全文内容。

## 功能说明
### 1. 文档检索 (search)
根据用户问题检索相关火山引擎官方文档，支持按产品过滤。
- 请求地址：`https://docs-api.cn-beijing.volces.com/api/v1/doc/search`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| Query | string | 是 | 用户的具体问题描述 |
| Limit | number | 否 | 检索返回的文档数量，默认返回5篇 |
| ServiceCodes | array<string> | 否 | 产品过滤条件，指定仅查询某几个产品的文档，可通过返回结果中的ServiceCodes字段获取产品编码 |

#### 返回参数
核心有效数据在 `Result.DocList` 字段中，每个文档项包含：
| 字段名 | 类型 | 说明 |
|--------|------|------|
| Title | string | 官方文档标题 |
| Url | string | 文档官方访问链接 |
| Content | string | 文档完整内容 |
| ServiceCodes | array<string> | 文档所属产品编码列表 |

---

### 2. 内容获取 (fetch)
根据火山引擎官方文档链接，获取对应的完整文档内容，支持结构化解析文档标题、正文内容。
- 请求地址：`https://docs-api.cn-beijing.volces.com/api/v1/doc/fetch`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| Url | string | 是 | 火山引擎官方文档链接，格式如 `https://www.volcengine.com/docs/6349/162514` |

⚠️ **重要处理规则**：
如果Url包含query参数（例如 `https://www.volcengine.com/docs/6396/624853?lang=zh`），需要在请求前去掉所有query参数，只保留 `https://www.volcengine.com/docs/6396/624853` 部分进行请求。

#### 返回参数
核心有效数据在 `Result` 字段中：
| 字段名 | 类型 | 说明 |
|--------|------|------|
| Title | string | 文档的完整标题 |
| Content | string | 文档的完整正文内容，结构化解析后的文本 |

## 结果处理规则
### 通用强制规则
1. 所有回答末尾**必须**附上对应的官方文档链接作为参考来源，使用 `[文档标题](纯净URL)` 格式，每条结果都要标注来源地址
2. 如果返回多个结果，按相关性排序展示，最多展示3条最相关的结果，每条结果都附带对应的文档链接
3. 链接必须使用脚本返回的`CleanUrl`（已剥离所有query参数），禁止使用带`?lang=zh`等参数的URL

### 检索结果处理
1. 优先使用返回的Content内容回答用户问题，信息更准确
2. 接口直接返回文档完整内容，无需做额外摘要提炼

### 内容获取结果处理
1. 接口直接返回文档完整内容，可直接使用无需额外处理

## 工具使用方法
### 检索文档
```bash
python {skill_dir}/scripts/volcengine_docs.py search "查询关键词" [返回数量] [产品编码1,产品编码2...]
```
示例：
```bash
python {skill_dir}/scripts/volcengine_docs.py search "tos是什么" 1 tos
```

### 获取文档完整内容
```bash
python {skill_dir}/scripts/volcengine_docs.py fetch "火山引擎文档链接"
```
示例：
```bash
python {skill_dir}/scripts/volcengine_docs.py fetch "https://www.volcengine.com/docs/6349/162514?lang=zh"
```

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples