yapi-cli

把 YApi 的查询、登录、同步、安装、更新、自检和补全能力接到命令行，方便在终端、脚本、CI 和 AI Skill 里直接调用。

除了标准 REST API，本工具还补充了部分扩展场景：会在必要时读取配置、做更新探测、生成补全脚本，或把常见查询封装成可调用命令，适合自动化和 Agent 工作流。

这版补了什么

• 新增高级 Mock 模块：7 个命令覆盖 Mock 期望与脚本管理，支持按请求参数/IP 匹配返回自定义响应。
• 新增接口风格推断：创建接口时自动分析目标分类已有接口的路径前缀、method 偏好、请求/响应字段结构，帮助新接口与现有风格保持一致。
• 导出新增 html / markdown 格式。
• 补齐 interface-create/update/save 可选字段：reqQuery、reqHeaders、reqParams、reqBodyForm、markdown、apiOpened 等。
• 补齐 project-create/update 可选字段：preScript、afterScript、projectMockScript、env。
• 30+ API 方法字段与 YApi 后端严格对齐。
• 新增 compact / normal / verbose / pretty 输出分级；--json 仍可用，且支持放在命令前后位置。
• 新增 interface-update 部分更新命令，可只改接口标题、路径、请求体或响应体；interface-save 继续用于完整 upsert。
• 写命令统一支持 --confirm true，未确认时返回 preview，不直接发起写请求。
• 新增 project-snapshot、interface-snapshot、workspace-snapshot，适合先拿上下文再细查。
• 新增 URL 解析能力：既可以显式执行 yapi url-parse --url ...，也可以直接把 YApi 页面 URL 贴给 CLI 自动解析并查询。
• 新增内置命令：doctor、changelog、completion，补齐安装 / 更新 / 卸载 / 版本查看链路。
• 配置文件按 url/username/password/authMode 收敛；install / config-init 现在统一走配置校验流程：交互终端会逐步提示填写，非交互环境会明确要求显式传参，token 只保存在认证缓存里。
• 普通账号 native 登录现在兼容两种后端形态：直接明文校验，以及先经 RSA 公钥加密再提交 /api/user/login。
• install / update / uninstall 的安装链路已对齐 zentao-cli：优先安装全局 CLI，再通过 skills add/remove 管理 skill，并在必要时自动清理旧的全局 bin 与 npm 残留。
• install / update 完成后会打印 ASCII 标识和快速开始提示，首次装好后能直接看到下一步命令。
• 命令层统一使用 InMemoryCliRegistry + Zod schema + jsonResult，便于 Agent 稳定调用。
• 共享了分页、项目 ID、可选文本、布尔值和导出格式等 Zod 片段，减少重复定义。
• API 客户端加入超时、重试和错误分层，遇到认证 / 网络 / 配置错误时可直接判断。

典型变化

• 输出模式：yapi <command> --output compact|normal|verbose|pretty 可切换结果粒度；--json 等价于结构化详细输出。
• 接口更新：interface-update 走部分更新语义，适合只修改 resBody / reqBody 等单个字段；interface-save 适合保存完整接口定义。
• 写保护：业务写命令需要显式追加 --confirm true，否则返回 preview 信息。
• 自检：yapi doctor --verbose 可检查 Node 版本、配置、网络连通性和认证状态。
• 版本记录：yapi changelog --limit 5、--version、--since、--raw 都可用。
• 补全：yapi completion bash|zsh|fish 会生成对应 shell 的补全脚本。
• 更新探测：yapi update 会先探测 npm 版本，再刷新 skill 文件。
• 快照查询：可先用 workspace-snapshot、project-snapshot、interface-snapshot 拿聚合上下文，再决定是否细查。
• URL 入口：可直接粘贴 YApi 页面 URL，让 CLI 自动解析并执行对应查询命令。

版本要求

• Node.js 版本：需要 Node.js >= 18。
• YApi 版本：支持 YApi 常见 REST API 和登录接口；登录方式同时兼容 token、普通账号、RSA 包装的普通账号和 LDAP 后端。

安装方式

推荐：一键安装 CLI + Skill

npx -y @cloudglab/yapi-cli@latest install

该命令会先安装全局 CLI，再通过 skills add 安装内置 Skill。首次安装时，会先检查本机是否已有可用配置；如果没有，会在交互终端里逐步提示你输入 YApi 地址、登录用户名、登录密码和认证方式。

安装或更新成功后，终端还会打印 ASCII 标识和一组快速开始命令，方便直接继续执行 yapi help、yapi config-init、yapi whoami 等操作。

如果需要重新安装 CLI 与 skill，可直接运行：

yapi install

如果想先检查更新再决定是否升级：

yapi update

常用命令示例

yapi help
yapi list
yapi --json help
yapi interface-list --project-id 1 --limit 20 --json
yapi project-list --output compact
yapi install
yapi version --verbose
yapi doctor
yapi changelog --limit 5
yapi completion bash

yapi config-init
yapi config-init --url https://yapi.example.com --username [email protected] --password secret --auth-mode native
yapi config-init --url https://yapi.example.com --username [email protected] --password secret --auth-mode ldap
yapi login
yapi login --token xxx
yapi login --email [email protected] --password secret --ldap true
yapi whoami

如果在 CI 或其他非交互环境中初始化配置，请显式传入 --url、--username、--password、--auth-mode。

如果本机之前残留了旧版全局 yapi / yapi-cli 可执行文件，install 会先尝试自动清理，再继续安装。

输出与管道

CLI 的日志走 stderr、结果走 stdout，二者已分离：

• --output compact|normal|verbose 已是合法 JSON，无需再用 python 重新解析；直接用 jq 提取字段即可。
• 拼管道时别加 2>&1，否则 [yapi] ... 日志会混进 stdout 破坏 JSON；丢弃日志用 2>/dev/null。
• resBody / resParams 等 YApi 字段是字符串化 JSON，用 jq '<path> | fromjson' 二次展开。

yapi --output verbose interface-get --interface-id 186512 2>/dev/null | jq '.interface.resBody | fromjson'

接口编辑示例

yapi interface-update --interfaceId 186512 --resBodyType json --resBody '{"errno":0,"data":[]}' --confirm true
yapi interface-save --projectId 1688 --interfaceId 186512 --catId 28376 --title "获取个人产品列表" --path "/flow-master/account/ownerProductList" --method POST --resBodyType json --resBody '{"errno":0,"data":[]}' --confirm true

常用命令示例

yapi group-list
yapi project-list --project-id 1
yapi interface-list --project-id 1 --limit 20
yapi request --path /api/user/status

yapi user-list
yapi user-search --query alice
yapi workspace-snapshot
yapi project-snapshot --project-id 1
yapi interface-snapshot --interface-id 123
yapi url-parse --url "https://yapi.example.com/project/1/interface/api/123"
yapi "https://yapi.example.com/project/1/interface/api/123"
yapi col-list --project-id 1
yapi docs-sync --file docs/api.md --project-id 1 --cat-id 2

可以这样问

下面这些自然语言请求可以交给 AI Skill / Agent 转成对应的 yapi-cli 命令。

账号 / 登录

• 看我当前是否登录。
• 用 token 登录。
• 用邮箱和密码登录。
• 检查当前配置是否可用。

项目 / 分组 / 接口

• 列出项目下的接口。
• 看某个接口的详情。
• 搜索某个关键词相关的接口。
• 看某个项目的分类、成员和环境。

用户 / 集合 / 导出

• 列出用户。
• 搜索用户。
• 查看测试集合。
• 导出项目数据。

文档同步 / 维护

• 把 Markdown 文档同步到 YApi。
• 检查当前环境是否健康。
• 看版本变更记录。
• 生成 shell 补全脚本。

目录结构

• src/core/：命令注册、解析、输出、自检、更新、补全。
• src/services/yapi/：YApi 服务层、认证、缓存和配置。
• src/tools/yapi/：业务命令注册入口。
• .agents/skills/yapi-cli/：skill 源目录。
• skills/yapi-cli/：构建时复制后的发布目录。

验证

pnpm typecheck
pnpm build
pnpm test
pnpm check
pnpm release:smoke-query