@sokeai/cli 1.0.77 → 1.0.78

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

@@ -0,0 +1,221 @@
+---
+name: soke-learning-profile
+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"]
+  cliHelp: "soke-cli learning-profile --help"
+---
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`./references/shared.md`](./references/shared.md)，其中包含认证、配置、权限处理**
+
+## 核心概念
+
+- **LearningProfile（学习档案）**: 学员的完整学习记录，包含课程、考试、证书、培训等多维度数据
+- **DeptUser（部门用户）**: 企业内的学员，通过 `dept_user_id` 标识
+- **Department（部门）**: 组织架构单元，通过 `dept_id` 标识
+
+## 资源关系
+
+```
+LearningProfile (学习档案)
+├── DeptUser (学员)
+│   ├── dept_user_id (学员ID)
+│   ├── dept_user_name (学员姓名)
+│   └── dept_names (所属部门)
+├── CourseData (课程数据)
+│   ├── required_learning/finished (必修课程)
+│   ├── optional_learning/finished (选修课程)
+│   └── learn_time (学习时长)
+├── ExamData (考试数据)
+│   ├── not_attempt (未开始)
+│   ├── passed (通过)
+│   ├── notpassed (未通过)
+│   └── reviewing (批阅中)
+├── CertificateData (证书数据)
+│   └── certificate_number (证书数量)
+├── PointsAndCredits (积分学分)
+│   ├── points (积分)
+│   └── credits (学分)
+└── TrainingData (培训数据)
+    ├── training_finished (线下培训)
+    ├── learning_map_finished (学习地图)
+    └── training_class_finished (培训班)
+```
+
+## Shortcuts（推荐优先使用）
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+list`](#list) | 查询学员学习档案列表 |
+
+## 辅助命令（contact 模块）
+
+| Shortcut | 说明 |
+|----------|------|
+| `contact +search-user` | 根据姓名搜索学员 |
+| `contact +search-dept` | 根据名称搜索部门 |
+
+---
+
+## 命令详解
+
+### +list
+
+查询学员学习档案列表，支持按部门、学员ID筛选。
+
+**命令格式**:
+```bash
+soke-cli learning-profile +list \
+  [--dept-user-ids <user_id1,user_id2,...>] \
+  [--dept-ids <dept_id1,dept_id2,...>] \
+  [--is-new <0|1>] \
+  [--offset <offset>] \
+  [--page-size <size>]
+```
+
+**参数说明**:
+- `--dept-user-ids`: 学员ID列表，多个ID用逗号分隔（可选）
+- `--dept-ids`: 部门ID列表，多个ID用逗号分隔（可选）
+- `--is-new`: 是否新员工，0-否，1-是（可选）
+- `--offset`: 偏移量，默认从0开始（可选）
+- `--page-size`: 每页条数，最大100，默认10（可选）
+
+**返回字段**（表格显示关键字段）:
+- `姓名`: 学员姓名
+- `部门`: 所属部门
+- `职位`: 职位
+- `必修完成`: 必修课程完成情况（完成数/总数）
+- `选修完成`: 选修课程完成情况（完成数/总数）
+- `考试通过`: 考试通过数
+- `学习时长`: 学习时长（格式化为"X小时Y分钟"）
+- `证书数`: 获得证书数量
+- `学分`: 学分
+- `积分`: 积分
+
+**JSON 输出包含完整字段**（30+ 字段）:
+- 基础信息：`dept_user_id`, `dept_user_name`, `dept_names`, `position`, `job_number`, `avatar`, `is_leave`, `hired_date`
+- 课程学习：`optional_learning`, `optional_finished`, `required_learning`, `required_finished`, `learn_time`
+- 考试情况：`not_attempt`, `passed`, `notpassed`, `reviewing`
+- 证书积分：`certificate_number`, `points`, `credits`
+- 培训情况：`training_not_attempt`, `training_finished`, `class_length`
+- 学习地图：`leaning_map_attempt`, `learning_map_finished`
+- 培训班：`training_class_attempt`, `training_class_finished`
+- 其他：`live_learn_time`, `external_training_time`, `knowledge_number`, `evaluation_score`
+
+**示例**:
+```bash
+# 查询所有学员学习档案
+soke-cli learning-profile +list --offset 0 --page-size 20
+
+# 查询特定学员（单个）
+soke-cli learning-profile +list --dept-user-ids user123
+
+# 查询多个学员
+soke-cli learning-profile +list --dept-user-ids user123,user456,user789
+
+# 查询特定部门的学员
+soke-cli learning-profile +list --dept-ids dept456
+
+# 查询多个部门的学员
+soke-cli learning-profile +list --dept-ids dept456,dept789
+
+# 查询新员工的学习档案
+soke-cli learning-profile +list --is-new 1 --page-size 50
+
+# 分页查询（使用 offset）
+soke-cli learning-profile +list --offset 0 --page-size 10   # 第1页
+soke-cli learning-profile +list --offset 10 --page-size 10  # 第2页
+soke-cli learning-profile +list --offset 20 --page-size 10  # 第3页
+```
+
+**权限要求**: `learningProfile:readonly`
+
+**使用场景**:
+- 当用户询问"查询学员学习档案"时使用
+- 当用户需要查看学员学习情况、统计学习数据时使用
+- 当用户需要导出学员学习报表时使用
+
+---
+
+## 权限表
+
+| 命令 | 所需权限 | 说明 |
+|------|----------|------|
+| `+list` | `learningProfile:readonly` | 查询学员学习档案 |
+| `contact +search-user` | `contact:user:readonly` | 搜索学员 |
+| `contact +search-dept` | `contact:department:readonly` | 搜索部门 |
+
+---
+
+## 常见工作流
+
+### 工作流1: 根据姓名查询学员学习档案
+
+当用户询问"查询张三的学习档案"时：
+
+**步骤1**: 搜索学员获取 dept_user_id
+```bash
+soke-cli contact +search-user --dept-user-name "张三"
+```
+
+**步骤2**: 使用 dept_user_id 查询学习档案
+```bash
+soke-cli learning-profile +list --dept-user-ids <从步骤1获取的dept_user_id>
+```
+
+**注意**: 学习档案接口不支持按姓名直接查询，必须先通过 contact 模块获取 dept_user_id。
+
+### 工作流2: 查询部门所有学员的学习档案
+
+当用户询问"查询技术部所有学员的学习情况"时：
+
+**步骤1**: 搜索部门获取 dept_id
+```bash
+soke-cli contact +search-dept --dept-name "技术部"
+```
+
+**步骤2**: 使用 dept_id 查询该部门学员学习档案
+```bash
+soke-cli learning-profile +list --dept-ids <从步骤1获取的dept_id> --page-size 100
+```
+
+### 工作流3: 批量导出学习档案
+
+当用户需要导出学习档案数据时：
+
+```bash
+# 使用 JSON 格式输出并保存到文件
+soke-cli learning-profile +list --page-size 100 --format json > learning_profiles.json
+```
+
+---
+
+## 注意事项
+
+1. **时间格式**: `learn_time`, `class_length` 等时长字段单位为秒，表格输出时会自动格式化为"X小时Y分钟"
+2. **分页**: 使用 `offset` 和 `page_size` 进行分页，默认每页10条，最大100条
+3. **数组参数**: `dept_user_ids` 和 `dept_ids` 是数组类型，多个ID用逗号分隔
+4. **姓名查询**: 学习档案接口不支持按姓名查询，需要先通过 `contact +search-user` 获取 dept_user_id
+5. **权限**: 需要 `learningProfile:readonly` 权限，如遇权限错误参考 soke-shared
+6. **数据完整性**: 表格输出仅显示关键字段，完整数据请使用 `--format json`
+
+---
+
+## 错误处理
+
+### 权限不足
+如果遇到权限错误，参考 [`./references/shared.md`](./references/shared.md)
+
+### 参数错误
+使用 `--help` 查看命令参数说明：
+```bash
+soke-cli learning-profile +list --help
+```
+
+### 数据为空
+如果查询结果为空，检查：
+1. 筛选条件是否正确（dept_ids, dept_user_ids, is_new）
+2. 学员是否有学习记录
+3. 是否有权限查看该部门/学员的数据
+4. 注意：学习档案接口不支持按姓名查询，需要先获取 dept_user_id

package/skills/multi/soke-learning-profile/references/installation.md

@@ -0,0 +1,451 @@
+# 授客CLI 工具 - 快速上手指南
+
+本文档将指导你从零开始安装 `soke-cli`，完成用户登录授权，并开始使用授客AI开放平台的各项功能。
+
+---
+
+## 📋 目录
+
+- [前置要求](#前置要求)
+- [安装步骤](#安装步骤)
+- [用户登录授权](#用户登录授权)
+- [验证安装](#验证安装)
+- [常见问题](#常见问题)
+- [下一步](#下一步)
+
+---
+
+## 前置要求
+
+在开始之前，请确保你的系统满足以下要求：
+
+### 必需条件
+- **Node.js**: 版本 >= 14.0.0（用于 NPM 安装）
+- **网络连接**: 能够访问授客AI开放平台 API（默认：`https://opendev.soke.cn`）
+- **浏览器**: 用于完成 OAuth 授权流程
+
+> 💡 **提示**: 使用 `soke-cli` 无需预先配置任何凭证，所有配置将在登录授权过程中自动完成。
+
+---
+
+## 安装步骤
+
+> ⚠️ **先看这里**：以下步骤会将 `soke-cli` 安装到用户专属目录（`~/.npm-global`），无需 sudo、不依赖任何 AI 工具，任何终端打开即用。
+> 
+> **三步走：① 改 npm prefix → ② 加 PATH → ③ 安装**
+
+### 第一步：配置 npm prefix（所有平台通用）
+
+设置 npm 全局安装路径为用户专属目录，这样：
+- **不需要 sudo/管理员权限**
+- **不会装到奇怪的系统目录**
+- **任何终端都能找到**
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+```
+
+> 💡 这一步只需执行一次，之后所有通过 `npm install -g` 安装的工具都会放到统一位置。
+
+---
+
+### 第二步：把 npm 全局 bin 目录加入 PATH
+
+把 `~/.npm-global/bin` 加入 shell 搜索路径，这样终端才能找到 `soke-cli`。
+
+#### macOS / Linux
+
+在 `~/.zshrc`（Zsh）或 `~/.bashrc`（Bash）末尾追加一行：
+
+```bash
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+> 💡 **Apple Silicon (M1/M2/M3) 用户**如果用 Homebrew 安装 Node.js，npm prefix 可能已指向 `/opt/homebrew`（arm64）或 `/usr/local`（x64）。上述 `npm config set prefix` 会覆盖默认值，所有全局工具统一走 `~/.npm-global`，不影响 Homebrew 自有工具。
+
+#### Windows
+
+**PowerShell**：
+```powershell
+# 查看当前用户 PATH
+[Environment]::GetEnvironmentVariable('Path', 'User')
+
+# 追加 npm-global 路径
+$npmGlobal = "$env:USERPROFILE\.npm-global\bin"
+[Environment]::SetEnvironmentVariable('Path', "$(([Environment]::GetEnvironmentVariable('Path', 'User') -split ';' -notlike '' -join ';'));$npmGlobal", 'User')
+
+# 验证（需要重新打开 PowerShell 使改动生效，或手动刷新）
+$env:Path = [Environment]::GetEnvironmentVariable('Path', 'User')
+```
+
+**CMD**：
+```cmd
+setx PATH "%PATH%;%USERPROFILE%\.npm-global\bin"
+```
+
+> ⚠️ **Windows**: `setx` 修改的是**系统环境变量**，需要新的 CMD/PowerShell 窗口才能生效（当前窗口不会变）。
+
+---
+
+### 第三步：安装 soke-cli
+
+PATH 配置完成后，新开一个终端窗口（或 `source` 刚改的文件），然后安装：
+
+**macOS / Linux**：
+```bash
+npm install -g @sokeai/cli@latest
+```
+
+**Windows (PowerShell / CMD)**：
+```powershell
+npm install -g @sokeai/cli@latest
+```
+
+> 💡 安装脚本会自动根据操作系统（macOS / Linux / Windows）和芯片架构（x64 / arm64）下载对应二进制文件，无需手动选择。
+
+---
+
+### 安装后验证
+
+新开一个终端（让 PATH 生效），依次执行：
+
+```bash
+# 确认路径
+which soke-cli
+# 预期输出类似: /Users/你的用户名/.npm-global/bin/soke-cli
+
+# 确认版本
+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` 有输出，若没有请重新执行第二步
+- Windows: 确认环境变量中已添加 `C:\Users\你的用户名\.npm-global\bin`
+
+---
+
+## 用户登录授权
+
+安装完成后，直接执行登录命令即可开始使用。无需预先配置，所有必要的配置信息将在授权过程中自动获取并保存。
+
+### OAuth 浏览器授权流程
+
+`soke-cli` 使用 OAuth 2.0 授权码流程（Authorization Code Flow），通过浏览器完成安全授权。
+
+### 执行登录命令
+
+```bash
+soke-cli auth login
+```
+
+### 授权步骤
+
+1. **自动打开浏览器**
+   
+   命令执行后，会自动在默认浏览器中打开授权页面。如果浏览器没有自动打开，会显示授权链接：
+   ```
+   ℹ️  未找到登录信息，开始授权流程
+   
+   请在浏览器中打开以下链接进行授权:
+   http://127.0.0.1:8080/callback?redirect_uri=...
+   
+   等待授权中...
+   ```
+
+2. **浏览器授权**
+   
+   在浏览器授权页面中：
+   - 如果未登录授客AI平台，先完成登录
+   - 查看应用请求的权限列表
+   - 勾选"一并开通审批的常用权限"（可选）
+   - 点击"开通并授权"按钮
+
+3. **授权成功**
+   
+   授权完成后，浏览器会显示成功页面，CLI 终端会显示：
+   ```
+   ✅ 已登录，Token 仍然有效
+   企业 ID: corp_123456
+   ```
+
+4. **配置自动保存**
+   
+   授权成功后，以下信息会自动保存到 `~/.soke-cli/config.json`：
+   - 用户访问令牌（`user_token`）
+   - 企业 ID（`corpid`）
+   - 部门用户 ID（`dept_user_id`）
+   - Token 过期时间
+
+### Token 有效期
+
+- **访问令牌（Access Token）**: 默认有效期根据平台设置，通常为数小时到数天
+- **自动检查**: 每次执行命令时，CLI 会自动检查 Token 是否有效
+- **自动续期**: Token 过期后，再次执行 `soke-cli auth login` 即可重新授权
+
+### 强制重新登录
+
+如果需要切换账号或强制重新授权，可以使用 `--force` 参数：
+
+```bash
+soke-cli auth login --force
+```
+
+### 退出登录
+
+如果需要退出登录，清除本地保存的令牌：
+
+```bash
+soke-cli auth logout
+```
+
+输出：
+```
+✓ 已退出登录
+```
+
+---
+
+## 验证安装
+
+完成登录授权后，让我们验证一切是否正常工作。推荐先运行 `doctor`，它会一次性检查 CLI 版本、配置文件、登录态、日志目录和网络连通性。
+
+### 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
+```
+
+确认配置信息已自动保存：
+```
+当前配置:
+  app_key: (未设置)
+  app_secret: (未设置)
+  api_base_url: 
+  corpid: corp_123456
+  用户ID: user_789012
+  用户凭证: eyJh...xyz
+  token过期时间: 2026-10-17 12:00:00
+```
+
+> 💡 **说明**: `app_key` 和 `app_secret` 在当前版本中不需要手动配置，授权流程会自动处理所有必要的认证信息。如果 `doctor` 已全部通过，这一步主要用于人工确认当前登录的企业和用户信息。
+
+### 3. 测试 API 调用
+
+尝试调用一个简单的 API：
+
+```bash
+soke-cli api GET /users/me
+```
+
+如果返回你的用户信息（JSON 格式），说明一切配置正确！
+
+### 4. 使用业务命令
+
+尝试使用一个业务快捷命令，例如查看考试列表：
+
+```bash
+soke-cli exam +list-exams --page 1 --page-size 10
+```
+
+---
+
+## 常见问题
+
+### Q1: 安装时提示 "网络连接失败"
+
+**原因**: 无法从 GitHub Releases 下载二进制文件。
+
+**解决方案**:
+1. 检查网络连接
+2. 如果在国内，可能需要配置代理
+3. 尝试重新安装：`npm install -g @sokeai/cli`
+
+### Q2: 执行 `soke-cli` 提示 "command not found" 或 "不是内部或外部命令"
+
+**原因**: 二进制文件不在系统 PATH 中。
+
+**解决方案（重新做安装步骤第二步）**:
+
+**macOS / Linux**：
+```bash
+# 确认 npm-global/bin 是否已在 PATH
+which soke-cli
+
+# 若无输出，检查路径是否存在
+ls ~/.npm-global/bin/soke-cli 2>/dev/null && echo "存在，但 PATH 未生效"
+
+# 重新追加 PATH 并生效
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+# 再次验证
+which soke-cli
+soke-cli --version
+```
+
+**Windows**：
+```powershell
+# 检查 .npm-global/bin 是否存在
+Test-Path "$env:USERPROFILE\.npm-global\bin\soke-cli.exe"
+
+# 若存在但命令找不到，手动刷新 PATH
+$env:Path = [Environment]::GetEnvironmentVariable('Path', 'User')
+
+# 确认
+where.exe soke-cli
+```
+
+**直接运行（临时方案，不推荐长期使用）**：
+
+**macOS / Linux**：
+```bash
+~/.npm-global/bin/soke-cli --version
+```
+
+**Windows**：
+```cmd
+%USERPROFILE%\.npm-global\bin\soke-cli.exe --version
+```
+
+### Q3: 登录时浏览器没有自动打开
+
+**原因**: 系统无法自动打开默认浏览器。
+
+**解决方案**:
+1. 复制终端显示的授权链接
+2. 手动在浏览器中打开该链接
+3. 完成授权流程
+
+### Q4: 浏览器授权后，CLI 仍显示 "等待授权中..."
+
+**原因**: 
+- 浏览器授权未成功完成
+- 本地回调服务器端口被占用
+- 网络连接问题
+
+**解决方案**:
+1. 确认浏览器页面显示"授权成功"
+2. 检查防火墙是否阻止了本地端口（127.0.0.1）
+3. 按 `Ctrl+C` 取消，重新执行 `soke-cli auth login`
+
+### Q5: API 调用返回 "401 Unauthorized"
+
+**原因**: Token 已过期或无效。
+
+**解决方案**:
+```bash
+# 重新登录
+soke-cli auth logout
+soke-cli auth login
+```
+
+### Q6: 如何在 AI Agent 中使用？
+
+**解决方案**:
+
+安装 AI Agent Skills：
+```bash
+npx skills add liuchenlong1111/soke-cli -y -g
+```
+
+然后在 AI Agent（如 Claude Code）中直接用自然语言：
+- "查询考试成绩"
+- "列出最近的考试"
+
+AI 会自动调用相应的 `soke-cli` 命令。
+
+---
+
+## 下一步
+
+恭喜！你已经成功安装并配置了 `soke-cli`。接下来你可以：
+
+### 📚 学习更多命令
+
+查看所有可用命令：
+```bash
+soke-cli --help
+```
+
+查看特定模块的命令：
+```bash
+soke-cli course --help
+soke-cli exam --help
+soke-cli contact --help
+```
+
+### 🚀 使用业务功能
+
+- **课程管理**: `soke-cli course +list-courses`
+- **考试管理**: `soke-cli exam +list-exams`
+- **通讯录**: `soke-cli contact +list-users`
+- **学习地图**: `soke-cli learning-map +list-maps`
+
+### 🤖 安装 AI Agent Skills（推荐）
+
+```bash
+npx skills add liuchenlong1111/soke-cli -y -g
+```
+
+安装后，在 AI Agent 中可以用自然语言操作授客AI平台，无需记忆复杂命令。
+
+### 📖 阅读详细文档
+
+
+---
+
+## 获取帮助
+
+如果遇到问题：
+
+1. **查看帮助文档**: `soke-cli --help`
+2. **查看配置**: `soke-cli config show`
+3. **访问开放平台**: https://opendev.soke.cn
+4. **提交 Issue**: https://github.com/liuchenlong1111/soke-cli/issues
+
+---
+
+**祝你使用愉快！** 🎉