ai-engineering-init 1.13.0 → 1.14.1

package/bin/index.js

@@ -1327,6 +1327,14 @@ const MCP_REGISTRY = [
     env: { YUQUE_TOKEN: '<YOUR_TOKEN>' },
     recommended: false,
   },
+  {
+    name: 'codex',
+    command: 'uvx',
+    args: ['--from', 'git+https://github.com/GuDaStudio/codexmcp.git', 'codexmcp'],
+    description: 'Codex 协作 — 代码审查、算法分析、生成补丁（需安装 uv）',
+    env: {},
+    recommended: false,
+  },
 ];
 
 /** MCP 配置文件路径映射 */
@@ -1335,43 +1343,73 @@ const MCP_CONFIG_PATHS = {
   cursor: { file: '.cursor/mcp.json',      key: 'mcpServers' },
 };
 
-/** 检测项目中已有的工具配置目录 */
-function detectMcpTools() {
+/** 解析 MCP 配置文件绝对路径 */
+function resolveMcpConfigPath(toolName, scope = 'project') {
+  const config = MCP_CONFIG_PATHS[toolName];
+  if (!config) return '';
+  const baseDir = scope === 'global' ? HOME_DIR : targetDir;
+  return path.join(baseDir, config.file);
+}
+
+/** 检测指定作用域中已有的工具配置目录 */
+function detectMcpTools(scope = 'project') {
+  const baseDir = scope === 'global' ? HOME_DIR : targetDir;
   const tools = [];
-  if (isRealDir(path.join(targetDir, '.claude'))) tools.push('claude');
-  if (isRealDir(path.join(targetDir, '.cursor'))) tools.push('cursor');
+  if (isRealDir(path.join(baseDir, '.claude'))) tools.push('claude');
+  if (isRealDir(path.join(baseDir, '.cursor'))) tools.push('cursor');
   return tools;
 }
 
 /** 读取指定工具的 MCP 已配置服务器 */
-function getMcpServers(toolName) {
+function getMcpServers(toolName, filePath) {
   const config = MCP_CONFIG_PATHS[toolName];
   if (!config) return {};
-  const filePath = path.join(targetDir, config.file);
+  const resolvedPath = filePath || resolveMcpConfigPath(toolName, 'project');
   try {
-    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const data = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
     return data[config.key] || {};
   } catch { return {}; }
 }
 
 /** 写入指定工具的 MCP 配置（保留文件其他字段） */
-function setMcpServers(toolName, mcpServers) {
+function setMcpServers(toolName, mcpServers, filePath) {
   const config = MCP_CONFIG_PATHS[toolName];
   if (!config) return;
-  const filePath = path.join(targetDir, config.file);
+  const resolvedPath = filePath || resolveMcpConfigPath(toolName, 'project');
   let data = {};
-  try { data = JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { /* 新建 */ }
+  try { data = JSON.parse(fs.readFileSync(resolvedPath, 'utf8')); } catch { /* 新建 */ }
   data[config.key] = mcpServers;
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+  fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+  fs.writeFileSync(resolvedPath, JSON.stringify(data, null, 2) + '\n');
+}
+
+/** 生成等效的手动安装 CLI 命令提示 */
+function buildCliHints(entry, scope) {
+  const scopeFlag = scope === 'global' ? '-s user ' : '';
+  const hints = [];
+
+  // Claude Code CLI
+  if (entry.command && entry.command !== 'npx') {
+    hints.push(`claude: claude mcp add ${entry.name} ${scopeFlag}--transport stdio -- ${entry.command} ${entry.args.join(' ')}`);
+  } else {
+    hints.push(`claude: claude mcp add ${entry.name} ${scopeFlag}-- npx -y ${entry.package}`);
+  }
+
+  // Cursor：无官方 CLI，提示手动编辑
+  const cursorFile = scope === 'global' ? '~/.cursor/mcp.json' : '.cursor/mcp.json';
+  hints.push(`cursor: 手动编辑 ${cursorFile}，在 mcpServers 中添加 "${entry.name}" 配置`);
+
+  return hints;
 }
 
 /** 构建单个 MCP 服务器的配置对象 */
 function buildMcpServerConfig(entry) {
-  const config = {
-    command: 'npx',
-    args: ['-y', entry.package],
-  };
+  const command = entry.command || 'npx';
+  const args = Array.isArray(entry.args) && entry.args.length > 0
+    ? [...entry.args]
+    : ['-y', entry.package];
+
+  const config = { command, args };
   if (Object.keys(entry.env).length > 0) {
     config.env = { ...entry.env };
   }
@@ -1379,10 +1417,11 @@ function buildMcpServerConfig(entry) {
 }
 
 /** 获取所有工具中已安装的 MCP 服务器名称集合 */
-function getInstalledMcpNames(tools) {
+function getInstalledMcpNames(tools, scope = 'project') {
   const names = new Set();
   for (const t of tools) {
-    const servers = getMcpServers(t);
+    const configPath = resolveMcpConfigPath(t, scope);
+    const servers = getMcpServers(t, configPath);
     for (const name of Object.keys(servers)) names.add(name);
   }
   return names;
@@ -1394,17 +1433,6 @@ function runMcp() {
     process.exit(1);
   }
 
-  const tools = detectMcpTools();
-  if (tools.length === 0) {
-    console.log(fmt('yellow', '⚠  当前目录未检测到 .claude/ 或 .cursor/ 配置目录。'));
-    console.log(`   请先运行: ${fmt('bold', hintCmd('init --tool claude'))}`);
-    console.log('');
-    process.exit(1);
-  }
-
-  console.log(`  检测到工具: ${fmt('bold', tools.join(', '))}`);
-  console.log('');
-
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const ask = (question) => new Promise((resolve) => {
     rl.question(question, (answer) => resolve(answer.trim()));
@@ -1412,6 +1440,42 @@ function runMcp() {
 
   (async () => {
     try {
+      // 第一步：选择作用域
+      console.log(fmt('cyan', '请选择 MCP 作用域：'));
+      console.log('');
+      console.log(`  ${fmt('bold', '1')}) ${fmt('green',  '项目级')}                       — 写入当前项目 .claude/.cursor`);
+      console.log(`  ${fmt('bold', '2')}) ${fmt('yellow', '全局（~/.claude / ~/.cursor）')} — 对当前用户所有项目生效`);
+      console.log('');
+      const scopeAnswer = await ask(fmt('bold', '请输入选项 [1-2]: '));
+      const scopeMap = { '1': 'project', '2': 'global' };
+      const scope = scopeMap[scopeAnswer];
+      if (!scope) {
+        console.error(fmt('red', '无效作用域选项，退出。'));
+        process.exit(1);
+      }
+      console.log('');
+
+      const tools = detectMcpTools(scope);
+      if (tools.length === 0) {
+        if (scope === 'global') {
+          console.log(fmt('yellow', '⚠  全局目录未检测到 ~/.claude/ 或 ~/.cursor/ 配置目录。'));
+          console.log(`   请先运行: ${fmt('bold', 'npx ai-engineering-init global --tool claude')}`);
+        } else {
+          console.log(fmt('yellow', '⚠  当前目录未检测到 .claude/ 或 .cursor/ 配置目录。'));
+          console.log(`   请先运行: ${fmt('bold', hintCmd('init --tool claude'))}`);
+        }
+        console.log('');
+        process.exit(1);
+      }
+
+      const scopeLabel = scope === 'global'
+        ? `全局（${HOME_DIR}/.claude / ${HOME_DIR}/.cursor）`
+        : `项目级（${targetDir}）`;
+      console.log(`  作用域: ${fmt('bold', scopeLabel)}`);
+      console.log(`  检测到工具: ${fmt('bold', tools.join(', '))}`);
+      console.log('');
+
+      // 第二步：选择操作
       console.log(fmt('cyan', '请选择 MCP 操作：'));
       console.log('');
       console.log(`  ${fmt('bold', '1')}) ${fmt('green',  '安装 MCP 服务器')}    — 从预置列表选择并安装到配置`);
@@ -1423,10 +1487,10 @@ function runMcp() {
       console.log('');
 
       switch (action) {
-        case '1': await mcpInstall(tools, ask); break;
-        case '2': await mcpUninstall(tools, ask); break;
-        case '3': mcpStatus(tools); break;
-        case '4': await mcpRecommend(tools, ask); break;
+        case '1': await mcpInstall(tools, ask, scope); break;
+        case '2': await mcpUninstall(tools, ask, scope); break;
+        case '3': mcpStatus(tools, scope); break;
+        case '4': await mcpRecommend(tools, ask, scope); break;
         default:
           console.error(fmt('red', '无效选项，退出。'));
           process.exit(1);
@@ -1438,8 +1502,8 @@ function runMcp() {
 }
 
 /** 安装 MCP 服务器 */
-async function mcpInstall(tools, ask) {
-  const installed = getInstalledMcpNames(tools);
+async function mcpInstall(tools, ask, scope = 'project') {
+  const installed = getInstalledMcpNames(tools, scope);
 
   console.log(fmt('cyan', '可用的 MCP 服务器：'));
   console.log('');
@@ -1478,25 +1542,38 @@ async function mcpInstall(tools, ask) {
 
   // 写入所有检测到的工具配置
   for (const toolName of tools) {
-    const servers = getMcpServers(toolName);
+    const configPath = resolveMcpConfigPath(toolName, scope);
+    const servers = getMcpServers(toolName, configPath);
     for (const entry of selected) {
       servers[entry.name] = buildMcpServerConfig(entry);
     }
-    setMcpServers(toolName, servers);
+    setMcpServers(toolName, servers, configPath);
     console.log(`  ${fmt('green', '✓')}  ${toolName}: 已写入 ${selected.map(e => e.name).join(', ')}`);
   }
 
   console.log('');
   console.log(fmt('green', fmt('bold', `✅ 已安装 ${selected.length} 个 MCP 服务器！`)));
   console.log('');
+
+  // 输出等效手动安装命令供参考
+  console.log(fmt('cyan', '💡 等效手动安装命令（仅供参考）：'));
+  console.log('');
+  for (const entry of selected) {
+    console.log(`  ${fmt('bold', entry.name)}:`);
+    for (const hint of buildCliHints(entry, scope)) {
+      console.log(`    ${fmt('yellow', hint)}`);
+    }
+    console.log('');
+  }
 }
 
 /** 卸载 MCP 服务器 */
-async function mcpUninstall(tools, ask) {
+async function mcpUninstall(tools, ask, scope = 'project') {
   // 收集所有已安装的服务器（合并去重）
   const allServers = new Map(); // name → 出现在哪些工具中
   for (const toolName of tools) {
-    const servers = getMcpServers(toolName);
+    const configPath = resolveMcpConfigPath(toolName, scope);
+    const servers = getMcpServers(toolName, configPath);
     for (const name of Object.keys(servers)) {
       if (!allServers.has(name)) allServers.set(name, []);
       allServers.get(name).push(toolName);
@@ -1531,7 +1608,8 @@ async function mcpUninstall(tools, ask) {
   console.log('');
 
   for (const toolName of tools) {
-    const servers = getMcpServers(toolName);
+    const configPath = resolveMcpConfigPath(toolName, scope);
+    const servers = getMcpServers(toolName, configPath);
     let removed = 0;
     for (const name of toRemove) {
       if (name in servers) {
@@ -1540,7 +1618,7 @@ async function mcpUninstall(tools, ask) {
       }
     }
     if (removed > 0) {
-      setMcpServers(toolName, servers);
+      setMcpServers(toolName, servers, configPath);
       console.log(`  ${fmt('green', '✓')}  ${toolName}: 已移除 ${toRemove.filter(n => !servers[n]).join(', ')}`);
     }
   }
@@ -1551,14 +1629,15 @@ async function mcpUninstall(tools, ask) {
 }
 
 /** 查看 MCP 状态 */
-function mcpStatus(tools) {
+function mcpStatus(tools, scope = 'project') {
   let hasAny = false;
 
   for (const toolName of tools) {
-    const servers = getMcpServers(toolName);
+    const configPath = resolveMcpConfigPath(toolName, scope);
+    const servers = getMcpServers(toolName, configPath);
     const names = Object.keys(servers);
 
-    console.log(fmt('cyan', `[${toolName}]`) + ` ${MCP_CONFIG_PATHS[toolName].file}`);
+    console.log(fmt('cyan', `[${toolName}]`) + ` ${configPath}`);
 
     if (names.length === 0) {
       console.log(`  ${fmt('yellow', '（无已安装的 MCP 服务器）')}`);
@@ -1566,10 +1645,12 @@ function mcpStatus(tools) {
       hasAny = true;
       for (const name of names) {
         const srv = servers[name];
-        const pkg = (srv.args || []).find(a => a.startsWith('@')) || '—';
+        const args = srv.args || [];
+        const pkg = args.find(a => a.startsWith('@'))
+          || (srv.command !== 'npx' ? `${srv.command} ${args.join(' ')}` : '—');
         const envKeys = srv.env ? Object.keys(srv.env).join(', ') : '—';
         console.log(`  ${fmt('green', '●')} ${fmt('bold', name)}`);
-        console.log(`    包: ${pkg}  |  环境变量: ${envKeys}`);
+        console.log(`    命令: ${pkg}  |  环境变量: ${envKeys}`);
       }
     }
     console.log('');
@@ -1583,14 +1664,14 @@ function mcpStatus(tools) {
 }
 
 /** 一键推荐安装 */
-async function mcpRecommend(tools, ask) {
-  const installed = getInstalledMcpNames(tools);
+async function mcpRecommend(tools, ask, scope = 'project') {
+  const installed = getInstalledMcpNames(tools, scope);
   const toInstall = MCP_REGISTRY.filter(e => e.recommended && !installed.has(e.name));
 
   if (toInstall.length === 0) {
     console.log(fmt('green', '  ✓ 所有推荐的 MCP 服务器已安装！'));
     console.log('');
-    mcpStatus(tools);
+    mcpStatus(tools, scope);
     return;
   }
 
@@ -1615,17 +1696,29 @@ async function mcpRecommend(tools, ask) {
 
   // 写入配置
   for (const toolName of tools) {
-    const servers = getMcpServers(toolName);
+    const configPath = resolveMcpConfigPath(toolName, scope);
+    const servers = getMcpServers(toolName, configPath);
     for (const entry of toInstall) {
       servers[entry.name] = buildMcpServerConfig(entry);
     }
-    setMcpServers(toolName, servers);
+    setMcpServers(toolName, servers, configPath);
     console.log(`  ${fmt('green', '✓')}  ${toolName}: 已写入 ${toInstall.map(e => e.name).join(', ')}`);
   }
 
   console.log('');
   console.log(fmt('green', fmt('bold', `✅ 已安装 ${toInstall.length} 个推荐 MCP 服务器！`)));
   console.log('');
+
+  // 输出等效手动安装命令供参考
+  console.log(fmt('cyan', '💡 等效手动安装命令（仅供参考）：'));
+  console.log('');
+  for (const entry of toInstall) {
+    console.log(`  ${fmt('bold', entry.name)}:`);
+    for (const hint of buildCliHints(entry, scope)) {
+      console.log(`    ${fmt('yellow', hint)}`);
+    }
+    console.log('');
+  }
 }
 
 // ── 工具选择菜单（init 用）─────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-init",
-  "version": "1.13.0",
+  "version": "1.14.1",
   "description": "AI 工程化配置初始化工具 — 一键为 Claude Code、OpenAI Codex 等 AI 工具初始化 Skills 和项目规范",
   "keywords": [
     "claude-code",

package/src/skills/collaborating-with-codex/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: collaborating-with-codex
 description: |
-  与 OpenAI Codex CLI 协同开发。支持 MCP 原生集成和桥接脚本两种模式。
-  默认模型：gpt-5.3-codex
+  与 Codex MCP 协同开发。通过 GuDaStudio/codexmcp 集成，使用 mcp__codex__codex 工具。
+  默认沙箱：read-only（严禁 codex 修改真实代码）。
 
   触发场景：
   - 需要算法实现或复杂逻辑分析
@@ -14,110 +14,128 @@ description: |
   触发词：Codex、协作、多模型、原型、Diff、算法分析、代码审查、codex协同
 
   前置要求：
-  - 已安装 Codex CLI (npm install -g @openai/codex)
-  - 已配置 OpenAI API Key (codex auth login)
+  - 已通过 `claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp` 注册
+  - ~/.claude/settings.json 的 permissions.allow 已加入 mcp__codex__codex
 ---
 
-# 与 Codex CLI 协同开发
+# 与 Codex MCP 协同开发
 
-> 两种调用方式：**MCP 原生集成**（推荐）和桥接脚本。默认模型 `gpt-5.3-codex`。
+> 通过 `mcp__codex__codex` 工具直接调用，无需命令行。始终使用 `read-only` 沙箱，要求 codex 只输出 unified diff patch。
 
 ---
 
-## 方式一：MCP 原生集成（推荐）
+## MCP 工具说明
 
-已通过 `codex-mcp-server` 注册为 Claude Code 的 MCP 工具，可直接在对话中使用。
+### 工具名
+`mcp__codex__codex`
 
-### MCP 工具列表
+### 参数
 
-| 工具 | 用途 | 示例指令 |
-|------|------|---------|
-| `codex` | AI 编码助手，支持会话、模型选择 | "用 codex 分析这个函数" |
-| `review` | 代码审查（未提交代码、分支、提交） | "用 codex review 检查 main 分支差异" |
-| `listSessions` | 查看活跃会话 | "列出 codex 会话" |
-| `ping` | 测试连接 | "ping codex" |
-
-### MCP 使用示例
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `PROMPT` | string | ✅ | - | 发送给 Codex 的任务指令（建议用英语） |
+| `cd` | Path | ✅ | - | 工作目录根路径（必须存在） |
+| `sandbox` | string | ❌ | `read-only` | `read-only` / `workspace-write` / `danger-full-access` |
+| `SESSION_ID` | UUID | ❌ | None | 继续之前的会话，保持上下文 |
+| `return_all_messages` | bool | ❌ | False | 是否返回推理过程和工具调用详情 |
+| `model` | string | ❌ | None | 指定模型（None 使用用户默认配置） |
+| `image` | List[Path] | ❌ | None | 附加图片文件 |
+| `yolo` | bool | ❌ | False | 跳过沙箱审批（危险，不推荐） |
+| `profile` | string | ❌ | None | 从 `~/.codex/config.toml` 加载的配置名 |
+| `skip_git_repo_check` | bool | ❌ | False | 允许在非 Git 仓库中运行 |
+
+### 返回值
+
+```json
+// 成功
+{
+  "success": true,
+  "SESSION_ID": "uuid-string",     // 必须保存，用于多轮交互
+  "agent_messages": "codex回复内容"
+}
+
+// 失败
+{
+  "success": false,
+  "error": "错误信息"
+}
+```
 
-**基础调用**：直接在 Claude Code 对话中说：
-- "用 codex 工具分析 OrderInfoService 的业务逻辑"
-- "用 codex review 检查当前未提交的代码变更"
-- "用 codex 生成这个方法的单元测试，模型用 gpt-5.3-codex"
+---
 
-**多轮会话**：codex 工具支持 `sessionId` 参数，自动维持上下文。
+## 标准协作流程
 
-**模型指定**：调用时传入 `model: "gpt-5.3-codex"` 参数（已配置为默认）。
+```
+1. 需求分析阶段
+   Claude 形成初步分析 → 告知 codex → codex 完善方案
 
-### MCP 配置位置
+2. 编码前（原型阶段）
+   调用 codex（read-only）→ 要求输出 unified diff patch
+   Claude 以 diff 为逻辑参考 → 重写为生产级代码
 
-```
-~/.claude.json → projects → mcpServers → codex-cli
-~/.codex/config.toml → profiles（review/analyze/prototype）
+3. 编码后（审查阶段）
+   调用 codex review 改动 → 验证需求完成度和代码质量
 ```
 
 ---
 
-## 方式二：桥接脚本
+## 调用示例
 
-适用于需要精细控制参数或后台批量执行的场景。
+### 场景一：需求分析完善
 
-### 快速开始
+```
+PROMPT: "Here is my requirement: [需求描述]. My initial approach: [初步思路].
+Please review and improve the analysis and implementation plan.
+Output: structured analysis with potential risks."
 
-```bash
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex --PROMPT "Your task"
+cd: /path/to/project
+sandbox: read-only
 ```
 
-### 参数说明
+### 场景二：获取代码原型（Diff）
 
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--PROMPT` | str | ✅ | - | 发送给 Codex 的任务指令（使用英语） |
-| `--cd` | Path | ✅ | - | 工作目录根路径 |
-| `--model` | str | ❌ | `gpt-5.3-codex` | 指定模型 |
-| `--sandbox` | Literal | ❌ | `read-only` | 沙箱策略 |
-| `--SESSION_ID` | UUID | ❌ | `None` | 会话 ID（继续之前的对话） |
-| `--profile` | str | ❌ | `None` | Codex profile（review/analyze/prototype） |
-| `--return-all-messages` | bool | ❌ | `False` | 返回完整推理信息 |
-| `--image` | List[Path] | ❌ | `None` | 附加图片 |
-| `--yolo` | bool | ❌ | `False` | 跳过审批（危险） |
-
-### 使用示例
+```
+PROMPT: "Generate a unified diff patch to implement [功能描述].
+File: [目标文件路径]
+Requirements:
+- [要求1]
+- [要求2]
 
-```bash
-# 代码分析（只读）
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex --profile analyze \
-  --PROMPT "Analyze the four-layer architecture in OrderInfoWebController"
-
-# 代码审查
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex --profile review \
-  --PROMPT "Review OrderWebBusiness.java for bugs. OUTPUT: Review with line numbers."
-
-# 生成 Diff 补丁
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex \
-  --PROMPT "Generate unified diff to add logging. OUTPUT: Unified Diff Patch ONLY."
-
-# 多轮会话
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex \
-  --SESSION_ID "uuid-from-previous" \
-  --PROMPT "Now write unit tests for the method we discussed"
+IMPORTANT: Output unified diff patch ONLY. Do NOT modify any real files.
+IMPORTANT: All Java comments and SQL COMMENTs MUST be in Chinese."
+
+cd: /path/to/project
+sandbox: read-only
 ```
 
----
+### 场景三：代码审查
+
+```
+PROMPT: "Review the following code changes for correctness, performance, and security.
+[粘贴代码或说明文件路径]
+
+Check:
+1. Logic correctness
+2. Edge cases
+3. Performance issues
+4. Security vulnerabilities
+
+Output: review with line numbers and severity (CRITICAL/WARNING/INFO)."
+
+cd: /path/to/project
+sandbox: read-only
+```
 
-## Codex Profile 配置
+### 场景四：多轮交互（继续会话）
 
-已在 `~/.codex/config.toml` 中预设 3 个 profile：
+```
+// 第一轮
+SESSION_ID: None → 保存返回的 SESSION_ID
 
-| Profile | 模型 | 沙箱 | 推理强度 | 适用场景 |
-|---------|------|------|---------|---------|
-| `review` | gpt-5.3-codex | read-only | medium | 快速代码审查 |
-| `analyze` | gpt-5.3-codex | read-only | high | 深度逻辑分析 |
-| `prototype` | gpt-5.3-codex | workspace-write | high | 原型生成 |
+// 第二轮
+SESSION_ID: "上一轮返回的 uuid"
+PROMPT: "Now refine the diff based on the feedback: [反馈内容]"
+```
 
 ---
 
@@ -125,24 +143,18 @@ python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
 
 | 角色 | Claude Code 负责 | Codex 负责 |
 |------|-----------------|-----------|
-| **架构** | 设计、决策、审校 | 分析现有代码 |
-| **开发** | 规范重构、最终代码 | 原型生成（Diff） |
-| **审查** | 规范检查、最终判定 | 逐文件审查、安全扫描 |
-| **调试** | 日志分析、定位 | 深度代码分析、补丁 |
+| **架构** | 设计决策、规范审校 | 分析现有代码结构 |
+| **开发** | 规范重写、最终代码实施 | 输出原型 diff（只读参考） |
+| **审查** | 规范检查、最终判定 | 逐文件逻辑审查 |
+| **调试** | 日志分析、问题定位 | 深度代码分析、补丁建议 |
 
 ### 重要约束
 
-1. **只读优先**: 默认 `read-only`，仅原型生成用 `workspace-write`
-2. **英语 Prompt**: 与 Codex 交互用英语
-3. **中文强制**: 每次 PROMPT 末尾追加：
-   ```
-   IMPORTANT LANGUAGE RULES:
-   - All SQL COMMENT values MUST be in Chinese
-   - All Java/code comments MUST be in Chinese
-   - Variable names and class names remain in English
-   ```
-4. **脏原型思维**: Codex 输出视为草稿，Claude 按项目规范重构
-5. **后台运行**: 长时间任务用 subagent `run_in_background`
+1. **只读优先**：始终使用 `sandbox="read-only"`
+2. **英语 Prompt**：与 codex 交互用英语，代码注释要求中文
+3. **脏原型思维**：codex 输出视为草稿，Claude 按项目规范重构
+4. **保存 SESSION_ID**：每次调用后记录，多轮对话时传入
+5. **质疑 codex**：codex 仅供参考，必须有独立判断
 
 ---
 
@@ -150,8 +162,19 @@ python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
 
 | 问题 | 解决方案 |
 |------|---------|
-| MCP 工具未出现 | 重启 Claude Code 会话，检查 `~/.claude.json` |
-| `codex: command not found` | `npm i -g @openai/codex` 并确认 PATH |
-| 模型不对 | 调用时显式传 `model: "gpt-5.3-codex"` |
-| MCP 连接超时 | `npx -y codex-mcp-server` 手动测试 |
-| 桥接脚本 SESSION_ID 失败 | 检查网络和 API Key |
+| 工具未出现 | 重启 Claude Code，检查 `~/.claude.json` 中 codex 配置 |
+| `cd` 参数报错 | 确认目录存在，使用绝对路径 |
+| 连接超时 | 检查网络，`uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp` 手动测试 |
+| SESSION_ID 失效 | 重新开启新会话（不传 SESSION_ID） |
+| codex 修改了文件 | 确认 `sandbox="read-only"` 已设置 |
+
+## 安装验证
+
+```bash
+# 查看 MCP 配置
+cat ~/.claude.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('mcpServers', {}).get('codex', 'not found'))"
+
+# 重启后运行
+claude mcp list
+# 期望看到: codex: uvx ... - ✓ Connected
+```