yapi-document

name	yapi-document
description	在用户需要查询 YAPI 接口文档、确认请求参数、查看响应结构、按路径或标题定位接口定义、核对某个接口的 body schema、或希望从 YAPI 拉取最新文档时使用。只要用户提到"查 YAPI""接口文档""请求参数""响应体""某个 path 的定义""YAPI 上这个接口怎么写"，即使没有明确点名这个 skill，也应优先使用。

YAPI Document Query

Overview

这个 skill 用于从 YAPI 平台导出的项目 JSON 中查询接口定义，并以精简、可阅读的方式返回请求与响应摘要。

skill 的核心目标不是把整份 YAPI 导出原样贴回上下文，而是：

1. 先把远端导出缓存到本地
2. 通过脚本做精确检索
3. 只输出当前问题需要的局部定义

适用场景

• 用户要查某个接口的请求参数
• 用户要确认某个接口的响应结构
• 用户只知道标题、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

工作原则

1. 先查询，后展开

• 如果用户只给了标题关键字、分类名、模糊 path，先运行 find
• 只有在唯一命中接口后，才运行 show
• 如果命中多个接口，先返回候选项，不要擅自展开多个大结果

2. 永远不要把整份导出 JSON 放进上下文

• 禁止直接输出整份缓存文件
• 禁止用 cat 或等价方式把全量 JSON 回填到回答中
• 如果结果过大且用户没有显式提供 --out，只返回摘要并提示如何导出完整内容

3. 优先使用本地缓存

• 默认通过脚本自动判断是否需要刷新
• 用户明确说“刷新”“重新拉取”“用最新文档”时，先执行 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：

• overview
• params
• query
• headers
• req-body
• res-body
• markdown
• all

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 分类、缓存状态

推荐串联方式：

1. 先用 find --json 缩小候选范围
2. 唯一命中后再用 show --json
3. 把 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、脚本或自动化流程继续消费。

查询策略

按下面顺序定位接口：

1. method + path 精确命中
2. path 精确命中
3. title 精确或包含命中
4. category 包含命中
5. 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 的请求体定义

处理：

1. 先执行 find --method PATCH --path /plan/update
2. 如果唯一命中，再执行 show --section req-body
3. 用中文总结请求体字段，不回填整份 schema 原文

示例 2：按关键字查接口

用户：

查一下标题里包含患者的接口

处理：

1. 执行 find --keyword 患者
2. 返回候选接口列表
3. 提醒用户继续指定 path、title 或 method

示例 3：先刷新再查看详情

用户：

先刷新 YAPI，再告诉我 /user/updateHospitalReport/{userId} 需要哪些参数

处理：

1. 执行 refresh
2. 执行 show --method PATCH --path /user/updateHospitalReport/{userId}
3. 分开整理 path param、query、header 和 body schema

示例 4：查完接口后交给 API 封装 skill

用户：

先用 yapi-document 查“获取协议”的接口定义，再把结果交给 api-wrapper 生成 TS 类型和请求封装。

处理：

1. 先执行 find --keyword 获取协议 --json
2. 唯一命中后执行 show --method POST --path /api/about-us/agreement --section all --json
3. 把返回的结构化 JSON 继续交给下游 skill，不要让下游去解析 Markdown

边界约束

• 这个 skill 只负责"查询与总结 YAPI 文档"，不负责生成 TypeScript 类型或请求代码
• 不要把真实 token 写进回答、文档、代码块或仓库文件
• 不要优先建议用户通过命令行传入 --token，除非明确是在本地调试
• 如果当前目录无法向上找到任何 env 配置文件（.env.local / .env.development / .env），要明确说明缺少项目级配置，而不是猜测项目 ID
• 如果结果不唯一，不要假装已经定位到正确接口
• 多项目配置时，项目 ID 和 token 的数量必须一致，顺序必须对应
• 每个项目的数据独立缓存，缓存文件命名格式为 project-{id}.json