@pigcloud/skills 1.0.10 → 1.1.2

package/bin/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
-const fs = require('fs/promises');
-const fsSync = require('fs');
-const path = require('path');
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
 const os = require('os');
-const { detectRulesBundle } = require('./rules-loader');
+const crypto = require('crypto');
+const { detectRulesStage } = require('./rules-loader');
 
 const PACKAGE_ROOT = path.join(__dirname, '..');
 const SKILLS_DIR = path.join(PACKAGE_ROOT, 'skills');
@@ -41,22 +42,32 @@ const chalk = {
   gray: text => colorize(COLORS.gray, text)
 };
 
-const SKILLS = [
-  { name: 'workflow-router', category: 'core', description: '路由工作阶段' },
-  { name: 'spec-refinement', category: 'analysis', description: '将需求输入整理为可执行规格' },
-  { name: 'technical-design', category: 'core', description: '梳理实现设计' },
-  { name: 'feature-build', category: 'core', description: '安全实现功能变更' },
-  { name: 'code-review', category: 'core', description: '审查代码变更' },
-  { name: 'domain-modeling', category: 'analysis', description: '提炼领域知识' },
-  { name: 'business-fact-extraction', category: 'analysis', description: '从代码中提取业务事实' },
-  { name: 'api-contract-docs', category: 'integration', description: '整理 API 契约文档' },
-  { name: 'test-design', category: 'integration', description: '设计测试覆盖' },
-  { name: 'security-audit', category: 'review', description: '审查安全风险' },
-  { name: 'performance-audit', category: 'review', description: '审查性能风险' },
-  { name: 'knowledge-capture', category: 'collaboration', description: '沉淀可复用知识' },
-  { name: 'project-bootstrap', category: 'infrastructure', description: '初始化项目骨架' },
-  { name: 'environment-deploy', category: 'infrastructure', description: '部署支撑环境' }
-];
+const SKILLS = [
+  { name: 'requirement-discovery', stage: '01-discovery', category: 'discovery', description: '梳理需求与问题边界' },
+  { name: 'business-analysis', stage: '01-discovery', category: 'discovery', description: '提炼业务语义和术语' },
+  { name: 'ambiguity-detection', stage: '01-discovery', category: 'discovery', description: '识别歧义、冲突和缺口' },
+  { name: 'impact-analysis', stage: '01-discovery', category: 'discovery', description: '评估变更影响面' },
+  { name: 'architecture-design', stage: '02-design', category: 'design', description: '梳理系统级设计边界' },
+  { name: 'api-design', stage: '02-design', category: 'design', description: '设计接口契约和兼容性' },
+  { name: 'database-design', stage: '02-design', category: 'design', description: '设计表结构和查询方案' },
+  { name: 'task-breakdown', stage: '02-design', category: 'design', description: '拆解成可执行任务' },
+  { name: 'backend-development', stage: '03-implementation', category: 'implementation', description: '实现后端变更' },
+  { name: 'frontend-development', stage: '03-implementation', category: 'implementation', description: '实现前端变更' },
+  { name: 'database-change', stage: '03-implementation', category: 'implementation', description: '执行数据库变更' },
+  { name: 'bug-fix', stage: '03-implementation', category: 'implementation', description: '修复缺陷并收敛回归' },
+  { name: 'unit-test', stage: '04-validation', category: 'validation', description: '补充和运行单元测试' },
+  { name: 'code-review', stage: '04-validation', category: 'validation', description: '审查代码变更' },
+  { name: 'security-review', stage: '04-validation', category: 'validation', description: '审查安全风险' },
+  { name: 'performance-review', stage: '04-validation', category: 'validation', description: '审查性能风险' },
+  { name: 'regression-check', stage: '04-validation', category: 'validation', description: '检查回归风险' },
+  { name: 'release-check', stage: '05-delivery', category: 'delivery', description: '检查发布前准备' },
+  { name: 'release-validation', stage: '05-delivery', category: 'delivery', description: '验证发布结果' },
+  { name: 'change-log', stage: '05-delivery', category: 'delivery', description: '记录变更说明' },
+  { name: 'deployment-guide', stage: '05-delivery', category: 'delivery', description: '整理部署和交付指南' },
+  { name: 'framework-guide', stage: 'shared', category: 'shared', description: '提供框架约束和约定' },
+  { name: 'codebase-learning', stage: 'shared', category: 'shared', description: '帮助快速理解代码库' },
+  { name: 'evidence-collector', stage: 'shared', category: 'shared', description: '收集可追溯证据' }
+];
 
 const TOOL_CONFIGS = {
   codex: { dir: '.codex/skills/pigcloud', rootFile: '.codex/AGENTS.md', markers: ['.codex/AGENTS.md', '.codex'] },
@@ -126,9 +137,15 @@ function resolveRequestedTools(toolOption, cwd = getInstallRoot()) {
   return [normalized];
 }
 
-function getSkillInfo(name) {
-  return SKILLS.find(skill => skill.name === name);
-}
+function getSkillInfo(name) {
+  return SKILLS.find(skill => skill.name === name);
+}
+
+function getSkillSourceDir(skillName) {
+  const info = getSkillInfo(skillName);
+  if (!info) return null;
+  return path.join(SKILLS_DIR, info.stage, info.name);
+}
 
 function getSelectedSkills(rawSkills, includeAll = false) {
   if (includeAll || !rawSkills) return [...SKILLS.map(skill => skill.name)];
@@ -202,19 +219,118 @@ async function ensureDir(targetPath) {
   await fs.mkdir(targetPath, { recursive: true });
 }
 
-async function copyDirectory(sourcePath, destinationPath) {
-  await ensureDir(path.dirname(destinationPath));
-  await fs.cp(sourcePath, destinationPath, { recursive: true, force: true });
-}
-
-async function copyDirectoryIfMissing(sourcePath, destinationPath) {
+async function copyDirectory(sourcePath, destinationPath) {
+  await ensureDir(path.dirname(destinationPath));
+  await fs.cp(sourcePath, destinationPath, { recursive: true, force: true });
+}
+
+async function copyDirectoryIfMissing(sourcePath, destinationPath) {
   if (await pathExists(destinationPath)) {
     return false;
   }
 
-  await copyDirectory(sourcePath, destinationPath);
-  return true;
-}
+  await copyDirectory(sourcePath, destinationPath);
+  return true;
+}
+
+async function readDirectoryEntries(targetPath) {
+  try {
+    return await fs.readdir(targetPath, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+}
+
+async function fileDigest(filePath) {
+  const content = await fs.readFile(filePath);
+  return crypto.createHash('sha1').update(content).digest('hex');
+}
+
+async function filesAreEqual(sourcePath, destinationPath) {
+  try {
+    const [sourceStats, destinationStats] = await Promise.all([
+      fs.stat(sourcePath),
+      fs.stat(destinationPath)
+    ]);
+
+    if (!sourceStats.isFile() || !destinationStats.isFile()) {
+      return false;
+    }
+
+    if (sourceStats.size !== destinationStats.size) {
+      return false;
+    }
+
+    if (sourceStats.size === 0) {
+      return true;
+    }
+
+    const [sourceDigest, destinationDigest] = await Promise.all([
+      fileDigest(sourcePath),
+      fileDigest(destinationPath)
+    ]);
+
+    return sourceDigest === destinationDigest;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function syncFile(sourcePath, destinationPath) {
+  if (await filesAreEqual(sourcePath, destinationPath)) {
+    return false;
+  }
+
+  await ensureDir(path.dirname(destinationPath));
+  await fs.copyFile(sourcePath, destinationPath);
+  return true;
+}
+
+async function syncDirectory(sourcePath, destinationPath) {
+  const sourceEntries = await readDirectoryEntries(sourcePath);
+  const destinationExists = await pathExists(destinationPath);
+
+  if (destinationExists) {
+    const destinationStats = await fs.stat(destinationPath);
+    if (!destinationStats.isDirectory()) {
+      await removePath(destinationPath);
+    }
+  }
+
+  await ensureDir(destinationPath);
+
+  const destinationEntries = await readDirectoryEntries(destinationPath);
+  const sourceNames = new Set(sourceEntries.map(entry => entry.name));
+
+  for (const entry of sourceEntries) {
+    const sourceEntryPath = path.join(sourcePath, entry.name);
+    const destinationEntryPath = path.join(destinationPath, entry.name);
+
+    if (entry.isDirectory()) {
+      await syncDirectory(sourceEntryPath, destinationEntryPath);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      await syncFile(sourceEntryPath, destinationEntryPath);
+      continue;
+    }
+
+    await copyDirectory(sourceEntryPath, destinationEntryPath);
+  }
+
+  for (const entry of destinationEntries) {
+    if (!sourceNames.has(entry.name)) {
+      await removePath(path.join(destinationPath, entry.name));
+    }
+  }
+}
 
 async function readJson(filePath) {
   const content = await fs.readFile(filePath, 'utf8');
@@ -230,22 +346,22 @@ async function removePath(targetPath) {
   await fs.rm(targetPath, { recursive: true, force: true });
 }
 
-async function copySkill(skillName, tool, cwd = process.cwd()) {
-  const skill = normalizeSkillName(skillName);
-  if (!getSkillInfo(skill)) {
-    throw new Error(`Unknown skill: ${skillName}`);
-  }
+async function copySkill(skillName, tool, cwd = process.cwd()) {
+  const skill = normalizeSkillName(skillName);
+  const sourceDir = getSkillSourceDir(skill);
+  if (!sourceDir) {
+    throw new Error(`Unknown skill: ${skillName}`);
+  }
 
   const targetSkillDir = getTargetSkillDir(tool, cwd);
   if (!targetSkillDir) {
     throw new Error(`Unsupported tool: ${tool}`);
-  }
-
-  const sourceDir = path.join(SKILLS_DIR, skill);
-  const destDir = path.join(targetSkillDir, skill);
-  await ensureDir(targetSkillDir);
-  await copyDirectory(sourceDir, destDir);
-}
+  }
+
+  const destDir = path.join(targetSkillDir, skill);
+  await ensureDir(targetSkillDir);
+  await syncDirectory(sourceDir, destDir);
+}
 
 async function writeRootFile(tool, cwd = process.cwd()) {
   const config = TOOL_CONFIGS[tool];
@@ -261,16 +377,14 @@ async function writeRootFile(tool, cwd = process.cwd()) {
 
 async function copySkillToCodexHome(skillName) {
   const skill = normalizeSkillName(skillName);
-  if (!getSkillInfo(skill)) {
+  const sourceDir = getSkillSourceDir(skill);
+  if (!sourceDir) {
     throw new Error(`Unknown skill: ${skillName}`);
   }
 
-  const sourceDir = path.join(SKILLS_DIR, skill);
   const destDir = path.join(CODEX_HOME_SKILLS_NAMESPACE_DIR, skill);
   await removePath(path.join(CODEX_HOME_SKILLS_DIR, skill));
-  await removePath(destDir);
-  await ensureDir(CODEX_HOME_SKILLS_NAMESPACE_DIR);
-  await copyDirectory(sourceDir, destDir);
+  await syncDirectory(sourceDir, destDir);
 }
 
 async function clearCodexPersonalSkillsNamespace() {
@@ -326,7 +440,7 @@ async function installCodexCommandPack() {
 
   const destDir = path.join(CODEX_PLUGINS_DIR, COMMAND_PACK_NAME);
   await ensureDir(CODEX_PLUGINS_DIR);
-  await copyDirectory(COMMAND_PACK_SOURCE, destDir);
+  await syncDirectory(COMMAND_PACK_SOURCE, destDir);
   await writeCodexMarketplaceEntry(COMMAND_PACK_NAME);
 }
 
@@ -343,33 +457,44 @@ async function installSharedWorkspaceAssets(cwd = getInstallRoot()) {
   }
 }
 
-async function installSkills(skills, tool, cwd = getInstallRoot(), options = {}) {
-  const { resetCodexNamespace = false } = options;
-  await installSharedWorkspaceAssets(cwd);
-  if (tool === 'codex' && resetCodexNamespace) {
-    await clearCodexPersonalSkillsNamespace();
-    await clearCodexLegacyFlatSkills(skills);
+async function syncCodexSkills(skills) {
+  const selectedSkills = [...new Set(skills.map(skill => normalizeSkillName(skill)).filter(Boolean))];
+  const selectedSkillNames = new Set(selectedSkills);
+
+  await ensureDir(CODEX_HOME_SKILLS_NAMESPACE_DIR);
+
+  for (const skill of selectedSkills) {
+    await copySkillToCodexHome(skill);
+  }
+
+  const existingEntries = await readDirectoryEntries(CODEX_HOME_SKILLS_NAMESPACE_DIR);
+  for (const entry of existingEntries) {
+    if (!selectedSkillNames.has(entry.name)) {
+      await removePath(path.join(CODEX_HOME_SKILLS_NAMESPACE_DIR, entry.name));
+    }
   }
+}
+
+async function installSkills(skills, tool, cwd = getInstallRoot()) {
+  await installSharedWorkspaceAssets(cwd);
   for (const skill of skills) {
     await copySkill(skill, tool, cwd);
   }
   await writeRootFile(tool, cwd);
   if (tool === 'codex') {
-    for (const skill of skills) {
-      await copySkillToCodexHome(skill);
-    }
-    await installCodexCommandPack();
-  }
-}
-
-async function installSkillsForTools(skills, tools, cwd = getInstallRoot(), options = {}) {
+    await syncCodexSkills(skills);
+    await installCodexCommandPack();
+  }
+}
+
+async function installSkillsForTools(skills, tools, cwd = getInstallRoot()) {
   const uniqueTools = [...new Set(tools.filter(Boolean))];
   if (uniqueTools.length === 0) {
     throw new Error('Unable to resolve any install targets.');
   }
 
   for (const tool of uniqueTools) {
-    await installSkills(skills, tool, cwd, options);
+    await installSkills(skills, tool, cwd);
   }
 }
 
@@ -404,45 +529,35 @@ function parseArgs(argv) {
       continue;
     }
 
-    if (token === '-b' || token === '--bundle') {
-      options.bundle = argv[++index];
-      continue;
-    }
-
-    if (token.startsWith('--bundle=')) {
-      options.bundle = token.slice('--bundle='.length);
-      continue;
-    }
-
-    if (token === '-k' || token === '--skill') {
-      options.skill = argv[++index];
-      continue;
-    }
-
-    if (token.startsWith('--skill=')) {
-      options.skill = token.slice('--skill='.length);
-      continue;
-    }
-
-    if (token === '-p' || token === '--profile') {
-      options.profile = argv[++index];
-      continue;
-    }
-
-    if (token.startsWith('--profile=')) {
-      options.profile = token.slice('--profile='.length);
-      continue;
-    }
-
-    if (token === '-f' || token === '--files') {
-      options.files = argv[++index];
-      continue;
-    }
-
-    if (token.startsWith('--files=')) {
-      options.files = token.slice('--files='.length);
-      continue;
-    }
+    if (token === '-k' || token === '--skill') {
+      options.skill = argv[++index];
+      continue;
+    }
+
+    if (token.startsWith('--skill=')) {
+      options.skill = token.slice('--skill='.length);
+      continue;
+    }
+
+    if (token === '-g' || token === '--stage') {
+      options.stage = argv[++index];
+      continue;
+    }
+
+    if (token.startsWith('--stage=')) {
+      options.stage = token.slice('--stage='.length);
+      continue;
+    }
+
+    if (token === '-o' || token === '--overlay') {
+      options.overlay = argv[++index];
+      continue;
+    }
+
+    if (token.startsWith('--overlay=')) {
+      options.overlay = token.slice('--overlay='.length);
+      continue;
+    }
 
     positionals.push(token);
   }
@@ -459,8 +574,8 @@ function printHelp() {
   console.log('  pig-skills auto [--skills a,b] [--all]');
   console.log('  pig-skills codex [--skills a,b] [--all]');
   console.log('  pig-skills bootstrap');
-  console.log('  pig-skills rules [--bundle <bundle>] [--profile <profile>] [--skill name] [--files a,b]');
-  console.log('  pig-skills rules [--bundle <bundle>] [--profile <profile>] [--files a,b]');
+  console.log('  pig-skills rules [--skill name] [--stage <stage>] [--overlay <overlay>]');
+  console.log('  pig-skills rules [--stage <stage>] [--overlay <overlay>]');
   console.log('  pig-skills list');
   console.log('  pig-skills add <skill> [--tool codex]');
   console.log('  pig-skills remove <skill> [--tool codex]');
@@ -468,104 +583,83 @@ function printHelp() {
   console.log('  pig-skills update [--tool codex]');
 }
 
-async function ensureRuntimeForInstall() {
-  if (!commandAvailable('npm')) {
-    throw new Error('npm is not available. Install Node.js LTS first, then rerun the command.');
-  }
-
-  return { installed: false, skipped: false, npmPath: 'npm' };
-}
-
-async function run() {
-  const { options, positionals } = parseArgs(process.argv.slice(2));
-  const command = positionals[0];
+async function run() {
+  const { options, positionals } = parseArgs(process.argv.slice(2));
+  const command = positionals[0];
 
   if (!command) {
     printHelp();
     return;
   }
 
-  if (command === 'init') {
-    const skills = getSelectedSkills(options.skills, options.all || !options.skills);
-    try {
-      await ensureRuntimeForInstall();
+  if (command === 'init') {
+    const skills = getSelectedSkills(options.skills, options.all || !options.skills);
+    try {
       const tools = resolveRequestedTools(options.tool);
-      await installSkillsForTools(skills, tools, getInstallRoot(), { resetCodexNamespace: true });
+      await installSkillsForTools(skills, tools, getInstallRoot());
       console.log(chalk.green(`Installed ${skills.length} skills for ${tools.join(', ')}`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exitCode = 1;
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exitCode = 1;
     }
     return;
   }
 
-  if (command === 'auto') {
-    const skills = getSelectedSkills(options.skills, options.all || !options.skills);
-    try {
-      await ensureRuntimeForInstall();
+  if (command === 'auto') {
+    const skills = getSelectedSkills(options.skills, options.all || !options.skills);
+    try {
       const tools = resolveRequestedTools('auto');
-      await installSkillsForTools(skills, tools, getInstallRoot(), { resetCodexNamespace: true });
+      await installSkillsForTools(skills, tools, getInstallRoot());
       console.log(chalk.green(`Auto-installed ${skills.length} skills for ${tools.join(', ')}`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exitCode = 1;
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exitCode = 1;
     }
     return;
   }
 
-  if (command === 'codex') {
-    const skills = getSelectedSkills(options.skills, options.all || !options.skills);
-    try {
-      await ensureRuntimeForInstall();
-      await installSkills(skills, 'codex', getInstallRoot(), { resetCodexNamespace: true });
+  if (command === 'codex') {
+    const skills = getSelectedSkills(options.skills, options.all || !options.skills);
+    try {
+      await installSkills(skills, 'codex', getInstallRoot());
       console.log(chalk.green(`Synced ${skills.length} skills into Codex`));
-      console.log(chalk.green(`Installed Codex command pack: ${COMMAND_PACK_NAME}`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exitCode = 1;
+      console.log(chalk.green(`Installed Codex command pack: ${COMMAND_PACK_NAME}`));
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exitCode = 1;
     }
     return;
   }
 
-  if (command === 'rules') {
-    try {
-      if (options.bundle) {
-        process.env.PIG_SKILLS_RULE_BUNDLE = options.bundle;
-      }
-      if (options.profile) {
-        process.env.PIG_SKILLS_RULE_PROFILE = options.profile;
-      }
-      if (options.skill) {
-        process.env.PIG_SKILLS_RULE_SKILL = options.skill;
-      }
-      if (options.files) {
-        process.env.PIG_SKILLS_CHANGED_FILES = options.files;
-      }
-      const selection = detectRulesBundle(
-        process.env.INIT_CWD || process.cwd(),
-        options.files ? options.files.split(',').map(item => item.trim()).filter(Boolean) : []
-      );
-      console.log(JSON.stringify(selection, null, 2));
-    } catch (error) {
-      console.error(chalk.red(error.message));
+  if (command === 'rules') {
+    try {
+      if (options.stage) {
+        process.env.PIG_SKILLS_RULE_STAGE = options.stage;
+      }
+      if (options.skill) {
+        process.env.PIG_SKILLS_RULE_SKILL = options.skill;
+      }
+      if (options.overlay) {
+        process.env.PIG_SKILLS_RULE_OVERLAY = options.overlay;
+      }
+      const selection = detectRulesStage(process.env.INIT_CWD || process.cwd());
+      console.log(JSON.stringify(selection, null, 2));
+    } catch (error) {
+      console.error(chalk.red(error.message));
       process.exitCode = 1;
     }
     return;
   }
 
-  if (command === 'bootstrap') {
-    try {
-      const result = await ensureRuntimeForInstall();
-      if (result.skipped) {
-        console.log(chalk.yellow('Runtime bootstrap skipped by PIG_SKILLS_SKIP_RUNTIME_BOOTSTRAP.'));
-      } else if (result.installed) {
-        console.log(chalk.green('Node.js/npm runtime is ready.'));
-      } else {
-        console.log(chalk.green('Node.js/npm runtime is already available.'));
-      }
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exitCode = 1;
+  if (command === 'bootstrap') {
+    try {
+      if (!commandAvailable('npm')) {
+        throw new Error('npm is not available. Install Node.js LTS first, then rerun the command.');
+      }
+      console.log(chalk.green('Node.js/npm runtime is already available.'));
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exitCode = 1;
     }
     return;
   }
@@ -661,22 +755,22 @@ async function run() {
       return;
     }
 
-    console.log(chalk.blue(info.name));
-    console.log(chalk.gray(`Category: ${info.category}`));
-    console.log(chalk.gray(`Description: ${info.description}`));
-    console.log(chalk.gray(`Path: skills/${info.name}/SKILL.md`));
-    return;
-  }
+    console.log(chalk.blue(info.name));
+    console.log(chalk.gray(`Category: ${info.category}`));
+    console.log(chalk.gray(`Description: ${info.description}`));
+    console.log(chalk.gray(`Path: skills/${info.stage}/${info.name}/SKILL.md`));
+    return;
+  }
 
-  if (command === 'update') {
-    try {
+  if (command === 'update') {
+    try {
       await ensureRuntimeForInstall();
       const tools = resolveRequestedTools(options.tool);
-      await installSkillsForTools(SKILLS.map(skill => skill.name), tools, getInstallRoot(), { resetCodexNamespace: true });
+      await installSkillsForTools(SKILLS.map(skill => skill.name), tools, getInstallRoot());
       console.log(chalk.green(`Updated ${SKILLS.length} skills for ${tools.join(', ')}`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exitCode = 1;
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exitCode = 1;
     }
     return;
   }