claude-coder 1.8.4 → 1.9.0

package/README.md

@@ -6,7 +6,7 @@
 
 ### 亮点
 
-- **Harness 生命周期管理**：统一的 Harness 类封装环境准备、任务调度、校验、回滚、推送全生命周期，含 AI 驱动的 JSON 自愈修复
+- **Session 生命周期管理**：Session 类封装 SDK 管理、query 执行、hooks、indicator 全生命周期，runner 编排循环含 AI 驱动的 JSON 自愈修复
 - **Hook 提示注入**：通过 JSON 配置在工具调用时向模型注入上下文引导，零代码修改即可扩展规则（[机制详解](design/hook-mechanism.md)）
 - **长时间自循环编码**：多 session 编排 + 倒计时活跃度监控 + git 回滚重试，Agent 可持续编码数小时不中断（[守护机制](design/session-guard.md)）
 - **配置驱动**：支持 Claude 官方、Coding Plan 多模型路由、DeepSeek 等任意 Anthropic 兼容 API
@@ -41,6 +41,7 @@ claude-coder run "实现用户注册和登录功能"
 |------|------|
 | `claude-coder setup` | 交互式配置（模型、MCP、安全限制、自动审查） |
 | `claude-coder init` | 初始化项目环境（扫描技术栈、生成 profile） |
+| `claude-coder init --deploy-templates` | 部署模板和食谱到项目目录（可自定义） |
 | `claude-coder plan "需求"` | 生成计划方案 |
 | `claude-coder plan -r [file]` | 从需求文件生成计划 |
 | `claude-coder plan --planOnly` | 仅生成计划文档，不分解任务 |
@@ -52,7 +53,7 @@ claude-coder run "实现用户注册和登录功能"
 | `claude-coder run --max 1` | 单次执行 |
 | `claude-coder run --dry-run` | 预览模式（查看任务队列） |
 | `claude-coder simplify [focus]` | 代码审查和简化 |
-| `claude-coder auth [url]` | 导出 Playwright 登录状态 |
+| `claude-coder auth [url]` | 配置浏览器测试工具 / 导出登录状态 |
 | `claude-coder status` | 查看进度和成本 |
 
 **选项**：`--max N` 限制 session 数（默认 50），`--pause N` 每 N 个 session 暂停确认，`--model M` 指定模型。
@@ -68,26 +69,26 @@ claude-coder run "实现用户注册和登录功能"
                                  │  3 步流程    │
                                  └──────┬──────┘
                                         │
-                                   Harness 校验
+                                   runner 校验
                                    (含 AI 自愈)
                                         │
                               通过 → simplify? → push → 下一个任务
                               失败 → git 回滚 + 重试
 ```
 
-每个 session 内，Agent 自主执行 3 步：**实现**（任务上下文由 harness 注入，编码实现） → **验证**（按 category 选最轻量测试） → **收尾**（git commit + 写 session_result.json）。
+每个 session 内，Agent 自主执行 3 步：**实现**（任务上下文由 prompt 注入，编码实现） → **验证**（按 category 选最轻量测试） → **收尾**（git commit + 写 session_result.json）。
 
-Harness 在 session 结束后自动校验 `session_result.json` + git 进度。校验失败时 AI 自动尝试修复损坏的 JSON 文件（`repair.js`），仍失败则回滚代码并重试。
+Runner 在 session 结束后自动校验 `session_result.json` + git 进度。校验失败时 AI 自动尝试修复损坏的 JSON 文件（`repair.js`），仍失败则回滚代码并重试。
 
 ## 机制文档
 
 | 文档 | 说明 |
 |------|------|
-| [技术架构](design/ARCHITECTURE.md) | 核心设计规则、Harness 类职责、模块关系、Prompt 注入架构 |
+| [技术架构](design/ARCHITECTURE.md) | 核心设计规则、Session 类职责、模块关系、Prompt 注入架构 |
 | [Hook 注入机制](design/hook-mechanism.md) | SDK Hook 调研、GuidanceInjector 三级匹配、配置格式、副作用评估 |
 | [Session 守护机制](design/session-guard.md) | 中断策略、倒计时活跃度检测、工具运行状态追踪、防刷屏 |
 | [Go 指令流程](design/go-flow.md) | AI 驱动的需求组装、食谱系统、与 plan 衔接 |
-| [测试凭证方案](docs/PLAYWRIGHT_CREDENTIALS.md) | Playwright 登录态导出、API Key 持久化 |
+| [浏览器测试工具](docs/PLAYWRIGHT_CREDENTIALS.md) | Playwright MCP / Chrome DevTools MCP 对比、安装、凭证管理 |
 | [SDK 使用指南](docs/CLAUDE_AGENT_SDK_GUIDE.md) | Claude Agent SDK 接口参考 |
 
 ## 使用场景
@@ -96,11 +97,57 @@ Harness 在 session 结束后自动校验 `session_result.json` + git 进度。
 
 **已有项目**：`claude-coder run "新增头像上传功能"` — 先扫描现有代码和技术栈，再增量开发。
 
-**需求文档驱动**：在项目根目录创建 `requirements.md`，运行 `claude-coder run`。需求变更后 `claude-coder add -r` 同步新任务。
+**需求文档驱动**：在项目根目录创建 `requirements.md`，运行 `claude-coder plan -r requirements.md` 分解任务后 `claude-coder run` 执行。
 
 **AI 驱动需求组装**：`claude-coder go "用户管理页面"` — AI 扫描内置食谱库，自动组装完整需求方案，一键进入 plan 分解任务。支持对话模式 (`go`) 逐步引导非技术人员。
 
-**自动测试 + 凭证持久化**：`claude-coder auth http://localhost:3000` — 导出浏览器登录态，Agent 测试时自动使用。详见 [测试凭证方案](docs/PLAYWRIGHT_CREDENTIALS.md)。
+**自动测试 + 凭证持久化**：`claude-coder auth http://localhost:3000` — 导出浏览器登录态，Agent 测试时自动使用。详见 [浏览器测试工具指南](docs/PLAYWRIGHT_CREDENTIALS.md)。
+
+## 浏览器测试工具
+
+支持两种 MCP 浏览器测试工具，通过 `WEB_TEST_TOOL` 环境变量切换：
+
+| 维度 | Playwright MCP | Chrome DevTools MCP |
+|------|---------------|---------------------|
+| **维护方** | 微软 | Google |
+| **核心优势** | 25+ 自动化工具，多实例并行 | 连接已打开 Chrome，调试能力强 |
+| **多实例** | 支持 | 不支持（单实例，多开请用 Playwright） |
+| **安装依赖** | `npx playwright install chromium` | Node.js v20.19+ / Chrome 144+ |
+| **凭证方案** | persistent 模式复用登录态 | 直接复用已打开 Chrome 的登录态 |
+| **适合场景** | CI/CD、多并行测试、需要 Chromium 隔离 | 本地开发、调试、利用已有 Chrome 环境 |
+
+### 安装步骤
+
+```bash
+# Playwright MCP（推荐）
+claude-coder setup          # → 选择「Playwright MCP」→ 选择模式
+npx playwright install chromium
+claude-coder auth http://your-app.com   # 导出登录态
+
+# Chrome DevTools MCP（需 Node.js v20.19+）
+claude-coder setup          # → 选择「Chrome DevTools MCP」
+# 打开 Chrome → chrome://inspect/#remote-debugging → 启用远程调试
+claude-coder auth           # 配置 .mcp.json
+```
+
+### 常见问题
+
+**Q: Playwright 和 Chrome DevTools 该选哪个？**
+A: 如果你需要多实例并行测试或 CI/CD 集成，选 Playwright MCP。如果你只需要本地调试、想复用已打开 Chrome 的登录态和扩展，选 Chrome DevTools MCP。
+
+**Q: Chrome DevTools MCP 报 `chrome-devtools-mcp` 安装失败？**
+A: 确保 Node.js ≥ v20.19。nvm 用户执行 `nvm alias default 22 && nvm use 22`，然后重新安装 `npm install -g @anthropic-ai/claude-code`。
+
+**Q: Playwright 浏览器启动后白屏或超时？**
+A: 运行 `npx playwright install chromium` 确保浏览器已安装。persistent 模式下检查 `.claude-coder/.runtime/browser-profile/` 目录是否存在。
+
+**Q: 切换工具后需要重新认证吗？**
+A: 不需要。`claude-coder setup` 切换时自动更新 `.env` 和 `.mcp.json`。之前的认证数据（如 browser-profile）保留，切回时直接可用。
+
+**Q: 两个工具可以同时启用吗？**
+A: 不可以。`.mcp.json` 中同时只保留一个工具的配置，切换时自动替换。
+
+详见 [浏览器测试工具完整文档](docs/PLAYWRIGHT_CREDENTIALS.md)。
 
 ## 模型支持
 
@@ -142,9 +189,9 @@ your-project/
     progress.json           # 会话历史 + 成本
     test.env                # 测试凭证（可选）
     go/                     # go 指令输出的方案文件
-    recipes/                # 食谱库（init 时从内置模板部署）
+    recipes/                # 食谱库（--deploy-templates 时从内置模板部署，可选）
     .runtime/
-      harness_state.json    # Harness 状态（session 计数等）
+      harness_state.json    # 运行状态（session 计数等）
       logs/                 # 每 session 独立日志
 ```
 
@@ -154,7 +201,7 @@ your-project/
 
 **中断恢复**：直接重新运行 `claude-coder run`，从上次中断处继续。
 
-**长时间无响应**：模型处理复杂任务时可能出现长思考间隔（indicator 显示黄色"工具执行中"或红色"无响应"），这是正常行为。超过阈值后 harness 自动中断并重试。通过 `claude-coder setup` 的安全限制配置或 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 调整。
+**长时间无响应**：模型处理复杂任务时可能出现长思考间隔（indicator 显示黄色"工具执行中"或红色"无响应"），这是正常行为。超过阈值后自动中断并重试。通过 `claude-coder setup` 的安全限制配置或 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 调整。
 
 **跳过任务**：将 `.claude-coder/tasks.json` 中该任务的 `status` 改为 `done`。
 

package/bin/cli.js

@@ -6,7 +6,7 @@ const pkg = require('../package.json');
 const COMMANDS = {
   run:       { desc: '自动编码循环',             usage: 'claude-coder run [--max N] [--pause N] [--dry-run]' },
   setup:     { desc: '交互式模型配置',           usage: 'claude-coder setup' },
-  init:      { desc: '初始化项目环境',           usage: 'claude-coder init' },
+  init:      { desc: '初始化项目环境',           usage: 'claude-coder init [--deploy-templates]' },
   plan:      { desc: '生成计划方案',             usage: 'claude-coder plan "需求" | plan -r requirements.md [--planOnly] [-i]' },
   simplify:  { desc: '代码审查和简化',           usage: 'claude-coder simplify [focus]' },
   auth:      { desc: '导出 Playwright 登录状态', usage: 'claude-coder auth [url]' },
@@ -31,6 +31,7 @@ function showHelp() {
   console.log('  claude-coder run --max 1             单次执行');
   console.log('  claude-coder run --max 5 --pause 5   每 5 个 session 暂停确认');
   console.log('  claude-coder run --dry-run            预览模式');
+  console.log('  claude-coder init --deploy-templates  部署模板和食谱到项目目录（可自定义）');
   console.log('  claude-coder simplify               代码审查和简化');
   console.log('  claude-coder simplify "内存效率"     聚焦特定领域审查');
   console.log('  claude-coder go                      对话式需求收集和方案组装');
@@ -50,6 +51,11 @@ function parseArgs(argv) {
   const positional = [];
 
   for (let i = 1; i < args.length; i++) {
+    // support --key=value syntax
+    if (args[i].startsWith('--') && args[i].includes('=')) {
+      const eq = args[i].indexOf('=');
+      args.splice(i, 1, args[i].slice(0, eq), args[i].slice(eq + 1));
+    }
     switch (args[i]) {
       case '--max':
         opts.max = parseInt(args[++i], 10) || 50;
@@ -87,6 +93,9 @@ function parseArgs(argv) {
       case '--interactive':
         opts.interactive = true;
         break;
+      case '--deploy-templates':
+        opts.deployTemplates = true;
+        break;
       case '--help':
       case '-h':
         showHelp();
@@ -103,7 +112,7 @@ function parseArgs(argv) {
   return { command, positional, opts };
 }
 
-async function main() {
+async function cliMain() {
   const { command, positional, opts } = parseArgs(process.argv);
 
   if (!command || command === '--help' || command === '-h') {
@@ -117,56 +126,30 @@ async function main() {
   }
 
   switch (command) {
-    case 'run': {
-      const runner = require('../src/core/runner');
-      await runner.run(opts);
-      break;
-    }
     case 'setup': {
       const setup = require('../src/commands/setup');
       await setup.setup();
-      break;
-    }
-    case 'init': {
-      const { init } = require('../src/core/init');
-      await init();
-      break;
-    }
-    case 'plan': {
-      const { run: planRun } = require('../src/core/plan');
-      const input = positional[0] || '';
-      await planRun(input, opts);
-      break;
-    }
-    case 'simplify': {
-      const { simplify } = require('../src/core/simplify');
-      await simplify(positional[0] || null, { n: opts.n });
-      break;
+      return;
     }
     case 'auth': {
       const { auth } = require('../src/commands/auth');
       await auth(positional[0] || null);
-      break;
-    }
-    case 'go': {
-      const { run: goRun } = require('../src/core/go');
-      await goRun(positional[0] || '', opts);
-      break;
+      return;
     }
     case 'status': {
       const tasks = require('../src/common/tasks');
       tasks.showStatus();
-      break;
+      return;
     }
-    default:
-      console.error(`未知命令: ${command}`);
-      showHelp();
-      process.exit(1);
   }
+
+  const { main } = require('../src');
+  await main(command, positional[0] || '', opts);
 }
 
-main().catch(err => {
-  console.error(`\n错误: ${err.message}`);
+cliMain().catch(err => {
+  const { log } = require('../src/common/config');
+  log('error', err.message);
   if (process.env.DEBUG) console.error(err.stack);
   process.exit(1);
 });

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "claude-coder",
-  "version": "1.8.4",
+  "version": "1.9.0",
   "description": "Claude Coder — Autonomous coding agent harness powered by Claude Code SDK. Scan, plan, code, validate, git-commit in a loop.",
   "bin": {
     "claude-coder": "bin/cli.js"
   },
+  "types": "types/index.d.ts",
   "files": [
     "bin/",
     "src/",
+    "types/",
     "recipes/",
     "templates/"
   ],

package/src/commands/auth.js

@@ -41,7 +41,11 @@ function updateGitignore(entry) {
   }
 }
 
-function updateMcpConfig(mcpPath, mode) {
+// ─────────────────────────────────────────────────────────────
+// .mcp.json 配置（Playwright / Chrome DevTools 共用）
+// ─────────────────────────────────────────────────────────────
+
+function updateMcpConfig(mcpPath, tool, mode) {
   let mcpConfig = {};
   if (fs.existsSync(mcpPath)) {
     try { mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf8')); } catch {}
@@ -49,6 +53,19 @@ function updateMcpConfig(mcpPath, mode) {
 
   if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
 
+  if (tool === 'chrome-devtools') {
+    delete mcpConfig.mcpServers.playwright;
+    mcpConfig.mcpServers['chrome-devtools'] = {
+      command: 'npx',
+      args: ['-y', 'chrome-devtools-mcp@latest', '--autoConnect'],
+    };
+    fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf8');
+    log('ok', '.mcp.json 已配置 Chrome DevTools MCP (autoConnect)');
+    return;
+  }
+
+  // Playwright MCP
+  delete mcpConfig.mcpServers['chrome-devtools'];
   const args = ['@playwright/mcp@latest'];
   const projectRoot = assets.projectRoot;
 
@@ -75,23 +92,23 @@ function updateMcpConfig(mcpPath, mode) {
   log('ok', `.mcp.json 已配置 Playwright MCP (${mode} 模式)`);
 }
 
-function enableMcpPlaywrightEnv() {
+function enableWebTestEnv(tool) {
   const envPath = assets.path('env');
   if (!envPath || !fs.existsSync(envPath)) return;
 
   let content = fs.readFileSync(envPath, 'utf8');
-  if (/^MCP_PLAYWRIGHT=/m.test(content)) {
-    content = content.replace(/^MCP_PLAYWRIGHT=.*/m, 'MCP_PLAYWRIGHT=true');
+  if (/^WEB_TEST_TOOL=/m.test(content)) {
+    content = content.replace(/^WEB_TEST_TOOL=.*/m, `WEB_TEST_TOOL=${tool}`);
   } else {
     const suffix = content.endsWith('\n') ? '' : '\n';
-    content += `${suffix}MCP_PLAYWRIGHT=true\n`;
+    content += `${suffix}WEB_TEST_TOOL=${tool}\n`;
   }
   fs.writeFileSync(envPath, content, 'utf8');
-  log('ok', '.claude-coder/.env 已设置 MCP_PLAYWRIGHT=true');
+  log('ok', `.claude-coder/.env 已设置 WEB_TEST_TOOL=${tool}`);
 }
 
 // ─────────────────────────────────────────────────────────────
-// 浏览器脚本（session cookie 自动持久化）
+// 浏览器脚本（Playwright persistent 模式用）
 // ─────────────────────────────────────────────────────────────
 
 function buildBrowserScript(playwrightDir, profileDir, url) {
@@ -185,9 +202,9 @@ async function authPersistent(url) {
 
   const mcpPath = assets.path('mcpConfig');
   log('ok', '登录状态已保存到持久化配置');
-  updateMcpConfig(mcpPath, 'persistent');
+  updateMcpConfig(mcpPath, 'playwright', 'persistent');
   updateGitignore('.claude-coder/.runtime/browser-profile');
-  enableMcpPlaywrightEnv();
+  enableWebTestEnv('playwright');
 
   console.log('');
   log('ok', '配置完成！');
@@ -227,9 +244,9 @@ async function authIsolated(url) {
 
   const mcpPath = assets.path('mcpConfig');
   log('ok', '登录状态已保存到 playwright-auth.json');
-  updateMcpConfig(mcpPath, 'isolated');
+  updateMcpConfig(mcpPath, 'playwright', 'isolated');
   updateGitignore('.claude-coder/playwright-auth.json');
-  enableMcpPlaywrightEnv();
+  enableWebTestEnv('playwright');
 
   console.log('');
   log('ok', '配置完成！');
@@ -251,8 +268,8 @@ function authExtension() {
   console.log('');
 
   const mcpPath = assets.path('mcpConfig');
-  updateMcpConfig(mcpPath, 'extension');
-  enableMcpPlaywrightEnv();
+  updateMcpConfig(mcpPath, 'playwright', 'extension');
+  enableWebTestEnv('playwright');
 
   console.log('');
   log('ok', '配置完成！');
@@ -260,13 +277,68 @@ function authExtension() {
   log('info', '确保 Chrome/Edge 已运行且 Playwright MCP Bridge 扩展已启用');
 }
 
+function authChromeDevTools() {
+  console.log('Chrome DevTools MCP 配置:');
+  console.log('');
+  console.log('  此模式通过 Chrome DevTools Protocol 连接到已打开的 Chrome 浏览器。');
+  console.log('  直接复用浏览器中已有的登录态、扩展和 DevTools 调试能力。');
+  console.log('');
+  console.log('  前置条件:');
+  console.log('  1. Node.js v20.19+（npx 自动下载 chrome-devtools-mcp 包）');
+  console.log('  2. Chrome 144+ 版本');
+  console.log('  3. 打开 chrome://inspect/#remote-debugging 启用远程调试');
+  console.log('  4. 允许传入调试连接');
+  console.log('');
+  console.log('  功能:');
+  console.log('  - 输入自动化: 点击、输入、表单填写');
+  console.log('  - 页面导航: 多页面管理、截图');
+  console.log('  - 性能分析: Trace 录制、Core Web Vitals、Lighthouse 审计');
+  console.log('  - 调试工具: Console 消息、网络请求检查、内存快照');
+  console.log('');
+  console.log(`  注意: 单实例限制，同一时间只能连接一个 Chrome 调试会话。`);
+  console.log(`  如需多实例并行，请配置 Playwright MCP（claude-coder setup）。`);
+  console.log('');
+
+  const mcpPath = assets.path('mcpConfig');
+  updateMcpConfig(mcpPath, 'chrome-devtools');
+  enableWebTestEnv('chrome-devtools');
+
+  console.log('');
+  log('ok', '配置完成！');
+  log('info', 'Chrome DevTools MCP 使用 autoConnect 模式');
+  log('info', '确保 Chrome 已启动且已在 chrome://inspect 中启用远程调试');
+}
+
 async function auth(url) {
   assets.ensureDirs();
   const config = loadConfig();
-  const mode = config.playwrightMode;
+  const tool = config.webTestTool;
+
+  if (!tool) {
+    log('error', '未配置浏览器测试工具');
+    log('info', '请先运行 claude-coder setup 选择 Playwright MCP 或 Chrome DevTools MCP');
+    return;
+  }
+
+  if (tool === 'chrome-devtools') {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 20 || (major === 20 && minor < 19)) {
+      log('warn', `当前 Node.js 版本 v${process.versions.node}，Chrome DevTools MCP 要求 v20.19+`);
+      log('info', 'nvm 用户请执行: nvm alias default 22 && nvm use 22');
+      log('info', '升级后重新运行此命令');
+      return;
+    }
+    log('info', '浏览器工具: Chrome DevTools MCP');
+    console.log('');
+    authChromeDevTools();
+    return;
+  }
+
+  // Playwright MCP
+  const mode = config.webTestMode;
   const targetUrl = normalizeUrl(url) || 'http://localhost:3000';
 
-  log('info', `Playwright 模式: ${mode}`);
+  log('info', `浏览器工具: Playwright MCP (${mode} 模式)`);
   log('info', `目标 URL: ${targetUrl}`);
   console.log('');
 

package/src/commands/setup-modules/helpers.js

@@ -76,11 +76,12 @@ function showCurrentConfig(existing) {
   console.log(`  提供商:     ${existing.MODEL_PROVIDER || '未配置'}`);
   console.log(`  BASE_URL:   ${existing.ANTHROPIC_BASE_URL || '默认'}`);
   console.log(`  模型:       ${existing.ANTHROPIC_MODEL || '默认'}`);
-  console.log(`  MCP:        ${existing.MCP_PLAYWRIGHT === 'true' ? `已启用 (${existing.MCP_PLAYWRIGHT_MODE || 'persistent'})` : '未启用'}`);
-  const compTimeout = existing.SESSION_COMPLETION_TIMEOUT || '300';
+  const webTool = existing.WEB_TEST_TOOL;
+  const webMode = existing.WEB_TEST_MODE;
+  console.log(`  浏览器工具: ${webTool ? `${webTool}${webMode ? ` (${webMode})` : ''}` : '未启用'}`);
   const turns = existing.SESSION_MAX_TURNS || '0';
   console.log(`  停顿超时:   ${existing.SESSION_STALL_TIMEOUT || '600'} 秒`);
-  console.log(`  完成检测:   ${compTimeout} 秒`);
+  console.log(`  完成检测:   Stop hook（SDK 原生）`);
   console.log(`  工具轮次:   ${turns === '0' ? '无限制' : turns}`);
   const simplifyInterval = existing.SIMPLIFY_INTERVAL ?? '5';
   const simplifyCommits = existing.SIMPLIFY_COMMITS ?? '5';

package/src/commands/setup-modules/mcp.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { ask, askChoice } = require('./helpers');
+const { askChoice } = require('./helpers');
 const { log, COLOR, updateEnvVar } = require('../../common/config');
 const { assets } = require('../../common/assets');
 
@@ -8,34 +8,31 @@ const { assets } = require('../../common/assets');
 
 async function configureMCP(rl) {
   console.log('');
-  console.log('是否启用 Playwright MCP（浏览器自动化测试）？');
+  console.log('是否启用浏览器测试工具？');
   console.log('');
-  console.log('  Playwright MCP 由微软官方维护 (github.com/microsoft/playwright-mcp)');
-  console.log('  提供 browser_click、browser_snapshot 等 25+ 浏览器自动化工具');
-  console.log('  适用于有 Web 前端的项目，Agent 可用它做端到端测试');
-  console.log('');
-  console.log('  1) 是 - 启用 Playwright MCP（项目有 Web 前端）');
-  console.log('  2) 否 - 跳过（纯后端 / CLI 项目）');
+  console.log('  1) Playwright MCP — 微软官方，25+ 浏览器自动化工具，支持多实例并行');
+  console.log('  2) Chrome DevTools MCP — Google 官方，连接已打开的 Chrome，调试能力更强');
+  console.log('     （单实例限制，多开请配置 Playwright MCP）');
+  console.log('  3) 跳过（纯后端 / CLI 项目）');
   console.log('');
 
-  const mcpChoice = await askChoice(rl, '选择 [1-2]: ', 1, 2);
+  const toolChoice = await askChoice(rl, '选择 [1-3]: ', 1, 3);
 
-  const mcpConfig = { enabled: false, mode: null };
+  const mcpConfig = { tool: '', mode: '' };
 
-  if (mcpChoice === 1) {
-    mcpConfig.enabled = true;
+  if (toolChoice === 1) {
+    mcpConfig.tool = 'playwright';
     console.log('');
     console.log('请选择 Playwright MCP 浏览器模式:');
     console.log('');
     console.log('  1) persistent - 懒人模式（默认，推荐）');
-    console.log('     登录一次永久生效，适合 Google SSO、企业内网 API 拉取等日常开发');
+    console.log('     登录一次永久生效，适合 Google SSO、企业内网等日常开发');
     console.log('');
     console.log('  2) isolated - 开发模式');
     console.log('     每次会话从快照加载，适合验证登录流程的自动化测试');
     console.log('');
     console.log('  3) extension - 连接真实浏览器（实验性）');
     console.log('     通过 Chrome 扩展复用已有登录态和插件');
-    console.log('     需要安装 "Playwright MCP Bridge" 扩展');
     console.log('');
 
     const modeChoice = await askChoice(rl, '选择 [1-3，默认 1]: ', 1, 3, 1);
@@ -58,6 +55,25 @@ async function configureMCP(rl) {
       console.log('  使用 claude-coder auth <URL> 录制登录状态到 playwright-auth.json');
       console.log('  MCP 每次会话从此文件加载初始 cookies/localStorage');
     }
+  } else if (toolChoice === 2) {
+    mcpConfig.tool = 'chrome-devtools';
+
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 20 || (major === 20 && minor < 19)) {
+      console.log('');
+      console.log(`  ${COLOR.yellow}⚠ 当前 Node.js v${process.versions.node}，Chrome DevTools MCP 要求 v20.19+${COLOR.reset}`);
+      console.log(`  ${COLOR.blue}  nvm 用户: nvm alias default 22 && nvm use 22${COLOR.reset}`);
+    }
+
+    console.log('');
+    console.log('  Chrome DevTools MCP 将连接已打开的 Chrome 浏览器。');
+    console.log('');
+    console.log('  前置条件:');
+    console.log('  1. Node.js v20.19+（npx 自动下载 chrome-devtools-mcp 包）');
+    console.log('  2. Chrome 144+');
+    console.log('  3. 打开 chrome://inspect/#remote-debugging 启用远程调试');
+    console.log('');
+    console.log('  运行 claude-coder auth 自动配置 .mcp.json');
   }
 
   return mcpConfig;
@@ -66,12 +82,12 @@ async function configureMCP(rl) {
 // ── MCP 配置追加到 lines ──
 
 function appendMcpConfig(lines, mcpConfig) {
-  lines.push('', '# MCP 工具配置');
-  if (mcpConfig.enabled) {
-    lines.push('MCP_PLAYWRIGHT=true');
-    if (mcpConfig.mode) lines.push(`MCP_PLAYWRIGHT_MODE=${mcpConfig.mode}`);
+  lines.push('', '# 浏览器测试工具配置');
+  if (mcpConfig.tool) {
+    lines.push(`WEB_TEST_TOOL=${mcpConfig.tool}`);
+    if (mcpConfig.mode) lines.push(`WEB_TEST_MODE=${mcpConfig.mode}`);
   } else {
-    lines.push('MCP_PLAYWRIGHT=false');
+    lines.push('WEB_TEST_TOOL=');
   }
 }
 
@@ -79,11 +95,15 @@ function appendMcpConfig(lines, mcpConfig) {
 
 async function updateMCPOnly(rl) {
   const mcpConfig = await configureMCP(rl);
-  updateEnvVar('MCP_PLAYWRIGHT', mcpConfig.enabled ? 'true' : 'false');
-  if (mcpConfig.enabled && mcpConfig.mode) {
-    updateEnvVar('MCP_PLAYWRIGHT_MODE', mcpConfig.mode);
+  updateEnvVar('WEB_TEST_TOOL', mcpConfig.tool);
+  if (mcpConfig.tool === 'playwright' && mcpConfig.mode) {
+    updateEnvVar('WEB_TEST_MODE', mcpConfig.mode);
+    const { updateMcpConfig } = require('../auth');
+    updateMcpConfig(assets.path('mcpConfig'), 'playwright', mcpConfig.mode);
+  } else if (mcpConfig.tool === 'chrome-devtools') {
+    updateEnvVar('WEB_TEST_MODE', '');
     const { updateMcpConfig } = require('../auth');
-    updateMcpConfig(assets.path('mcpConfig'), mcpConfig.mode);
+    updateMcpConfig(assets.path('mcpConfig'), 'chrome-devtools');
   }
   log('ok', 'MCP 配置已更新');
 }
@@ -92,4 +112,4 @@ module.exports = {
   configureMCP,
   appendMcpConfig,
   updateMCPOnly,
-};
+};

package/src/commands/setup-modules/safety.js

@@ -7,16 +7,14 @@ const { log, COLOR, updateEnvVar } = require('../../common/config');
 
 async function updateSafetyLimits(rl, existing) {
   const currentStall = existing.SESSION_STALL_TIMEOUT || '600';
-  const currentCompletion = existing.SESSION_COMPLETION_TIMEOUT || '300';
   const currentTurns = existing.SESSION_MAX_TURNS || '0';
 
   console.log(`${COLOR.blue}当前安全限制:${COLOR.reset}`);
   console.log(`  停顿超时:     ${currentStall} 秒 (${Math.floor(parseInt(currentStall) / 60)} 分钟)`);
-  console.log(`  完成检测超时: ${currentCompletion} 秒 (${Math.ceil(parseInt(currentCompletion) / 60)} 分钟)`);
   console.log(`  最大工具轮次: ${currentTurns === '0' ? '无限制' : currentTurns}`);
   console.log('');
   console.log(`${COLOR.yellow}说明:${COLOR.reset}`);
-  console.log('  完成检测 — 模型写入 session_result.json 后缩短等待，解决"完成但不退出"');
+  console.log('  完成检测 — 通过 SDK Stop hook 感知模型结束，无需额外超时');
   console.log('  停顿超时 — 长时间无工具调用时自动中断（通用兜底）');
   console.log('  最大轮次 — 限制总轮次，仅 CI 推荐（默认 0 = 无限制）');
   console.log('');
@@ -32,18 +30,6 @@ async function updateSafetyLimits(rl, existing) {
     }
   }
 
-  console.log('');
-  const compInput = await ask(rl, `完成检测超时秒数（回车保留 ${currentCompletion}）: `);
-  if (compInput.trim()) {
-    const seconds = parseInt(compInput.trim(), 10);
-    if (isNaN(seconds) || seconds < 30) {
-      log('warn', '完成检测超时需 >= 30 秒，跳过');
-    } else {
-      updateEnvVar('SESSION_COMPLETION_TIMEOUT', String(seconds));
-      log('ok', `完成检测超时已设置为 ${seconds} 秒`);
-    }
-  }
-
   console.log('');
   const turnsInput = await ask(rl, `最大工具轮次（回车保留 ${currentTurns === '0' ? '无限制' : currentTurns}，输入 0 = 无限制）: `);
   if (turnsInput.trim()) {