@sokeai/cli 1.2.2 → 1.3.1

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,6 +1,6 @@
 {
     "name": "@sokeai/cli",
-    "version": "1.2.2",
+    "version": "1.3.1",
     "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
     "bin": {
         "soke-cli": "scripts/run.js"

package/scripts/build-binaries.sh

@@ -15,8 +15,37 @@ NC='\033[0m' # No Color
 VERSION=$(node -p "require('./package.json').version")
 echo -e "${GREEN}开始编译 soke-cli v${VERSION}${NC}"
 
+# task 11.2 — OAuth 凭证通过 env 注入(替代原 sed 改 Go 源的方式)。
+#
+# 重要:vendor.yaml 的 ${SOKE_CLIENT_ID} / ${SOKE_CLIENT_SECRET} 由
+# sokeai/provider.go 在 init() 阶段 Interpolate,**取的是产物运行时的 env**,
+# 而不是 build 期。因此:
+#
+#   * 本地开发:用户在 shell 里 export SOKE_CLIENT_ID / SOKE_CLIENT_SECRET,
+#     然后 go run / 已 build 的 ./bin/soke-cli 启动时 init() 取到。
+#   * Release 二进制:client_id / client_secret 不在 build 阶段嵌入产物。
+#     发版 CI 应当在制作 NPM 包时附带一个 wrapper(scripts/run.js)在启动
+#     soke-cli 前 setenv 注入(具体方式由 release-lead 在发版 CI 里定),
+#     或要求最终用户自己 export(仅适用于内部分发场景)。
+#
+# 本脚本只做 sanity check + 把当前 shell env 透传到 go build(用于自动化
+# 测试场景中,build 后立即跑 ./bin/soke-cli auth login 走流程)。
+if [ -z "${SOKE_CLIENT_ID:-}" ] || [ -z "${SOKE_CLIENT_SECRET:-}" ]; then
+    if [ "${SOKE_CLI_RELEASE:-}" = "1" ]; then
+        echo -e "${RED}[FATAL] release 模式必须设置 SOKE_CLIENT_ID / SOKE_CLIENT_SECRET${NC}"
+        echo -e "${RED}        二进制本身不嵌入凭证,run.js wrapper 也需要相应的注入逻辑${NC}"
+        exit 1
+    fi
+    echo -e "${YELLOW}[警告] SOKE_CLIENT_ID / SOKE_CLIENT_SECRET 未设置;${NC}"
+    echo -e "${YELLOW}        本地 build 后直接 ./bin/soke-cli auth login 会 fail-fast。${NC}"
+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/ci/check-legacy-constants.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# task 9.1 — 拦截误引入的 dws-cli upstream 旧常量。
+#
+# 故意提一个引入旧常量的 bad PR 时,CI 该步骤应当失败。
+# 允许出现在 openspec/ 历史 doc 与 docs/dead-code-audit-*.md。
+#
+# 用法:bash scripts/ci/check-legacy-constants.sh
+
+set -euo pipefail
+
+PATTERN='OpenDevURL\|AuthorizeURL\|DefaultMCPBaseURL\|DefaultClientID\|DefaultClientSecret\|<YOUR_CLIENT_'
+
+# 只扫源码目录;openspec/docs/scripts 历史档案允许出现。
+hits=$(grep -rn -E "$PATTERN" cmd/ internal/ extension/ 2>/dev/null \
+  | grep -v vendorplugin/ \
+  | grep -v "_test.go" \
+  || true)
+
+if [ -n "$hits" ]; then
+  echo "[FAIL] 检测到 dws-cli 旧常量残留:"
+  echo "$hits"
+  echo
+  echo "请改用 vendor.Active().Endpoints() / OAuth() 读取(见 cmd/user_auth/vendor.go)。"
+  exit 1
+fi
+
+echo "[OK] 无 dws-cli 旧常量残留。"

package/scripts/ci/check-yaml-env-whitelist.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# task 9.2 — 校验 extension/vendorplugin/builtin/**/vendor.yaml 内 ${VAR}
+# 占位符全部符合白名单(^SOKE_[A-Z0-9_]+$)。
+#
+# 故意写一个 ${HOME} 进 vendor.yaml 时,本步骤应当 FAIL。
+#
+# 用法:bash scripts/ci/check-yaml-env-whitelist.sh
+
+set -euo pipefail
+
+WHITELIST_RE='^SOKE_[A-Z0-9_]+$'
+fail=0
+
+for yaml in $(find extension/vendorplugin/builtin -name vendor.yaml 2>/dev/null); do
+  # 抽出所有 ${...} 占位符内层内容(去掉默认值部分)
+  vars=$(grep -oE '\$\{[^{}]+\}' "$yaml" \
+    | sed -E 's/^\$\{([^:}]+)(:-[^}]*)?\}$/\1/' \
+    | sort -u)
+  for v in $vars; do
+    if ! echo "$v" | grep -qE "$WHITELIST_RE"; then
+      echo "[FAIL] $yaml 引用了非白名单 env: $v"
+      fail=1
+    fi
+  done
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo
+  echo "白名单规则:^SOKE_[A-Z0-9_]+\$(见 extension/vendorplugin/env_whitelist.go)"
+  exit 1
+fi
+
+echo "[OK] 所有 vendor.yaml 内 \${VAR} 占位符均符合 SOKE_* 白名单。"

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/mcp-stdout-scan.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# mcp-stdout-scan.sh — openspec change make-soke-cli-mcp-first §10.3
+#
+# 静态扫描 internal/mcp/ / extension/vendor/builtin/ / internal/courseimport/ 三个
+# 与 mcp stdio 帧纯净性相关的代码树,拦下任何会污染 stdout JSON-RPC 帧的调用:
+#   - fmt.Println / fmt.Printf / fmt.Print
+#   - fmt.Fprintln / Fprintf / Fprint to os.Stdout
+#   - os.Stdout.Write*
+#   - 顶层 print( / println( 内建函数
+#
+# 排除 _test.go (测试代码允许写 stdout);
+# 通过 sed 把 `// ...` 注释剥掉再 grep,避免文档/注释里提到 fmt.Println 触发 false positive。
+#
+# 用法: bash scripts/mcp-stdout-scan.sh
+# 退出码: 0 = 干净;1 = 有命中(并打到 stderr)。
+
+set -e
+
+ROOTS="internal/mcp extension/vendor/builtin internal/courseimport"
+PATTERN='fmt\.(Println|Printf|Print\()|fmt\.(Fprintln|Fprintf|Fprint)\(os\.Stdout|os\.Stdout\.Write|^[[:space:]]*(print|println)\('
+
+have_hits=0
+for d in $ROOTS; do
+  if [ ! -d "$d" ]; then
+    echo "skip 不存在的目录 $d"
+    continue
+  fi
+  files=$(find "$d" -name '*.go' ! -name '*_test.go' 2>/dev/null)
+  for f in $files; do
+    # 把行号前缀附在文件内容上, 再用 sed 剥 // 注释 (单行注释一律剥), 再 grep
+    hits=$(awk '{ printf "%s:%d:%s\n", FILENAME, NR, $0 }' "$f" \
+           | sed 's_//.*$__' \
+           | grep -E "$PATTERN" \
+           || true)
+    if [ -n "$hits" ]; then
+      echo "❌ $f 检测到 stdout-write 调用 (会破坏 mcp stdio JSON-RPC 帧):" >&2
+      echo "$hits" >&2
+      have_hits=1
+    fi
+  done
+done
+
+if [ "$have_hits" -eq 1 ]; then
+  exit 1
+fi
+echo "✓ stdout 纯净性扫描通过"

package/scripts/regress-auth.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# 回归 auth 命令体感 — task 8.1
+#
+# 串行跑:
+#   1. auth status --json   (预期未登录)
+#   2. auth login            (人工:浏览器跳转 + 真账号授权)
+#   3. auth status --json   (预期已登录)
+#   4. auth logout
+#   5. auth status --json   (预期未登录)
+#
+# 用法:
+#   SOKE_CLIENT_ID=... SOKE_CLIENT_SECRET=... bash scripts/regress-auth.sh
+#   首次运行前 build:make install 或 go build -o bin/soke-cli main.go
+#
+# 输出建议用 tee 保存,事后人工对比 baseline:
+#   bash scripts/regress-auth.sh 2>&1 | tee /tmp/regress-after.txt
+#   diff /tmp/regress-before.txt /tmp/regress-after.txt
+
+set -u
+
+BIN="${SOKE_CLI_BIN:-./bin/soke-cli}"
+if [ ! -x "$BIN" ]; then
+  BIN="$(command -v soke-cli 2>/dev/null || echo "$BIN")"
+fi
+
+if [ ! -x "$BIN" ]; then
+  echo "[FATAL] 找不到 soke-cli 二进制(尝试 SOKE_CLI_BIN env 指定路径)" >&2
+  exit 2
+fi
+
+run_step() {
+  local label="$1"; shift
+  echo
+  echo "==== [$label] $* ===="
+  "$@"
+  local rc=$?
+  echo "==== [$label] exit=$rc ===="
+  return $rc
+}
+
+# baseline 时间戳 mask:让 diff 忽略 expires_at / iat / nbf / exp 等时间字段。
+mask_timestamps() {
+  sed -E 's/("(expires_at|iat|nbf|exp|access_token|refresh_token)":\s*)"[^"]*"/\1"<masked>"/g'
+}
+
+run_step "1.before-status" "$BIN" auth status --json | mask_timestamps
+echo
+echo "请在浏览器完成授权后按回车继续…"
+run_step "2.login" "$BIN" auth login
+read -r _
+run_step "3.after-login-status" "$BIN" auth status --json | mask_timestamps
+run_step "4.logout" "$BIN" auth logout
+run_step "5.final-status" "$BIN" auth status --json | mask_timestamps
+
+echo
+echo "[done] 完成。请人工对比 baseline diff(/tmp/regress-before.txt)。"

package/scripts/regress-baseline.md

@@ -0,0 +1,84 @@
+# auth 回归 baseline 流程(task 8.2)
+
+> 配套脚本:`scripts/regress-auth.sh`
+> 用途:在本 change 引入前后两次跑同一脚本,diff 验证零回归。
+
+## 1. baseline 采样(本 change 引入**前**)
+
+在 master 或上一个 release tag 下:
+
+```bash
+git checkout <last-release-tag>
+make install   # 或:go build -o bin/soke-cli main.go
+SOKE_CLIENT_ID=... SOKE_CLIENT_SECRET=... \
+  bash scripts/regress-auth.sh 2>&1 | tee /tmp/regress-before.txt
+```
+
+`/tmp/regress-before.txt` 即 baseline,包含:
+- 各步 stdout/stderr
+- 各步 exit code(脚本内 `==== [label] exit=N ====` 行)
+- timestamps 已 mask,仅保留结构性差异
+
+## 2. 引入后采样
+
+切到本 change 分支,重新 build 跑一次:
+
+```bash
+git checkout worktree-generalize-vendor-plugin
+make install
+SOKE_CLIENT_ID=... SOKE_CLIENT_SECRET=... \
+  bash scripts/regress-auth.sh 2>&1 | tee /tmp/regress-after.txt
+```
+
+## 3. diff
+
+```bash
+diff /tmp/regress-before.txt /tmp/regress-after.txt
+```
+
+期望:**无差异**(允许时间戳 mask 后的剩余 token 字段差异,因每次实际签发的
+token bytes 不同 —— 但 mask 应已覆盖)。
+
+若 diff 显示行为变化,本 change 视为引入回归,**禁止 merge**,
+回到代码层检查 ClientID() / Endpoints() / CallbackPath 取值路径。
+
+## 4. keychain 字段验证(任选其一,平台相关)
+
+macOS:
+```bash
+security find-generic-password -s "soke-cli" -g 2>&1 | grep -E "acct|cdat"
+```
+
+Linux(libsecret):
+```bash
+secret-tool search service soke-cli
+```
+
+字段名(`access_token` / `refresh_token` 等)与 baseline 完全一致。
+
+## 5. 三平台 matrix(task 8.3)
+
+本 change 不接入 GH Actions yml(避免 PR 卡在未跑通的 CI 任务),由 ①
+`make-soke-cli-mcp-first` 在 same release 时一并引入。matrix 草案:
+
+```yaml
+# .github/workflows/regress-auth.yml(草案,在 ① 同 release 一起合)
+strategy:
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]
+jobs:
+  regress:
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with: { go-version: '1.25' }
+      - run: |
+          go build -o bin/soke-cli main.go
+          # auth login 需要真账号,CI 内只跑 status / logout 路径
+          ./bin/soke-cli auth status --json
+          ./bin/soke-cli auth logout
+          ./bin/soke-cli auth status --json
+```
+
+跑出 CI matrix 三个 job 全绿,本 change 才视为通过 task 8.3 AC。

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（如果考试未完成或未提交）