@sokeai/cli 1.0.66 → 1.0.68

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

@@ -0,0 +1,189 @@
+# MentorAI CLI 已验证命令清单
+
+> 用于 AI 陪练场景的标准命令速查。凡涉及场景创建、读取、预览、应用、封面上传、知识包同步，统一使用 `soke-cli ai-training +...`，不要省略 `ai-training`。
+
+## 0. 总规则
+
+- 错误写法：`soke-cli +create-scenario`
+- 正确写法：`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`
+- 每次 `apply` 后，立刻执行一次 `soke-cli ai-training +get-scenario --raw` 做验收
+- ⚠️ **所有 soke-cli 命令通过 Bash 工具执行时，必须设置 `dangerouslyDisableSandbox: true`**。soke-cli 是 Go 编译二进制，在沙箱中会被限制执行（`permission denied` 或静默无输出）。此规则适用于本文件中全部命令，不限于创建型流程
+
+## 1. Step1 创建场景
+
+### 1.1 上传封面
+
+```bash
+soke-cli ai-training +upload-scenario-cover \
+  --file ./scenario-cover.png \
+  --pretty
+```
+
+### 1.2 创建场景
+
+```bash
+soke-cli ai-training +create-scenario \
+  --request-file ./step1-create.json \
+  --pretty
+```
+
+### 1.3 创建后立即回读
+
+```bash
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --raw \
+  --pretty
+```
+
+## 2. Part2-Part5 通用同步模板
+
+### 2.1 先获取最新基线
+
+```bash
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --pretty
+```
+
+### 2.2 预览更新
+
+```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: 更新说明" \
+  --pretty
+```
+
+### 2.3 应用更新
+
+```bash
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./partX-operations.json \
+  --idempotency-key "cli-<scenario_short>-partX-apply" \
+  --reason "PartX: 更新说明" \
+  --pretty
+```
+
+### 2.4 应用后强制验收
+
+```bash
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --raw \
+  --pretty
+```
+
+## 3. 各 Part 推荐 operations 文件名
+
+- Part2：`./part2-operations.json`
+- Part3：`./part3-operations.json`
+- Part4：`./part4-operations.json`
+- Part5：`./part5-operations.json`
+- 微调：`./optimize-operations.json`
+
+## 4. 知识包同步与场景绑定
+
+### 4.1 同步知识包
+
+```bash
+soke-cli ai-training +sync \
+  --manifest ./knowledge-package.json \
+  --idempotency-key "cli-<package_id>-sync" \
+  --pretty
+```
+
+### 4.2 绑定到场景
+
+```bash
+soke-cli ai-training +bind-scenario \
+  --scenario-id <scenario_id> \
+  --version-ids <version_id> \
+  --compile-plan
+```
+
+## 5. 发布场景
+
+### 5.1 发布
+
+```bash
+soke-cli ai-training +publish-scenario \
+  --scenario-id <scenario_id> \
+  --version 1 \
+  --version-description "CLI发布" \
+  --pretty
+```
+
+### 5.2 发布后验收
+
+```bash
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --raw \
+  --pretty
+```
+
+## 6. 快照与恢复
+
+### 6.1 查询快照
+
+```bash
+soke-cli ai-training +list-scenario-snapshots \
+  --scenario-id <scenario_id> \
+  --page 1 \
+  --page-size 20 \
+  --pretty
+```
+
+### 6.2 恢复快照
+
+```bash
+soke-cli ai-training +restore-scenario-snapshot \
+  --scenario-id <scenario_id> \
+  --snapshot-id <snapshot_id> \
+  --reason "回滚本次 CLI 更新" \
+  --pretty
+```
+
+## 7. 当前已验证可用命令
+
+- `soke-cli ai-training +upload-scenario-cover`
+- `soke-cli ai-training +create-scenario`
+- `soke-cli ai-training +get-scenario`
+- `soke-cli ai-training +list-scenarios`
+- `soke-cli ai-training +preview-scenario-update`
+- `soke-cli ai-training +apply-scenario-update`
+- `soke-cli ai-training +publish-scenario`
+- `soke-cli ai-training +list-scenario-snapshots`
+- `soke-cli ai-training +restore-scenario-snapshot`
+- `soke-cli ai-training +sync`
+- `soke-cli ai-training +bind-scenario`
+
+## 8. 常见误抄与纠正
+
+- 误抄：`soke-cli +create-scenario`
+  - 改成：`soke-cli ai-training +create-scenario`
+- 误抄：`soke-cli +get-scenario`
+  - 改成：`soke-cli ai-training +get-scenario`
+- 误抄：`soke-cli +preview-scenario-update`
+  - 改成：`soke-cli ai-training +preview-scenario-update`
+- 误抄：`soke-cli +apply-scenario-update`
+  - 改成：`soke-cli ai-training +apply-scenario-update`
+- 误抄：`soke-cli +sync`
+  - 改成：`soke-cli ai-training +sync`
+- 误抄：`soke-cli +bind-scenario`
+  - 改成：`soke-cli ai-training +bind-scenario`
+
+## 7. 推荐阅读顺序
+
+1. 先看 `platform-api-pitfalls.md`
+2. 再看 `platform/sync-engine.md`
+3. 真正执行前，按本文件复制命令模板
+4. 若平台返回与历史文档冲突，以最新 CLI 实证为准

package/skills/ai-coach-director/scripts/activator.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# AI 陪练 — 学习提醒钩子
+# 每轮对话后提醒评估学习（可选启用）
+echo "[activator] 提醒：检查本轮是否有新的学习点需要记录"

package/skills/ai-coach-director/scripts/error-detector.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# AI 陪练 — 命令错误检测
+# 命令执行失败时自动检测并提示记录
+echo "[error-detector] 检测到错误，建议记录到 .learnings/ERRORS.md"

package/skills/ai-coach-director/scripts/extract-skill.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+# AI 陪练 — 学习条目提取为独立 skill
+# 用法: extract-skill.sh LRN-YYYYMMDD-XXX [--dry-run]
+LEARNING_ID="$1"
+DRY_RUN="$2"
+echo "[extract-skill] 从 $LEARNING_ID 提取新 skill"
+[ "$DRY_RUN" = "--dry-run" ] && echo "[dry-run] 预览模式，不实际执行"

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

@@ -227,9 +227,9 @@ soke-cli config show
   app_secret: (未设置)
   api_base_url: 
   corpid: corp_123456
-  dept_user_id: user_789012
-  user_token: eyJh...xyz
-  bot_token: (未设置)
+  用户ID: user_789012
+  用户凭证: eyJh...xyz
+  token过期时间: 2026-10-17 12:00:00
 ```
 
 > 💡 **说明**: `app_key` 和 `app_secret` 在当前版本中不需要手动配置，授权流程会自动处理所有必要的认证信息。

package/skills/soke-course/SKILL.md

@@ -239,7 +239,7 @@ Gate 4→5: ✅ status=1
 #### Phase 5: 指派学员
 
   → 调度 soke-assign
-    
+
   Step 5.1 拉取部门列表
     exec: soke assign +list-departments
     提取: 全量部门名称+ID → 存内存

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

@@ -227,9 +227,9 @@ soke-cli config show
   app_secret: (未设置)
   api_base_url: 
   corpid: corp_123456
-  dept_user_id: user_789012
-  user_token: eyJh...xyz
-  bot_token: (未设置)
+  用户ID: user_789012
+  用户凭证: eyJh...xyz
+  token过期时间: 2026-10-17 12:00:00
 ```
 
 > 💡 **说明**: `app_key` 和 `app_secret` 在当前版本中不需要手动配置，授权流程会自动处理所有必要的认证信息。

package/skills/soke-exam/SKILL.md

@@ -2,7 +2,7 @@
 name: soke-exam
 summary: 授客考试管理（考试/题库/试题/试卷的创建、查询与管理），通过 soke-cli 操作
 version: 1.1.0
-description: "授客考试管理：创建和查询考试、题库、试题、试卷，管理考试用户和成绩。当用户需要创建考试、创建试题、管理题库、查询考试成绩、查看考试列表时使用。"
+description: "授客考试管理：创建和查询考试、题库、试题、试卷，管理考试用户和成绩。当用户需要创建考试、创建试题、管理题库、查询考试成绩、查看考试列表时使用。 | Soke exam management: create and query exams, question banks, questions, and papers; manage exam users and scores. Use when users need to create exams, create questions, manage question banks, query exam scores, or view exam lists."
 metadata:
   requires:
     bins: ["soke-cli"]

package/skills/soke-examPool/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: soke-examPool
+summary: 授客可练习题库查询（题库列表、题库详情、题目列表），通过 soke-cli exam-pool 命令操作
+version: 1.0.0
+description: "授客可练习题库查询：按 examQuestionPool 接口链路先查询题库列表，再用题库 uuid 查询详情和题目列表。当用户需要查看可练习题库、题库详情、题目内容、答案和解析时使用。 | Soke question pool lookup: use the examQuestionPool API flow to list pools, get pool detail, and list questions."
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli exam-pool --help"
+---
+
+# 可练习题库查询 (examQuestionPool)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+
+## 核心链路
+
+这组命令对接 `/skills/examQuestionPool/...` 接口。调用顺序必须固定：
+
+1. `+list` 获取题库列表，从 `data.list[].uuid` 取题库 UUID。
+2. `+get --pool-id <uuid>` 查询详情，确认 `data.info.uuid` 与传入 `pool-id` 一致。
+3. `+questions --pool-id <uuid>` 使用同一个 `pool-id` 查询题目。
+
+`--page`、`--page-size`、`--status` 只用于第一步列表分页和筛选，不要传给详情或题目查询。
+
+## Shortcuts 总览
+
+| Shortcut | 说明 |
+|----------|------|
+| `+list` | 获取可练习题库列表，返回后续 `pool-id` 所需的 `uuid` |
+| `+get` | 根据题库 `pool-id` 获取可练习题库详情 |
+| `+questions` | 根据同一个 `pool-id` 获取题库题目 |
+
+## +list
+
+获取可练习题库列表。
+
+```bash
+soke-cli exam-pool +list \
+  --page 1 \
+  --page-size 10 \
+  --status 1 \
+  --format json
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--page` | 否 | 页码，从 1 开始，默认 1 |
+| `--page-size` | 否 | 每页条数，默认 10 |
+| `--status` | 否 | 状态筛选，`1` 表示启用 |
+
+关键返回字段：
+
+| 字段 | 说明 |
+|------|------|
+| `data.list[].uuid` | 题库 UUID，后续作为 `--pool-id` |
+| `data.list[].title` | 题库标题 |
+| `data.list[].question_count` | 题目数量 |
+| `data.list[].category_title` | 分类名称 |
+
+## +get
+
+根据题库 UUID 获取可练习题库详情。
+
+```bash
+soke-cli exam-pool +get \
+  --pool-id "<上一步 data.list[].uuid>" \
+  --format json
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--pool-id` | 是 | 题库 ID，必须来自 `+list` 的 `data.list[].uuid` |
+
+关键返回字段：
+
+| 字段 | 说明 |
+|------|------|
+| `data.info.uuid` | 题库 UUID，应与请求 `--pool-id` 一致 |
+| `data.info.title` | 题库标题 |
+| `data.all_count` | 题库总题数 |
+| `data.point` | 积分配置 |
+| `data.examPoolUser` | 当前用户在题库中的状态 |
+| `data.question_url` | 题库题目 JSON 地址 |
+| `data.answer_url` | 题库答案 JSON 地址 |
+
+## +questions
+
+根据同一个题库 UUID 获取题目明细。
+
+```bash
+soke-cli exam-pool +questions \
+  --pool-id "<同一个题库 uuid>" \
+  --format json
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--pool-id` | 是 | 题库 ID，复用列表或详情中的同一个 UUID |
+
+关键返回字段：
+
+| 字段 | 说明 |
+|------|------|
+| `data.pool_id` | 题库 ID，应与请求 `--pool-id` 一致 |
+| `data.content[].uuid` | 题目 UUID |
+| `data.content[].title` | 题目标题 |
+| `data.content[].type` | 题目类型 |
+| `data.content[].choices` | 选项列表 |
+| `data.content[].show_answer` | 展示答案 |
+| `data.content[].analysis` | 题目解析 |
+
+## 推荐操作顺序
+
+```bash
+# 1. 查询题库列表，取 data.list[0].uuid
+soke-cli exam-pool +list --page 1 --page-size 10 --status 1 --format json
+
+# 2. 查询题库详情
+soke-cli exam-pool +get --pool-id "<pool_uuid>" --format json
+
+# 3. 查询同一题库的题目
+soke-cli exam-pool +questions --pool-id "<pool_uuid>" --format json
+```

package/skills/soke-learning-map/SKILL.md

@@ -2,7 +2,7 @@
 name: soke-learning-map
 summary: 授客学堂学习地图管理（创建/阶段/发布/查询/指派），完整管理学习地图生命周期
 version: 1.0.0
-description: "授客学堂学习地图管理：完整的学习地图生命周期管理，包括创建学习地图、查询课程分类与课程、检查课程可用性、创建阶段、发布地图、指派部门/学员、查询学员进度的全链路流程。集成 soke-assign（指派管理）子 skill。当用户需要创建学习地图、添加阶段和课程内容、发布地图、指派学员、查询学习进度时使用。"
+description: "授客学堂学习地图管理：完整的学习地图生命周期管理，包括创建学习地图、查询课程分类与课程、检查课程可用性、创建阶段、发布地图、指派部门/学员、查询学员进度的全链路流程。集成 soke-assign（指派管理）子 skill。学习地图学员统计导出任务已独立到 soke-task skill。当用户需要创建学习地图、添加阶段和课程内容、发布地图、指派学员、查询学习进度时使用。 | Soke Academy learning map management: complete learning map lifecycle management, covering the full workflow of creating learning maps, querying course categories and courses, checking course availability, creating stages, publishing maps, assigning departments/learners, and querying learner progress. Integrates soke-assign (assignment management) sub-skill. Learning map learner statistics export tasks are handled by the standalone soke-task skill. Use when users need to create learning maps, add stages and course content, publish maps, assign learners, or query learning progress."
 metadata:
   requires:
     bins: ["soke-cli"]
@@ -380,6 +380,8 @@ soke-cli learning-map +detail --uuid "MAP-UUID" --format json
 | `+list-item-users` | 查询内容学员列表 | read |
 | `+get-map-user` | 查询单个学员详情 | read |
 
+学员统计导出任务使用独立模块：`soke-cli task +create` / `soke-cli task +get`，详见 [`../soke-task/SKILL.md`](../soke-task/SKILL.md)。
+
 ### 指派管理（soke-assign）
 
 | 命令 | 说明 |

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

@@ -227,9 +227,9 @@ soke-cli config show
   app_secret: (未设置)
   api_base_url: 
   corpid: corp_123456
-  dept_user_id: user_789012
-  user_token: eyJh...xyz
-  bot_token: (未设置)
+  用户ID: user_789012
+  用户凭证: eyJh...xyz
+  token过期时间: 2026-10-17 12:00:00
 ```
 
 > 💡 **说明**: `app_key` 和 `app_secret` 在当前版本中不需要手动配置，授权流程会自动处理所有必要的认证信息。

package/skills/soke-learning-profile/SKILL.md

@@ -2,7 +2,7 @@
 name: soke-learning-profile
 summary: 学员学习档案查询
 version: 1.0.0
-description: "学员学习档案查询：查询学员的完整学习记录，包括课程学习、考试成绩、证书获取、学分积分等。当用户需要查询学员学习档案、查看学员学习情况、统计学员学习数据、查询学员综合学习信息时使用。"
+description: "学员学习档案查询：查询学员的完整学习记录，包括课程学习、考试成绩、证书获取、学分积分等。当用户需要查询学员学习档案、查看学员学习情况、统计学员学习数据、查询学员综合学习信息时使用。 | Learner learning profile query: query a learner's complete learning records, including course learning progress, exam scores, certificate acquisition, credits, and points. Use when users need to query learner profiles, review learning status, aggregate learning statistics, or retrieve comprehensive learning information for a learner."
 metadata:
   requires:
     bins: ["soke-cli"]

package/skills/soke-photo-gallery/SKILL.md

@@ -2,7 +2,7 @@
 name: soke-photo-gallery
 summary: 授客图片库管理（查询分类/图片列表、上传图片、批量删除），上传自动处理 OSS 存储
 version: 1.0.0
-description: "授客图片库管理：查询图片分类列表、查询图片库列表、上传本地图片到图片库（自动先上传 OSS 再创建记录）、批量删除图片。当用户需要管理图片库、上传图片、查询图片、删除图片时使用。"
+description: "授客图片库管理：查询图片分类列表、查询图片库列表、上传本地图片到图片库（自动先上传 OSS 再创建记录）、批量删除图片。当用户需要管理图片库、上传图片、查询图片、删除图片时使用。 | Soke photo gallery management: query image category lists, query photo gallery lists, upload local images to the gallery (automatically uploads to OSS first, then creates the record), and batch delete images. Use when users need to manage the photo gallery, upload images, query images, or delete images."
 metadata:
   requires:
     bins: ["soke-cli"]

package/skills/soke-shared/SKILL.md

@@ -21,6 +21,7 @@ soke-cli auth login
 ```
 
 配置项包括：
+- `app_id`: 开放平台应用ID
 - `app_key`: 开放平台应用Key
 - `app_secret`: 开放平台应用Secret
 - `api_base_url`: API地址（默认: https://opendev.soke.cn）

package/skills/soke-task/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: soke-task
+summary: 授客学堂异步任务管理（创建任务/查询任务），支持学习地图学员统计导出
+version: 1.0.0
+description: "授客学堂异步任务管理：通过独立 task 命令创建和查询异步导出任务。目前支持学习地图学员统计导出任务，按“创建任务 -> 获取 data.id -> 查询任务详情和 filePath”的流程使用。当用户需要导出学习地图学员统计、查询导出任务状态、获取导出文件下载地址时使用。 | Soke Academy async task management: create and query export jobs through the standalone task command. Currently supports learning map learner statistics export tasks. Use when users need to export learner statistics, check export task status, or obtain exported file URLs."
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli task --help"
+---
+
+# 异步任务管理 (soke-task)
+
+**CRITICAL — 开始前 MUST 先读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置和权限处理。**
+
+## 核心规则
+
+- 任务接口是独立模块，命令统一使用 `soke-cli task ...`，不要使用 `soke-cli learning-map ...` 创建或查询任务。
+- 创建任务后必须保存返回的 `data.id`，再调用 `+get` 查询任务详情。
+- 默认用 `--format json` 获取结构化输出；需要人工快速查看时可省略 format 输出表格。
+- 当前已知任务类型是学习地图学员统计导出，`--module` 默认 `learningMapUser`，`--action` 默认 `export`。
+
+## 命令
+
+### 创建学习地图学员统计导出任务
+
+```bash
+soke-cli task +create \
+  --map-id "MAP-UUID" \
+  --learn-type "required" \
+  --limit 4500 \
+  --format json
+```
+
+完整参数：
+
+| 参数 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--map-id` | 是 | - | 学习地图 UUID |
+| `--module` | 否 | `learningMapUser` | 任务模块，学习地图学员统计固定为 `learningMapUser` |
+| `--learn-type` | 否 | `required` | 学习类型，如 `required` |
+| `--learn-status` | 否 | 空 | 学习状态筛选：空值表示不限，`learning` 未完成，`finished` 已完成 |
+| `--eligible-status` | 否 | 空 | 达标状态筛选，空值表示不限 |
+| `--limit` | 否 | `4500` | 任务处理上限 |
+| `--action` | 否 | `export` | 操作类型，导出任务固定为 `export` |
+
+响应关键字段：
+
+| 字段 | 说明 |
+|------|------|
+| `data.id` | 任务 ID，查询任务详情时传给 `+get --id` |
+| `data.key` | 任务去重或配置缓存 Key |
+| `data.config_result` | 上游配置模块检查结果 |
+
+默认输出会打印单行任务 ID，例如 `id:13288419`。需要完整字段时使用 `--format json`。
+
+### 查询异步导出任务
+
+```bash
+soke-cli task +get --id "TASK-ID" --format json
+```
+
+响应关键字段：
+
+| 字段 | 说明 |
+|------|------|
+| `data.status` | 任务执行状态；接口示例中 `2` 表示执行完成 |
+| `data.export_status` | 导出状态；接口示例中 `2` 表示已生成导出文件 |
+| `data.filePath` | 导出文件访问地址，未生成时为空 |
+| `data.filename` | 导出文件名 |
+| `data.filesize` | 导出文件大小 |
+| `data.params` | 创建任务参数的 JSON 字符串 |
+
+## 推荐工作流
+
+```bash
+TASK_ID=$(soke-cli task +create \
+  --map-id "$MAP_UUID" \
+  --learn-type "required" \
+  --limit 4500 \
+  --format json | jq -r '.data.id')
+
+soke-cli task +get --id "$TASK_ID" --format json | jq -r '.data.filePath'
+```
+
+## API 接口映射
+
+| CLI 命令 | API 路径 | 方法 |
+|----------|----------|------|
+| `task +create` | `/skills/job/task` | POST (form) |
+| `task +get` | `/skills/job/task/{id}` | GET |
+
+## 排错
+
+- `data.filePath` 为空：任务可能还未完成，等待后重新执行 `task +get --id "TASK-ID" --format json`。
+- `未登录授权`：按 `soke-shared` 执行 `soke-cli auth login` 后重试。
+- 任务创建失败：确认 `--map-id` 是有效学习地图 UUID，`--module learningMapUser`，`--action export`。

package/skills/soke-training-demand/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: soke-training-demand
+summary: 培训需求收集：查询需求、查询分类、提交培训需求和投票
+version: 1.0.0
+description: "用于通过 soke-cli 对接授客AI培训需求收集接口。当用户需要查看培训需求列表、获取需求分类、提交新的培训需求、或给培训需求投票时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli training-demand --help"
+---
+
+# 培训需求收集
+
+**CRITICAL — 开始前 MUST 先读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置和权限处理。**
+
+## 核心规则
+
+- 提交需求前，先执行 `+list-categories`，使用返回的分类 `uuid` 和 `title`。
+- 投票前，先执行 `+list`，使用返回的培训需求 `uuid`。不要把分类 `uuid` 传给投票接口。
+- 创建和投票是写操作。用户意图不明确时，先确认要提交或投票的对象。
+- 默认用 `--format json` 获取结构化输出；需要人工快速查看时可省略 format 输出表格。
+
+## 命令
+
+### 查询培训需求列表
+
+```bash
+soke-cli training-demand +list \
+  --page 1 \
+  --limit 10 \
+  --status 1 \
+  --keyword "" \
+  --is-owner 0 \
+  --create-time-order desc \
+  --owner-vote 0 \
+  --format json
+```
+
+列表返回的 `data.list[].uuid` 是投票使用的培训需求 UUID。
+
+### 查询培训需求分类
+
+```bash
+soke-cli training-demand +list-categories --format json
+```
+
+分类返回的 `data.list[].uuid` 和 `data.list[].title` 只用于创建需求。
+
+### 提交培训需求
+
+推荐从分类列表提取分类后，用分类 UUID 和名称提交：
+
+```bash
+soke-cli training-demand +create \
+  --title "门店销售沟通训练" \
+  --tag "销售,沟通" \
+  --level 0 \
+  --category-uuid "FA0C937C-EE52-463B-BE3A-C13F96C426AE" \
+  --category-title "新建培训需求测试" \
+  --format json
+```
+
+多分类或已有完整分类数组时，使用 `--category-list`：
+
+```bash
+soke-cli training-demand +create \
+  --title "新员工产品知识培训" \
+  --tag "产品,新员工" \
+  --level 0 \
+  --category-list '[{"uuid":"FA0C937C-EE52-463B-BE3A-C13F96C426AE","title":"新建培训需求测试"}]' \
+  --format json
+```
+
+### 给培训需求投票
+
+```bash
+soke-cli training-demand +vote \
+  --uuid "41EA8B23-5E5E-48FD-99A3-FF8F420752A6" \
+  --format json
+```
+
+`--uuid` 必须来自 `+list` 返回的需求 UUID。
+
+## 常见工作流
+
+1. 用户说“我想提一个培训需求”：
+   - 先问清楚标题、标签、分类偏好和等级。
+   - 执行 `+list-categories --format json`。
+   - 匹配或让用户选择分类。
+   - 执行 `+create`。
+
+2. 用户说“帮我给某个需求投票”：
+   - 执行 `+list --keyword "<关键词>" --format json`。
+   - 用需求标题和创建人等信息确认目标。
+   - 执行 `+vote --uuid "<需求uuid>"`。
+
+3. 用户只想浏览需求：
+   - 执行 `+list --page 1 --limit 10 --create-time-order desc`。
+   - 返回标题、分类、标签、票数、是否已投票和需求 UUID。
+
+## 字段依赖
+
+| 场景 | 依赖字段 | 来源 |
+|------|----------|------|
+| 创建需求 | `category_list[].uuid` / `category_list[].title` | `+list-categories` 的 `data.list[]` |
+| 投票 | `uuid` | `+list` 的 `data.list[].uuid` |
+
+## 排错
+
+- 创建失败提示分类无效：重新执行 `+list-categories`，不要使用需求列表中的分类名称手写 UUID。
+- 投票失败提示需求无效：确认传入的是培训需求 UUID，不是分类 UUID。
+- 鉴权失败：按 `soke-shared` 执行 `soke-cli auth login` 后重试。