@sokeai/cli 1.0.21 → 1.0.23

package/README.md

@@ -15,9 +15,10 @@
 
 3. **业务模块快捷命令**
    - 针对授客AI核心业务场景提供了丰富的快捷命令集：
-     - **通讯录 (contact)**: 部门与用户查询、管理等。
+     - **通讯录 (contact)**: 部门与用户查询、管理、搜索等。
      - **课程 (course)**: 课程列表、分类、学习记录、人脸识别记录等。
      - **考试 (exam)**: 考试列表、分类、考试成绩与记录查询。
+     - **学习档案 (learning-profile)**: 学员学习档案查询、学习情况统计。
      - **学习地图 (learning-map)**: 学习地图、阶段、任务查询与分配。
      - **证书 (certificate)**: 证书发放记录、分类等。
      - **学分 (credit) & 积分 (point)**: 学分/积分日志及用户情况查询。
@@ -71,6 +72,8 @@ AI Agent 会自动：
 
 - **soke-shared**: 配置初始化、用户认证、权限处理等基础功能
 - **soke-exam**: 考试管理（查询考试、考试成绩、考试分类）
+- **soke-course**: 课程管理（查询课程、课程分类、学习记录）
+- **soke-learning-profile**: 学习档案查询（查询学员学习档案、学习情况统计）
 - 更多业务模块的 Skills 正在开发中...
 
 详细文档：[skills/README.md](skills/README.md)
@@ -156,8 +159,68 @@ soke-cli api POST /some/endpoint --data '{"key": "value"}'
 
 ## 开发与贡献
 
-1. 依赖管理：项目使用 Go Modules，可以运行 `go mod tidy` 整理依赖。
-2. 添加新命令：
+### 快速开始本地测试
+
+```bash
+# 1. 编译、安装到全局、运行测试（一条命令）
+bash ./scripts/local-test.sh
+# 提示时输入 'y' 更新全局安装
+
+# 2. 链接 Skills 到 Claude（首次需要）
+bash ./scripts/link-skills.sh
+# 选择 'all' 链接到所有目录
+
+# 3. 在 AI Agent 中测试
+# 打开 Claude Code，输入："查询张三的学习档案"
+```
+
+**📖 详细指南：** [docs/LOCAL_TESTING.md](docs/LOCAL_TESTING.md)
+
+### 本地开发测试
+
+1. **一键测试和安装**
+   ```bash
+   # 编译 -> 安装到全局 -> 运行测试（一条命令完成所有步骤）
+   bash ./scripts/local-test.sh
+   ```
+   
+   这个脚本会：
+   - 编译项目
+   - 检查本地版本功能
+   - 检测全局安装状态
+   - 提示是否需要更新全局安装（会自动备份）
+   - 运行功能测试验证
+
+2. **运行完整 E2E 测试**
+   ```bash
+   # 测试所有模块
+   bash ./scripts/e2e-test.sh
+   
+   # 测试特定模块
+   bash ./scripts/e2e-test.sh learning-profile
+   bash ./scripts/e2e-test.sh contact
+   ```
+
+3. **依赖管理**
+   
+   项目使用 Go Modules，可以运行 `go mod tidy` 整理依赖。
+
+4. **添加新命令**
    - 业务接口建议在 `shortcuts/` 目录下添加对应的结构定义。
    - 基础功能可在 `cmd/` 下新建对应包并在 `cmd/root.go` 中注册。
-3. 测试：运行 `make test` 进行单元测试。
+   - 为新模块创建 Skill 文档：`skills/<module-name>/SKILL.md`
+
+5. **完整开发流程**
+   ```bash
+   # 1. 修改代码后，运行本地测试（会提示是否更新全局安装）
+   bash ./scripts/local-test.sh
+   
+   # 2. 运行完整 E2E 测试
+   bash ./scripts/e2e-test.sh
+   
+   # 3. 测试 Skills（需要先更新全局安装）
+   npx skills add liuchenlong1111/soke-cli -y -g
+   
+   # 4. 在 AI Agent 中测试自然语言交互
+   # 例如："查询张三的学习档案"
+   ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sokeai/cli",
-    "version": "1.0.21",
+    "version": "1.0.23",
     "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
     "bin": {
         "soke-cli": "scripts/run.js"

package/scripts/e2e-test.sh

@@ -42,6 +42,35 @@ if [ ! -f "./soke-cli" ]; then
     echo ""
 fi
 
+# 检查全局安装的 CLI 版本
+echo -e "${YELLOW}检查全局 CLI 安装...${NC}"
+GLOBAL_CLI=$(which soke-cli 2>/dev/null)
+if [ -n "$GLOBAL_CLI" ]; then
+    echo -e "  全局 CLI 路径: ${BLUE}${GLOBAL_CLI}${NC}"
+
+    # 检查全局版本是否支持 learning-profile
+    if ! $GLOBAL_CLI learning-profile --help &>/dev/null; then
+        echo -e "${YELLOW}  警告: 全局 CLI 不支持 learning-profile 模块${NC}"
+        echo -e "${YELLOW}  需要更新全局安装以支持 skill 测试${NC}"
+        echo ""
+        echo -e "${YELLOW}是否要将本地编译版本安装到全局? (y/n)${NC}"
+        read -r INSTALL_GLOBAL
+        if [ "$INSTALL_GLOBAL" = "y" ] || [ "$INSTALL_GLOBAL" = "Y" ]; then
+            echo -e "${YELLOW}安装到全局...${NC}"
+            sudo cp ./soke-cli $GLOBAL_CLI
+            echo -e "${GREEN}✓ 全局 CLI 已更新${NC}"
+        else
+            echo -e "${YELLOW}跳过全局安装，将仅测试本地版本${NC}"
+        fi
+    else
+        echo -e "${GREEN}✓ 全局 CLI 支持 learning-profile 模块${NC}"
+    fi
+else
+    echo -e "${YELLOW}  未找到全局 CLI 安装${NC}"
+    echo -e "${YELLOW}  Skill 测试需要全局安装 soke-cli${NC}"
+fi
+echo ""
+
 # 检查是否已登录
 echo -e "${YELLOW}检查登录状态...${NC}"
 if ! ./soke-cli config show &>/dev/null; then
@@ -99,6 +128,15 @@ if should_test_module "contact"; then
     test_command "contact" "+list-lectors" "" "获取讲师列表"
     test_command "contact" "+list-groups" "--start-time 1672502400000 --end-time 1704038400000" "获取用户组列表"
     test_command "contact" "+search-user" "--dept-user-name 测试" "搜索用户"
+    test_command "contact" "+search-dept" "--dept-name 测试" "搜索部门"
+    echo ""
+fi
+
+# ==================== Learning Profile 模块 ====================
+if should_test_module "learning-profile"; then
+    echo -e "${YELLOW}[Learning Profile 模块]${NC}"
+    test_command "learning-profile" "+list" "--offset 0 --page-size 10" "获取学习档案列表"
+    test_command "learning-profile" "+list" "--is-new 1 --page-size 5" "获取新员工学习档案"
     echo ""
 fi
 

package/scripts/link-skills.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+
+# soke-cli Skills 本地测试脚本
+# 将本地 skills 链接到 Claude 的 skills 目录进行测试
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}  soke-cli Skills 本地测试${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+# 检查 skills 目录是否存在
+if [ ! -d "./skills" ]; then
+    echo -e "${RED}错误: 未找到 ./skills 目录${NC}"
+    exit 1
+fi
+
+# 查找所有可能的 skills 目录
+echo -e "${YELLOW}查找 Claude skills 目录...${NC}"
+SKILLS_DIRS=(
+    "$HOME/.codex/skills"
+    "$HOME/.openclaw/skills"
+    "$HOME/.agents/skills"
+    "$HOME/.workclaw/skills"
+    "$HOME/.skills"
+)
+
+FOUND_DIRS=()
+for dir in "${SKILLS_DIRS[@]}"; do
+    if [ -d "$dir" ]; then
+        FOUND_DIRS+=("$dir")
+        echo -e "  ${GREEN}✓${NC} 找到: $dir"
+    fi
+done
+
+if [ ${#FOUND_DIRS[@]} -eq 0 ]; then
+    echo -e "${RED}错误: 未找到任何 Claude skills 目录${NC}"
+    echo -e "${YELLOW}提示: 请先运行 'npx skills add' 安装任意一个 skill 来初始化目录${NC}"
+    exit 1
+fi
+echo ""
+
+# 选择要链接的目录
+if [ ${#FOUND_DIRS[@]} -eq 1 ]; then
+    TARGET_DIR="${FOUND_DIRS[0]}"
+    echo -e "${BLUE}将链接到: ${TARGET_DIR}${NC}"
+else
+    echo -e "${YELLOW}找到多个 skills 目录，请选择:${NC}"
+    for i in "${!FOUND_DIRS[@]}"; do
+        echo -e "  $((i+1)). ${FOUND_DIRS[$i]}"
+    done
+    echo ""
+
+    # 如果有参数，使用参数作为选择
+    if [ -n "$1" ]; then
+        choice=$1
+    else
+        echo -n "请输入序号 (1-${#FOUND_DIRS[@]}) 或 'all' 链接到所有目录: "
+        read -r choice
+    fi
+
+    if [ "$choice" = "all" ]; then
+        echo -e "${BLUE}将链接到所有目录${NC}"
+        LINK_ALL=true
+    elif [[ "$choice" =~ ^[0-9]+$ ]] && [ "$choice" -ge 1 ] && [ "$choice" -le ${#FOUND_DIRS[@]} ]; then
+        TARGET_DIR="${FOUND_DIRS[$((choice-1))]}"
+        echo -e "${BLUE}已选择: ${TARGET_DIR}${NC}"
+        LINK_ALL=false
+    else
+        echo -e "${RED}无效的选择${NC}"
+        exit 1
+    fi
+fi
+echo ""
+
+# 获取当前项目的绝对路径
+PROJECT_DIR=$(pwd)
+SOURCE_SKILLS_DIR="${PROJECT_DIR}/skills"
+
+# 列出要链接的 skills
+echo -e "${YELLOW}准备链接以下 skills:${NC}"
+for skill_dir in "$SOURCE_SKILLS_DIR"/*; do
+    if [ -d "$skill_dir" ]; then
+        skill_name=$(basename "$skill_dir")
+        echo -e "  - ${BLUE}${skill_name}${NC}"
+    fi
+done
+echo ""
+
+# 确认操作
+echo -e "${YELLOW}是否继续? (y/n)${NC}"
+read -r CONFIRM
+if [ "$CONFIRM" != "y" ] && [ "$CONFIRM" != "Y" ]; then
+    echo -e "${YELLOW}取消操作${NC}"
+    exit 0
+fi
+echo ""
+
+# 创建符号链接
+echo -e "${YELLOW}创建符号链接...${NC}"
+SUCCESS_COUNT=0
+SKIP_COUNT=0
+
+# 如果选择链接到所有目录
+if [ "$LINK_ALL" = true ]; then
+    for target_dir in "${FOUND_DIRS[@]}"; do
+        echo -e "${BLUE}链接到: ${target_dir}${NC}"
+        for skill_dir in "$SOURCE_SKILLS_DIR"/*; do
+            if [ -d "$skill_dir" ]; then
+                skill_name=$(basename "$skill_dir")
+                target_link="${target_dir}/${skill_name}"
+
+                if [ -L "$target_link" ]; then
+                    current_target=$(readlink "$target_link")
+                    if [ "$current_target" = "$skill_dir" ]; then
+                        echo -e "  ${GREEN}✓${NC} ${skill_name} (已存在)"
+                        SKIP_COUNT=$((SKIP_COUNT + 1))
+                    else
+                        rm "$target_link"
+                        ln -s "$skill_dir" "$target_link"
+                        echo -e "  ${GREEN}✓${NC} ${skill_name} (已更新)"
+                        SUCCESS_COUNT=$((SUCCESS_COUNT + 1))
+                    fi
+                elif [ -e "$target_link" ]; then
+                    echo -e "  ${RED}✗${NC} ${skill_name} (存在同名文件)"
+                else
+                    ln -s "$skill_dir" "$target_link"
+                    echo -e "  ${GREEN}✓${NC} ${skill_name} (已链接)"
+                    SUCCESS_COUNT=$((SUCCESS_COUNT + 1))
+                fi
+            fi
+        done
+        echo ""
+    done
+else
+    # 链接到单个目录
+    for skill_dir in "$SOURCE_SKILLS_DIR"/*; do
+        if [ -d "$skill_dir" ]; then
+            skill_name=$(basename "$skill_dir")
+            target_link="${TARGET_DIR}/${skill_name}"
+
+            # 检查是否已存在
+            if [ -L "$target_link" ]; then
+                # 已存在符号链接，检查是否指向正确位置
+                current_target=$(readlink "$target_link")
+                if [ "$current_target" = "$skill_dir" ]; then
+                    echo -e "  ${GREEN}✓${NC} ${skill_name} (已存在，指向正确)"
+                    SKIP_COUNT=$((SKIP_COUNT + 1))
+                else
+                    echo -e "  ${YELLOW}!${NC} ${skill_name} (已存在，但指向: ${current_target})"
+                    echo -n "    是否覆盖? (y/n): "
+                    read -r overwrite
+                    if [ "$overwrite" = "y" ] || [ "$overwrite" = "Y" ]; then
+                        rm "$target_link"
+                        ln -s "$skill_dir" "$target_link"
+                        echo -e "    ${GREEN}✓${NC} 已覆盖"
+                        SUCCESS_COUNT=$((SUCCESS_COUNT + 1))
+                    else
+                        echo -e "    ${YELLOW}跳过${NC}"
+                        SKIP_COUNT=$((SKIP_COUNT + 1))
+                    fi
+                fi
+            elif [ -e "$target_link" ]; then
+                # 存在同名文件/目录
+                echo -e "  ${RED}✗${NC} ${skill_name} (存在同名文件/目录)"
+                echo -e "    请手动删除: rm -rf ${target_link}"
+            else
+                # 创建新链接
+                ln -s "$skill_dir" "$target_link"
+                echo -e "  ${GREEN}✓${NC} ${skill_name} (已链接)"
+                SUCCESS_COUNT=$((SUCCESS_COUNT + 1))
+            fi
+        fi
+    done
+fi
+echo ""
+
+# 完成
+echo -e "${GREEN}========================================${NC}"
+echo -e "${GREEN}  Skills 链接完成! ✓${NC}"
+echo -e "${GREEN}========================================${NC}"
+echo ""
+echo -e "${BLUE}统计:${NC}"
+echo -e "  新建链接: ${GREEN}${SUCCESS_COUNT}${NC}"
+echo -e "  已存在: ${YELLOW}${SKIP_COUNT}${NC}"
+echo ""
+echo -e "${BLUE}下一步:${NC}"
+echo -e "  1. 确保全局 CLI 已更新: ${BLUE}bash ./scripts/local-test.sh${NC}"
+echo -e "  2. 在 Claude Code 中测试:"
+echo -e "     ${BLUE}\"查询张三的学习档案\"${NC}"
+echo -e "     ${BLUE}\"查询技术部的学员学习情况\"${NC}"
+echo ""
+echo -e "${YELLOW}提示:${NC}"
+echo -e "  - Skills 已链接到: ${TARGET_DIR}"
+echo -e "  - 修改本地 skills 文件会立即生效"
+echo -e "  - 删除链接: ${BLUE}rm ${TARGET_DIR}/soke-*${NC}"
+echo ""

package/scripts/local-test.js

@@ -0,0 +1,503 @@
+#!/usr/bin/env node
+
+/**
+ * 本地测试脚本 - 将 skills 分发到本地 AI Agent 环境
+ * 用于开发完 skill 后在本地测试，无需发布到 npm
+ *
+ * 使用方法:
+ *   node scripts/local-test.js
+ *   node scripts/local-test.js --skill soke-course
+ *   node scripts/local-test.js --clean
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// 颜色输出
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m'
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function logSection(title) {
+  console.log('');
+  log(`${'='.repeat(60)}`, 'blue');
+  log(`  ${title}`, 'bright');
+  log(`${'='.repeat(60)}`, 'blue');
+  console.log('');
+}
+
+function logSuccess(message) {
+  log(`✅ ${message}`, 'green');
+}
+
+function logError(message) {
+  log(`❌ ${message}`, 'red');
+}
+
+function logWarning(message) {
+  log(`⚠️  ${message}`, 'yellow');
+}
+
+function logInfo(message) {
+  log(`ℹ️  ${message}`, 'cyan');
+}
+
+/**
+ * 递归复制目录
+ */
+function copyDirRecursive(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) return false;
+
+  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);
+    } else if (entry.isSymbolicLink()) {
+      try {
+        const linkTarget = fs.readlinkSync(srcPath);
+        try {
+          fs.unlinkSync(destPath);
+        } catch (_) {}
+        fs.symlinkSync(linkTarget, destPath);
+      } catch (_) {}
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+
+  return true;
+}
+
+/**
+ * 检测所有 soke-* skills
+ */
+function detectSkillNames(packagedSkillsDir) {
+  if (!fs.existsSync(packagedSkillsDir)) return [];
+
+  try {
+    const entries = fs.readdirSync(packagedSkillsDir, { withFileTypes: true });
+    return entries
+      .filter(entry => entry.isDirectory() && entry.name.startsWith('soke-'))
+      .map(entry => entry.name)
+      .sort();
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * 从 SKILL.md 解析元数据
+ */
+function parseSkillMetadata(skillDir) {
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillMdPath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(skillMdPath, 'utf8');
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) return null;
+
+    const frontmatter = frontmatterMatch[1];
+    const metadata = {};
+
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    if (nameMatch) metadata.name = nameMatch[1].trim();
+
+    const summaryMatch = frontmatter.match(/^summary:\s*(.+)$/m);
+    if (summaryMatch) metadata.summary = summaryMatch[1].trim();
+
+    const descMatch = frontmatter.match(/^description:\s*["'](.+)["']$/m);
+    if (descMatch) {
+      metadata.description = descMatch[1].trim();
+    } else {
+      const descMatch2 = frontmatter.match(/^description:\s*(.+)$/m);
+      if (descMatch2) metadata.description = descMatch2[1].trim();
+    }
+
+    const versionMatch = frontmatter.match(/^version:\s*(.+)$/m);
+    if (versionMatch) metadata.version = versionMatch[1].trim();
+
+    const binsMatch = frontmatter.match(/bins:\s*\[(.+?)\]/);
+    if (binsMatch) {
+      metadata.bins = binsMatch[1].split(',').map(b => b.trim().replace(/['"]/g, ''));
+    }
+
+    return metadata;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * 推断 skill emoji
+ */
+function inferSkillEmoji(skillName) {
+  const emojiMap = {
+    'soke-exam': '📝',
+    'soke-course': '📚',
+    'soke-shared': '🔧',
+    'soke-user': '👤',
+    'soke-contact': '📇',
+    'soke-department': '🏢',
+    'soke-approval': '✅',
+    'soke-attendance': '📅',
+    'soke-report': '📊'
+  };
+  return emojiMap[skillName] || '📦';
+}
+
+/**
+ * 检测本地 AI Agent 环境
+ * 只检测 agent 相关的目录，不包括全局安装目录
+ */
+function detectLocalAgentDirs() {
+  const homeDir = os.homedir();
+  const dirs = [];
+
+  // 1. workclaw (Claude Code) - Agent skills 目录
+  const workclawDir = path.join(homeDir, '.workclaw', 'skills');
+  if (fs.existsSync(path.join(homeDir, '.workclaw'))) {
+    dirs.push({
+      name: 'workclaw (Claude Code)',
+      path: workclawDir,
+      registryPath: path.join(workclawDir, 'registry.json'),
+      type: 'workclaw'
+    });
+  }
+
+  // 2. claude (Claude Desktop) - Agent skills 目录
+  const claudeDir = path.join(homeDir, '.claude', 'skills');
+  if (fs.existsSync(path.join(homeDir, '.claude'))) {
+    dirs.push({
+      name: 'claude (Claude Desktop)',
+      path: claudeDir,
+      registryPath: null,
+      type: 'claude'
+    });
+  }
+
+  // 3. sokeclaw - Agent skills 目录
+  const sokeclawDir = path.join(homeDir, '.sokeclaw', 'openai-agents', 'workspaces', 'main', 'skills');
+  if (fs.existsSync(path.join(homeDir, '.sokeclaw'))) {
+    dirs.push({
+      name: 'sokeclaw',
+      path: sokeclawDir,
+      registryPath: null,
+      type: 'sokeclaw'
+    });
+  }
+
+  // 4. zev - Agent skills 目录
+  const zevDir = path.join(homeDir, '.zev', 'openai-agents', 'workspaces', 'main', 'skills');
+  if (fs.existsSync(path.join(homeDir, '.zev'))) {
+    dirs.push({
+      name: 'zev',
+      path: zevDir,
+      registryPath: null,
+      type: 'zev'
+    });
+  }
+
+  return dirs;
+}
+
+/**
+ * 更新 workclaw registry.json
+ */
+function updateWorkclawRegistry(registryPath, skillName, metadata, skillInstallPath) {
+  let registry;
+
+  try {
+    registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  } catch (_) {
+    registry = { version: 1, migrations: {}, skills: [] };
+  }
+
+  if (registry.version == null) registry.version = 1;
+  if (!registry.migrations) registry.migrations = {};
+  if (!Array.isArray(registry.skills)) registry.skills = [];
+
+  const displayName = metadata.summary || metadata.name || skillName;
+  const description = metadata.description || `${displayName} - 授客AI CLI工具`;
+  const version = metadata.version || '1.0.0';
+  const emoji = inferSkillEmoji(skillName);
+  const requires = metadata.bins ? { bins: metadata.bins } : {};
+
+  const skillEntry = {
+    id: `skill:${skillName}`,
+    name: skillName,
+    displayName: displayName,
+    description: description,
+    source: { type: 'local', slug: '', url: '' },
+    install: {
+      path: skillInstallPath,
+      installedAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      version: version
+    },
+    state: { enabled: true, health: 'ok', lastError: '' },
+    runtime: { supported: ['openclaw'], enabled: ['openclaw'], primary: 'openclaw' },
+    security: { riskLevel: 'normal', requiresApproval: false },
+    metadata: { emoji: emoji, homepage: '', requires: requires }
+  };
+
+  const idx = registry.skills.findIndex(s => s && s.id === skillEntry.id);
+  if (idx >= 0) {
+    registry.skills[idx] = { ...registry.skills[idx], ...skillEntry };
+  } else {
+    registry.skills.push(skillEntry);
+  }
+
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+}
+
+/**
+ * 分发单个 skill 到所有本地环境
+ */
+function distributeSkill(skillName, packagedSkillsDir, targetDirs) {
+  const srcDir = path.join(packagedSkillsDir, skillName);
+
+  if (!fs.existsSync(srcDir)) {
+    logError(`Skill 目录不存在: ${srcDir}`);
+    return false;
+  }
+
+  const metadata = parseSkillMetadata(srcDir);
+  if (!metadata || !metadata.name) {
+    logWarning(`无法解析 ${skillName} 的元数据，将使用默认值`);
+  }
+
+  logInfo(`分发 ${skillName}...`);
+  console.log('');
+
+  let successCount = 0;
+
+  for (const target of targetDirs) {
+    try {
+      fs.mkdirSync(target.path, { recursive: true });
+
+      const destDir = path.join(target.path, skillName);
+      const success = copyDirRecursive(srcDir, destDir);
+
+      if (success) {
+        logSuccess(`  → ${target.name}`);
+        logInfo(`     ${destDir}`);
+
+        // 更新 workclaw registry
+        if (target.type === 'workclaw' && target.registryPath) {
+          updateWorkclawRegistry(target.registryPath, skillName, metadata, destDir);
+          logInfo(`     已更新 registry.json`);
+        }
+
+        successCount++;
+      } else {
+        logError(`  → ${target.name} (复制失败)`);
+      }
+    } catch (err) {
+      logError(`  → ${target.name} (错误: ${err.message})`);
+    }
+    console.log('');
+  }
+
+  return successCount > 0;
+}
+
+/**
+ * 清理所有本地环境中的 skills
+ */
+function cleanSkills(targetDirs, skillNames) {
+  logSection('清理本地 Skills');
+
+  for (const target of targetDirs) {
+    logInfo(`清理 ${target.name}...`);
+
+    for (const skillName of skillNames) {
+      const skillDir = path.join(target.path, skillName);
+
+      if (fs.existsSync(skillDir)) {
+        try {
+          fs.rmSync(skillDir, { recursive: true, force: true });
+          logSuccess(`  ✓ 删除 ${skillName}`);
+        } catch (err) {
+          logError(`  ✗ 删除 ${skillName} 失败: ${err.message}`);
+        }
+      }
+    }
+
+    // 清理 workclaw registry
+    if (target.type === 'workclaw' && target.registryPath && fs.existsSync(target.registryPath)) {
+      try {
+        const registry = JSON.parse(fs.readFileSync(target.registryPath, 'utf8'));
+        if (Array.isArray(registry.skills)) {
+          const before = registry.skills.length;
+          registry.skills = registry.skills.filter(s => {
+            return !s || !s.name || !skillNames.includes(s.name);
+          });
+          const after = registry.skills.length;
+
+          if (before !== after) {
+            fs.writeFileSync(target.registryPath, JSON.stringify(registry, null, 2));
+            logSuccess(`  ✓ 清理 registry.json (删除 ${before - after} 个条目)`);
+          }
+        }
+      } catch (err) {
+        logError(`  ✗ 清理 registry.json 失败: ${err.message}`);
+      }
+    }
+
+    console.log('');
+  }
+}
+
+/**
+ * 主函数
+ */
+function main() {
+  const args = process.argv.slice(2);
+  const isClean = args.includes('--clean');
+  const skillArg = args.find(arg => arg.startsWith('--skill='));
+  const specificSkill = skillArg ? skillArg.split('=')[1] : null;
+
+  logSection('本地 Skill 测试工具');
+
+  // 检测项目目录
+  const packageRoot = path.join(__dirname, '..');
+  const packagedSkillsDir = path.join(packageRoot, 'skills');
+
+  if (!fs.existsSync(packagedSkillsDir)) {
+    logError(`Skills 目录不存在: ${packagedSkillsDir}`);
+    process.exit(1);
+  }
+
+  // 检测所有 skills
+  const allSkills = detectSkillNames(packagedSkillsDir);
+
+  if (allSkills.length === 0) {
+    logError('未检测到任何 soke-* skills');
+    process.exit(1);
+  }
+
+  logInfo(`检测到 ${allSkills.length} 个 skills: ${allSkills.join(', ')}`);
+  console.log('');
+
+  // 检测本地 AI Agent 环境
+  const targetDirs = detectLocalAgentDirs();
+
+  if (targetDirs.length === 0) {
+    logError('未检测到任何本地 AI Agent 环境');
+    logInfo('支持的环境:');
+    logInfo('  • workclaw (~/.workclaw/skills/)');
+    logInfo('  • claude (~/.claude/skills/)');
+    logInfo('  • sokeclaw (~/.sokeclaw/openai-agents/workspaces/main/skills/)');
+    logInfo('  • zev (~/.zev/openai-agents/workspaces/main/skills/)');
+    console.log('');
+    logWarning('注意: 此脚本只分发到 Agent skills 目录，不包括全局安装目录');
+    process.exit(1);
+  }
+
+  logInfo(`检测到 ${targetDirs.length} 个本地环境:`);
+  for (const target of targetDirs) {
+    logInfo(`  • ${target.name}`);
+    logInfo(`    ${target.path}`);
+  }
+  console.log('');
+
+  // 清理模式
+  if (isClean) {
+    cleanSkills(targetDirs, allSkills);
+    logSuccess('清理完成！');
+    return;
+  }
+
+  // 确定要分发的 skills
+  const skillsToDistribute = specificSkill
+    ? (allSkills.includes(specificSkill) ? [specificSkill] : [])
+    : allSkills;
+
+  if (skillsToDistribute.length === 0) {
+    logError(`Skill 不存在: ${specificSkill}`);
+    process.exit(1);
+  }
+
+  // 分发 skills
+  logSection('分发 Skills 到本地环境');
+
+  let totalSuccess = 0;
+  let totalFailed = 0;
+
+  for (const skillName of skillsToDistribute) {
+    const success = distributeSkill(skillName, packagedSkillsDir, targetDirs);
+    if (success) {
+      totalSuccess++;
+    } else {
+      totalFailed++;
+    }
+  }
+
+  // 总结
+  logSection('分发完成');
+
+  logInfo(`总计: ${skillsToDistribute.length} 个 skills`);
+  logSuccess(`成功: ${totalSuccess} 个`);
+  if (totalFailed > 0) {
+    logError(`失败: ${totalFailed} 个`);
+  }
+  console.log('');
+
+  // 下一步提示
+  logSection('下一步');
+  console.log('');
+  log('1. 重启你的 AI Agent', 'cyan');
+  log('   • Claude Code: 重启 VS Code 或重新打开 Claude Code 窗口', 'cyan');
+  log('   • Claude Desktop: 重启 Claude Desktop 应用', 'cyan');
+  log('   • Sokeclaw: 重启 sokeclaw 进程', 'cyan');
+  log('   • Zev: 重启 zev 进程', 'cyan');
+  console.log('');
+  log('2. 在对话中测试 skill 功能', 'cyan');
+  log('   例如: "查询课程列表" 或 "查询考试成绩"', 'cyan');
+  console.log('');
+  log('3. 验证命令是否可用:', 'cyan');
+  console.log('');
+  for (const skillName of skillsToDistribute) {
+    log(`   soke-cli ${skillName.replace('soke-', '')} --help`, 'yellow');
+  }
+  console.log('');
+  log('4. 测试完成后，可以清理:', 'cyan');
+  log('   node scripts/local-test.js --clean', 'yellow');
+  console.log('');
+  log('💡 提示:', 'cyan');
+  log('   • 此脚本只分发到 Agent skills 目录', 'cyan');
+  log('   • 全局安装 (npm install -g) 需要单独处理', 'cyan');
+  log('   • 修改后重新运行此脚本即可更新', 'cyan');
+  console.log('');
+}
+
+// 运行
+try {
+  main();
+} catch (err) {
+  logError(`发生错误: ${err.message}`);
+  console.error(err);
+  process.exit(1);
+}

package/scripts/local-test.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+
+# soke-cli 本地测试脚本
+# 用于本地开发测试：编译 -> 安装到全局 -> 验证功能
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}  soke-cli 本地测试${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+# 步骤1: 编译
+echo -e "${YELLOW}[1/4] 编译 soke-cli...${NC}"
+if go build -o soke-cli main.go; then
+    echo -e "${GREEN}✓ 编译成功${NC}"
+else
+    echo -e "${RED}✗ 编译失败${NC}"
+    exit 1
+fi
+echo ""
+
+# 步骤2: 检查本地版本功能
+echo -e "${YELLOW}[2/4] 检查本地版本功能...${NC}"
+echo -e "  检查 learning-profile 模块..."
+if ./soke-cli learning-profile --help &>/dev/null; then
+    echo -e "${GREEN}  ✓ learning-profile 模块存在${NC}"
+else
+    echo -e "${RED}  ✗ learning-profile 模块不存在${NC}"
+    exit 1
+fi
+
+echo -e "  检查 contact +search-dept 命令..."
+if ./soke-cli contact +search-dept --help &>/dev/null; then
+    echo -e "${GREEN}  ✓ contact +search-dept 命令存在${NC}"
+else
+    echo -e "${RED}  ✗ contact +search-dept 命令不存在${NC}"
+    exit 1
+fi
+echo ""
+
+# 步骤3: 安装到全局
+echo -e "${YELLOW}[3/4] 安装到全局...${NC}"
+
+# 查找全局 CLI 路径
+GLOBAL_CLI=$(which soke-cli 2>/dev/null)
+if [ -z "$GLOBAL_CLI" ]; then
+    echo -e "${YELLOW}  未找到全局 soke-cli 安装${NC}"
+    echo -e "${YELLOW}  请先通过 npm 安装: npm install -g @sokeai/cli${NC}"
+    echo -e "${YELLOW}  跳过全局安装，仅测试本地版本${NC}"
+    SKIP_GLOBAL=true
+else
+    echo -e "  全局 CLI 路径: ${BLUE}${GLOBAL_CLI}${NC}"
+
+    # 检查是否需要更新
+    NEED_UPDATE=false
+    if ! $GLOBAL_CLI learning-profile --help &>/dev/null; then
+        echo -e "${YELLOW}  全局版本不支持 learning-profile 模块${NC}"
+        NEED_UPDATE=true
+    elif ! $GLOBAL_CLI contact +search-dept --help &>/dev/null; then
+        echo -e "${YELLOW}  全局版本不支持 contact +search-dept 命令${NC}"
+        NEED_UPDATE=true
+    fi
+
+    if [ "$NEED_UPDATE" = true ]; then
+        echo -e "${YELLOW}  需要更新全局安装${NC}"
+        echo ""
+        echo -e "${YELLOW}  是否要用本地版本覆盖全局安装? (y/n)${NC}"
+        read -r CONFIRM
+
+        if [ "$CONFIRM" = "y" ] || [ "$CONFIRM" = "Y" ]; then
+            # 备份原文件
+            BACKUP_FILE="${GLOBAL_CLI}.backup.$(date +%Y%m%d_%H%M%S)"
+            echo -e "  备份原文件到: ${BACKUP_FILE}"
+            if sudo cp $GLOBAL_CLI $BACKUP_FILE; then
+                echo -e "${GREEN}  ✓ 备份成功${NC}"
+            else
+                echo -e "${RED}  ✗ 备份失败${NC}"
+                exit 1
+            fi
+
+            # 安装新版本
+            echo -e "  安装新版本..."
+            if sudo cp ./soke-cli $GLOBAL_CLI; then
+                echo -e "${GREEN}  ✓ 安装成功${NC}"
+                echo -e "${BLUE}  备份文件: ${BACKUP_FILE}${NC}"
+            else
+                echo -e "${RED}  ✗ 安装失败${NC}"
+                echo -e "${YELLOW}  恢复备份...${NC}"
+                sudo cp $BACKUP_FILE $GLOBAL_CLI
+                exit 1
+            fi
+            SKIP_GLOBAL=false
+        else
+            echo -e "${YELLOW}  跳过全局安装${NC}"
+            SKIP_GLOBAL=true
+        fi
+    else
+        echo -e "${GREEN}  ✓ 全局版本已是最新，无需更新${NC}"
+        SKIP_GLOBAL=false
+    fi
+fi
+echo ""
+
+# 步骤4: 运行测试
+echo -e "${YELLOW}[4/4] 运行功能测试...${NC}"
+
+# 测试本地版本
+echo -e "  ${BLUE}测试本地版本:${NC}"
+if ./soke-cli learning-profile +list --help &>/dev/null; then
+    echo -e "${GREEN}  ✓ learning-profile +list 命令可用${NC}"
+else
+    echo -e "${RED}  ✗ learning-profile +list 命令不可用${NC}"
+    exit 1
+fi
+
+if ./soke-cli contact +search-dept --help &>/dev/null; then
+    echo -e "${GREEN}  ✓ contact +search-dept 命令可用${NC}"
+else
+    echo -e "${RED}  ✗ contact +search-dept 命令不可用${NC}"
+    exit 1
+fi
+
+if ./soke-cli contact +search-user --help &>/dev/null; then
+    echo -e "${GREEN}  ✓ contact +search-user 命令可用${NC}"
+else
+    echo -e "${RED}  ✗ contact +search-user 命令不可用${NC}"
+    exit 1
+fi
+
+# 测试全局版本（如果已安装）
+if [ "$SKIP_GLOBAL" = false ] && [ -n "$GLOBAL_CLI" ]; then
+    echo ""
+    echo -e "  ${BLUE}测试全局版本:${NC}"
+    if $GLOBAL_CLI learning-profile +list --help &>/dev/null; then
+        echo -e "${GREEN}  ✓ learning-profile +list 命令可用${NC}"
+    else
+        echo -e "${RED}  ✗ learning-profile +list 命令不可用${NC}"
+        echo -e "${YELLOW}  提示: 全局安装可能未成功更新${NC}"
+    fi
+
+    if $GLOBAL_CLI contact +search-dept --help &>/dev/null; then
+        echo -e "${GREEN}  ✓ contact +search-dept 命令可用${NC}"
+    else
+        echo -e "${RED}  ✗ contact +search-dept 命令不可用${NC}"
+        echo -e "${YELLOW}  提示: 全局安装可能未成功更新${NC}"
+    fi
+
+    if $GLOBAL_CLI contact +search-user --help &>/dev/null; then
+        echo -e "${GREEN}  ✓ contact +search-user 命令可用${NC}"
+    else
+        echo -e "${RED}  ✗ contact +search-user 命令不可用${NC}"
+        echo -e "${YELLOW}  提示: 全局安装可能未成功更新${NC}"
+    fi
+fi
+echo ""
+
+# 完成
+echo -e "${GREEN}========================================${NC}"
+echo -e "${GREEN}  本地测试完成! ✓${NC}"
+echo -e "${GREEN}========================================${NC}"
+echo ""
+echo -e "${BLUE}下一步:${NC}"
+if [ "$SKIP_GLOBAL" = true ]; then
+    echo -e "  ${YELLOW}提示: 未更新全局安装，Skills 可能无法使用新功能${NC}"
+    echo -e "  ${YELLOW}如需测试 Skills，请重新运行此脚本并选择更新全局安装${NC}"
+    echo ""
+fi
+echo -e "  1. 运行完整测试: ${BLUE}bash ./scripts/e2e-test.sh${NC}"
+echo -e "  2. 测试 Skills: ${BLUE}npx skills add liuchenlong1111/soke-cli -y -g${NC}"
+echo -e "  3. 在 AI Agent 中测试: ${BLUE}\"查询张三的学习档案\"${NC}"
+echo ""
+

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

@@ -0,0 +1,223 @@
+---
+name: soke-learning-profile
+summary: 学员学习档案查询
+version: 1.0.0
+description: "学员学习档案查询：查询学员的完整学习记录，包括课程学习、考试成绩、证书获取、学分积分等。当用户需要查询学员学习档案、查看学员学习情况、统计学员学习数据、查询学员综合学习信息时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli learning-profile --help"
+---
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.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`
+
+---
+
+## 错误处理
+
+### 权限不足
+如果遇到权限错误，参考 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)
+
+### 参数错误
+使用 `--help` 查看命令参数说明：
+```bash
+soke-cli learning-profile +list --help
+```
+
+### 数据为空
+如果查询结果为空，检查：
+1. 筛选条件是否正确（dept_ids, dept_user_ids, is_new）
+2. 学员是否有学习记录
+3. 是否有权限查看该部门/学员的数据
+4. 注意：学习档案接口不支持按姓名查询，需要先获取 dept_user_id