prizmkit 1.1.57 → 1.1.60

package/src/scaffold.js

@@ -10,13 +10,12 @@
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import path from 'path';
-import { readFileSync, existsSync } from 'fs';
-import { fileURLToPath } from 'url';
+import { readFileSync } from 'fs';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { dirname, join } from 'path';
 import { execSync } from 'child_process';
 import {
   loadMetadata,
-  getSkillsDir,
   getAgentsDir,
   getTeamDir,
   getTemplatesDir,
@@ -24,12 +23,16 @@ import {
   getAdaptersDir,
   getRulesDir,
   loadRulesMetadata,
+  getSkillCandidatePaths,
 } from './metadata.js';
 import { generateGitignore } from './gitignore-template.js';
 import { buildManifest, writeManifest } from './manifest.js';
+import { defaultCliForPlatform, expandPlatforms, isKnownPlatform, platformLabel, projectMemoryFile } from './platforms.js';
+import { normalizeRuntime, runtimeLabel, RUNTIME_UNIX, RUNTIME_WINDOWS } from './runtimes.js';
 
 const __scaffoldDirname = dirname(fileURLToPath(import.meta.url));
 const scaffoldPkg = JSON.parse(readFileSync(join(__scaffoldDirname, '..', 'package.json'), 'utf-8'));
+const PIPELINE_INSTALL_EXCLUDE = new Set(['tests', 'docs', '__pycache__', 'node_modules', '.DS_Store']);
 
 // ============================================================
 // Adapter 动态加载
@@ -42,12 +45,12 @@ const scaffoldPkg = JSON.parse(readFileSync(join(__scaffoldDirname, '..', 'packa
 async function loadAdapter(platform, adapterName) {
   const adaptersDir = getAdaptersDir();
   const adapterPath = path.join(adaptersDir, platform, adapterName);
-  return import(adapterPath);
+  return import(pathToFileURL(adapterPath).href);
 }
 
 async function loadSharedFrontmatter() {
   const adaptersDir = getAdaptersDir();
-  return import(path.join(adaptersDir, 'shared', 'frontmatter.js'));
+  return import(pathToFileURL(path.join(adaptersDir, 'shared', 'frontmatter.js')).href);
 }
 
 // ============================================================
@@ -81,6 +84,13 @@ export async function resolveSkillList(suite) {
   return suiteDef.skills;
 }
 
+export function resolveRuleNamesForRuntime(rulesMeta, rulesPreset = 'recommended', runtime = 'unix') {
+  const preset = rulesMeta.presets[rulesPreset] || rulesMeta.presets.recommended;
+  const ruleNames = preset?.rules || [];
+  if (normalizeRuntime(runtime) !== RUNTIME_WINDOWS) return ruleNames;
+  return ruleNames.filter(name => name !== 'general/prefer-linux-commands');
+}
+
 // ============================================================
 // 安装函数
 // ============================================================
@@ -88,8 +98,7 @@ export async function resolveSkillList(suite) {
 /**
  * 安装 Skills（纯 Copy 模式）
  */
-export async function installSkills(platform, skills, projectRoot, dryRun) {
-  const skillsDir = getSkillsDir();
+export async function installSkills(platform, skills, projectRoot, dryRun, runtime = 'unix') {
   const { parseFrontmatter, buildMarkdown } = await loadSharedFrontmatter();
   
   // Load metadata to get skill -> category + subcategory mapping
@@ -103,9 +112,13 @@ export async function installSkills(platform, skills, projectRoot, dryRun) {
 
   // Load Claude command adapter for skill conversion
   let convertSkillToCommand;
+  let convertSkillToCodex;
   if (platform === 'claude') {
     const commandAdapter = await loadAdapter('claude', 'command-adapter.js');
     convertSkillToCommand = commandAdapter.convertSkillToCommand;
+  } else if (platform === 'codex') {
+    const codexSkillAdapter = await loadAdapter('codex', 'skill-adapter.js');
+    convertSkillToCodex = codexSkillAdapter.convertSkill;
   }
 
   for (const skillName of skills) {
@@ -128,21 +141,9 @@ export async function installSkills(platform, skills, projectRoot, dryRun) {
       continue;
     }
 
-    // Build path: prefer hierarchical layout (<skillsDir>/<category>/[<subcategory>/]/<skillName>),
-    // fallback to flat bundled layout (<skillsDir>/<skillName>) for npm package compatibility.
-    let corePath = subcategory
-      ? path.resolve(skillsDir, category, subcategory, skillName)
-      : path.resolve(skillsDir, category, skillName);
-    // Ensure resolved path stays within skillsDir
-    if (!corePath.startsWith(path.resolve(skillsDir))) {
-      console.warn(`  ⚠ Skill ${skillName} path escapes skills directory, skipping`);
-      continue;
-    }
-    if (!await fs.pathExists(corePath)) {
-      corePath = path.resolve(skillsDir, skillName);
-      if (!corePath.startsWith(path.resolve(skillsDir))) continue;
-    }
-    if (!await fs.pathExists(corePath)) continue;
+    const corePath = getSkillCandidatePaths(skillName, metadata.skills[skillName], runtime)
+      .find(candidatePath => fs.pathExistsSync(candidatePath));
+    if (!corePath) continue;
 
     const stat = await fs.stat(corePath);
     if (!stat.isDirectory()) continue;
@@ -205,6 +206,26 @@ export async function installSkills(platform, skills, projectRoot, dryRun) {
         }
       }
       console.log(chalk.green(`      ✓ .claude/commands/${skillName}.md`));
+    } else if (platform === 'codex') {
+      const content = await fs.readFile(skillMdPath, 'utf8');
+      const converted = convertSkillToCodex(content, skillName);
+      const targetDir = path.join(projectRoot, '.agents', 'skills', skillName);
+
+      if (dryRun) {
+        console.log(chalk.gray(`      [dry-run] .agents/skills/${skillName}/`));
+        continue;
+      }
+
+      await fs.ensureDir(targetDir);
+      await fs.writeFile(path.join(targetDir, 'SKILL.md'), converted);
+
+      const codexEntries = await fs.readdir(corePath, { withFileTypes: true });
+      for (const entry of codexEntries) {
+        if (entry.isDirectory()) {
+          await fs.copy(path.join(corePath, entry.name), path.join(targetDir, entry.name));
+        }
+      }
+      console.log(chalk.green(`      ✓ .agents/skills/${skillName}/`));
     }
   }
 }
@@ -221,6 +242,9 @@ export async function installAgents(platform, projectRoot, dryRun) {
   if (platform === 'claude') {
     const agentAdapter = await loadAdapter('claude', 'agent-adapter.js');
     convertAgentFn = agentAdapter.convertAgent;
+  } else if (platform === 'codex') {
+    const agentAdapter = await loadAdapter('codex', 'agent-adapter.js');
+    convertAgentFn = agentAdapter.convertAgent;
   }
 
   for (const file of agentFiles) {
@@ -247,6 +271,19 @@ export async function installAgents(platform, projectRoot, dryRun) {
       await fs.ensureDir(targetDir);
       await fs.writeFile(path.join(targetDir, file), converted);
       console.log(chalk.green(`      ✓ .claude/agents/${file}`));
+    } else if (platform === 'codex') {
+      const baseName = path.basename(file, '.md');
+      const targetFile = `${baseName}.toml`;
+      const converted = convertAgentFn(content, { name: baseName });
+      const targetDir = path.join(projectRoot, '.codex', 'agents');
+      if (dryRun) {
+        console.log(chalk.gray(`      [dry-run] .codex/agents/${targetFile}`));
+        continue;
+      }
+      await fs.ensureDir(targetDir);
+      await fs.writeFile(path.join(targetDir, targetFile), converted);
+      await fs.remove(path.join(targetDir, file));
+      console.log(chalk.green(`      ✓ .codex/agents/${targetFile}`));
     }
   }
 }
@@ -340,18 +377,50 @@ export async function installTeamConfig(platform, projectRoot, dryRun) {
     );
 
     console.log(chalk.green(`      ✓ .claude/team-info.json`));
+  } else if (platform === 'codex') {
+    const codexDir = path.join(projectRoot, '.codex');
+
+    if (dryRun) {
+      console.log(chalk.gray(`      [dry-run] .codex/team-info.json`));
+      return;
+    }
+
+    await fs.ensureDir(codexDir);
+
+    const teamConfig = {
+      name: teamDef.name,
+      description: teamDef.description,
+      platform: 'codex',
+      orchestrationMode: 'codex-subagents',
+      agents: teamDef.members
+        .filter(m => m.role !== 'lead')
+        .map(m => ({
+          name: m.name,
+          role: m.role,
+          agentFile: `.codex/agents/${m.agentDefinition}.toml`,
+          prompt: m.prompt,
+          subscriptions: m.subscriptions || [],
+        })),
+    };
+
+    await fs.writeFile(
+      path.join(codexDir, 'team-info.json'),
+      JSON.stringify(teamConfig, null, 2)
+    );
+
+    console.log(chalk.green(`      ✓ .codex/team-info.json`));
   }
 }
 
 /**
  * 安装平台配置文件（settings/hooks/rules）
  */
-export async function installSettings(platform, projectRoot, options, dryRun) {
+export async function installSettings(platform, projectRoot, options, dryRun, runtime = 'unix') {
+  const normalizedRuntime = normalizeRuntime(runtime);
   // 从文件加载 rules
   const rulesMeta = await loadRulesMetadata();
   const rulesPreset = options.rules || 'recommended';
-  const preset = rulesMeta.presets[rulesPreset] || rulesMeta.presets.recommended;
-  const ruleNames = preset?.rules || [];
+  const ruleNames = resolveRuleNamesForRuntime(rulesMeta, rulesPreset, runtime);
   const rulesDir = getRulesDir();
   const ruleFiles = [];
   for (const name of ruleNames) {
@@ -374,9 +443,12 @@ export async function installSettings(platform, projectRoot, options, dryRun) {
 
     await fs.ensureDir(path.dirname(settingsPath));
 
-    // Read hook definition from unified template
+    // Read hook definition from unified template.
+    // Windows runtime intentionally omits POSIX shell hook commands.
     const templatesDir = getTemplatesDir();
-    const hookTemplate = await fs.readJSON(path.join(templatesDir, 'hooks', 'commit-intent.json'));
+    const hookTemplate = normalizedRuntime === RUNTIME_WINDOWS
+      ? { hooks: {} }
+      : await fs.readJSON(path.join(templatesDir, 'hooks', 'commit-intent.json'));
 
     await fs.writeFile(settingsPath, JSON.stringify(hookTemplate, null, 2));
     console.log(chalk.green(`      ✓ .codebuddy/settings.json`));
@@ -399,13 +471,18 @@ export async function installSettings(platform, projectRoot, options, dryRun) {
 
     await fs.ensureDir(claudeDir);
 
-    // Read hook definition from unified template
+    // Read hook definition from unified template.
+    // Windows runtime intentionally omits POSIX shell hook commands.
     const templatesDir = getTemplatesDir();
-    const hookTemplate = await fs.readJSON(path.join(templatesDir, 'hooks', 'commit-intent.json'));
+    const hookTemplate = normalizedRuntime === RUNTIME_WINDOWS
+      ? { hooks: {} }
+      : await fs.readJSON(path.join(templatesDir, 'hooks', 'commit-intent.json'));
 
     // Settings
-    const permissions = [
+    const permissions = normalizedRuntime === RUNTIME_WINDOWS ? [] : [
       'Bash(python3 .prizmkit/dev-pipeline/scripts/*)',
+      'Bash(python .prizmkit/dev-pipeline/scripts/*)',
+      'Bash(py -3 .prizmkit/dev-pipeline/scripts/*)',
       'Bash(git add *)',
       'Bash(git commit *)',
       'Bash(git diff *)',
@@ -413,12 +490,15 @@ export async function installSettings(platform, projectRoot, options, dryRun) {
       'Bash(git log *)',
       'Bash(jq *)',
     ];
-    if (options.pipeline) {
-      // 动态扫描 pipeline 目录中的 .sh 入口脚本（run-*、launch-*），自动添加执行权限
-      const pipelineDir = getPipelineDir();
+    if (options.pipeline && normalizedRuntime !== RUNTIME_WINDOWS) {
+      // 动态扫描 pipeline 目录中的入口脚本，自动添加执行权限
+      const pipelineDir = getPipelineDir(runtime);
       try {
         const pipelineEntries = await fs.readdir(pipelineDir);
-        const entryScripts = pipelineEntries.filter(f => /^(run-|launch-|retry-|reset-).*\.sh$/.test(f));
+        const entryRe = normalizedRuntime === RUNTIME_WINDOWS
+          ? /^(run-|launch-|retry-|reset-).*\.ps1$/i
+          : /^(run-|launch-|retry-|reset-).*\.sh$/;
+        const entryScripts = pipelineEntries.filter(f => entryRe.test(f));
         for (const script of entryScripts) {
           permissions.push(`Bash(./.prizmkit/dev-pipeline/${script} *)`);
         }
@@ -429,7 +509,7 @@ export async function installSettings(platform, projectRoot, options, dryRun) {
 
     const settings = {
       permissions: { allow: permissions },
-      hooks: {
+      hooks: normalizedRuntime === RUNTIME_WINDOWS ? {} : {
         ...hookTemplate.hooks,
         SessionStart: [
           {
@@ -455,17 +535,54 @@ export async function installSettings(platform, projectRoot, options, dryRun) {
     const { installRules: installClaudeRules } = await loadAdapter('claude', 'rules-adapter.js');
     await installClaudeRules(projectRoot, ruleFiles);
     console.log(chalk.green(`      ✓ .claude/rules/ (${ruleFiles.length} 条规则)`));
+  } else if (platform === 'codex') {
+    const configPath = path.join(projectRoot, '.codex', 'config.toml');
+    const legacySettingsPath = path.join(projectRoot, '.codex', 'prizmkit-settings.json');
+    const allRuleFileNames = Object.keys(rulesMeta.rules || {})
+      .map(name => `${name.includes('/') ? name.split('/').pop() : name}.md`);
+
+    if (dryRun) {
+      console.log(chalk.gray(`      [dry-run] .codex/config.toml`));
+      console.log(chalk.gray(`      [dry-run] .agents/rules/ (${ruleFiles.length} 条规则)`));
+      return;
+    }
+
+    await fs.ensureDir(path.dirname(configPath));
+    const configToml = `# Generated by PrizmKit for Codex CLI project configuration.
+# Keep project guidance in AGENTS.md; repository skills in .agents/skills/;
+# PrizmKit behavioral rules live in .agents/rules/; native Codex subagents live in .codex/agents/.
+
+project_doc_fallback_filenames = ["CLAUDE.md", "CODEBUDDY.md"]
+
+[agents]
+max_depth = 1
+`;
+    await fs.writeFile(configPath, configToml);
+    await fs.remove(legacySettingsPath);
+    console.log(chalk.green(`      ✓ .codex/config.toml`));
+
+    const {
+      installRules: installCodexRules,
+      removeLegacyCodexRules,
+    } = await loadAdapter('codex', 'rules-adapter.js');
+    await installCodexRules(projectRoot, ruleFiles);
+    removeLegacyCodexRules(projectRoot, allRuleFileNames);
+    console.log(chalk.green(`      ✓ .agents/rules/ (${ruleFiles.length} 条规则)`));
   }
 }
 
 /**
  * 安装 git pre-commit hook（prizm 格式校验）
  */
-export async function installGitHook(projectRoot, dryRun) {
+export async function installGitHook(projectRoot, dryRun, runtime = 'unix') {
   const gitDir = path.join(projectRoot, '.git');
+  const normalizedRuntime = normalizeRuntime(runtime);
 
   if (dryRun) {
-    console.log(chalk.gray('      [dry-run] .git/hooks/pre-commit (prizm format check)'));
+    const hookLabel = normalizedRuntime === RUNTIME_WINDOWS
+      ? '.git/hooks/pre-commit skipped (Windows runtime: no shell hook)'
+      : '.git/hooks/pre-commit (prizm format check)';
+    console.log(chalk.gray(`      [dry-run] ${hookLabel}`));
     return;
   }
 
@@ -475,6 +592,27 @@ export async function installGitHook(projectRoot, dryRun) {
   const hooksDir = path.join(gitDir, 'hooks');
   const preCommitPath = path.join(hooksDir, 'pre-commit');
 
+  if (normalizedRuntime === RUNTIME_WINDOWS) {
+    if (fs.existsSync(preCommitPath) && fs.existsSync(templatePath)) {
+      const existing = fs.readFileSync(preCommitPath, 'utf8');
+      const shellTemplate = fs.readFileSync(templatePath, 'utf8');
+      if (existing === shellTemplate) {
+        await fs.remove(preCommitPath);
+        console.log(chalk.gray('      • .git/hooks/pre-commit shell hook removed for Windows runtime'));
+      } else if (existing.includes(shellTemplate)) {
+        const cleaned = existing.replace(shellTemplate, '').replace(/\n{3,}/g, '\n\n').trimEnd();
+        if (cleaned) {
+          fs.writeFileSync(preCommitPath, `${cleaned}\n`);
+        } else {
+          await fs.remove(preCommitPath);
+        }
+        console.log(chalk.gray('      • PrizmKit shell hook block removed for Windows runtime'));
+      }
+    }
+    console.log(chalk.gray('      • Git hook skipped (Windows runtime uses no shell hook)'));
+    return;
+  }
+
   fs.mkdirSync(hooksDir, { recursive: true });
 
   if (fs.existsSync(preCommitPath)) {
@@ -491,11 +629,12 @@ export async function installGitHook(projectRoot, dryRun) {
 }
 
 /**
- * 安装 PrizmKit 脚本到 .prizmkit/scripts/（始终安装）
+ * 安装 PrizmKit 脚本到 .prizmkit/scripts/（Windows runtime 跳过 shell-only 脚本）
  */
-export async function installPrizmkitScripts(projectRoot, dryRun) {
+export async function installPrizmkitScripts(projectRoot, dryRun, runtime = 'unix') {
   const scriptsDir = path.join(projectRoot, '.prizmkit', 'scripts');
   const templateHooksDir = path.join(getTemplatesDir(), 'hooks');
+  const normalizedRuntime = normalizeRuntime(runtime);
 
   const scripts = [
     'validate-prizm-docs.sh',
@@ -504,8 +643,17 @@ export async function installPrizmkitScripts(projectRoot, dryRun) {
 
   if (dryRun) {
     for (const s of scripts) {
-      console.log(chalk.gray(`      [dry-run] .prizmkit/scripts/${s}`));
+      const action = normalizedRuntime === RUNTIME_WINDOWS ? 'skip shell script' : `.prizmkit/scripts/${s}`;
+      console.log(chalk.gray(`      [dry-run] ${action}`));
+    }
+    return;
+  }
+
+  if (normalizedRuntime === RUNTIME_WINDOWS) {
+    for (const s of scripts) {
+      await fs.remove(path.join(scriptsDir, s));
     }
+    console.log(chalk.gray('      • shell-only PrizmKit scripts skipped for Windows runtime'));
     return;
   }
 
@@ -525,16 +673,16 @@ const PRIZMKIT_MARKER_START = '<!-- PRIZMKIT:START';
 const PRIZMKIT_MARKER_END = '<!-- PRIZMKIT:END -->';
 
 /**
- * Merge PrizmKit template content into a project memory file (CLAUDE.md / CODEBUDDY.md).
+ * Merge PrizmKit template content into a project memory file.
  * - File missing → create with template content
  * - File exists with markers → replace content between markers
  * - File exists without markers → append template content
  */
 export async function installProjectMemory(platform, projectRoot, dryRun) {
   const templatesDir = getTemplatesDir();
-  const skillsDir = getSkillsDir();
   const templateName = 'project-memory-template.md';
-  const targetName = platform === 'claude' ? 'CLAUDE.md' : 'CODEBUDDY.md';
+  const targetName = projectMemoryFile(platform);
+  if (!targetName) return;
   const targetPath = path.join(projectRoot, targetName);
 
   // Template lives in core/templates/ (bundled as templates/).
@@ -548,7 +696,19 @@ export async function installProjectMemory(platform, projectRoot, dryRun) {
     return;
   }
 
-  const templateContent = (await fs.readFile(templatePath, 'utf-8')).trimEnd();
+  let templateContent = (await fs.readFile(templatePath, 'utf-8')).trimEnd();
+  if (platform === 'codex') {
+    templateContent = templateContent.replace(
+      '### Available Commands\nRun `/prizm-kit` to see all available PrizmKit commands.',
+      `### Available PrizmKit Skills
+Codex discovers repository skills from \`.agents/skills/\`. When a user or prompt mentions \`/prizmkit-xxx\`, use the matching skill at \`.agents/skills/prizmkit-xxx/SKILL.md\`.
+
+- Start with \`.agents/skills/prizm-kit/SKILL.md\` to see all available PrizmKit skills.
+- Skill assets and references live inside each \`.agents/skills/<skill>/\` directory.
+- PrizmKit behavioral rules live in \`.agents/rules/\`; read the relevant Markdown guidance before commit, documentation, or context-loading work.
+- Native Codex subagents live in \`.codex/agents/*.toml\`; use them when spawning or coordinating subagents.`
+    );
+  }
 
   if (dryRun) {
     console.log(chalk.gray(`      [dry-run] ${targetName}`));
@@ -599,25 +759,15 @@ function collectFilesRecursive(dir, base = '') {
   return files;
 }
 
-/**
- * Resolve the list of pipeline files from the source (bundled) pipeline directory.
- * Used by upgrade to compute diff before actual installation.
- * @returns {string[]} relative file paths
- */
-export function resolvePipelineFileList() {
-  const pipelineSource = getPipelineDir();
-  if (!pipelineSource || !fs.pathExistsSync(pipelineSource)) return [];
-
-  // 动态扫描，与 installPipeline() 保持一致的排除规则
-  const EXCLUDE = new Set(['tests', 'docs', '__pycache__', 'node_modules', '.DS_Store']);
+function collectInstallablePipelineFiles(pipelineSource) {
   let allEntries;
   try {
     allEntries = fs.readdirSync(pipelineSource);
   } catch {
     return [];
   }
-  const items = allEntries.filter(name => !EXCLUDE.has(name) && !name.startsWith('.'));
 
+  const items = allEntries.filter(name => !PIPELINE_INSTALL_EXCLUDE.has(name) && !name.startsWith('.'));
   const files = [];
   for (const item of items) {
     const src = path.join(pipelineSource, item);
@@ -632,13 +782,67 @@ export function resolvePipelineFileList() {
   return files;
 }
 
+/**
+ * Resolve the list of pipeline files from the source (bundled) pipeline directory.
+ * Used by upgrade to compute diff before actual installation.
+ * @returns {string[]} relative file paths
+ */
+export function resolvePipelineFileList(runtime = 'unix') {
+  const pipelineSource = getPipelineDir(runtime);
+  if (!pipelineSource || !fs.pathExistsSync(pipelineSource)) return [];
+  return collectInstallablePipelineFiles(pipelineSource);
+}
+
+async function pruneStalePipelineRuntimeFiles(pipelineTarget, runtime) {
+  if (!await fs.pathExists(pipelineTarget)) return false;
+
+  const staleRuntime = runtime === RUNTIME_WINDOWS ? RUNTIME_UNIX : RUNTIME_WINDOWS;
+  const staleFiles = resolvePipelineFileList(staleRuntime);
+  const currentFiles = new Set(resolvePipelineFileList(runtime));
+  const staleDirs = new Set();
+  let prunedRuntimeSpecificFiles = false;
+
+  for (const relativeFile of staleFiles) {
+    if (currentFiles.has(relativeFile)) continue;
+
+    const targetFile = path.join(pipelineTarget, relativeFile);
+    if (await fs.pathExists(targetFile)) {
+      const stat = await fs.stat(targetFile);
+      if (stat.isFile()) {
+        await fs.remove(targetFile);
+        prunedRuntimeSpecificFiles = true;
+      }
+    }
+
+    const relativeDir = path.dirname(relativeFile);
+    if (relativeDir && relativeDir !== '.') staleDirs.add(relativeDir);
+  }
+
+  const dirsByDepth = [...staleDirs].sort((a, b) => b.split(path.sep).length - a.split(path.sep).length);
+  for (const relativeDir of dirsByDepth) {
+    const targetDir = path.join(pipelineTarget, relativeDir);
+    if (!await fs.pathExists(targetDir)) continue;
+    const entries = await fs.readdir(targetDir);
+    if (entries.length === 0) {
+      await fs.remove(targetDir);
+    }
+  }
+
+  return prunedRuntimeSpecificFiles;
+}
+
 /**
  * 安装 dev-pipeline（纯 Copy 模式）
  * 安装目标：.prizmkit/dev-pipeline/
  * Returns an array of installed file relative paths (relative to .prizmkit/dev-pipeline/).
  */
-export async function installPipeline(projectRoot, dryRun, { forceOverwrite = false } = {}) {
-  const pipelineSource = getPipelineDir();
+export async function installPipeline(projectRoot, dryRun, options = {}) {
+  const runtime = normalizeRuntime(options.runtime);
+  const previousRuntime = options.previousRuntime === undefined
+    ? runtime
+    : normalizeRuntime(options.previousRuntime);
+  const forceOverwrite = Boolean(options.forceOverwrite);
+  const pipelineSource = getPipelineDir(runtime);
   const pipelineTarget = path.join(projectRoot, '.prizmkit', 'dev-pipeline');
 
   if (dryRun) {
@@ -651,51 +855,41 @@ export async function installPipeline(projectRoot, dryRun, { forceOverwrite = fa
   await fs.ensureDir(path.join(projectRoot, '.prizmkit', 'state', 'bugfix'));
   await fs.ensureDir(path.join(projectRoot, '.prizmkit', 'state', 'refactor'));
 
-  // 动态扫描 bundled dev-pipeline 目录，排除不应安装到用户项目的内容
-  const EXCLUDE = new Set(['tests', 'docs', '__pycache__', 'node_modules', '.DS_Store']);
-  const allEntries = await fs.readdir(pipelineSource);
-  const items = allEntries.filter(name => !EXCLUDE.has(name) && !name.startsWith('.'));
+  const runtimeSwitched = previousRuntime !== runtime;
+  const prunedStaleRuntimeFiles = await pruneStalePipelineRuntimeFiles(pipelineTarget, runtime);
+  const overwriteExisting = forceOverwrite || runtimeSwitched || prunedStaleRuntimeFiles;
 
-  let installedCount = 0;
-  const installedFiles = [];
-  for (const item of items) {
-    const src = path.join(pipelineSource, item);
-    const tgt = path.join(pipelineTarget, item);
+  const installedFiles = collectInstallablePipelineFiles(pipelineSource);
+  let copiedCount = 0;
+  let skippedCount = 0;
 
-    if (!await fs.pathExists(src)) continue;
+  for (const relativeFile of installedFiles) {
+    const src = path.join(pipelineSource, relativeFile);
+    const tgt = path.join(pipelineTarget, relativeFile);
 
-    const srcStat = await fs.stat(src);
-
-    if (await fs.pathExists(tgt) && !forceOverwrite) {
-      console.log(chalk.yellow(`      ⚠ .prizmkit/dev-pipeline/${item} 已存在，跳过`));
-      // Still collect existing files for manifest tracking
-      if (srcStat.isDirectory()) {
-        installedFiles.push(...collectFilesRecursive(src, item));
-      } else {
-        installedFiles.push(item);
-      }
+    if (await fs.pathExists(tgt) && !overwriteExisting) {
+      skippedCount++;
       continue;
     }
 
-    await fs.copy(src, tgt);
-    installedCount++;
-
-    // Collect installed file paths
-    if (srcStat.isDirectory()) {
-      installedFiles.push(...collectFilesRecursive(src, item));
-    } else {
-      installedFiles.push(item);
-    }
+    await fs.ensureDir(path.dirname(tgt));
+    await fs.copy(src, tgt, { overwrite: true, errorOnExist: false });
+    copiedCount++;
   }
 
-  console.log(chalk.green(`      ✓ .prizmkit/dev-pipeline/ (${installedCount} 项)`));
+  const skipSuffix = skippedCount ? `, preserved ${skippedCount} existing` : '';
+  console.log(chalk.green(`      ✓ .prizmkit/dev-pipeline/ (${copiedCount} files copied${skipSuffix})`));
 
   // Copy .env.example to .prizmkit/.env.example if it exists in pipeline source
   const envExampleSrc = path.join(pipelineSource, '.env.example');
   const envExampleTgt = path.join(projectRoot, '.prizmkit', '.env.example');
-  if (await fs.pathExists(envExampleSrc) && !await fs.pathExists(envExampleTgt)) {
-    await fs.copy(envExampleSrc, envExampleTgt);
-    console.log(chalk.green(`      ✓ .prizmkit/.env.example (pipeline environment configuration)`));
+  if (await fs.pathExists(envExampleSrc)) {
+    if (overwriteExisting || !(await fs.pathExists(envExampleTgt))) {
+      await fs.copy(envExampleSrc, envExampleTgt, { overwrite: true, errorOnExist: false });
+      console.log(chalk.green(`      ✓ .prizmkit/.env.example (pipeline environment configuration)`));
+    } else {
+      console.log(chalk.gray(`      • .prizmkit/.env.example exists, preserved`));
+    }
   }
 
   return installedFiles;
@@ -839,7 +1033,7 @@ export async function installOpenCli(projectRoot, dryRun, autoDownload = true) {
       console.log(chalk.yellow('      ⚠ Chrome Browser Bridge extension is NOT connected'));
 
       if (autoDownload) {
-        await downloadOpenCliExtension(projectRoot);
+        await downloadOpenCliExtension();
       } else {
         printOpenCliManualSteps();
       }
@@ -859,7 +1053,7 @@ export async function installOpenCli(projectRoot, dryRun, autoDownload = true) {
  * 从 GitHub releases 下载并解压 opencli Chrome 扩展。
  * 省去用户手动下载解压步骤，但仍需在 Chrome 中手动加载。
  */
-async function downloadOpenCliExtension(projectRoot) {
+async function downloadOpenCliExtension() {
   const extDir = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.opencli', 'extension');
 
   // Check if already downloaded
@@ -959,7 +1153,8 @@ export const EXTRAS_REGISTRY = {
 /**
  * 执行纯净安装
  * @param {Object} config
- * @param {string} config.platform - 'codebuddy' | 'claude' | 'both'
+ * @param {string} config.platform - 'codebuddy' | 'claude' | 'codex' | 'both' | 'all'
+ * @param {string} [config.runtime] - 'unix' | 'windows'
  * @param {string} config.skills - 'core' | 'minimal' | 'recommended:<type>'
  * @param {boolean} config.team - 是否启用团队模式
  * @param {boolean} config.pipeline - 是否安装 dev-pipeline
@@ -974,7 +1169,11 @@ export const EXTRAS_REGISTRY = {
  */
 export async function scaffold(config) {
   const { platform, skills, team, pipeline, rules, aiCli, externalSkills, playwrightCli, openCli, openCliAutoDownload, projectRoot, dryRun } = config;
-  const platforms = platform === 'both' ? ['codebuddy', 'claude'] : [platform];
+  const runtime = normalizeRuntime(config.runtime);
+  if (!isKnownPlatform(platform)) {
+    throw new Error(`Unknown platform "${platform}". Expected codebuddy, claude, codex, both, or all.`);
+  }
+  const platforms = expandPlatforms(platform);
 
   if (dryRun) {
     console.log(chalk.yellow('\n  [DRY RUN] 预览将要安装的内容:\n'));
@@ -986,12 +1185,11 @@ export async function scaffold(config) {
   console.log('');
 
   for (const p of platforms) {
-    const platformLabel = p === 'codebuddy' ? 'CodeBuddy' : 'Claude Code';
-    console.log(chalk.bold(`  正在安装 ${platformLabel} 环境...\n`));
+    console.log(chalk.bold(`  正在安装 ${platformLabel(p)} 环境...\n`));
 
     // 1. Skills
     console.log(chalk.blue('    技能文件:'));
-    await installSkills(p, skillList, projectRoot, dryRun);
+    await installSkills(p, skillList, projectRoot, dryRun, runtime);
 
     // 2. Agents
     console.log(chalk.blue('\n    Agent 定义:'));
@@ -1005,7 +1203,7 @@ export async function scaffold(config) {
 
     // 4. Settings/Hooks/Rules
     console.log(chalk.blue('\n    平台配置:'));
-    await installSettings(p, projectRoot, { pipeline, rules }, dryRun);
+    await installSettings(p, projectRoot, { pipeline, rules }, dryRun, runtime);
 
     // 5. Project Memory
     console.log(chalk.blue('\n    项目记忆文件:'));
@@ -1018,7 +1216,7 @@ export async function scaffold(config) {
   let installedPipelineFiles = [];
   if (pipeline) {
     console.log(chalk.blue('    自动化流水线:'));
-    installedPipelineFiles = await installPipeline(projectRoot, dryRun) || [];
+    installedPipelineFiles = await installPipeline(projectRoot, dryRun, { runtime }) || [];
     console.log('');
   }
 
@@ -1097,11 +1295,11 @@ export async function scaffold(config) {
 
   // 12. Git pre-commit hook
   console.log(chalk.blue('    Git Hook:'));
-  await installGitHook(projectRoot, dryRun);
+  await installGitHook(projectRoot, dryRun, runtime);
 
-  // 13. PrizmKit scripts (always installed)
+  // 13. PrizmKit scripts
   console.log(chalk.blue('    PrizmKit 脚本:'));
-  await installPrizmkitScripts(projectRoot, dryRun);
+  await installPrizmkitScripts(projectRoot, dryRun, runtime);
 
   // 14. Write installation manifest
   if (!dryRun) {
@@ -1109,12 +1307,12 @@ export async function scaffold(config) {
     const agentFileNames = (await fs.readdir(agentsDir)).filter(f => f.endsWith('.md'));
     const rulesMeta = await loadRulesMetadata();
     const rulesPresetName = rules || 'recommended';
-    const rulesPresetDef = rulesMeta.presets[rulesPresetName] || rulesMeta.presets.recommended;
-    const ruleFileNames = (rulesPresetDef?.rules || []).map(name => `${name}.md`);
+    const ruleFileNames = resolveRuleNamesForRuntime(rulesMeta, rulesPresetName, runtime).map(name => `${name}.md`);
 
     const manifest = buildManifest({
       version: scaffoldPkg.version,
       platform,
+      runtime,
       suite: skills,
       skills: skillList,
       agents: agentFileNames,
@@ -1142,15 +1340,20 @@ export async function scaffold(config) {
 
   if (!dryRun) {
     // 打印下一步提示
-    const mainPlatform = platforms.includes('claude') ? 'claude' : 'codebuddy';
-    const defaultCli = mainPlatform === 'claude' ? 'claude' : 'cbc';
+    const mainPlatform = platforms.includes('claude') ? 'claude'
+      : platforms.includes('codebuddy') ? 'codebuddy'
+        : platforms[0];
+    const defaultCli = defaultCliForPlatform(mainPlatform);
     const cli = aiCli || defaultCli;
 
     console.log('');
     console.log('  下一步:');
     console.log(`    1. ${chalk.cyan('cd ' + projectRoot)}`);
     console.log(`    2. ${chalk.cyan(cli)}                          ${chalk.gray('# 启动 AI 对话')}`);
-    console.log(`    3. ${chalk.cyan('说 "/prizmkit-init"')}           ${chalk.gray('# 初始化项目上下文')}`);
+    const initInstruction = mainPlatform === 'codex'
+      ? '说 "运行 prizmkit-init"'
+      : '说 "/prizmkit-init"';
+    console.log(`    3. ${chalk.cyan(initInstruction)}           ${chalk.gray('# 初始化项目上下文')}`);
 
     if (pipeline) {
       console.log(`    4. ${chalk.cyan('说 "规划一个应用"')}             ${chalk.gray('# 生成 feature-list.json')}`);
@@ -1166,7 +1369,8 @@ export async function scaffold(config) {
 
     console.log(chalk.gray(`  安装统计:`));
     console.log(chalk.gray(`    技能: ${suiteLabel}`));
-    console.log(chalk.gray(`    平台: ${platforms.map(p => p === 'codebuddy' ? 'CodeBuddy' : 'Claude Code').join(' + ')}`));
+    console.log(chalk.gray(`    平台: ${platforms.map(platformLabel).join(' + ')}`));
+    console.log(chalk.gray(`    运行系统: ${runtimeLabel(runtime)}`));
     console.log(chalk.gray(`    团队: ${team ? '已启用' : '未启用'}`));
     console.log(chalk.gray(`    流水线: ${pipeline ? '已安装' : '未安装'}`));
     const browserTools = [playwrightCli && 'playwright-cli', openCli && 'opencli'].filter(Boolean);
@@ -1175,4 +1379,4 @@ export async function scaffold(config) {
     if (aiCli) console.log(chalk.gray(`    AI CLI: ${aiCli}`));
     console.log('');
   }
-}
+}