@cloudglab/yapi-cli 0.0.8 → 0.0.9

package/skills/yapi-cli/reference/project.md

@@ -2,96 +2,74 @@
 
 ## 强制判断
 
-先确认用户想查什么维度的项目信息：
-- **项目列表** → 查全量或按分组过滤
-- **项目详情** → 需要 `projectId`
-- **环境配置** → 需要 `projectId`
-- **项目成员** → 需要 `projectId`
-- **关注项目** → 查我关注的，不需要参数
-- **Mock 配置** → 项目级 Mock 开关和脚本
+- 项目 → 分类 → 接口的三层结构
+- 先 `group-list` 找 `groupId`，再 `project-create` 建项目
+- 建项目后自动生成 `local` 环境和 `公共分类` + `公共测试集`
+- 项目级 Mock 开关会级联影响全部接口
 
 ## 查询
 
-### 项目列表
-
-```bash
-yapi project-list [--groupId <id>] [--page 1] [--limit 50]
-```
-
-`--groupId` 可选，不传时查全部可见项目。
-
-### 项目详情
-
-```bash
-yapi project-get --projectId <id>
-```
-
-返回项目基本信息、分组、创建时间、统计等。
-
-### 项目 Token
-
-```bash
-yapi project-token --projectId <id>
-```
-
-获取项目的 API Token。
-
-### 环境配置
-
-```bash
-yapi env --projectId <id>
-```
-
-列出项目环境变量（域名、header 等）。
-
-### 项目成员
-
-```bash
-yapi member --projectId <id>
-```
-
-### 修改成员角色
-
-```bash
-yapi member-change-role --projectId <id> --memberUid <uid> --role <role> --confirm true
-```
-
-`--role` 支持：`owner`、`dev`、`guest`、`developer`、`viewer`
-
-### 关注项目
-
-```bash
-yapi follow
-```
-
-列出当前用户关注的项目。
-
-## 写入
-
-### Mock 开关
-
-```bash
-yapi project-mock-toggle --projectId <id> [--open true] --confirm true
-```
-
-### Mock 脚本
-
-```bash
-yapi project-mock-script --projectId <id> --script <script> --confirm true
-```
-
-设置项目级全局 Mock 脚本。脚本在沙箱中执行，可操控 `mockJson`、`httpCode`、`resHeader`、`delay`。
+| 场景 | 命令 | 用法 | 说明 |
+| --- | --- | --- | --- |
+| 项目列表 | `project-list` | `yapi project-list [--groupId <id>] [--page <n>] [--limit <n>]` | 所有项目 |
+| 项目搜索 | `project-search` | `yapi project-search --query <q> [--groupId <id>]` | 按名称搜 |
+| 项目详情 | `project-get` | `yapi project-get --projectId <id>` | 含 mock 字段 |
+| 项目 Token | `project-token` | `yapi project-token --projectId <id>` | 查询 token |
+| 项目快照 | `project-snapshot` | `yapi project-snapshot --projectId <id> [--interfaceLimit 10]` | 一次拿项目、分类、接口、环境 |
+| 项目环境 | `env` | `yapi env --projectId <id>` | 环境列表 |
+| 项目成员 | `member` | `yapi member --projectId <id>` | 成员列表 |
+| 关注项目 | `follow` | `yapi follow` | 关注的列表 |
+| Swagger URL | `project-swagger-url` | `yapi project-swagger-url --url <swagger-json-url>` | 服务端从该 URL 拉取 Swagger JSON 数据 |
+
+## 高频写入
+
+| 场景 | 命令 | 用法 | 说明 |
+| --- | --- | --- | --- |
+| 建项目前校名 | `project-check-name` | `yapi project-check-name --name <name> --groupId <id>` | 先查重名 |
+| 创建项目 | `project-create` | `yapi project-create --name <name> --groupId <id> [--basepath /api] [--projectType private] [--desc <desc>] [--tags a,b] [--preScript <js>] [--afterScript <js>] [--env <json>] --confirm true` | 建项目 |
+| 更新项目 | `project-update` | `yapi project-update --projectId <id> [--name <name>] [--basepath /api] [--desc <desc>] [--icon <icon>] [--color <color>] [--tags a,b] [--preScript <js>] [--afterScript <js>] [--projectMockScript <js>] --confirm true` | 改基础信息 |
+| 更新项目标签 | `project-tag-update` | `yapi project-tag-update --projectId <id> --tags 订单,支付 --confirm true` | 逗号分隔名称或 JSON 对象数组，覆盖标签 |
+| 重新生成 Token | `project-token-update` | `yapi project-token-update --projectId <id> --confirm true` | 旧 Token 失效 |
+| 关注项目 | `project-follow` | `yapi project-follow --projectId <id> --confirm true` | 加入关注 |
+| 取消关注 | `project-unfollow` | `yapi project-unfollow --projectId <id> --confirm true` | 取消关注 |
+| 改项目 Mock 开关 | `project-mock-toggle` | `yapi project-mock-toggle --projectId <id> [--open true] --confirm true` | 项目级 Mock |
+| 改项目 Mock 脚本 | `project-mock-script` | `yapi project-mock-script --projectId <id> --script <script> --confirm true` | 设置项目脚本 |
+| 加项目成员 | `project-member-add` | `yapi project-member-add --projectId <id> --uid <uid> [--role developer] --confirm true` | 加成员 |
+| 移除项目成员 | `project-member-remove` | `yapi project-member-remove --projectId <id> --uid <uid> --confirm true` | 移除成员 |
+| 改成员角色 | `project-member-role` | `yapi project-member-role --projectId <id> --memberUid <uid> [--role developer] --confirm true` | 默认 `developer` |
+| 改邮件通知 | `project-member-email-notice` | `yapi project-member-email-notice --projectId <id> --uid <uid> [--emailNotice true] --confirm true` | 控制邮件通知 |
+
+## 低频治理 / 迁移
+
+| 场景 | 命令 | 用法 | 说明 |
+| --- | --- | --- | --- |
+| 复制项目 | `project-copy` | `yapi project-copy --projectId <id> --groupId <gid> [--name <newName>] --confirm true` | 克隆项目到新分组 |
+| 覆盖环境配置 | `project-env-update` | `yapi project-env-update --projectId <id> --envs <json> --confirm true` | 整体覆盖环境 |
+| 删除项目 | `project-delete` | `yapi project-delete --projectId <id> --confirm true` | 不可恢复 |
 
 ## 参数对照
 
 | 参数名 | 类型 | 必填 | 说明 |
 |--------|------|------|------|
 | `projectId` | number | 大多数操作 | 项目 ID |
-| `groupId` | number | project-list 筛选 | 分组 ID |
+| `groupId` | number | project-copy / project-list 筛选 | 分组 ID |
 | `page` | number | 否 | 页码（默认 1） |
 | `limit` | number | 否 | 每页数（默认 50） |
-| `memberUid` | number | member-change-role | 成员用户 ID |
-| `role` | string | member-change-role | 角色枚举 |
+| `name` | string | project-check-name/create/update | 项目名 |
+| `query` | string | project-search | 搜索关键词 |
+| `basepath` | string | create/update | 项目前缀路径 |
+| `projectType` | string | project-create | `private` / `public` |
+| `tags` | string | create/update/tag-update | 逗号分隔标签；tag-update 也支持 `[{"name":"x","desc":"y"}]` 格式 |
+| `preScript` | string | create/update | 项目级前置脚本 |
+| `afterScript` | string | create/update | 项目级后置脚本 |
+| `projectMockScript` | string | update | 项目级全局 Mock 脚本 |
+| `env` | JSON 字符串 | create | 环境配置数组，如 `[{"name":"prod","domain":"https://api.example.com"}]` |
+| `uid` | number | project-member-add/remove | 成员用户 ID |
+| `memberUid` | number | project-member-role | 成员用户 ID |
+| `role` | string | project-member-role | 角色枚举 |
+| `emailNotice` | string | project-member-email-notice | 是否开启邮件通知 |
+| `envs` | string | project-env-update | 环境数组 JSON |
+| `interfaceLimit` | number | project-snapshot | 快照带出的接口数 |
 | `open` | boolean | mock-toggle | 是否开启 |
 | `script` | string | mock-script | Mock 脚本内容 |
 | `confirm` | boolean | 写操作 | 确认执行 |
@@ -101,15 +79,17 @@ yapi project-mock-script --projectId <id> --script <script> --confirm true
 ```bash
 # 查项目完整信息
 yapi project-get --projectId <id>
-yapi env --projectId <id>
-yapi member --projectId <id>
-yapi interface-list --projectId <id> --limit 50
 
-# 配置 Mock
-yapi project-mock-toggle --projectId <id> --open true --confirm true
-yapi project-mock-script --projectId <id> --script 'mockJson={code:0}' --confirm true
+# 查项目所在分组
+yapi group-get --id <groupId>
 
-# 分组成员管理
+# 查项目环境 + 成员
+yapi env --projectId <id>
 yapi member --projectId <id>
-yapi member-change-role --projectId <id> --memberUid <uid> --role dev --confirm true
+
+# 创建项目 → 更新标签 → 设 Mock 脚本 → 加成员
+yapi project-create --name '我的项目' --groupId <gid> --basepath /api --tags 订单,支付 --confirm true
+yapi project-tag-update --projectId <pid> --tags '订单,支付,用户' --confirm true
+yapi project-mock-script --projectId <pid> --script 'mockJson = { errcode: 0, errmsg: "success" };' --confirm true
+yapi project-member-add --projectId <pid> --uid 42 --role developer --confirm true
 ```

package/skills/yapi-cli/reference/scenarios.md

@@ -0,0 +1,184 @@
+# Scenarios
+
+典型链路示范。所有写命令示例都必须带 `--confirm true` 才能真实执行；省略时返回 preview。
+
+## 1. 首次接入新 YApi 实例
+
+```bash
+# 1. 安装 CLI + skill
+npx -y @cloudglab/yapi-cli@latest install
+
+# 2. 一键安装后会自动调起 init 流程；非交互场景可直接传参
+yapi config-init --url https://yapi.example.com --username dev@x --password *** --auth-mode native
+
+# 3. 校验登录态
+yapi whoami
+```
+
+## 2. 把浏览器 URL 转成 CLI 调用
+
+```bash
+# 把 https://yapi.example.com/project/123/interface/api-456 这种 URL 解析为结构化信息
+yapi url-parse --url 'https://yapi.example.com/project/123/interface/api-456'
+
+# 也可以直接把 URL 作为第一个参数；CLI 会自动 dispatch
+yapi 'https://yapi.example.com/project/123/interface/api-456'
+```
+
+## 3. 工作区 / 项目 / 接口 上下文三连
+
+```bash
+# 一次拿到账号 + 分组 + 项目列表
+yapi workspace-snapshot --project-limit 10
+
+# 进入项目后拿分类、最近接口、环境
+yapi project-snapshot --project-id 123 --interface-limit 10
+
+# 看具体接口的请求 / 响应 + 最近 5 条变更
+yapi interface-snapshot --interface-id 456 --log-limit 5
+```
+
+## 4. 批量调整 Mock 策略
+
+```bash
+# 打开项目级 Mock
+yapi project-mock-toggle --project-id 123 --open true --confirm true
+
+# 设置项目级 Mock 脚本
+yapi project-mock-script --project-id 123 --script 'mockval = { code: 0, data: { ok: true } };' --confirm true
+
+# 给单个接口加 Mock 脚本
+yapi interface-mock-script --interface-id 456 --script 'mockval = { code: 0, data: { id: 1 } };' --confirm true
+```
+
+## 5. 创建接口时保持风格一致
+
+```bash
+# 1. 先看目标分类有哪些接口，了解已有风格
+yapi category-get --catId <id>
+
+# 2. 创建接口时指定目标分类，CLI 自动分析风格
+yapi interface-create \
+  --project-id <pid> \
+  --cat-id <cid> \
+  --title '订单查询-分页' \
+  --path '/api/order/list' \
+  --desc '分页查询订单，保持与分类中其他接口一致的响应结构' \
+  --confirm true
+# CLI 会返回该分类已有接口的风格分析：
+#   - 公共路径前缀：/api/order/
+#   - 常用方法：GET
+#   - 常用请求体字段：page, size, status
+#   - 常用响应体字段：code, data, message, total
+
+# 3. 预填 reqBody/resBody 时参考风格分析的字段
+yapi interface-create \
+  --project-id <pid> \
+  --cat-id <cid> \
+  --title '订单详情' \
+  --path '/api/order/detail' \
+  --method GET \
+  --reqBody '{"page":1,"size":20}' \
+  --resBody '{"code":0,"data":{"id":1,"status":"paid"},"message":"success"}' \
+  --confirm true
+```
+
+## 6. 高级 Mock 配置
+
+```bash
+# 列出接口现有高级 Mock 期望
+yapi mock-expect-list --interface-id <iid>
+
+# 添加一个 Mock 期望：匹配参数 type=1，返回特定响应
+yapi mock-expect-save \
+  --interface-id <iid> \
+  --project-id <pid> \
+  --name '参数匹配-类型1' \
+  --params '{"type":"1"}' \
+  --resBody '{"code":0,"data":{"type":1,"name":"mock数据"}}' \
+  --code 200 \
+  --confirm true
+
+# 设置或更新高级 Mock 脚本（沙箱 JS）
+yapi mock-script-save \
+  --interface-id <iid> \
+  --project-id <pid> \
+  --script 'if (params.type == 1) { mockJson.errcode = 400; }' \
+  --confirm true
+
+# 快速开关期望（不删除）
+yapi mock-expect-toggle --case-id <objectId> --enable false --confirm true
+```
+
+## 7. 导入 Swagger / OpenAPI
+
+```bash
+# 把本地 swagger 文档直接导入（content 是 JSON 字符串）
+yapi interface-upload --project-id 123 --type swagger --content "$(cat swagger.json)" --confirm true
+
+# 也可以走 importData（同步合并策略）
+yapi import --project-id 123 --type swagger --content "$(cat swagger.json)" --merge normal --confirm true
+```
+
+## 8. 测试集合与用例
+
+```bash
+# 创建集合
+yapi col-create --project-id 123 --name '回归冒烟-生产' --desc 'P0 用例' --confirm true
+
+# 批量添加用例
+yapi case-add-list \
+  --col-id 11 \
+  --project-id 123 \
+  --case-list '[{"req_method":"GET","req_url":"/api/health"}]' \
+  --confirm true
+
+# 运行集合脚本
+yapi case-run --col-id 11 --confirm true
+```
+
+## 9. 用户与权限管理（需要管理员）
+
+```bash
+yapi user-list --page 1 --limit 20
+yapi user-search --query 'dev'
+yapi project-member-add --project-id 123 --uid 42 --role developer --confirm true
+yapi project-member-role --project-id 123 --member-uid 42 --role viewer --confirm true
+```
+
+## 10. Token 静默登录（CI / 脚本场景）
+
+```bash
+# 方式 1：环境变量
+export YAPI_URL=https://yapi.example.com
+export YAPI_TOKEN=eyJhbGciOiJIUzI1...
+
+# 方式 2：CLI 参数
+yapi login-by-token --token eyJhbGciOiJIUzI1... --confirm true
+```
+
+## 11. 写操作保护与 preview
+
+```bash
+# 不带 confirm 会返回 preview（不真正写入）
+yapi interface-delete --interface-id 456
+# → 返回 { ok: false, preview: true, reason: "写操作缺少确认", ... }
+
+# 加 confirm 才会真正写入
+yapi interface-delete --interface-id 456 --confirm true
+
+# 整体禁用写操作
+export YAPI_DISABLE_WRITE=true
+yapi project-delete --project-id 123
+# → 全部写命令即使加 --confirm 也会被拒
+```
+
+## 12. URL 解析 + 命令 dispatch
+
+```bash
+# 直接传 URL：CLI 会调用 url-parse 并尝试执行对应查询命令
+yapi 'https://yapi.example.com/project/123/interface/api-456'
+# 等价于：
+#   yapi url-parse --url '...'
+#   yapi interface-get --interface-id 456
+```

package/skills/yapi-cli/reference/test.md

@@ -2,14 +2,12 @@
 
 ## 强制判断
 
-测试命令用于发送 HTTP 请求并查看响应，主要用于接口调试和验证：
+- **HTTP 方法测试** → `test-*`
+- **上传** → `test-single-upload` / `test-files-upload`
+- **响应分析** → `test-http-code` / `test-raw` / `test-response`
+- **自动测试** → `open-run-auto-test` / `open-project-interface-data`
 
-- **标准 HTTP 测试** → 测试 GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH
-- **上传测试** → 单文件或多文件上传
-- **响应分析** → 检查状态码、原始响应、响应结构
-- **自动测试** → 运行项目预设的自动测试
-
-所有测试命令都接受 `--url <url>` 参数（完整 URL，不是路径），不需要 YApi 认证。
+除自动测试外，测试命令都用完整 `--url`，且不依赖 YApi 登录。
 
 ## HTTP 方法测试
 
@@ -19,7 +17,7 @@
 yapi test-get --url https://api.example.com/endpoint [--params '{"key":"value"}']
 ```
 
-`--params` 为 JSON 字符串，转为查询参数。
+`--params` 是 JSON 字符串，会转成查询参数。
 
 ### POST
 
@@ -27,7 +25,7 @@ yapi test-get --url https://api.example.com/endpoint [--params '{"key":"value"}'
 yapi test-post --url https://api.example.com/endpoint [--body '{"key":"value"}']
 ```
 
-`--body` 为 JSON 字符串，作为请求体。
+`--body` 是 JSON 字符串。
 
 ### PUT / DELETE / PATCH
 
@@ -66,7 +64,7 @@ yapi test-files-upload --url https://api.example.com/upload --filePaths /path/a
 yapi test-http-code --url https://api.example.com/endpoint
 ```
 
-只返回 HTTP 状态码。
+只返回状态码。
 
 ### 原始响应
 
@@ -74,7 +72,7 @@ yapi test-http-code --url https://api.example.com/endpoint
 yapi test-raw --url https://api.example.com/endpoint
 ```
 
-查看原始文本响应，不解析 JSON。
+返回原始文本。
 
 ### 响应结构
 
@@ -82,22 +80,22 @@ yapi test-raw --url https://api.example.com/endpoint
 yapi test-response --url https://api.example.com/endpoint
 ```
 
-查看完整响应结构（状态码、头、体）。
+返回状态码、头、体。
 
 ## 自动测试
 
 ### 运行自动测试
 
 ```bash
-yapi run-auto-test --projectId <id> [--format json]
+yapi open-run-auto-test --pid <id> --colId <id> [--envParamsId <id>]
 ```
 
-调用 YApi 项目的自动测试功能。
+调用 YApi 自动测试。
 
 ### 项目接口数据
 
 ```bash
-yapi project-interface-data --projectId <id>
+yapi open-project-interface-data --projectId <id> [--page <n>] [--limit <n>] [--keyword <q>]
 ```
 
 查询项目接口测试数据。
@@ -111,8 +109,13 @@ yapi project-interface-data --projectId <id>
 | `params` | string | get/files-upload | JSON 查询参数 |
 | `filePath` | string | single-upload | 上传文件路径 |
 | `filePaths` | string[] | files-upload | 多文件上传路径 |
-| `projectId` | number | run-auto-test | 项目 ID |
-| `format` | string | 否 | 输出格式（json） |
+| `pid` | number | open-run-auto-test | 项目 ID |
+| `colId` | number | open-run-auto-test | 测试集合 ID |
+| `envParamsId` | number | 否 | 环境参数 ID |
+| `projectId` | number | open-project-interface-data | 项目 ID |
+| `page` | number | 否 | 页码 |
+| `limit` | number | 否 | 每页数量 |
+| `keyword` | string | 否 | 关键词筛选 |
 
 ## 常见链路
 

package/skills/yapi-cli/reference/tooling.md

@@ -0,0 +1,89 @@
+# 集合 / 用例 / 导入导出 / 快照
+
+## 强制判断
+
+- **工作区 / 链接定位** → `workspace-snapshot` / `url-parse`
+- **测试集合** → `col-*`
+- **测试用例** → `case-*`
+- **导入导出 / 文档同步** → `import` / `export` / `docs-sync`
+- **动态日志** → `log-list-by-update`
+
+## 高频查询
+
+| 场景 | 命令 | 用法 | 说明 |
+| --- | --- | --- | --- |
+| 工作区快照 | `workspace-snapshot` | `yapi workspace-snapshot [--projectLimit 10] [--groupLimit 10] [--followLimit 10]` | 一次取账号、分组、项目、关注 |
+| 页面 URL 解析 | `url-parse` | `yapi url-parse --url <yapi-page-url>` | 从页面反推命令 |
+| 集合列表 | `col-list` | `yapi col-list --projectId <id>` | 查项目下测试集合 |
+| 集合用例 | `col-cases` | `yapi col-cases --projectId <id> --colId <id>` | 查某集合下用例 |
+| 用例详情 | `case-get` | `yapi case-get --caseId <id>` | 查单个测试用例 |
+| 用例环境 | `case-env-list` | `yapi case-env-list --caseId <id>` | 看用例环境变量 |
+| 变量筛选用例 | `col-case-list-by-var-params` | `yapi col-case-list-by-var-params --projectId <id> --colId <id>` | 按变量筛用例 |
+| 动态日志 | `log-list-by-update` | `yapi log-list-by-update --apid <id> [--type interface] [--limit 20]` | 查更新日志 |
+
+## 高频写入
+
+| 场景 | 命令 | 用法 | 说明 |
+| --- | --- | --- | --- |
+| 创建集合 | `col-create` | `yapi col-create --projectId <id> --name <name> [--desc <desc>] --confirm true` | 新建集合 |
+| 更新集合 | `col-update` | `yapi col-update --colId <id> [--name <name>] [--desc <desc>] --confirm true` | 改集合信息 |
+| 删除集合 | `col-delete` | `yapi col-delete --colId <id> --confirm true` | 删除集合 |
+| 调整集合排序 | `col-up-index` | `yapi col-up-index --projectId <id> --ids 1,2,3 --confirm true` | 批量调顺序 |
+| 克隆集合用例 | `col-case-clone` | `yapi col-case-clone --projectId <id> --colId <target> --srcColId <source> --confirm true` | 从另一集合复制 |
+| 调整用例排序 | `col-case-up-index` | `yapi col-case-up-index --colId <id> --ids 1,2,3 --confirm true` | 调整用例顺序 |
+| 添加用例 | `case-add` | `yapi case-add --projectId <id> --colId <id> --interfaceId <id> --name <name> [--env <name>] --confirm true` | 关联已有接口的单条用例 |
+| 批量添加用例 | `case-add-list` | `yapi case-add-list --projectId <id> --colId <id> --caseList <json> --confirm true` | 批量导入 |
+| 更新用例 | `case-update` | `yapi case-update --caseId <id> [--caseType col] [--method POST] [--url /api/demo] --confirm true` | 改用例字段 |
+| 删除用例 | `case-delete` | `yapi case-delete --caseId <id> --confirm true` | 删除单个用例 |
+| 运行集合 / 用例脚本 | `case-run` | `yapi case-run --colId <id> --confirm true` | 执行脚本 |
+
+## 低频治理 / 迁移
+
+| 场景 | 命令 | 用法 | 说明 |
+| --- | --- | --- | --- |
+| 导入项目数据 | `import` | `yapi import --projectId <id> --type swagger --content <json> [--merge normal] --confirm true` | 支持 swagger/json/har/postman |
+| 导出项目数据 | `export` | `yapi export --projectId <id> [--format json]` | 导出 JSON / Swagger / OpenAPI3 / HTML / Markdown |
+| 文档同步 | `docs-sync` | `yapi docs-sync --file <p> --projectId <id> --catId <id> [--merge create|update|skip] [--watch true] --confirm true` | 从 markdown 同步到 YApi |
+
+## 参数对照
+
+| 参数名 | 类型 | 归属命令 | 说明 |
+| --- | --- | --- | --- |
+| `projectId` | number | col/import/export | 项目 ID |
+| `colId` | number | col/case | 集合 ID |
+| `srcColId` | number | col-case-clone | 源集合 ID |
+| `caseId` | number | case-get/update/delete/env-list | 用例 ID |
+| `interfaceId` | number | case-add | 关联接口 ID |
+| `name` | string | case-create/add | 用例名称 |
+| `env` | string | case-add | 用例环境名 |
+| `ids` | string | col-up-index / col-case-up-index | 逗号分隔 ID 列表 |
+| `caseList` | string | case-add-list | 用例数组 JSON |
+| `format` | string | export | 导出格式：json / swagger / openapi3 / html / markdown |
+| `type` | string | import/log-list-by-update | 导入类型或日志类型 |
+| `content` | string | import | 导入内容 |
+| `merge` | string | import/docs-sync | 合并策略 |
+| `apid` | number | log-list-by-update | 接口 ID |
+| `url` | string | url-parse | YApi 页面 URL |
+| `projectLimit` | number | workspace-snapshot | 项目快照上限 |
+| `groupLimit` | number | workspace-snapshot | 分组快照上限 |
+| `followLimit` | number | workspace-snapshot | 关注项目快照上限 |
+| `confirm` | boolean | 写操作 | 确认执行 |
+
+## 常见链路
+
+```bash
+# 从页面 URL 反推命令，再取工作区快照
+yapi url-parse --url <yapi-page-url>
+yapi workspace-snapshot --projectLimit 10
+
+# 新建集合 -> 加用例 -> 运行
+yapi col-create --projectId <id> --name <name> --confirm true
+yapi case-add --projectId <pid> --colId <colId> --interfaceId <iid> --name '健康检查' --confirm true
+yapi case-run --colId <colId> --confirm true
+
+# 导入 / 导出 / 文档同步
+yapi export --projectId <id> --format openapi3
+yapi export --projectId <id> --format markdown
+yapi import --projectId <id> --type swagger --content <json> --confirm true
+yapi docs-sync --file ./docs/api.md --projectId <id> --catId <id> --merge update --confirm true
+```

package/dist/services/yapi/cache.d.ts

@@ -1,27 +0,0 @@
-/**
- * 简单的 JSON 文件缓存。
- * 缓存项目列表/接口列表等数据，减少 YApi API 请求。
- */
-export declare class YApiCache {
-    private readonly cacheDir;
-    private readonly ttlMs;
-    private cache;
-    private dirty;
-    constructor(cacheDir: string, ttlMs?: number);
-    /** 获取缓存目录路径 */
-    static getCacheDir(homeDir: string): string;
-    /** 获取缓存文件路径 */
-    private get cacheFile();
-    /** 加载持久化缓存 */
-    load(): void;
-    /** 持久化缓存到磁盘 */
-    save(): void;
-    /** 获取缓存项 */
-    get<T>(key: string): T | undefined;
-    /** 设置缓存项 */
-    set(key: string, data: unknown): void;
-    /** 删除缓存项 */
-    delete(key: string): void;
-    /** 清空缓存 */
-    clear(): void;
-}

package/dist/services/yapi/cache.js

@@ -1,88 +0,0 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-/**
- * 简单的 JSON 文件缓存。
- * 缓存项目列表/接口列表等数据，减少 YApi API 请求。
- */
-export class YApiCache {
-    constructor(cacheDir, ttlMs = 5 * 60 * 1000) {
-        this.cacheDir = cacheDir;
-        this.ttlMs = ttlMs;
-        this.cache = new Map();
-        this.dirty = false;
-    }
-    /** 获取缓存目录路径 */
-    static getCacheDir(homeDir) {
-        return join(homeDir, '.yapi-cache');
-    }
-    /** 获取缓存文件路径 */
-    get cacheFile() {
-        return join(this.cacheDir, 'cache.json');
-    }
-    /** 加载持久化缓存 */
-    load() {
-        try {
-            if (!existsSync(this.cacheFile))
-                return;
-            const raw = readFileSync(this.cacheFile, 'utf-8');
-            const data = JSON.parse(raw);
-            for (const [key, entry] of Object.entries(data)) {
-                this.cache.set(key, entry);
-            }
-        }
-        catch {
-            // 缓存文件损坏则忽略
-        }
-    }
-    /** 持久化缓存到磁盘 */
-    save() {
-        if (!this.dirty)
-            return;
-        try {
-            const dir = dirname(this.cacheFile);
-            if (!existsSync(dir)) {
-                mkdirSync(dir, { recursive: true });
-            }
-            const data = {};
-            for (const [key, entry] of this.cache.entries()) {
-                data[key] = entry;
-            }
-            writeFileSync(this.cacheFile, JSON.stringify(data, null, 2), 'utf-8');
-            this.dirty = false;
-        }
-        catch {
-            // 忽略写入错误
-        }
-    }
-    /** 获取缓存项 */
-    get(key) {
-        const entry = this.cache.get(key);
-        if (!entry)
-            return undefined;
-        if (Date.now() - entry.time > this.ttlMs) {
-            this.cache.delete(key);
-            this.dirty = true;
-            return undefined;
-        }
-        return entry.data;
-    }
-    /** 设置缓存项 */
-    set(key, data) {
-        this.cache.set(key, { data, time: Date.now() });
-        this.dirty = true;
-    }
-    /** 删除缓存项 */
-    delete(key) {
-        if (this.cache.delete(key)) {
-            this.dirty = true;
-        }
-    }
-    /** 清空缓存 */
-    clear() {
-        if (this.cache.size > 0) {
-            this.cache.clear();
-            this.dirty = true;
-        }
-    }
-}
-//# sourceMappingURL=cache.js.map

package/dist/services/yapi/cache.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/services/yapi/cache.ts"],"names":[],"mappings":"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"}