Skill: volc-sdk-team/volcengine-documentation (version 1.0.0)

--- name: volcengine-documentation description: "火山引擎官方文档查询工具，支持文档检索和全文获取。涵盖火山引擎全部产品、开发者工具、服务支持、最佳实践，包括产品介绍、使用、计费、部署、故障排查、API、SDK、服务条款/协议等全流程。任何涉及火山引擎产品咨询、使用问题、文档查询的需求都优先调用本技能。" --- # 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" ```

path: scripts/volcengine_docs.py
content: #!/usr/bin/env python3
import sys
import json
import requests
from urllib.parse import urlparse

API_BASE = "https://docs-api.cn-beijing.volces.com/api/v1/doc"
REQUEST_TIMEOUT = 15  # 超时时间15秒，防止永久阻塞

# 已取消负向关键词判断逻辑，所有查询默认放行

def search(query, limit=10, service_codes=None):
    """检索火山引擎文档"""
    url = f"{API_BASE}/search"
    payload = {
        "Query": query,
        "Limit": limit
    }
    if service_codes:
        payload["ServiceCodes"] = service_codes
    
    headers = {
        "Content-Type": "application/json"
    }
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=REQUEST_TIMEOUT)
        response.raise_for_status()
        return response.json()
    except Exception as e:
        return {"error": f"检索请求失败: {str(e)}"}

def fetch(doc_url):
    """获取文档完整内容，自动处理URL中的query参数"""
    parsed = urlparse(doc_url)
    # 完全剥离query参数和fragment参数，确保URL纯净
    clean_url = f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
    
    url = f"{API_BASE}/fetch"
    payload = {
        "Url": clean_url
    }
    headers = {
        "Content-Type": "application/json"
    }
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=REQUEST_TIMEOUT)
        response.raise_for_status()
        result = response.json()
        # 始终返回纯净URL
        if "Result" in result:
            result["Result"]["CleanUrl"] = clean_url
        return result
    except Exception as e:
        return {"error": f"内容获取请求失败: {str(e)}"}

def print_help():
    help_info = {
        "name": "volcengine-docs 火山引擎文档查询工具",
        "usage": [
            {
                "action": "search",
                "desc": "检索火山引擎文档",
                "params": "<查询关键词> [返回数量] [产品编码1,产品编码2...]",
                "example": 'python volcengine_docs.py search "tos是什么" 1 tos'
            },
            {
                "action": "fetch",
                "desc": "获取文档完整内容",
                "params": "<火山引擎文档链接>",
                "example": 'python volcengine_docs.py fetch "https://www.volcengine.com/docs/6349/162514?lang=zh"'
            }
        ]
    }
    print(json.dumps(help_info, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print_help()
        sys.exit(1)
    
    action = sys.argv[1]
    result = {}
    
    if action == "search":
        if len(sys.argv) < 3:
            result = {"error": "缺少查询关键词", "help": "用法: python volcengine_docs.py search <查询关键词> [返回数量] [产品编码1,产品编码2...]"}
        else:
            query = sys.argv[2]
            limit = 10
            service_codes = None
            if len(sys.argv) >=4:
                try:
                    limit = int(sys.argv[3])
                except ValueError:
                    result = {"error": "返回数量必须是数字"}
            if len(sys.argv) >=5:
                service_codes = sys.argv[4].split(",")
            
            if "error" not in result:
                result = search(query, limit, service_codes)
    
    elif action == "fetch":
        if len(sys.argv) < 3:
            result = {"error": "缺少文档URL", "help": "用法: python volcengine_docs.py fetch <火山引擎文档链接>"}
        else:
            doc_url = sys.argv[2]
            result = fetch(doc_url)
    
    else:
        result = {"error": f"未知操作 {action}", "help": "支持的操作: search, fetch"}
    
    print(json.dumps(result, ensure_ascii=False, indent=2))
    if "error" in result:
        sys.exit(1)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)