@sokeai/cli 1.3.0 → 1.3.2

package/README.md

@@ -39,6 +39,7 @@
 4. **AI Agent Skills**
    - 提供 AI Agent 技能（Skills），使 AI 助手能够自动发现和调用 CLI 功能。
    - 支持自然语言交互，无需记忆复杂的命令参数。
+   - 支持维护者删除受管 Skill，并通过本地同步与升级安装自动清理废弃 Skill。
 
 ## 安装方法
 
@@ -164,6 +165,28 @@ soke-cli api GET /users/me
 soke-cli api POST /some/endpoint --data '{"key": "value"}'
 ```
 
+### 删除受管 Skill（维护者）
+
+如果你需要从当前仓库中下线一个受管 Skill，可以执行：
+
+```bash
+soke-cli delete-skill soke-business-training-report
+```
+
+删除后再执行：
+
+```bash
+bash ./scripts/local-test.sh
+```
+
+本地 Agent 中由 `soke-cli` 管理的过期 `soke-*` Skills 会被自动清理。客户后续执行：
+
+```bash
+npm install -g @sokeai/cli@latest
+```
+
+也会按当前发布包中的 Skill 集合自动清理废弃的受管 Skill。
+
 ## 开发指南
 
 ### 从接口封装到发布的完整流程

package/package.json

@@ -1,36 +1,36 @@
 {
-    "name": "@sokeai/cli",
-    "version": "1.3.0",
-    "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
-    "bin": {
-        "soke-cli": "scripts/run.js"
-    },
-    "scripts": {
-        "postinstall": "node scripts/install.js",
-        "build": "./scripts/build-binaries.sh",
-        "release": "./scripts/release.sh"
-    },
-    "files": [
-        "scripts/",
-        "skills/"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/liuchenlong1111/soke-cli.git"
-    },
-    "keywords": [
-        "soke",
-        "cli",
-        "授客AI",
-        "shouke",
-        "command-line",
-        "ai-agent",
-        "skills",
-        "claude-code"
-    ],
-    "author": "授客AI",
-    "license": "MIT",
-    "engines": {
-        "node": ">=14.0.0"
-    }
+  "name": "@sokeai/cli",
+  "version": "1.3.2",
+  "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
+  "bin": {
+    "soke-cli": "scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "build": "./scripts/build-binaries.sh",
+    "release": "./scripts/release.sh"
+  },
+  "files": [
+    "scripts/",
+    "skills/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/liuchenlong1111/soke-cli.git"
+  },
+  "keywords": [
+    "soke",
+    "cli",
+    "授客AI",
+    "shouke",
+    "command-line",
+    "ai-agent",
+    "skills",
+    "claude-code"
+  ],
+  "author": "授客AI",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  }
 }

package/scripts/build-binaries.sh

@@ -42,7 +42,10 @@ fi
 export SOKE_CLIENT_ID SOKE_CLIENT_SECRET
 
 # 编译参数
-LDFLAGS="-s -w -X main.Version=${VERSION}"
+# -X 注入路径必须匹配 internal/version.Version 所在包,
+# 此前误写为 main.Version,导致 --version 始终落回 checker.go 里
+# 的 hardcoded 默认值。
+LDFLAGS="-s -w -X codeup.aliyun.com/5edbc121d1d1abe63b55f1c7/soke/soke-cli/internal/version.Version=${VERSION}"
 
 # 创建输出目录
 BIN_DIR="bin"

package/scripts/install.js

@@ -107,6 +107,46 @@ function detectSkillNames(packagedSkillsDir) {
   }
 }
 
+function removeManagedSkillDir(targetDir, skillName) {
+  const dest = path.join(targetDir, skillName);
+  if (!fs.existsSync(dest)) return false;
+  try {
+    fs.rmSync(dest, { recursive: true, force: true });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function pruneManagedSkillDirs(targetDir, expectedSkillNames) {
+  if (!fs.existsSync(targetDir)) return [];
+  try {
+    const entries = fs.readdirSync(targetDir, { withFileTypes: true });
+    const removed = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !entry.name.startsWith('soke-')) continue;
+      if (expectedSkillNames.includes(entry.name)) continue;
+      if (removeManagedSkillDir(targetDir, entry.name)) {
+        removed.push(entry.name);
+      }
+    }
+    return removed;
+  } catch (_) {
+    return [];
+  }
+}
+
+function pruneRegistrySkills(registry, expectedSkillNames) {
+  if (!registry || !Array.isArray(registry.skills)) return 0;
+  const before = registry.skills.length;
+  registry.skills = registry.skills.filter((entry) => {
+    if (!entry || typeof entry.name !== 'string') return true;
+    if (!entry.name.startsWith('soke-')) return true;
+    return expectedSkillNames.includes(entry.name);
+  });
+  return before - registry.skills.length;
+}
+
 function syncSkillsToSokeclawWorkspace() {
   const packageRoot = path.join(__dirname, '..');
   const packagedSkillsDir = path.join(packageRoot, 'skills');
@@ -118,6 +158,7 @@ function syncSkillsToSokeclawWorkspace() {
   for (const targetDir of targetDirs) {
     try {
       fs.mkdirSync(targetDir, { recursive: true });
+      pruneManagedSkillDirs(targetDir, skillNames);
       for (const skillName of skillNames) {
         const src = path.join(packagedSkillsDir, skillName);
         const dest = path.join(targetDir, skillName);
@@ -263,6 +304,9 @@ function syncSkillsToWorkclawRegistry() {
     if (fs.existsSync(src)) copyDirRecursive(src, dest);
   }
 
+  pruneManagedSkillDirs(workclawSkillInstallDir, skillNames);
+  pruneRegistrySkills(registry, skillNames);
+
   // 自动注册所有 skills
   for (const skillName of skillNames) {
     const skillDir = path.join(packagedSkillsDir, skillName);
@@ -418,29 +462,19 @@ const archMap = {
 const mappedPlatform = platformMap[platform];
 const mappedArch = archMap[arch];
 
-if (!mappedPlatform || !mappedArch) {
-  console.error(`不支持的平台: ${platform}-${arch}`);
-  console.error('支持的平台: darwin-x64, darwin-arm64, linux-x64, windows-x64');
-  process.exit(1);
-}
-
 const binaryName = platform === 'win32' ? 'soke-cli.exe' : 'soke-cli';
-const binaryFileName = `soke-cli-${mappedPlatform}-${mappedArch}${platform === 'win32' ? '.exe' : ''}`;
+const binaryFileName = mappedPlatform && mappedArch
+  ? `soke-cli-${mappedPlatform}-${mappedArch}${platform === 'win32' ? '.exe' : ''}`
+  : '';
 
 // GitHub Releases 下载地址
-const downloadURL = `https://github.com/liuchenlong1111/soke-cli/releases/download/v${version}/${binaryFileName}`;
+const downloadURL = binaryFileName
+  ? `https://github.com/liuchenlong1111/soke-cli/releases/download/v${version}/${binaryFileName}`
+  : '';
 
 const binDir = path.join(__dirname, '..', 'bin');
 const binaryPath = path.join(binDir, binaryName);
 
-console.log(`正在为 ${mappedPlatform}-${mappedArch} 下载 soke-cli v${version}...`);
-console.log(`下载地址: ${downloadURL}`);
-
-// 创建 bin 目录
-if (!fs.existsSync(binDir)) {
-  fs.mkdirSync(binDir, { recursive: true });
-}
-
 // 下载文件
 function downloadFile(url, dest) {
   return new Promise((resolve, reject) => {
@@ -492,6 +526,19 @@ function downloadFile(url, dest) {
 
 // 执行下载
 if (require.main === module) {
+  if (!mappedPlatform || !mappedArch) {
+    console.error(`不支持的平台: ${platform}-${arch}`);
+    console.error('支持的平台: darwin-x64, darwin-arm64, linux-x64, windows-x64');
+    process.exit(1);
+  }
+
+  console.log(`正在为 ${mappedPlatform}-${mappedArch} 下载 soke-cli v${version}...`);
+  console.log(`下载地址: ${downloadURL}`);
+
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true });
+  }
+
   downloadFile(downloadURL, binaryPath)
     .then(() => {
       // 设置可执行权限（非 Windows 平台）
@@ -535,6 +582,10 @@ if (require.main === module) {
 }
 
 module.exports = {
+  detectSkillNames,
+  parseSkillMetadata,
+  pruneManagedSkillDirs,
+  pruneRegistrySkills,
   syncSkillsToSokeclawWorkspace,
   syncSkillsToWorkclawRegistry
 };

package/scripts/local-test.js

@@ -104,6 +104,46 @@ function detectSkillNames(packagedSkillsDir) {
   }
 }
 
+function removeManagedSkillDir(targetDir, skillName) {
+  const skillDir = path.join(targetDir, skillName);
+  if (!fs.existsSync(skillDir)) return false;
+  try {
+    fs.rmSync(skillDir, { recursive: true, force: true });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function pruneManagedSkillDirs(targetDir, expectedSkillNames) {
+  if (!fs.existsSync(targetDir)) return [];
+  try {
+    const entries = fs.readdirSync(targetDir, { withFileTypes: true });
+    const removed = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !entry.name.startsWith('soke-')) continue;
+      if (expectedSkillNames.includes(entry.name)) continue;
+      if (removeManagedSkillDir(targetDir, entry.name)) {
+        removed.push(entry.name);
+      }
+    }
+    return removed;
+  } catch (_) {
+    return [];
+  }
+}
+
+function pruneRegistrySkills(registry, expectedSkillNames) {
+  if (!registry || !Array.isArray(registry.skills)) return 0;
+  const before = registry.skills.length;
+  registry.skills = registry.skills.filter((entry) => {
+    if (!entry || typeof entry.name !== 'string') return true;
+    if (!entry.name.startsWith('soke-')) return true;
+    return expectedSkillNames.includes(entry.name);
+  });
+  return before - registry.skills.length;
+}
+
 /**
  * 从 SKILL.md 解析元数据
  */
@@ -226,6 +266,7 @@ function detectLocalAgentDirs() {
  * 更新 workclaw registry.json
  */
 function updateWorkclawRegistry(registryPath, skillName, metadata, skillInstallPath) {
+  const safeMetadata = metadata && typeof metadata === 'object' ? metadata : {};
   let registry;
 
   try {
@@ -238,11 +279,11 @@ function updateWorkclawRegistry(registryPath, skillName, metadata, skillInstallP
   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 displayName = safeMetadata.summary || safeMetadata.name || skillName;
+  const description = safeMetadata.description || `${displayName} - 授客AI CLI工具`;
+  const version = safeMetadata.version || '1.0.0';
   const emoji = inferSkillEmoji(skillName);
-  const requires = metadata.bins ? { bins: metadata.bins } : {};
+  const requires = safeMetadata.bins ? { bins: safeMetadata.bins } : {};
 
   const skillEntry = {
     id: `skill:${skillName}`,
@@ -323,6 +364,26 @@ function distributeSkill(skillName, packagedSkillsDir, targetDirs) {
   return successCount > 0;
 }
 
+function reconcileTarget(target, expectedSkillNames) {
+  const removedDirs = pruneManagedSkillDirs(target.path, expectedSkillNames);
+  if (removedDirs.length > 0) {
+    logInfo(`  清理过期 skills: ${removedDirs.join(', ')}`);
+  }
+
+  if (target.type === 'workclaw' && target.registryPath && fs.existsSync(target.registryPath)) {
+    try {
+      const registry = JSON.parse(fs.readFileSync(target.registryPath, 'utf8'));
+      const removedEntries = pruneRegistrySkills(registry, expectedSkillNames);
+      if (removedEntries > 0) {
+        fs.writeFileSync(target.registryPath, JSON.stringify(registry, null, 2));
+        logInfo(`  清理 registry 过期条目: ${removedEntries}`);
+      }
+    } catch (err) {
+      logError(`  ✗ 清理 registry 失败: ${err.message}`);
+    }
+  }
+}
+
 /**
  * 清理所有本地环境中的 skills
  */
@@ -455,6 +516,10 @@ function main() {
     }
   }
 
+  for (const target of targetDirs) {
+    reconcileTarget(target, allSkills);
+  }
+
   // 总结
   logSection('分发完成');
 
@@ -493,11 +558,21 @@ function main() {
   console.log('');
 }
 
+module.exports = {
+  detectSkillNames,
+  parseSkillMetadata,
+  pruneManagedSkillDirs,
+  pruneRegistrySkills,
+  updateWorkclawRegistry
+};
+
 // 运行
-try {
-  main();
-} catch (err) {
-  logError(`发生错误: ${err.message}`);
-  console.error(err);
-  process.exit(1);
+if (require.main === module) {
+  try {
+    main();
+  } catch (err) {
+    logError(`发生错误: ${err.message}`);
+    console.error(err);
+    process.exit(1);
+  }
 }

package/scripts/local-test.sh

@@ -109,34 +109,15 @@ echo ""
 
 # 步骤3.5: 分发 Skills 到本地 Agent
 echo -e "${YELLOW}[3.5/4] 分发 Skills 到本地 Agent...${NC}"
-if [ "$SKIP_GLOBAL" = false ]; then
-    echo -e "  执行 scripts/install.js 同步 Skills..."
-    
-    # 使用 node 调用 install.js 中导出的同步函数
-    cat > ./scripts/sync-skills-local.js << 'EOF'
-const install = require('./install.js');
-
-try {
-  console.log("  同步到 Sokeclaw Workspace...");
-  install.syncSkillsToSokeclawWorkspace();
-  console.log("  ✓ Sokeclaw Workspace 同步成功");
-} catch (e) {
-  console.error("  ✗ Sokeclaw Workspace 同步失败:", e.message);
-}
-
-try {
-  console.log("  同步到 Workclaw Registry...");
-  install.syncSkillsToWorkclawRegistry();
-  console.log("  ✓ Workclaw Registry 同步成功");
-} catch (e) {
-  console.error("  ✗ Workclaw Registry 同步失败:", e.message);
-}
-EOF
-    node ./scripts/sync-skills-local.js
-    rm ./scripts/sync-skills-local.js
+echo -e "  执行 scripts/local-test.js 同步并清理本地 Agent Skills..."
+if node ./scripts/local-test.js; then
     echo -e "${GREEN}  ✓ Skills 同步完成${NC}"
+    if [ "$SKIP_GLOBAL" = true ]; then
+        echo -e "${YELLOW}  提示: 已跳过全局 CLI 覆盖，但本地 Agent Skills 已按当前仓库状态完成同步${NC}"
+    fi
 else
-    echo -e "${YELLOW}  跳过全局安装，同时跳过 Skills 同步${NC}"
+    echo -e "${RED}  ✗ Skills 同步失败${NC}"
+    exit 1
 fi
 echo ""
 
@@ -197,4 +178,3 @@ echo ""
 echo -e "${GREEN}========================================${NC}"
 echo -e "${GREEN}  本地测试完成! ✓${NC}"
 echo -e "${GREEN}========================================${NC}"
-

package/scripts/test-auto-detect.js

@@ -5,66 +5,14 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
-
-// 复制 detectSkillNames 函数
-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 [];
-  }
-}
-
-// 复制 parseSkillMetadata 函数
-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;
-  }
-}
+const {
+  detectSkillNames,
+  parseSkillMetadata,
+  pruneManagedSkillDirs,
+  pruneRegistrySkills
+} = require('./install.js');
 
 // 测试
 const packageRoot = path.join(__dirname, '..');
@@ -102,19 +50,13 @@ for (const skillName of skillNames) {
 // 验证结果
 console.log('📊 验证结果:\n');
 
-const expectedSkills = ['soke-course', 'soke-exam', 'soke-shared'];
-const missingSkills = expectedSkills.filter(s => !skillNames.includes(s));
-const extraSkills = skillNames.filter(s => !expectedSkills.includes(s));
-
-if (missingSkills.length > 0) {
-  console.log(`❌ 缺少的 skills: ${missingSkills.join(', ')}`);
-} else {
-  console.log('✅ 所有预期的 skills 都已检测到');
-}
-
-if (extraSkills.length > 0) {
-  console.log(`ℹ️  额外的 skills: ${extraSkills.join(', ')}`);
+const requiredSkills = ['soke-shared'];
+const missingRequiredSkills = requiredSkills.filter(s => !skillNames.includes(s));
+if (missingRequiredSkills.length > 0) {
+  console.log(`❌ 缺少基础 skills: ${missingRequiredSkills.join(', ')}`);
+  process.exit(1);
 }
+console.log('✅ 基础 skills 检测通过');
 
 console.log('');
 console.log('🎉 测试完成！');
@@ -123,3 +65,38 @@ console.log('💡 提示:');
 console.log('   - 新增 skill 时，只需在 skills/ 目录下创建 soke-* 目录');
 console.log('   - 确保每个 skill 都有 SKILL.md 文件，包含完整的 frontmatter');
 console.log('   - install.js 会自动检测并注册所有 skills');
+
+// 验证清理逻辑
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'soke-skill-prune-'));
+const targetDir = path.join(tempRoot, 'skills');
+fs.mkdirSync(targetDir, { recursive: true });
+fs.mkdirSync(path.join(targetDir, 'soke-stale'));
+fs.mkdirSync(path.join(targetDir, 'soke-course'));
+fs.mkdirSync(path.join(targetDir, 'custom-skill'));
+
+const removedDirs = pruneManagedSkillDirs(targetDir, ['soke-course']);
+if (!removedDirs.includes('soke-stale')) {
+  console.error('❌ pruneManagedSkillDirs 未删除过期 managed skill');
+  process.exit(1);
+}
+if (!fs.existsSync(path.join(targetDir, 'custom-skill'))) {
+  console.error('❌ pruneManagedSkillDirs 错误删除了非受管 skill');
+  process.exit(1);
+}
+
+const registry = {
+  skills: [
+    { name: 'soke-stale' },
+    { name: 'soke-course' },
+    { name: 'custom-skill' }
+  ]
+};
+const removedEntries = pruneRegistrySkills(registry, ['soke-course']);
+if (removedEntries !== 1) {
+  console.error('❌ pruneRegistrySkills 未正确移除过期条目');
+  process.exit(1);
+}
+if (!registry.skills.find((entry) => entry.name === 'custom-skill')) {
+  console.error('❌ pruneRegistrySkills 错误移除了非受管条目');
+  process.exit(1);
+}

package/scripts/test-local-reconcile.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  pruneManagedSkillDirs,
+  pruneRegistrySkills,
+  updateWorkclawRegistry
+} = require('./local-test.js');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'soke-local-reconcile-'));
+const targetDir = path.join(tempRoot, 'skills');
+fs.mkdirSync(targetDir, { recursive: true });
+
+fs.mkdirSync(path.join(targetDir, 'soke-stale'));
+fs.mkdirSync(path.join(targetDir, 'soke-exam'));
+fs.mkdirSync(path.join(targetDir, 'custom-skill'));
+
+const removedDirs = pruneManagedSkillDirs(targetDir, ['soke-exam']);
+if (!removedDirs.includes('soke-stale')) {
+  console.error('❌ stale managed skill was not removed');
+  process.exit(1);
+}
+if (!fs.existsSync(path.join(targetDir, 'custom-skill'))) {
+  console.error('❌ unmanaged local skill should remain untouched');
+  process.exit(1);
+}
+
+const registry = {
+  skills: [
+    { name: 'soke-stale' },
+    { name: 'soke-exam' },
+    { name: 'custom-skill' }
+  ]
+};
+const removedEntries = pruneRegistrySkills(registry, ['soke-exam']);
+if (removedEntries !== 1) {
+  console.error('❌ registry stale entry removal failed');
+  process.exit(1);
+}
+if (!registry.skills.find((entry) => entry.name === 'custom-skill')) {
+  console.error('❌ unmanaged registry entry should remain untouched');
+  process.exit(1);
+}
+
+const registryPath = path.join(tempRoot, 'registry.json');
+updateWorkclawRegistry(registryPath, 'soke-contact', null, '/tmp/soke-contact');
+const updatedRegistry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+if (!updatedRegistry.skills.find((entry) => entry.name === 'soke-contact')) {
+  console.error('❌ registry update should tolerate missing metadata');
+  process.exit(1);
+}
+
+console.log('✅ local reconciliation tests passed');

package/skills/soke-exam/SKILL.md

@@ -1,319 +0,0 @@
----
-name: soke-exam
-summary: 授客考试管理（考试列表/分类/考试用户成绩/详情），通过 soke-cli 查询
-version: 1.0.0
-description: "授客考试管理：查询考试、考试用户和成绩。查询考试列表、考试分类、考试用户成绩、考试详情。当用户需要查询考试成绩、查看考试列表、查询考试用户信息、查看考试分类时使用。"
-requiredAuthorizations: [{"platformId":"soke-ai"}]
-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

@@ -1,212 +0,0 @@
-# +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（如果考试未完成或未提交）