@cloudglab/yapi-cli 0.0.5 → 0.0.7

package/docs/ai-cli-optimization-plan.md

@@ -0,0 +1,412 @@
+# yapi-cli 面向 AI 的 CLI 深度优化方案
+
+## 目标
+
+阅读参考项目 `zentao-cli` 后，可以把它的 AI 友好设计拆成 5 类能力：
+
+1. 更省 token 的输出
+2. 更短路径的 help / list / 下一步引导
+3. 更明确的参数语义与错误信息
+4. 更低干扰的更新探针
+5. 更少请求次数的缓存、指标与快照命令
+
+`yapi-cli` 当前已经有一部分基础能力，但还没有把这些能力真正串成完整体验。
+
+---
+
+## 参考项目里最值得迁移的设计
+
+### 1. 输出分级，而不是只有 `--json`
+
+`zentao-cli` 的核心不是“能输出 JSON”，而是“能输出适合 AI 首轮探测的 JSON”。
+
+建议保留 3 档：
+
+- `compact`：默认给 AI，用于首轮探测
+- `normal`：默认给脚本/排查，保留主要字段
+- `verbose`：完整原始 JSON
+
+其中 `compact` 的关键规则：
+
+- 长文本字段截断
+- 长数组只保留前 N 项，同时补 `total`
+- 大对象只保留高价值字段
+- 自动补 `meta.requestCount`、`meta.durationMs`、`meta.cacheHit`
+
+这能显著降低 token 消耗，也更适合 agent 做后续决策。
+
+### 2. help 不是罗列命令，而是引导下一步
+
+`zentao-cli` 的 help / list 设计重点：
+
+- 先告诉用户怎么开始
+- 按场景分组命令
+- 每个命令给出成本提示
+- 每个命令给出“下一步推荐命令”
+
+这对 AI 特别重要，因为它可以减少 agent 自己摸索命令链路的成本。
+
+### 3. 参数描述要写业务语义，不只是类型
+
+`zentao-cli` 不是只写“这个参数是 number/string”，而是写：
+
+- 这个参数的业务意义
+- 推荐值
+- 优先级和互斥关系
+- 历史兼容行为
+- 某些版本是否会忽略该参数
+
+这会直接降低 AI 调错参数、误解参数含义、反复试错的概率。
+
+### 4. 错误信息要能直接指导修复
+
+好错误信息不只是 `message + hint`，而是：
+
+- 失败分类
+- 已尝试的 fallback
+- 实际请求目标
+- 返回状态与关键响应
+- 用户下一步应检查什么
+
+这种设计对 agent 很关键，因为它能减少“再试一次看看”的盲试行为。
+
+### 5. 更新检查要轻量且异步
+
+`zentao-cli` 的更新检查不会阻塞正常命令，也不会每次都打 npm。
+
+建议保留这些原则：
+
+- 内置命令跳过更新探针
+- 每天最多检查一次
+- 后台异步执行
+- 提示写到 `stderr`
+- 允许环境变量关闭
+
+### 6. 快照命令比让 AI 串多跳命令更省
+
+`zentao-cli` 专门设计“快照命令”，把原本多次请求、多次拼装的信息压缩成一次调用。
+
+对 AI 来说，这比单纯增加更多原子命令更有价值。
+
+---
+
+## yapi-cli 当前已经具备的基础
+
+这些不用重做，应直接复用：
+
+### 已有基础能力
+
+- `src/core/cli-registry.ts` 已支持严格参数解析、`--key value` / `--key=value`、未知参数报错、布尔/数字/数组/object coercion
+- `src/core/cli-registry.ts` 已有 `metadata.costHint` 和 `metadata.nextBestTools`
+- `src/core/manifest.ts` 已有命令到分组的映射能力
+- `src/tools/yapi/register-*.ts` 里已经给不少命令写了 `costHint` / `nextBestTools`
+- `src/core/errors.ts` 已有 `CliError` 分层
+- `src/install.ts` 已有 install / update 的引导和 ASCII banner
+
+### 当前短板
+
+- `src/cli.ts` 只有 `--json`，没有 `compact|normal|verbose`
+- `src/core/output.ts` 的 `json` 仍是完整 `JSON.stringify`
+- `src/core/cli-output.ts` 还没有消费 `costHint` / `nextBestTools`
+- `src/core/cli-output.ts` 的 `list` 仍等于总 help，没有独立分组导航
+- `src/core/update-probe.ts` 仍是同步阻塞式 `npm view`
+- `src/services/yapi/api.ts` 还没有统一请求指标、GET 缓存、cacheHit 元信息
+- 业务命令还缺少面向 AI 的“快照命令”
+
+---
+
+## 可落地改造清单
+
+下面按优先级排序，建议按 P0 → P1 → P2 实施。
+
+## P0：一周内就能落地，且收益最大
+
+### P0-1. 引入 `--output compact|normal|verbose`
+
+目标：让默认输出变成 AI 友好，而不是完整 JSON。
+
+改造点：
+
+- `src/cli.ts`
+  - 新增全局 `--output compact|normal|verbose|pretty`
+  - 保留 `--json` 作为兼容写法，等价到 `--output verbose` 或 `--output normal`，需要明确最终语义
+- `src/tools/shared.ts`
+  - 把 `setOutputFormat()` 从二值改成多档模式
+- `src/core/output.ts`
+  - 增加 `compact` / `normal` / `verbose` 三档 JSON 序列化策略
+  - 抽出统一 `summarizeForCompact()`
+  - 为数组输出自动补 `{ total, items }`
+  - 为长文本字段做裁剪
+
+建议默认值：
+
+- 终端默认 `pretty`
+- 显式要求结构化结果时默认 `compact`
+
+如果不想改变现有默认行为，也可以：
+
+- `pretty` 保持现状
+- `--json` 改为 `compact`
+- `--output verbose` 才返回完整 JSON
+
+这是最稳妥的兼容方案。
+
+### P0-2. 让 `help` / `list` 真正消费 metadata
+
+目标：把已经存在的数据层能力变成用户可见能力。
+
+改造点：
+
+- `src/core/cli-output.ts`
+  - `printHelp()` 改成按分组展示业务命令
+  - `printCommandHelp()` 增加：
+    - 预估成本 `costHint`
+    - 下一步 `nextBestTools`
+    - 输出模式提示
+- `src/core/manifest.ts`
+  - 扩展分组显示名映射，不直接暴露 `auth/group/project/interface/util/test` 这种内部代号
+- `src/tools/yapi/groups.ts`
+  - 补充适合 AI 的分组文案，例如：
+    - 开始使用
+    - 账号认证
+    - 项目与分组
+    - 接口查询与检索
+    - 导出与实用工具
+    - 自动化测试
+
+建议输出风格：
+
+- 总 help 只推荐少量高价值命令
+- `list` 再给完整分组清单
+- 每个帮助结尾都有“下一步”
+
+### P0-3. 提升错误信息密度
+
+目标：减少 agent 盲试。
+
+改造点：
+
+- `src/core/errors.ts`
+  - 新增更细的错误 code 到可读消息映射
+  - 统一把 hint 设计成“下一步操作建议”
+- `src/services/yapi/api.ts`
+  - 对登录失败、401、403、404、网络超时、空响应、JSON 解析失败分别给不同提示
+  - 把已尝试的 fallback 写进错误消息
+
+建议优先补这些高频场景：
+
+- 配置缺失
+- 登录失败
+- 服务端不可达
+- token 失效
+- 项目/接口不存在
+- 后端返回非 JSON
+
+### P0-4. 把更新检查改成轻量探针
+
+目标：避免 `yapi update` 之外的命令被同步 `npm view` 拖慢。
+
+改造点：
+
+- `src/core/update-probe.ts`
+  - 改成缓存文件 + 最短检查间隔
+  - 支持后台异步查询
+  - 支持 `YAPI_SKIP_UPDATE_CHECK=true`
+- `src/cli.ts`
+  - 对业务命令执行前或执行后触发非阻塞探针
+  - `help/list/version/install/update` 默认跳过
+
+---
+
+## P1：明显提升“AI 用起来顺不顺”
+
+### P1-1. 增加请求指标与轻量缓存
+
+目标：让 AI 能知道“这次调用贵不贵”“有没有命中缓存”。
+
+改造点：
+
+- 新增 `src/core/http-metrics.ts`
+  - 记录本次命令的 `requestCount`
+  - 记录最近一次 `durationMs`
+- `src/services/yapi/api.ts`
+  - 抽出统一 `request()` 封装
+  - GET 请求加短时内存缓存
+  - 命中缓存时返回 `cacheHit: true`
+- `src/core/output.ts`
+  - 把指标统一塞到 `meta`
+
+建议缓存策略：
+
+- 仅缓存 GET
+- TTL 10~15 秒
+- key 包含 URL + query + 登录态标识
+
+### P1-2. 增加 2~3 个快照命令
+
+目标：减少 AI 串联多个命令的成本。
+
+建议优先做这些：
+
+- `getProjectSnapshot`
+  - 输出项目基础信息 + 分类数量 + 接口数量 + 最近更新接口
+- `getInterfaceSnapshot`
+  - 输出接口基础信息 + 请求/响应摘要 + 测试状态 + 最近变更
+- `getWorkspaceSnapshot`
+  - 输出我的账号、可访问项目、最近活跃项目、关注项
+
+推荐放在：
+
+- `src/tools/yapi/register-project.ts`
+- `src/tools/yapi/register-interface.ts`
+- 或新增 `src/tools/yapi/register-snapshot.ts`
+
+如果要新增分组，可以把 `src/tools/yapi/groups.ts` 从 6 组扩为 7 组，加入 `snapshot`。
+
+### P1-3. 给参数描述补业务语义
+
+目标：help 直接可用，不需要翻源码猜参数。
+
+做法：
+
+- 逐步检查 `src/tools/yapi/register-*.ts`
+- 把只写“项目 ID / 接口 ID / 关键字”的描述，补成：
+  - 传什么
+  - 推荐格式
+  - 适用场景
+  - 是否支持多个值
+  - 与其他参数的优先级关系
+
+优先补这些高频命令：
+
+- `listProjects`
+- `getProjectDetail`
+- `searchInterfaces`
+- `getInterfaceDetail`
+- `exportProject`
+- `runAutoTest`
+
+---
+
+## P2：中期优化，锦上添花
+
+### P2-1. 角色化 help 视图
+
+如果后续命令继续增多，可以引入角色视图：
+
+- `dev`
+- `qa`
+- `pm`
+- `admin`
+
+这样 `help` 与 `list` 可以只展示更相关的命令集合。
+
+目前 `yapi-cli` 命令规模还不算特别大，这项不是第一优先级。
+
+### P2-2. URL / 页面名转命令
+
+如果用户经常从浏览器页面复制 YApi URL，再转成 CLI 调用，可以考虑支持：
+
+- 从项目 URL 自动提取 `projectId`
+- 从接口 URL 自动提取 `interfaceId`
+
+这个能力很适合 AI 与人混合使用场景，但不是当前最急的点。
+
+---
+
+## 推荐实施顺序
+
+### 第一阶段：先把“输出 + help”做好
+
+优先做：
+
+1. `--output compact|normal|verbose`
+2. `help/list` 消费 `costHint` 和 `nextBestTools`
+3. `compact` 输出裁剪规则
+
+原因：
+
+- 改动范围集中
+- 不需要改后端协议
+- 对 AI 体验提升最大
+- 风险比缓存和快照命令更低
+
+### 第二阶段：再做“错误 + 更新探针”
+
+优先做：
+
+1. `src/services/yapi/api.ts` 错误归因增强
+2. `src/core/update-probe.ts` 轻量化
+
+原因：
+
+- 这两项能显著降低误报和等待时间
+- 不会影响业务命令接口定义
+
+### 第三阶段：最后做“缓存 + 快照命令”
+
+优先做：
+
+1. 请求指标
+2. GET 短缓存
+3. 快照命令
+
+原因：
+
+- 这部分收益大，但需要更谨慎设计返回结构
+- 需要额外验证是否会误导用户读取到短时缓存数据
+
+---
+
+## 最小可执行版本（建议直接开做）
+
+如果只做一轮小改动，我建议锁定下面 4 项：
+
+1. `src/cli.ts` + `src/tools/shared.ts` + `src/core/output.ts`
+   - 加入 `--output compact|normal|verbose`
+2. `src/core/cli-output.ts`
+   - 单命令帮助展示 `costHint`、`nextBestTools`
+   - `list` 改为按组展示
+3. `src/core/update-probe.ts`
+   - 改成每日一次、非阻塞探针
+4. `src/services/yapi/api.ts`
+   - 登录/网络/API 错误信息更具体
+
+这 4 项做完，`yapi-cli` 的 AI 可用性就会有明显提升，而且不会引入太多新命令和新概念。
+
+---
+
+## 建议暂时不要照搬的点
+
+下面这些不建议第一轮就照搬：
+
+- 复杂角色系统
+- 过多快照命令
+- 过深的 URL 到命令自动推导
+- 为所有命令都做高度定制 pretty 输出
+
+原因很简单：
+
+- `yapi-cli` 当前最缺的不是“功能数量”，而是“默认输出质量”和“help 的引导能力”
+- 先把这两件事补齐，收益最大
+
+---
+
+## 结论
+
+`zentao-cli` 最值得迁移到 `yapi-cli` 的，不是单个命令，而是一套设计原则：
+
+- 默认给 AI 低成本输出
+- 用 help 明确下一步，而不是让 AI 猜
+- 参数描述写业务语义，而不是只写类型
+- 错误信息直接指向修复动作
+- 用快照命令减少多跳调用
+
+对 `yapi-cli` 来说，最现实的落地方向是：
+
+1. 先改输出分级
+2. 再改 help / list / metadata 展示
+3. 再补错误与更新探针
+4. 最后做缓存、指标和快照命令
+
+这样改，投入小，收益快，也最适合当前仓库的演进节奏。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudglab/yapi-cli",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "private": false,
   "type": "module",
   "main": "dist/index.js",