name: voc-api-catalog

description: 清单驱动的 VOC 数据采集，覆盖三类情报源。把所有转发接口做成清单，按需查清单、读参数文档，自己拼参数完成任意行业/任意方向的数据采集。三条通道：①社媒内容（channel=social，默认）覆盖抖音、TikTok、小红书、Instagram、YouTube、Twitter/X、LinkedIn、微博、B站、快手、知乎、Reddit、Threads、微信视频号等 18 个国内外社媒平台的搜索/评论/详情；②国内电商 + 创作者情报（channel=ecommerce）覆盖京东、淘宝/天猫、1688、抖音电商、TikTok Shop、闲鱼、得物等电商平台的商品搜索·详情·价格·评论·店铺商品，抖音星图、小红书蒲公英（PGY）创作者搜索/画像/受众/绩效，以及微信公众号、视频号、微博、B站、知乎、快手、头条、豆瓣、IMDb 等内容平台的结构化数据；③海外选品（channel=overseas）覆盖亚马逊海外站点的类目树/Best Seller 榜单、产品详情与销量、ABA 关键词、产品评论、数据监控等选品数据。当用户要采集某关键词的社交内容/评论、查电商商品/价格/商品评论/选品（含京东淘宝天猫拼多多类需求与海外亚马逊）、做竞对/创作者生态/受众洞察/选题/内容战略分析、要调用某个数据接口、或现有专用工具不覆盖某接口时使用——优先来这里查清单，不要因为以为「没有这个能力」就退回 WebSearch。

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 调用，无需改代码。

三条通道：社媒内容 / 国内电商+创作者 / 海外选品（channel）

清单里每个接口都带 channel 字段，voc_api_call 据此自动选用对应网关，你通常无需关心：

channel="social"（默认）：走社媒中转网关 https://server.fmode.cn/api/voc-social。抖音/小红书等 18 平台的内容搜索、评论、用户/笔记详情等 VOC 口碑采集走这条。
channel="ecommerce"：走电商与创作者数据网关 https://server.fmode.cn/api/voc-e-commerce，覆盖三块：
1. 国内电商商品：京东、淘宝/天猫、1688、抖音电商、TikTok Shop、闲鱼、得物等平台的商品搜索、商品详情、价格、商品评论、店铺商品列表等——用户问「京东/淘宝/天猫某商品、某品类选品、商品评论」时就用这里（注意：上游暂无拼多多接口，遇拼多多需求可用京东/淘宝/天猫/1688 替代，并如实说明）。
2. 创作者侧情报：抖音星图、小红书蒲公英（PGY）的创作者搜索、画像、受众/粉丝分布、内容与评论关键词、笔记/视频绩效与性价比等，服务创作者生态理解、竞对达人布局、受众匹配与内容方向验证（不是替用户做投放采买决策）。
3. 内容平台：微信公众号/视频号、微博、B站、知乎、快手、今日头条、豆瓣、IMDb 等的结构化内容数据。
channel="overseas"：走海外电商选品网关 https://server.fmode.cn/api/voc-ecom。亚马逊海外站点的类目树 / Best Seller Top100 榜单、产品详情与子体销量、ABA 关键词与搜索排名、产品评论实时采集、ASIN/榜单/卖家数据监控等选品数据走这条。

三套网关鉴权、计费、错误处理完全同源（同一把 sk-/r: token、同样的 401/402/403 语义、同样的回退逻辑），只是根地址不同。调用清单里没有的接口时，传 rawPath 的同时显式带对应 channel（ecommerce / overseas）即可路由（社媒接口不传 channel 默认 social）。

工具

voc_api_search：检索接口清单。入参 query（关键词，可选）、platform（如 douyin / tiktok / xiaohongshu / instagram / youtube / twitter / linkedin 等 18 个平台 key，可选）、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 等技能）。

创作者侧情报（channel=ecommerce）

抖音星图 / 小红书蒲公英（PGY）的创作者数据是 VOC 在创作者生态维度的情报源——它服务的是 VOC 一贯的「内容战略、竞对理解、受众洞察、选题与脚本」闭环，而不是「替用户挑达人投广告」。同一套数据用来回答这些 VOC 问题：

创作者生态 / 竞对达人布局：某品类、某竞品周边在合作哪些量级的创作者、内容走什么方向、谁的影响力在涨。
受众匹配：某创作者的粉丝画像 / 受众分布是否贴合品牌目标人群，用于判断内容触达的相关性。
内容方向验证：某类内容主题在创作者侧的真实表现与受众反馈（内容关键词、评论热词、笔记/视频绩效），为选题与脚本提供事实依据。
创作者能力的客观评估：用公开绩效 / 性价比数据客观描述一个创作者的内容能力与转化表现（作为洞察结论，不是采买建议）。

数据按「先定位创作者、再补结构化数据」两步取：

定位创作者（拿到创作者列表与 id）：
- 抖音星图：douyin.xingtu.creator_search（按 keyword 搜，可按粉丝量级 / 报价 / 内容标签筛）或轻量版 douyin.xingtu.creator_search_light；返回项里的 star_id 即详情接口入参 oAuthorId。
- 小红书蒲公英：xiaohongshu.pgy.creator_search（按 keyword 搜）或 xiaohongshu.pgy.content_square_notes（从内容广场反查创作者 / 笔记）；返回项里的 userId 即详情接口入参。xiaohongshu.pgy.similar_creators 可由一个创作者扩展出同类创作者，快速铺开生态图。
补结构化数据（用第一步拿到的 id 逐个补，按情报目的取所需接口）：
- 画像与受众匹配：抖音 douyin.xingtu.creator_profile / marketing_metrics / audience_distribution / follower_distribution；小红书 xiaohongshu.pgy.creator_profile / creator_core_metrics / creator_content_tags / creator_feature_tags / follower_distribution。
- 内容方向与绩效基准：抖音 douyin.xingtu.content_keyword_analysis / comment_keyword_analysis / recommended_videos / item_report_analysis；小红书 xiaohongshu.pgy.creator_note_list / note_performance_metrics。
- 能力与性价比的客观评估：抖音 douyin.xingtu.cost_performance_analysis / conversion_analysis；小红书 xiaohongshu.pgy.cost_effectiveness_analysis。
把这些创作者侧事实喂给下游 VOC 技能（voc-competitor-map 做竞对达人布局、voc-content-plan / voc-speaking-script 做选题与脚本、voc-issue-pool 补充创作者 / 受众视角），形成洞察结论，而非「该投谁」的采买清单。

提示：voc_api_search 用「星图创作者」「蒲公英画像」「受众分布」「性价比」等词即可定位创作者接口，用「京东商品」「淘宝评论」「1688 搜索」「亚马逊选品」「ABA 关键词」等词定位电商/选品接口；voc_api_doc 会在请求行标注通道（ecommerce / overseas）并列出参数。当前清单 ecommerce 通道已登记约 289 个接口（电商商品 + 创作者 + 内容平台）、overseas 通道 37 个（亚马逊选品），未登记的可直接用 voc_api_call 传 rawPath + 对应 channel 调用。

淘宝/天猫版本选择与时效

完整的 V7 请求示例、字段表、异常处理和版本职责见 ../../docs/taobao-item-detail-v7.md。

需要 48 小时内的当前标题、基础价格、SKU 和店铺信息：优先 taobao.get_item_detail_v7。V7 是实时发起采集的主接口，但 monthSold、baseAttrList 可能为空，不能单独承担页面销量、完整属性或券后价。
V7 返回业务码 301 表示采集失败，工具会自动重试；连续失败后按 upstream_unstable 返回。业务码 202 表示当前商品/口径不支持，按 not_supported 返回，均不能当作成功详情使用。
查较完整的商品属性、SKU 标价与促销价可补充使用 taobao.get_item_detail_v6；查券后价/优惠后价补充使用 taobao.get_item_detail_v4。价格必须标注是标价、促销价、活动价还是券后价，不要压成单一「真实价格」。
查商品页当前展示的「已售/付款人数」：使用 taobao.get_item_detail_v3 的 data.sellCount。V3 不返回价格，价格与页面销量需分别调用 V6/V3。
taobao.get_item_detail_v1 仅用于兼容旧流程；v2 直接调用不会发起商品采集。taobao.get_item_sale_v1 和 taobao.get_shop_item_list_v3 已被上游标记弃用。
V9 的 num 是该版本销售量级信号，totalCount 是评价总量，两者都不是商品页当前展示付款人数。V9 attribute 可能是独立旧属性快照；价格和“上市时间”等关键属性优先 V6，页面销量优先 V3。
返回里的 recordTime 是上游数据采集时间，不是本次 API 请求时间。每个版本有独立数据源/快照，必须用「当前时间 - recordTime」计算滞后并在结果中明示；V3/V4/V6/V7 超过 48 小时会返回 stale_data，只作历史参考。
上游文档未给出固定刷新 SLA，不要将返回值表述为「请求时实时数据」，也不要将旧版 orderPayUV 与商品页当前展示口径直接等同。V3 sellCount 也必须先通过 48 小时时效门禁，超时后不能再称为页面当前销量。
实际结算价还会受 SKU、账号会员价、地区、店铺券、平台补贴和活动时间影响。API 返回的是对应口径快照，不等于任意账号在结算页的最终应付价。
店铺商品列表的新调用优先 taobao.get_shop_item_list_v4，入参为 sellerId + 可选 page。

Token（计费已迁移 NewAPI）

请求头统一 Authorization: Bearer ${token}，优先用 NewAPI（fmode-api）的 sk- token。

这把 sk- 计费 token 是什么、从哪来：它就是 Claude Code 自己的 ANTHROPIC_AUTH_TOKEN——配在用户级 ~/.claude/settings.json 的 env.ANTHROPIC_AUTH_TOKEN（sk- 开头，且 ANTHROPIC_BASE_URL 指向 api.fmode.cn）。Claude Code 用户装完技能即用，无需任何额外配置：工具会自动从这里（以及进程环境）读到它。所以 newapi（fmode-api）≠ 某个要单独开通的东西，它用的就是你正在用的这把 fmode key。

取值优先级：入参 newapiToken/fmodeApiKey → .env.local / 环境变量 FMODE_API_KEY·NEWAPI_TOKEN → ~/.claude/voc-credentials.json 的 fmodeApiKey → ~/.fmode/config.json 的 newapiToken/fmodeApiToken → ~/.claude/settings.json 的 env.ANTHROPIC_AUTH_TOKEN（Claude Code 默认入口，sk- 开头）。
sk- 鉴权失败（401，含「未入仓」类报错）且存在 r: 开头的会话 token 时，工具会自动回退用 r: sessionToken 走原 apig 接口重试一次（过渡期：服务端未迁完 / 该号未入仓）。此回退是正常的原始付费路径，不是出故障。
兼容：若把 sk- 直接填进 VOC_TOKEN，也会被当作 NewAPI token 使用。
token 绝不回显；底层鉴权/入仓原始报错不甩给用户，只给友好提示。

缺 token / token 无效时该怎么自救（重要，别进死循环）：这是可恢复状态，不是「技能用不了」。先确认 ~/.claude/settings.json 的 env.ANTHROPIC_AUTH_TOKEN 是否为 sk- 开头的 fmode key；若工具仍报缺 token，把它取出来用 FMODE_API_KEY=sk-…（或入参 newapiToken）传给工具再调一次。不要因为提示里出现充值/付费链接就让用户去点充值——只有真正 402 余额不足 才需要充值，缺 token 只是没读到这把 SK 而已。

错误码（401/402/403 等）的完整对照、真实报文样例与处理纪律见 references/error-codes.md。

禁止事项（护栏）

禁止把入参/参数错误（needs_input）误报成「采集不到数据 / 该关键词没结果 / 类目不支持」。参数错就如实说参数错，并用 voc_api_doc 核对后重试。
禁止把上游不稳定（upstream_unstable，如 5xx / 连接超时 / fetch failed）误报成「关键词问题 / 类目不支持 / 余额不足」。如实说明是上游接口波动，稍后重试。
禁止把 token 无效/类型不对（needs_valid_token）误报成「余额不足」或「类目不支持」。
禁止把缺 token / token 无效（needs_token / needs_valid_token）误报成「这个技能用不了 / 功能不可用」——它是可恢复的：SK 就在 ~/.claude/settings.json 的 env.ANTHROPIC_AUTH_TOKEN，取出来用 FMODE_API_KEY=sk-… 传入重试即可，别因此放弃或去点充值。
禁止输出「某行业不可用 / 系统只支持某类目」这类结论——任何行业、任何关键词都能采集，前提只是 token 类型正确且有额度。
失败时禁止退回 web search / yt-dlp / ffmpeg / 让用户手动传媒体文件来「绕过」采集。
接口第一次调用失败，禁止立刻转 WebSearch / 公开网页搜索来「代替」采集。正确动作：先按工具返回的 status / assistantMessage 对照 references/error-codes.md 判定错误类型——若是 upstream_unstable（5xx / 超时 / fetch failed）直接重试该接口（上游抖动重试即恢复，实测重试数次即 200）；若是 needs_input 用 voc_api_doc 核对参数后重试；若是 needs_token/needs_valid_token 取 sk- 重试。只有在确认接口本身不存在该能力、且清单与 rawPath 都无法覆盖时，才考虑其它来源，并如实说明原因。
禁止因为「我以为没有这个能力」就跳过清单直接 WebSearch。京东/淘宝/天猫/1688/抖音电商/闲鱼/得物的商品与评论、亚马逊海外选品都在 channel=ecommerce/overseas 里——先 voc_api_search 查清单确认，再下结论。

状态码含义（详表见 `references/error-codes.md`）

ok：调用成功，data.result 是上游返回数据。
needs_token：没读到任何 token（可恢复，不是没钱、不是功能用不了）——优先去 ~/.claude/settings.json 取 env.ANTHROPIC_AUTH_TOKEN（sk-）用 FMODE_API_KEY=sk-… 传入重试。needs_valid_token：token 缺失/失效/无效（HTTP 401）——不是没钱，提示配置有效 sk-（或回退 r:）token。
needs_recharge：仅 HTTP 402（余额不足），透传工具生成的 Tokenized Balance 链接或二维码支付结果；Balance 链接格式为 https://app.fmode.cn/dev/studio/balance/?token=USER_SESSION_TOKEN。需要直接出二维码时，调用 voc_billing_query 时传 createPaymentQr=true，由技能包复用现有 pay_code2 链路。
needs_permission：HTTP 403（账号禁用/无权限），≠ 余额不足，不引导充值，提示联系服务方确认权限。
needs_input：必填参数缺失或参数错误（不是类目/余额问题）。
stale_data：接口有返回，但 recordTime 已超过该接口的时效门槛；只能作为历史参考。
not_supported：业务码 202，当前商品或数据口径不受该接口支持。
upstream_unstable：上游接口报错或波动（5xx / fetch failed），稍后重试。

⚠️ 不要把 403/401 一律说成「余额不足」。只有 402 才是真的没钱要充值；403 是权限、401 是 token 问题。

媒体缓存规则

任何通过本技能采集到的图片、视频、音频或封面，交给统一媒体流水线下载到任务本地 assets/ 并写入清单。
报告和标准化结果只使用本地媒体路径；本技能包不执行线上 Storage 上传，也不请求预签名上传地址。

SKILL.md 17 KB Trvalý odkaz Historie Surový