@mison/wecom-cleaner 1.3.0 → 1.3.3

package/src/config.js

@@ -11,6 +11,9 @@ const ALLOWED_EXTERNAL_ROOT_SOURCES = new Set(['preset', 'configured', 'auto', '
 const ALLOWED_GOVERNANCE_TIERS = new Set(['safe', 'caution', 'protected']);
 const ALLOWED_UPGRADE_METHODS = new Set(['npm', 'github-script']);
 const ALLOWED_UPGRADE_CHANNELS = new Set(['stable', 'pre']);
+const ALLOWED_SKILL_SYNC_METHODS = new Set(['npm', 'github-script']);
+const ALLOWED_RUN_TASK_MODES = new Set(['preview', 'execute', 'preview-execute-verify']);
+const ALLOWED_SCAN_DEBUG_LEVELS = new Set(['off', 'summary', 'full']);
 const ACTION_FLAG_MAP = new Map([
   ['--cleanup-monthly', 'cleanup_monthly'],
   ['--analysis-only', 'analysis_only'],
@@ -18,6 +21,7 @@ const ACTION_FLAG_MAP = new Map([
   ['--recycle-maintain', 'recycle_maintain'],
   ['--doctor', 'doctor'],
   ['--check-update', 'check_update'],
+  ['--sync-skills', 'sync_skills'],
 ]);
 const MODE_TO_ACTION_MAP = new Map([
   ['cleanup_monthly', 'cleanup_monthly'],
@@ -28,6 +32,7 @@ const MODE_TO_ACTION_MAP = new Map([
   ['doctor', 'doctor'],
   ['check_update', 'check_update'],
   ['upgrade', 'upgrade'],
+  ['sync_skills', 'sync_skills'],
 ]);
 
 export class CliArgError extends Error {
@@ -196,6 +201,11 @@ export function parseCliArgs(argv) {
     upgradeVersion: null,
     upgradeChannel: null,
     upgradeYes: false,
+    upgradeSyncSkills: null,
+    skillSyncMethod: null,
+    skillSyncRef: null,
+    runTask: null,
+    scanDebug: 'off',
   };
   const actionValues = [];
 
@@ -300,6 +310,31 @@ export function parseCliArgs(argv) {
       parsed.upgradeYes = true;
       continue;
     }
+    if (token === '--upgrade-sync-skills') {
+      parsed.upgradeSyncSkills = parseBooleanFlag(token, takeValue(token, i));
+      i += 1;
+      continue;
+    }
+    if (token === '--skill-sync-method') {
+      parsed.skillSyncMethod = parseEnumValue(token, takeValue(token, i), ALLOWED_SKILL_SYNC_METHODS);
+      i += 1;
+      continue;
+    }
+    if (token === '--skill-sync-ref') {
+      parsed.skillSyncRef = takeValue(token, i);
+      i += 1;
+      continue;
+    }
+    if (token === '--run-task') {
+      parsed.runTask = parseEnumValue(token, takeValue(token, i), ALLOWED_RUN_TASK_MODES);
+      i += 1;
+      continue;
+    }
+    if (token === '--scan-debug') {
+      parsed.scanDebug = parseEnumValue(token, takeValue(token, i), ALLOWED_SCAN_DEBUG_LEVELS);
+      i += 1;
+      continue;
+    }
     if (token === '--theme') {
       const theme = normalizeTheme(takeValue(token, i));
       if (!theme) {

package/src/constants.js

@@ -108,6 +108,7 @@ export const MODES = {
   RECYCLE_MAINTAIN: 'recycle_maintain',
   CHECK_UPDATE: 'check_update',
   UPGRADE: 'upgrade',
+  SYNC_SKILLS: 'sync_skills',
   SETTINGS: 'settings',
 };
 

package/src/doctor.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { collectRecycleStats, normalizeRecycleRetention } from './recycle-maintenance.js';
 import { detectExternalStorageRoots, discoverAccounts } from './scanner.js';
+import { inspectSkillBinding, skillBindingStatusLabel } from './skill-installer.js';
 import { normalizeSelfUpdateConfig } from './updater.js';
 
 const STATUS_PASS = 'pass';
@@ -291,6 +292,43 @@ export async function runDoctor({ config, aliases, projectRoot, appVersion }) {
     )
   );
 
+  let skillBinding = null;
+  try {
+    skillBinding = await inspectSkillBinding({
+      appVersion: appVersion || '',
+      targetRoot: process.env.WECOM_CLEANER_SKILLS_ROOT || '',
+    });
+  } catch (error) {
+    skillBinding = {
+      status: 'invalid_skill_dir',
+      matched: false,
+      installed: false,
+      expectedAppVersion: String(appVersion || ''),
+      installedManifest: null,
+      recommendation: `技能检测失败：${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  const skillDetail = (() => {
+    if (!skillBinding) {
+      return '未获取到技能状态';
+    }
+    const installedVersion = skillBinding.installedManifest?.skillVersion || '-';
+    const requiredAppVersion = skillBinding.installedManifest?.requiredAppVersion || '-';
+    return `${skillBindingStatusLabel(skillBinding.status)}，技能版本 ${installedVersion}，绑定程序版本 ${requiredAppVersion}`;
+  })();
+  checks.push(
+    buildCheck(
+      'skills_binding',
+      'Agent Skills 版本绑定',
+      skillBinding?.matched ? STATUS_PASS : STATUS_WARN,
+      skillDetail,
+      skillBinding?.matched
+        ? ''
+        : skillBinding?.recommendation ||
+            '建议执行 wecom-cleaner-skill install --force 重新同步 skills 版本。'
+    )
+  );
+
   const target = resolveRuntimeTarget();
   const manifest = await readManifest(projectRoot);
   const manifestTarget = manifest.parsed?.targets?.[target.targetTag] || null;
@@ -384,6 +422,9 @@ export async function runDoctor({ config, aliases, projectRoot, appVersion }) {
       recycleBytes: recycleStats.totalBytes,
       recycleThresholdBytes: thresholdBytes,
       recycleOverThreshold,
+      skillsStatus: skillBinding?.status || 'unknown',
+      skillsMatched: Boolean(skillBinding?.matched),
+      skillsInstalled: Boolean(skillBinding?.installed),
     },
     recommendations,
   };

package/src/skill-cli.js

@@ -1,15 +1,42 @@
 #!/usr/bin/env node
-import { installSkill, resolveDefaultSkillsRoot } from './skill-installer.js';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import {
+  installSkill,
+  inspectSkillBinding,
+  resolveDefaultSkillsRoot,
+  skillBindingStatusLabel,
+} from './skill-installer.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+
+async function loadAppVersion() {
+  try {
+    const packagePath = path.join(PROJECT_ROOT, 'package.json');
+    const text = await readFile(packagePath, 'utf-8');
+    const pkg = JSON.parse(text);
+    return String(pkg.version || '').trim();
+  } catch {
+    return '';
+  }
+}
 
 function printHelp() {
   console.log(`wecom-cleaner-skill
 
 用法：
-  wecom-cleaner-skill install [--target <目录>] [--force] [--dry-run]
+  wecom-cleaner-skill install [--target <目录>] [--force] [--dry-run] [--json]
+  wecom-cleaner-skill sync [--target <目录>] [--dry-run] [--json]
+  wecom-cleaner-skill status [--target <目录>] [--app-version <x.y.z>] [--json]
   wecom-cleaner-skill path
 
 说明：
   - install: 安装 wecom-cleaner-agent 到 Codex 技能目录
+  - sync: 同步/升级技能版本（等价 install --force）
+  - status: 检查技能是否与主程序版本匹配
   - path: 输出默认技能目录（由 CODEX_HOME 或 ~/.codex 推导）
 `);
 }
@@ -20,6 +47,8 @@ function parseArgs(argv) {
     target: '',
     force: false,
     dryRun: false,
+    json: false,
+    appVersion: '',
     help: false,
   };
 
@@ -44,6 +73,10 @@ function parseArgs(argv) {
       parsed.dryRun = true;
       continue;
     }
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
     if (token === '--target') {
       const next = tokens[i + 1];
       if (!next || next.startsWith('-')) {
@@ -53,15 +86,47 @@ function parseArgs(argv) {
       i += 1;
       continue;
     }
+    if (token === '--app-version') {
+      const next = tokens[i + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('参数 --app-version 缺少版本值');
+      }
+      parsed.appVersion = next;
+      i += 1;
+      continue;
+    }
     throw new Error(`未知参数: ${token}`);
   }
 
   return parsed;
 }
 
+function printStatusText(result) {
+  console.log(`技能: ${result.skillName}`);
+  console.log(`状态: ${skillBindingStatusLabel(result.status)}`);
+  console.log(`匹配: ${result.matched ? '是' : '否'}`);
+  console.log(`主程序版本: ${result.expectedAppVersion || '-'}`);
+  console.log(`已安装: ${result.installed ? '是' : '否'}`);
+  if (result.installedManifest?.skillVersion) {
+    console.log(`技能版本: ${result.installedManifest.skillVersion}`);
+  } else {
+    console.log('技能版本: -');
+  }
+  if (result.installedManifest?.requiredAppVersion) {
+    console.log(`技能绑定版本: ${result.installedManifest.requiredAppVersion}`);
+  } else {
+    console.log('技能绑定版本: -');
+  }
+  console.log(`目标目录: ${result.targetSkillDir}`);
+  if (result.recommendation) {
+    console.log(`建议: ${result.recommendation}`);
+  }
+}
+
 async function main() {
   try {
     const args = parseArgs(process.argv.slice(2));
+    const appVersion = args.appVersion || (await loadAppVersion());
 
     if (args.help) {
       printHelp();
@@ -73,21 +138,63 @@ async function main() {
       return;
     }
 
-    if (args.command !== 'install') {
+    if (args.command === 'status') {
+      const status = await inspectSkillBinding({
+        targetRoot: args.target,
+        appVersion,
+      });
+      if (args.json) {
+        console.log(JSON.stringify(status, null, 2));
+        process.exitCode = status.matched ? 0 : 1;
+        return;
+      }
+      printStatusText(status);
+      process.exitCode = status.matched ? 0 : 1;
+      return;
+    }
+
+    if (args.command !== 'install' && args.command !== 'sync') {
       throw new Error(`不支持的命令: ${args.command}`);
     }
 
+    const force = args.command === 'sync' ? true : args.force;
     const result = await installSkill({
       targetRoot: args.target,
-      force: args.force,
+      force,
       dryRun: args.dryRun,
+      appVersion,
+    });
+    const status = await inspectSkillBinding({
+      targetRoot: args.target,
+      appVersion,
     });
 
+    if (args.json) {
+      console.log(
+        JSON.stringify(
+          {
+            action: args.command,
+            result,
+            status,
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+
     const mode = result.dryRun ? '预演' : '安装';
     const replaceText = result.replaced ? '（覆盖已存在版本）' : '';
     console.log(`${mode}成功${replaceText}`);
     console.log(`技能: ${result.skillName}`);
+    console.log(`技能版本: ${result.targetManifest.skillVersion}`);
+    console.log(`绑定程序版本: ${result.targetManifest.requiredAppVersion}`);
     console.log(`目标: ${result.targetSkillDir}`);
+    console.log(`匹配状态: ${skillBindingStatusLabel(status.status)}`);
+    if (!status.matched && status.recommendation) {
+      console.log(`建议: ${status.recommendation}`);
+    }
   } catch (error) {
     console.error(`执行失败: ${error.message}`);
     process.exitCode = 1;

package/src/skill-installer.js

@@ -1,15 +1,60 @@
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { access, cp, mkdir, rm } from 'node:fs/promises';
+import { access, cp, mkdir, readFile, rm } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
 
 export const SKILL_NAME = 'wecom-cleaner-agent';
+export const SKILL_VERSION_FILE = 'version.json';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = path.resolve(__dirname, '..');
 const DEFAULT_SOURCE_SKILL_DIR = path.join(PROJECT_ROOT, 'skills', SKILL_NAME);
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+function normalizeSemver(rawValue) {
+  const text = String(rawValue || '').trim();
+  if (!text) {
+    return '';
+  }
+  const matched = text.match(SEMVER_RE);
+  if (!matched) {
+    return '';
+  }
+  const base = `${matched[1]}.${matched[2]}.${matched[3]}`;
+  return matched[4] ? `${base}-${matched[4]}` : base;
+}
+
+function buildFallbackManifest(appVersion = '') {
+  const normalizedAppVersion = normalizeSemver(appVersion) || '0.0.0';
+  return {
+    schemaVersion: 1,
+    skillName: SKILL_NAME,
+    skillVersion: normalizedAppVersion,
+    requiredAppVersion: normalizedAppVersion,
+  };
+}
+
+function normalizeSkillManifest(rawManifest, options = {}) {
+  const fallback = buildFallbackManifest(options.appVersion);
+  const source = rawManifest && typeof rawManifest === 'object' ? rawManifest : {};
+  const schemaVersion = Number.isFinite(Number(source.schemaVersion))
+    ? Number(source.schemaVersion)
+    : fallback.schemaVersion;
+  const skillName =
+    typeof source.skillName === 'string' && source.skillName.trim()
+      ? source.skillName.trim()
+      : fallback.skillName;
+  const skillVersion = normalizeSemver(source.skillVersion) || fallback.skillVersion;
+  const requiredAppVersion = normalizeSemver(source.requiredAppVersion) || fallback.requiredAppVersion;
+  return {
+    schemaVersion,
+    skillName,
+    skillVersion,
+    requiredAppVersion,
+  };
+}
 
 export function resolveDefaultSkillsRoot(env = process.env) {
   const codexHome = typeof env.CODEX_HOME === 'string' ? env.CODEX_HOME.trim() : '';
@@ -35,6 +80,142 @@ async function exists(targetPath) {
   }
 }
 
+export function skillBindingStatusLabel(status) {
+  if (status === 'matched') {
+    return '已匹配';
+  }
+  if (status === 'mismatch') {
+    return '版本不匹配';
+  }
+  if (status === 'legacy_unversioned') {
+    return '旧版技能（缺少版本信息）';
+  }
+  if (status === 'not_installed') {
+    return '未安装';
+  }
+  if (status === 'invalid_skill_dir') {
+    return '安装目录异常';
+  }
+  return '未知';
+}
+
+export async function readSkillManifestFromDir(skillDir, options = {}) {
+  const resolvedSkillDir = path.resolve(String(skillDir || ''));
+  const manifestPath = path.join(resolvedSkillDir, SKILL_VERSION_FILE);
+  const manifestExists = await exists(manifestPath);
+  if (!manifestExists) {
+    return {
+      path: manifestPath,
+      exists: false,
+      parseError: '',
+      manifest: normalizeSkillManifest(null, options),
+    };
+  }
+
+  try {
+    const text = await readFile(manifestPath, 'utf-8');
+    const parsed = JSON.parse(text);
+    return {
+      path: manifestPath,
+      exists: true,
+      parseError: '',
+      manifest: normalizeSkillManifest(parsed, options),
+    };
+  } catch (error) {
+    return {
+      path: manifestPath,
+      exists: true,
+      parseError: error instanceof Error ? error.message : String(error),
+      manifest: normalizeSkillManifest(null, options),
+    };
+  }
+}
+
+export async function inspectSkillBinding(options = {}) {
+  const appVersion = normalizeSemver(options.appVersion);
+  const sourceSkillDir = path.resolve(options.sourceSkillDir || DEFAULT_SOURCE_SKILL_DIR);
+  const sourceSkillFile = path.join(sourceSkillDir, 'SKILL.md');
+  if (!(await exists(sourceSkillFile))) {
+    throw new Error(`技能源目录无效，缺少 SKILL.md: ${sourceSkillDir}`);
+  }
+
+  const sourceManifestState = await readSkillManifestFromDir(sourceSkillDir, {
+    appVersion,
+  });
+  const expectedAppVersion = appVersion || sourceManifestState.manifest.requiredAppVersion;
+  const targetRoot = resolveTargetSkillsRoot(options.targetRoot, options.env || process.env);
+  const targetSkillDir = path.join(targetRoot, SKILL_NAME);
+  const targetSkillExists = await exists(targetSkillDir);
+  const targetSkillFile = path.join(targetSkillDir, 'SKILL.md');
+  const targetSkillFileExists = targetSkillExists ? await exists(targetSkillFile) : false;
+  const installedManifestState = targetSkillExists
+    ? await readSkillManifestFromDir(targetSkillDir, {
+        appVersion: expectedAppVersion,
+      })
+    : null;
+
+  const recommendation = (() => {
+    if (!targetSkillExists) {
+      return '执行 wecom-cleaner-skill install 安装技能。';
+    }
+    if (!targetSkillFileExists) {
+      return '目标目录缺少 SKILL.md，建议执行 wecom-cleaner-skill install --force 修复。';
+    }
+    if (installedManifestState && !installedManifestState.exists) {
+      return '检测到旧版技能（缺少 version.json），建议执行 wecom-cleaner-skill install --force。';
+    }
+    if (
+      installedManifestState &&
+      installedManifestState.manifest.skillName === SKILL_NAME &&
+      installedManifestState.manifest.requiredAppVersion === expectedAppVersion
+    ) {
+      return '';
+    }
+    return '建议执行 wecom-cleaner-skill install --force 同步技能版本。';
+  })();
+
+  let status = 'matched';
+  let matched = true;
+  if (!targetSkillExists) {
+    status = 'not_installed';
+    matched = false;
+  } else if (!targetSkillFileExists) {
+    status = 'invalid_skill_dir';
+    matched = false;
+  } else if (installedManifestState && !installedManifestState.exists) {
+    status = 'legacy_unversioned';
+    matched = false;
+  } else if (
+    !installedManifestState ||
+    installedManifestState.manifest.skillName !== SKILL_NAME ||
+    installedManifestState.manifest.requiredAppVersion !== expectedAppVersion
+  ) {
+    status = 'mismatch';
+    matched = false;
+  }
+
+  return {
+    skillName: SKILL_NAME,
+    status,
+    matched,
+    recommendation,
+    expectedAppVersion: expectedAppVersion || '',
+    sourceSkillDir,
+    sourceManifestPath: sourceManifestState.path,
+    sourceManifest: sourceManifestState.manifest,
+    sourceManifestExists: sourceManifestState.exists,
+    sourceManifestParseError: sourceManifestState.parseError || '',
+    targetRoot,
+    targetSkillDir,
+    installed: targetSkillExists,
+    installedSkillFileExists: targetSkillFileExists,
+    installedManifestPath: installedManifestState?.path || path.join(targetSkillDir, SKILL_VERSION_FILE),
+    installedManifest: installedManifestState?.manifest || null,
+    installedManifestExists: Boolean(installedManifestState?.exists),
+    installedManifestParseError: installedManifestState?.parseError || '',
+  };
+}
+
 export async function installSkill(options = {}) {
   const sourceSkillDir = path.resolve(options.sourceSkillDir || DEFAULT_SOURCE_SKILL_DIR);
   const targetRoot = resolveTargetSkillsRoot(options.targetRoot);
@@ -46,9 +227,17 @@ export async function installSkill(options = {}) {
   if (!sourceExists) {
     throw new Error(`技能源目录无效，缺少 SKILL.md: ${sourceSkillDir}`);
   }
+  const sourceManifestState = await readSkillManifestFromDir(sourceSkillDir, {
+    appVersion: options.appVersion,
+  });
 
   const targetSkillDir = path.join(targetRoot, SKILL_NAME);
   const targetExists = await exists(targetSkillDir);
+  const previousManifestState = targetExists
+    ? await readSkillManifestFromDir(targetSkillDir, {
+        appVersion: options.appVersion || sourceManifestState.manifest.requiredAppVersion,
+      })
+    : null;
   if (targetExists && !force) {
     throw new Error(`目标技能已存在：${targetSkillDir}。如需覆盖请加 --force`);
   }
@@ -65,6 +254,12 @@ export async function installSkill(options = {}) {
     });
   }
 
+  const targetManifestState = dryRun
+    ? sourceManifestState
+    : await readSkillManifestFromDir(targetSkillDir, {
+        appVersion: options.appVersion || sourceManifestState.manifest.requiredAppVersion,
+      });
+
   return {
     skillName: SKILL_NAME,
     sourceSkillDir,
@@ -72,5 +267,13 @@ export async function installSkill(options = {}) {
     targetSkillDir,
     dryRun,
     replaced: targetExists,
+    sourceManifest: sourceManifestState.manifest,
+    sourceManifestPath: sourceManifestState.path,
+    previousManifest: previousManifestState?.manifest || null,
+    previousManifestPath: previousManifestState?.path || null,
+    previousManifestExists: Boolean(previousManifestState?.exists),
+    targetManifest: targetManifestState.manifest,
+    targetManifestPath: targetManifestState.path,
+    targetManifestExists: targetManifestState.exists,
   };
 }