@sokeai/cli 1.0.6 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sokeai/cli",
-    "version": "1.0.6",
+    "version": "1.0.8",
     "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
     "bin": {
         "soke-cli": "scripts/run.js"
@@ -11,7 +11,8 @@
         "release": "./scripts/release.sh"
     },
     "files": [
-        "scripts/"
+        "scripts/",
+        "skills/"
     ],
     "repository": {
         "type": "git",

package/scripts/install.js

@@ -8,6 +8,86 @@ const platform = os.platform();
 const arch = os.arch();
 const version = require('../package.json').version;
 
+function copyDirRecursive(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) return;
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+      continue;
+    }
+
+    if (entry.isSymbolicLink()) {
+      try {
+        const linkTarget = fs.readlinkSync(srcPath);
+        try {
+          fs.unlinkSync(destPath);
+        } catch (_) {}
+        fs.symlinkSync(linkTarget, destPath);
+      } catch (_) {}
+      continue;
+    }
+
+    fs.copyFileSync(srcPath, destPath);
+  }
+}
+
+function detectSokeclawWorkspaceSkillsDir() {
+  const homeDir = os.homedir();
+  const defaultSkillsDir = path.join(
+    homeDir,
+    '.sokeclaw',
+    'openai-agents',
+    'workspaces',
+    'main',
+    'skills'
+  );
+
+  const workclawConfigPath = path.join(homeDir, '.sokeclaw', 'workclaw.json');
+  if (!fs.existsSync(workclawConfigPath)) return defaultSkillsDir;
+
+  try {
+    const configText = fs.readFileSync(workclawConfigPath, 'utf8');
+    const config = JSON.parse(configText);
+    const workspaceDir = config?.defaults?.agents?.openaiAgents?.main?.workspace;
+    if (typeof workspaceDir === 'string' && workspaceDir.length > 0) {
+      return path.join(workspaceDir, 'skills');
+    }
+  } catch (_) {}
+
+  return defaultSkillsDir;
+}
+
+function syncSkillsToSokeclawWorkspace() {
+  const packageRoot = path.join(__dirname, '..');
+  const packagedSkillsDir = path.join(packageRoot, 'skills');
+  if (!fs.existsSync(packagedSkillsDir)) return;
+
+  const sokeclawSkillsDir = detectSokeclawWorkspaceSkillsDir();
+  const sokeclawRootDir = path.join(os.homedir(), '.sokeclaw');
+  if (!fs.existsSync(sokeclawRootDir)) return;
+
+  try {
+    fs.mkdirSync(sokeclawSkillsDir, { recursive: true });
+  } catch (_) {
+    return;
+  }
+
+  const skillNames = ['soke-shared', 'soke-exam'];
+  for (const skillName of skillNames) {
+    const src = path.join(packagedSkillsDir, skillName);
+    const dest = path.join(sokeclawSkillsDir, skillName);
+    if (fs.existsSync(src)) {
+      copyDirRecursive(src, dest);
+    }
+  }
+}
+
 // 平台映射
 const platformMap = {
   'darwin': 'darwin',
@@ -109,6 +189,10 @@ downloadFile(downloadURL, binaryPath)
       }
     }
 
+    try {
+      syncSkillsToSokeclawWorkspace();
+    } catch (_) {}
+
     console.log('soke-cli 安装成功!');
     console.log(`二进制文件位置: ${binaryPath}`);
     console.log('\n使用方法:');

package/skills/README.md

@@ -0,0 +1,196 @@
+# 授客CLI AI Agent Skills
+
+本目录包含授客CLI的AI Agent技能定义，使AI Agent能够自动发现和调用授客CLI的各种功能。
+
+## 安装方法
+
+### 前提条件
+
+1. 已安装授客CLI：
+```bash
+npm install -g @sokeai/cli
+```
+
+2. 已完成配置和认证：
+```bash
+soke-cli config init
+soke-cli auth login
+```
+
+### 安装Skills
+
+**方式1：从GitHub安装（推荐）**
+
+```bash
+# 全局安装所有skills
+npx skills add <org>/soke-cli -y -g
+
+# 或安装特定skill
+npx skills add <org>/soke-cli --skill soke-exam -y -g
+```
+
+> 注意：需要先将本项目推送到GitHub公开仓库，然后将 `<org>` 替换为实际的GitHub组织或用户名。
+
+**方式2：本地安装（开发测试）**
+
+```bash
+# 复制到全局skills目录
+cp -r skills/soke-shared ~/.claude/skills/
+cp -r skills/soke-exam ~/.claude/skills/
+
+# 或复制到项目级skills目录
+mkdir -p .claude/skills
+cp -r skills/soke-shared .claude/skills/
+cp -r skills/soke-exam .claude/skills/
+```
+
+### 验证安装
+
+安装完成后，AI Agent会自动加载这些skills。你可以通过以下方式验证：
+
+1. 在AI Agent对话中询问："查询考试成绩"
+2. AI Agent应该能够识别并使用 `soke-exam` skill
+3. AI Agent会自动执行 `soke-cli exam +get-exam-user` 命令
+
+## Skills列表
+
+### soke-shared
+
+**功能**: 共享基础规则，包含配置、认证、权限处理
+
+**触发条件**: 
+- 首次使用soke-cli
+- 需要配置初始化
+- 需要用户登录
+- 遇到权限错误
+
+**关键内容**:
+- 配置初始化（`soke-cli config init`）
+- 用户认证（`soke-cli auth login`）
+- 权限不足处理
+- 错误处理规范
+- 安全规则
+
+### soke-exam
+
+**功能**: 考试管理，查询考试、考试用户和成绩
+
+**触发条件**:
+- 查询考试成绩
+- 查看考试列表
+- 查询考试用户信息
+- 查看考试分类
+
+**支持的命令**:
+- `+list-exams`: 列出考试列表
+- `+list-exam-users`: 列出考试用户成绩列表
+- `+get-exam-user`: 获取单个考试用户详细成绩
+- `+list-categories`: 列出考试分类
+
+**使用示例**:
+```bash
+# 查询考试成绩
+soke-cli exam +get-exam-user --exam-id exam123 --dept-user-id user456
+
+# 列出考试
+soke-cli exam +list-exams --start-time 1672502400000 --end-time 1704038400000
+```
+
+## 目录结构
+
+```
+skills/
+├── soke-shared/              # 共享基础skill
+│   └── SKILL.md
+├── soke-exam/                # 考试管理skill
+│   ├── SKILL.md
+│   └── references/           # 详细文档
+│       └── exam-get-exam-user.md
+└── README.md                 # 本文件
+```
+
+## Skill文件格式
+
+每个skill目录包含一个 `SKILL.md` 文件，格式如下：
+
+```markdown
+---
+name: skill-name              # 技能名称
+version: 1.0.0                # 版本号
+description: "简短描述。当用户需要...时使用。"  # 触发条件（关键）
+metadata:
+  requires:
+    bins: ["soke-cli"]        # 依赖的CLI工具
+  cliHelp: "soke-cli exam --help"  # 帮助命令
+---
+
+# Skill标题
+
+[Markdown格式的详细说明]
+```
+
+**关键字段说明**:
+- `name`: 技能标识符，小写字母、数字、连字符
+- `version`: 语义版本号
+- `description`: **最重要**，AI用它判断何时触发此skill，必须包含"当用户需要...时使用"
+- `metadata.requires.bins`: 依赖的CLI工具列表
+
+## 开发新的Skill
+
+### 步骤1：创建目录
+
+```bash
+mkdir -p skills/soke-<module>/references
+```
+
+### 步骤2：编写SKILL.md
+
+参考 `soke-exam/SKILL.md` 的格式，包含：
+1. Frontmatter（name, version, description, metadata）
+2. 核心概念说明
+3. Shortcuts列表
+4. 命令详解
+5. 权限表
+6. 常见工作流
+
+### 步骤3：编写详细文档（可选）
+
+在 `references/` 目录下为每个重要命令创建详细文档。
+
+### 步骤4：测试
+
+```bash
+# 本地安装测试
+cp -r skills/soke-<module> ~/.claude/skills/
+
+# 在AI Agent中测试触发条件
+```
+
+## 后续扩展
+
+可以按相同模式创建其他业务模块的skills：
+
+- `soke-course` - 课程管理
+- `soke-contact` - 组织架构（部门、用户、讲师）
+- `soke-training` - 培训管理
+- `soke-credit` - 学分管理
+- `soke-certificate` - 证书管理
+- 等等...
+
+## 注意事项
+
+1. **Description字段至关重要**: 这是AI匹配skill的唯一依据，必须清晰描述触发场景
+2. **命令示例要完整**: 包含所有必需参数，避免AI猜测
+3. **引用共享规则**: 每个业务skill都应引用soke-shared，避免重复
+4. **保持简洁**: SKILL.md应该是快速参考，详细文档放在references/目录
+5. **版本管理**: 更新skill时记得更新version字段
+
+## 相关链接
+
+- 授客AI开放平台: https://opendev.soke.cn
+- NPM包: @sokeai/cli
+- Skills规范: https://github.com/agent-skills/spec
+
+## 许可证
+
+MIT

package/skills/soke-exam/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: soke-exam
+version: 1.0.0
+description: "授客考试管理：查询考试、考试用户和成绩。查询考试列表、考试分类、考试用户成绩、考试详情。当用户需要查询考试成绩、查看考试列表、查询考试用户信息、查看考试分类时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli exam --help"
+---
+
+# 考试管理 (exam)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+
+## 核心概念
+
+- **Exam（考试）**: 考试实体，包含标题、时间范围、状态等信息，通过 `uuid` 标识
+- **ExamUser（考试用户）**: 用户的考试记录，包含成绩、状态、答题时间等，通过 `target_id` 标识
+- **Category（考试分类）**: 考试分类，支持层级结构，通过 `uuid` 标识
+- **DeptUser（部门用户）**: 企业内的用户，通过 `dept_user_id` 标识
+
+## 资源关系
+
+```
+Exam (考试)
+├── ExamUser (考试用户记录)
+│   ├── dept_user_id (用户ID)
+│   ├── score (成绩)
+│   ├── exam_status (考试状态)
+│   └── submit_time (提交时间)
+└── Category (考试分类)
+```
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`soke-cli exam +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+list-exams`](#list-exams) | 列出考试列表，支持时间范围和状态筛选 |
+| [`+list-exam-users`](#list-exam-users) | 列出考试用户成绩列表，支持用户筛选和时间范围 |
+| [`+get-exam-user`](#get-exam-user) | 获取单个考试用户的详细成绩信息 |
+| [`+list-categories`](#list-categories) | 列出考试分类 |
+
+## 命令详解
+
+### +list-exams
+
+列出考试列表，支持按时间范围和状态筛选。
+
+**命令格式**:
+```bash
+soke-cli exam +list-exams \
+  --start-time <timestamp> \
+  --end-time <timestamp> \
+  [--status <status>] \
+  [--page <page>] \
+  [--page-size <size>]
+```
+
+**参数说明**:
+- `--start-time`: 开始时间（Unix时间戳，毫秒）**必需**
+- `--end-time`: 结束时间（Unix时间戳，毫秒）**必需**
+- `--status`: 考试状态（可选）
+- `--page`: 页码，从1开始（默认: 1）
+- `--page-size`: 每页数量，最大100（默认: 100）
+
+**返回字段**:
+- `uuid`: 考试ID
+- `title`: 考试标题
+- `start_time`: 开始时间
+- `end_time`: 结束时间
+- `status`: 考试状态
+
+**示例**:
+```bash
+# 查询2023年的所有考试
+soke-cli exam +list-exams \
+  --start-time 1672502400000 \
+  --end-time 1704038400000
+
+# 查询进行中的考试
+soke-cli exam +list-exams \
+  --start-time 1672502400000 \
+  --end-time 1704038400000 \
+  --status "进行中"
+```
+
+**权限要求**: `exam:exam:readonly`
+
+---
+
+### +list-exam-users
+
+列出考试用户成绩列表，支持按用户ID和完成时间筛选。
+
+**命令格式**:
+```bash
+soke-cli exam +list-exam-users \
+  --exam-id <exam_id> \
+  [--userid-list <user_ids>] \
+  [--finish-start-time <timestamp>] \
+  [--finish-end-time <timestamp>] \
+  [--page <page>] \
+  [--page-size <size>]
+```
+
+**参数说明**:
+- `--exam-id`: 考试ID **必需**
+- `--userid-list`: 用户ID列表，逗号分隔，最多100个（可选）
+- `--finish-start-time`: 完成开始时间（Unix时间戳，毫秒）（可选）
+- `--finish-end-time`: 完成结束时间（Unix时间戳，毫秒）（可选）
+- `--page`: 页码，从1开始（默认: 1）
+- `--page-size`: 每页数量，最大100（默认: 100）
+
+**返回字段**:
+- `target_id`: 考试用户记录ID
+- `dept_user_id`: 部门用户ID
+- `score`: 成绩
+- `exam_status`: 考试状态
+- `create_time`: 创建时间
+
+**示例**:
+```bash
+# 查询某个考试的所有用户成绩
+soke-cli exam +list-exam-users --exam-id exam123
+
+# 查询特定用户的成绩
+soke-cli exam +list-exam-users \
+  --exam-id exam123 \
+  --userid-list "user1,user2,user3"
+
+# 查询某个时间段内完成的考试
+soke-cli exam +list-exam-users \
+  --exam-id exam123 \
+  --finish-start-time 1672502400000 \
+  --finish-end-time 1704038400000
+```
+
+**权限要求**: `exam:examUser:readonly`
+
+---
+
+### +get-exam-user
+
+获取单个考试用户的详细成绩信息，包含答题详情。
+
+**命令格式**:
+```bash
+soke-cli exam +get-exam-user \
+  --exam-id <exam_id> \
+  --dept-user-id <dept_user_id>
+```
+
+**参数说明**:
+- `--exam-id`: 考试ID **必需**
+- `--dept-user-id`: 部门用户ID **必需**
+
+**返回字段**:
+- `target_id`: 考试用户记录ID
+- `target_title`: 考试标题
+- `dept_user_id`: 部门用户ID
+- `score`: 成绩
+- `exam_status`: 考试状态
+- `start_time`: 开始时间
+- `submit_time`: 提交时间
+- `question_count`: 题目数量
+- `create_time`: 创建时间
+
+**示例**:
+```bash
+# 查询张三的考试成绩
+soke-cli exam +get-exam-user \
+  --exam-id exam123 \
+  --dept-user-id user456
+```
+
+**权限要求**: `exam:examUser:readonly`
+
+**使用场景**:
+- 当用户询问"查询某人的考试成绩"时使用
+- 需要同时提供考试ID和用户ID
+- 如果只知道用户名，需要先通过 `soke-cli contact +search-user` 查询用户ID
+
+---
+
+### +list-categories
+
+列出考试分类，支持分页。
+
+**命令格式**:
+```bash
+soke-cli exam +list-categories \
+  [--page <page>] \
+  [--page-size <size>]
+```
+
+**参数说明**:
+- `--page`: 页码，从1开始（默认: 1）
+- `--page-size`: 每页数量，最大100（默认: 100）
+
+**返回字段**:
+- `uuid`: 分类ID
+- `title`: 分类名称
+- `parent_id`: 父分类ID
+- `create_time`: 创建时间
+
+**示例**:
+```bash
+# 查询所有考试分类
+soke-cli exam +list-categories
+
+# 分页查询
+soke-cli exam +list-categories --page 1 --page-size 20
+```
+
+**权限要求**: `exam:category:readonly`
+
+## 通用API调用
+
+如果Shortcuts不满足需求，可以使用通用API调用：
+
+```bash
+soke-cli api <METHOD> <path> [--params <json>]
+```
+
+示例：
+```bash
+soke-cli api GET /exam/exam/list --params '{"start_time":"1672502400000","end_time":"1704038400000"}'
+```
+
+## 权限表
+
+| 操作 | 所需权限 |
+|------|---------|
+| `+list-exams` | `exam:exam:readonly` |
+| `+list-exam-users` | `exam:examUser:readonly` |
+| `+get-exam-user` | `exam:examUser:readonly` |
+| `+list-categories` | `exam:category:readonly` |
+
+## 常见工作流
+
+### 工作流1: 查询用户考试成绩
+
+当用户询问"查询张三的考试成绩"时：
+
+**步骤1**: 如果只知道用户名，先查询用户ID
+```bash
+soke-cli contact +search-user --name "张三"
+```
+
+**步骤2**: 获取考试列表，找到目标考试ID
+```bash
+soke-cli exam +list-exams \
+  --start-time 1672502400000 \
+  --end-time 1704038400000
+```
+
+**步骤3**: 查询该用户的考试成绩
+```bash
+soke-cli exam +get-exam-user \
+  --exam-id <exam_id> \
+  --dept-user-id <dept_user_id>
+```
+
+### 工作流2: 统计考试完成情况
+
+当用户询问"统计某个考试的完成情况"时：
+
+**步骤1**: 获取考试用户列表
+```bash
+soke-cli exam +list-exam-users --exam-id <exam_id>
+```
+
+**步骤2**: 分析返回的数据
+- 统计 `exam_status` 字段的分布
+- 计算平均分（`score` 字段）
+- 统计完成人数
+
+### 工作流3: 查询某个时间段的考试
+
+当用户询问"查询本月的考试"时：
+
+**步骤1**: 计算时间范围（Unix时间戳，毫秒）
+```bash
+# 例如：2024年1月1日 00:00:00 = 1704038400000
+# 2024年1月31日 23:59:59 = 1706716799000
+```
+
+**步骤2**: 查询考试列表
+```bash
+soke-cli exam +list-exams \
+  --start-time 1704038400000 \
+  --end-time 1706716799000
+```
+
+## 注意事项
+
+1. **时间格式**: 所有时间参数使用Unix时间戳（毫秒），不是秒
+2. **分页**: 默认每页100条，最大100条，超过需要分页查询
+3. **用户ID**: `dept_user_id` 是企业内的用户ID，不是用户名
+4. **考试ID**: `exam-id` 和 `uuid` 是同一个字段，都表示考试ID
+5. **权限**: 所有操作都需要先完成认证（`soke-cli auth login`）
+
+## 错误处理
+
+### 权限不足
+如果遇到权限错误，参考 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md) 中的权限处理章节。
+
+### 参数错误
+使用 `--help` 查看命令参数说明：
+```bash
+soke-cli exam +get-exam-user --help
+```
+
+### 数据不存在
+如果查询的考试或用户不存在，API会返回空数据或错误提示。

package/skills/soke-exam/references/exam-get-exam-user.md

@@ -0,0 +1,212 @@
+# +get-exam-user - 获取考试用户详细成绩
+
+## 概述
+
+获取单个用户在特定考试中的详细成绩信息，包括分数、状态、答题时间等。
+
+## 命令格式
+
+```bash
+soke-cli exam +get-exam-user \
+  --exam-id <exam_id> \
+  --dept-user-id <dept_user_id>
+```
+
+## 参数说明
+
+### 必需参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `--exam-id` | string | 考试ID（uuid） |
+| `--dept-user-id` | string | 部门用户ID |
+
+### 可选参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--format` | string | json | 输出格式（json/table） |
+
+## 返回数据
+
+### JSON格式
+
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "target_id": "exam_user_123",
+    "target_title": "2024年度安全培训考试",
+    "dept_user_id": "user456",
+    "score": 85,
+    "exam_status": "已完成",
+    "start_time": 1704038400000,
+    "submit_time": 1704042000000,
+    "question_count": 20,
+    "create_time": 1704038400000
+  }
+}
+```
+
+### 表格格式
+
+```
+target_id      | target_title           | dept_user_id | score | exam_status | start_time    | submit_time   | question_count | create_time
+exam_user_123  | 2024年度安全培训考试    | user456      | 85    | 已完成      | 1704038400000 | 1704042000000 | 20             | 1704038400000
+```
+
+## 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `target_id` | string | 考试用户记录ID |
+| `target_title` | string | 考试标题 |
+| `dept_user_id` | string | 部门用户ID |
+| `score` | number | 考试成绩（分数） |
+| `exam_status` | string | 考试状态（如：已完成、进行中、未开始） |
+| `start_time` | number | 开始答题时间（Unix时间戳，毫秒） |
+| `submit_time` | number | 提交时间（Unix时间戳，毫秒） |
+| `question_count` | number | 题目总数 |
+| `create_time` | number | 记录创建时间（Unix时间戳，毫秒） |
+
+## 使用示例
+
+### 示例1: 查询单个用户成绩
+
+```bash
+soke-cli exam +get-exam-user \
+  --exam-id exam123 \
+  --dept-user-id user456
+```
+
+### 示例2: 以表格格式输出
+
+```bash
+soke-cli exam +get-exam-user \
+  --exam-id exam123 \
+  --dept-user-id user456 \
+  --format table
+```
+
+## 常见场景
+
+### 场景1: 用户询问自己的成绩
+
+**用户输入**: "我的考试成绩是多少？"
+
+**处理步骤**:
+1. 获取当前用户的 `dept_user_id`（通过 `soke-cli api GET /users/me`）
+2. 确认考试ID（可能需要先列出考试）
+3. 执行查询命令
+
+```bash
+# 步骤1: 获取当前用户信息
+soke-cli api GET /users/me
+
+# 步骤2: 查询成绩
+soke-cli exam +get-exam-user \
+  --exam-id exam123 \
+  --dept-user-id <从步骤1获取的user_id>
+```
+
+### 场景2: 管理员查询员工成绩
+
+**用户输入**: "查询张三的考试成绩"
+
+**处理步骤**:
+1. 通过姓名查询用户ID（使用 `soke-cli contact +search-user`）
+2. 确认考试ID
+3. 执行查询命令
+
+```bash
+# 步骤1: 查询用户ID
+soke-cli contact +search-user --name "张三"
+
+# 步骤2: 查询成绩
+soke-cli exam +get-exam-user \
+  --exam-id exam123 \
+  --dept-user-id <从步骤1获取的dept_user_id>
+```
+
+### 场景3: 批量查询多个用户成绩
+
+**用户输入**: "查询所有人的考试成绩"
+
+**处理步骤**:
+使用 `+list-exam-users` 更合适，可以一次获取所有用户的成绩列表。
+
+```bash
+soke-cli exam +list-exam-users --exam-id exam123
+```
+
+## 权限要求
+
+- **所需权限**: `exam:examUser:readonly`
+- **认证方式**: 需要先执行 `soke-cli auth login` 完成用户认证
+
+## 错误处理
+
+### 错误1: 考试不存在
+
+```json
+{
+  "code": 404,
+  "msg": "考试不存在"
+}
+```
+
+**解决方案**: 检查 `exam-id` 是否正确
+
+### 错误2: 用户未参加考试
+
+```json
+{
+  "code": 404,
+  "msg": "用户未参加该考试"
+}
+```
+
+**解决方案**: 确认用户是否已参加该考试
+
+### 错误3: 权限不足
+
+```json
+{
+  "code": 403,
+  "msg": "权限不足"
+}
+```
+
+**解决方案**: 
+1. 确认已执行 `soke-cli auth login`
+2. 联系管理员开通 `exam:examUser:readonly` 权限
+
+### 错误4: 参数缺失
+
+```bash
+Error: required flag(s) "exam-id", "dept-user-id" not set
+```
+
+**解决方案**: 检查是否提供了所有必需参数
+
+## API详情
+
+- **HTTP方法**: GET
+- **API路径**: `/exam/user/info`
+- **请求参数**:
+  - `exam_id`: 考试ID
+  - `dept_user_id`: 部门用户ID
+
+## 相关命令
+
+- `+list-exam-users`: 列出考试用户成绩列表
+- `+list-exams`: 列出考试列表
+- `soke-cli contact +search-user`: 查询用户信息
+
+## 注意事项
+
+1. **时间戳格式**: 所有时间字段都是Unix时间戳（毫秒），不是秒
+2. **用户ID**: 必须使用 `dept_user_id`，不能使用用户名或其他标识
+3. **考试状态**: 状态值可能因系统配置而异，常见值包括：已完成、进行中、未开始、已过期
+4. **成绩计算**: 成绩字段可能为null（如果考试未完成或未提交）

package/skills/soke-shared/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: soke-shared
+version: 1.0.0
+description: "授客CLI共享基础：应用配置初始化、认证登录（auth login）、权限管理、错误处理、安全规则。当用户需要第一次配置（soke-cli config init）、使用登录授权（soke-cli auth login）、遇到权限不足、或首次使用soke-cli时触发。"
+---
+
+# soke-cli 共享规则
+
+本技能指导你如何通过soke-cli操作授客AI资源，以及有哪些注意事项。
+
+## 配置初始化
+
+首次使用需运行 `soke-cli config init` 完成应用配置。
+
+当你帮用户初始化配置时，引导用户按照交互式提示完成配置：
+
+```bash
+# 初始化配置
+soke-cli config init
+```
+
+配置项包括：
+- `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 config init` 重新配置，或直接编辑 `~/.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