@sokeai/cli 1.0.76 → 1.0.78

package/skills/multi/soke-certificate/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-certificate/references/shared.md

@@ -0,0 +1,185 @@
+---
+name: soke-shared
+summary: 授客CLI共享基础（配置/登录/权限/错误处理/安全规则）
+version: 1.0.0
+description: "授客CLI共享基础：应用配置初始化、认证登录（auth login）、权限管理、错误处理、安全规则。当用户需要第一次配置（soke-cli auth login）、使用登录授权（soke-cli auth login）、遇到权限不足、或首次使用soke-cli时触发。"
+---
+
+# soke-cli 共享规则
+
+本技能指导你如何通过soke-cli操作授客AI资源，以及有哪些注意事项。
+
+## 配置初始化
+
+首次使用需运行 `soke-cli auth login` 完成应用配置。
+
+当你帮用户初始化配置时，引导用户按照交互式提示完成配置：
+
+```bash
+# 初始化配置
+soke-cli auth login
+```
+
+配置项包括：
+- `app_id`: 开放平台应用ID
+- `app_key`: 开放平台应用Key
+- `app_secret`: 开放平台应用Secret
+- `api_base_url`: API地址（默认: https://opendev.soke.cn）
+- `corpid`: 企业ID
+
+配置文件保存在 `~/.soke-cli/config.json`
+
+## 认证
+
+### 用户登录
+
+用户需要通过OAuth授权获取访问令牌：
+
+```bash
+# 用户登录授权
+soke-cli auth login
+```
+
+登录成功后，`access_token` 和 `refresh_token` 会自动保存到配置文件中。
+
+### Token管理
+
+- **access_token**: 用户访问令牌，用于调用API
+- **refresh_token**: 刷新令牌，用于获取新的access_token
+- Token过期后需要重新执行 `soke-cli auth login`
+
+### 查看当前配置
+
+```bash
+# 查看当前配置（不显示敏感信息）
+soke-cli config show
+```
+
+## 权限不足处理
+
+遇到权限相关错误时，通常有以下几种情况：
+
+### 1. 未登录或Token过期
+
+**错误特征**: 返回401 Unauthorized或Token无效
+
+**解决方案**:
+```bash
+soke-cli auth login
+```
+
+### 2. 缺少必要权限
+
+**错误特征**: 返回403 Forbidden或权限不足提示
+
+**解决方案**:
+- 联系管理员在开放平台后台为应用开通相应权限
+- 确认企业ID（corpid）和应用配置正确
+
+### 3. 参数错误
+
+**错误特征**: 返回400 Bad Request或参数验证失败
+
+**解决方案**:
+- 检查必需参数是否提供
+- 使用 `--help` 查看命令参数说明
+- 参考API文档确认参数格式
+
+## 命令结构
+
+### Shortcuts（推荐）
+
+Shortcuts是对常用操作的高级封装，参数友好，最适合AI Agent调用：
+
+```bash
+soke-cli <service> +<verb> [flags]
+```
+
+示例：
+```bash
+soke-cli exam +get-exam-user --exam-id exam123 --dept-user-id user456
+soke-cli course +list-courses --page 1 --page-size 10
+```
+
+### 通用API调用
+
+支持直接调用任意API：
+
+```bash
+soke-cli api <METHOD> <path> [--data <json>] [--params <json>]
+```
+
+示例：
+```bash
+soke-cli api GET /users/me
+soke-cli api POST /some/endpoint --data '{"key": "value"}'
+```
+
+## 输出格式
+
+### JSON格式（默认）
+
+所有命令默认输出JSON格式，便于程序解析：
+
+```bash
+soke-cli exam +list-exams --format json
+```
+
+### 表格格式
+
+部分命令支持表格格式输出，更易读：
+
+```bash
+soke-cli exam +list-exams --format table
+```
+
+## 安全规则
+
+- **禁止输出密钥**（app_secret、access_token）到终端明文
+- **写入/删除操作前必须确认用户意图**
+- 敏感操作建议先使用 `--dry-run`（如果支持）预览
+
+## 错误处理
+
+当命令执行失败时：
+
+1. **检查配置**: 运行 `soke-cli config show` 确认配置正确
+2. **检查登录状态**: 如果是认证错误，运行 `soke-cli auth login`
+3. **检查参数**: 使用 `soke-cli <service> <command> --help` 查看参数说明
+4. **查看错误信息**: 错误响应中通常包含详细的错误原因
+
+## 常见问题
+
+### Q: 如何获取app_key和app_secret？
+
+A: 登录授客AI开放平台（https://opendev.soke.cn），创建应用后即可获取。
+
+### Q: Token过期了怎么办？
+
+A: 重新执行 `soke-cli auth login` 进行授权。
+
+### Q: 如何切换企业？
+
+A: 运行 `soke-cli auth login` 重新配置，或直接编辑 `~/.soke-cli/config.json` 文件。
+
+### Q: 支持哪些业务模块？
+
+A: 目前支持以下模块：
+- `contact`: 组织架构（部门、用户、岗位、讲师）
+- `course`: 课程管理
+- `exam`: 考试管理
+- `training`: 培训管理
+- `learning_map`: 学习地图
+- `credit`: 学分管理
+- `point`: 积分管理
+- `news`: 资讯管理
+- `certificate`: 证书管理
+- 等等...
+
+每个模块都有对应的Skill，AI Agent会根据用户意图自动选择。
+
+## 相关链接
+
+- 授客AI开放平台: https://opendev.soke.cn
+- NPM包: @sokeai/cli
+- 代码仓库: https://codeup.aliyun.com/5edbc121d1d1abe63b55f1c7/soke/soke-cli.git

package/skills/{soke-course → multi/soke-course}/README.md

@@ -4,7 +4,6 @@
 
 ## 普通用户文档
 
-- 普通使用者（业务/运营/培训）请优先阅读：[`USER_GUIDE.md`](./USER_GUIDE.md)
 
 ## 功能概述
 
@@ -21,11 +20,11 @@
 
 ### 📦 soke-material - 素材库管理
 负责文件上传和素材管理
-- [详细文档](../soke-material/SKILL.md)
+- [详细文档](./references/dependencies/soke-material.md)
 
 ### 📚 soke-lesson - 课件管理
 负责课件的创建和管理
-- [详细文档](../soke-lesson/SKILL.md)
+- [详细文档](./references/dependencies/soke-lesson.md)
 
 ## 快速开始
 
@@ -81,6 +80,7 @@ soke-cli course +list-course-users --course-id "COURSE-UUID"
 | `+list-categories` | 查询课程分类（获取 category-id） |
 | `+create` | 创建课程基本信息 |
 | `+update` | 更新课程信息 |
+| `+delete` | 删除未发布或已关闭课程 |
 | `+advanced` | 更新课程高级设置 |
 | `+publish` | 发布课程 |
 | `+get-course` | 查询课程详情 |
@@ -168,6 +168,9 @@ soke-cli course +update \
   --title "新标题" \
   --description "新描述"
 
+# 删除未发布或已关闭课程
+soke-cli course +delete --course-id "COURSE-UUID"
+
 # 添加新课件
 media_id=$(soke-cli file +upload --file ./new-lesson.mp4 --format json | jq -r '.data.uuid')
 soke-cli course +lesson-create \
@@ -215,8 +218,8 @@ const endTime = new Date('2024-12-31').getTime();   // 1735660799000
 - `2`: 已关闭
 
 **课程来源 (is-in)**:
-- `0`: 采购课
-- `1`: 自建课
+- `0`: 外部课列表
+- `1`: 内部课列表
 
 **学习模式 (study_type)**:
 - `1`: 自由式（可任意顺序学习）
@@ -258,10 +261,9 @@ soke-cli auth login
 ## 相关文档
 
 - [SKILL.md](./SKILL.md) - 完整的 Skill 文档和 API 参考
-- [素材库管理 Skill](../soke-material/SKILL.md) - 文件上传和素材管理
-- [课件管理 Skill](../soke-lesson/SKILL.md) - 课件创建和管理
-- [共享配置 Skill](../soke-shared/SKILL.md) - 认证和配置管理
-- [API 接口文档](../../docs/API_PROXY_INTERFACES.md) - 完整的 API 接口说明
+- [素材库管理 Skill](./references/dependencies/soke-material.md) - 文件上传和素材管理
+- [课件管理 Skill](./references/dependencies/soke-lesson.md) - 课件创建和管理
+- [共享配置 Skill](./references/shared.md) - 认证和配置管理
 
 ## Skill 架构