@sokeai/cli 1.0.67 → 1.0.69

package/README.md

@@ -7,6 +7,7 @@
 - [核心能力](#核心能力)
 - [安装方法](#安装方法)
 - [快速开始](#快速开始)
+- [日志与排障](#日志与排障)
 - [开发指南](#开发指南)
   - [从接口封装到发布的完整流程](#从接口封装到发布的完整流程)
   - [本地开发测试](#本地开发测试)
@@ -142,6 +143,78 @@ soke-cli course +list-courses --start-time 1672502400000 --end-time 170403840000
 soke-cli exam +get-exam-user --exam-id exam123 --dept-user-id user456
 ```
 
+## 日志与排障
+
+`soke-cli` 默认会在本地写入结构化诊断日志，用于排查用户执行命令时的本地环境、命令链路、HTTP 请求摘要和错误关联信息。日志不会自动上传。
+
+### 查看日志路径
+
+```bash
+soke-cli logs +path
+```
+
+登录后日志文件名会拼接当前应用、企业和用户身份，便于一台机器上多个身份并存时定位：
+
+```text
+~/.soke-cli/logs/cli_<app_id>_<corp_id>_<dept_user_id>.log
+```
+
+未登录或无法读取配置时，会回退到：
+
+```text
+~/.soke-cli/logs/soke-cli.log
+```
+
+### 收集诊断包
+
+当需要反馈问题给支持人员时，可以生成本地诊断包：
+
+```bash
+soke-cli logs +collect
+```
+
+默认输出到 `~/.soke-cli/support/`，只生成本地 zip 文件，不会自动发送。
+
+### 清理日志
+
+CLI 启动时会静默清理过期文件：日志默认保留 30 天，诊断包默认保留 14 天。也可以手动清理：
+
+```bash
+# 预览将清理哪些文件
+soke-cli logs +clean --dry-run
+
+# 清理 30 天前的日志和诊断包
+soke-cli logs +clean
+
+# 清理指定时间之前的文件
+soke-cli logs +clean --older-than 7d
+
+# 清理全部日志和诊断包，需要显式确认
+soke-cli logs +clean --all --yes
+```
+
+`logs +clean` 只清理日志文件和诊断包，不会删除配置、token 或 keychain。
+默认清理会保护当前正在写入的日志；`--all --yes` 会尝试清理全部日志文件。
+
+### 健康检查
+
+```bash
+soke-cli doctor --format json
+```
+
+`doctor` 会检查 CLI 版本、配置、登录态、日志目录和网络连通性。
+
+### 调试输出
+
+```bash
+soke-cli --verbose <command>
+soke-cli --debug <command>
+```
+
+`--verbose` 用于查看关键行为节点，`--debug` 会输出更详细的 HTTP 摘要。完整结构化日志仍以 JSON Lines 写入本地日志文件。
+
+更多日志字段、脱敏规则和开发规范见：[docs/LOGGING_GUIDE.md](docs/LOGGING_GUIDE.md)。
+
 ## 使用示例
 
 ### 调用快捷业务命令
@@ -649,6 +722,7 @@ soke-cli/
 
 - **[QUICKSTART.md](QUICKSTART.md)** - 快速开始指南
 - **[CLAUDE.md](CLAUDE.md)** - 项目架构和开发规范
+- **[docs/LOGGING_GUIDE.md](docs/LOGGING_GUIDE.md)** - 日志记录、查看和诊断包收集规范
 - **[docs/LOCAL_TESTING.md](docs/LOCAL_TESTING.md)** - 本地测试详细指南
 - **[skills/README.md](skills/README.md)** - AI Agent Skills 使用说明
 - **[npm.md](npm.md)** - NPM 包发布详细文档

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sokeai/cli",
-    "version": "1.0.67",
+    "version": "1.0.69",
     "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
     "bin": {
         "soke-cli": "scripts/run.js"

package/skills/README.md

@@ -37,6 +37,7 @@ npx skills add <org>/soke-cli --skill soke-exam -y -g
 cp -r skills/soke-shared ~/.claude/skills/
 cp -r skills/soke-exam ~/.claude/skills/
 cp -r skills/soke-training-demand ~/.claude/skills/
+cp -r skills/soke-task ~/.claude/skills/
 
 # 或复制到项目级skills目录
 mkdir -p .claude/skills
@@ -173,6 +174,7 @@ cp -r skills/soke-<module> ~/.claude/skills/
 - `soke-contact` - 组织架构（部门、用户、讲师）
 - `soke-training` - 培训管理
 - `soke-training-demand` - 培训需求收集
+- `soke-task` - 异步任务管理
 - `soke-credit` - 学分管理
 - `soke-certificate` - 证书管理
 - 等等...

package/skills/SKILL.md

@@ -2,7 +2,7 @@
 name: soke-cli
 summary: 授客AI CLI 全套 Skills 索引 — 安装指南与各业务模块能力总览
 version: 1.0.0
-description: "授客AI CLI（soke-cli）Skills 总索引：包含安装配置、认证登录，以及课程、考试、素材、课件、指派、学习地图、学习档案等全业务模块的 AI 快捷命令。当用户需要了解授客AI CLI 有哪些能力、从零开始使用、或不确定该调用哪个 skill 时使用。 | Soke AI CLI (soke-cli) skills master index: covers installation, configuration, authentication, and AI shortcut commands for all business modules including courses, exams, materials, lessons, assignments, learning maps, and learning records. Use when users need to understand what capabilities Soke AI CLI offers, get started from scratch, or are unsure which skill to invoke."
+description: "授客AI CLI（soke-cli）Skills 总索引：包含安装配置、认证登录，以及课程、考试、素材、课件、指派、学习地图、异步任务、学习档案等全业务模块的 AI 快捷命令。当用户需要了解授客AI CLI 有哪些能力、从零开始使用、或不确定该调用哪个 skill 时使用。 | Soke AI CLI (soke-cli) skills master index: covers installation, configuration, authentication, and AI shortcut commands for all business modules including courses, exams, materials, lessons, assignments, learning maps, async tasks, and learning records. Use when users need to understand what capabilities Soke AI CLI offers, get started from scratch, or are unsure which skill to invoke."
 metadata:
   requires:
     bins: ["soke-cli"]
@@ -70,9 +70,9 @@ metadata:
 
 ---
 
-### soke-examPool — 可练习题库查询
+### soke-exam-question-pool — 可练习题库查询
 
-**路径**: [soke-examPool/SKILL.md](./soke-examPool/SKILL.md)
+**路径**: [soke-exam-question-pool/SKILL.md](./soke-exam-question-pool/SKILL.md)
 
 按 `examQuestionPool` 接口链路查询可练习题库，严格遵循“题库列表 -> 题库详情 -> 题目列表”的参数依赖。
 
@@ -85,6 +85,19 @@ metadata:
 
 ---
 
+### soke-task — 异步任务管理
+
+**路径**: [soke-task/SKILL.md](./soke-task/SKILL.md)
+
+独立异步任务模块，支持创建和查询导出任务。目前用于学习地图学员统计导出。
+
+**核心能力**:
+- 创建异步导出任务（`soke-cli task +create`）
+- 支持选择部门导出类型：单列导出 `aloneDept`（默认）或部门多列导出 `manyDept`
+- 查询任务状态与导出文件地址（`soke-cli task +get`）
+
+---
+
 ### soke-assign — 指派管理
 
 **路径**: [soke-assign/SKILL.md](./soke-assign/SKILL.md)
@@ -194,7 +207,7 @@ soke-cli安装指南.md (所有 skill 的前置条件)
     └── soke-shared (认证/配置/权限基础)
             │
             ├── soke-exam
-            ├── soke-examPool
+            ├── soke-exam-question-pool
             ├── soke-assign
             ├── soke-learning-profile
             ├── soke-material
@@ -219,7 +232,7 @@ soke-cli安装指南.md (所有 skill 的前置条件)
 | 上传视频/音频/文档素材 | [soke-material](./soke-material/SKILL.md) |
 | 创建/管理课件 | [soke-lesson](./soke-lesson/SKILL.md) |
 | 创建/发布/查询考试、题库、试卷 | [soke-exam](./soke-exam/SKILL.md) |
-| 查询可练习题库详情和题目列表 | [soke-examPool](./soke-examPool/SKILL.md) |
+| 查询可练习题库详情和题目列表 | [soke-exam-question-pool](./soke-exam-question-pool/SKILL.md) |
 | 将课程/考试/地图指派给部门或用户 | [soke-assign](./soke-assign/SKILL.md) |
 | 创建/发布/查询学习地图 | [soke-learning-map](./soke-learning-map/SKILL.md) |
 | 查询学员学习档案/统计数据 | [soke-learning-profile](./soke-learning-profile/SKILL.md) |

package/skills/{soke-examPool → soke-exam-question-pool}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: soke-examPool
-summary: 授客可练习题库查询（题库列表、题库详情、题目列表），通过 soke-cli exam-pool 命令操作
+name: soke-exam-question-pool
+summary: 授客可练习题库查询（题库列表、题库详情、题目列表），通过 soke-cli exam-question-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"
+  cliHelp: "soke-cli exam-question-pool --help"
 ---
 
 # 可练习题库查询 (examQuestionPool)
@@ -36,7 +36,7 @@ metadata:
 获取可练习题库列表。
 
 ```bash
-soke-cli exam-pool +list \
+soke-cli exam-question-pool +list \
   --page 1 \
   --page-size 10 \
   --status 1 \
@@ -63,7 +63,7 @@ soke-cli exam-pool +list \
 根据题库 UUID 获取可练习题库详情。
 
 ```bash
-soke-cli exam-pool +get \
+soke-cli exam-question-pool +get \
   --pool-id "<上一步 data.list[].uuid>" \
   --format json
 ```
@@ -89,7 +89,7 @@ soke-cli exam-pool +get \
 根据同一个题库 UUID 获取题目明细。
 
 ```bash
-soke-cli exam-pool +questions \
+soke-cli exam-question-pool +questions \
   --pool-id "<同一个题库 uuid>" \
   --format json
 ```
@@ -114,11 +114,11 @@ soke-cli exam-pool +questions \
 
 ```bash
 # 1. 查询题库列表，取 data.list[0].uuid
-soke-cli exam-pool +list --page 1 --page-size 10 --status 1 --format json
+soke-cli exam-question-pool +list --page 1 --page-size 10 --status 1 --format json
 
 # 2. 查询题库详情
-soke-cli exam-pool +get --pool-id "<pool_uuid>" --format json
+soke-cli exam-question-pool +get --pool-id "<pool_uuid>" --format json
 
 # 3. 查询同一题库的题目
-soke-cli exam-pool +questions --pool-id "<pool_uuid>" --format json
+soke-cli exam-question-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。当用户需要创建学习地图、添加阶段和课程内容、发布地图、指派学员、查询学习进度时使用。 | 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. Use when users need to create learning maps, add stages and course content, publish maps, assign learners, or query learning progress."
+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-task/SKILL.md

@@ -0,0 +1,104 @@
+---
+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`，`--type` 默认 `aloneDept`。
+
+## 命令
+
+### 创建学习地图学员统计导出任务
+
+```bash
+soke-cli task +create \
+  --map-id "MAP-UUID" \
+  --learn-type "required" \
+  --type "aloneDept" \
+  --custom-tags "工号,职位,部门" \
+  --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` |
+| `--type` | 否 | `aloneDept` | 部门导出类型：`aloneDept` 单列导出，`manyDept` 部门多列导出 |
+| `--custom-tags` | 否 | 空 | 导出的自定义字段列表，多个字段用英文逗号分隔；也可传 JSON 字符串数组 |
+
+响应关键字段：
+
+| 字段 | 说明 |
+|------|------|
+| `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" \
+  --type "aloneDept" \
+  --custom-tags "工号,岗位,入职日期" \
+  --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` 后重试。
+- 自定义字段没有导出：确认已通过 `--custom-tags "字段1,字段2"` 指定，字段名需与学习地图学员统计支持的自定义字段一致。
+- 任务创建失败：确认 `--map-id` 是有效学习地图 UUID，`--module learningMapUser`，`--action export`，`--type aloneDept` 或 `--type manyDept`。

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

@@ -15,7 +15,8 @@ metadata:
 
 ## 核心规则
 
-- 提交需求前，先执行 `+list-categories`，使用返回的分类 `uuid` 和 `title`。
+- 提交需求前，先执行 `+list-categories`，使用返回的分类 `uuid`、`title` 和 `tag`。
+- 创建需求的 `--tag` 不是自由填写，必须从所选分类返回的 `tag` 字段中选择；多个分类时合并这些分类的 tag 值。
 - 投票前，先执行 `+list`，使用返回的培训需求 `uuid`。不要把分类 `uuid` 传给投票接口。
 - 创建和投票是写操作。用户意图不明确时，先确认要提交或投票的对象。
 - 默认用 `--format json` 获取结构化输出；需要人工快速查看时可省略 format 输出表格。
@@ -44,30 +45,32 @@ soke-cli training-demand +list \
 soke-cli training-demand +list-categories --format json
 ```
 
-分类返回的 `data.list[].uuid` 和 `data.list[].title` 只用于创建需求。
+分类返回的 `data.list[].uuid`、`data.list[].title` 和 `data.list[].tag` 只用于创建需求。
 
 ### 提交培训需求
 
 推荐从分类列表提取分类后，用分类 UUID 和名称提交：
 
+`--title` 是培训需求描述；`--tag` 必须来自所选分类返回的 `tag`；`--level` 是培训需求等级，可省略，默认 `0`。用户指定等级时只能使用 `1-5`。
+
 ```bash
 soke-cli training-demand +create \
   --title "门店销售沟通训练" \
-  --tag "销售,沟通" \
+  --tag "职场心态,需求测试" \
   --level 0 \
   --category-uuid "FA0C937C-EE52-463B-BE3A-C13F96C426AE" \
   --category-title "新建培训需求测试" \
+  --category-tag "职场心态,新建培训需求测试,新建培训需求,需求测试,培训需求测试,企业新建培训需求测试" \
   --format json
 ```
 
-多分类或已有完整分类数组时，使用 `--category-list`：
+不传 `--tag` 时，CLI 会从 `--category-tag` 自动合并标签。多分类或已有完整分类数组时，使用 `--category-list`，推荐把分类返回的 `tag` 一并带上：
 
 ```bash
 soke-cli training-demand +create \
   --title "新员工产品知识培训" \
-  --tag "产品,新员工" \
-  --level 0 \
-  --category-list '[{"uuid":"FA0C937C-EE52-463B-BE3A-C13F96C426AE","title":"新建培训需求测试"}]' \
+  --level 1 \
+  --category-list '[{"uuid":"FA0C937C-EE52-463B-BE3A-C13F96C426AE","title":"新建培训需求测试","tag":"职场心态,新建培训需求测试,新建培训需求,需求测试,培训需求测试,企业新建培训需求测试"}]' \
   --format json
 ```
 
@@ -84,9 +87,9 @@ soke-cli training-demand +vote \
 ## 常见工作流
 
 1. 用户说“我想提一个培训需求”：
-   - 先问清楚标题、标签、分类偏好和等级。
+   - 先问清楚培训需求描述和分类偏好；等级没说明时使用默认 `0`。
    - 执行 `+list-categories --format json`。
-   - 匹配或让用户选择分类。
+   - 匹配或让用户选择分类，并从所选分类的 `tag` 中确定标签；用户未指定具体标签时，直接使用所选分类的全部 tag。
    - 执行 `+create`。
 
 2. 用户说“帮我给某个需求投票”：
@@ -102,11 +105,12 @@ soke-cli training-demand +vote \
 
 | 场景 | 依赖字段 | 来源 |
 |------|----------|------|
-| 创建需求 | `category_list[].uuid` / `category_list[].title` | `+list-categories` 的 `data.list[]` |
+| 创建需求 | `category_list[].uuid` / `category_list[].title` / `tag` | `+list-categories` 的 `data.list[]` |
 | 投票 | `uuid` | `+list` 的 `data.list[].uuid` |
 
 ## 排错
 
 - 创建失败提示分类无效：重新执行 `+list-categories`，不要使用需求列表中的分类名称手写 UUID。
+- 创建失败提示标签无效：重新执行 `+list-categories`，从所选分类返回的 `tag` 中选择，不要自行编写标签。
 - 投票失败提示需求无效：确认传入的是培训需求 UUID，不是分类 UUID。
 - 鉴权失败：按 `soke-shared` 执行 `soke-cli auth login` 后重试。