@sokeai/cli 1.0.68 → 1.0.70

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.68",
+    "version": "1.0.70",
     "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
     "bin": {
         "soke-cli": "scripts/run.js"

package/skills/SKILL.md

@@ -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` 接口链路查询可练习题库，严格遵循“题库列表 -> 题库详情 -> 题目列表”的参数依赖。
 
@@ -93,6 +93,7 @@ metadata:
 
 **核心能力**:
 - 创建异步导出任务（`soke-cli task +create`）
+- 支持选择部门导出类型：单列导出 `aloneDept`（默认）或部门多列导出 `manyDept`
 - 查询任务状态与导出文件地址（`soke-cli task +get`）
 
 ---
@@ -206,7 +207,7 @@ soke-cli安装指南.md (所有 skill 的前置条件)
     └── soke-shared (认证/配置/权限基础)
             │
             ├── soke-exam
-            ├── soke-examPool
+            ├── soke-exam-question-pool
             ├── soke-assign
             ├── soke-learning-profile
             ├── soke-material
@@ -231,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-task/SKILL.md

@@ -18,7 +18,7 @@ metadata:
 - 任务接口是独立模块，命令统一使用 `soke-cli task ...`，不要使用 `soke-cli learning-map ...` 创建或查询任务。
 - 创建任务后必须保存返回的 `data.id`，再调用 `+get` 查询任务详情。
 - 默认用 `--format json` 获取结构化输出；需要人工快速查看时可省略 format 输出表格。
-- 当前已知任务类型是学习地图学员统计导出，`--module` 默认 `learningMapUser`，`--action` 默认 `export`。
+- 当前已知任务类型是学习地图学员统计导出，`--module` 默认 `learningMapUser`，`--action` 默认 `export`，`--type` 默认 `aloneDept`。
 
 ## 命令
 
@@ -28,6 +28,8 @@ metadata:
 soke-cli task +create \
   --map-id "MAP-UUID" \
   --learn-type "required" \
+  --type "aloneDept" \
+  --custom-tags "job_number,position" \
   --limit 4500 \
   --format json
 ```
@@ -43,6 +45,8 @@ soke-cli task +create \
 | `--eligible-status` | 否 | 空 | 达标状态筛选，空值表示不限 |
 | `--limit` | 否 | `4500` | 任务处理上限 |
 | `--action` | 否 | `export` | 操作类型，导出任务固定为 `export` |
+| `--type` | 否 | `aloneDept` | 部门导出类型：`aloneDept` 单列导出，`manyDept` 部门多列导出 |
+| `--custom-tags` | 否 | 空 | 导出的自定义字段列表，多个字段用英文逗号分隔；也可传 JSON 字符串数组 |
 
 响应关键字段：
 
@@ -77,6 +81,8 @@ soke-cli task +get --id "TASK-ID" --format json
 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')
 
@@ -94,4 +100,5 @@ soke-cli task +get --id "$TASK_ID" --format json | jq -r '.data.filePath'
 
 - `data.filePath` 为空：任务可能还未完成，等待后重新执行 `task +get --id "TASK-ID" --format json`。
 - `未登录授权`：按 `soke-shared` 执行 `soke-cli auth login` 后重试。
-- 任务创建失败：确认 `--map-id` 是有效学习地图 UUID，`--module learningMapUser`，`--action export`。
+- 自定义字段没有导出：确认已通过 `--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` 后重试。