dream-wf 0.1.1 → 0.1.2

package/src/deps/index.js

@@ -2,6 +2,8 @@ import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { pathExists, readTextIfExists } from '../lib/files.js';
 import { commandExists } from '../lib/trellis.js';
+import { readMcpServers, mcpConfigExists } from '../lib/mcp.js';
+import { MCP_CATALOG } from '../lib/catalog.js';
 
 export async function checkDependencies(rootDir, platform) {
   const checks = [];
@@ -18,18 +20,31 @@ export async function checkDependencies(rootDir, platform) {
     checks.push(await fileCheck(path.join(rootDir, '.cursor', 'rules', 'dream-wf.mdc'), 'Cursor dream-wf always-on rule'));
     checks.push(await fileCheck(path.join(rootDir, '.cursor', 'skills', 'dream-wf-grill-prd', 'SKILL.md'), 'Cursor dream-wf grill PRD skill'));
     checks.push(await fileCheck(path.join(rootDir, '.cursor', 'skills', 'dream-wf-mcp-policy', 'SKILL.md'), 'Cursor dream-wf MCP policy skill'));
+    checks.push(await mcpConfigCheck(rootDir, 'cursor'));
   }
 
   if (platform === 'claude') {
     checks.push(await contentCheck(path.join(rootDir, 'CLAUDE.md'), '<!-- DREAM-WF:START -->', 'Claude Code dream-wf entry block'));
     checks.push(await fileCheck(path.join(rootDir, '.claude', 'skills', 'dream-wf-grill-prd', 'SKILL.md'), 'Claude Code dream-wf grill PRD skill'));
     checks.push(await fileCheck(path.join(rootDir, '.claude', 'skills', 'dream-wf-mcp-policy', 'SKILL.md'), 'Claude Code dream-wf MCP policy skill'));
+    checks.push(await mcpConfigCheck(rootDir, 'claude'));
   }
 
   if (platform === 'opencode') {
     checks.push(await contentCheck(path.join(rootDir, 'AGENTS.md'), '<!-- DREAM-WF:START -->', 'OpenCode dream-wf entry block'));
     checks.push(await fileCheck(path.join(rootDir, '.opencode', 'skills', 'dream-wf-grill-prd', 'SKILL.md'), 'OpenCode dream-wf grill PRD skill'));
     checks.push(await fileCheck(path.join(rootDir, '.opencode', 'skills', 'dream-wf-mcp-policy', 'SKILL.md'), 'OpenCode dream-wf MCP policy skill'));
+    checks.push(await mcpConfigCheck(rootDir, 'opencode'));
+  }
+
+  if (platform === 'codex') {
+    checks.push(await contentCheck(path.join(rootDir, 'AGENTS.md'), '<!-- DREAM-WF:START -->', 'Codex dream-wf entry block'));
+    checks.push(await fileCheck(path.join(rootDir, '.codex', 'skills', 'dream-wf-grill-prd', 'SKILL.md'), 'Codex dream-wf grill PRD skill'));
+    checks.push(await fileCheck(path.join(rootDir, '.codex', 'skills', 'dream-wf-mcp-policy', 'SKILL.md'), 'Codex dream-wf MCP policy skill'));
+    checks.push(await fileCheck(path.join(rootDir, '.codex', 'hooks', 'dream-wf-guard.py'), 'Codex dream-wf guard hook'));
+    checks.push(await contentCheck(path.join(rootDir, '.codex', 'hooks.json'), 'dream-wf-guard.py', 'Codex hooks.json registration'));
+    checks.push(await contentCheck(path.join(rootDir, '.codex', 'config.toml'), 'hooks = true', 'Codex hooks feature enabled'));
+    checks.push(await mcpConfigCheck(rootDir, 'codex'));
   }
 
   checks.push(await secretScan(rootDir));
@@ -37,6 +52,41 @@ export async function checkDependencies(rootDir, platform) {
   return checks;
 }
 
+// 检查 MCP 配置文件存在性以及是否包含 catalog 里的默认 MCP 条目。
+async function mcpConfigCheck(rootDir, platform) {
+  const configPaths = {
+    cursor: '.cursor/mcp.json',
+    claude: '.mcp.json',
+    opencode: 'opencode.json',
+    codex: '.codex/config.toml'
+  };
+
+  const exists = await mcpConfigExists(rootDir, platform);
+  if (!exists) {
+    return {
+      name: `MCP config (${configPaths[platform]})`,
+      ok: false,
+      hint: `Missing ${configPaths[platform]}. Run dream-wf init or TUI to configure MCP servers.`
+    };
+  }
+
+  const servers = await readMcpServers(rootDir, platform);
+  const missing = MCP_CATALOG.filter((entry) => !servers[entry.name]).map((entry) => entry.name);
+  if (missing.length > 0) {
+    return {
+      name: `MCP config (${configPaths[platform]})`,
+      ok: false,
+      hint: `Missing MCP servers: ${missing.join(', ')}.`
+    };
+  }
+
+  return {
+    name: `MCP config (${configPaths[platform]})`,
+    ok: true,
+    hint: `MCP config OK (${MCP_CATALOG.map((entry) => entry.name).join(', ')}).`
+  };
+}
+
 function binaryCheck(command, hint) {
   return {
     name: command,

package/src/lib/catalog.js

@@ -0,0 +1,82 @@
+// 安装聚合器的可选 skill 和 mcp 条目。
+// 每个 skill 对应一个模板目录 templates/skills/<name>/，由 shared.installSkill 装入各平台 skills 目录。
+// 每个 mcp 对应一个独立 server 配置，由 mcp.installMcpServer 写入各平台 mcp 配置文件。
+
+export const SKILL_CATALOG = [
+  {
+    id: 'trellis-dream-wf-patch',
+    name: 'dream-wf-grill-prd',
+    label: 'dream-wf-grill-prd (Trellis patch · grill-me style PRD)',
+    description: 'grill-me 风格的 PRD 澄清 skill，dream-wf 的核心 patch。',
+    templateDir: 'dream-wf-grill-prd',
+    default: true
+  },
+  {
+    id: 'dream-wf-mcp-policy',
+    name: 'dream-wf-mcp-policy',
+    label: 'dream-wf-mcp-policy (MCP 优先级策略 skill)',
+    description: '强制 fast-context-mcp / grok-search-mcp 优先级的策略 skill。',
+    templateDir: 'dream-wf-mcp-policy',
+    default: true
+  }
+];
+
+export const MCP_CATALOG = [
+  {
+    id: 'fast-context',
+    name: 'fast-context',
+    label: 'fast-context-mcp (代码语义检索)',
+    description: '代码库语义理解优先 MCP，来源 SammySnake-d/fast-context-mcp。',
+    server: {
+      command: 'npx',
+      args: ['-y', '--prefer-online', 'fast-context-mcp@latest'],
+      env: {
+        WINDSURF_API_KEY: 'devin-session-xx'
+      }
+    },
+    default: true,
+    requires: {
+      binaries: ['npx']
+    }
+  },
+  {
+    id: 'grok-search',
+    name: 'grok-search',
+    label: 'grok-search-mcp (外部文档/实时网络检索)',
+    description: '外部文档和实时网络检索优先 MCP，来源 GuDaStudio/GrokSearch。',
+    server: {
+      type: 'stdio',
+      command: 'uvx',
+      args: ['--from', 'git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily', 'grok-search'],
+      env: {
+        GROK_API_URL: 'https://your-api-endpoint.com/v1',
+        GROK_API_KEY: 'your-grok-api-key',
+        GROK_MODEL: 'your-model-name',
+        TAVILY_API_KEY: 'optional-tavily-key',
+        TAVILY_API_URL: 'https://api.tavily.com'
+      }
+    },
+    default: true,
+    requires: {
+      binaries: ['uvx']
+    }
+  }
+];
+
+export function defaultSkillIds() {
+  return SKILL_CATALOG.filter((item) => item.default).map((item) => item.id);
+}
+
+export function defaultMcpIds() {
+  return MCP_CATALOG.filter((item) => item.default).map((item) => item.id);
+}
+
+export function resolveSkills(ids) {
+  const set = new Set(ids);
+  return SKILL_CATALOG.filter((item) => set.has(item.id));
+}
+
+export function resolveMcps(ids) {
+  const set = new Set(ids);
+  return MCP_CATALOG.filter((item) => set.has(item.id));
+}

package/src/lib/mcp.js

@@ -0,0 +1,305 @@
+import path from 'node:path';
+import { pathExists, readTextIfExists, writeTextFile } from './files.js';
+import { readJsonObject, writeJsonObject } from './json.js';
+
+// 把一个 mcp catalog 条目规范化成可写入的 server 描述对象。
+// 去掉 catalog 里的 type 字段时保留 type（如果原始 server 已带），并保证字段顺序稳定。
+function normalizeServer(entry) {
+  const server = entry.server;
+  const out = {};
+  if (server.type) {
+    out.type = server.type;
+  }
+  out.command = server.command;
+  if (Array.isArray(server.args)) {
+    out.args = server.args;
+  }
+  if (server.env && Object.keys(server.env).length > 0) {
+    out.env = server.env;
+  }
+  return out;
+}
+
+// Cursor: .cursor/mcp.json -> { mcpServers: { name: {...} } }
+async function installCursorMcp(rootDir, mcpEntries) {
+  const configPath = path.join(rootDir, '.cursor', 'mcp.json');
+  const config = await readJsonObject(configPath, { mcpServers: {} });
+  config.mcpServers = config.mcpServers ?? {};
+
+  let changed = false;
+  for (const entry of mcpEntries) {
+    const server = normalizeServer(entry);
+    if (!deepEqual(config.mcpServers[entry.name], server)) {
+      config.mcpServers[entry.name] = server;
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    await writeJsonObject(configPath, config);
+  }
+  return { changed, action: changed ? 'updated' : 'unchanged', path: configPath };
+}
+
+// Claude Code: .mcp.json -> { mcpServers: { name: {...} } }
+async function installClaudeMcp(rootDir, mcpEntries) {
+  const configPath = path.join(rootDir, '.mcp.json');
+  const config = await readJsonObject(configPath, { mcpServers: {} });
+  config.mcpServers = config.mcpServers ?? {};
+
+  let changed = false;
+  for (const entry of mcpEntries) {
+    const server = normalizeServer(entry);
+    if (!deepEqual(config.mcpServers[entry.name], server)) {
+      config.mcpServers[entry.name] = server;
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    await writeJsonObject(configPath, config);
+  }
+  return { changed, action: changed ? 'updated' : 'unchanged', path: configPath };
+}
+
+// OpenCode: opencode.json -> { mcp: { servers: { name: {...} } } }
+async function installOpenCodeMcp(rootDir, mcpEntries) {
+  const configPath = path.join(rootDir, 'opencode.json');
+  const config = await readJsonObject(configPath, { mcp: { servers: {} } });
+  config.mcp = config.mcp ?? {};
+  config.mcp.servers = config.mcp.servers ?? {};
+
+  let changed = false;
+  for (const entry of mcpEntries) {
+    const server = normalizeServer(entry);
+    if (!deepEqual(config.mcp.servers[entry.name], server)) {
+      config.mcp.servers[entry.name] = server;
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    await writeJsonObject(configPath, config);
+  }
+  return { changed, action: changed ? 'updated' : 'unchanged', path: configPath };
+}
+
+// Codex: ~/.codex/config.toml 的 [mcp_servers.<name>] 段。
+// 项目级 Codex 配置也支持放到 .codex/config.toml（Codex CLI 0.8+ 读取项目目录）。
+async function installCodexMcp(rootDir, mcpEntries) {
+  const configPath = path.join(rootDir, '.codex', 'config.toml');
+  const existing = await readTextIfExists(configPath);
+  const lines = existing ? existing.split('\n') : [];
+
+  let working = [...lines];
+
+  for (const entry of mcpEntries) {
+    const block = renderCodexServerBlock(entry);
+    const marker = `[mcp_servers.${entry.name}]`;
+    const next = replaceOrAppendTomlBlock(working, marker, block);
+    working = next.lines;
+  }
+
+  // 规范化：去掉末尾空行后再统一加一个尾换行。
+  while (working.length > 0 && working[working.length - 1] === '') {
+    working.pop();
+  }
+  const normalized = [...working, ''].join('\n');
+  const original = existing ? `${existing.replace(/\s+$/, '')}\n` : '';
+
+  const changed = normalized !== original;
+  if (changed) {
+    await writeTextFile(configPath, normalized);
+  }
+  return { changed, action: changed ? (existing ? 'updated' : 'created') : 'unchanged', path: configPath };
+}
+
+function renderCodexServerBlock(entry) {
+  const server = entry.server;
+  const out = [`[mcp_servers.${entry.name}]`];
+  out.push(`command = ${tomlString(server.command)}`);
+  if (Array.isArray(server.args) && server.args.length > 0) {
+    out.push(`args = [${server.args.map(tomlString).join(', ')}]`);
+  }
+  if (server.env && Object.keys(server.env).length > 0) {
+    out.push(`[mcp_servers.${entry.name}.env]`);
+    for (const [key, value] of Object.entries(server.env)) {
+      out.push(`${key} = ${tomlString(value)}`);
+    }
+  }
+  return out.join('\n');
+}
+
+function replaceOrAppendTomlBlock(lines, marker, blockText) {
+  const start = lines.findIndex((line) => line.trim() === marker.trim());
+  if (start === -1) {
+    const newLines = [...lines];
+    if (newLines.length > 0 && newLines[newLines.length - 1] !== '') {
+      newLines.push('');
+    }
+    newLines.push(blockText, '');
+    return { changed: true, lines: newLines };
+  }
+
+  // 找到该块的结束位置：下一个顶层 [ 开头的行或文件末尾。
+  let end = start + 1;
+  while (end < lines.length) {
+    const trimmed = lines[end].trim();
+    if (trimmed.startsWith('[') && !trimmed.startsWith('[mcp_servers.') || trimmed === marker) {
+      break;
+    }
+    if (trimmed.startsWith('[') && !trimmed.startsWith(`[mcp_servers.${extractTableName(marker)}.`)) {
+      break;
+    }
+    end += 1;
+  }
+
+  const blockLines = blockText.split('\n');
+  const before = lines.slice(0, start);
+  const after = lines.slice(end);
+  const next = [...before, ...blockLines, '', ...after];
+  return { changed: true, lines: next };
+}
+
+function extractTableName(marker) {
+  const match = marker.match(/^\[mcp_servers\.([^\].]+)\]$/);
+  return match ? match[1] : '';
+}
+
+function tomlString(value) {
+  if (typeof value !== 'string') {
+    return String(value);
+  }
+  const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return `"${escaped}"`;
+}
+
+function deepEqual(a, b) {
+  return JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b));
+}
+
+function sortKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  if (value && typeof value === 'object') {
+    return Object.keys(value).sort().reduce((acc, key) => {
+      acc[key] = sortKeys(value[key]);
+      return acc;
+    }, {});
+  }
+  return value;
+}
+
+const INSTALLERS = {
+  cursor: installCursorMcp,
+  claude: installClaudeMcp,
+  opencode: installOpenCodeMcp,
+  codex: installCodexMcp
+};
+
+export async function installMcpServers(rootDir, platform, mcpEntries) {
+  const installer = INSTALLERS[platform];
+  if (!installer) {
+    throw new Error(`MCP install is not supported for platform "${platform}".`);
+  }
+  return installer(rootDir, mcpEntries);
+}
+
+// 读取已存在的 mcp 配置，用于 doctor 检查。
+export async function readMcpServers(rootDir, platform) {
+  switch (platform) {
+    case 'cursor': {
+      const config = await readJsonObject(path.join(rootDir, '.cursor', 'mcp.json'), { mcpServers: {} });
+      return config.mcpServers ?? {};
+    }
+    case 'claude': {
+      const config = await readJsonObject(path.join(rootDir, '.mcp.json'), { mcpServers: {} });
+      return config.mcpServers ?? {};
+    }
+    case 'opencode': {
+      const config = await readJsonObject(path.join(rootDir, 'opencode.json'), { mcp: { servers: {} } });
+      return config.mcp?.servers ?? {};
+    }
+    case 'codex': {
+      const text = await readTextIfExists(path.join(rootDir, '.codex', 'config.toml'));
+      return parseCodexMcpServers(text ?? '');
+    }
+    default:
+      return {};
+  }
+}
+
+function parseCodexMcpServers(text) {
+  const servers = {};
+  const lines = text.split('\n');
+  let currentName = null;
+  let inEnv = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const head = trimmed.match(/^\[mcp_servers\.([^\].]+)\]$/);
+    if (head) {
+      currentName = head[1];
+      servers[currentName] = {};
+      inEnv = false;
+      continue;
+    }
+    if (currentName && trimmed.startsWith(`[mcp_servers.${currentName}.env]`)) {
+      servers[currentName].env = {};
+      inEnv = true;
+      continue;
+    }
+    if (currentName && trimmed.startsWith('[')) {
+      currentName = null;
+      inEnv = false;
+      continue;
+    }
+    if (!currentName) {
+      continue;
+    }
+    const match = trimmed.match(/^([A-Za-z0-9_]+)\s*=\s*(.*)$/);
+    if (!match) {
+      continue;
+    }
+    const [, key, rawValue] = match;
+    const value = parseTomlValue(rawValue);
+    if (inEnv) {
+      servers[currentName].env[key] = value;
+    } else if (key === 'args' && Array.isArray(value)) {
+      servers[currentName].args = value;
+    } else {
+      servers[currentName][key] = value;
+    }
+  }
+  return servers;
+}
+
+function parseTomlValue(raw) {
+  const value = raw.trim();
+  if (value.startsWith('[') && value.endsWith(']')) {
+    const inner = value.slice(1, -1).trim();
+    if (!inner) {
+      return [];
+    }
+    return inner.split(',').map((item) => parseTomlValue(item.trim())).filter((item) => item !== undefined);
+  }
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  }
+  return value;
+}
+
+export async function mcpConfigExists(rootDir, platform) {
+  switch (platform) {
+    case 'cursor':
+      return pathExists(path.join(rootDir, '.cursor', 'mcp.json'));
+    case 'claude':
+      return pathExists(path.join(rootDir, '.mcp.json'));
+    case 'opencode':
+      return pathExists(path.join(rootDir, 'opencode.json'));
+    case 'codex':
+      return pathExists(path.join(rootDir, '.codex', 'config.toml'));
+    default:
+      return false;
+  }
+}

package/src/lib/platforms.js

@@ -1,4 +1,11 @@
-export const SUPPORTED_PLATFORMS = new Set(['cursor', 'claude', 'opencode']);
+export const SUPPORTED_PLATFORMS = new Set(['cursor', 'claude', 'opencode', 'codex']);
+
+export const PLATFORM_LABELS = {
+  cursor: 'Cursor',
+  claude: 'Claude Code',
+  opencode: 'OpenCode',
+  codex: 'Codex'
+};
 
 export function normalizePlatform(value) {
   if (!value) {
@@ -10,11 +17,11 @@ export function normalizePlatform(value) {
 
 export function assertSupportedPlatform(platform) {
   if (!platform) {
-    throw new Error('Missing required -p <cursor|claude|opencode>.');
+    throw new Error('Missing required -p <cursor|claude|opencode|codex>.');
   }
 
   if (!SUPPORTED_PLATFORMS.has(platform)) {
-    throw new Error(`Unsupported platform "${platform}". Use one of: cursor, claude, opencode.`);
+    throw new Error(`Unsupported platform "${platform}". Use one of: cursor, claude, opencode, codex.`);
   }
 }
 
@@ -28,5 +35,8 @@ export function trellisPlatformFlag(platform) {
   if (platform === 'opencode') {
     return '--opencode';
   }
+  if (platform === 'codex') {
+    return '--codex';
+  }
   assertSupportedPlatform(platform);
 }

package/src/lib/trellis.js

@@ -1,10 +1,15 @@
 import path from 'node:path';
+import process from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { appendBlockOnce, pathExists, readTextIfExists, writeTextFile } from './files.js';
 import { trellisPlatformFlag } from './platforms.js';
 
 const DREAM_WF_MARKER = '<!-- dream-wf:profile:v1 -->';
 
+function writeOutput(message) {
+  process.stdout.write(`${message}\n`);
+}
+
 export async function detectTrellis(rootDir) {
   const trellisDir = path.join(rootDir, '.trellis');
   const workflowPath = path.join(trellisDir, 'workflow.md');
@@ -37,11 +42,25 @@ export async function ensureTrellisInitialized(rootDir, options) {
     throw new Error('Pass --developer <name> when using --install-deps so dream-wf can run trellis init non-interactively.');
   }
 
+  // trellis CLI 未安装时，先 npm install -g。
   if (!state.cli) {
-    throw new Error('trellis is not installed. Install it with: npm install -g @mindfoldhq/trellis@latest');
+    writeOutput('Installing @mindfoldhq/trellis globally...');
+    const installResult = spawnSync('npm', ['install', '-g', '@mindfoldhq/trellis@latest'], {
+      stdio: 'inherit'
+    });
+
+    if (installResult.status !== 0) {
+      throw new Error(`Failed to install trellis with npm, exit code ${installResult.status ?? 'unknown'}.`);
+    }
+
+    // 重新检测。
+    state.cli = commandExists('trellis');
+    if (!state.cli) {
+      throw new Error('trellis CLI still not found after npm install. Check your PATH.');
+    }
   }
 
-  const result = spawnSync('trellis', ['init', '-u', options.developer, platformFlag], {
+  const result = spawnSync('trellis', ['init', '-u', options.developer, platformFlag, '--yes'], {
     cwd: rootDir,
     stdio: 'inherit'
   });
@@ -99,6 +118,7 @@ function dreamWorkflowBlock() {
     '- Use grill-me behavior for requirement discovery: ask one question at a time, provide 2-3 options and a recommended answer, and inspect code/docs/config before asking the user.',
     '- Update `prd.md` only after a user answer, confirmed existing fact, or explicit decision is available.',
     '- Treat PRD confirmation as separate from task creation consent.',
+    '- **Before requesting PRD confirmation, perform a Knowledge Verification pass.** Use `grok-search-mcp` (`web_search`, `web_fetch`) to verify technical assumptions that could be outdated or wrong (API names, hook events, config formats, version-specific behavior, release status). Record results in the `## Knowledge Verification` section of `prd.md`. Correct any outdated assumptions. Move unverified points to `Open Questions`. Add `knowledge verified` to the PRD after verification is complete.',
     '- Generate initial spec candidates from user answers, PRD decisions, and verified project/code facts; require user review before treating them as stable conventions.',
     '- Do not guess or fabricate unknown facts, APIs, package behavior, release status, or external documentation; search with preferred MCP tools or ask the user until accurate information is available.',
     '- Write README and project documentation in Chinese. Write code comments in Chinese when comments are necessary, and avoid obvious comments.',

package/src/platforms/claude-code/index.js

@@ -2,16 +2,20 @@ import path from 'node:path';
 import { readFile, chmod } from 'node:fs/promises';
 import { readJsonObject, writeJsonObject, pushUniqueByCommand } from '../../lib/json.js';
 import { writeIfChanged } from '../../lib/files.js';
-import { installCommonDreamWfFiles, installManagedBlock, installSkill } from '../shared.js';
+import { installCommonDreamWfFiles, installManagedBlock, installSelectedSkills } from '../shared.js';
+import { installMcpServers } from '../../lib/mcp.js';
 
 export async function installClaudeCode(packageRoot, targetRoot, options) {
   const results = [];
 
   results.push(await installManagedBlock(packageRoot, targetRoot, 'templates/rules/claude-code/dream-wf-block.md', 'CLAUDE.md', '<!-- DREAM-WF:START -->', '<!-- DREAM-WF:END -->'));
-  results.push(await installSkill(packageRoot, targetRoot, '.claude', 'dream-wf-grill-prd'));
-  results.push(await installSkill(packageRoot, targetRoot, '.claude', 'dream-wf-mcp-policy'));
+  results.push(...await installSelectedSkills(packageRoot, targetRoot, '.claude', options.skills));
   results.push(...await installCommonDreamWfFiles(packageRoot, targetRoot));
 
+  if (options.mcps && options.mcps.length > 0) {
+    results.push(await installMcpServers(targetRoot, 'claude', options.mcps));
+  }
+
   if (options.mode === 'strict') {
     results.push(await installClaudeHook(packageRoot, targetRoot));
     results.push(await mergeClaudeSettings(targetRoot));

package/src/platforms/codex/index.js

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import { readFile, chmod } from 'node:fs/promises';
+import { readJsonObject, writeJsonObject, pushUniqueByCommand } from '../../lib/json.js';
+import { writeIfChanged, readTextIfExists, writeTextFile } from '../../lib/files.js';
+import { installCommonDreamWfFiles, installManagedBlock, installSelectedSkills } from '../shared.js';
+import { installMcpServers } from '../../lib/mcp.js';
+
+// Codex CLI 读取项目根的 AGENTS.md 作为入口规则。
+// Codex 支持 PreToolUse 阻塞式 hook，配置在 .codex/hooks.json（和 config.toml [hooks] 段等效）。
+// 需要在 config.toml 里加 [features] hooks = true 来启用 hooks 功能。
+// hook 脚本放在 .codex/hooks/dream-wf-guard.py。
+export async function installCodex(packageRoot, targetRoot, options) {
+  const results = [];
+
+  results.push(await installManagedBlock(packageRoot, targetRoot, 'templates/rules/codex/dream-wf-block.md', 'AGENTS.md', '<!-- DREAM-WF:START -->', '<!-- DREAM-WF:END -->'));
+  results.push(...await installSelectedSkills(packageRoot, targetRoot, '.codex', options.skills));
+  results.push(...await installCommonDreamWfFiles(packageRoot, targetRoot));
+
+  if (options.mcps && options.mcps.length > 0) {
+    results.push(await installMcpServers(targetRoot, 'codex', options.mcps));
+  }
+
+  if (options.mode === 'strict') {
+    results.push(await installCodexHook(packageRoot, targetRoot));
+    results.push(await ensureCodexHooksFeature(targetRoot));
+    results.push(await mergeCodexHooks(targetRoot));
+  }
+
+  return results;
+}
+
+async function installCodexHook(packageRoot, targetRoot) {
+  const sourcePath = path.join(packageRoot, 'templates', 'hooks', 'codex', 'dream-wf-guard.py');
+  const targetPath = path.join(targetRoot, '.codex', 'hooks', 'dream-wf-guard.py');
+  const contents = await readFile(sourcePath, 'utf8');
+  const result = await writeIfChanged(targetPath, contents);
+  await chmod(targetPath, 0o755);
+  return result;
+}
+
+// 在 config.toml 里确保 [features] hooks = true 存在。
+// 用简单的文本检查实现幂等：如果已有则不动。
+async function ensureCodexHooksFeature(rootDir) {
+  const configPath = path.join(rootDir, '.codex', 'config.toml');
+  const existing = await readTextIfExists(configPath);
+  const hasFeature = existing?.includes('hooks = true') || existing?.includes('hooks=true');
+
+  if (hasFeature) {
+    return { changed: false, action: 'unchanged', path: configPath };
+  }
+
+  const featureBlock = '[features]\nhooks = true\n';
+  const prefix = existing && !existing.endsWith('\n') ? `${existing}\n\n` : existing ? `${existing}\n` : '';
+  await writeTextFile(configPath, `${prefix}${featureBlock}`);
+  return { changed: true, action: existing ? 'updated' : 'created', path: configPath };
+}
+
+// Codex hooks.json 格式和 Claude Code 的 settings.json hooks 段一致：
+// { "hooks": { "PreToolUse": [ { "matcher": "...", "hooks": [ { "type": "command", "command": "...", "timeout": 10 } ] } ] } }
+// Codex 的 matcher 是正则匹配 tool_name，用 Bash|Shell|apply_patch|Edit|Write 匹配变更类工具。
+async function mergeCodexHooks(rootDir) {
+  const hooksPath = path.join(rootDir, '.codex', 'hooks.json');
+  const hooks = await readJsonObject(hooksPath, { hooks: {} });
+  hooks.hooks = hooks.hooks ?? {};
+  hooks.hooks.PreToolUse = hooks.hooks.PreToolUse ?? [];
+
+  const changed = pushUniqueByCommand(hooks.hooks.PreToolUse, {
+    matcher: 'Bash|Shell|shell|apply_patch|Edit|Write',
+    hooks: [
+      {
+        type: 'command',
+        command: 'python3 "$CODEX_PROJECT_DIR/.codex/hooks/dream-wf-guard.py"',
+        timeout: 10
+      }
+    ]
+  });
+
+  if (changed) {
+    await writeJsonObject(hooksPath, hooks);
+  }
+
+  return { changed, action: changed ? 'updated' : 'unchanged', path: hooksPath };
+}