name: voc-api-catalog

description: 清单驱动的 VOC 社交数据采集。把所有转发接口做成清单，按需查清单、读参数文档，自己拼参数完成任意行业/任意方向的社交数据采集（目前覆盖抖音、小红书等国内社媒）。当用户要采集某关键词的社交内容/评论、要调用某个社交数据接口、或现有专用工具不覆盖某接口时使用。

VOC 接口清单驱动采集

核心理念

VOC 后端是一个通用转发网关（https://server.fmode.cn/api/voc-social/<proxyPath>），任意 proxyPath 都会被透传到我们的中转上游（请求头已封装，对外不暴露具体数据供应商）。所以不需要为每个接口写死一个工具：你只要

查清单：用 voc_api_search 找到要用的接口；
读参数文档：用 voc_api_doc 读该接口的详细参数；
拼参数调用：用 voc_api_call 自己拼好参数发起真实调用。

清单里没有的接口，也可以直接用 voc_api_call 传 rawPath + method + params 调用，无需改代码。

工具

voc_api_search：检索接口清单。入参 query（关键词，可选）、platform（如 douyin / xiaohongshu，可选）、tag（可选）。返回接口 id、标题、method、proxyPath、必填参数。
voc_api_doc：读取单个接口的完整参数文档。入参 id（或 proxyPath）。返回参数表 + 可直接复制的调用模板。
voc_api_call：发起真实调用。入参：
- id：清单里的接口 id（推荐），或
- rawPath + method：调用未登记接口；
- params：参数对象（按 doc 拼）。也可显式用 query / body 分开传；
- token：从 vocToken / token 或环境读取，绝不回显。

标准流程

理解任务 → 确定平台和要采集的内容（搜索 / 评论 / 详情）。
voc_api_search（带行业无关的关键词或 platform）找到接口。
voc_api_doc 读参数，确认必填项和取值含义。
voc_api_call 用真实关键词调用；翻页/拉评论时把上一次返回里的 cursor / id 透传进下一次调用。
用返回数据继续后续分析（可交给 voc-issue-pool、voc-content-plan 等技能）。

Token

采集需要从充值/开通页复制的、以 r: 开头的会话 token（session token）。不要用 ~/.claude/voc-credentials.json 里 sk- 开头的 AIGate API Key —— 后端不认它，会被工具直接判为 needs_valid_token。

禁止事项（护栏）

禁止把入参/参数错误（needs_input）误报成「采集不到数据 / 该关键词没结果 / 类目不支持」。参数错就如实说参数错，并用 voc_api_doc 核对后重试。
禁止把上游不稳定（upstream_unstable，如 5xx / 连接超时 / fetch failed）误报成「关键词问题 / 类目不支持 / 余额不足」。如实说明是上游接口波动，稍后重试。
禁止把 token 无效/类型不对（needs_valid_token）误报成「余额不足」或「类目不支持」。
禁止输出「某行业不可用 / 系统只支持某类目」这类结论——任何行业、任何关键词都能采集，前提只是 token 类型正确且有额度。
失败时禁止退回 web search / yt-dlp / ffmpeg / 让用户手动传媒体文件来「绕过」采集。

状态码含义

ok：调用成功，data.result 是上游返回数据。
needs_token / needs_valid_token：没配置 token，或 token 类型不对（sk-）。提示配置 r: token。
needs_recharge：额度不足，提示充值。
needs_input：必填参数缺失或参数错误（不是类目/余额问题）。
upstream_unstable：上游接口报错或波动，稍后重试。

SKILL.md 3.7 KB История Исходник