@sokeai/cli 1.0.74 → 1.0.76

package/skills/soke-course/references/subs/settings/SOP.md

@@ -1,7 +1,7 @@
 ---
 name: soke-course-settings
 version: 1.0.0
-description: 课程设置 — 基础信息编辑及高级设置项说明，高级设置需后台操作
+description: 课程设置 — 基础信息编辑及高级设置项说明，支持通过 CLI 更新课程高级设置
 tags: [soke, course, settings, configuration, advanced]
 ---
 
@@ -9,7 +9,7 @@ tags: [soke, course, settings, configuration, advanced]
 
 ## 触发描述
 
-课程创建后需要对课程标题、描述等基础信息进行修改，或需要了解高级设置项（学习模式、人脸识别、证书等）的配置方式时触发本技能。
+课程创建后需要对课程标题、描述等基础信息进行修改，或需要更新高级设置项（学习模式、人脸识别、提醒、倍速等）时触发本技能。
 
 ## CLI 支持的操作
 
@@ -19,33 +19,88 @@ tags: [soke, course, settings, configuration, advanced]
 soke course +update \
   --course-id <courseId> \
   --title "<新标题>" \
-  --description "<新描述>"
+  --credit 10 \
+  --description "<新描述>" \
+  --image "<图片库 photoUri>"
 ```
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--course-id` | 是 | 课程 ID |
 | `--title` | 否 | 课程标题 |
+| `--credit` | 否 | 学分 |
 | `--description` | 否 | 课程描述/简介 |
+| `--image` | 否 | 课程封面图片地址，使用图片库列表接口返回的 `photoUri` |
+| `--image-x` | 否 | 封面裁剪 x 坐标，默认 0 |
+| `--image-y` | 否 | 封面裁剪 y 坐标，默认 0 |
+| `--image-w` | 否 | 封面裁剪宽度，默认 0 |
+| `--image-h` | 否 | 封面裁剪高度，默认 0 |
 
-> `title` 和 `description` 至少传一个，可同时更新。
+> 至少传一个可更新字段，可同时更新。`--description ""` 会清空课程描述。
 
-## ⚠️ CLI 不支持的高级设置
+### 高级设置更新 `course +advanced`
 
-以下 9 项高级设置均需通过管理后台操作，CLI 暂不支持：
+```bash
+soke course +advanced \
+  --course-id <courseId> \
+  --study-type 2 \
+  --is-accelerate 1 \
+  --is-drag 0 \
+  --evaluate-required 1
+```
+
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| `--course-id` | 必填 | 课程 ID |
+| `--open-workrecord` | 0 | 待办推送，1 开启，0 不开启 |
+| `--allow-after-expiration` | 1 | 截止后继续学习，1 允许，0 不允许 |
+| `--open-face-recognition` | 0 | 课程前人脸识别，1 开启，0 不开启 |
+| `--is-first-face` | 0 | 0 不识别，1 首次使用，2 每次进入 |
+| `--learning-face-recognition` | 0 | 视频学习中人脸识别，1 开启，0 不开启 |
+| `--face-recognition-times` | 1 | 视频学习中人脸识别次数 |
+| `--study-type` | 1 | 学习模式，1 自由式，2 解锁式 |
+| `--is-remind` | 0 | 未学提醒，1 开启，0 不开启 |
+| `--remind-days` | 1 | 未学提醒推送周期，单位天 |
+| `--remind-time` | 空 | 推送时间，格式 HH:MM:SS |
+| `--remind-content` | 管理员提醒文案 | 未学提醒推送内容 |
+| `--is-accelerate` | 1 | 视频或音频倍速，1 开启，0 不开启 |
+| `--is-drag` | 0 | 视频是否可拖动，1 允许，0 不允许 |
+| `--drag-type` | 1 | 1 仅首次播放不允许拖动，2 每次播放均不允许拖动 |
+| `--evaluate-required` | 0 | 完成学习后打星评价，1 开启，0 不开启 |
+| `--image-file` | 空 | 本地交流群二维码图片路径，命令内部上传到 OSS 并写入 `imageOssUrl`，不进入图片库；支持 jpg/jpeg/png |
+| `--image-oss-url` | 空 | 已上传到 OSS/CDN 的交流群二维码完整访问 URL；与 `--image-file` 二选一 |
+| `--is-hang` | 0 | 文档防挂机，1 开启，0 不开启 |
+| `--hang-time` | 0 | 文档防挂机时间，单位分钟，最多 60 |
+| `--comment-switch` | 1 | 课程评论，1 开启，0 不开启 |
+
+该命令请求 `PUT /skills/course/advanceSetting/{id}`，请求体固定带 `action=advanced`。
+
+**交流群二维码 `imageOssUrl` 取值规则：**
+
+1. 如果用户提供的是本地二维码图片，直接使用 `--image-file`。命令会在内部调用 OSS 上传能力，使用 `Module: "image"` 上传，并把签名里的 `editorHost`（优先）或 `cdnhost` 与 OSS object 拼成完整 URL 写入 `imageOssUrl`。该图片不会进入图片库。
+
+```bash
+soke-cli course +advanced \
+  --course-id <courseId> \
+  --image-file "./qrcode.png"
+```
 
-| 序号 | 设置项 | 说明 | 后台操作路径 |
-|------|--------|------|-------------|
-| 1 | **学习模式** `study_type` | 必修/选修模式、闯关模式（顺序解锁）、自由模式 | 后台 → 课程管理 → 课程列表 → 编辑 → 学习设置 |
-| 2 | **倍速播放** `speed` | 允许学员使用倍速播放（0.5x - 2.0x） | 后台 → 课程管理 → 课程列表 → 编辑 → 学习设置 → 播放控制 |
-| 3 | **人脸识别** `face_recognition` | 开启后学员学习时需人脸验证，防挂机/替学 | 后台 → 课程管理 → 课程列表 → 编辑 → 学习设置 → 人脸识别 |
-| 4 | **学习提醒** `reminders` | 配置定时提醒推送（未完成学员、推送时间、频次） | 后台 → 课程管理 → 课程列表 → 编辑 → 学习设置 → 提醒设置 |
-| 5 | **课程评价** `rating` | 开启学员评分/评论功能，可设为审核后展示 | 后台 → 课程管理 → 课程列表 → 编辑 → 评价设置 |
-| 6 | **证书设置** `certificate` | 配置结业证书模板（背景图、字段、盖章）和通过条件 | 后台 → 课程管理 → 课程列表 → 编辑 → 证书设置 |
-| 7 | **证书签名** `signature` | 配置证书上的签名图片（讲师/负责人手写签名） | 后台 → 课程管理 → 课程列表 → 编辑 → 证书设置 → 签名管理 |
-| 8 | **钉钉二维码** `dingtalk_qrcode` | 配置钉钉群二维码，学员学习页展示入群入口 | 后台 → 课程管理 → 课程列表 → 编辑 → 学习设置 → 钉钉二维码 |
+2. 如果用户已经有 OSS/CDN 完整访问 URL，直接传 `--image-oss-url`：
 
-> 操作路径示例以标准后台结构为准，实际路径可能因后台版本略有差异。
+```bash
+soke-cli course +advanced \
+  --course-id <courseId> \
+  --image-oss-url "$IMAGE_URL"
+```
+
+3. `--image-file` 和 `--image-oss-url` 只能传一个。不要把图片 UUID、素材 UUID 或纯 `data.object` 当作 `imageOssUrl`；该字段需要可访问的完整图片 URL。
+
+## ⚠️ CLI 暂不支持的设置
+
+| 设置项 | 说明 | 后台操作路径 |
+|--------|------|-------------|
+| **证书设置** `certificate` | 配置结业证书模板（背景图、字段、盖章）和通过条件 | 后台 → 课程管理 → 课程列表 → 编辑 → 证书设置 |
+| **证书签名** `signature` | 配置证书上的签名图片（讲师/负责人手写签名） | 后台 → 课程管理 → 课程列表 → 编辑 → 证书设置 → 签名管理 |
 
 ## 输出标准
 
@@ -57,18 +112,24 @@ soke course +update \
 - 描述: {newDescription 摘要}
 ```
 
-当用户询问高级设置时，列出上述 9 项并以表格形式呈现，引导至对应后台路径。
+高级设置更新成功后：
+
+```
+✅ 课程高级设置更新成功
+- 课程: {courseId}
+- 结果: 1
+```
 
 ## 注意事项
 
-1. `course +update` 仅支持 `title` 和 `description` 两个字段的修改
-2. 封面图修改属于素材上传范围，不在本技能覆盖内
-3. 分类修改需通过专门的分类设置功能或后台操作
-4. 高级设置项之间可能存在依赖关系（如证书依赖签名设置），建议按表格顺序逐项配置
+1. `course +update` 支持标题、学分、描述、封面图和分类 ID 修改
+2. 封面图地址来自图片库列表接口返回的 `photoUri`
+3. 分类修改可通过 `--category-id` 更新
+4. 高级设置项之间可能存在依赖关系（如开启视频学习中人脸识别后再设置识别次数），建议按表格顺序逐项配置
 5. 钉钉二维码设置与课程复制时的行为有关联（复制时不携带，见 `soke-course-copy`）
 
 ## 检查清单
 
-- [ ] CLI 操作：title/description 已准备完毕，courseId 确认存在
-- [ ] 高级设置需求已识别，已提供对应后台路径
-- [ ] 所有 9 项高级设置均已告知用户为后台操作
+- [ ] CLI 操作：title/description 或高级设置参数已准备完毕，courseId 确认存在
+- [ ] 高级设置需求已识别，优先使用 `course +advanced`
+- [ ] 证书/签名等未支持设置已提供对应后台路径

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. 使用业务命令
 
 尝试使用一个业务快捷命令，例如查看考试列表：
 

package/skills/soke-exam-question-pool/SKILL.md

@@ -1,155 +1,123 @@
 ---
 name: soke-exam-question-pool
-summary: 授客可练习题库（题库列表、题库详情、题目列表、题库练习交卷），通过 soke-cli exam-question-pool 命令操作
-version: 1.1.0
-description: "授客可练习题库：按 examQuestionPool 接口链路先查询题库列表，再用题库 uuid 查询详情、题目列表，可进行题库练习交卷。当用户需要查看可练习题库、题库详情、题目内容、答案和解析，或提交题库练习交卷时使用。 | Soke question pool: use the examQuestionPool API flow to list pools, get pool detail, list questions, and finish a practice session."
+summary: 授客可练习题库交互式练习系统
+version: 2.0.0
+description: 授客可练习题库交互式练习
 metadata:
   requires:
-    bins: ["soke-cli"]
-  cliHelp: "soke-cli exam-question-pool --help"
+    bins: [soke-cli]
+  cliHelp: soke-cli exam-question-pool --help
 ---
 
-# 可练习题库 (examQuestionPool)
+# 可练习题库交互式练习系统
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+核心链路全量分页选库随机逐题实时反馈
 
-## 核心链路
+## 交互流程总览
 
-这组命令对接 `/skills/examQuestionPool/...` 接口。推荐调用顺序：
+用户触发练习Step1全量分页拉取全部题库展示供选择Step2用户选择一个题库Step3拉取该题库全部题目加载答题状态Step4从未答题目中随机抽一道呈现判分Step5询问下一题结束重开循环Step4
 
-1. `+list` 获取题库列表，从默认输出的 `uuid` 取题库 UUID。
-2. `+get --pool-id <uuid>` 查询详情，确认题库列表的 `uuid` 与传入 `pool-id` 一致。
-3. `+questions --pool-id <uuid>` 使用同一个 `pool-id` 查询题目。
-4. `+finish --pool-id <uuid> --answers '<答案JSON>'` 进行题库练习交卷。
+## Step1全量分页拉取题库列表
 
-`--page`、`--page-size` 用于第一步题库列表分页查询。
+soke-cli exam-question-pool +list --page 1 --page-size 100 --status 1 --format json
 
-## Shortcuts 总览
+循环拉取检查data.hasMore若为1则继续翻页直到hasMore为0合并所有页data.list按uuid去重
+重要API分页存在跨页重叠bug相邻两页可能返回相同uuid的题库必须按uuid去重不能简单拼接
+优先使用page-size100一次拉全减少分页次数和重叠风险
 
-| Shortcut | 说明 |
-|----------|------|
-| `+list` | 获取可练习题库列表，返回后续 `pool-id` 所需的题库 `uuid` |
-| `+get` | 根据题库 `pool-id` 获取可练习题库详情 |
-| `+questions` | 根据 `pool-id`(题库id)，即题库列表的 `uuid`，获取题库题目 |
-| `+finish` | 根据 `pool-id` 进行题库练习交卷 |
+### 展示规则
 
-## +list
+每个题库一行选项只显示序号和题库名称格式为title
+不要显示题目数question_count和状态pass_status
+题库总数小于等于20一次性展示全部
+题库总数大于20分页展示每页最多20个末尾追加下一页翻到底后追加上一页
 
-获取可练习题库列表。
+## Step2用户选择题库
 
-```bash
-soke-cli exam-question-pool +list \
-  --page 1 \
-  --page-size 10
-```
+用户输入编号取pool_id为选中项的uuid
+若用户说随机选一个从未完成题库中随机选全部完成则全量随机
 
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--page` | 否 | 页码，从 1 开始，默认 1 |
-| `--page-size` | 否 | 每页条数，默认 10 |
+## Step3拉取题目和初始化状态
 
-默认输出为横向单行文本，每条题库数据显示：
+soke-cli exam-question-pool +questions --pool-id UUID --format json
 
-| 字段 | 说明 |
-|------|------|
-| `uuid` | 题库 UUID，后续作为 `--pool-id` |
-| `title` | 题库标题 |
-| `description` | 题库描述，默认会清理简单 HTML 标签和换行 |
-| `题目数量` | 来自 `question_count` |
-| `创建时间` | 来自 `create_exercise_time` |
+注意pool-id的值不要加引号否则会报参数格式错误
 
-## +get
+提取data.content中所有题目uuid type title choices answer show_answer analysis
 
-根据题库 UUID 获取可练习题库详情。
+### 答题状态文件
 
-```bash
-soke-cli exam-question-pool +get \
-  --pool-id "<上一步题库列表的 uuid，即题库id>"
-```
+路径C:\Users\soke\.qclaw\workspace\.exam-state\{pool-uuid}.json
 
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--pool-id` | 是 | 题库 ID，必须来自 `+list` 默认输出中的 `uuid` |
+格式pool_id uuid pool_title 题库名 total 5 correct 0 answered 空数组
 
-默认输出为横向单行文本，题库详情数据：
+文件不存在或pool_id不匹配新建answered为空数组
+答完一题追加uuid到answered正确则correct加1
+结束答题保留state
+重新开始清空answered为空数组correct为0
+answered长度大于等于total自动提示本轮全部答完
+已展示但未作答的题目不算已答用户在题目展示后说退出结束退出答题等该题不计入answered不计入correct不出现在本轮总结表格中只有用户实际选择了选项或输入了答案并提交才算作答
 
-| 字段 | 说明 |
-|------|------|
-| `uuid` | 题库 UUID，应与请求 `--pool-id` 一致 |
-| `title` | 题库标题 |
-| `description` | 题库描述，默认会清理简单 HTML 标签和换行 |
-| `题目数量` | 来自 `question_count` |
-| `创建时间` | 来自 `create_exercise_time` |
-| `总题数` | 来自 `data.all_count` |
+## Step4随机出题和呈现
 
+### 随机逻辑
 
-## +questions
+从data.content排除answered中已有uuid
+剩余题目随机选一道
+每次进入题库出题顺序随机不固定
 
-根据同一个题库 UUID 获取题目明细。
+### 用户输出红线
 
-```bash
-soke-cli exam-question-pool +questions \
-  --pool-id "<题库列表的 uuid，即题库id>"
-```
+严禁在面向用户的任何输出中暴露内部标识字段包括但不限于uuid pool_id source_id category_id target_id dept_user_id company_id answer_type display
+这些字段仅用于内部逻辑和状态文件不要出现在题目展示判分反馈进度统计小结表格或任何用户可见的文本中
+如果需要区分题目在内部用uuid但在用户界面只用序号或题目内容来标识
+用户看到的内容应该像正常的练习题一样干净简洁没有任何技术性ID字段
 
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--pool-id` | 是 | 题库 ID，复用列表或详情中的同一个 UUID |
+### 按题型呈现
 
-默认输出为 JSON，是题目数据本身。
+A填空题type fill文本输入禁止变选择题
+纯文本呈现题目提示用户输入答案
+题目展示标题填空题第X题共N题题目将title中的span标签替换为括号加下划线提示多个空请用英文逗号分隔如答案1答案2答案3
+重要提示示例绝不能使用当前题目的正确答案只能用答案1答案2答案3等占位符
+填空判分show_answer为二维数组用户逗号分隔答案按序对应每个空匹配子数组中任一值即算对忽略首尾空格大小写不敏感全对正确部分对逐空标注全错错误
 
-关键字段：
+B判断题type determine
+标题判断题第X题共N题选项A正确B错误判分show_answer A正确B错误
 
-| 字段 | 说明 |
-|------|------|
-| `uuid` | 题目 UUID |
-| `title` | 题目标题 |
-| `type` | 题目类型 |
-| `choices` | 选项列表 |
-| `show_answer` | 展示答案 |
-| `analysis` | 题目解析 |
+C单选题type single_choice
+标题单选题第X题共N题选项A choices0 title B choices1 title等判分show_answer如A用户选了选项A即对
 
-## 推荐操作顺序
+D多选题type choice
+标题多选题第X题共N题选项同单选判分用户所选字母集合与show_answer字母集合完全一致顺序无关
 
-```bash
-# 1. 查询题库列表，取输出中的 uuid
-soke-cli exam-question-pool +list --page 1 --page-size 10
+E不定项选择type uncertain_choice
+同多选题标题标注不定项选择
 
-# 2. 查询题库详情
-soke-cli exam-question-pool +get --pool-id "<pool_uuid>"
+## Step5判分反馈和循环
 
-# 3. 查询同一题库的题目列表
-soke-cli exam-question-pool +questions --pool-id "<pool_uuid>"
+答完后纯文本反馈正确或错误你的答案正确答案解析如有进度已答n题共total题正确m题pct百分比
+然后询问下一步下一题结束答题重新开始本轮
+下一题保存状态回到Step4
+结束答题保存状态显示本轮小结退出当前题目未作答则不计入总结
+重新开始本轮清空answered和correct回到Step4
+本轮答完时仅提供重新开始和结束
 
-# 4. 题库练习交卷
-soke-cli exam-question-pool +finish \
-  --pool-id "<pool_uuid>" \
-  --answers '{"<question_uuid>":[0,1]}'
-```
+### 本轮小结规则
 
-## +finish
+总结表格只包含实际作答的题目即uuid已写入answered的题目
+已展示但用户说退出未作答的题目不出现在总结中下次进入该题库时仍会出现
+进度统计以状态文件中的answered和correct为准不要自行脑补
 
-提交可练习题库练习交卷。
+## Shortcuts参考
 
-```bash
-soke-cli exam-question-pool +finish \
-  --pool-id "70DE9AFB-1C18-4F5C-B158-E25182ECBE1A" \
-  --answers '{"A93647C7-7ECF-44D6-931D-DE84344DA580":["1","1","1"],"0E7E8283-EB5F-489C-9778-34A9B2F13BA7":[0]}'
-```
+list获取可练习题库列表
+get获取题库详情
+questions获取题库全部题目
 
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--pool-id` | 是 | 题库 ID，复用列表或详情中的同一个 UUID |
-| `--answers` | 是 | 答案 JSON 原文，key 为题目 ID，数组为答题选项 |
+## 重要注意
 
-`--answers` 会加密之后进行传输。
-
-返回结果默认展示：
-
-| 字段 | 说明 |
-|------|------|
-| `rightCount` | 答对题目数 |
-| `allCount` | 全部题目数量 |
-| `rate` | 题库练习进度 |
-
-默认输出示例：`题库id:70DE9AFB-1C18-4F5C-B158-E25182ECBE1A，答对题目数：2，全部题目数量：0，题库练习进度：0%`。使用 `--format json` 时输出接口原始字段。
+data.content数量可能与all_count不一致过滤题以实际返回为准
+填空show_answer是string二维数组每空可能有多个可接受值
+状态文件路径C:\Users\soke\.qclaw\workspace\.exam-state\uuid.json先确保目录存在
+每次出题前根据当前状态重新计算未答题池保证随机性
+填空题提示示例不能泄露正确答案统一用答案1答案2答案3占位

package/skills/soke-learning-map/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
 
 ---
 
-**祝你使用愉快！** 🎉
+**祝你使用愉快！** 🎉