claude-coder 1.5.6 → 1.6.2

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,18 +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}` };
-  }
-
-  if (!data.task_id) {
-    log('warn', 'session_result.json 缺少 task_id (建议包含)');
+    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') {
@@ -83,50 +105,56 @@ function checkGitProgress(headBefore) {
   return { hasCommit: true, warning: false };
 }
 
-function checkTestCoverage() {
+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 taskId = sr.task_id || '';
     const testCases = tests.test_cases || [];
-
-    if (sr.status_after === 'done' && sr.tests_passed) {
-      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 */ }
 }
 
-async function validate(headBefore) {
+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();
+  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,8 +51,8 @@
 | `.claude-coder/session_result.json` | 本次会话的结构化输出 | 每次会话结束时覆盖写入 |
 | `.claude-coder/tests.json` | 功能验证记录（轻量） | 可新增和更新；仅当功能涉及 API 或核心逻辑时记录 |
 | `.claude-coder/test.env` | 测试凭证（API Key、测试账号等） | **可追加写入**；发现测试需要的凭证时持久化到此文件 |
-| `.claude-coder/playwright-auth.json` | 登录状态快照（备份参考） | 只读；由 `claude-coder auth` 生成 |
-| `.claude-coder/browser-profile/` | 持久化浏览器 Profile | MCP 自动维护；首次需手动登录，之后永久保持 |
+| `.claude-coder/playwright-auth.json` | 浏览器登录状态快照（isolated 模式时由 `claude-coder auth` 生成） | 只读；persistent/extension 模式下此文件不存在 |
+| `.mcp.json` | MCP 服务配置（由 `claude-coder auth` 自动生成） | **只读，绝对不得修改** |
 
 ### requirements.md 处理原则
 
@@ -98,12 +98,9 @@
 ```json
 {
   "session_result": "success | failed",
-  "task_id": "feat-xxx",
   "status_before": "pending | failed",
   "status_after": "done | failed | in_progress | testing",
-  "git_commit": "abc1234 或 null",
-  "tests_passed": true | false,
-  "notes": "本次会话的简要说明"
+  "notes": "本次做了什么 + 遇到的问题 + 给下一个会话的提醒"
 }
 ```
 
@@ -138,38 +135,17 @@
 
 ## 任务状态机（严格遵守）
 
-每个任务在 `tasks.json` 中有一个 `status` 字段，合法状态和迁移规则如下：
+每个任务在 `tasks.json` 中有一个 `status` 字段，合法迁移路径如下：
 
-```
-pending ──→ in_progress ──→ testing ──→ done
-                              │
-                              ▼
-                           failed ──→ in_progress（重试）
-```
-
-### 状态说明
-
-| 状态 | 含义 | 何时设置 |
+| 当前状态 | 可迁移至 | 触发条件 |
 |---|---|---|
-| `pending` | 未开始 | 初始状态 |
-| `in_progress` | 正在实现 | 你开始编码时 |
-| `testing` | 代码已写完，正在测试 | 代码完成、开始验证时 |
-| `done` | 测试通过，功能完成 | 端到端测试通过后 |
-| `failed` | 测试失败或实现有问题 | 测试未通过时 |
-
-### 迁移规则（铁律）
-
-- `pending` → `in_progress`：开始工作
-- `in_progress` → `testing`：代码写完，开始验证
-- `testing` → `done`：所有测试通过
-- `testing` → `failed`：测试未通过
-- `failed` → `in_progress`：重试修复
-
-**禁止的迁移**：
-- `pending` → `done`（不允许跳步）
-- `pending` → `testing`（必须先写代码）
-- `in_progress` → `done`（必须先测试）
-- 任何状态 → `pending`（不允许回退到未开始）
+| `pending` | `in_progress` | 开始编码 |
+| `in_progress` | `testing` | 代码写完，开始验证 |
+| `testing` | `done` | 所有测试通过 |
+| `testing` | `failed` | 测试未通过 |
+| `failed` | `in_progress` | 重试修复 |
+
+**禁止**：跳步（如 `pending` → `done`）、回退到 `pending`、未测试直接 `done`
 
 ---
 
@@ -248,18 +224,15 @@ pending ──→ in_progress ──→ testing ──→ done
 1. **后台服务管理**：根据 prompt 提示决定——单次模式（`--max 1`）时停止所有后台服务（`lsof -ti :端口 | xargs kill`）；连续模式时保持服务运行，下个 session 继续使用
 2. **按需更新文档和 profile**：
    - **README / 用户文档**：仅当对外行为变化（新增功能、API 变更、使用方式变化）时更新
-   - **架构 / API 文档**：如果本次新增了模块、改变了模块职责或新增了 API 端点，更新 `existing_docs` 中对应的架构或 API 文档。同时更新 `project_profile.json` 的 `existing_docs` 列表（若新增了文档文件）
+   - **项目指令文件**：如果本次新增了模块、改变了模块职责或新增了 API 端点，更新 `.claude/CLAUDE.md`。同时确保 `project_profile.json` 的 `existing_docs` 列表包含此文件
    - **profile 补全**：如果 prompt 中提示 `project_profile.json` 有缺陷（如 services 为空、existing_docs 为空），在此步骤补全。Harness 依赖 profile 做环境初始化和上下文注入
 3. **Git 提交**：`git add -A && git commit -m "feat(task-id): 功能描述"`
 4. **写入 session_result.json**（notes 要充分记录上下文供下次恢复）：
    ```json
    {
      "session_result": "success 或 failed",
-     "task_id": "当前任务 ID",
      "status_before": "任务开始时的状态",
      "status_after": "任务结束时的状态",
-     "git_commit": "本次提交的 hash",
-     "tests_passed": true 或 false,
      "notes": "本次做了什么 + 遇到的问题 + 给下一个会话的提醒"
    }
    ```

package/templates/SCAN_PROTOCOL.md

@@ -20,8 +20,8 @@
 
 **文档标准（按优先级）**：
 1. **README.md**（必须有）：项目简介、技术栈、目录结构、如何运行。若缺失或过于简略，先补充
-2. **架构文档**（推荐有）：如果 `docs/` 中没有架构概述，生成一份简要的架构文档（如 `docs/ARCHITECTURE.md`），包含：模块职责、核心数据流、关键 API 路由。格式用结构化标题，方便 AI 快速检索
-3. **API 文档**：如果项目有 API 且无文档，在 docs/ 或 README 中补充主要端点列表
+2. **`.claude/CLAUDE.md`**（推荐有）：检查 `.claude/` 目录下是否已有 `CLAUDE.md`。若无，生成一份项目指令文件，采用 WHAT/WHY/HOW 格式：WHAT（项目是什么、技术栈）、WHY（关键技术决策）、HOW（开发命令、测试命令、关键路径表、编码规则）。此文件会被 Claude Code 自动加载为项目上下文
+3. **API 文档**：如果项目有 API 且无文档，在 `.claude/CLAUDE.md` 的 HOW 部分或 README 中补充主要端点列表
 
 按顺序检查以下文件，**存在则读取**，不存在则跳过：
 
@@ -42,7 +42,7 @@
 2. 根据需求（`requirements.md` 或 harness 传入的需求文本），设计技术架构
 3. 创建项目目录结构和基础文件（入口文件、配置文件、依赖文件等）
 4. 生成 `README.md`（项目用途、技术栈、如何运行）
-5. 如果项目包含 2 个以上模块或前后端分离，生成简要架构文档 `docs/ARCHITECTURE.md`（模块职责、数据流、API 路由）
+5. 如果 `.claude/CLAUDE.md` 不存在，生成项目指令文件（WHAT/WHY/HOW 格式），包含模块职责、数据流、API 路由、开发和测试命令
 6. 初始化包管理（`npm init` / `pip freeze` 等）
 7. 完成后，执行**步骤 2A 的扫描流程**生成 `project_profile.json`
 
@@ -100,7 +100,7 @@
     "python_env": "conda:env_name | venv | system",
     "node_version": "20 | 18 | none"
   },
-  "existing_docs": ["README.md", "docs/api.md"],
+  "existing_docs": ["README.md", ".claude/CLAUDE.md"],
   "has_tests": false,
   "has_docker": false,
   "mcp_tools": {

package/templates/test_rule.md

@@ -0,0 +1,158 @@
+# Playwright 自动化测试通用规则 v0.0.1
+
+## 一、四条铁律
+
+1. **真实操作** — 必须通过 Playwright MCP 产生浏览器交互，代码审查不等于测试
+2. **测试业务** — 断言基于用户可见结果（页面文本、按钮状态），非内部变量
+3. **独立可重复** — 每个场景不依赖其他测试结果
+4. **先调查再修复** — 失败先分析根因，不要修改测试让它通过
+
+## 二、三步测试方法论
+
+任何 Web 项目的端到端测试遵循三步走：
+
+### Step 1: 功能验证（Happy Path）
+
+核心用户流程能走通，每个步骤对应一个 Playwright MCP 工具调用：
+
+```
+1. browser_navigate → [页面URL]
+2. browser_snapshot → 确认页面加载，定位关键元素 ref
+3. browser_fill_form / browser_type → 输入测试数据
+4. browser_click → 提交操作
+5. browser_wait_for → 等待结果出现
+6. browser_snapshot → 验证预期结果
+```
+
+### Step 2: 错误场景（Unhappy Path）
+
+| 类别 | 典型场景 |
+|------|---------|
+| 输入验证 | 空提交、超长输入、特殊字符、非法格式 |
+| 认证权限 | 未登录访问、过期凭证、无效 API Key |
+| 网络服务 | 后端宕机、慢响应、API 500 |
+| 状态边界 | 空数据、大数据量、重复提交、浏览器后退 |
+
+### Step 3: 探索性测试
+
+以目标用户角色自由使用系统，关注可发现性、可理解性、响应速度、错误恢复、视觉一致性。
+
+## 三、Playwright MCP 工具速查
+
+### 导航与观察
+
+| 工具 | 用途 | 关键参数 |
+|------|------|---------|
+| `browser_navigate` | 打开页面 | `url` |
+| `browser_snapshot` | 获取页面可访问性快照 | 无 |
+| `browser_console_messages` | 检查控制台 | `level` |
+| `browser_network_requests` | 网络请求日志 | 无 |
+
+### 交互操作
+
+| 工具 | 用途 | 关键参数 |
+|------|------|---------|
+| `browser_click` | 点击元素 | `ref`, `element` |
+| `browser_type` | 逐字符输入 | `ref`, `text`, `submit` |
+| `browser_fill_form` | 批量填写表单 | `fields[]` |
+| `browser_select_option` | 选择下拉项 | `ref`, `values[]` |
+| `browser_press_key` | 按键 | `key` |
+| `browser_file_upload` | 上传文件 | `paths[]` |
+| `browser_handle_dialog` | 处理弹窗 | `accept` |
+
+### 等待与控制
+
+| 工具 | 用途 | 关键参数 |
+|------|------|---------|
+| `browser_wait_for` | 等待元素/文本出现 | `text`, `ref`, `timeout` |
+| `browser_evaluate` | 执行 JS | `function` |
+| `browser_close` | 关闭页面 | 无 |
+
+## 四、Smart Snapshot 策略（节省 40-60% Token）
+
+每次 `browser_snapshot` 消耗 3,000-8,000 tokens。分级控制：
+
+| 级别 | 何时 snapshot | 示例 |
+|------|-------------|------|
+| **必须** | 首次加载页面 | navigate 后确认页面正确 |
+| **必须** | 关键断言点 | 验证操作结果出现 |
+| **必须** | 操作失败时 | 调查页面状态 |
+| **可选** | 中间操作后 | fill 后确认文字填入 |
+| **跳过** | 连续同类操作间 | 连续选择多个下拉框 |
+| **跳过** | 等待循环中 | 改用 `browser_wait_for` |
+
+**高效模式**：navigate → snapshot → fill → select → click → wait_for → snapshot（**2 次**）
+**低效模式**：navigate → snapshot → fill → snapshot → select → snapshot → click → snapshot（**4 次**）
+
+## 五、等待策略
+
+### 按操作类型选择
+
+| 操作类型 | 策略 | Token 消耗 |
+|---------|------|-----------|
+| 瞬时（导航、点击） | 直接操作，不等待 | 极低 |
+| 短等（表单提交） | `browser_wait_for text="成功" timeout=10000` | ~5K |
+| 长等（AI 生成、文件处理） | 指数退避轮询 | ~20K |
+| 超长等（批量处理） | Shell 端 API 检查 + 最终 1 次 snapshot | ~5.5K |
+
+### 指数退避轮询模式（长操作）
+
+- 每步 snapshot → 合并 2-3 操作后再 snapshot
+- MCP 做 20+ 步 → 长流程用 Playwright CLI
+- 反复 navigate 同一页面 → 在同一页面完成
+- 失败后盲目重试 → 先 `browser_console_messages` 分析
+
+### 优先级映射
+
+P0（核心流程）必测 → P1（错误处理）必测 → P2（次要功能）按需 → P3 低优先
+
+预算 >200K: P0+P1+P2 | 100-200K: P0+P1 | <100K: 仅 P0
+
+## 六、凭证管理
+
+`.mcp.json` 由 `claude-coder auth` 自动生成，根据配置模式使用不同参数：
+- persistent（默认）：`--user-data-dir=<path>`，登录态自动保持
+- isolated：`--isolated --storage-state=<path>`，每次从快照加载
+- extension：`--extension`，连接真实浏览器
+
+凭证失效时：不修改 auth 文件，报告中标注，提示用户运行 `claude-coder auth [URL]`。
+
+## 七、失败处理
+
+**阻断性**（立即停止）: 服务未启动、500 错误、凭证缺失、页面空白
+
+**非阻断性**（记录继续）: 样式异常、console warning、慢响应
+
+失败时: snapshot（记录状态）→ console_messages（错误日志）→ 停止该场景 → 继续下一个
+
+## 八、tasks.json 测试步骤模板
+
+```json
+{
+  "steps": [
+    "【规则】阅读 .claude-coder/test_rule.md",
+    "【环境】curl [后端]/health && curl [前端]（失败则停止）",
+    "【P0】Playwright MCP 执行核心 Happy Path（Smart Snapshot）",
+    "【P1】错误场景：空输入、无效凭证",
+    "【记录】结果写入 record/",
+    "【预算】消耗 >80% 时跳过低优先级，记录 session_result.json"
+  ]
+}
+```
+
+## 九、测试报告格式
+
+```markdown
+# E2E 测试报告
+**日期**: YYYY-MM-DD | **环境**: 前端 [URL] / 后端 [URL]
+
+| 场景 | 结果 | 备注 |
+|------|------|------|
+| [名称] | PASS/FAIL | [简要] |
+
+## 发现的问题
+### [P0/P1/P2] 标题
+- **复现**: [Playwright 动作序列]
+- **预期/实际**: ...
+- **根因**: [代码分析]
+```