背景：接口文档不止给人看
团队用 YApi 管接口时，常见痛点是：查文档要切网页、联调要对照字段、写前端还要手抄类型。如果再把 AI 编码助手接进来，还需要一条稳定通路，让模型能「按需」读到真实接口定义，而不是整份文档塞进上下文。
@vtian/yapi-cli 的定位是：以 CLI 为唯一能力内核，在同一套逻辑上提供终端命令、MCP（Model Context Protocol）和 Cursor Skill，并支持多项目、多空间（多 baseUrl）配置，方便在 monorepo 或多后端场景下使用。
使用文档
核心能力一览
| 能力 | 说明 |
|---|---|
| 联调 / 查详情 | 按接口 ID 或 path 拉取接口信息，支持精简视图与带原始 schema 的完整视图 |
| Mock | 根据响应体 JSON Schema 生成 mock 数据 |
| TypeScript 类型 | 从 schema 生成 TS 类型，可自定义基类型名 |
| 检索 | 按分类列表、按关键词搜索标题/路径 |
| 多形态入口 | 同一套逻辑：yapi 命令行、yapi-mcp 给支持 MCP 的客户端、Skill 给 Cursor 等 Agent 环境 |
架构：CLI 优先，MCP 只是薄适配层
从代码结构可以清楚看到分层：
cli/core/service.ts
真正的业务：listInterfaces、searchInterfaces、getInterfaceDetails、generateMockData、generateTypes等，内部调用 YApi 开放接口（如project/get、interface/list_menu、interface/get），并结合json-schema模块做 mock 与类型生成。cli/api.ts
基于 axios 的 HTTP 客户端工厂与各 API 封装，按ResolvedProject的baseUrl发请求。cli/public-api.ts
对外暴露与 CLI/MCP 共用的函数式 API（再导出配置解析相关工具），保证 npm 包可被其他 Node 程序或 MCP 进程直接import。mcp/index.ts
使用@modelcontextprotocol/sdk注册yapi_search、yapi_list、yapi_get、yapi_mock、yapi_types等 tool，参数用 zod 描述，实现里一律调用public-api的同名能力。
这样 MCP 层不包含重复业务逻辑，升级行为时只改一处。cli/index.ts
Commander 注册子命令：config、list/ls、search/s、get、mock、types，与 MCP tool 一一对应。
整体可以理解为：YApi HTTP → service 层 →（CLI 子命令 | MCP tools | Skill 调 CLI/约定），避免「三套实现、三套 bug」。
配置设计：多项目 + 显式「活跃项目」
yapi.config.json 的设计兼顾了「配置复用」和「Agent 场景下的成本控制」：
baseUrl：全局默认；单个project可覆盖（例如本地联调指向http://localhost:3000）。projects：多个projectId+token+ 可选projectName，避免每个项目重复写主机地址。activeProjectIds：只有列在其中的projectId才会参与解析与查询。
在源码里，resolveProjectById会校验 ID 是否在activeProjectIds中，防止误扫未授权或不需要的项目，也减少 AI 侧无意义的全量遍历。
未显式指定 -p / projectId 时，多项目操作默认使用 activeProjectIds；需要「唯一项目」的命令（如 get/mock/types）在多个 active 项目时会要求你明确指定，避免歧义。
使用方式速览
终端：yapi config init 生成模板，yapi config list 查看解析到的配置路径与内容；yapi list、yapi search、yapi get、yapi mock、yapi types 均支持 -p 与 --json 等选项（详见项目 README）。
MCP：在客户端配置里用 npx -y -p @vtian/yapi-cli yapi-mcp 启动 stdio 服务；若使用 fnm/nvm 等导致子进程没有 Node 环境，README 里给出了用 zsh -lic 包裹 npx 的写法。
Skill：npm run build 会产出 dist/yapi-skills.zip；可用官方脚本从 GitHub 拉取 zip 解压到 .agents/skills/yapi-cli-skill，与全局安装的 CLI 分步安装。
与旧项目 @vtian/yapi-mcp-server 在 Agent 里的用法保持一致，便于迁移；更细的接入说明可参考 README 中引用的掘金文章。
技术栈与工程细节
- TypeScript 编译到
dist/，双入口：yapi、yapi-mcp。 - commander 做 CLI，axios 请求 YApi，zod 约束 MCP 入参，chalk 等用于终端输出。
- MCP 进程里 stdout 专用于 JSON-RPC，启动时在 TTY 下用 stderr 提示「正在 stdio 监听」，避免破坏协议——这是写 MCP Server 时值得注意的细节。
小结与延伸
yapi-cli 的价值不在于「又一个查文档工具」，而在于：把 YApi 变成可编排的 API——终端脚本、CI、IDE 插件、MCP 客户端都能复用同一实现；activeProjectIds 则把「多项目」和「Agent 上下文节约」绑在一起，设计上是连贯的。
