@cloudglab/yapi-cli 0.0.7 → 0.0.9

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

@@ -2,12 +2,12 @@
 
 ## 强制判断
 
-在调用任何认证或用户管理命令前，先判断用户意图：
+先分四类：
 
-1. **配置初始化** → 新用户首次使用，可直接运行 `config-init` 交互填写，也可显式传 `--url` + `--username` + `--password` + `--auth-mode`
-2. **登录** → 区分 token 登录 vs 密码登录（普通 native / LDAP）
-3. **查看当前用户** → `whoami`，不需要参数
-4. **用户管理** → 管理员操作，需要确认是否有权限
+1. **首次配置** → `config-init`
+2. **登录** → token 或密码
+3. **看当前身份** → `whoami`
+4. **管用户** → 先确认管理员权限
 
 ## 认证
 
@@ -18,12 +18,12 @@ yapi config-init --url https://yapi.example.com --username user@example.com --pa
 yapi config-init --url https://yapi.example.com --username user@example.com --password secret --auth-mode ldap
 ```
 
-- `--url`：YApi 服务地址（必填）
-- `--username`：登录用户名（通常是邮箱）
-- `--password`：登录密码
-- `--auth-mode`：认证方式，支持 `native` / `ldap`
+- `--url`：YApi 地址
+- `--username`：用户名，通常是邮箱
+- `--password`：密码
+- `--auth-mode`：`native` / `ldap`
 
-如果不传 `--url`、`--username`、`--password`、`--auth-mode`，`install` / `config-init` 会在交互终端里逐步提示你填写；其中 `auth-mode` 会引导你选择普通登录还是 LDAP 登录。
+不传参数时，`install` / `config-init` 会交互收集配置。
 
 ### Token 登录
 
@@ -32,7 +32,7 @@ yapi login --token <token>
 yapi login-by-token --token <token>
 ```
 
-`login-by-token` 用于快速校验 token；`uid` 会从 JWT 中自动提取。
+`login-by-token` 更适合校验 token 是否可用。
 
 ### 密码登录
 
@@ -43,7 +43,7 @@ yapi login --email <email> --password <password>
 yapi login --username <username> --password <password> --ldap true
 ```
 
-不带参数时，默认读取 `~/.yapi/config.json` 里的 `username/password/authMode` 登录。
+不带参数时，默认读取 `~/.yapi/config.json`。
 
 ### 登出
 
@@ -51,7 +51,7 @@ yapi login --username <username> --password <password> --ldap true
 yapi logout
 ```
 
-清除本地认证缓存，同时调用服务端登出接口。
+清理本地认证并请求服务端登出。
 
 ### 查看当前用户
 
@@ -59,44 +59,29 @@ yapi logout
 yapi whoami
 ```
 
-优先从本地认证缓存读取，失败时回退到服务端查询。
+优先读本地缓存，失败再回源。
 
 ## 用户管理
 
-### 用户列表
+### 高频查询
 
-```bash
-yapi user-list
-```
-
-列出所有注册用户。
-
-### 搜索用户
-
-```bash
-yapi user-search --q <keyword>
-```
-
-支持按用户名或邮箱搜索。
-
-### 注册用户
+| 场景 | 命令 | 用法 | 说明 |
+| --- | --- | --- | --- |
+| 用户列表 | `user-list` | `yapi user-list` | 列出所有注册用户 |
+| 搜索用户 | `user-search` | `yapi user-search --q <keyword>` | 按用户名或邮箱搜索 |
+| 用户详情 | `user-get` | `yapi user-get --uid <uid>` | 取单个用户详情 |
+| 我的项目 | `user-projects` | `yapi user-projects` | 列出当前用户参与的项目 |
+| 用户头像 | `user-avatar` | `yapi user-avatar --uid <uid>` | 获取头像 URL |
 
-```bash
-yapi user-register --username <name> --password <pass> --email <email> --confirm true
-```
-
-### 删除用户
+### 高频写入
 
-```bash
-yapi user-delete --uid <uid> --confirm true
-```
-
-### 用户头像
-
-```bash
-yapi user-avatar --uid <uid>
-yapi user-upload-avatar --uid <uid> --imagePath <path> --confirm true
-```
+| 场景 | 命令 | 用法 | 说明 |
+| --- | --- | --- | --- |
+| 注册用户 | `user-register` | `yapi user-register --username <name> --password <pass> --email <email> --confirm true` | 管理员写操作 |
+| 更新用户 | `user-update` | `yapi user-update --uid <uid> [--username <name>] [--email <mail>] [--role admin] --confirm true` | 管理员修改用户信息 |
+| 删除用户 | `user-delete` | `yapi user-delete --uid <uid> --confirm true` | 不可恢复 |
+| 上传头像 | `user-upload-avatar` | `yapi user-upload-avatar --uid <uid> --imagePath <path> --confirm true` | 上传用户头像 |
+| 修改自己密码 | `user-change-password` | `yapi user-change-password --oldPassword <old> --newPassword <new> --confirm true` | 当前用户自助改密 |
 
 ## 参数对照
 
@@ -110,4 +95,8 @@ yapi user-upload-avatar --uid <uid> --imagePath <path> --confirm true
 | `authMode` | string | config-init | `native` / `ldap` |
 | `uid` | number | user-delete/avatar | 用户 ID |
 | `username` | string | user-register | 用户名 |
+| `email` | string | user-update | 用户邮箱 |
+| `role` | string | user-update | 用户角色 |
+| `oldPassword` | string | user-change-password | 原密码 |
+| `newPassword` | string | user-change-password | 新密码 |
 | `confirm` | boolean | 写操作 | 确认执行 |

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

@@ -0,0 +1,156 @@
+# Cheatsheet
+
+CLI 注册的全部命令速查。命令按 commandGroup 排序；写命令标注 `✎`，直连（不走 write-guard）标注 `↯`。
+
+## auth（认证 / 配置）
+
+- `config-init` — 初始化本地 YApi 登录配置 ✎
+- `login` — 登录 YApi 并写入认证缓存 ✎
+- `login-by-token` — 使用 token 静默登录 ✎
+- `logout` — 登出 YApi ✎
+- `whoami` — 查看当前账号与认证状态
+
+## group（分组）
+
+- `group-list` — 列出所有分组
+- `group-get` — 查看分组详情
+- `group-mine` — 列出我作为成员加入的分组
+- `group-member-list` — 列出分组成员
+- `group-create` — 创建新分组 ✎
+- `group-update` — 更新分组信息 ✎
+- `group-delete` — 删除分组 ✎
+- `group-member-add` — 添加分组成员 ✎
+- `group-member-role` — 修改分组成员角色 ✎
+- `group-member-remove` — 移除分组成员 ✎
+
+## project（项目）
+
+- `project-list` — 列出项目
+- `project-get` — 查看项目详情
+- `project-search` — 按名称搜索项目
+- `project-token` — 获取项目 Token
+- `project-snapshot` — 项目快照（一次拿到项目基础信息、分类、最近接口和环境）
+- `env` — 列出项目环境
+- `member` — 列出项目成员
+- `follow` — 列出关注的项目
+- `project-check-name` — 检查分组下项目名称是否可用
+- `project-swagger-url` — 获取项目的 Swagger 数据源 URL
+- `project-create` — 创建新项目 ✎
+- `project-update` — 更新项目基础信息 ✎
+- `project-copy` — 复制项目 ✎
+- `project-delete` — 删除项目 ✎
+- `project-token-update` — 重新生成项目 Token ✎
+- `project-env-update` — 更新项目环境配置 ✎
+- `project-tag-update` — 更新项目标签 ✎
+- `project-mock-toggle` — 切换项目全局 Mock 开关 ✎
+- `project-mock-script` — 设置项目级 Mock 脚本 ✎
+- `project-member-add` — 添加项目成员 ✎
+- `project-member-remove` — 从项目中移除成员 ✎
+- `project-member-role` — 修改项目成员角色 ✎
+- `project-member-email-notice` — 修改项目成员的邮件通知开关 ✎
+- `project-follow` — 关注项目 ✎
+- `project-unfollow` — 取消关注项目 ✎
+
+## interface（接口 / 分类）
+
+- `search` — 搜索 YApi 接口
+- `interface-list` — 列出项目中的接口
+- `interface-list-by-menu` — 以菜单模式列出项目中的接口
+- `interface-list-by-cat` — 按分类 ID 列出接口
+- `interface-list-public` — 列出公开项目的接口（无需登录）
+- `interface-get` — 查看接口详情
+- `interface-snapshot` — 接口快照（一次拿到接口详情、请求 / 响应摘要和最近变更）
+- `request` — 发送原始 API 请求到 YApi 服务器 ↯
+- `log` — 查看接口变更日志
+- `interface-download-crx` — 下载浏览器扩展 CRX
+- `schema-to-json` — 将 JSON Schema 转换为 JSON 示例
+- `interface-create` — 创建新接口 ✎
+- `interface-update` — 更新接口（部分更新，未传字段保持原值）✎
+- `interface-save` — 保存接口（存在则更新，不存在则创建）✎
+- `interface-delete` — 删除接口 ✎
+- `interface-upload` — 导入接口（支持 swagger/json 等格式）✎
+- `interface-up-index` — 更新接口排序 ✎
+- `interface-up-cat-index` — 更新分类排序 ✎
+- `interface-mock-toggle` — 切换接口 Mock 开关 ✎
+- `interface-mock-script` — 设置接口自定义 Mock 脚本 ✎
+- `category-list` — 列出项目中的分类（目录）
+- `category-get` — 查看分类详情（含接口列表）
+- `category-create` — 创建接口分类（目录）✎
+- `category-update` — 更新分类信息 ✎
+- `category-delete` — 删除分类 ✎
+
+## util（通用工具 / 用户 / 集合）
+
+- `url-parse` — 解析 YApi 前端页面 URL
+- `workspace-snapshot` — 工作区快照
+- `export` — 导出项目数据（json / swagger / openapi3 / html / markdown）
+- `import` — 导入数据到项目 ✎
+- `self-update` — 检查 CLI 更新 ✎
+- `docs-sync` — 同步 Markdown 文档到 YApi 项目 ✎
+- `install-skill` — 安装 OpenCode skill 文件 ✎
+- `user-list` — 用户管理：列出用户
+- `user-search` — 用户管理：搜索用户
+- `user-get` — 用户管理：获取用户详情
+- `user-avatar` — 用户管理：获取用户头像 URL
+- `user-projects` — 用户管理：列出当前用户参与的项目
+- `user-register` — 用户管理：注册新用户 ✎
+- `user-update` — 用户管理：更新用户信息 ✎
+- `user-delete` — 用户管理：删除用户 ✎
+- `user-change-password` — 用户管理：修改当前用户密码 ✎
+- `user-upload-avatar` — 用户管理：上传用户头像 ✎
+- `col-list` — 测试集合管理：列出集合
+- `col-cases` — 测试集合管理：查看用例
+- `col-create` — 测试集合管理：创建集合 ✎
+- `col-update` — 测试集合：更新集合信息 ✎
+- `col-delete` — 测试集合管理：删除集合 ✎
+- `col-up-index` — 测试集合：调整集合排序 ✎
+- `col-case-up-index` — 测试用例：调整用例排序 ✎
+- `col-case-clone` — 测试集合：从另一个集合克隆用例列表 ✎
+- `col-case-list-by-var-params` — 测试用例：按变量参数过滤列出用例
+- `case-add` — 测试用例管理：添加用例 ✎
+- `case-add-list` — 测试用例：批量添加用例到集合 ✎
+- `case-get` — 测试用例：获取用例详情
+- `case-update` — 测试用例：更新用例信息 ✎
+- `case-delete` — 测试用例管理：删除用例 ✎
+- `case-run` — 测试用例管理：运行集合脚本 ✎
+- `case-env-list` — 测试用例：获取用例环境变量列表
+- `log-list-by-update` — 动态日志：按接口 ID 与更新时间查询
+
+## mock（高级 Mock）
+
+- `mock-expect-list` — 列出接口的 Mock 期望
+- `mock-expect-get` — 获取单个 Mock 期望详情
+- `mock-expect-save` — 保存/更新 Mock 期望 ✎
+- `mock-expect-delete` — 删除 Mock 期望 ✎
+- `mock-expect-toggle` — 启用/禁用 Mock 期望 ✎
+- `mock-script-get` — 获取接口级高级 Mock 脚本
+- `mock-script-save` — 保存/更新接口级高级 Mock 脚本 ✎
+
+## test（开放接口 / 测试桩）
+
+- `test-get` — 测试接口：发送 GET 请求
+- `test-post` — 测试接口：发送 POST 请求
+- `test-put` — 测试接口：发送 PUT 请求
+- `test-delete` — 测试接口：发送 DELETE 请求
+- `test-head` — 测试接口：发送 HEAD 请求
+- `test-options` — 测试接口：发送 OPTIONS 请求
+- `test-patch` — 测试接口：发送 PATCH 请求
+- `test-files-upload` — 测试接口：批量文件上传
+- `test-single-upload` — 测试接口：单文件上传
+- `test-http-code` — 测试接口：检查 HTTP 状态码
+- `test-raw` — 测试接口：发送原始请求体
+- `test-response` — 测试接口：获取响应
+- `open-project-interface-data` — 开放接口：获取项目接口数据
+- `open-run-auto-test` — 开放接口：触发自动化测试
+
+## 内置命令
+
+- `help` — 查看帮助
+- `list` — 列出全部命令
+- `version` / `--version` — 查看版本
+- `install` — 安装 CLI + skill
+- `update` — 更新 CLI + skill
+- `uninstall` / `remove` — 卸载
+- `doctor` — 系统自检
+- `changelog` — 查看版本变更历史
+- `completion` — 生成 shell 补全脚本

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

@@ -2,59 +2,63 @@
 
 ## 入口
 
-- `yapi --help` — 查看帮助
-- `yapi <command> --<key> <value>` — 执行命令
-- `yapi help <command>` — 查看单命令帮助
-- `yapi version` — 查看版本
-- `yapi doctor` — 自检
-- `yapi completion --shell bash` — 生成补全脚本
+- `yapi --help`：总帮助
+- `yapi list`：按分组查看全部命令
+- `yapi help <command>`：查看单命令参数
+- `yapi version`：查看版本
+- `yapi doctor`：做环境自检
+- `yapi completion bash`：生成补全脚本
 
 ## 参数规则
 
-- 参数名使用 kebab-case：`--project-id`、`--group-id`、`--interface-id`
-- 支持 `=` 语法：`--project-id=60`
-- 数组参数可重复：`--tag a --tag b`
-- JSON 对象参数：`--body '{"key":"value"}'`
-- 全局 `--json`：输出 JSON 格式（替代 pretty）
-- 写操作需要 `--confirm true`
+- 参数名以 `yapi help <command>` 输出为准，文档统一按 camelCase 写：`--projectId`、`--groupId`、`--interfaceId`
+- CLI 同时接受 kebab-case：`--project-id`、`--group-id`、`--interface-id`
+- 支持 `=` 语法：`--projectId=60`
+- JSON 参数直接传字符串：`--body '{"key":"value"}'`
+- 写操作默认只 preview，真实执行要加 `--confirm true`
 
-## 81 个命令总览
+## 输出与管道
 
-### 认证 & 配置（5 个）
+- 默认 `--output pretty` 适合人看
+- `--output compact|normal|verbose` 都是合法 JSON，可直接给 `jq`
+- 日志在 stderr，结果在 stdout；不要直接 `2>&1`
+- 常见写法：
 
-`config-init` `login` `login-by-token` `logout` `whoami`
+  ```bash
+  yapi --output compact search --q 关键词 2>/dev/null
+  yapi --output verbose interface-get --interface-id 186512 2>/dev/null | jq '.interface.resBody | fromjson'
+  ```
 
-### 分组（6 个）
+## 两级索引
 
-`group-list` `group-get` `group-add` `group-up` `group-del` `member-list`
+当前文档已覆盖全部 `121` 个业务命令；外层只保留场景索引，详细参数放到二级页。
 
-### 项目（10 个）
+### 一级：先按场景选页
 
-`project-list` `project-get` `project-token` `env` `member` `member-change-role` `follow` `project-mock-toggle` `project-mock-script` `interface-upload`
+| 场景 | 命令量 | 二级页 | 高频命令 |
+| --- | ---: | --- | --- |
+| 安装 / 入口 / 自检 | 10 | `reference/install.md` | `install` `list` `doctor` `remove` |
+| 认证 / 用户 | 14 | `reference/auth.md` | `config-init` `login` `whoami` `user-search` |
+| 分组 | 10 | `reference/group.md` | `group-list` `group-get` `group-create` |
+| 项目 / 环境 / 项目治理 | 25 | `reference/project.md` | `project-list` `project-get` `project-create` `project-update` |
+| 接口 / 分类 / 接口治理 | 26 | `reference/interface.md` | `search` `interface-list` `interface-get` `interface-update` |
+| 高级 Mock（期望 / 脚本） | 7 | `reference/mock.md` | `mock-expect-list` `mock-script-get` `mock-expect-save` |
+| HTTP 测试 / 自动测试 | 14 | `reference/test.md` | `test-get` `test-post` `open-run-auto-test` |
+| 集合 / 用例 / 导入导出 / 快照 | 25 | `reference/tooling.md` | `col-list` `case-run` `docs-sync` `workspace-snapshot` |
 
-### 接口（15 个）
+### 二级：页内再按使用程度读
 
-`search` `interface-list` `interface-get` `interface-create` `interface-update` `interface-delete` `interface-mock-toggle` `interface-mock-script` `category-list` `interface-up-cat-index` `interface-up-index` `request` `log` `export` `interface-download-crx`
+- 每个专题页都按 `高频查询 → 高频写入 → 低频治理 / 维护` 排序
+- 不确定命令时，先看 `reference/commands.md`
+- 需要精确参数时，最终以 `yapi help <command>` 为准
 
-### 用户（6 个）
+## 覆盖说明
 
-`user-list` `user-search` `user-register` `user-delete` `user-avatar` `user-upload-avatar`
-
-### 测试（14 个）
-
-`test-get` `test-post` `test-put` `test-delete` `test-head` `test-options` `test-patch` `test-files-upload` `test-single-upload` `test-http-code` `test-raw` `test-response` `run-auto-test` `project-interface-data`
-
-### 集合（2 个）
-
-`col-list` `col-cases`
-
-### 系统（8 个）
-
-`install` `update` `uninstall` `doctor` `changelog` `completion` `install-skill` `docs-sync`
+- 外层索引不再平铺 `121` 个命令，避免上下文过大
+- 完整覆盖由二级页承接：`reference/install.md`、`reference/auth.md`、`reference/group.md`、`reference/project.md`、`reference/interface.md`、`reference/mock.md`、`reference/test.md`、`reference/tooling.md`
 
 ## 扩展
 
-- 新命令在 `src/tools/yapi/register-*.ts` 中用 `registry.tool(name, schema, handler, desc, metadata)` 注册
-- 参数类型用 Zod schema：`z.string()` / `z.coerce.number()` / `z.boolean()` / `z.enum([...])`
-- Handler 返回 `jsonResult({...})`，自动按 format 输出
-- 元数据：`costHint`（low/medium/high）+ `nextBestTools`（相关命令推荐）
+- 新命令注册入口：`src/tools/yapi/register-*.ts`
+- manifest 来源：`src/core/manifest.ts`
+- 命令覆盖校验：`tests/manifest-and-skills.test.ts`

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

@@ -2,119 +2,38 @@
 
 ## 使用规则
 
-- 先按用户场景选命令，再用 `yapi help <command>` 校对参数。
-- 参数名以 `yapi help <command>` 输出为准；不要猜 `id`、`projectId`、`interfaceId` 这类相似参数。
-- 读命令不需要 `confirm=true`；写操作（create/update/delete/upload/toggle/script）必须显式传 `--confirm true`。
-- 如果命令返回 `未知参数`，立即运行 `yapi help <command>` 修正命令。
-- 本机没有 `yapi` 时，用 `npx -y @cloudglab/yapi-cli@latest <command> ...`。
-
-## 认证 & 配置
-
-| 场景 | 命令 | 用法 | 说明 |
-| --- | --- | --- | --- |
-| 初始化配置 | `config-init` | `yapi config-init [--url <url>] [--username <u>] [--password <p>] [--auth-mode native]` | 首次使用必做；缺参时可交互填写 |
-| Token 登录 | `login` | `yapi login --token <t>` | 用 token 认证 |
-| 密码登录 | `login` | `yapi login [--username <u>] [--email <e>] [--password <p>] [--ldap true]` | 不带参数时使用配置文件 |
-| Token 快捷登录 | `login-by-token` | `yapi login-by-token --token <t>` | 纯 token 登录 |
-| 登出 | `logout` | `yapi logout` | 清除本地认证缓存 + 服务端登出 |
-| 查看当前用户 | `whoami` | `yapi whoami` | 返回当前用户信息 |
-
-## 分组
-
-| 场景 | 命令 | 用法 | 说明 |
-| --- | --- | --- | --- |
-| 分组列表 | `group-list` | `yapi group-list` | 列出可见分组 |
-| 分组详情 | `group-get` | `yapi group-get --groupId <id>` | 查分组详细信息 |
-| 创建分组 | `group-add` | `yapi group-add --groupName <name> [--groupDesc <d>] --confirm true` | 写操作 |
-| 更新分组 | `group-up` | `yapi group-up --groupId <id> [--groupName <n>] [--groupDesc <d>] --confirm true` | 写操作 |
-| 删除分组 | `group-del` | `yapi group-del --groupId <id> --confirm true` | 写操作 |
-| 分组成员 | `member-list` | `yapi member-list --groupId <id>` | 列出分组下的成员 |
-
-## 项目
-
-| 场景 | 命令 | 用法 | 说明 |
-| --- | --- | --- | --- |
-| 项目列表 | `project-list` | `yapi project-list [--groupId <id>] [--page <n>] [--limit <n>]` | 可按分组过滤 |
-| 项目详情 | `project-get` | `yapi project-get --projectId <id>` | 查项目信息 |
-| 项目 Token | `project-token` | `yapi project-token --projectId <id>` | 获取项目 token |
-| 环境配置 | `env` | `yapi env --projectId <id>` | 项目环境变量 |
-| 项目成员 | `member` | `yapi member --projectId <id>` | 项目成员列表 |
-| 改成员角色 | `member-change-role` | `yapi member-change-role --projectId <id> --memberUid <uid> --role <role> --confirm true` | 写操作 |
-| 关注项目 | `follow` | `yapi follow` | 我关注的项目列表 |
-| 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 <s>] --confirm true` | 设置项目 Mock 脚本 |
-| 导入接口 | `interface-upload` | `yapi interface-upload --projectId <id> --content <json> [--type swagger] --confirm true` | 批量导入 |
-
-## 接口
-
-| 场景 | 命令 | 用法 | 说明 |
-| --- | --- | --- | --- |
-| 搜索接口 | `search` | `yapi search --q <keyword> [--projectId <id>] [--page <n>] [--limit <n>]` | 关键词搜索 |
-| 接口列表 | `interface-list` | `yapi interface-list --projectId <id> [--status <s>] [--method <m>] [--page <n>] [--limit <n>]` | 按项目查接口 |
-| 接口详情 | `interface-get` | `yapi interface-get --interfaceId <id>` | 查看接口定义 |
-| 创建接口 | `interface-create` | `yapi interface-create --projectId <n> --catId <n> --title <s> --path <s> [--method GET] [--desc <s>] --confirm true` | 写操作 |
-| 更新接口 | `interface-update` | `yapi interface-update --interfaceId <id> [--title <s>] [--path <s>] [--method <m>] --confirm true` | 写操作 |
-| 删除接口 | `interface-delete` | `yapi interface-delete --interfaceId <id> --confirm true` | 写操作 |
-| Mock 开关 | `interface-mock-toggle` | `yapi interface-mock-toggle --interfaceId <id> [--open true] --confirm true` | 开关接口级 Mock |
-| Mock 脚本 | `interface-mock-script` | `yapi interface-mock-script --interfaceId <id> [--script <s>] --confirm true` | 设置接口 Mock 脚本 |
-| 分类列表 | `category-list` | `yapi category-list --projectId <id>` | 项目的接口分类 |
-| 分类排序 | `interface-up-cat-index` | `yapi interface-up-cat-index --catid <id> --index <n> --confirm true` | 调整分类排序 |
-| 接口排序 | `interface-up-index` | `yapi interface-up-index --interfaceId <id> --index <n> --confirm true` | 调整接口排序 |
-| 原始请求 | `request` | `yapi request --path <s> [--method GET] [--body <json>]` | 发送任意请求 |
-| 日志 | `log` | `yapi log --interfaceId <id> [--projectId <id>]` | 查看接口更新日志 |
-| 导出 | `export` | `yapi export --projectId <id> [--type json]` | 导出接口定义 |
-| 下载 CRX | `interface-download-crx` | `yapi interface-download-crx` | 下载 YApi 跨域插件 |
-
-## 用户管理
-
-| 场景 | 命令 | 用法 | 说明 |
-| --- | --- | --- | --- |
-| 用户列表 | `user-list` | `yapi user-list` | 列出所有用户 |
-| 搜索用户 | `user-search` | `yapi user-search --q <keyword>` | 按关键词搜索用户 |
-| 注册用户 | `user-register` | `yapi user-register --username <u> --password <p> --email <e> [--role <r>] --confirm true` | 写操作 |
-| 删除用户 | `user-delete` | `yapi user-delete --uid <uid> --confirm true` | 写操作 |
-| 用户头像 | `user-avatar` | `yapi user-avatar --uid <uid>` | 查看用户头像 |
-| 上传头像 | `user-upload-avatar` | `yapi user-upload-avatar --uid <uid> --imagePath <path> --confirm true` | 写操作 |
-
-## 测试
-
-| 场景 | 命令 | 用法 | 说明 |
-| --- | --- | --- | --- |
-| GET 测试 | `test-get` | `yapi test-get --url <url> [--params <json>]` | HTTP GET 请求测试 |
-| POST 测试 | `test-post` | `yapi test-post --url <url> [--body <json>]` | HTTP POST 请求测试 |
-| PUT 测试 | `test-put` | `yapi test-put --url <url> [--body <json>]` | HTTP PUT 请求测试 |
-| DELETE 测试 | `test-delete` | `yapi test-delete --url <url>` | HTTP DELETE 请求测试 |
-| HEAD 测试 | `test-head` | `yapi test-head --url <url>` | HTTP HEAD 请求测试 |
-| OPTIONS 测试 | `test-options` | `yapi test-options --url <url>` | HTTP OPTIONS 请求测试 |
-| PATCH 测试 | `test-patch` | `yapi test-patch --url <url> [--body <json>]` | HTTP PATCH 请求测试 |
-| 文件上传 | `test-files-upload` | `yapi test-files-upload --url <url> --filePaths <p1> [--params <json>]` | 多文件上传测试 |
-| 单文件上传 | `test-single-upload` | `yapi test-single-upload --url <url> --filePath <p>` | 单文件上传测试 |
-| HTTP 状态码 | `test-http-code` | `yapi test-http-code --url <url>` | 检查响应状态码 |
-| 原始响应 | `test-raw` | `yapi test-raw --url <url>` | 查看原始响应 |
-| 响应结构 | `test-response` | `yapi test-response --url <url>` | 查看完整响应结构 |
-| 自动测试 | `run-auto-test` | `yapi run-auto-test --projectId <id> [--format json]` | 运行项目自动测试 |
-| 项目接口数据 | `project-interface-data` | `yapi project-interface-data --projectId <id>` | 查询项目接口测试数据 |
-
-## 集合
-
-| 场景 | 命令 | 用法 | 说明 |
-| --- | --- | --- | --- |
-| 集合列表 | `col-list` | `yapi col-list --projectId <id>` | 项目下的测试集合列表 |
-| 集合用例 | `col-cases` | `yapi col-cases --projectId <id> --colId <id>` | 集合下的测试用例 |
-
-## 系统
-
-| 场景 | 命令 | 用法 | 说明 |
-| --- | --- | --- | --- |
-| 自检 | `doctor` | `yapi doctor` | 检查 Node/配置/网络连通性 |
-| 版本 | `version` | `yapi version [--json] [--verbose]` | 查看版本详情 |
-| 变更日志 | `changelog` | `yapi changelog [--limit <n>] [--version <v>]` | 查看版本变更历史 |
-| 更新 | `update` | `yapi update [--cli-only] [--skill-only]` | 更新 CLI + skill |
-| 安装 skill | `install-skill` | `yapi install-skill` | 安装 skill 到本地 |
-| 文档同步 | `docs-sync` | `yapi docs-sync [--path <p>] [--validate]` | 从 markdown 同步文档 |
-| Shell 补全 | `completion` | `yapi completion [--shell bash]` | 生成 shell 补全脚本 |
-
-## 常用组合
+- 先按场景挑页，再看页内高频 / 低频分组
+- 精确参数最终以 `yapi help <command>` 为准
+- 读命令不用 `--confirm true`；写命令必须显式确认
+- 如果目标是“找得到命令”，优先看本页；如果目标是“抄正确参数”，进二级专题页
+
+## 两级入口
+
+| 用户场景 | 一级入口 | 二级页 | 推荐起手命令 |
+| --- | --- | --- | --- |
+| 第一次安装 / 排查环境 | 系统入口 | `reference/install.md` | `yapi install` `yapi list` `yapi doctor` |
+| 登录 / 看当前账号 / 用户管理 | 账号入口 | `reference/auth.md` | `yapi config-init` `yapi login` `yapi whoami` |
+| 查分组 / 管分组成员 | 分组入口 | `reference/group.md` | `yapi group-list` `yapi group-get` |
+| 查项目 / 建项目 / 改项目配置 | 项目入口 | `reference/project.md` | `yapi project-list` `yapi project-get` `yapi project-create` |
+| 查接口 / 建接口 / 改 Mock / 改分类 | 接口入口 | `reference/interface.md` | `yapi search` `yapi interface-list` `yapi interface-update` |
+| 高级 Mock（期望 / 脚本） | Mock 入口 | `reference/mock.md` | `yapi mock-expect-list` `yapi mock-script-get` |
+| 联调接口 / 跑自动测试 | 测试入口 | `reference/test.md` | `yapi test-get` `yapi test-post` `yapi open-run-auto-test` |
+| 管集合 / 管用例 / 导入导出 / 快照 | 工具入口 | `reference/tooling.md` | `yapi col-list` `yapi case-run` `yapi docs-sync` |
+
+## 高频起手命令
+
+| 需求 | 命令 |
+| --- | --- |
+| 看全部命令 | `yapi list` |
+| 看命令参数 | `yapi help <command>` |
+| 校验账号 | `yapi whoami` |
+| 查项目 | `yapi project-list` |
+| 查接口 | `yapi search --q <keyword>` |
+| 看接口详情 | `yapi interface-get --interfaceId <id>` |
+| 跑一次 GET 测试 | `yapi test-get --url <url>` |
+| 做工作区快照 | `yapi workspace-snapshot` |
+
+## 常见链路
 
 ### 查一个项目的完整上下文
 
@@ -129,24 +48,16 @@ yapi member --projectId <id>
 ### 创建并配置新接口
 
 ```bash
-yapi category-list --projectId <id>          # 确认分类 ID
+yapi category-list --projectId <id>
 yapi interface-create --projectId <id> --catId <cid> --title <t> --path <p> --confirm true
-yapi interface-list --projectId <id>          # 验证已创建
+yapi interface-list --projectId <id>
 yapi interface-mock-script --interfaceId <iid> --script <s> --confirm true
 ```
 
-### 查接口详情 + 日志 + Mock 状态
+### 查接口详情再联调
 
 ```bash
 yapi interface-get --interfaceId <id>
 yapi log --interfaceId <id>
-yapi interface-mock-toggle --interfaceId <id>
-```
-
-### 搜索 + 测试
-
-```bash
-yapi search --q <keyword> --limit 20
-yapi interface-get --interfaceId <id>
 yapi test-get --url <url>
 ```