yapi

该 Skill 专注于 YApi 接口文档的查询与同步管理。当用户粘贴 YApi URL 或提及相关需求时，系统会提取项目 ID 和接口 ID，通过调用 yapi CLI 工具与配置的 YApi 实例交互。支持通过 yapi search 按关键词搜索接口，使用 yapi --path /api/interface/get 获取详细定义（包含请求方法、路径、头信息、参数结构、响应模型及示例），并通过 yapi docs-sync 实现本地 Markdown 文档与 YApi 平台的自动化同步绑定。

显著优点方面，首先具备 URL 智能识别能力，可自动解析 YApi 链接中的项目与接口标识，无需手动输入 ID。其次，文档同步功能支持双向绑定，通过 .yapi/docs-sync.json 配置实现本地文档变更的自动检测与推送，支持强制全量同步与增量同步两种模式。第三，集成 Mermaid 图表渲染能力（依赖 mmdc），可将接口流程图自动转换为可视化图表。第四，纯命令行交互方式适合开发者工作流，查询结果可直接展示接口的 JSON Schema 定义与示例数据，便于快速理解数据结构。

潜在缺点与局限性不容忽视。该 Skill 存在明显的使用门槛，必须手动安装 @leeguoo/yapi-mcp npm 包并完成交互式登录配置，首次使用成本较高。其次，严格依赖特定 YApi 实例的配置，如果用户提供的 URL 与 ~/.yapi/config.toml 中配置的 base_url 不匹配则无法使用，灵活性受限。第三，文档同步功能对 Pandoc 有额外依赖（用于完整 Markdown 渲染），且 Mermaid 渲染失败不会阻塞同步但会影响文档完整性。第四，来源为个人开发者（T3 级），长期维护稳定性存疑。

适合的目标群体主要面向使用 YApi 作为 API 管理平台的开发团队，特别是需要频繁查询接口定义的前后端工程师；适合需要维护大量接口文档并期望实现本地文档与平台自动同步的 API 维护者；也适用于需要基于 YApi 链接快速获取技术细节进行代码编写或调试的技术人员。不适用于使用 Swagger、Postman 等其他 API 管理工具的团队。

使用风险方面，安全层面需特别关注凭据管理，YApi 登录信息（邮箱/密码或 Token）存储在 ~/.yapi/config.toml 及 ~/.yapi-mcp/auth-*.json 文件中，需确保文件权限设置正确防止泄露。依赖风险方面，核心功能依赖社区个人开发者维护的 npm 包，版本更新与安全补丁可能存在滞后。网络环境风险在于必须确保连接的 YApi 实例可信，避免在不可信网络环境下传输敏感接口定义。此外，CLI 工具执行需 Node.js 环境，若环境配置不当可能导致命令执行失败，且 Skill 本身无法自动处理安装与配置过程。

核心功能

yapi 是一款面向 YApi 平台的接口文档管理助手，主要提供两大能力：接口文档查询与本地文档同步。通过 CLI 工具链，用户可直接在终端完成 YApi 的认证、搜索、详情获取及批量同步操作，无需频繁切换浏览器与编辑器。

显著优点

1. URL 智能识别：自动解析 YApi 链接，提取 project_id 与 api_id，一键获取接口详情，大幅降低人工查找成本。
2. 双向文档绑定：支持本地 Markdown 与 YApi 分类目录的映射绑定（docs-sync bind），实现文档的单向或双向同步，适合将本地 API 设计文档推送至 YApi 平台。
3. 灵活认证机制：支持交互式登录（邮箱+密码）与 Token 模式，配置持久化存储于 ~/.yapi/config.toml，避免重复输入。
4. 辅助渲染支持：可选集成 Mermaid（图表）与 Pandoc（Markdown 渲染），提升文档可读性。

潜在局限

• 外部依赖重：核心功能完全依赖 @leeguoo/yapi-mcp CLI 工具，若该包停止维护或出现安全漏洞，本 Skill 将失效。
• T3 来源风险：作者为个人开发者（leeguooooo），无企业背书，长期维护与响应速度存在不确定性。
• 无可视化界面：纯命令行交互，对非技术背景的产品或测试人员不够友好。
• YApi 版本锁定：不同 YApi 自建版本的 API 可能存在差异，文档未明确兼容性矩阵。

适合人群

• 后端工程师：快速查询、验证接口契约，生成调用代码。
• 前端/客户端开发者：批量同步接口变更，维护本地 Mock 或类型定义。
• 技术负责人：统一管理多项目接口文档，建立文档同步流水线。

常规风险

• 凭证泄露：~/.yapi/config.toml 与 auth-*.json 存储登录态，需确保文件权限（建议 600），避免多用户环境共享。
• 同步覆盖：docs-sync 默认仅同步变更文件，但 --force 模式可能覆盖他人编辑的线上文档，需配合版本控制使用。
• CLI 供应链：全局安装 npm 包存在供应链攻击面，建议锁定版本并定期审计。