@sokeai/cli 1.0.76 → 1.0.78

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

package/skills/multi/soke-course/references/intent-cases.md

@@ -0,0 +1,99 @@
+# 意图识别案例库
+
+## create（创建课程）
+
+| # | 用户输入 | 提取 | 上下文 | 路由 |
+|---|---------|------|--------|------|
+| 1 | "帮我创建一门Python数据分析的线上课，放技术培训分类里" | title=Python数据分析, category=技术培训 | 无 course-id | Phase 1 |
+| 2 | "做课：新员工入职培训" | title=新员工入职培训 | 无 course-id | Phase 1（需补充分类） |
+| 3 | "新建一门课" | — | 无 course-id | Phase 1（需补充标题+分类） |
+| 4 | "开课：产品知识" | title=产品知识 | 无 course-id | Phase 1（需补充分类） |
+| 5 | "帮我生成一门关于安全培训的课程" | title=安全培训 | 无 course-id | Phase 1 |
+
+## add_lesson（添加课件）
+
+| # | 用户输入 | 提取 | 上下文 | 路由 |
+|---|---------|------|--------|------|
+| 6 | "给这门课加个视频" + video.mp4 | type=video, file=video.mp4 | course-id 已知 | Phase 2 |
+| 7 | "上传课件" + lesson.pdf | type=document, file=lesson.pdf | course-id 已知 | Phase 2 |
+| 8 | "再传一个音频" + lecture.mp3 | type=audio, file=lecture.mp3 | course-id 已知 | Phase 2 |
+| 9 | "课件排序调整一下" | sort | course-id 已知 | Phase 2 Step 2.5 |
+| 10 | "第一个和第三个课件换一下位置" | sort | course-id 已知 | Phase 2 Step 2.5 |
+
+## settings（设置）
+
+| # | 用户输入 | 提取 | 路由 |
+|---|---------|------|------|
+| 11 | "设置学分 10 分" | credit=10 | Phase 3 |
+| 12 | "修改一下课程描述" | description | Phase 3 |
+| 13 | "把讲师改成张三" | lector=张三 | Phase 3（⚠️ CLI 不支持） |
+| 14 | "换个封面" | cover | Phase 3（⚠️ CLI 不支持） |
+| 15 | "加几个标签" | tags | Phase 3（⚠️ CLI 不支持） |
+
+## advanced（高级设置）
+
+| # | 用户输入 | 提取 | 路由 |
+|---|---------|------|------|
+| 16 | "开启倍速" | is_accelerate=1 | Phase 3（course +advanced） |
+| 17 | "改成解锁式学习" | study_type=2 | Phase 3（course +advanced） |
+| 18 | "开启人脸识别" | open_face_recognition=1 | Phase 3（course +advanced） |
+| 19 | "设置未学提醒，每周推送" | is_remind=1, remind_days=7 | Phase 3（course +advanced） |
+| 20 | "关联证书" | certificate | Phase 3（⚠️ 不支持） |
+
+## charge（收费）
+
+| # | 用户输入 | 提取 | 路由 |
+|---|---------|------|------|
+| 21 | "设置收费 99 元" | charge, price=99 | Phase 3（⚠️ 不支持） |
+| 22 | "开启试看，前两个课件免费" | trial, trial_lessons=2 | Phase 3（⚠️ 不支持） |
+
+## publish（发布）
+
+| # | 用户输入 | 提取 | 路由 |
+|---|---------|------|------|
+| 23 | "发布课程" | publish | Phase 4 |
+| 24 | "上线吧" | publish | Phase 4 |
+| 25 | "定时发布，下周一早上9点" | scheduled, publish_time | Phase 4 |
+| 26 | "提交审批" | approval | Phase 4（⚠️ 不支持） |
+
+## assign（指派）
+
+| # | 用户输入 | 提取 | 路由 |
+|---|---------|------|------|
+| 27 | "指派给研发部" | dept=研发部 | Phase 5 |
+| 28 | "安排张三学习" | user=张三 | Phase 5 |
+| 29 | "全员必修" | compulsory=1, all | Phase 5 |
+| 30 | "设为选修课" | compulsory=0 | Phase 5 |
+
+## query（查询）
+
+| # | 用户输入 | 提取 | 路由 |
+|---|---------|------|------|
+| 31 | "看看学习进度" | progress | Phase 6 |
+| 32 | "谁学完了" | completed | Phase 6 |
+| 33 | "完成率多少" | completion_rate | Phase 6 |
+| 34 | "张三学到哪了" | user=张三 | Phase 6 |
+
+## maintain（维护）
+
+| # | 用户输入 | 提取 | 路由 |
+|---|---------|------|------|
+| 35 | "关闭这门课" | close | Phase 6（course +update --action close） |
+| 36 | "删除课程" | delete | Phase 6（先查 status，仅 0/2 可删） |
+| 37 | "复制这门课，叫 V2.0" | copy, title=V2.0 | Phase 6（⚠️ 不支持） |
+| 38 | "批量发布这几门" | batch, publish | Phase 6（⚠️ 不支持） |
+
+## 歧义消解案例
+
+| # | 用户输入 | 情况 | 处理 |
+|---|---------|------|------|
+| 39 | "上传一下" | 没有课程上下文，没有附件 | 询问: 你要上传课件到哪门课？还是先创建新课程？ |
+| 40 | "帮我看看" | 没有课程上下文 | 列课程列表让用户选 |
+| 41 | "设置一下" | 有 course-id 但不清楚要设什么 | 列设置选项：基础设置/高级设置/收费设置 |
+
+## 关键提取规则
+
+1. **有 course-id 上下文** → 在当前课程操作，不创建新课程
+2. **有文件附件** → 倾向课件上传意图
+3. **无 course-id + 无附件 + 无明确操作** → 列出课程让用户选
+4. **创建词 + 无 course-id** → 走 Phase 1 全流程