claude-coder 1.5.7 → 1.6.2

package/README.md

@@ -60,6 +60,7 @@ claude-coder run "实现用户注册和登录功能"
 | `claude-coder validate` | 手动校验 |
 | `claude-coder status` | 查看进度和成本 |
 | `claude-coder config sync` | 同步配置到 ~/.claude/ |
+| `claude-coder config mcp <mode>` | 快速切换 Playwright 模式 |
 
 **选项**：`--max N` 限制 session 数（默认 50），`--pause N` 每 N 个 session 暂停确认（默认不暂停）。
 
@@ -97,10 +98,10 @@ your-project/
     progress.json           # 会话历史 + 成本
     tests.json              # 验证记录
     test.env                # 测试凭证（API Key 等，可选）
-    playwright-auth.json    # 登录状态快照（备份参考，auth 命令生成）
-    browser-profile/        # 持久化浏览器 Profile（MCP 实际使用）
+    playwright-auth.json    # 登录状态快照（isolated 模式，auth 命令生成）
     .runtime/               # 临时文件
       logs/                 # 每 session 独立日志（含工具调用记录）
+      browser-profile/      # 持久化浏览器 Profile（persistent 模式，auth 命令生成）
   requirements.md           # 需求文档（可选）
 ```
 

package/bin/cli.js

@@ -11,7 +11,7 @@ const COMMANDS = {
   auth:     { desc: '导出 Playwright 登录状态', usage: 'claude-coder auth [url]' },
   validate: { desc: '手动校验上次 session',     usage: 'claude-coder validate' },
   status:   { desc: '查看任务进度和成本',       usage: 'claude-coder status' },
-  config:   { desc: '配置管理',                 usage: 'claude-coder config sync' },
+  config:   { desc: '配置管理',                 usage: 'claude-coder config sync | config mcp <mode>' },
 };
 
 function showHelp() {
@@ -32,6 +32,7 @@ function showHelp() {
   console.log('  claude-coder add "..." --model opus-4 指定模型追加任务');
   console.log('  claude-coder auth                    导出 Playwright 登录状态');
   console.log('  claude-coder auth http://localhost:8080  指定登录 URL');
+  console.log('  claude-coder config mcp persistent   快速切换 Playwright 模式');
   console.log('  claude-coder status                  查看进度和成本');
   console.log(`\n前置条件: npm install -g @anthropic-ai/claude-agent-sdk`);
 }
@@ -152,8 +153,32 @@ async function main() {
       const config = require('../src/config');
       if (positional[0] === 'sync') {
         config.syncToGlobal();
+      } else if (positional[0] === 'mcp') {
+        const validModes = ['persistent', 'isolated', 'extension'];
+        const mode = positional[1];
+        if (!mode || !validModes.includes(mode)) {
+          console.error(`用法: claude-coder config mcp <${validModes.join('|')}>`);
+          process.exit(1);
+        }
+        const ok = config.updateEnvVar('MCP_PLAYWRIGHT_MODE', mode);
+        if (!ok) {
+          console.error('未找到配置文件，请先运行 claude-coder setup');
+          process.exit(1);
+        }
+        config.updateEnvVar('MCP_PLAYWRIGHT', 'true');
+        const { updateMcpConfig } = require('../src/auth');
+        updateMcpConfig(config.paths(), mode);
+        const { log } = config;
+        log('ok', `Playwright 模式已切换为: ${mode}`);
+        if (mode === 'persistent') {
+          log('info', '运行 claude-coder auth <URL> 完成首次登录');
+        } else if (mode === 'isolated') {
+          log('info', '运行 claude-coder auth <URL> 录制登录状态');
+        } else {
+          log('info', '确保已安装 Playwright MCP Bridge 扩展并启动浏览器');
+        }
       } else {
-        console.error('用法: claude-coder config sync');
+        console.error('用法: claude-coder config sync | config mcp <mode>');
         process.exit(1);
       }
       break;

package/docs/ARCHITECTURE.md

@@ -51,8 +51,8 @@ Agent 在单次 session 中应最大化推进任务进度。**任何非致命问
 | 文件 | git 状态 | 说明 |
 |------|---------|------|
 | `test.env` | .gitignore | Agent 可写入发现的 API Key、测试账号 |
-| `playwright-auth.json` | .gitignore | 登录状态快照备份（`claude-coder auth` 生成） |
-| `browser-profile/` | .gitignore | 持久化浏览器 Profile（MCP 实际使用） |
+| `playwright-auth.json` | .gitignore | cookies + localStorage 快照（isolated 模式，`claude-coder auth` 生成） |
+| `.runtime/browser-profile/` | .gitignore | 持久化浏览器 Profile（persistent 模式，`claude-coder auth` 生成） |
 | `session_result.json` | git-tracked | Agent 每次 session 覆盖写入 |
 | `tasks.json` | git-tracked | Agent 修改 status 字段 |
 
@@ -208,10 +208,10 @@ templates/
 | `tasks.json` | 首次扫描 | 任务列表 + 状态跟踪 |
 | `progress.json` | 每次 session 结束 | 结构化会话日志 + 成本记录 |
 | `session_result.json` | 每次 session 结束 | 当前 session 结果（扁平格式，向后兼容旧 `current` 包装） |
-| `playwright-auth.json` | `claude-coder auth` | 登录状态快照（备份参考） |
-| `browser-profile/` | `claude-coder auth` | 持久化浏览器 Profile（MCP 通过 `--user-data-dir` 使用） |
+| `playwright-auth.json` | `claude-coder auth`（isolated 模式） | 浏览器 cookies + localStorage 快照 |
+| `.runtime/browser-profile/` | `claude-coder auth`（persistent 模式） | 持久化浏览器 Profile（MCP 通过 `--user-data-dir` 使用） |
 | `tests.json` | 首次测试时 | 验证记录（防止反复测试） |
-| `.runtime/` | 运行时 | 临时文件（phase、step、logs/）；工具调用记录合并到 session log |
+| `.runtime/` | 运行时 | 临时文件（logs/、browser-profile/）；工具调用记录合并到 session log |
 
 ---
 
@@ -267,7 +267,7 @@ flowchart TB
 | 5 | `docsHint` | profile.existing_docs 非空或 profile 有缺陷 | Step 4：读文档后再编码；profile 缺陷时提示 Agent 在 Step 6 补全 services/docs |
 | 6 | `taskHint` | tasks.json 存在且有待办任务 | Step 1：跳过读取 tasks.json，harness 已注入当前任务上下文 + 项目绝对路径 |
 | 6b | `testEnvHint` | 始终注入（内容因 test.env 是否存在而不同） | Step 5：存在时提示加载；不存在时告知可创建 |
-| 6c | `playwrightAuthHint` | .claude-coder/browser-profile/ 存在 | Step 5：提示 Agent MCP 使用持久化浏览器 Profile，首次需手动登录 |
+| 6c | `playwrightAuthHint` | MCP_PLAYWRIGHT=true（按 playwrightMode 动态生成） | Step 5：告知 Agent 当前 Playwright 模式（persistent/isolated/extension）及认证状态 |
 | 7 | `memoryHint` | session_result.json 存在（扁平格式） | Step 1：跳过读取 session_result.json，harness 已注入上次会话摘要 |
 | 8 | `serviceHint` | 始终注入 | Step 6：单次模式停止服务，连续模式保持服务运行 |
 | 9 | `toolGuidance` | 始终注入 | 全局：工具使用规范（Grep/Glob/Read/LS/MultiEdit/Task 替代 bash 命令），非 Claude 模型必需 |
@@ -408,8 +408,8 @@ Harness 在 `buildCodingPrompt()` 中预读 `session_result.json`，将上次会
 | `tasks.json` | Agent（仅 `status` 字段） | 修改 `status` | tracked |
 | `project_profile.json` | Agent（仅扫描阶段） | 扫描时写入 | tracked |
 | `test.env` | Agent + 用户 | 可追加写入 | .gitignore |
-| `playwright-auth.json` | 用户（`claude-coder auth`） | 快照备份 | .gitignore |
-| `browser-profile/` | 用户（`claude-coder auth`） | MCP 自动维护 | .gitignore |
+| `playwright-auth.json` | 用户（`claude-coder auth`，isolated 模式） | cookies + localStorage 快照 | .gitignore |
+| `.runtime/browser-profile/` | 用户（`claude-coder auth`，persistent 模式） | 持久化浏览器 Profile | .gitignore |
 
 ---
 

package/docs/PLAYWRIGHT_CREDENTIALS.md

@@ -1,145 +1,178 @@
-# 测试凭证持久化方案
+# Playwright MCP 浏览器模式与凭证管理
 
-## 设计思想
+## 三种模式一览
 
-claude-coder 的核心目标是让 Agent **完全自主测试**，不因凭证缺失而中断。测试中涉及三类凭证：
+| | persistent（默认推荐） | isolated | extension |
+|---|---|---|---|
+| **一句话** | **懒人模式** — 登录一次，永久生效 | **开发模式** — 验证登录流程的自动化测试 | 连接真实浏览器（实验性） |
+| **使用的浏览器** | Chrome for Testing（Playwright 自带） | Chrome for Testing（Playwright 自带） | **用户的真实 Chrome/Edge** |
+| **登录态** | 持久化，关闭后下次自动恢复 | 每次从 JSON 快照加载（auth 录制一次） | 直接复用浏览器已有登录态 |
+| **典型场景** | Google SSO、企业内网 API 文档拉取、日常维护开发 | 验证登录流程本身、需要可重复的干净测试环境 | 需要浏览器插件或绕过自动化检测 |
+| **状态存储** | `.claude-coder/.runtime/browser-profile/` | `.claude-coder/playwright-auth.json` | 无（浏览器自身管理） |
+| **前置安装** | `npx playwright install chromium` | `npx playwright install chromium` | Playwright MCP Bridge 扩展 |
+| **.mcp.json 参数** | `--user-data-dir=<path>` | `--isolated --storage-state=<path>` | `--extension` |
 
-| 类型 | 示例 | 特点 |
-|------|------|------|
-| 浏览器状态 | 登录 cookies、localStorage 中的用户配置 | 有过期时间，跨 session 需要持久化 |
-| API Key | OPENAI_API_KEY、ZHIPU_API_KEY | 长期有效，需安全存储 |
-| 测试账号 | 注册的测试用户名密码、生成的 token | 可能是 Agent 自己创建的，需跨 session 传递 |
+### 如何选择
 
-**核心原则**：
-1. **Agent 可自行发现并持久化凭证** — 测试中发现需要的 API Key 或账号，直接写入 `test.env`
-2. **凭证不受回滚影响** — `git reset --hard` 不会摧毁已保存的凭证
-3. **零手动干预** — 首次浏览器登录后，后续由持久化 profile 自动处理
+- **persistent（推荐）**：适合需要 Google 登录态、内网 API 获取等场景。登录一次，后续所有 MCP 会话自动复用。
+- **isolated**：适合需要验证登录流程的自动化测试，或需要每次干净环境的场景。cookies 过期后需重新 `auth`。
+- **extension**（实验性）：适合需要浏览器插件（VPN、广告拦截等）的场景。需安装 Chrome 扩展。
 
 ---
 
-## 持久化架构
+## 前置安装
 
-```
-.claude-coder/
-  .env                    ← 模型配置（ANTHROPIC_API_KEY 等）     [用户配置]
-  test.env                ← 测试凭证（API Key、测试账号等）      [Agent 可写]
-  playwright-auth.json    ← 浏览器登录状态（MCP 每次会话加载）   [auth 命令生成]
+### persistent / isolated 模式
+
+```bash
+# 安装 Playwright 自带的 Chromium 浏览器（Chrome for Testing）
+npx playwright install chromium
 ```
 
-### 文件生命周期
-
-| 文件 | 创建方 | 写入方 | 回滚保护 | 生命周期 |
-|------|--------|--------|----------|----------|
-| `.env` | `claude-coder setup` | 用户 | 是 | 长期 |
-| `test.env` | Agent 或用户 | Agent + 用户 | 是 | 长期，按需更新 |
-| `playwright-auth.json` | `claude-coder auth` | auth 命令 | 是 | 长期，MCP 每次会话自动加载；如需更新重新运行 auth |
-
-### 技术实现：为什么用 `--isolated --storage-state`
-
-| 维度 | `--user-data-dir`（persistent） | `--isolated --storage-state`（当前方案） |
-|------|--------------------------|--------------------------------------|
-| 上下文类型 | 持久化上下文 | 隔离上下文 |
-| localStorage | **已知 Bug #14949：`launchPersistentContext` 不注入 localStorage** | 从 JSON 可靠注入 |
-| Cookies | Profile 自动续期 | 每次从 JSON 加载（静态） |
-| 状态保持 | 跨会话自动保持 | 每次会话从 JSON 重新加载 |
-| 适用场景 | 需要 cookie 自动续期（Google OAuth） | 需要 localStorage 注入（API Key 等） |
-
-> **选择 `--isolated --storage-state` 的原因**：
-> 经实测验证，Playwright 的 `launchPersistentContext` + `storageState` 存在已知缺陷
->（Issue #14949）：localStorage 完全不注入。而 `--isolated` 模式使用 `newContext({ storageState })`，
-> localStorage 可靠注入。claude-coder 的典型场景是注入 API Key（存储在 localStorage），
-> 因此选择 `--isolated --storage-state` 作为默认方案。
->
-> 如需 cookie 持久化（Google OAuth/SSO），可手动修改 `.mcp.json` 为 `--user-data-dir` 模式，
-> 但需在 MCP 浏览器中手动登录一次。
+安装后位于 `~/Library/Caches/ms-playwright/chromium-*/`（macOS）。这不是你的真实 Chrome，是 Playwright 专用的自动化浏览器。
+
+### extension 模式
+
+1. 在真实 Chrome/Edge 中安装 [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) 扩展
+2. 确保扩展已启用
+3. 无需安装 Chromium
 
 ---
 
-## 核心流程
+## 配置流程
 
-### 流程 1：Agent 自动发现凭证
+### Step 1：选择模式
 
-```
-Agent 测试 → 发现需要 API Key → 写入 test.env → 下次 session 自动加载
+```bash
+claude-coder setup
+# → 启用 Playwright MCP → 选择模式（persistent / isolated / extension）
+# → 模式写入 .claude-coder/.env 的 MCP_PLAYWRIGHT_MODE
 ```
 
-### 流程 2：用户预配置浏览器登录态
+### Step 2：运行认证
 
-```
-用户运行 claude-coder auth url
-→ playwright codegen 打开浏览器 → 手动登录 → 关闭浏览器
-→ cookies + localStorage 保存到 playwright-auth.json
-→ 更新 .mcp.json（--isolated --storage-state 指向 playwright-auth.json）
-→ 每次 MCP 会话自动从 JSON 加载状态（无需手动登录）
-→ 如需更新状态，重新运行 claude-coder auth
+```bash
+# persistent / isolated：打开浏览器，手动登录后关闭
+claude-coder auth http://your-target-url.com
+
+# extension：不开浏览器，只生成 .mcp.json 配置
+claude-coder auth
 ```
 
-### 流程 3：用户预配置 API Key
+`auth` 命令会自动完成：
+1. 根据当前模式执行对应的认证流程
+2. 生成/更新 `.mcp.json`（Claude Code SDK 读取此文件启动 MCP 服务）
+3. 更新 `.gitignore`
+4. 启用 `.env` 中 `MCP_PLAYWRIGHT=true`
 
-```
-用户编辑 test.env → 填入 API Key → Agent 测试前 source 加载
+### Step 3：开始使用
+
+```bash
+claude-coder run "你的需求"
+# Agent 自动通过 Playwright MCP 工具操作浏览器
 ```
 
 ---
 
-## CLI 命令
+## 各模式详细说明
 
-### `claude-coder auth [url]`
+### persistent 模式（默认）
 
-配置持久化浏览器认证：
+**原理**：使用 `--user-data-dir` 创建持久化浏览器配置文件（类似 Chrome Profile）。所有 cookies、localStorage、IndexedDB、Service Worker 状态都保留在磁盘上。
 
-```bash
-# 默认打开 http://localhost:3000
-claude-coder auth
+```
+.claude-coder/.runtime/browser-profile/   ← 持久化浏览器配置（~20-50MB）
+```
+
+**优点**：
+- 登录状态完整保留，包括 Google SSO、OAuth 回调等复杂流程
+- 无需重复登录
+- cookies 自动续期
+
+**缺点**：
+- 配置目录较大
+- 不同 session 共享状态（非隔离）
 
-# 指定 URL（如内部 API 文档平台）
-claude-coder auth http://testyapi.example.com/group/2245
+### isolated 模式
+
+**原理**：使用 `--isolated --storage-state` 将 cookies + localStorage 快照注入新的隔离上下文。每次 MCP 会话从 JSON 文件重新加载。
+
+```
+.claude-coder/playwright-auth.json   ← cookies + localStorage 快照（~10-20KB）
 ```
 
-**自动完成**：
-1. 启动 `playwright codegen`，用户手动登录后关闭浏览器
-2. cookies + localStorage 保存到 `.claude-coder/playwright-auth.json`
-3. 创建/更新 `.mcp.json`，配置 `--isolated --storage-state=.claude-coder/playwright-auth.json`
-4. 添加 `.gitignore` 条目（`playwright-auth.json`）
-5. 启用 `.claude-coder/.env` 中 `MCP_PLAYWRIGHT=true`
+**优点**：
+- 每次 session 从相同状态开始，可重复性好
+- 状态文件小，可版本控制（脱敏后）
+
+**缺点**：
+- cookies 过期后需重新 `claude-coder auth`
+- Google SSO 等复杂登录可能无法完整恢复（缺少 IndexedDB/Service Worker 状态）
+
+### extension 模式
+
+**原理**：使用 `--extension` 通过 Chrome 扩展（WebSocket CDP relay）连接到用户正在运行的真实浏览器。
+
+**优点**：
+- 直接复用浏览器已有登录态，无需额外认证
+- 可使用浏览器已安装的扩展（VPN、广告拦截等）
+- 绕过自动化检测
+
+**缺点**：
+- 需要安装 [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) 扩展
+- Agent 操作会影响用户正在使用的浏览器
+- 首次连接需要用户审批（可用 Token 自动跳过）
 
 ---
 
-## 场景示例
+## 测试凭证管理
 
-### 场景 1：全栈项目首次测试
+除浏览器登录态外，Agent 还需要 API Key、测试账号等凭证：
+
+| 文件 | 创建方 | 写入方 | 用途 |
+|------|--------|--------|------|
+| `.claude-coder/.env` | `setup` | 用户 | 模型配置、MCP 开关 |
+| `.claude-coder/test.env` | Agent 或用户 | Agent + 用户 | 测试凭证（API Key、测试账号） |
 
 ```bash
-claude-coder setup
+# 用户预配置
 cat >> .claude-coder/test.env << 'EOF'
 OPENAI_API_KEY=sk-xxx
+TEST_USER=testuser@example.com
+TEST_PASSWORD=xxx
 EOF
-claude-coder auth http://localhost:3000
-claude-coder run
-# MCP 每次会话自动从 playwright-auth.json 加载 localStorage 和 cookies
 ```
 
-### 场景 2：内部系统（Google OAuth / SSO）
+Agent 在测试前会 `source .claude-coder/test.env` 加载凭证。发现新凭证需求时也会自动追加写入。
 
-```bash
-claude-coder auth http://testyapi.example.com/group/2245
-# 在弹出的浏览器中完成登录，关闭后状态保存到 JSON
-# MCP 每次会话自动加载此状态
-```
-
-> **关于 Google OAuth**：`--isolated` 模式每次创建新上下文，Google 可能要求重新验证。
-> 如需 cookie 持久化，可手动修改 `.mcp.json` 为 `--user-data-dir` 模式（但 localStorage 不会注入）。
+---
 
-### 场景 3：更新登录状态
+## 切换模式
 
 ```bash
-claude-coder auth http://localhost:3000
-# 重新登录，覆盖 playwright-auth.json
+# 推荐：一行命令切换（同时更新 .env 和 .mcp.json）
+claude-coder config mcp persistent
+claude-coder config mcp isolated
+claude-coder config mcp extension
+
+# 如果新模式需要登录（persistent / isolated），还需运行 auth
+claude-coder auth <URL>
 ```
 
-### 场景 4：清除登录状态
+> **说明**：`config mcp` 会同时更新 `.env` 中的 `MCP_PLAYWRIGHT_MODE` 和重新生成 `.mcp.json`，无需重走 `setup` 全流程。如果之前已经 auth 过对应模式（如 persistent 的 browser-profile 还在），切换回去后无需重新 auth。
+
+---
+
+## 清理
 
 ```bash
+# 清除 persistent 模式配置
+rm -rf .claude-coder/.runtime/browser-profile
+
+# 清除 isolated 模式登录状态
 rm .claude-coder/playwright-auth.json
-# 下次运行 claude-coder auth 重新配置
+
+# 完全重置 Playwright 配置
+rm .mcp.json
+# 然后重新运行 claude-coder auth
 ```

package/docs/README.en.md

@@ -60,6 +60,7 @@ Each session, the agent autonomously follows 6 steps: restore context → env ch
 | `claude-coder validate` | Manually validate last session |
 | `claude-coder status` | View progress and costs |
 | `claude-coder config sync` | Sync config to ~/.claude/ |
+| `claude-coder config mcp <mode>` | Switch Playwright mode (persistent/isolated/extension) |
 
 **Options**: `--max N` limit sessions (default 50), `--pause N` pause every N sessions (default: no pause).
 
@@ -85,10 +86,10 @@ your-project/
     progress.json           # Session history + costs
     tests.json              # Verification records
     test.env                # Test credentials (API keys, optional)
-    playwright-auth.json    # Login state snapshot (backup, via auth command)
-    browser-profile/        # Persistent browser profile (used by MCP)
+    playwright-auth.json    # Login state snapshot (isolated mode, via auth command)
     .runtime/               # Temp files
       logs/                 # Per-session logs (with tool call traces)
+      browser-profile/      # Persistent browser profile (persistent mode, via auth command)
   requirements.md           # Requirements (optional)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.5.7",
+  "version": "1.6.2",
   "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"
@@ -38,5 +38,7 @@
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": ">=0.1.0"
   },
-  "dependencies": {}
+  "optionalDependencies": {
+    "playwright": "^1.58.2"
+  }
 }

package/src/auth.js

@@ -1,9 +1,10 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { execSync } = require('child_process');
-const { paths, log, getProjectRoot, ensureLoopDir } = require('./config');
+const { paths, loadConfig, log, getProjectRoot, ensureLoopDir } = require('./config');
 
 function updateGitignore(entry) {
   const gitignorePath = path.join(getProjectRoot(), '.gitignore');
@@ -18,31 +19,35 @@ function updateGitignore(entry) {
   log('ok', `.gitignore 已添加: ${entry}`);
 }
 
-function updateMcpConfig() {
-  const p = paths();
+function updateMcpConfig(p, mode) {
   let mcpConfig = {};
   if (fs.existsSync(p.mcpConfig)) {
-    try {
-      mcpConfig = JSON.parse(fs.readFileSync(p.mcpConfig, 'utf8'));
-    } catch {
-      log('warn', '.mcp.json 解析失败，将覆盖');
-    }
+    try { mcpConfig = JSON.parse(fs.readFileSync(p.mcpConfig, 'utf8')); } catch {}
   }
 
   if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
 
-  const relAuthPath = path.relative(getProjectRoot(), p.playwrightAuth).split(path.sep).join('/');
-  mcpConfig.mcpServers.playwright = {
-    command: 'npx',
-    args: [
-      '@playwright/mcp@latest',
-      '--isolated',
-      `--storage-state=${relAuthPath}`,
-    ],
-  };
+  const args = ['@playwright/mcp@latest'];
+
+  switch (mode) {
+    case 'persistent': {
+      const relProfile = path.relative(getProjectRoot(), p.browserProfile).split(path.sep).join('/');
+      args.push(`--user-data-dir=${relProfile}`);
+      break;
+    }
+    case 'isolated': {
+      const relAuth = path.relative(getProjectRoot(), p.playwrightAuth).split(path.sep).join('/');
+      args.push('--isolated', `--storage-state=${relAuth}`);
+      break;
+    }
+    case 'extension':
+      args.push('--extension');
+      break;
+  }
 
+  mcpConfig.mcpServers.playwright = { command: 'npx', args };
   fs.writeFileSync(p.mcpConfig, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf8');
-  log('ok', `.mcp.json 已配置 Playwright MCP (isolated + storage-state: ${relAuthPath})`);
+  log('ok', `.mcp.json 已配置 Playwright MCP (${mode} 模式)`);
 }
 
 function enableMcpPlaywrightEnv() {
@@ -60,30 +65,108 @@ function enableMcpPlaywrightEnv() {
   log('ok', '.claude-coder/.env 已设置 MCP_PLAYWRIGHT=true');
 }
 
-async function auth(url) {
-  ensureLoopDir();
-  const p = paths();
-  const targetUrl = url || 'http://localhost:3000';
+// ── persistent 模式：启动持久化浏览器让用户登录 ──
+
+async function authPersistent(url, p) {
+  const profileDir = p.browserProfile;
+  if (!fs.existsSync(profileDir)) fs.mkdirSync(profileDir, { recursive: true });
+
+  const lockFile = path.join(profileDir, 'SingletonLock');
+  if (fs.existsSync(lockFile)) {
+    fs.unlinkSync(lockFile);
+    log('warn', '已清理残留的 SingletonLock（上次浏览器未正常关闭）');
+  }
+
+  console.log('操作步骤:');
+  console.log('  1. 浏览器将自动打开，请手动完成登录');
+  console.log('  2. 登录成功后关闭浏览器窗口');
+  console.log('  3. 登录状态将保存在持久化配置中');
+  console.log('  4. MCP 后续会话自动复用此登录状态');
+  console.log('');
+
+  const scriptContent = [
+    `let chromium;`,
+    `try { chromium = require('playwright').chromium; } catch {`,
+    `  try { chromium = require('@playwright/test').chromium; } catch {`,
+    `    console.error('错误: 未找到 playwright 模块');`,
+    `    console.error('请安装: npx playwright install chromium');`,
+    `    process.exit(1);`,
+    `  }`,
+    `}`,
+    `(async () => {`,
+    `  const ctx = await chromium.launchPersistentContext(${JSON.stringify(profileDir)}, { headless: false });`,
+    `  const page = ctx.pages()[0] || await ctx.newPage();`,
+    `  try { await page.goto(${JSON.stringify(url)}); } catch {}`,
+    `  console.log('请在浏览器中完成登录后关闭窗口...');`,
+    `  await new Promise(r => {`,
+    `    ctx.on('close', r);`,
+    `    const t = setInterval(() => { try { if (!ctx.pages().length) { clearInterval(t); r(); } } catch { clearInterval(t); r(); } }, 2000);`,
+    `  });`,
+    `  try { await ctx.close(); } catch {}`,
+    `})().then(() => process.exit(0)).catch(() => process.exit(0));`,
+  ].join('\n');
+
+  const tmpScript = path.join(os.tmpdir(), `pw-auth-${Date.now()}.js`);
+  fs.writeFileSync(tmpScript, scriptContent);
+
+  const helperModules = path.join(__dirname, '..', 'node_modules');
+  const existingNodePath = process.env.NODE_PATH || '';
+  const nodePath = existingNodePath ? `${helperModules}:${existingNodePath}` : helperModules;
+
+  let scriptOk = false;
+  try {
+    execSync(`node "${tmpScript}"`, {
+      stdio: 'inherit',
+      cwd: getProjectRoot(),
+      env: { ...process.env, NODE_PATH: nodePath },
+    });
+    scriptOk = true;
+  } catch {
+    // 浏览器关闭时可能返回非零退出码，只要 profile 目录有内容就认为成功
+    const profileFiles = fs.readdirSync(profileDir);
+    scriptOk = profileFiles.length > 2;
+    if (!scriptOk) {
+      log('error', 'Playwright 启动失败，且未检测到有效的浏览器配置');
+      log('info', '请确保已安装 Chromium: npx playwright install chromium');
+      try { fs.unlinkSync(tmpScript); } catch {}
+      return;
+    }
+    log('warn', '浏览器退出码非零，但已检测到有效配置，继续...');
+  }
+
+  try { fs.unlinkSync(tmpScript); } catch {}
+
+  log('ok', '登录状态已保存到持久化配置');
+  updateMcpConfig(p, 'persistent');
+  updateGitignore('.claude-coder/.runtime/browser-profile');
+  enableMcpPlaywrightEnv();
 
-  log('info', '启动 Playwright 浏览器，请手动登录...');
-  log('info', `目标 URL: ${targetUrl}`);
   console.log('');
+  log('ok', '配置完成！');
+  const relProfile = path.relative(getProjectRoot(), profileDir);
+  log('info', `MCP 使用 persistent 模式 (user-data-dir: ${relProfile})`);
+  log('info', '如需更新登录状态，重新运行 claude-coder auth');
+}
+
+// ── isolated 模式：使用 codegen 录制 storage-state ──
+
+async function authIsolated(url, p) {
   console.log('操作步骤:');
   console.log('  1. 浏览器将自动打开，请手动完成登录');
   console.log('  2. 登录成功后关闭浏览器窗口');
   console.log('  3. 登录状态（cookies + localStorage）将保存到 playwright-auth.json');
-  console.log('  4. MCP 每次会话自动加载此状态（isolated 模式）');
+  console.log('  4. MCP 每次会话自动从此文件加载初始状态');
   console.log('');
 
   try {
     execSync(
-      `npx playwright codegen --save-storage="${p.playwrightAuth}" "${targetUrl}"`,
+      `npx playwright codegen --save-storage="${p.playwrightAuth}" "${url}"`,
       { stdio: 'inherit', cwd: getProjectRoot() }
     );
   } catch (err) {
     if (!fs.existsSync(p.playwrightAuth)) {
       log('error', `Playwright 登录状态导出失败: ${err.message}`);
-      log('info', '请确保已安装 playwright: npx playwright install');
+      log('info', '请确保已安装: npx playwright install chromium');
       return;
     }
   }
@@ -94,16 +177,69 @@ async function auth(url) {
   }
 
   log('ok', '登录状态已保存到 playwright-auth.json');
-
-  updateMcpConfig();
+  updateMcpConfig(p, 'isolated');
   updateGitignore('.claude-coder/playwright-auth.json');
   enableMcpPlaywrightEnv();
 
   console.log('');
   log('ok', '配置完成！');
-  log('info', 'MCP 使用 --isolated --storage-state 模式');
-  log('info', 'localStorage 和 cookies 每次会话自动从 playwright-auth.json 加载');
+  log('info', 'MCP 使用 isolated 模式 (storage-state)');
+  log('info', 'cookies 和 localStorage 每次会话自动从 playwright-auth.json 加载');
   log('info', '如需更新登录状态，重新运行 claude-coder auth');
 }
 
-module.exports = { auth };
+// ── extension 模式：连接真实浏览器 ──
+
+function authExtension(p) {
+  console.log('Extension 模式说明:');
+  console.log('');
+  console.log('  此模式通过 Chrome 扩展连接到您正在运行的浏览器。');
+  console.log('  MCP 将直接使用浏览器中已有的登录态和扩展。');
+  console.log('');
+  console.log('  前置条件:');
+  console.log('  1. 安装 "Playwright MCP Bridge" Chrome/Edge 扩展');
+  console.log('     https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm');
+  console.log('  2. 确保浏览器已启动且扩展已启用');
+  console.log('  3. 无需额外认证操作，您的浏览器登录态将自动可用');
+  console.log('');
+
+  updateMcpConfig(p, 'extension');
+  enableMcpPlaywrightEnv();
+
+  console.log('');
+  log('ok', '配置完成！');
+  log('info', 'MCP 使用 extension 模式（连接真实浏览器）');
+  log('info', '确保 Chrome/Edge 已运行且 Playwright MCP Bridge 扩展已启用');
+}
+
+// ── 主入口 ──
+
+async function auth(url) {
+  ensureLoopDir();
+  const config = loadConfig();
+  const p = paths();
+  const mode = config.playwrightMode;
+  const targetUrl = url || 'http://localhost:3000';
+
+  log('info', `Playwright 模式: ${mode}`);
+  log('info', `目标 URL: ${targetUrl}`);
+  console.log('');
+
+  switch (mode) {
+    case 'persistent':
+      await authPersistent(targetUrl, p);
+      break;
+    case 'isolated':
+      await authIsolated(targetUrl, p);
+      break;
+    case 'extension':
+      authExtension(p);
+      break;
+    default:
+      log('error', `未知的 Playwright 模式: ${mode}`);
+      log('info', '请运行 claude-coder setup 重新配置');
+      return;
+  }
+}
+
+module.exports = { auth, updateMcpConfig };

package/src/config.js

@@ -57,6 +57,7 @@ function paths() {
     testsFile:        path.join(loopDir, 'tests.json'),
     testEnvFile:      path.join(loopDir, 'test.env'),
     playwrightAuth:   path.join(loopDir, 'playwright-auth.json'),
+    browserProfile:   path.join(runtime, 'browser-profile'),
     mcpConfig:        path.join(getProjectRoot(), '.mcp.json'),
     claudeMd:         getTemplatePath('CLAUDE.md'),
     scanProtocol:     getTemplatePath('SCAN_PROTOCOL.md'),
@@ -97,7 +98,7 @@ function loadConfig() {
     timeoutMs: parseInt(env.API_TIMEOUT_MS, 10) || 3000000,
     mcpToolTimeout: parseInt(env.MCP_TOOL_TIMEOUT, 10) || 30000,
     mcpPlaywright: env.MCP_PLAYWRIGHT === 'true',
-    debug: env.CLAUDE_DEBUG || '',
+    playwrightMode: env.MCP_PLAYWRIGHT_MODE || 'persistent',
     disableNonessential: env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC || '',
     effortLevel: env.CLAUDE_CODE_EFFORT_LEVEL || '',
     smallFastModel: env.ANTHROPIC_SMALL_FAST_MODEL || '',
@@ -190,6 +191,21 @@ function syncToGlobal() {
   log('ok', `已同步配置到 ${settingsPath}`);
 }
 
+function updateEnvVar(key, value) {
+  const p = paths();
+  if (!fs.existsSync(p.envFile)) return false;
+  let content = fs.readFileSync(p.envFile, 'utf8');
+  const regex = new RegExp(`^${key}=.*$`, 'm');
+  if (regex.test(content)) {
+    content = content.replace(regex, `${key}=${value}`);
+  } else {
+    const suffix = content.endsWith('\n') ? '' : '\n';
+    content += `${suffix}${key}=${value}\n`;
+  }
+  fs.writeFileSync(p.envFile, content, 'utf8');
+  return true;
+}
+
 module.exports = {
   COLOR,
   log,
@@ -203,4 +219,5 @@ module.exports = {
   buildEnvVars,
   getAllowedTools,
   syncToGlobal,
+  updateEnvVar,
 };

package/src/hooks.js

@@ -74,7 +74,16 @@ function createSessionHooks(indicator, logStream, options = {}) {
 
         return {};
       }]
-    }]
+    }],
+    PostToolUse: [{
+      matcher: '*',
+      hooks: [async () => {
+        indicator.updatePhase('thinking');
+        indicator.updateStep('');
+        indicator.toolTarget = '';
+        return {};
+      }]
+    }],
   };
 
   return {

package/src/indicator.js

@@ -2,7 +2,7 @@
 
 const { COLOR } = require('./config');
 
-const SPINNERS = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNERS = ['⠋', '⠙', '⠸', '⠴', '⠦', '⠇'];
 
 class Indicator {
   constructor() {
@@ -15,12 +15,14 @@ class Indicator {
     this.lastToolTime = Date.now();
     this.sessionNum = 0;
     this.startTime = Date.now();
+    this.stallTimeoutMin = 30;
   }
 
-  start(sessionNum) {
+  start(sessionNum, stallTimeoutMin) {
     this.sessionNum = sessionNum;
     this.startTime = Date.now();
-    this.timer = setInterval(() => this._render(), 500);
+    if (stallTimeoutMin > 0) this.stallTimeoutMin = stallTimeoutMin;
+    this.timer = setInterval(() => this._render(), 1000);
   }
 
   stop() {
@@ -64,7 +66,7 @@ class Indicator {
 
     let line = `${spinner} [Session ${this.sessionNum}] ${clock} ${phaseLabel} ${mm}:${ss}`;
     if (idleMin >= 2) {
-      line += ` | ${COLOR.red}${idleMin}分无工具调用${COLOR.reset}`;
+      line += ` | ${COLOR.red}${idleMin}分无工具调用（等待模型响应, ${this.stallTimeoutMin}分钟超时自动中断）${COLOR.reset}`;
     }
     if (this.step) {
       line += ` | ${this.step}`;
@@ -83,8 +85,7 @@ class Indicator {
 
   _render() {
     this.spinnerIndex++;
-    const line = this.getStatusLine();
-    process.stderr.write(`\r\x1b[K${line}`);
+    process.stderr.write(`\r\x1b[K${this.getStatusLine()}`);
   }
 }
 
@@ -107,7 +108,7 @@ function extractBashLabel(cmd) {
 function extractBashTarget(cmd) {
   let clean = cmd.replace(/^(?:cd\s+\S+\s*&&\s*)+/g, '').trim();
   clean = clean.split(/\s*(?:\|{1,2}|;|&&|2>&1|>\s*\/dev\/null)\s*/)[0].trim();
-  return clean.slice(0, 40);
+  return clean;
 }
 
 function inferPhaseStep(indicator, toolName, toolInput) {

package/src/prompts.js

@@ -98,10 +98,23 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     testEnvHint = `如需持久化测试凭证（API Key、测试账号密码等），写入 ${projectRoot}/.claude-coder/test.env（KEY=value 格式，每行一个）。后续 session 会自动感知。`;
   }
 
-  // Hint 6c: Playwright auth state
+  // Hint 6c: Playwright mode awareness
   let playwrightAuthHint = '';
-  if (fs.existsSync(p.playwrightAuth)) {
-    playwrightAuthHint = `已检测到 Playwright 登录状态（${projectRoot}/.claude-coder/playwright-auth.json），MCP 使用 --isolated --storage-state 模式，每次会话自动加载 localStorage 和 cookies。`;
+  if (config.mcpPlaywright) {
+    const mode = config.playwrightMode;
+    switch (mode) {
+      case 'persistent':
+        playwrightAuthHint = 'Playwright MCP 使用 persistent 模式（user-data-dir），浏览器登录状态持久保存在本地配置中，无需额外登录操作。';
+        break;
+      case 'isolated':
+        playwrightAuthHint = fs.existsSync(p.playwrightAuth)
+          ? `Playwright MCP 使用 isolated 模式，已检测到登录状态文件（playwright-auth.json），每次会话自动加载 cookies 和 localStorage。`
+          : 'Playwright MCP 使用 isolated 模式，但未检测到登录状态文件。如目标页面需要登录，请先运行 claude-coder auth <URL>。';
+        break;
+      case 'extension':
+        playwrightAuthHint = 'Playwright MCP 使用 extension 模式，已连接用户真实浏览器，直接复用浏览器已有的登录态和扩展。注意：操作会影响用户正在使用的浏览器。';
+        break;
+    }
   }
 
   // Hint 7: Session memory (read flat session_result.json)

package/src/session.js

@@ -135,7 +135,8 @@ async function runCodingSession(sessionNum, opts = {}) {
     editThreshold: config.editThreshold,
   });
 
-  indicator.start(sessionNum);
+  const stallTimeoutMin = Math.floor(stallTimeoutMs / 60000);
+  indicator.start(sessionNum, stallTimeoutMin);
 
   try {
     const queryOpts = buildQueryOptions(config, opts);
@@ -203,7 +204,7 @@ async function runScanSession(requirement, opts = {}) {
     stallTimeoutMs,
   });
 
-  indicator.start(0);
+  indicator.start(0, Math.floor(stallTimeoutMs / 60000));
   log('info', `正在调用 Claude Code 执行项目扫描（${projectType}项目）...`);
 
   try {
@@ -264,7 +265,7 @@ async function runAddSession(instruction, opts = {}) {
     stallTimeoutMs,
   });
 
-  indicator.start(0);
+  indicator.start(0, Math.floor(stallTimeoutMs / 60000));
   log('info', '正在追加任务...');
 
   try {

package/src/setup.js

@@ -90,7 +90,7 @@ async function setup() {
   console.log('============================================');
   console.log('');
   console.log('  第一步: 模型提供商配置');
-  console.log('  第二步: MCP 工具 + 调试输出（可选）');
+  console.log('  第二步: MCP 工具配置（可选）');
   console.log('');
 
   // Detect existing config
@@ -336,34 +336,45 @@ async function setup() {
   if (mcpChoice === 1) {
     configLines.push('MCP_PLAYWRIGHT=true');
     log('ok', 'Playwright MCP 已启用');
+
+    console.log('');
+    console.log('请选择 Playwright MCP 浏览器模式:');
+    console.log('');
+    console.log('  1) persistent - 懒人模式（默认，推荐）');
+    console.log('     登录一次永久生效，适合 Google SSO、企业内网 API 拉取等日常开发');
+    console.log('');
+    console.log('  2) isolated - 开发模式');
+    console.log('     每次会话从快照加载，适合验证登录流程的自动化测试');
+    console.log('');
+    console.log('  3) extension - 连接真实浏览器（实验性）');
+    console.log('     通过 Chrome 扩展复用已有登录态和插件');
+    console.log('     需要安装 "Playwright MCP Bridge" 扩展');
     console.log('');
-    console.log('  请确保已安装 Playwright MCP：');
-    console.log(`  ${COLOR.blue}npx @anthropic-ai/claude-code mcp add playwright -- npx @anthropic-ai/playwright-mcp${COLOR.reset}`);
-    console.log(`  ${COLOR.blue}详见: https://github.com/microsoft/playwright-mcp${COLOR.reset}`);
-  } else {
-    configLines.push('MCP_PLAYWRIGHT=false');
-    log('info', '已跳过 Playwright MCP');
-  }
 
-  // Debug output
-  console.log('');
-  console.log('是否开启 Claude 调试输出（便于排查问题，输出较多）？');
-  console.log('');
-  console.log('  1) 否 - 静默（默认，推荐）');
-  console.log('  2) 是 - verbose（完整每轮输出）');
-  console.log('  3) 是 - mcp（MCP 调用，如 Playwright Click）');
-  console.log('');
+    const modeChoice = await askChoice(rl, '选择 [1-3，默认 1]: ', 1, 3, 1);
+    const modeMap = { 1: 'persistent', 2: 'isolated', 3: 'extension' };
+    const mode = modeMap[modeChoice];
+    configLines.push(`MCP_PLAYWRIGHT_MODE=${mode}`);
 
-  const debugChoice = await askChoice(rl, '选择 [1-3，默认 1]: ', 1, 3, 1);
-  configLines.push('', '# Claude 调试（可随时修改）');
-  if (debugChoice === 2) {
-    configLines.push('CLAUDE_DEBUG=verbose');
-    log('info', '已启用 CLAUDE_DEBUG=verbose');
-  } else if (debugChoice === 3) {
-    configLines.push('CLAUDE_DEBUG=mcp');
-    log('info', '已启用 CLAUDE_DEBUG=mcp');
+    console.log('');
+    if (mode === 'extension') {
+      console.log(`  ${COLOR.yellow}⚠ 前置条件：安装 Playwright MCP Bridge 浏览器扩展${COLOR.reset}`);
+      console.log(`  ${COLOR.blue}  https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm${COLOR.reset}`);
+      console.log('');
+      console.log('  安装扩展后，运行 claude-coder auth 生成 .mcp.json 配置');
+    } else if (mode === 'persistent') {
+      console.log('  使用 claude-coder auth <URL> 打开浏览器完成首次登录');
+      console.log('  登录状态将持久保存，后续 MCP 会话自动复用');
+      console.log('');
+      console.log('  请确保已安装 Playwright:');
+      console.log(`  ${COLOR.blue}npx playwright install chromium${COLOR.reset}`);
+    } else {
+      console.log('  使用 claude-coder auth <URL> 录制登录状态到 playwright-auth.json');
+      console.log('  MCP 每次会话从此文件加载初始 cookies/localStorage');
+    }
   } else {
-    configLines.push('# CLAUDE_DEBUG=verbose  # 取消注释可开启');
+    configLines.push('MCP_PLAYWRIGHT=false');
+    log('info', '已跳过 Playwright MCP');
   }
 
   // Write config
@@ -378,6 +389,7 @@ async function setup() {
   console.log(`  配置文件: ${p.envFile}`);
   console.log('  使用方式: claude-coder run "你的需求"');
   console.log('  详细需求: 创建 requirements.md 后运行 claude-coder run');
+  console.log('  切换模式: claude-coder config mcp <persistent|isolated|extension>');
   console.log('  重新配置: claude-coder setup');
   console.log('');
 }

package/src/tasks.js

@@ -48,7 +48,11 @@ function findNextTask(data) {
       });
     })
     .sort((a, b) => (a.priority || 999) - (b.priority || 999));
-  return pending[0] || null;
+  if (pending.length > 0) return pending[0];
+
+  const inProgress = features.filter(f => f.status === 'in_progress')
+    .sort((a, b) => (a.priority || 999) - (b.priority || 999));
+  return inProgress[0] || null;
 }
 
 function setStatus(data, taskId, newStatus) {

package/src/validator.js

@@ -3,6 +3,26 @@
 const fs = require('fs');
 const { execSync } = require('child_process');
 const { paths, log, getProjectRoot } = require('./config');
+const { loadTasks, getFeatures } = require('./tasks');
+
+function tryExtractFromBroken(text) {
+  const result = {};
+  const srMatch = text.match(/"session_result"\s*:\s*"(success|failed)"/);
+  if (srMatch) result.session_result = srMatch[1];
+  const saMatch = text.match(/"status_after"\s*:\s*"(\w+)"/);
+  if (saMatch) result.status_after = saMatch[1];
+  const sbMatch = text.match(/"status_before"\s*:\s*"(\w+)"/);
+  if (sbMatch) result.status_before = sbMatch[1];
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+function inferFromTasks(taskId) {
+  if (!taskId) return null;
+  const data = loadTasks();
+  if (!data) return null;
+  const task = getFeatures(data).find(f => f.id === taskId);
+  return task ? task.status : null;
+}
 
 function validateSessionResult() {
   const p = paths();
@@ -12,12 +32,18 @@ function validateSessionResult() {
     return { valid: false, fatal: true, recoverable: false, reason: 'session_result.json 不存在' };
   }
 
+  const raw = fs.readFileSync(p.sessionResult, 'utf8');
   let data;
   try {
-    data = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
+    data = JSON.parse(raw);
   } catch (err) {
-    log('error', `session_result.json 解析失败: ${err.message}`);
-    return { valid: false, fatal: true, recoverable: false, reason: `JSON 解析失败: ${err.message}` };
+    log('warn', `session_result.json 解析失败: ${err.message}`);
+    const extracted = tryExtractFromBroken(raw);
+    if (extracted) {
+      log('info', `从截断 JSON 中提取到关键字段: ${JSON.stringify(extracted)}`);
+      return { valid: false, fatal: false, recoverable: true, reason: 'JSON 截断但提取到关键字段', data: extracted };
+    }
+    return { valid: false, fatal: false, recoverable: true, reason: `JSON 解析失败: ${err.message}` };
   }
 
   // Backward compat: unwrap legacy { current: {...} } format
@@ -33,14 +59,14 @@ function validateSessionResult() {
   }
 
   if (!['success', 'failed'].includes(data.session_result)) {
-    log('error', `session_result 必须是 success 或 failed，实际是: ${data.session_result}`);
-    return { valid: false, fatal: true, recoverable: false, reason: `无效 session_result: ${data.session_result}` };
+    log('warn', `session_result 必须是 success 或 failed，实际是: ${data.session_result}`);
+    return { valid: false, fatal: false, recoverable: true, reason: `无效 session_result: ${data.session_result}`, data };
   }
 
   const validStatuses = ['pending', 'in_progress', 'testing', 'done', 'failed'];
   if (!validStatuses.includes(data.status_after)) {
-    log('error', `status_after 不合法: ${data.status_after}`);
-    return { valid: false, fatal: true, recoverable: false, reason: `无效 status_after: ${data.status_after}` };
+    log('warn', `status_after 不合法: ${data.status_after}`);
+    return { valid: false, fatal: false, recoverable: true, reason: `无效 status_after: ${data.status_after}`, data };
   }
 
   if (data.session_result === 'success') {
@@ -79,25 +105,22 @@ function checkGitProgress(headBefore) {
   return { hasCommit: true, warning: false };
 }
 
-function checkTestCoverage(taskId) {
+function checkTestCoverage(taskId, statusAfter) {
   const p = paths();
 
-  if (!fs.existsSync(p.testsFile) || !fs.existsSync(p.sessionResult)) return;
+  if (!fs.existsSync(p.testsFile)) return;
+  if (statusAfter !== 'done' || !taskId) return;
 
   try {
-    const sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
     const tests = JSON.parse(fs.readFileSync(p.testsFile, 'utf8'));
     const testCases = tests.test_cases || [];
-
-    if (sr.status_after === 'done' && taskId) {
-      const taskTests = testCases.filter(t => t.feature_id === taskId);
-      if (taskTests.length > 0) {
-        const failed = taskTests.filter(t => t.last_result === 'fail');
-        if (failed.length > 0) {
-          log('warn', `tests.json 中有失败的验证记录: ${failed.map(t => t.id).join(', ')}`);
-        } else {
-          log('ok', `${taskTests.length} 条验证记录覆盖任务 ${taskId}`);
-        }
+    const taskTests = testCases.filter(t => t.feature_id === taskId);
+    if (taskTests.length > 0) {
+      const failed = taskTests.filter(t => t.last_result === 'fail');
+      if (failed.length > 0) {
+        log('warn', `tests.json 中有失败的验证记录: ${failed.map(t => t.id).join(', ')}`);
+      } else {
+        log('ok', `${taskTests.length} 条验证记录覆盖任务 ${taskId}`);
       }
     }
   } catch { /* ignore */ }
@@ -106,21 +129,32 @@ function checkTestCoverage(taskId) {
 async function validate(headBefore, taskId) {
   log('info', '========== 开始校验 ==========');
 
-  let srResult = validateSessionResult();
+  const srResult = validateSessionResult();
   const gitResult = checkGitProgress(headBefore);
 
-  // Tiered: has commit + session_result issue → warn, don't rollback good code
-  if (srResult.recoverable && gitResult.hasCommit) {
-    log('warn', 'session_result.json 格式异常，但有新提交，降级为警告（不回滚代码）');
-  } else if (srResult.recoverable && !gitResult.hasCommit) {
-    log('error', '无新提交且 session_result.json 格式错误，视为致命');
-    srResult.fatal = true;
-  }
+  let fatal = false;
+  let hasWarnings = false;
 
-  checkTestCoverage(taskId);
+  if (srResult.valid) {
+    hasWarnings = gitResult.warning;
+  } else {
+    // session_result.json has issues — cross-validate with git + tasks.json
+    if (gitResult.hasCommit) {
+      const taskStatus = inferFromTasks(taskId);
+      if (taskStatus === 'done' || taskStatus === 'testing') {
+        log('warn', `session_result.json 异常，但 tasks.json 显示 ${taskId} 已 ${taskStatus}，且有新提交，降级为警告`);
+      } else {
+        log('warn', 'session_result.json 异常，但有新提交，降级为警告（不回滚代码）');
+      }
+      hasWarnings = true;
+    } else {
+      log('error', '无新提交且 session_result.json 异常，视为致命');
+      fatal = true;
+    }
+  }
 
-  const fatal = srResult.fatal;
-  const hasWarnings = gitResult.warning || srResult.recoverable;
+  const statusAfter = srResult.data?.status_after || inferFromTasks(taskId) || null;
+  checkTestCoverage(taskId, statusAfter);
 
   if (fatal) {
     log('error', '========== 校验失败 (致命) ==========');

package/templates/CLAUDE.md

@@ -51,7 +51,8 @@
 | `.claude-coder/session_result.json` | 本次会话的结构化输出 | 每次会话结束时覆盖写入 |
 | `.claude-coder/tests.json` | 功能验证记录（轻量） | 可新增和更新；仅当功能涉及 API 或核心逻辑时记录 |
 | `.claude-coder/test.env` | 测试凭证（API Key、测试账号等） | **可追加写入**；发现测试需要的凭证时持久化到此文件 |
-| `.claude-coder/playwright-auth.json` | 浏览器登录状态（cookies + localStorage） | 只读；由 `claude-coder auth` 生成，MCP 每次会话自动加载 |
+| `.claude-coder/playwright-auth.json` | 浏览器登录状态快照（isolated 模式时由 `claude-coder auth` 生成） | 只读；persistent/extension 模式下此文件不存在 |
+| `.mcp.json` | MCP 服务配置（由 `claude-coder auth` 自动生成） | **只读，绝对不得修改** |
 
 ### requirements.md 处理原则
 

package/templates/test_rule.md

@@ -110,9 +110,10 @@ P0（核心流程）必测 → P1（错误处理）必测 → P2（次要功能
 
 ## 六、凭证管理
 
-`.mcp.json` 配置 `--isolated --storage-state=path/to/auth.json`。
-
-**关键**: `--storage-state` **必须**配合 `--isolated`，否则 localStorage 不注入。
+`.mcp.json` 由 `claude-coder auth` 自动生成，根据配置模式使用不同参数：
+- persistent（默认）：`--user-data-dir=<path>`，登录态自动保持
+- isolated：`--isolated --storage-state=<path>`，每次从快照加载
+- extension：`--extension`，连接真实浏览器
 
 凭证失效时：不修改 auth 文件，报告中标注，提示用户运行 `claude-coder auth [URL]`。