@heihei0299/matt-skills 3.0.29 → 3.1.0

package/bin/cli.js

@@ -1,37 +1,23 @@
 #!/usr/bin/env node
-import { readdir, readFile, writeFile, cp, stat, lstat, rm, mkdir, mkdtemp } from 'node:fs/promises';
-import os from 'node:os';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import prompts from 'prompts';
-import {
-  PROPRIETARY_SKILLS,
-  isDistributableSkill,
-  isRepoLocalSkill,
-  REPO_LOCAL_SKILLS,
-} from './skill-boundaries.js';
-import { resolveSkillNames } from './skill-selection.js';
-import { loadSkillSet } from './skill-config.js';
+import { runCheck } from './commands/check.js';
+import { runInit } from './commands/init.js';
+import { runInstall } from './commands/install.js';
+import { runList } from './commands/list.js';
+import { runSync } from './commands/sync.js';
+import { PROJECT_SKILLS_DIR } from './project/skills.js';
 
-const SKILLS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '.agents', 'skills');
-const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'template');
-const DEFAULT_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'default.json');
-let DEFAULT_SKILLS = null;
-async function loadDefaultSkills() {
-  if (!DEFAULT_SKILLS) DEFAULT_SKILLS = await loadSkillSet(DEFAULT_PATH, 'default');
-  return DEFAULT_SKILLS;
-}
 process.stdout.on('error', (err) => {
   if (err.code === 'EPIPE') process.exit(0);
   throw err;
 });
 
-const PROJECT_SKILL_DIRS = '.agents/skills';
-
 const HELP_GLOBAL = `matt-skills — install and manage this skill collection
 
 Usage:
-  matt-skills init [options]                   Initialize a project: template + skills (${PROJECT_SKILL_DIRS})
+  matt-skills init [options]                   Initialize a project: template + skills (${PROJECT_SKILLS_DIR})
   matt-skills sync [--all|--dry-run|--refresh-agents] [--dest <path>]   Sync existing project to latest template + skills
   matt-skills list [--all] [--json]            List available skills and their descriptions
   matt-skills install [options]                Install skills (interactive by default)
@@ -41,7 +27,7 @@ Usage:
   matt-skills --version | -v                  Show version
 `;
 
-const HELP_INIT = `matt-skills init [options] — Initialize a project: template + skills (${PROJECT_SKILL_DIRS})
+const HELP_INIT = `matt-skills init [options] — Initialize a project: template + skills (${PROJECT_SKILLS_DIR})
 
 Usage:
   matt-skills init [options]
@@ -67,7 +53,7 @@ Sync options:
   --json             仅与 --dry-run 一起使用，输出机器可读结果
   --dest <path>      Target directory (default: current directory)
   --help, -h         Show this help
-  项目 skills：${PROJECT_SKILL_DIRS}
+  项目 skills：${PROJECT_SKILLS_DIR}
 
 说明：默认同步默认 workflow skill 并保留现有 AGENTS.md；--all 只扩大技能范围。
       --refresh-agents 与 --all、--dry-run 可组合；上游检查请使用 check。
@@ -120,610 +106,6 @@ Install options:
 提示：matt-skills --help 查看全量
 `;
 
-const HELP = HELP_GLOBAL;
-
-const DRY_RUN_PATHS = ['AGENTS.md', 'AGENTS.md.bak', '.opencode', '.pi', '.agents/skills', '.claude/skills'];
-
-function parseFrontmatter(text) {
-  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return {};
-  const fields = {};
-  for (const line of match[1].split(/\r?\n/)) {
-    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-    if (!m) continue;
-    let value = m[2].trim();
-    if (value.startsWith('"') && value.endsWith('"')) {
-      value = value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
-    }
-    fields[m[1]] = value;
-  }
-  return fields;
-}
-
-async function listAvailableSkillNames() {
-  const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
-  return entries
-    .filter((entry) => entry.isDirectory())
-    .filter((entry) => !entry.name.endsWith('.bak'))
-    .filter((entry) => entry.name !== 'skill-creator' && entry.name !== '.git')
-    .map((entry) => entry.name);
-}
-
-async function listSkillNames({ onlyProgramming = false } = {}) {
-  return resolveSkillNames({
-    availableNames: await listAvailableSkillNames(),
-    mode: onlyProgramming ? 'default' : 'all',
-    defaults: onlyProgramming ? await loadDefaultSkills() : [],
-  });
-}
-
-async function listSkills({ onlyProgramming = false } = {}) {
-  const skills = [];
-  for (const name of await listSkillNames({ onlyProgramming })) {
-    let content;
-    try {
-      content = await readFile(path.join(SKILLS_DIR, name, 'SKILL.md'), 'utf8');
-    } catch {
-      continue;
-    }
-    const { description } = parseFrontmatter(content);
-    if (description) skills.push({ name, description });
-  }
-  return skills.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-}
-
-async function pathExists(p) {
-  try {
-    await stat(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function shouldCopyTemplatePath(src) {
-  const relative = path.relative(TEMPLATE_DIR, src);
-  const parts = relative.split(path.sep);
-  return !(parts[0] === '.agents' && parts[1] === 'skills');
-}
-
-const AGENTS_MANAGED_START = '<!-- matt-skills:managed:start -->';
-const AGENTS_MANAGED_END = '<!-- matt-skills:managed:end -->';
-
-function findManagedBlock(content) {
-  const start = content.indexOf(AGENTS_MANAGED_START);
-  if (start < 0 || content.indexOf(AGENTS_MANAGED_START, start + AGENTS_MANAGED_START.length) >= 0) return null;
-  const endStart = content.indexOf(AGENTS_MANAGED_END, start + AGENTS_MANAGED_START.length);
-  if (endStart < 0 || content.indexOf(AGENTS_MANAGED_END, endStart + AGENTS_MANAGED_END.length) >= 0) return null;
-  return { start, end: endStart + AGENTS_MANAGED_END.length };
-}
-
-function mergeManagedAgents(current, template) {
-  const currentBlock = findManagedBlock(current);
-  const templateBlock = findManagedBlock(template);
-  if (!currentBlock || !templateBlock) return null;
-  const managed = template.slice(templateBlock.start, templateBlock.end);
-  return current.slice(0, currentBlock.start) + managed + current.slice(currentBlock.end);
-}
-
-async function syncManagedAgents(targetFile) {
-  const current = await readFile(targetFile, 'utf8');
-  const template = await readFile(path.join(TEMPLATE_DIR, 'AGENTS.md'), 'utf8');
-  const merged = mergeManagedAgents(current, template);
-  if (merged === null) return false;
-  if (merged !== current) await writeFile(targetFile, merged);
-  return true;
-}
-
-const TOOLS = ['codex', 'pi', 'opencode', 'claude'];
-
-const PROJECT_DIRS = {
-  codex: '.agents/skills',
-  pi: '.agents/skills',
-  opencode: '.agents/skills',
-  claude: '.agents/skills',
-};
-
-function projectSkillTargets(target) {
-  const targets = new Map();
-  for (const tool of TOOLS) {
-    const dir = path.resolve(target, PROJECT_DIRS[tool]);
-    if (!targets.has(dir)) targets.set(dir, { tool, dir });
-  }
-  return [...targets.values()];
-}
-
-const LEGACY_PROJECT_SKILL_DIRS = ['.pi/skills', '.opencode/skills', '.claude/skills'];
-
-async function isSafeRealPath(targetPath) {
-  const absolute = path.resolve(targetPath);
-  const root = path.parse(absolute).root;
-  let current = root;
-  for (const segment of path.relative(root, absolute).split(path.sep).filter(Boolean)) {
-    current = path.join(current, segment);
-    try {
-      if ((await lstat(current)).isSymbolicLink()) return false;
-    } catch {
-      return false;
-    }
-  }
-  return true;
-}
-
-function sameMetadata(left, right) {
-  return (left.mode & 0o7777) === (right.mode & 0o7777)
-    && left.uid === right.uid
-    && left.gid === right.gid;
-}
-
-async function sameTree(left, right) {
-  try {
-    const [leftInfo, rightInfo] = await Promise.all([lstat(left), lstat(right)]);
-    if (leftInfo.isSymbolicLink() || rightInfo.isSymbolicLink()) return false;
-    if (leftInfo.isDirectory() !== rightInfo.isDirectory()) return false;
-    if (leftInfo.isDirectory()) {
-      const [leftEntries, rightEntries] = await Promise.all([
-        readdir(left, { withFileTypes: true }),
-        readdir(right, { withFileTypes: true }),
-      ]);
-      if (!sameMetadata(leftInfo, rightInfo) || leftEntries.length !== rightEntries.length) return false;
-      const rightNames = new Set(rightEntries.map((entry) => entry.name));
-      for (const entry of leftEntries) {
-        if (!rightNames.has(entry.name) || !await sameTree(path.join(left, entry.name), path.join(right, entry.name))) {
-          return false;
-        }
-      }
-      return true;
-    }
-    if (leftInfo.isFile() && rightInfo.isFile()) {
-      return (await readFile(left)).equals(await readFile(right)) && sameMetadata(leftInfo, rightInfo);
-    }
-    return false;
-  } catch {
-    return false;
-  }
-}
-
-const GLOBAL_DIRS = {
-  codex: '.codex/skills',
-  pi: '.pi/agent/skills',
-  opencode: '.config/opencode/skills',
-  claude: '.claude/skills',
-};
-
-function toolDir(tool, global) {
-  if (global) return path.join(os.homedir(), GLOBAL_DIRS[tool]);
-  return path.resolve(process.cwd(), PROJECT_DIRS[tool]);
-}
-
-async function promptTools() {
-  const res = await prompts({
-    type: 'multiselect',
-    name: 'tools',
-    message: '选择要安装到的工具',
-    choices: TOOLS.map((t) => ({ title: t, value: t })),
-    instructions: '空格勾选，回车确认',
-  });
-  return Array.isArray(res?.tools) ? res.tools : [];
-}
-
-async function promptSkills(skills) {
-  const res = await prompts({
-    type: 'autocompleteMultiselect',
-    name: 'skills',
-    message: '选择要安装的技能',
-    choices: skills.map((s) => ({ title: s.name, value: s.name })),
-    instructions: '输入过滤，空格勾选，回车确认',
-  });
-  return Array.isArray(res?.skills) ? res.skills : [];
-}
-
-async function installCommand({ dest, all, force, tools, global }) {
-  const onlyProgramming = !all;
-  const skillNames = await listSkillNames({ onlyProgramming });
-  const skills = await listSkills({ onlyProgramming });
-  let targets;
-  if (dest) {
-    targets = [{ tool: null, dir: path.resolve(process.cwd(), dest) }];
-  } else {
-    const selectedTools = tools
-      ? tools.filter((t) => TOOLS.includes(t))
-      : await promptTools();
-    if (selectedTools.length === 0) {
-      process.stdout.write('未选择任何工具，未安装任何技能\n');
-      return;
-    }
-    targets = selectedTools.map((tool) => ({ tool, dir: toolDir(tool, global) }));
-    // 去重：保留对自定义 PROJECT_DIRS 映射的兼容。
-    const seen = new Map();
-    for (const t of targets) {
-      if (!seen.has(t.dir)) seen.set(t.dir, t);
-    }
-    targets = [...seen.values()];
-  }
-  const selected = all ? skillNames : await promptSkills(skills);
-  if (selected.length === 0) {
-    process.stdout.write('未选择任何技能，未安装任何技能\n');
-    return;
-  }
-  const knownDistributable = new Set(skillNames);
-  for (const name of selected) {
-    if (!isDistributableSkill(name, knownDistributable)) {
-      throw new Error(`${name} is repository-local or unavailable and cannot be distributed`);
-    }
-  }
-  for (const { tool, dir } of targets) {
-    let installed = 0;
-    let skipped = 0;
-    for (const name of selected) {
-      const dst = path.join(dir, name);
-      if (!force && (await pathExists(dst))) {
-        skipped++;
-        continue;
-      }
-      await cp(path.join(SKILLS_DIR, name), dst, { recursive: true, force: true });
-      installed++;
-    }
-    if (tool) process.stdout.write(`${tool}：已装 ${installed}、跳过 ${skipped}\n`);
-    else process.stdout.write(`已装 ${installed}、跳过 ${skipped}\n`);
-    process.stdout.write(`目标路径：${dir}\n`);
-  }
-}
-
-async function initCommand({ dest, all }) {
-  const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
-  const marker = path.join(target, 'AGENTS.md');
-  const onlyProgramming = !all;
-  if (await pathExists(marker)) {
-    process.stdout.write('模板已存在（AGENTS.md），跳过\n');
-  } else {
-    await cp(TEMPLATE_DIR, target, {
-      recursive: true,
-      force: true,
-      filter: shouldCopyTemplatePath,
-    });
-    const selectedSkills = await listSkillNames({ onlyProgramming });
-    for (const { dir } of projectSkillTargets(target)) {
-      await mkdir(dir, { recursive: true });
-      for (const name of selectedSkills) {
-        const source = path.join(SKILLS_DIR, name);
-        const destination = path.join(dir, name);
-        if (path.resolve(source) === path.resolve(destination)) continue;
-        await cp(source, destination, { recursive: true, force: true });
-      }
-    }
-    process.stdout.write(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILL_DIRS}）\n`);
-  }
-  // 统计（区分编程 vs 全量）
-  const skillsDir = path.join(target, '.agents', 'skills');
-  let installed = 0;
-  try {
-    const entries = await readdir(skillsDir, { withFileTypes: true });
-    installed = entries.filter((e) => e.isDirectory() && !e.name.endsWith('.bak') && e.name !== '.git' && e.name !== 'skill-creator' && !isRepoLocalSkill(e.name)).length;
-  } catch {}
-  const allSkillsFull = await listSkills({ onlyProgramming: false });
-  const defaultSkills = await listSkills({ onlyProgramming: true });
-  const defaultCount = defaultSkills.length;
-  const upstreamFull = allSkillsFull.filter((s) => !PROPRIETARY_SKILLS.has(s.name)).length;
-  const upstreamDefault = defaultSkills.filter((s) => !PROPRIETARY_SKILLS.has(s.name)).length;
-  const displayTotal = onlyProgramming ? defaultCount : allSkillsFull.length;
-  const displayUpstream = onlyProgramming ? upstreamDefault : upstreamFull;
-  if (path.resolve(skillsDir) === path.resolve(SKILLS_DIR)) {
-    process.stdout.write(`技能：已装 ${installed}、跳过 0（可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}；默认 workflow ${defaultCount}，含上游 ${upstreamDefault}）\n`);
-  } else {
-    if (onlyProgramming) {
-      process.stdout.write(`技能：已装 ${installed}（默认 workflow ${displayTotal}，含上游 ${displayUpstream}；可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}）\n`);
-    } else {
-      process.stdout.write(`技能：已装 ${installed}（可分发 ${displayTotal}，含上游 ${displayUpstream}）\n`);
-    }
-  }
-  process.stdout.write(`目标路径：${target}\n`);
-}
-async function copyDryRunInputs(target, stage) {
-  for (const relative of DRY_RUN_PATHS) {
-    const source = path.join(target, relative);
-    if (!await pathExists(source)) continue;
-    const destination = path.join(stage, relative);
-    await mkdir(path.dirname(destination), { recursive: true });
-    await cp(source, destination, { recursive: true, force: true });
-  }
-}
-
-async function compareDryRunTrees(target, stage) {
-  const result = { added: [], updated: [], removed: [] };
-  for (const relative of DRY_RUN_PATHS) {
-    const before = path.join(target, relative);
-    const after = path.join(stage, relative);
-    const beforeExists = await pathExists(before);
-    const afterExists = await pathExists(after);
-    if (!beforeExists && afterExists) result.added.push(relative);
-    else if (beforeExists && !afterExists) result.removed.push(relative);
-    else if (beforeExists && afterExists && !await sameTree(before, after)) result.updated.push(relative);
-  }
-  return result;
-}
-
-function formatTargetComparison({ target, result, onlyProgramming, refreshAgents }) {
-  const lines = [
-    `目标: ${target}`,
-    `范围: ${onlyProgramming ? '默认 workflow' : '全部可分发'}${refreshAgents ? '；刷新 AGENTS.md' : ''}`,
-    '',
-  ];
-  const totalDiff = result.added.length + result.updated.length + result.removed.length;
-  if (totalDiff === 0) {
-    lines.push('✅ 无需更新');
-    return lines.join('\n');
-  }
-  if (result.added.length) lines.push(`新增 (${result.added.length}): ${result.added.join(', ')}`);
-  if (result.updated.length) lines.push(`更新 (${result.updated.length}): ${result.updated.join(', ')}`);
-  if (result.removed.length) lines.push(`删除 (${result.removed.length}): ${result.removed.join(', ')}`);
-  return lines.join('\n');
-}
-
-async function refreshAgentsFile(targetFile) {
-  const templateFile = path.join(TEMPLATE_DIR, 'AGENTS.md');
-  const current = await readFile(targetFile, 'utf8');
-  const template = await readFile(templateFile, 'utf8');
-  const merged = mergeManagedAgents(current, template);
-  if (merged !== null) {
-    if (merged !== current) await writeFile(targetFile, merged);
-    return 'managed';
-  }
-  await cp(targetFile, `${targetFile}.bak`, { force: true });
-  await cp(templateFile, targetFile, { force: true });
-  return 'full';
-}
-
-async function syncCommand({ dest, all, dryRun, json, refreshAgents, quiet = false }) {
-  const onlyProgramming = !all;
-  const output = (text) => {
-    if (!quiet) process.stdout.write(text);
-  };
-  if (!dryRun && json) throw new Error('--json 仅支持 sync --dry-run');
-  if (dryRun) {
-    const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
-    const stage = await mkdtemp(path.join(os.tmpdir(), 'matt-skills-sync-dry-run-'));
-    try {
-      await copyDryRunInputs(target, stage);
-      await syncCommand({ dest: stage, all, dryRun: false, json: false, refreshAgents, quiet: true });
-      const result = await compareDryRunTrees(target, stage);
-      const payload = { target, result, onlyProgramming, refreshAgents };
-      if (json) output(`${JSON.stringify(payload, null, 2)}\n`);
-      else output(`${formatTargetComparison(payload)}\n`);
-      const totalDiff = result.added.length + result.updated.length + result.removed.length;
-      if (totalDiff > 0) process.exitCode = 1;
-    } finally {
-      await rm(stage, { recursive: true, force: true });
-    }
-    return;
-  }
-
-  const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
-  const marker = path.join(target, 'AGENTS.md');
-  async function copyTemplateFiltered() {
-    await cp(TEMPLATE_DIR, target, {
-      recursive: true,
-      force: true,
-      filter: shouldCopyTemplatePath,
-    });
-  }
-  if (!(await pathExists(marker))) {
-    output('未检测到现有项目（AGENTS.md 不存在），将执行全新初始化\n');
-    await copyTemplateFiltered();
-    output(`模板：已复制（AGENTS.md、skills：${PROJECT_SKILL_DIRS}）\n`);
-  } else {
-    output('同步：检测到现有项目，将增量更新\n');
-    let agentsManaged = false;
-    let agentsRefreshed = false;
-    let agentsRefreshMode = null;
-    if (refreshAgents) {
-      agentsRefreshMode = await refreshAgentsFile(marker);
-      agentsRefreshed = true;
-    } else {
-      try {
-        agentsManaged = await syncManagedAgents(marker);
-      } catch {}
-    }
-    await cp(path.join(TEMPLATE_DIR, '.opencode'), path.join(target, '.opencode'), { recursive: true, force: true });
-    await cp(path.join(TEMPLATE_DIR, '.pi'), path.join(target, '.pi'), { recursive: true, force: true });
-    if (agentsRefreshed && agentsRefreshMode === 'managed') {
-      output(`模板：已同步（AGENTS.md 受管区块已刷新、skills：${PROJECT_SKILL_DIRS}，项目自定义内容已保留）\n`);
-    } else if (agentsRefreshed) {
-      output(`模板：已同步（AGENTS.md 已刷新，旧文件备份为 AGENTS.md.bak、skills：${PROJECT_SKILL_DIRS}）\n`);
-    } else if (agentsManaged) {
-      output(`模板：已同步（AGENTS.md 受管区块已更新、skills：${PROJECT_SKILL_DIRS}，项目自定义内容已保留）\n`);
-    } else {
-      output(`模板：已同步（AGENTS.md 未受管、skills：${PROJECT_SKILL_DIRS}，已原样保留）\n`);
-    }
-  }
-  // --all 只扩大技能范围；同名覆盖、不存在新增，不删除目标中的额外技能。
-  const allSkills = await listSkillNames({ onlyProgramming });
-  const skillTargets = projectSkillTargets(target);
-  const skillsDir = path.resolve(target, PROJECT_DIRS.codex);
-  const legacyLocations = LEGACY_PROJECT_SKILL_DIRS.map((relative) => ({
-    dir: path.resolve(target, relative),
-    label: relative,
-    isWorkspaceSource: false,
-  }));
-  const preservedRepoLocal = [];
-  const preserveLocations = [
-    ...skillTargets.map(({ tool, dir }) => ({
-      dir,
-      label: PROJECT_DIRS[tool],
-      isWorkspaceSource: path.resolve(dir) === path.resolve(SKILLS_DIR),
-    })),
-    ...legacyLocations,
-  ];
-  for (const { dir } of skillTargets) await mkdir(dir, { recursive: true });
-  for (const name of REPO_LOCAL_SKILLS) {
-    for (const location of preserveLocations) {
-      if (!location.isWorkspaceSource && await pathExists(path.join(location.dir, name))) {
-        preservedRepoLocal.push(`${location.label}/${name}`);
-      }
-    }
-  }
-  let installed = 0;
-  let updated = 0;
-  for (const { dir } of skillTargets) {
-    for (const name of allSkills) {
-      const src = path.join(SKILLS_DIR, name);
-      const dst = path.join(dir, name);
-      if (path.resolve(src) === path.resolve(dst)) {
-        if (path.resolve(dir) === skillsDir) updated++;
-        continue;
-      }
-      const exists = await pathExists(dst);
-      if (exists) {
-        await rm(dst, { recursive: true, force: true });
-        await cp(src, dst, { recursive: true, force: true });
-        if (path.resolve(dir) === skillsDir) updated++;
-      } else {
-        await cp(src, dst, { recursive: true, force: true });
-        if (path.resolve(dir) === skillsDir) installed++;
-      }
-    }
-  }
-  const distributableSkillNames = (await listSkillNames({ onlyProgramming: false })).filter((name) => !REPO_LOCAL_SKILLS.has(name));
-  const cleanedLegacy = [];
-  for (const location of legacyLocations) {
-    let entries;
-    try {
-      if (!await isSafeRealPath(location.dir)) continue;
-      const locationInfo = await lstat(location.dir);
-      if (!locationInfo.isDirectory()) continue;
-      entries = await readdir(location.dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name === '.git' || entry.name.endsWith('.bak')) continue;
-      if (!distributableSkillNames.includes(entry.name)) continue;
-      const src = path.join(SKILLS_DIR, entry.name);
-      const dst = path.join(location.dir, entry.name);
-      try {
-        if (await sameTree(src, dst)) {
-          await rm(dst, { recursive: true, force: true });
-          cleanedLegacy.push(`${location.label}/${entry.name}`);
-        }
-      } catch {}
-    }
-  }
-  // Legacy harness dirs may contain project-local Skills. Only exact canonical
-  // trees of clearly distributable skills are removed; repo-local, modified or
-  // unknown trees remain untouched.
-  // 清理过时的 .pi/settings.json 指向
-  try {
-    const piSettings = path.join(target, '.pi/settings.json');
-    if (await pathExists(piSettings)) {
-      const txt = await readFile(piSettings, 'utf8');
-      if (txt.includes('.opencode/skills') || txt.includes('../.opencode')) {
-        await writeFile(piSettings, '{}\n');
-      }
-    }
-  } catch {}
-  if (cleanedLegacy.length) {
-    output(`迁移清理：${cleanedLegacy.join(', ')} 旧共享副本已移除\n`);
-  }
-  if (preservedRepoLocal.length) {
-    output(`迁移提示：${preservedRepoLocal.join(', ')} 已不再分发，现有副本已保留\n`);
-  }
-  const modeLabel = onlyProgramming ? '默认 workflow' : '全部可分发';
-  output(`技能：新增 ${installed}、更新 ${updated}（${modeLabel} ${allSkills.length}）\n`);
-  output(`目标路径：${target}\n`);
-}
-
-function parseInitArgs(args) {
-  let dest;
-  let all = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--dest') {
-      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--dest' requires a value`);
-      dest = args[++i];
-    } else if (arg.startsWith('--dest=')) dest = arg.slice('--dest='.length);
-    else if (arg === '--all') all = true;
-    else if (arg === '--help' || arg === '-h') {} // handled at main level, ignore here
-    else if (arg.startsWith('-')) throw new Error(`unknown option '${arg}' for command 'init'`);
-    else throw new Error(`unknown argument '${arg}' for command 'init'`);
-  }
-  return { dest, all };
-}
-
-function parseSyncArgs(args) {
-  let dest;
-  let all = false;
-  let dryRun = false;
-  let json = false;
-  let refreshAgents = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--dest') {
-      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--dest' requires a value`);
-      dest = args[++i];
-    } else if (arg.startsWith('--dest=')) dest = arg.slice('--dest='.length);
-    else if (arg === '--all') all = true;
-    else if (arg === '--dry-run') dryRun = true;
-    else if (arg === '--json') json = true;
-    else if (arg === '--refresh-agents') refreshAgents = true;
-    else if (arg === '--help' || arg === '-h') {} // handled at main
-    else if (arg === '--apply') {} // deprecated alias, same as default safe incremental
-    else if (arg.startsWith('-')) throw new Error(`unknown option '${arg}' for command 'sync'`);
-    else throw new Error(`unknown argument '${arg}' for command 'sync'`);
-  }
-  return { dest, all, dryRun, json, refreshAgents };
-}
-
-function parseInstallArgs(args) {
-  let dest;
-  let all = false;
-  let force = false;
-  let global = false;
-  let toolsArg;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--dest') {
-      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--dest' requires a value`);
-      dest = args[++i];
-    } else if (arg.startsWith('--dest=')) dest = arg.slice('--dest='.length);
-    else if (arg === '--all') all = true;
-    else if (arg === '--force') force = true;
-    else if (arg === '--tools') {
-      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new Error(`unknown option '--tools' requires a value`);
-      toolsArg = args[++i];
-    } else if (arg.startsWith('--tools=')) toolsArg = arg.slice('--tools='.length);
-    else if (arg === '--global') global = true;
-    else if (arg === '--project') global = false;
-    else if (arg === '--help' || arg === '-h') {} // handled at main
-    else if (arg.startsWith('-')) throw new Error(`unknown option '${arg}' for command 'install'`);
-    else throw new Error(`unknown argument '${arg}' for command 'install'`);
-  }
-  const tools = toolsArg
-    ? toolsArg.split(',').map((t) => t.trim()).filter(Boolean)
-    : null;
-  return { dest, all, force, global, tools };
-}
-
-async function checkCommand(args) {
-  const { compare, formatComparison } = await import('../scripts/sync-upstream.js');
-  const json = args.includes('--json');
-  const onlyProgramming = !args.includes('--all');
-  const upstreamIdx = args.indexOf('--upstream');
-  const upstreamEq = args.find((x) => x.startsWith('--upstream='));
-  const upstreamUrl = upstreamIdx !== -1 ? args[upstreamIdx + 1] : (upstreamEq ? upstreamEq.slice('--upstream='.length) : undefined);
-  const refIdx = args.indexOf('--ref');
-  const refEq = args.find((x) => x.startsWith('--ref='));
-  const ref = refIdx !== -1 ? args[refIdx + 1] : (refEq ? refEq.slice('--ref='.length) : undefined);
-  const cmp = await compare({ upstreamUrl, ref, onlyProgramming });
-  if (json) {
-    process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result, onlyProgramming }, null, 2) + '\n');
-  } else {
-    process.stdout.write(formatComparison(cmp) + '\n');
-  }
-  const { rm } = await import('node:fs/promises');
-  await rm(cmp.dest, { recursive: true, force: true });
-  const hasDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length > 0;
-  if (hasDiff) process.exitCode = 1;
-}
 
 async function main() {
   const args = process.argv.slice(2);
@@ -764,55 +146,23 @@ async function main() {
     return;
   }
   if (command === 'list') {
-    // list strict: only --all/--json/--help allowed, rest handled via parse but we keep simple
-    for (const a of rest) {
-      if (a === '--all' || a === '--json' || a === '--help' || a === '-h') continue;
-      if (a.startsWith('-')) { process.stderr.write(`error: unknown option '${a}' for command 'list'\n`); process.stderr.write(`Run 'matt-skills list --help' for usage.\n`); process.exitCode = 2; return; }
-      process.stderr.write(`error: unknown argument '${a}' for command 'list'\n`); process.stderr.write(`Run 'matt-skills list --help' for usage.\n`); process.exitCode = 2; return;
-    }
-    const onlyProgramming = !rest.includes('--all');
-    const skills = await listSkills({ onlyProgramming });
-    if (rest.includes('--json')) {
-      process.stdout.write(`${JSON.stringify(skills, null, 2)}\n`);
-    } else {
-      for (const skill of skills) {
-        process.stdout.write(`${skill.name} — ${skill.description}\n`);
-      }
-    }
+    await runList(rest);
     return;
   }
   if (command === 'init') {
-    await initCommand(parseInitArgs(rest));
+    await runInit(rest);
     return;
   }
   if (command === 'sync') {
-    await syncCommand(parseSyncArgs(rest));
+    await runSync(rest);
     return;
   }
   if (command === 'install') {
-    await installCommand(parseInstallArgs(rest));
+    await runInstall(rest);
     return;
   }
   if (command === 'check') {
-    // check strict: allow --all/--json/--upstream/--ref/--help
-    for (let i = 0; i < rest.length; i++) {
-      const a = rest[i];
-      if (a === '--all' || a === '--json' || a === '--help' || a === '-h') continue;
-      if (a === '--upstream' || a === '--ref') {
-        if (i + 1 >= rest.length || rest[i + 1].startsWith('-')) {
-          process.stderr.write(`error: option '${a}' for command 'check' requires a value\n`);
-          process.stderr.write(`Run 'matt-skills check --help' for usage.\n`);
-          process.exitCode = 2;
-          return;
-        }
-        i++;
-        continue;
-      }
-      if (a.startsWith('--upstream=') || a.startsWith('--ref=')) continue;
-      if (a.startsWith('-')) { process.stderr.write(`error: unknown option '${a}' for command 'check'\n`); process.stderr.write(`Run 'matt-skills check --help' for usage.\n`); process.exitCode = 2; return; }
-      process.stderr.write(`error: unknown argument '${a}' for command 'check'\n`); process.stderr.write(`Run 'matt-skills check --help' for usage.\n`); process.exitCode = 2; return;
-    }
-    await checkCommand(rest);
+    await runCheck(rest);
     return;
   }
   if (command === 'update') {