@sokeai/cli 1.0.20 → 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.20",
+    "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/install.js

@@ -89,13 +89,31 @@ function detectSokeclawWorkspaceSkillsDirs() {
   return dirs;
 }
 
+/**
+ * 自动检测 skills 目录中的所有 skill
+ * 只包含以 'soke-' 开头的目录
+ */
+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 [];
+  }
+}
+
 function syncSkillsToSokeclawWorkspace() {
   const packageRoot = path.join(__dirname, '..');
   const packagedSkillsDir = path.join(packageRoot, 'skills');
   if (!fs.existsSync(packagedSkillsDir)) return;
 
   const targetDirs = detectSokeclawWorkspaceSkillsDirs();
-  const skillNames = ['soke-shared', 'soke-exam'];
+  const skillNames = detectSkillNames(packagedSkillsDir);
 
   for (const targetDir of targetDirs) {
     try {
@@ -126,6 +144,76 @@ function upsertSkillRegistryEntry(registry, entry) {
   registry.skills.push(entry);
 }
 
+/**
+ * 从 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');
+
+    // 解析 frontmatter (YAML)
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) return null;
+
+    const frontmatter = frontmatterMatch[1];
+    const metadata = {};
+
+    // 解析 name
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    if (nameMatch) metadata.name = nameMatch[1].trim();
+
+    // 解析 summary (用作 displayName)
+    const summaryMatch = frontmatter.match(/^summary:\s*(.+)$/m);
+    if (summaryMatch) metadata.summary = summaryMatch[1].trim();
+
+    // 解析 description
+    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();
+    }
+
+    // 解析 version
+    const versionMatch = frontmatter.match(/^version:\s*(.+)$/m);
+    if (versionMatch) metadata.version = versionMatch[1].trim();
+
+    // 解析 metadata.requires.bins
+    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] || '📦';
+}
+
 function syncSkillsToWorkclawRegistry() {
   const homeDir = os.homedir();
   const workclawRootDir = path.join(homeDir, '.workclaw');
@@ -165,48 +253,50 @@ function syncSkillsToWorkclawRegistry() {
       ? existingSkills[0].source.type
       : 'local';
 
-  const skillNames = ['soke-shared', 'soke-exam'];
+  // 自动检测所有 skills
+  const skillNames = detectSkillNames(packagedSkillsDir);
+
+  // 复制所有 skills
   for (const skillName of skillNames) {
     const src = path.join(packagedSkillsDir, skillName);
     const dest = path.join(workclawSkillInstallDir, skillName);
     if (fs.existsSync(src)) copyDirRecursive(src, dest);
   }
 
-  upsertSkillRegistryEntry(registry, {
-    id: 'skill:soke-exam',
-    name: 'soke-exam',
-    displayName: '授客考试管理',
-    description: '授客考试管理：查询考试、考试分类、考试用户成绩、考试详情。',
-    source: { type: defaultSourceType, slug: '', url: '' },
-    install: {
-      path: path.join(workclawSkillInstallDir, 'soke-exam'),
-      installedAt: '',
-      updatedAt: '',
-      version: '1.0.0'
-    },
-    state: { enabled: true, health: 'ok', lastError: '' },
-    runtime: { supported: ['openclaw'], enabled: ['openclaw'], primary: 'openclaw' },
-    security: { riskLevel: 'normal', requiresApproval: false },
-    metadata: { emoji: '📝', homepage: '', requires: { bins: ['soke-cli'] } }
-  });
+  // 自动注册所有 skills
+  for (const skillName of skillNames) {
+    const skillDir = path.join(packagedSkillsDir, skillName);
+    const metadata = parseSkillMetadata(skillDir);
 
-  upsertSkillRegistryEntry(registry, {
-    id: 'skill:soke-shared',
-    name: 'soke-shared',
-    displayName: 'soke-shared 共享规则',
-    description: '授客CLI共享基础：配置、登录、权限管理、错误处理、安全规则。',
-    source: { type: defaultSourceType, slug: '', url: '' },
-    install: {
-      path: path.join(workclawSkillInstallDir, 'soke-shared'),
-      installedAt: '',
-      updatedAt: '',
-      version: '1.0.0'
-    },
-    state: { enabled: true, health: 'ok', lastError: '' },
-    runtime: { supported: ['openclaw'], enabled: ['openclaw'], primary: 'openclaw' },
-    security: { riskLevel: 'normal', requiresApproval: false },
-    metadata: { emoji: '🔧', homepage: '', requires: {} }
-  });
+    if (!metadata || !metadata.name) {
+      console.warn(`警告: 无法解析 ${skillName} 的元数据，跳过注册`);
+      continue;
+    }
+
+    const displayName = metadata.summary || metadata.name;
+    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 } : {};
+
+    upsertSkillRegistryEntry(registry, {
+      id: `skill:${skillName}`,
+      name: skillName,
+      displayName: displayName,
+      description: description,
+      source: { type: defaultSourceType, slug: '', url: '' },
+      install: {
+        path: path.join(workclawSkillInstallDir, skillName),
+        installedAt: '',
+        updatedAt: '',
+        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 }
+    });
+  }
 
   try {
     fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));

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 ""