claude-coder 1.2.0 → 1.5.0

package/README.md

@@ -53,9 +53,10 @@ claude-coder run "实现用户注册和登录功能"
 | `claude-coder run --max 1` | 单次执行 |
 | `claude-coder run --dry-run` | 预览模式 |
 | `claude-coder init` | 初始化项目环境 |
-| `claude-coder add "指令"` | 追加任务（默认用 opus 级模型推理） |
+| `claude-coder add "指令"` | 追加任务 |
 | `claude-coder add -r [file]` | 从需求文件追加任务 |
 | `claude-coder add "..." --model M` | 指定模型追加任务 |
+| `claude-coder auth [url]` | 导出 Playwright 登录状态 |
 | `claude-coder validate` | 手动校验 |
 | `claude-coder status` | 查看进度和成本 |
 | `claude-coder config sync` | 同步配置到 ~/.claude/ |
@@ -72,6 +73,8 @@ claude-coder run "实现用户注册和登录功能"
 
 **追加任务**：`claude-coder add "新增管理员后台"` 或 `claude-coder add -r requirements.md` — 仅追加到任务列表，下次 run 时执行。
 
+**自动测试 + 凭证持久化**：`claude-coder auth http://localhost:3000` — 导出浏览器登录态（cookies + localStorage），Agent 测试时自动使用。缺 API Key 时 Agent 会自行记录到 `test.env` 并继续推进，不会停工。详见 [测试凭证持久化方案](docs/PLAYWRIGHT_CREDENTIALS.md)。
+
 ## 模型支持
 
 | 提供商 | 说明 |
@@ -94,7 +97,9 @@ your-project/
     progress.json           # 会话历史 + 成本
     tests.json              # 验证记录
     test.env                # 测试凭证（API Key 等，可选）
-    .runtime/               # 临时文件（含日志）
+    playwright-auth.json    # Playwright 登录状态（可选，auth 命令生成）
+    .runtime/               # 临时文件
+      logs/                 # 每 session 独立日志 + activity log
   requirements.md           # 需求文档（可选）
 ```
 
@@ -104,14 +109,16 @@ your-project/
 
 **中断恢复**：直接重新运行 `claude-coder run`，会从上次中断处继续。
 
+**长时间无响应**：模型处理复杂文件时可能出现 10-20 分钟的思考间隔（spinner 会显示红色警告），这是正常行为。超过 30 分钟无工具调用时 Harness 会自动中断并重试。可通过 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 调整阈值。
+
 **跳过任务**：将 `.claude-coder/tasks.json` 中该任务的 `status` 改为 `done`。
 
 **Windows 支持**：完全支持，纯 Node.js 实现。
 
 ## 文档
 
-- [技术架构](docs/ARCHITECTURE.md) — 模块职责、提示语注入架构、注意力机制、Hook 数据流、后续优化方向
-- [Playwright 凭证持久化](docs/PLAYWRIGHT_CREDENTIALS.md) — 测试 cookies 和 API Key 管理方案
+- [技术架构](docs/ARCHITECTURE.md) — 核心设计规则、模块职责、提示语注入架构、注意力机制、Hook 数据流
+- [测试凭证持久化方案](docs/PLAYWRIGHT_CREDENTIALS.md) — 自动测试的凭证管理：Playwright 登录态导出、API Key 持久化、Agent 缺凭证时的行为策略
 
 ## License
 

package/bin/cli.js

@@ -8,6 +8,7 @@ const COMMANDS = {
   setup:    { desc: '交互式模型配置',           usage: 'claude-coder setup' },
   init:     { desc: '初始化项目环境',           usage: 'claude-coder init' },
   add:      { desc: '追加任务到 tasks.json',    usage: 'claude-coder add "指令" [--model M] | add -r [file]' },
+  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' },
@@ -29,6 +30,8 @@ function showHelp() {
   console.log('  claude-coder add "新增搜索功能"       追加任务');
   console.log('  claude-coder add -r                   从 requirements.md 追加任务');
   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 status                  查看进度和成本');
   console.log(`\n前置条件: npm install -g @anthropic-ai/claude-agent-sdk`);
 }
@@ -109,14 +112,16 @@ async function main() {
       break;
     }
     case 'add': {
+      const fs = require('fs');
+      const nodePath = require('path');
       let instruction = positional[0] || '';
       if (opts.readFile) {
-        const reqPath = require('path').resolve(opts.readFile);
-        if (!require('fs').existsSync(reqPath)) {
+        const reqPath = nodePath.resolve(opts.readFile);
+        if (!fs.existsSync(reqPath)) {
           console.error(`文件不存在: ${reqPath}`);
           process.exit(1);
         }
-        instruction = require('fs').readFileSync(reqPath, 'utf8');
+        instruction = fs.readFileSync(reqPath, 'utf8');
         console.log(`已读取需求文件: ${opts.readFile}`);
       }
       if (!instruction) {
@@ -127,6 +132,11 @@ async function main() {
       await runner.add(instruction, opts);
       break;
     }
+    case 'auth': {
+      const { auth } = require('../src/auth');
+      await auth(positional[0] || null);
+      break;
+    }
     case 'validate': {
       const validator = require('../src/validator');
       const result = await validator.validate();

package/docs/ARCHITECTURE.md

@@ -10,6 +10,67 @@
 
 ---
 
+## 0. 核心设计规则（MUST READ）
+
+> 以下规则按重要性排序（注意力 primacy zone），所有代码修改和架构决策必须遵循。
+
+### 规则 1：长 Session 不停工
+
+Agent 在单次 session 中应最大化推进任务进度。**任何非致命问题都不应中断 session**。
+
+- 缺少 API Key → 用 mock 或代码逻辑验证替代，记录到 `test.env`，继续推进
+- 测试环境未就绪 → 跳过该测试步骤，完成其余可验证的步骤
+- 服务启动失败 → 尝试排查修复，无法修复则记录问题后推进代码实现
+- **长时间思考是正常行为**：模型处理大文件（如 500+ 行的代码文件）时可能出现 10-20 分钟的思考间隔，不代表卡死
+
+**反面案例**：Agent 因 `OPENAI_API_KEY` 缺失直接标记任务 `failed` → 浪费整个 session
+
+> Harness 兜底机制：当工具调用间隔超过 `SESSION_STALL_TIMEOUT`（默认 30 分钟）时自动中断 session 并触发 rollback + 重试。此阈值设计为远超正常思考时长，仅捕捉真正的卡死场景。
+
+### 规则 2：回滚即彻底回滚
+
+`git reset --hard` 是全量回滚，不做部分文件保护。
+
+- 凭证文件（`test.env`、`playwright-auth.json`）应通过 `.gitignore` 排除在 git 之外
+- 如果回滚发生，说明 session 确实失败，代码应全部还原
+- 不需要 backup/restore 机制 — 这是过度设计
+
+### 规则 3：分层校验（fatal / recoverable / pass）
+
+不是所有校验失败都需要回滚：
+
+| 情况 | 有新 commit | 处理 |
+|------|------------|------|
+| session_result.json 格式异常 | 是 | **warn** — 代码已提交且可能正确，不回滚 |
+| session_result.json 格式异常 | 否 | **fatal** — 无进展，回滚 |
+| 代码结构性错误 | — | **fatal** — 回滚 |
+| 全部通过 | — | **pass** — 推送 |
+
+### 规则 4：凭证与代码分离
+
+| 文件 | git 状态 | 说明 |
+|------|---------|------|
+| `test.env` | .gitignore | Agent 可写入发现的 API Key、测试账号 |
+| `playwright-auth.json` | .gitignore | 用户通过 `claude-coder auth` 生成 |
+| `session_result.json` | git-tracked | Agent 每次 session 覆盖写入 |
+| `tasks.json` | git-tracked | Agent 修改 status 字段 |
+
+### 规则 5：Harness 准备上下文，Agent 直接执行
+
+Agent 不应浪费工具调用读取 harness 已知的数据。所有可预读的上下文通过 prompt hint 注入（见第 5 节 Prompt 注入架构）。
+
+### 规则 6：停顿检测 — 模型卡死自动恢复
+
+模型可能长时间「思考」但不调用工具（20+ 分钟无进展）。Harness 通过 PreToolUse hook 追踪最后一次工具调用时间：
+
+- 无工具调用 > `SESSION_STALL_TIMEOUT`（默认 1800 秒 / 30 分钟） → 自动中断 session
+- 中断后进入 runner 的重试逻辑（连续失败 ≥ 3 次 → 标记 task failed）
+- Spinner 在无工具调用 > 2 分钟时显示红色警告
+
+配置方式：`.claude-coder/.env` 中设置 `SESSION_STALL_TIMEOUT=1800`（秒）
+
+---
+
 ## 1. 核心架构
 
 ```mermaid
@@ -31,7 +92,7 @@ flowchart TB
         direction TB
         profile["project_profile.json<br/>tasks.json"]
         runtime["session_result.json<br/>progress.json"]
-        phase[".runtime/<br/>phase / step / activity.log"]
+        phase[".runtime/<br/>phase / step / logs/"]
     end
 
     scan -->|"systemPrompt =<br/>CLAUDE.md + SCAN_PROTOCOL.md"| query
@@ -42,13 +103,14 @@ flowchart TB
 
     query -->|Agent 工具调用| Files
     validate -->|读取| runtime
-    validate -->|"pass → 下一 session<br/>fail → rollback"| coding
+    validate -->|"pass → 下一 session<br/>fatal → rollback<br/>recoverable + commit → warn"| coding
 ```
 
 **核心特征：**
 - **项目无关**：项目信息由 Agent 扫描后存入 `project_profile.json`，harness 不含项目特定逻辑
 - **可恢复**：通过 `session_result.json` 跨会话记忆，任意 session 可断点续跑
-- **可观测**：SDK 内联 `PreToolUse` hook 实时显示 Agent 当前步骤和工具调用
+- **可观测**：SDK 内联 `PreToolUse` hook 实时显示当前工具、操作目标和停顿警告
+- **自愈**：编辑死循环检测 + 停顿超时自动中断 + runner 重试机制
 - **跨平台**：纯 Node.js 实现，macOS / Linux / Windows 通用
 - **零依赖**：`dependencies` 为空，Claude Agent SDK 作为 peerDependency
 
@@ -80,7 +142,7 @@ flowchart LR
     pause_check -->|继续| session
     done_check -->|是| finish([完成])
 
-    val -->|fail| rollback["git reset --hard"]
+    val -->|fatal| rollback["git reset --hard"]
     rollback --> retry_check{连续失败<br/>≥3次?}
     retry_check -->|否| session
     retry_check -->|是| mark_failed["标记 task failed"]
@@ -96,13 +158,14 @@ bin/cli.js          CLI 入口：参数解析、命令路由、SDK peerDep 检
 src/
   config.js         配置管理：.env 加载、模型映射、环境变量构建、全局同步
   runner.js         主循环：scan → session → validate → retry/rollback
-  session.js        SDK 交互：query() 调用、hook 绑定、日志流
+  session.js        SDK 交互：query() 调用、hook 绑定、停顿检测、日志流
   prompts.js        提示语构建：系统 prompt 组合 + 条件 hint + 任务分解指导
   init.js           环境初始化：读取 profile 执行依赖安装、服务启动、健康检查
   scanner.js        初始化扫描：调用 runScanSession + 重试
-  validator.js      校验引擎：session_result 结构校验 + git 检查 + 测试覆盖
+  validator.js      校验引擎：分层校验（fatal/recoverable/pass）+ git 检查 + 测试覆盖
   tasks.js          任务管理：CRUD + 状态机 + 进度展示
-  indicator.js      进度指示：终端 spinner + phase/step 文件写入
+  auth.js           Playwright 凭证：导出登录状态 + MCP 配置 + gitignore
+  indicator.js      进度指示：终端 spinner + 工具目标显示 + 停顿警告 + phase/step 文件写入
   setup.js          交互式配置：模型选择、API Key、MCP 工具
 templates/
   CLAUDE.md         Agent 协议（注入为 systemPrompt）
@@ -125,8 +188,9 @@ templates/
 | `src/prompts.js` | 提示语构建（系统 prompt + 条件 hint + 任务分解指导） |
 | `src/init.js` | 环境初始化（依赖安装、服务启动） |
 | `src/scanner.js` | 项目初始化扫描 |
-| `src/validator.js` | 校验引擎 |
+| `src/validator.js` | 校验引擎（分层校验） |
 | `src/tasks.js` | 任务 CRUD + 状态机 |
+| `src/auth.js` | Playwright 凭证持久化 |
 | `src/indicator.js` | 终端进度指示器 |
 | `src/setup.js` | 交互式配置向导 |
 | `templates/CLAUDE.md` | Agent 协议 |
@@ -140,9 +204,10 @@ templates/
 | `project_profile.json` | 首次扫描 | 项目元数据 |
 | `tasks.json` | 首次扫描 | 任务列表 + 状态跟踪 |
 | `progress.json` | 每次 session 结束 | 结构化会话日志 + 成本记录 |
-| `session_result.json` | 每次 session 结束 | 当前 + 历史 session 结果 |
+| `session_result.json` | 每次 session 结束 | 当前 session 结果（扁平格式，向后兼容旧 `current` 包装） |
+| `playwright-auth.json` | `claude-coder auth` | Playwright 登录状态（cookies + localStorage） |
 | `tests.json` | 首次测试时 | 验证记录（防止反复测试） |
-| `.runtime/` | 运行时 | 临时文件（phase、step、activity.log、logs/） |
+| `.runtime/` | 运行时 | 临时文件（phase、step、logs/session_N.activity.log） |
 
 ---
 
@@ -183,11 +248,11 @@ flowchart TB
 
 | Session 类型 | systemPrompt | user prompt | 触发条件 |
 |---|---|---|---|
-| **编码** | CLAUDE.md | `buildCodingPrompt()` + 10 个条件 hint | 主循环每次迭代 |
+| **编码** | CLAUDE.md | `buildCodingPrompt()` + 11 个条件 hint | 主循环每次迭代 |
 | **扫描** | CLAUDE.md + SCAN_PROTOCOL.md | `buildScanPrompt()` + 任务分解指导 + profile 质量要求 | 首次运行 |
 | **追加** | CLAUDE.md | `buildAddPrompt()` + 任务分解指导 | `claude-coder add` |
 
-### 编码 Session 的 10 个条件 Hint
+### 编码 Session 的 11 个条件 Hint
 
 | # | Hint | 触发条件 | 影响 |
 |---|---|---|---|
@@ -197,7 +262,8 @@ flowchart TB
 | 4 | `testHint` | tests.json 有记录 | Step 5：避免重复验证 |
 | 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` | .claude-coder/test.env 存在 | Step 5：提示 Agent 在测试前加载测试环境变量 |
+| 6b | `testEnvHint` | 始终注入（内容因 test.env 是否存在而不同） | Step 5：存在时提示加载；不存在时告知可创建 |
+| 6c | `playwrightAuthHint` | .claude-coder/playwright-auth.json 存在 | Step 5：提示 Agent 前端测试可使用已认证的浏览器状态 |
 | 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 模型必需 |
@@ -247,17 +313,27 @@ sequenceDiagram
     participant SDK as Claude Agent SDK
     participant Hook as inferPhaseStep()
     participant Ind as Indicator (setInterval)
+    participant Stall as stallChecker (30s)
     participant Term as 终端
 
     SDK->>Hook: PreToolUse 回调<br/>{tool_name: "Edit", tool_input: {path: "src/app.tsx"}}
     Hook->>Hook: 推断阶段: Edit → coding
     Hook->>Ind: updatePhase("coding")
+    Hook->>Ind: lastToolTime = now
+    Hook->>Ind: toolTarget = "src/app.tsx"
     Hook->>Ind: appendActivity("Edit", "src/app.tsx")
 
     Note over SDK,Hook: 同步回调，return {decision: "allow"}
 
     loop 每 500ms
-        Ind->>Term: ⠋ [Session 3] 编码中 02:15 | Git 操作
+        Ind->>Term: ⠋ [Session 3] 编码中 02:15 | 读取文件: ppt_generator.py
+    end
+
+    loop 每 30s
+        Stall->>Ind: 检查 now - lastToolTime
+        alt 超过 STALL_TIMEOUT
+            Stall->>SDK: stallDetected = true → break for-await
+        end
     end
 ```
 
@@ -312,19 +388,23 @@ Harness 在 `buildCodingPrompt()` 中预读 `tasks.json`，将下一个待办任
 
 Harness 在 `buildCodingPrompt()` 中预读 `session_result.json`，将上次会话的 task_id、结果和 notes 摘要注入 user prompt。Agent 无需自行读取历史 session 数据。
 
-### Loop Detection（编辑死循环检测）
+### 自愈机制
+
+**编辑死循环检测**：PreToolUse hook 追踪每个文件的编辑次数，同一文件 Write/Edit 超 5 次 → `decision: "block"`。
 
-PreToolUse hook 中追踪每个文件的编辑次数。当同一文件被 Write/Edit 超过 5 次时，hook 返回 `decision: "block"` 阻止操作并提示 Agent 重新审视方案。
+**停顿超时检测**：每 30 秒检查 `indicator.lastToolTime`，若距上次工具调用超过 `SESSION_STALL_TIMEOUT`（默认 1800 秒 / 30 分钟），自动 `break` 退出并触发 rollback + 重试。
+> 注意：模型在处理复杂文件时可能出现 10-20 分钟的长时间思考，这是正常行为。超时设为 30 分钟以避免误杀正常思考。可通过 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 自定义。
 
 ### 文件权限模型
 
-| 文件 | 写入方 | Agent 权限 |
-|------|--------|-----------|
-| `progress.json` | Harness | 只读 |
-| `sync_state.json` | Harness | 只读 |
-| `session_result.json` | Agent 写 `current`，Harness 归档到 `history` | 写 `current` |
-| `tasks.json` | Agent（仅 `status` 字段） | 修改 `status` |
-| `project_profile.json` | Agent（仅扫描阶段） | 扫描时写入 |
+| 文件 | 写入方 | Agent 权限 | git 状态 |
+|------|--------|-----------|---------|
+| `progress.json` | Harness | 只读 | tracked |
+| `session_result.json` | Agent 每次 session 覆盖写入（扁平格式） | 写入 | tracked |
+| `tasks.json` | Agent（仅 `status` 字段） | 修改 `status` | tracked |
+| `project_profile.json` | Agent（仅扫描阶段） | 扫描时写入 | tracked |
+| `test.env` | Agent + 用户 | 可追加写入 | .gitignore |
+| `playwright-auth.json` | 用户（`claude-coder auth`） | 只读 | .gitignore |
 
 ---
 
@@ -416,16 +496,16 @@ query({
 
 ---
 
-## 设计原则
+## 实现原则
+
+> 核心设计规则见 Section 0（primacy zone），以下为实现层面的补充原则。
 
 1. **SDK 原生集成**：通过 `query()` 调用 Claude，内联 hooks，原生 cost tracking
 2. **零硬依赖**：Claude Agent SDK 作为 peerDependency
-3. **Agent 自治**：Agent 通过 CLAUDE.md 协议自主决策，harness 只负责调度和校验
-4. **幂等设计**：所有入口可重复执行，不产生副作用
-5. **跨平台**：纯 Node.js + `child_process` 调用 git，无平台特定脚本
-6. **运行时隔离**：每个项目的 `.claude-coder/` 独立，不同项目互不干扰
-7. **Prompt 架构分离**：静态规则在 `templates/`，动态上下文在 `src/prompts.js`
-8. **文档即上下文**：文档在 harness 中分两层角色——Blueprint（`project_profile.json`，给 harness 的结构化元数据）和 Context Docs（`docs/ARCHITECTURE.md` 等，给 Agent 的人类可读文档）。Harness 通过 Hint 6 动态提醒 Agent 读取相关文档，并在 profile 有缺陷时提示补全
+3. **幂等设计**：所有入口可重复执行，不产生副作用
+4. **跨平台**：纯 Node.js + `child_process` 调用 git，无平台特定脚本
+5. **运行时隔离**：每个项目的 `.claude-coder/` 独立，不同项目互不干扰
+6. **文档即上下文**：Blueprint（`project_profile.json`）给 harness，Context Docs 给 Agent。Hint 6 动态提醒 Agent 读取相关文档
 
 ### 文档架构的学术依据
 

package/docs/PLAYWRIGHT_CREDENTIALS.md

@@ -1,131 +1,161 @@
-# Playwright MCP 凭证持久化方案
+# 测试凭证持久化方案
 
-## 背景
+## 设计思想
 
-在使用 claude-coder 运行涉及前端测试的任务时，Playwright MCP 可能需要：
-1. 已登录状态的 cookies（如后台管理页面）
-2. API Key 等测试凭证（如 AI 生成功能需要真实 API 调用）
+claude-coder 的核心目标是让 Agent **完全自主测试**，不因凭证缺失而中断。测试中涉及三类凭证：
 
-本文档描述如何在 claude-coder 工作流中管理这些凭证。
+| 类型 | 示例 | 特点 |
+|------|------|------|
+| 浏览器状态 | 登录 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. **零手动干预** — 除首次浏览器登录态外，其余由 Agent 自动处理
 
 ---
 
-## 方案 1: Playwright --storage-state（推荐用于 cookies）
+## 持久化架构
 
-### 原理
+```
+.claude-coder/
+  .env                    ← 模型配置（ANTHROPIC_API_KEY 等）     [用户配置]
+  test.env                ← 测试凭证（API Key、测试账号等）      [Agent 可写]
+  playwright-auth.json    ← 浏览器状态（cookies + localStorage） [auth 命令生成]
+```
 
-`@playwright/mcp` 支持 `--storage-state=<path>` 参数，加载预存的浏览器状态（cookies、localStorage）。
+### 文件生命周期
 
-### 步骤
+| 文件 | 创建方 | 写入方 | 回滚保护 | 生命周期 |
+|------|--------|--------|----------|----------|
+| `.env` | `claude-coder setup` | 用户 | 是 | 长期 |
+| `test.env` | Agent 或用户 | Agent + 用户 | 是 | 长期，按需更新 |
+| `playwright-auth.json` | `claude-coder auth` | auth 命令 | 是 | 中期，cookies 过期后需刷新 |
 
-**1. 手动登录并导出状态**
+### 回滚保护机制
 
-```bash
-# 启动 Playwright，手动登录后导出
-npx playwright codegen --save-storage=.claude-coder/playwright-auth.json http://localhost:3000
-```
+Harness 在 `git reset --hard` 前备份、后恢复以下文件：
+- `session_result.json` — 会话结果
+- `progress.json` — 历史记录
+- `test.env` — 测试凭证
+- `playwright-auth.json` — 浏览器状态
 
-登录完成后关闭浏览器，状态自动保存到 `playwright-auth.json`。
+这确保无论回滚多少次，凭证始终保留。
 
-**2. 配置 MCP 使用保存的状态**
+---
+
+## 核心流程
 
-在项目的 `.mcp.json`（Claude Code MCP 配置）中：
+### 流程 1：Agent 自动发现凭证
 
-```json
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": [
-        "@playwright/mcp@latest",
-        "--storage-state=.claude-coder/playwright-auth.json"
-      ]
-    }
-  }
-}
 ```
+Agent 测试 → 发现需要 API Key → 写入 test.env → 下次 session 自动加载
+```
+
+Agent 在 CLAUDE.md Step 5 中被指导：测试中发现的凭证追加到 `.claude-coder/test.env`。Harness 在每次 session 的 prompt 中注入 hint，告知 Agent `test.env` 的存在和用法。
 
-**3. 安全注意事项**
+### 流程 2：用户预配置浏览器登录态
 
-```gitignore
-# .gitignore
-.claude-coder/playwright-auth.json
+```
+用户运行 claude-coder auth → 手动登录 → 状态自动保存 → Agent 测试时使用
 ```
 
-### 注意
+适用于需要已登录状态才能测试的前端页面（如后台管理、需要 cookie 的 SPA）。
 
-- 状态文件包含敏感 cookies，必须加入 `.gitignore`
-- cookies 有过期时间，需要定期重新导出
-- `--storage-state` 与 `--isolated` 模式配合使用效果最佳
+### 流程 3：用户预配置 API Key
 
----
+```
+用户编辑 test.env → 填入 API Key → Agent 测试前 source 加载
+```
 
-## 方案 2: test.env（推荐用于 API Key）
+适用于后端功能依赖真实 API 调用的场景。
 
-### 原理
+---
 
-在 `.claude-coder/test.env` 中存放测试专用的环境变量（如 API Key）。claude-coder 会自动检测此文件存在，并通过 Hint 提示 Agent 在测试前加载它。
+## CLI 命令
 
-### 步骤
+### `claude-coder auth [url]`
 
-**1. 创建 test.env**
+一键导出浏览器登录态：
 
 ```bash
-# .claude-coder/test.env
-OPENAI_API_KEY=sk-xxx
-ZHIPU_API_KEY=xxx.xxx
-TEST_USER_TOKEN=xxx
-```
+# 默认打开 http://localhost:3000
+claude-coder auth
 
-**2. Agent 自动感知**
-
-当 `.claude-coder/test.env` 存在时，harness 在编码 session 的 prompt 中注入提示：
+# 指定 URL
+claude-coder auth http://localhost:8080/admin
+```
 
-> 测试环境变量在 .claude-coder/test.env（含 API Key 等），测试前用 source .claude-coder/test.env 或 export 加载。
+**自动完成**：
+1. 启动 Playwright 浏览器，用户手动登录后关闭
+2. 保存 cookies + localStorage 到 `.claude-coder/playwright-auth.json`
+3. 创建/更新 `.mcp.json`，配置 `--storage-state`
+4. 添加 `.gitignore` 条目
+5. 启用 `.claude-coder/.env` 中 `MCP_PLAYWRIGHT=true`
 
-Agent 在执行测试时会自动 `source` 该文件。
+### `claude-coder setup`（相关）
 
-**3. 安全注意事项**
+配置模型时可启用 Playwright MCP：
 
-```gitignore
-# .gitignore
-.claude-coder/test.env
+```bash
+claude-coder setup
+# 选择启用 MCP_PLAYWRIGHT=true
 ```
 
 ---
 
-## 方案 3: project_profile.json 中声明测试依赖
+## 场景示例
+
+### 场景 1：全栈项目首次测试
+
+```bash
+# 1. 配置模型
+claude-coder setup
+
+# 2. 填入后端测试需要的 API Key
+cat >> .claude-coder/test.env << 'EOF'
+OPENAI_API_KEY=sk-xxx
+ZHIPU_API_KEY=xxx.xxx
+EOF
 
-在扫描阶段或手动编辑 `project_profile.json`，声明哪些测试需要真实 API Key：
+# 3. 导出前端登录态（可选，Agent 也能用 Playwright MCP 自动登录）
+claude-coder auth http://localhost:3000
 
-```json
-{
-  "test_dependencies": {
-    "real_api_key": true,
-    "required_env_vars": ["OPENAI_API_KEY", "ZHIPU_API_KEY"],
-    "env_file": ".claude-coder/test.env"
-  }
-}
+# 4. 开始自动编码和测试
+claude-coder run
 ```
 
-Agent 在 Step 5 测试时，如果检测到 `preconditions.real_api_key: true`，会先检查环境变量是否可用，不可用则跳过该测试并标记为 `skip`。
+### 场景 2：Agent 自主发现并处理凭证缺失
 
----
+Agent 在测试 feat-005（AI 内容生成）时发现需要 `OPENAI_API_KEY`：
+
+1. Agent 尝试调用 API → 报错 "API key required"
+2. Agent **不中断任务**，改用替代验证方式（如 mock 响应、检查代码逻辑是否正确、验证接口可达性）
+3. Agent 将凭证需求写入 `test.env`：`echo 'OPENAI_API_KEY=需要配置' >> .claude-coder/test.env`
+4. Agent 在 `session_result.json` 的 notes 中记录："AI 内容生成功能已实现，但需要真实 OPENAI_API_KEY 才能完整测试，已记录到 test.env"
+5. Agent 完成其他可验证的步骤后标记任务为 `done`（功能已实现）或 `testing`（等待凭证后完整验证）
+
+**核心原则**：缺少凭证不等于任务失败。Agent 应最大化推进，将凭证问题记录为后续补充项，而非阻塞整个 session。
 
-## 最佳实践
+### 场景 3：前端 localStorage 配置持久化
 
-| 场景 | 推荐方案 |
-|------|----------|
-| 需要已登录状态测试页面 | 方案 1 (--storage-state) |
-| 需要 API Key 测试后端功能 | 方案 2 (test.env) |
-| 需要区分 mock 测试和集成测试 | 方案 3 (profile 声明) |
-| 以上组合 | 方案 1 + 2 + 3 |
+项目的前端将 LLM 服务商配置存储在 localStorage 中：
 
-### 工作流示例
+```bash
+# 启动前后端服务
+# 运行 auth，手动在页面中配置 LLM 设置
+claude-coder auth http://localhost:3000
 
+# playwright-auth.json 中已包含 localStorage 数据
+# 后续 Agent 使用 Playwright MCP 测试时自动加载这些配置
 ```
-1. claude-coder setup        → 配置模型
-2. 创建 .claude-coder/test.env  → 填入 API Key
-3. npx playwright codegen ...   → 导出登录状态
-4. claude-coder run             → Agent 自动使用凭证测试
+
+### 场景 4：cookies 过期后刷新
+
+```bash
+# 重新运行 auth 即可
+claude-coder auth http://localhost:3000
+# 新的 cookies 覆盖旧文件，立即生效
 ```

package/docs/README.en.md

@@ -53,9 +53,10 @@ Each session, the agent autonomously follows 6 steps: restore context → env ch
 | `claude-coder run --max 1` | Single session (replaces old view mode) |
 | `claude-coder run --dry-run` | Preview mode |
 | `claude-coder init` | Initialize project environment |
-| `claude-coder add "instruction"` | Append tasks (defaults to opus-class model) |
+| `claude-coder add "instruction"` | Append tasks |
 | `claude-coder add -r [file]` | Append tasks from requirements file |
 | `claude-coder add "..." --model M` | Append tasks with specific model |
+| `claude-coder auth [url]` | Export Playwright login state |
 | `claude-coder validate` | Manually validate last session |
 | `claude-coder status` | View progress and costs |
 | `claude-coder config sync` | Sync config to ~/.claude/ |
@@ -84,7 +85,9 @@ your-project/
     progress.json           # Session history + costs
     tests.json              # Verification records
     test.env                # Test credentials (API keys, optional)
-    .runtime/               # Temp files (logs)
+    playwright-auth.json    # Playwright login state (optional, via auth command)
+    .runtime/               # Temp files
+      logs/                 # Per-session logs + activity logs
   requirements.md           # Requirements (optional)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.2.0",
+  "version": "1.5.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"

package/src/auth.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { paths, log, getProjectRoot, ensureLoopDir } = require('./config');
+
+function updateGitignore(entry) {
+  const gitignorePath = path.join(getProjectRoot(), '.gitignore');
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf8');
+  }
+  if (content.includes(entry)) return;
+
+  const suffix = content.endsWith('\n') || content === '' ? '' : '\n';
+  fs.appendFileSync(gitignorePath, `${suffix}${entry}\n`, 'utf8');
+  log('ok', `.gitignore 已添加: ${entry}`);
+}
+
+function updateMcpConfig(authFilePath) {
+  const p = paths();
+  let mcpConfig = {};
+  if (fs.existsSync(p.mcpConfig)) {
+    try {
+      mcpConfig = JSON.parse(fs.readFileSync(p.mcpConfig, 'utf8'));
+    } catch {
+      log('warn', '.mcp.json 解析失败，将覆盖');
+    }
+  }
+
+  if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+
+  const relAuthPath = path.relative(getProjectRoot(), authFilePath);
+  mcpConfig.mcpServers.playwright = {
+    command: 'npx',
+    args: [
+      '@playwright/mcp@latest',
+      `--storage-state=${relAuthPath}`,
+    ],
+  };
+
+  fs.writeFileSync(p.mcpConfig, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf8');
+  log('ok', `.mcp.json 已配置 Playwright MCP (storage-state: ${relAuthPath})`);
+}
+
+function enableMcpPlaywrightEnv() {
+  const p = paths();
+  if (!fs.existsSync(p.envFile)) return;
+
+  let content = fs.readFileSync(p.envFile, 'utf8');
+  if (/^MCP_PLAYWRIGHT=/m.test(content)) {
+    content = content.replace(/^MCP_PLAYWRIGHT=.*/m, 'MCP_PLAYWRIGHT=true');
+  } else {
+    const suffix = content.endsWith('\n') ? '' : '\n';
+    content += `${suffix}MCP_PLAYWRIGHT=true\n`;
+  }
+  fs.writeFileSync(p.envFile, content, 'utf8');
+  log('ok', '.claude-coder/.env 已设置 MCP_PLAYWRIGHT=true');
+}
+
+async function auth(url) {
+  ensureLoopDir();
+  const p = paths();
+  const targetUrl = url || 'http://localhost:3000';
+
+  log('info', '启动 Playwright 浏览器，请手动登录...');
+  log('info', `目标 URL: ${targetUrl}`);
+  log('info', `登录状态将保存到: ${p.playwrightAuth}`);
+  console.log('');
+  console.log('操作步骤:');
+  console.log('  1. 浏览器将自动打开，请手动完成登录');
+  console.log('  2. 登录成功后关闭浏览器窗口');
+  console.log('  3. 登录状态（cookies + localStorage）将自动保存');
+  console.log('');
+
+  try {
+    execSync(
+      `npx playwright codegen --save-storage="${p.playwrightAuth}" "${targetUrl}"`,
+      { stdio: 'inherit', cwd: getProjectRoot() }
+    );
+  } catch (err) {
+    if (!fs.existsSync(p.playwrightAuth)) {
+      log('error', `Playwright 登录状态导出失败: ${err.message}`);
+      log('info', '请确保已安装 playwright: npx playwright install');
+      return;
+    }
+  }
+
+  if (!fs.existsSync(p.playwrightAuth)) {
+    log('error', '未检测到导出的登录状态文件');
+    return;
+  }
+
+  log('ok', '登录状态已保存');
+
+  updateMcpConfig(p.playwrightAuth);
+  updateGitignore('.claude-coder/playwright-auth.json');
+  enableMcpPlaywrightEnv();
+
+  console.log('');
+  log('ok', 'Playwright 凭证配置完成！');
+  log('info', '后续运行 claude-coder run 时，Agent 的前端测试将自动使用已认证状态');
+  log('info', '注意: cookies 有过期时间，需要定期重新运行 claude-coder auth 更新');
+}
+
+module.exports = { auth };

package/src/config.js

@@ -56,12 +56,13 @@ function paths() {
     profile:          path.join(loopDir, 'project_profile.json'),
     testsFile:        path.join(loopDir, 'tests.json'),
     testEnvFile:      path.join(loopDir, 'test.env'),
+    playwrightAuth:   path.join(loopDir, 'playwright-auth.json'),
+    mcpConfig:        path.join(getProjectRoot(), '.mcp.json'),
     claudeMd:         getTemplatePath('CLAUDE.md'),
     scanProtocol:     getTemplatePath('SCAN_PROTOCOL.md'),
     runtime,
     phaseFile:        path.join(runtime, 'phase'),
     stepFile:         path.join(runtime, 'step'),
-    activityLog:      path.join(runtime, 'activity.log'),
     logsDir:          path.join(runtime, 'logs'),
   };
 }
@@ -105,6 +106,7 @@ function loadConfig() {
     defaultSonnet: env.ANTHROPIC_DEFAULT_SONNET_MODEL || '',
     defaultHaiku: env.ANTHROPIC_DEFAULT_HAIKU_MODEL || '',
     thinkingBudget: env.ANTHROPIC_THINKING_BUDGET || '',
+    stallTimeout: parseInt(env.SESSION_STALL_TIMEOUT, 10) || 1800,
     raw: env,
   };
 
@@ -188,16 +190,6 @@ function syncToGlobal() {
   log('ok', `已同步配置到 ${settingsPath}`);
 }
 
-// --------------- Requirements hash ---------------
-
-function getRequirementsHash() {
-  const crypto = require('crypto');
-  const reqFile = path.join(getProjectRoot(), 'requirements.md');
-  if (!fs.existsSync(reqFile)) return '';
-  const content = fs.readFileSync(reqFile, 'utf8');
-  return crypto.createHash('sha256').update(content).digest('hex');
-}
-
 module.exports = {
   COLOR,
   log,
@@ -211,5 +203,4 @@ module.exports = {
   buildEnvVars,
   getAllowedTools,
   syncToGlobal,
-  getRequirementsHash,
 };

package/src/indicator.js

@@ -9,15 +9,18 @@ class Indicator {
   constructor() {
     this.phase = 'thinking';
     this.step = '';
+    this.toolTarget = '';
     this.spinnerIndex = 0;
     this.timer = null;
     this.lastActivity = '';
+    this.lastToolTime = Date.now();
     this.sessionNum = 0;
     this.startTime = Date.now();
   }
 
-  start(sessionNum) {
+  start(sessionNum, activityLogPath) {
     this.sessionNum = sessionNum;
+    this.activityLogPath = activityLogPath || null;
     this.startTime = Date.now();
     this.timer = setInterval(() => this._render(), 500);
   }
@@ -45,8 +48,9 @@ class Indicator {
     const entry = `[${ts}] ${toolName}: ${summary}`;
     this.lastActivity = entry;
     try {
-      const p = paths();
-      fs.appendFileSync(p.activityLog, entry + '\n', 'utf8');
+      if (this.activityLogPath) {
+        fs.appendFileSync(this.activityLogPath, entry + '\n', 'utf8');
+      }
     } catch { /* ignore */ }
   }
 
@@ -74,8 +78,17 @@ class Indicator {
       ? `${COLOR.yellow}思考中${COLOR.reset}`
       : `${COLOR.green}编码中${COLOR.reset}`;
 
+    const idleMs = Date.now() - this.lastToolTime;
+    const idleMin = Math.floor(idleMs / 60000);
+
     let line = `${spinner} [Session ${this.sessionNum}] ${clock} ${phaseLabel} ${mm}:${ss}`;
-    if (this.step) line += ` | ${this.step}`;
+    if (idleMin >= 2) {
+      line += ` | ${COLOR.red}${idleMin}分无工具调用${COLOR.reset}`;
+    }
+    if (this.step) {
+      line += ` | ${this.step}`;
+      if (this.toolTarget) line += `: ${this.toolTarget}`;
+    }
     return line;
   }
 
@@ -94,6 +107,14 @@ class Indicator {
 function inferPhaseStep(indicator, toolName, toolInput) {
   const name = (toolName || '').toLowerCase();
 
+  indicator.lastToolTime = Date.now();
+
+  const rawTarget = typeof toolInput === 'object'
+    ? (toolInput.file_path || toolInput.path || toolInput.command || toolInput.pattern || '')
+    : String(toolInput || '');
+  const shortTarget = rawTarget.split('/').slice(-2).join('/').slice(0, 40);
+  indicator.toolTarget = shortTarget;
+
   if (name === 'write' || name === 'edit' || name === 'multiedit' || name === 'str_replace_editor' || name === 'strreplace') {
     indicator.updatePhase('coding');
   } else if (name === 'bash' || name === 'shell') {
@@ -119,9 +140,23 @@ function inferPhaseStep(indicator, toolName, toolInput) {
     indicator.updateStep('查阅文档');
   }
 
-  const summary = typeof toolInput === 'object'
-    ? (toolInput.path || toolInput.command || toolInput.pattern || JSON.stringify(toolInput).slice(0, 80))
-    : String(toolInput || '').slice(0, 80);
+  let summary;
+  if (typeof toolInput === 'object') {
+    const target = toolInput.file_path || toolInput.path || '';
+    const cmd = toolInput.command || '';
+    const pattern = toolInput.pattern || '';
+    if (target) {
+      summary = target;
+    } else if (cmd) {
+      summary = cmd.slice(0, 200);
+    } else if (pattern) {
+      summary = `pattern: ${pattern}`;
+    } else {
+      summary = JSON.stringify(toolInput).slice(0, 200);
+    }
+  } else {
+    summary = String(toolInput || '').slice(0, 200);
+  }
   indicator.appendActivity(toolName, summary);
 }
 

package/src/prompts.js

@@ -72,9 +72,9 @@ function buildCodingPrompt(sessionNum, opts = {}) {
   }
 
   // Hint 6: Task context (harness pre-read, saves Agent 2-3 Read calls)
+  const projectRoot = getProjectRoot();
   let taskHint = '';
   try {
-    const projectRoot = getProjectRoot();
     const taskData = loadTasks();
     if (taskData) {
       const next = findNextTask(taskData);
@@ -89,11 +89,18 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     }
   } catch { /* ignore */ }
 
-  // Hint 6b: Test environment variables
+  // Hint 6b: Test environment variables (readable + writable by Agent)
   let testEnvHint = '';
-  const testEnvFile = paths().testEnvFile;
-  if (testEnvFile && fs.existsSync(testEnvFile)) {
-    testEnvHint = '测试环境变量在 .claude-coder/test.env（含 API Key 等），测试前用 source .claude-coder/test.env 或 export 加载。';
+  if (p.testEnvFile && fs.existsSync(p.testEnvFile)) {
+    testEnvHint = `测试凭证文件: ${projectRoot}/.claude-coder/test.env（含 API Key、测试账号等），测试前用 source ${projectRoot}/.claude-coder/test.env 加载。发现新凭证需求时可追加写入（KEY=value 格式）。`;
+  } else {
+    testEnvHint = `如需持久化测试凭证（API Key、测试账号密码等），写入 ${projectRoot}/.claude-coder/test.env（KEY=value 格式，每行一个）。后续 session 会自动感知。`;
+  }
+
+  // Hint 6c: Playwright authenticated state
+  let playwrightAuthHint = '';
+  if (p.playwrightAuth && fs.existsSync(p.playwrightAuth)) {
+    playwrightAuthHint = `已检测到 Playwright 登录状态（${projectRoot}/.claude-coder/playwright-auth.json），前端/全栈测试将使用已认证的浏览器会话（含 cookies 和 localStorage）。`;
   }
 
   // Hint 7: Session memory (read flat session_result.json)
@@ -136,6 +143,7 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     envHint,
     taskHint,
     testEnvHint,
+    playwrightAuthHint,
     memoryHint,
     serviceHint,
     toolGuidance,

package/src/runner.js

@@ -183,7 +183,7 @@ async function run(requirement, opts = {}) {
   ensureLoopDir();
 
   const maxSessions = opts.max || 50;
-  const pauseEvery = opts.pause || 5;
+  const pauseEvery = opts.pause ?? 0;
   const dryRun = opts.dryRun || false;
 
   console.log('');
@@ -301,12 +301,35 @@ async function run(requirement, opts = {}) {
       lastValidateLog: consecutiveFailures > 0 ? '上次校验失败' : '',
     });
 
+    if (sessionResult.stalled) {
+      log('warn', `Session ${session} 因停顿超时中断，跳过校验直接重试`);
+      consecutiveFailures++;
+      rollback(headBefore, '停顿超时');
+      if (consecutiveFailures >= MAX_RETRY) {
+        log('error', `连续失败 ${MAX_RETRY} 次，跳过当前任务`);
+        markTaskFailed();
+        consecutiveFailures = 0;
+      }
+      appendProgress({
+        session,
+        timestamp: new Date().toISOString(),
+        result: 'stalled',
+        cost: sessionResult.cost,
+        taskId,
+      });
+      continue;
+    }
+
     // Validate
     log('info', '开始 harness 校验 ...');
     const validateResult = await validate(headBefore);
 
     if (!validateResult.fatal) {
-      log('ok', `Session ${session} 校验通过`);
+      if (validateResult.hasWarnings) {
+        log('warn', `Session ${session} 校验通过 (有自动修复或警告)`);
+      } else {
+        log('ok', `Session ${session} 校验通过`);
+      }
       tryPush();
       consecutiveFailures = 0;
 
@@ -369,8 +392,8 @@ async function add(instruction, opts = {}) {
   if (!opts.model) {
     if (config.defaultOpus) {
       opts.model = config.defaultOpus;
-    } else if (config.provider === 'claude' || !config.baseUrl) {
-      opts.model = 'claude-sonnet-4-20250514';
+    } else if (config.model) {
+      opts.model = config.model;
     }
   }
 

package/src/session.js

@@ -99,12 +99,23 @@ async function runCodingSession(sessionNum, opts = {}) {
   const taskId = opts.taskId || 'unknown';
   const dateStr = new Date().toISOString().slice(0, 10).replace(/-/g, '');
   const logFile = path.join(p.logsDir, `${taskId}_session_${sessionNum}_${dateStr}.log`);
+  const activityLogFile = path.join(p.logsDir, `session_${sessionNum}.activity.log`);
   const logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
-  indicator.start(sessionNum);
+  indicator.start(sessionNum, activityLogFile);
 
   const editCounts = {};
   const EDIT_THRESHOLD = 5;
+  const stallTimeoutMs = config.stallTimeout * 1000;
+  let stallDetected = false;
+
+  const stallChecker = setInterval(() => {
+    const idleMs = Date.now() - indicator.lastToolTime;
+    if (idleMs > stallTimeoutMs && !stallDetected) {
+      stallDetected = true;
+      log('warn', `无新工具调用超过 ${Math.floor(idleMs / 60000)} 分钟，自动中断 session`);
+    }
+  }, 30000);
 
   try {
     const queryOpts = buildQueryOptions(config, opts);
@@ -115,13 +126,18 @@ async function runCodingSession(sessionNum, opts = {}) {
         hooks: [async (input) => {
           inferPhaseStep(indicator, input.tool_name, input.tool_input);
 
-          const filePath = input.tool_input?.file_path || input.tool_input?.path || '';
-          if (['Write', 'Edit', 'MultiEdit'].includes(input.tool_name) && filePath) {
-            editCounts[filePath] = (editCounts[filePath] || 0) + 1;
-            if (editCounts[filePath] > EDIT_THRESHOLD) {
+          const target = input.tool_input?.file_path || input.tool_input?.path || '';
+          const toolSummary = target ? target.split('/').slice(-2).join('/') : '';
+          if (toolSummary) {
+            logStream.write(`[${new Date().toISOString()}] ${input.tool_name}: ${toolSummary}\n`);
+          }
+
+          if (['Write', 'Edit', 'MultiEdit'].includes(input.tool_name) && target) {
+            editCounts[target] = (editCounts[target] || 0) + 1;
+            if (editCounts[target] > EDIT_THRESHOLD) {
               return {
                 decision: 'block',
-                message: `已对 ${filePath} 编辑 ${editCounts[filePath]} 次，疑似死循环。请重新审视方案后再继续。`,
+                message: `已对 ${target} 编辑 ${editCounts[target]} 次，疑似死循环。请重新审视方案后再继续。`,
               };
             }
           }
@@ -135,21 +151,28 @@ async function runCodingSession(sessionNum, opts = {}) {
 
     const collected = [];
     for await (const message of session) {
+      if (stallDetected) {
+        log('warn', '停顿超时，中断消息循环');
+        break;
+      }
       collected.push(message);
       logMessage(message, logStream, indicator);
     }
 
+    clearInterval(stallChecker);
     logStream.end();
     indicator.stop();
 
     const result = extractResult(collected);
     return {
-      exitCode: 0,
+      exitCode: stallDetected ? 2 : 0,
       cost: result?.total_cost_usd ?? null,
       tokenUsage: result?.usage ?? null,
       logFile,
+      stalled: stallDetected,
     };
   } catch (err) {
+    clearInterval(stallChecker);
     logStream.end();
     indicator.stop();
     log('error', `Claude SDK 错误: ${err.message}`);

package/src/validator.js

@@ -9,7 +9,7 @@ function validateSessionResult() {
 
   if (!fs.existsSync(p.sessionResult)) {
     log('error', 'Agent 未生成 session_result.json');
-    return { valid: false, fatal: true, reason: 'session_result.json 不存在' };
+    return { valid: false, fatal: true, recoverable: false, reason: 'session_result.json 不存在' };
   }
 
   let data;
@@ -17,25 +17,30 @@ function validateSessionResult() {
     data = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
   } catch (err) {
     log('error', `session_result.json 解析失败: ${err.message}`);
-    return { valid: false, fatal: true, reason: `JSON 解析失败: ${err.message}` };
+    return { valid: false, fatal: true, recoverable: false, reason: `JSON 解析失败: ${err.message}` };
+  }
+
+  // Backward compat: unwrap legacy { current: {...} } format
+  if (data.current && typeof data.current === 'object') {
+    data = data.current;
   }
 
   const required = ['session_result', 'status_after'];
   const missing = required.filter(k => !(k in data));
   if (missing.length > 0) {
-    log('error', `session_result.json 缺少字段: ${missing.join(', ')}`);
-    return { valid: false, fatal: true, reason: `缺少字段: ${missing.join(', ')}` };
+    log('warn', `session_result.json 缺少字段: ${missing.join(', ')}`);
+    return { valid: false, fatal: false, recoverable: true, reason: `缺少字段: ${missing.join(', ')}` };
   }
 
   if (!['success', 'failed'].includes(data.session_result)) {
     log('error', `session_result 必须是 success 或 failed，实际是: ${data.session_result}`);
-    return { valid: false, fatal: true, reason: `无效 session_result: ${data.session_result}` };
+    return { valid: false, fatal: true, recoverable: false, reason: `无效 session_result: ${data.session_result}` };
   }
 
   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, reason: `无效 status_after: ${data.status_after}` };
+    return { valid: false, fatal: true, recoverable: false, reason: `无效 status_after: ${data.status_after}` };
   }
 
   if (!data.task_id) {
@@ -48,7 +53,7 @@ function validateSessionResult() {
     log('warn', 'session_result.json 合法，但 Agent 报告失败 (failed)');
   }
 
-  return { valid: true, fatal: false, data };
+  return { valid: true, fatal: false, recoverable: false, data };
 }
 
 function checkGitProgress(headBefore) {
@@ -107,12 +112,21 @@ function checkTestCoverage() {
 async function validate(headBefore) {
   log('info', '========== 开始校验 ==========');
 
-  const srResult = validateSessionResult();
+  let 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;
+  }
+
   checkTestCoverage();
 
   const fatal = srResult.fatal;
-  const hasWarnings = gitResult.warning;
+  const hasWarnings = gitResult.warning || srResult.recoverable;
 
   if (fatal) {
     log('error', '========== 校验失败 (致命) ==========');

package/templates/CLAUDE.md

@@ -50,6 +50,8 @@
 | `.claude-coder/progress.json` | 跨会话记忆日志（外部循环自动维护） | 只读 |
 | `.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` 预配置 |
 
 ### requirements.md 处理原则
 
@@ -232,6 +234,8 @@ pending ──→ in_progress ──→ testing ──→ done
 
 6. **记录验证命令**：如果本功能涉及 API 或核心逻辑，在 `tests.json` 中追加一条记录（含 `last_run_session` 为当前 session 编号）。纯配置 / 纯样式 / 改动 < 100 行的任务无需记录
 
+7. **凭证持久化**：测试中发现需要的凭证（API Key、测试账号密码等），追加写入 `.claude-coder/test.env`，格式为 `KEY=value`（每行一个）。后续 session 会自动感知该文件。确保 `test.env` 已在 `.gitignore` 中（不被 git 追踪）
+
 **禁止**：
 - 后端任务启动浏览器测试
 - 创建独立测试文件（`test-*.js` / `test-*.html`）