@sokeai/cli 1.0.73 → 1.0.75

package/skills/ai-coach-director/references/env-check.md

@@ -4,13 +4,17 @@
 
 ---
 
-> ⚠️ **沙箱绕过（全局规则）**：soke-cli 是 Go 编译的二进制文件，在 WorkBuddy Bash 工具沙箱中执行会受限（表现为 `permission denied`、`operation not permitted`、静默无输出）。**以下所有命令在调用 Bash 工具时必须设置 `dangerouslyDisableSandbox: true`**，包括 `which soke-cli`、`soke-cli --version`、`soke-cli config show`、`soke-cli auth login` 及后续全部 `soke-cli ai-training +...` 命令。若 soke-cli 命令在沙箱中执行失败并返回权限错误，这是预期行为——切换为 `dangerouslyDisableSandbox: true` 重试即可。
+> ⚠️ **沙箱绕过（全局规则）**：soke-cli 是 Go 编译的二进制文件，在 WorkBuddy Bash 工具沙箱中执行会受限（表现为 `permission denied`、`operation not permitted`、静默无输出）。**以下所有命令在 WorkBuddy 平台调用 Bash 工具时必须设置 `dangerouslyDisableSandbox: true`**。悟空/QClaw/Zework 等平台的沙箱机制不同，按各平台适配器（`platform/adapters/`）的规则执行，一般无需此参数。
+
+> 📱 **跨平台检测策略（v2.4）**：Step 0 检测按当前运行平台自动选择策略——WorkBuddy 用 `dangerouslyDisableSandbox: true` + soke-cli CLI 命令；悟空/QClaw/Zework 直接执行 CLI（无 WorkBuddy 沙箱限制）；纯聊天平台可跳过 Node.js/soke-cli 安装检测，直接引导用户获取 Token 并通过 REST API（`platform/api-fallback.md`）验证连通性。
 
 ---
 
 ## 检测流程
 
-按顺序执行，任一步不通过则停止并引导修复。
+按顺序执行，任一步不通过则先按本文件修复流程处理；只有确认 CLI 与登录态可用后才继续平台同步。
+
+> ⚠️ **soke-cli 多版本与配置修复优先级**：如果默认 `soke-cli` 路径异常，不要反复重试同一个命令。按本文件「多版本故障降级」寻找可用二进制。
 
 ### 1. Node.js 版本
 
@@ -30,7 +34,8 @@ node --version
 which soke-cli && soke-cli --version
 ```
 
-- ✅ 输出版本号 → 通过
+- ✅ 输出版本号 → 继续执行 `soke-cli config show` 验证该路径是否真的可用
+- ⚠️ 输出版本号但后续命令报 `spawn Unknown system error -88` / Exit 137 / panic → 不视为通过，立即进入「多版本故障降级」
 - ❌ `command not found` → 执行安装：
 
 ```bash
@@ -45,6 +50,28 @@ npm install -g @sokeai/cli@latest
 
 > Windows：将 `~/.zshrc` 替换为 PowerShell profile 路径，PATH 追加方式不同（见安装指南 Q2）。
 
+#### 2.1 多版本故障降级
+
+当默认 `soke-cli` 出现以下任一现象时，必须切换可用路径，而不是继续重试：
+
+- Node wrapper 报 `spawn Unknown system error -88`
+- 直接执行 Go 二进制无输出并 Exit 137
+- `config show` panic：`slice bounds out of range [-4:]`
+- `config show` 因短 token、空 token、`test_token_12345` 等占位值触发崩溃
+
+按以下顺序探测候选路径，选择第一个同时满足 `--version`、`config show`、`auth login` 可执行的路径：
+
+```bash
+which -a soke-cli
+/Users/edy/soke-cli/soke-cli/soke-cli --version
+/Users/edy/Library/Application\ Support/QClaw/npm-global/bin/soke-cli --version
+/Users/edy/.nvm/versions/node/v22.22.1/bin/soke-cli --version
+```
+
+已知可用经验：在 edy 的 macOS 环境中，`/Users/edy/soke-cli/soke-cli/soke-cli`（v1.0.30）可正常执行 `config show` 和 `auth login`，可作为新版 v1.0.66 panic 时的优先 fallback。
+
+若 fallback 路径可用，后续本轮所有 `soke-cli` 命令都必须使用该绝对路径，不再调用默认 PATH 中的 `soke-cli`。
+
 ---
 
 ### 3. 登录状态
@@ -53,8 +80,9 @@ npm install -g @sokeai/cli@latest
 soke-cli config show
 ```
 
-- ✅ 输出含 `user_token` → 通过，进入下一步企业绑定检查
-- ❌ 无 `user_token` → 执行登录：
+- ✅ 输出含 `user_token` / `UserToken` 且长度充足、非占位值 → 通过，进入下一步企业绑定检查
+- ❌ 无 `user_token` / `UserToken`、值为空、值为 `test_token_12345`、或长度不足 4 → 执行登录：
+- ⚠️ `config show` panic 但存在 `~/.soke-cli/config.json` → 可用 Read 工具读取配置文件判断字段是否存在，但**不得在对话中展示 Token 原文**；若 token 为空/占位/长度不足，按未登录处理
 
 ```bash
 soke-cli auth login
@@ -84,11 +112,12 @@ soke-cli config show
 依次检查以下字段是否存在且非空：
 - `implementation_corp_id`
 - `corpid`
+- `CorpID`（旧版配置文件字段）
 
 判定规则：
 - ✅ `implementation_corp_id` 非空 → 通过，后续优先使用该字段
-- ✅ `implementation_corp_id` 为空，但 `corpid` 非空 → 通过，后续可使用 `corpid`
-- ❌ 两者都为空 → 提示用户：
+- ✅ `implementation_corp_id` 为空，但 `corpid` / `CorpID` 非空 → 通过，后续可使用该字段
+- ❌ 全部为空 → 提示用户：
   > 已登录，但当前账号未绑定企业。请先在授客AI平台完成企业绑定，再重新执行 `soke-cli auth login --force`
 
 如需强制刷新企业绑定信息，执行：
@@ -108,12 +137,17 @@ soke-cli auth login --force
 | 现象 | 原因 | 修复 |
 |------|------|------|
 | `which soke-cli` 无输出但已安装 | PATH 未生效 | `source ~/.zshrc` 或新开终端 |
+| `config show` panic: `slice bounds out of range [-4:]` | 新版 CLI 对短 token / 空 token 脱敏时切片越界 | 进入 2.1 多版本故障降级；优先用 `/Users/edy/soke-cli/soke-cli/soke-cli config show`；必要时读取 `~/.soke-cli/config.json` 判断登录态 |
+| Node wrapper `spawn Unknown system error -88` | npm wrapper 无法 spawn Go 二进制 | 避免默认 wrapper，改用可运行的本地二进制绝对路径 |
+| Go 二进制无输出 Exit 137 | 当前二进制在环境中被系统杀死或不兼容 | 切换多版本候选路径；不要重复调用同一路径 |
+| 配置中 `UserToken` 为 `test_token_12345` | 测试占位 token，非有效登录 | 按未登录处理，执行 `auth login` |
 | `401 Unauthorized` | Token 过期 | `soke-cli auth logout && soke-cli auth login` |
 | 登录时浏览器未打开 | 系统无默认浏览器 | 手动复制终端链接到浏览器 |
 | `npm: command not found` | Node.js 未安装 | 安装 Node.js >= 14 |
 | `EACCES` 权限错误 | npm 全局安装需要 sudo | 使用 `~/.npm-global` 方案（见步骤2） |
 | `implementation_corp_id` / `corpid` 为空 | 未绑定企业 | `soke-cli auth login --force` 重新授权，或联系管理员 |
-| `permission denied` / 静默无输出 | soke-cli 在沙箱中受限（Go 二进制） | Bash 工具设置 `dangerouslyDisableSandbox: true` 重试 |
+| `permission denied` / 静默无输出 | soke-cli 在 WorkBuddy 沙箱中受限（Go 二进制） | Bash 工具设置 `dangerouslyDisableSandbox: true` 重试 |
+| 悟空/QClaw 中 soke-cli 不可用 | 平台安全策略或未安装 | 跳过 CLI 检测，按 `platform/api-fallback.md` 用 Token 验证 API 连通性 |
 
 ---
 
@@ -124,9 +158,10 @@ soke-cli auth login --force
 read references/env-check.md
 按顺序执行 4 步检测：
   1. node --version
-  2. which soke-cli && soke-cli --version
-  3. soke-cli config show → 确认 user_token
-  4. soke-cli config show → 确认 implementation_corp_id / corpid 至少一个非空
+  2. which soke-cli && soke-cli --version；若默认路径异常，按 2.1 多版本故障降级选择可用绝对路径
+  3. <可用soke-cli路径> config show → 确认 user_token/UserToken 非空、非 test_token_12345、长度充足
+  4. <可用soke-cli路径> config show 或 ~/.soke-cli/config.json → 确认 implementation_corp_id / corpid / CorpID 至少一个非空
 全部通过 → 记录企业 ID，继续调度
+补充约定：后续场景更新命令默认优先使用 `--request-file <partX-update.json>`；仅在排障时才改用 `--operations-file`。
 任一步失败 → 按修复流程引导用户，不进入内容生成/同步
 ```

package/skills/ai-coach-director/references/platform-api-pitfalls.md

@@ -4,6 +4,8 @@
 
 > 需要复制标准命令时，统一参考 `verified-cli-cheatsheet.md`，避免误写成顶层 `soke-cli +...`。
 
+> 同步请求结构额外对齐附件《比得_AI陪练CLI创建与更新场景使用指南 2.0》：默认优先 `--request-file <partX-update.json>` 传完整更新请求；仅在排障或拆解问题时退回 `--operations-file` + `--base-updated-at` 模式。
+
 ## 1. Step2 / Part3 对话流程不能整包替换
 
 - 历史误区：使用 `replace_conversation_steps`
@@ -74,6 +76,7 @@
 - 已验证做法：
   - `preview`：不传 `--idempotency-key`
   - `apply`：传 `--idempotency-key "nature-part2-apply-1752395205"`（建议格式 `{场景短码}-{part}-apply-{timestamp}`）
+  - 若使用 `--request-file <partX-update.json>`，则 `idempotency_key` 写在 JSON 请求体中，而不是命令行参数
 
 ## 3.8 reason 是 preview 和 apply 的必填参数
 
@@ -172,6 +175,17 @@
 - 只生成业务按需画像，不补平台外壳字段
 - `taboos_objections` 写成长段散文，无法稳定映射为列表
 
+## 4.2 Part2 首次写入默认不要整包 replace
+
+- 历史误区：为了省步骤，直接一次 `replace_ai_roles` 写入多个角色，再同时写 OS
+- 真实结果：preview/apply 可能成功，但回读时某一个角色被平台打成“角色数据异常”
+- 已验证做法：新场景首写 Part2 时，默认改为逐个保守写入：
+  1. 先 `add_ai_role` 写入第1个角色
+  2. 立刻 `+get-scenario` 验收
+  3. 验收通过后再逐个追加剩余角色
+  4. 最后单独 `update_basic` 写 `ai_roles_overall_description`
+- 备注：只有目标平台已被实证验证整包稳定时，才允许回退为 `replace_ai_roles`
+
 ## 5. preview / apply 成功，不等于平台最终可正常解析
 
 - 历史误区：只要 preview 通过、apply 成功，就等于配置闭环完成
@@ -206,7 +220,7 @@
 - 历史误区：以为 `add_conversation_step` apply 返回 snapshot_id 就代表保存成功
 - 真实结果：`+get-scenario` 永远返回 `conversation_steps: []`——数据完全不保存（CLI v1.0.65/1.0.66 均存在此 bug）
 - 影响范围：`add_conversation_step`（平铺 data + data.step 格式均无效）、`replace_conversation_steps`（422 校验拒绝不支持此 operation type）
-- 已验证做法：创建型流程的对话步骤目前只能通过 MentorAI Web 管理后台手动添加，CLI 无法写入对话流程
+- 已验证做法：最新官方语义仍要求用 `add_conversation_step` / `patch_conversation_step` 等操作先尝试 CLI 更新；若 apply 后 `get-scenario` 回读仍为空，再判定当前版本存在持久化缺陷，并改走 MentorAI Web 管理后台手动添加
 - 备注：全量创建 `+create-scenario --request-file` 中 `conversation_steps` 理论上可写入，但实测时 `ai_roles` 和 `scoring_criteria_config` 等其他复杂字段被同时忽略（见 §9）
 
 ## 9. 全量创建 `--request-file` 只保存基础字段

package/skills/ai-coach-director/references/role-resource-matching.md

@@ -1,12 +1,12 @@
 # Part2 平台资源自动匹配规则
 
-> 本节是 Part2 角色创建后自动执行的资源匹配流程。头像和语音不在 Part2 内容生成阶段预设，而是在角色落地后查询系统资源库自动匹配。
+> 本节是 Part2 用户确认后、角色 JSON 生成前自动执行的资源匹配流程。头像和语音不在 Part2 内容展示阶段预设或展示，而是在后台查询系统资源库自动匹配，并随角色主体一次写入。
 >
 > **v2.0 升级**：匹配模式从"拉全量→文本匹配"升级为"提取角色性别/年龄特征→CLI 参数精准过滤→取结果"，利用 CLI 原生的 `--gender` / `--age-group` 服务端过滤能力，提升匹配精度和效率。
 
 ## 资源匹配时机
 
-Part2 `replace_ai_roles` / `add_ai_role` apply 成功 → 立即执行资源匹配流程，不等待用户触发。
+Part2 完整内容已展示（先 OS，再逐个角色）并由用户确认 → 后台立即执行资源匹配流程 → 将 avatar URL 与 voice_id 写入角色级 JSON → 逐个角色 apply + 回读验证。资源匹配、写入、回读校验不等待用户触发，也不向用户二次确认。
 
 ---
 
@@ -79,11 +79,11 @@ CLI 返回的头像列表已经是服务端按 `sort` 排序的过滤结果。
 
 > **降级链路**：一阶查询返回空 → 去掉 `--age-group`（仅性别）→ 仍空则去掉 `--gender`（仅年龄）→ 仍空则全量无过滤。每次降级记录一次。
 
-### Step 3：写入角色
+### Step 3：写入角色级 JSON
 
-> ⚠️ **必须与语音资源合并写入**：头像和语音写入**同一个** `patch_ai_role` 操作，不可分两次。合并写入示例见文件末尾「合并写入模板」。
+> ⚠️ **必须与语音资源合并写入角色级同步单元**：头像和语音写入同一个角色级操作，不可分两次。
 
-使用 `patch_ai_role` 将匹配到的头像资源 URL 写入（与 voice_id 合并为单次操作）：
+将匹配到的头像资源 URL 写入该角色的 `role_data.avatar`（与 voice_id 一起进入 `part2-role-XX.json`）：
 
 ```json
 [
@@ -105,7 +105,7 @@ CLI 返回的头像列表已经是服务端按 `sort` 排序的过滤结果。
 > ⚠️ `avatar` 字段传入头像资源 **URL**（如 `https://newsokeeditorcdn.soke.cn/public/ai/avatars/business_owner_female.png`），来自 `+list-role-avatars` 返回的 `url` 字段，**不能**传资源 `id`。
 > ⚠️ `patch` 中必须包含 `customized_fields`，指明被修改的字段，否则平台可能不识别该更新。
 
-匹配结果在聊天中只显示一行摘要（如「张总 → 威严中年男性头像」），不展示原始 JSON。
+匹配过程默认不在聊天中展示；只有失败且影响后续发布时，才输出最小必要异常。
 
 ---
 
@@ -135,11 +135,11 @@ soke-cli ai-training +list-role-voices \
 
 > **降级链路**：同头像匹配——一阶→去年龄→去性别→全量。每次降级记录一次。
 
-### Step 3：写入角色
+### Step 3：写入角色级 JSON
 
-> ⚠️ **必须与头像资源合并写入**：语音和头像写入**同一个** `patch_ai_role` 操作，不可分两次。合并写入示例见文件末尾「合并写入模板」。
+> ⚠️ **必须与头像资源合并写入角色级同步单元**：语音和头像写入同一个角色级操作，不可分两次。
 
-使用 `patch_ai_role` 将匹配到的语音资源 ID 写入（与 avatar 合并为单次操作）：
+将匹配到的语音资源 ID 写入该角色的 `role_data.voice_id`（与 avatar 一起进入 `part2-role-XX.json`）：
 
 ```json
 [
@@ -161,27 +161,30 @@ soke-cli ai-training +list-role-voices \
 > ⚠️ `voice_id` 传入声音资源 **ID**（如 `zh_female_warm_01`），来自 `+list-role-voices` 返回的 `id` 字段，**不能**传 `sample_url` 或名称字符串。
 > ⚠️ `patch` 中必须包含 `customized_fields`，指明被修改的字段。
 
-匹配结果在聊天中只显示一行摘要（如「张总 → 沉稳中年男声」）。
+匹配过程默认不在聊天中展示；只有失败且影响后续发布时，才输出最小必要异常。
 
 ---
 
 ## 完整流程时序
 
 ```
-Part2 角色 apply 成功
-  → 提取角色性别(gender) + 年龄(age_group)
+Part2 完整展示并由用户确认
+  → 提取每个角色的性别(gender) + 年龄(age_group)
   → CLI 并行精准过滤查询:
       +list-role-avatars --gender <g> --age-group <a> --lang zh --show-detail --pretty
       +list-role-voices --gender <g> --age-group <a> --lang zh --pretty
     → 任一返回空则降级（去年龄→去性别→全量）
-  → ⚠️ 单次 patch_ai_role 合并写入 avatar + voice_id（customized_fields: ["avatar", "voice_id"]）
-  → ⚠️ get-scenario 强制验证 avatar 非空 URL + voice_id 非空 ID
+  → ⚠️ 将 avatar + voice_id 写入对应角色级 JSON
+  → 角色1 preview + apply → get-scenario 强制验证该角色 avatar 非空 URL + voice_id 非空 ID
+  → 角色2 preview + apply → get-scenario 强制验证
+  → 角色3 preview + apply → get-scenario 强制验证
+  → OS preview + apply → get-scenario 强制验证 OS 完整写入
   → 验证失败 → 重新读取 updated_at → 重试 1 次
   → 仍失败 → 标注「资源匹配未完成」，不阻断后续 Part
-  → 资源匹配完成后，再进入 Part3
+  → 全部同步完成后，再输出 Part3
 ```
 
-> **头像/语音的 patch 操作用同一个 idempotency_key**（如 `cli-<scenario_short>-part2-resources`），avatar 和 voice_id 放在同一个 `patch_ai_role` 的 `patch.role_data` 中，`customized_fields` 写 `["avatar", "voice_id"]`。**禁止分两次 patch**——分开调用会导致 updated_at 竞态。
+> **头像/语音必须在同一角色同步单元内写入**，avatar 和 voice_id 放在同一个角色的 `role_data` 中，`customized_fields` 同时包含 `avatar` 和 `voice_id`。**禁止分两次 patch**——分开调用会导致 updated_at 竞态。
 
 ---
 
@@ -310,3 +313,37 @@ soke-cli ai-training +get-scenario --scenario-id <scenario_id> --pretty
 # 重新生成 patch → 重新 preview + apply（新 idempotency_key）
 # 仍失败 → 标注并继续 Part3
 ```
+
+---
+
+## REST API 回填路径（soke-cli 不可用时）
+
+> 当 soke-cli 不可用（如悟空/QClaw/Zework 等非 WorkBuddy 平台，或企业安全策略禁止 CLI 执行），头像和语音资源回填**不得跳过**，必须降级为 REST API 路径。
+
+完整流程详见 `platform/api-fallback.md`「资源回填完整流程」，本节仅说明与 CLI 路径的差异点。
+
+### 执行条件
+
+- soke-cli 未安装、执行持续失败、或 `which soke-cli` 返回空
+- 所在平台支持 HTTP 请求（curl / Python requests）
+
+### 差异点
+
+| 步骤 | CLI 路径 | REST API 路径 |
+|------|---------|---------------|
+| 头像查询 | `soke-cli ai-training +list-role-avatars --gender <g> --age-group <a>` | `GET /api/v1/ai-training/role-avatars?gender=<g>&age_group=<a>` |
+| 语音查询 | `soke-cli ai-training +list-role-voices --gender <g> --age-group <a>` | `GET /api/v1/ai-training/role-voices?gender=<g>&age_group=<a>` |
+| 回填 | `+preview-scenario-update` → `+apply-scenario-update` | 单次 `PATCH /api/v1/ai-training/scenarios/<id>`（无 preview 步骤，PATCH 前先 GET 对比） |
+| 验证 | `soke-cli ai-training +get-scenario` | `GET /api/v1/ai-training/scenarios/<id>` |
+| 沙箱 | `dangerouslyDisableSandbox: true` | 不适用（HTTP 请求） |
+
+### 相同点（保证回填质量一致）
+
+- 性别/年龄段特征提取与映射表**完全相同**（本文件「性别映射表」「年龄段映射表」）
+- P0-P3 降级链路**完全相同**
+- 合并写入（单次 patch avatar+voice_id）规则**完全相同**
+- 写入值规范：`avatar` = URL，`voice_id` = ID，**完全相同**
+- 强制验证 + 重试 1 次 + 失败标注不阻断 Part3，**完全相同**
+- 匹配摘要一行输出（「张总 → 威严中年男性头像 + 沉稳男中音」），**完全相同**
+
+> ⚠️ **关键原则**：REST API 路径**不是简化版**——它和 CLI 路径共享完全相同的匹配规则和验证标准。唯一的区别是数据传输方式（CLI 命令 vs HTTP 请求）。头像和语音的匹配质量和写入结果必须等价。

package/skills/ai-coach-director/references/verified-cli-cheatsheet.md

@@ -8,6 +8,7 @@
 - 正确写法：`soke-cli ai-training +create-scenario`
 - 同理，`+get-scenario`、`+preview-scenario-update`、`+apply-scenario-update`、`+upload-scenario-cover`、`+sync`、`+bind-scenario` 都必须挂在 `ai-training` 子命令下
 - 每次 `preview` / `apply` 前，先重新执行一次 `soke-cli ai-training +get-scenario`
+- 默认优先使用 `--request-file <partX-update.json>` 传完整更新请求；排障时再改用 `--operations-file <partX-operations.json>`
 - 每次 `apply` 后，立刻执行一次 `soke-cli ai-training +get-scenario --raw` 做验收
 - ⚠️ **所有 soke-cli 命令通过 Bash 工具执行时，必须设置 `dangerouslyDisableSandbox: true`**。soke-cli 是 Go 编译二进制，在沙箱中会被限制执行（`permission denied` 或静默无输出）。此规则适用于本文件中全部命令，不限于创建型流程
 
@@ -48,25 +49,38 @@ soke-cli ai-training +get-scenario \
   --pretty
 ```
 
-### 2.2 预览更新
+### 2.2 预览更新（默认 request-file 模式）
 
 ```bash
 soke-cli ai-training +preview-scenario-update \
   --scenario-id <scenario_id> \
-  --base-updated-at <updated_at> \
-  --operations-file ./partX-operations.json \
-  --idempotency-key "cli-<scenario_short>-partX-preview" \
-  --reason "PartX: 更新说明" \
+  --request-file ./partX-update.json \
   --pretty
 ```
 
-### 2.3 应用更新
+### 2.3 应用更新（默认 request-file 模式）
 
 ```bash
 soke-cli ai-training +apply-scenario-update \
   --scenario-id <scenario_id> \
+  --request-file ./partX-update.json \
+  --pretty
+```
+
+### 2.3A 排障时退回 operations 模式
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --operations-file ./partX-operations.json \
   --base-updated-at <updated_at> \
+  --reason "PartX: 更新说明" \
+  --pretty
+
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
   --operations-file ./partX-operations.json \
+  --base-updated-at <updated_at> \
   --idempotency-key "cli-<scenario_short>-partX-apply" \
   --reason "PartX: 更新说明" \
   --pretty
@@ -81,13 +95,13 @@ soke-cli ai-training +get-scenario \
   --pretty
 ```
 
-## 3. 各 Part 推荐 operations 文件名
+## 3. 各 Part 推荐文件名
 
-- Part2：`./part2-operations.json`
-- Part3：`./part3-operations.json`
-- Part4：`./part4-operations.json`
-- Part5：`./part5-operations.json`
-- 微调：`./optimize-operations.json`
+- Part2：`./part2-operations.json` + `./part2-update.json`
+- Part3：`./part3-operations.json` + `./part3-update.json`
+- Part4：`./part4-operations.json` + `./part4-update.json`
+- Part5：`./part5-operations.json` + `./part5-update.json`
+- 微调：`./optimize-operations.json` + `./optimize-update.json`
 
 ## 4. 知识包同步与场景绑定
 

package/skills/soke-cli/345/256/211/350/243/205/346/214/207/345/215/227.md

@@ -121,7 +121,7 @@ soke-cli --version
 # 预期输出: soke-cli version x.x.x
 ```
 
-如果显示版本号，说明安装成功 ✅。
+如果显示版本号，说明基础安装成功。完成后续登录授权后，请继续运行 `soke-cli doctor` 做完整健康检查，确保配置、登录态、日志目录和网络连通性都可用。
 
 **如果 `which soke-cli` 无输出**，说明 PATH 未生效：
 - macOS/Linux: 确认 `echo $PATH | tr ':' '\n' | grep npm-global` 有输出，若没有请重新执行第二步
@@ -212,9 +212,47 @@ soke-cli auth logout
 
 ## 验证安装
 
-完成登录授权后，让我们验证一切是否正常工作。
+完成登录授权后，让我们验证一切是否正常工作。推荐先运行 `doctor`，它会一次性检查 CLI 版本、配置文件、登录态、日志目录和网络连通性。
 
-### 1. 查看配置信息
+### 1. 运行健康检查
+
+```bash
+soke-cli doctor
+```
+
+正常情况下会看到类似输出：
+```text
+pass    cli_version     x.x.x
+pass    config          /Users/你的用户名/.soke-cli/config.json
+pass    auth            login data looks valid locally
+pass    logs            /Users/你的用户名/.soke-cli/logs
+pass    network         https://opendev.soke.cn reachable (123ms)
+```
+
+如果任意检查项显示 `fail`，请根据同一行或下一行的 `hint` 提示处理。常见情况：
+- `config` 或 `auth` 失败：重新执行 `soke-cli auth login`
+- `logs` 失败：检查 `~/.soke-cli` 或 `SOKE_CLI_LOG_DIR` 的写入权限
+- `network` 失败：检查网络连接或代理设置
+
+需要机器可读输出时，可以使用 JSON 格式：
+
+```bash
+soke-cli doctor --format json
+```
+
+如果当前环境不能访问外网，只想检查本地安装、配置、登录态和日志目录，可以跳过网络检查：
+
+```bash
+soke-cli doctor --offline
+```
+
+网络较慢时可以调大超时时间：
+
+```bash
+soke-cli doctor --timeout 30
+```
+
+### 2. 查看配置信息
 
 ```bash
 soke-cli config show
@@ -232,9 +270,9 @@ soke-cli config show
   token过期时间: 2026-10-17 12:00:00
 ```
 
-> 💡 **说明**: `app_key` 和 `app_secret` 在当前版本中不需要手动配置，授权流程会自动处理所有必要的认证信息。
+> 💡 **说明**: `app_key` 和 `app_secret` 在当前版本中不需要手动配置，授权流程会自动处理所有必要的认证信息。如果 `doctor` 已全部通过，这一步主要用于人工确认当前登录的企业和用户信息。
 
-### 2. 测试 API 调用
+### 3. 测试 API 调用
 
 尝试调用一个简单的 API：
 
@@ -244,7 +282,7 @@ soke-cli api GET /users/me
 
 如果返回你的用户信息（JSON 格式），说明一切配置正确！
 
-### 3. 使用业务命令
+### 4. 使用业务命令
 
 尝试使用一个业务快捷命令，例如查看考试列表：
 
@@ -413,4 +451,4 @@ npx skills add liuchenlong1111/soke-cli -y -g
 
 ---
 
-**祝你使用愉快！** 🎉
+**祝你使用愉快！** 🎉

package/skills/soke-course/soke-cli/345/256/211/350/243/205/346/214/207/345/215/227.md

@@ -121,7 +121,7 @@ soke-cli --version
 # 预期输出: soke-cli version x.x.x
 ```
 
-如果显示版本号，说明安装成功 ✅。
+如果显示版本号，说明基础安装成功。完成后续登录授权后，请继续运行 `soke-cli doctor` 做完整健康检查，确保配置、登录态、日志目录和网络连通性都可用。
 
 **如果 `which soke-cli` 无输出**，说明 PATH 未生效：
 - macOS/Linux: 确认 `echo $PATH | tr ':' '\n' | grep npm-global` 有输出，若没有请重新执行第二步
@@ -212,9 +212,47 @@ soke-cli auth logout
 
 ## 验证安装
 
-完成登录授权后，让我们验证一切是否正常工作。
+完成登录授权后，让我们验证一切是否正常工作。推荐先运行 `doctor`，它会一次性检查 CLI 版本、配置文件、登录态、日志目录和网络连通性。
 
-### 1. 查看配置信息
+### 1. 运行健康检查
+
+```bash
+soke-cli doctor
+```
+
+正常情况下会看到类似输出：
+```text
+pass    cli_version     x.x.x
+pass    config          /Users/你的用户名/.soke-cli/config.json
+pass    auth            login data looks valid locally
+pass    logs            /Users/你的用户名/.soke-cli/logs
+pass    network         https://opendev.soke.cn reachable (123ms)
+```
+
+如果任意检查项显示 `fail`，请根据同一行或下一行的 `hint` 提示处理。常见情况：
+- `config` 或 `auth` 失败：重新执行 `soke-cli auth login`
+- `logs` 失败：检查 `~/.soke-cli` 或 `SOKE_CLI_LOG_DIR` 的写入权限
+- `network` 失败：检查网络连接或代理设置
+
+需要机器可读输出时，可以使用 JSON 格式：
+
+```bash
+soke-cli doctor --format json
+```
+
+如果当前环境不能访问外网，只想检查本地安装、配置、登录态和日志目录，可以跳过网络检查：
+
+```bash
+soke-cli doctor --offline
+```
+
+网络较慢时可以调大超时时间：
+
+```bash
+soke-cli doctor --timeout 30
+```
+
+### 2. 查看配置信息
 
 ```bash
 soke-cli config show
@@ -232,9 +270,9 @@ soke-cli config show
   token过期时间: 2026-10-17 12:00:00
 ```
 
-> 💡 **说明**: `app_key` 和 `app_secret` 在当前版本中不需要手动配置，授权流程会自动处理所有必要的认证信息。
+> 💡 **说明**: `app_key` 和 `app_secret` 在当前版本中不需要手动配置，授权流程会自动处理所有必要的认证信息。如果 `doctor` 已全部通过，这一步主要用于人工确认当前登录的企业和用户信息。
 
-### 2. 测试 API 调用
+### 3. 测试 API 调用
 
 尝试调用一个简单的 API：
 
@@ -244,7 +282,7 @@ soke-cli api GET /users/me
 
 如果返回你的用户信息（JSON 格式），说明一切配置正确！
 
-### 3. 使用业务命令
+### 4. 使用业务命令
 
 尝试使用一个业务快捷命令，例如查看考试列表：