技能介绍

解决什么问题

有赞开放平台和开发者文档分散在多个入口，接口参数、错误语义、类目结构容易混在一起。直接让模型凭记忆回答，会出现参数名写错、场景判断错位、把旧版文档当成当前事实的问题。这个技能把「取证据」和「解释证据」拆开：youzan-toolkit CLI 负责请求、参数校验、鉴权、TLS、缓存和结构化返回；Skill 负责识别这是文档检索、字段解释还是完整文档阅读，并把结果组织成可验证的回答。

工作方式

检索前先读取当前 CLI 携带的说明，而不是使用发行包里写死的内网地址或默认凭证。需要鉴权时可通过进程环境变量配置，--authorization 优先级最高；查看状态不会回显真实凭证。默认行为如下：

text 取用户真实问题。
topN 为 10，retrievalType 为 2，即混合检索。
algRerank 默认开启，命中切片上下各扩展 2 段，并合并扩展内容。
retrieveCategoryPath 和 retrieveRawContent 默认为真，便于同时拿到类目路径和原文。
expandPrevChunks、expandNextChunks、mergeExpandedContent、maxExpandedChars 控制扩展窗口和最大长度。

实际执行时，技能先提取用户问题作为 --keyword；若用户指定 topN、retrievalType 或 filters，则覆盖默认值；随后调用 youzan-toolkit docs search。回答时优先依据高分结果、原文和类目路径；需要完整文档时，从命中结果中提取标识并调用 docs read。如果结果不足，应明确说明没有检索到充分依据，而不是补全未返回的事实。

边界与注意点

它只解决开发者知识的检索与解释，不替代业务规则推理。默认输出是 JSON，便于 Agent 继续组合；给人看时可用 --format pretty，用户要求原始结果时使用 --full-response。配置必须指向可公网访问的 HTTPS 服务，且不能依赖发行包内置凭证；缺少鉴权或服务不可达时，检索会失败。结论应先于 JSON 给出，关键依据要来自实际返回，不能编造接口、参数或文档内容。