| name | yapi-document |
| description | 在用户需要查询 YAPI 接口文档、确认请求参数、查看响应结构、按路径或标题定位接口定义、核对某个接口的 body schema、或希望从 YAPI 拉取最新文档时使用。只要用户提到"查 YAPI""接口文档""请求参数""响应体""某个 path 的定义""YAPI 上这个接口怎么写"，即使没有明确点名这个 skill，也应优先使用。 |
YAPI Document Query
Overview
这个 skill 用于从 YAPI 平台导出的项目 JSON 中查询接口定义，并以精简、可阅读的方式返回请求与响应摘要。
skill 的核心目标不是把整份 YAPI 导出原样贴回上下文，而是：
- 先把远端导出缓存到本地
- 通过脚本做精确检索
- 只输出当前问题需要的局部定义
适用场景
- 用户要查某个接口的请求参数
- 用户要确认某个接口的响应结构
- 用户只知道标题、path、method 或分类名，需要定位接口
- 用户希望刷新当前项目的 YAPI 文档缓存
- 用户希望对比某个接口的 query、path param、header、body schema
- 用户希望把接口定义继续交给其他 skill 或脚本生成 API 封装、TS 类型或请求代码
前置要求
在当前 git 仓库根目录范围内，从工作目录向上查找以下 env 文件（优先级从高到低）：
| 优先级 | 文件名 | 说明 |
|---|
| 1 | .env.local | 本地覆盖，不进 git |
| 2 | .env.development | 开发环境配置 |
| 3 | .env | 全局基础配置 |
文件中的变量会按优先级合并，高优先级的值不会被低优先级覆盖。如果都找不到，回退读取 shell 环境变量。
单项目配置
YAPI_BASE_URL=https://你的YAPI域名
YAPI_PROJECT_ID=29
YAPI_TOKEN=你的YAPI导出token
多项目配置
如需同时管理多个 YAPI 项目，使用逗号分隔多个项目 ID 和对应的 token：
YAPI_BASE_URL=https://你的YAPI域名
YAPI_PROJECT_ID=29,35,42
YAPI_TOKEN=token1,token2,token3
配置规则：
YAPI_PROJECT_ID 和 YAPI_TOKEN 中的值数量必须一一对应- 项目 ID 顺序和 token 顺序必须一致
- 每个项目的数据会分别缓存，缓存文件命名格式为
project-{id}.json
约束如下：
- YAPI 域名通过
YAPI_BASE_URL 配置，由用户指定（如 https://yapi.hrttest.cn）
- 只会在当前 git 仓库根目录范围内，从工作目录向上查找
.env.local、.env.development、.env
- 所有 env 文件都找不到时，回退读取 shell 环境变量
- 正常使用优先依赖 env 文件，不要默认让用户通过命令行直传
--token
工作原则
- 先查询，后展开
- 如果用户只给了标题关键字、分类名、模糊 path，先运行
find
- 只有在唯一命中接口后，才运行
show
- 如果命中多个接口，先返回候选项，不要擅自展开多个大结果
- 永远不要把整份导出 JSON 放进上下文
- 禁止直接输出整份缓存文件
- 禁止用
cat 或等价方式把全量 JSON 回填到回答中
- 如果结果过大且用户没有显式提供
--out，只返回摘要并提示如何导出完整内容
- 优先使用本地缓存
- 默认通过脚本自动判断是否需要刷新
- 用户明确说“刷新”“重新拉取”“用最新文档”时，先执行
refresh
- 用户明确要求离线查询时，给
find/show 添加 --offline
推荐流程
1. 刷新缓存
在这些场景先刷新：
- 用户明确要求最新文档
- 缓存明显过期
- 你怀疑接口刚改过
命令：
node skills/yapi-document/scripts/yapi-document.mjs refresh
如需查看命令帮助，可使用：
node skills/yapi-document/scripts/yapi-document.mjs --help
2. 查找候选接口
当用户提供的是模糊条件时，先运行：
node skills/yapi-document/scripts/yapi-document.mjs find --method PATCH --path /plan/update
或：
node skills/yapi-document/scripts/yapi-document.mjs find --keyword 患者
如果用户要看“当前项目有哪些接口”，运行：
node skills/yapi-document/scripts/yapi-document.mjs find --all --group-by category --max-results 50
注意：
--all 只表示允许在“没有过滤条件”时列出接口清单- 如果同时传了
--category、--keyword、--path 等条件，仍然必须只返回过滤后的结果
返回多个候选时，只列候选项并请用户确认要看哪一个。
3. 查看单个接口详情
唯一命中后再运行：
node skills/yapi-document/scripts/yapi-document.mjs show --method PATCH --path /plan/update
如果只看某一部分，使用 --section：
node skills/yapi-document/scripts/yapi-document.mjs show --method PATCH --path /plan/update --section req-body
可选 section：
overviewparamsqueryheadersreq-bodyres-bodymarkdownall
4. 结构化输出给其他 skill
如果当前查询结果还要继续交给其他 skill 或脚本处理，优先加上 --json：
node skills/yapi-document/scripts/yapi-document.mjs show \
--method POST \
--path /api/about-us/agreement \
--section all \
--json
适用场景：
- 需要把接口定义继续交给
api-wrapper、vue-api-client-wrapper 或自定义生成脚本
- 需要稳定拿到
method、path、参数列表、body schema、缓存状态
- 不希望让下游再去解析 Markdown 文本
输出约定：
refresh --json：返回拉取时间、分类数、接口总数、缓存文件信息find --json：返回查询条件、总命中数、当前展示数、候选接口列表、缓存状态show --json：返回匹配接口、请求参数、响应 schema、缓存状态stats --json：返回分类数量、接口总数、方法分布、Top 分类、缓存状态
推荐串联方式：
- 先用
find --json 缩小候选范围
- 唯一命中后再用
show --json
- 把
show --json 的结果直接交给下游 skill 生成类型或请求封装
列出接口清单
如果用户是想先了解“这个 YAPI 项目里有哪些接口”，使用：
node skills/yapi-document/scripts/yapi-document.mjs find --all --group-by category --max-results 50
规则：
- 默认仍然只返回清单，不展开正文
- 推荐配合
--group-by category 一起使用，便于先按分类浏览
- 如果结果很多，优先让用户指定分类、标题关键字或 path，再继续缩小范围
- 回答里应包含“总命中数”和“当前展示数”，避免把截断结果误当成全量接口
统计接口信息
如果用户想看当前项目的接口规模、方法分布、Top 分类，使用：
node skills/yapi-document/scripts/yapi-document.mjs stats
可选参数：
node skills/yapi-document/scripts/yapi-document.mjs stats --top-categories 15
输出格式
默认按下面结构整理回答：
## 匹配接口
## 请求定义
## 响应定义
## 备注
要求如下：
匹配接口：给出标题、method、path、分类、接口 ID请求定义：拆成 Path 参数、Query 参数、Header、Body Schema 摘要响应定义：只保留关键字段、对象层级、必填项和必要说明备注：补充分类说明、文档摘要、缓存时间、是否来自缓存、缓存状态- 如果缓存已过期但未刷新，必须明确说明未刷新原因
- 如果结果过大但未指定
--out，备注中必须明确提示“未自动落盘”
当显式传入 --json 时，不再输出 Markdown，而是输出结构化 JSON，供其他 skill、脚本或自动化流程继续消费。
查询策略
按下面顺序定位接口：
method + path 精确命中path 精确命中title 精确或包含命中category 包含命中keyword 在 title/path/desc/markdown 中模糊命中
大结果处理
如果 show 返回内容较大：
- 只有在用户显式提供
--out 时，才把完整结果写入文件
- 回答中只引用摘要，不粘贴大段原文
- 如果未提供
--out，明确提示如何导出完整结果
多项目配置使用
当在项目根目录的 env 文件中配置了多个项目时：
YAPI_PROJECT_ID=29,35,42
YAPI_TOKEN=token1,token2,token3
刷新缓存
刷新所有项目：
node skills/yapi-document/scripts/yapi-document.mjs refresh
刷新特定项目：
node skills/yapi-document/scripts/yapi-document.mjs refresh --project-id 35
查找接口
在所有项目中查找：
node skills/yapi-document/scripts/yapi-document.mjs find --keyword 患者
在特定项目中查找：
node skills/yapi-document/scripts/yapi-document.mjs find --project-id 35 --keyword 患者
查看接口详情
如果 method + path 在多个项目中都存在，会列出所有匹配的项目供选择：
node skills/yapi-document/scripts/yapi-document.mjs show --method GET --path /api/user
直接指定项目查看：
node skills/yapi-document/scripts/yapi-document.mjs show --project-id 35 --method GET --path /api/user
统计信息
统计所有项目：
node skills/yapi-document/scripts/yapi-document.mjs stats
统计特定项目：
node skills/yapi-document/scripts/yapi-document.mjs stats --project-id 35
常见用法
示例 1：按 path 查请求体
用户：
帮我查一下 PATCH /plan/update 的请求体定义
处理：
- 先执行
find --method PATCH --path /plan/update
- 如果唯一命中，再执行
show --section req-body
- 用中文总结请求体字段，不回填整份 schema 原文
示例 2：按关键字查接口
用户：
查一下标题里包含患者的接口
处理：
- 执行
find --keyword 患者
- 返回候选接口列表
- 提醒用户继续指定 path、title 或 method
示例 3：先刷新再查看详情
用户：
先刷新 YAPI，再告诉我 /user/updateHospitalReport/{userId} 需要哪些参数
处理：
- 执行
refresh
- 执行
show --method PATCH --path /user/updateHospitalReport/{userId}
- 分开整理 path param、query、header 和 body schema
示例 4：查完接口后交给 API 封装 skill
用户：
先用 yapi-document 查“获取协议”的接口定义，再把结果交给 api-wrapper 生成 TS 类型和请求封装。
处理：
- 先执行
find --keyword 获取协议 --json
- 唯一命中后执行
show --method POST --path /api/about-us/agreement --section all --json
- 把返回的结构化 JSON 继续交给下游 skill，不要让下游去解析 Markdown
边界约束
- 这个 skill 只负责"查询与总结 YAPI 文档"，不负责生成 TypeScript 类型或请求代码
- 不要把真实 token 写进回答、文档、代码块或仓库文件
- 不要优先建议用户通过命令行传入
--token，除非明确是在本地调试
- 如果当前目录无法向上找到任何 env 配置文件（.env.local / .env.development / .env），要明确说明缺少项目级配置，而不是猜测项目 ID
- 如果结果不唯一，不要假装已经定位到正确接口
- 多项目配置时，项目 ID 和 token 的数量必须一致，顺序必须对应
- 每个项目的数据独立缓存，缓存文件命名格式为
project-{id}.json
