claude-coder 1.1.0 → 1.4.0

package/README.md

@@ -55,6 +55,8 @@ claude-coder run "实现用户注册和登录功能"
 | `claude-coder init` | 初始化项目环境 |
 | `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/ |
@@ -71,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)。
+
 ## 模型支持
 
 | 提供商 | 说明 |
@@ -92,7 +96,9 @@ your-project/
     session_result.json     # 上次 session 结果（扁平）
     progress.json           # 会话历史 + 成本
     tests.json              # 验证记录
-    .runtime/               # 临时文件
+    test.env                # 测试凭证（API Key 等，可选）
+    playwright-auth.json    # Playwright 登录状态（可选，auth 命令生成）
+    .runtime/               # 临时文件（含日志）
   requirements.md           # 需求文档（可选）
 ```
 
@@ -108,7 +114,8 @@ your-project/
 
 ## 文档
 
-- [技术架构](docs/ARCHITECTURE.md) — 模块职责、提示语注入架构、注意力机制、Hook 数据流、后续优化方向
+- [技术架构](docs/ARCHITECTURE.md) — 核心设计规则、模块职责、提示语注入架构、注意力机制、Hook 数据流
+- [测试凭证持久化方案](docs/PLAYWRIGHT_CREDENTIALS.md) — 自动测试的凭证管理：Playwright 登录态导出、API Key 持久化、Agent 缺凭证时的行为策略
 
 ## License
 

package/bin/cli.js

@@ -7,7 +7,8 @@ const COMMANDS = {
   run:      { desc: '自动编码循环',             usage: 'claude-coder run [需求] [--max N] [--pause N] [--dry-run]' },
   setup:    { desc: '交互式模型配置',           usage: 'claude-coder setup' },
   init:     { desc: '初始化项目环境',           usage: 'claude-coder init' },
-  add:      { desc: '追加任务到 tasks.json',    usage: 'claude-coder add "指令" | add -r [file]' },
+  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' },
@@ -28,6 +29,9 @@ function showHelp() {
   console.log('  claude-coder run --dry-run            预览模式');
   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`);
 }
@@ -35,7 +39,7 @@ function showHelp() {
 function parseArgs(argv) {
   const args = argv.slice(2);
   const command = args[0];
-  const opts = { max: 50, pause: 0, dryRun: false, readFile: null };
+  const opts = { max: 50, pause: 0, dryRun: false, readFile: null, model: null };
   const positional = [];
 
   for (let i = 1; i < args.length; i++) {
@@ -49,6 +53,9 @@ function parseArgs(argv) {
       case '--dry-run':
         opts.dryRun = true;
         break;
+      case '--model':
+        opts.model = args[++i] || null;
+        break;
       case '-r': {
         const next = args[i + 1];
         if (next && !next.startsWith('-')) {
@@ -105,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) {
@@ -123,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,54 @@
 
 ---
 
+## 0. 核心设计规则（MUST READ）
+
+> 以下规则按重要性排序（注意力 primacy zone），所有代码修改和架构决策必须遵循。
+
+### 规则 1：长 Session 不停工
+
+Agent 在单次 session 中应最大化推进任务进度。**任何非致命问题都不应中断 session**。
+
+- 缺少 API Key → 用 mock 或代码逻辑验证替代，记录到 `test.env`，继续推进
+- 测试环境未就绪 → 跳过该测试步骤，完成其余可验证的步骤
+- 服务启动失败 → 尝试排查修复，无法修复则记录问题后推进代码实现
+
+**反面案例**：Agent 因 `OPENAI_API_KEY` 缺失直接标记任务 `failed` → 浪费整个 session
+
+### 规则 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 注入架构）。
+
+---
+
 ## 1. 核心架构
 
 ```mermaid
@@ -42,7 +90,7 @@ 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
 ```
 
 **核心特征：**
@@ -80,7 +128,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"]
@@ -100,8 +148,9 @@ src/
   prompts.js        提示语构建：系统 prompt 组合 + 条件 hint + 任务分解指导
   init.js           环境初始化：读取 profile 执行依赖安装、服务启动、健康检查
   scanner.js        初始化扫描：调用 runScanSession + 重试
-  validator.js      校验引擎：session_result 结构校验 + git 检查 + 测试覆盖
+  validator.js      校验引擎：分层校验（fatal/recoverable/pass）+ git 检查 + 测试覆盖
   tasks.js          任务管理：CRUD + 状态机 + 进度展示
+  auth.js           Playwright 凭证：导出登录状态 + MCP 配置 + gitignore
   indicator.js      进度指示：终端 spinner + phase/step 文件写入
   setup.js          交互式配置：模型选择、API Key、MCP 工具
 templates/
@@ -125,8 +174,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,7 +190,8 @@ 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/） |
 
@@ -183,11 +234,11 @@ flowchart TB
 
 | Session 类型 | systemPrompt | user prompt | 触发条件 |
 |---|---|---|---|
-| **编码** | CLAUDE.md | `buildCodingPrompt()` + 9 个条件 hint | 主循环每次迭代 |
+| **编码** | CLAUDE.md | `buildCodingPrompt()` + 11 个条件 hint | 主循环每次迭代 |
 | **扫描** | CLAUDE.md + SCAN_PROTOCOL.md | `buildScanPrompt()` + 任务分解指导 + profile 质量要求 | 首次运行 |
 | **追加** | CLAUDE.md | `buildAddPrompt()` + 任务分解指导 | `claude-coder add` |
 
-### 编码 Session 的 9 个条件 Hint
+### 编码 Session 的 11 个条件 Hint
 
 | # | Hint | 触发条件 | 影响 |
 |---|---|---|---|
@@ -196,7 +247,9 @@ flowchart TB
 | 3 | `envHint` | 连续成功且 session>1 | Step 2：跳过 init |
 | 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 已注入当前任务上下文 + .claude-coder/ 路径提示 |
+| 6 | `taskHint` | tasks.json 存在且有待办任务 | Step 1：跳过读取 tasks.json，harness 已注入当前任务上下文 + 项目绝对路径 |
+| 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 模型必需 |
@@ -267,7 +320,7 @@ sequenceDiagram
 | 维度 | 评分 | 说明 |
 |------|------|------|
 | **CLAUDE.md 系统提示** | 8/10 | U 型注意力设计；铁律清晰；状态机和 6 步流程是核心竞争力 |
-| **动态 prompt** | 9/10 | 9 个条件 hint 精准注入，含 task/memory 上下文注入 + 服务管理 + 工具使用指导，减少 Agent 冗余操作 |
+| **动态 prompt** | 9/10 | 10 个条件 hint 精准注入，含 task/memory 上下文注入 + cwd 路径 + test.env + 服务管理 + 工具使用指导，减少 Agent 冗余操作 |
 | **SCAN_PROTOCOL.md** | 8.5/10 | 新旧项目分支完整，profile 格式全面 |
 | **tests.json 设计** | 7.5/10 | 精简字段，核心目的（防反复测试）明确 |
 | **注入时机** | 9/10 | 静态规则 vs 动态上下文分离干净 |
@@ -317,13 +370,14 @@ PreToolUse hook 中追踪每个文件的编辑次数。当同一文件被 Write/
 
 ### 文件权限模型
 
-| 文件 | 写入方 | 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 |
 
 ---
 
@@ -415,16 +469,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

@@ -0,0 +1,161 @@
+# 测试凭证持久化方案
+
+## 设计思想
+
+claude-coder 的核心目标是让 Agent **完全自主测试**，不因凭证缺失而中断。测试中涉及三类凭证：
+
+| 类型 | 示例 | 特点 |
+|------|------|------|
+| 浏览器状态 | 登录 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 自动处理
+
+---
+
+## 持久化架构
+
+```
+.claude-coder/
+  .env                    ← 模型配置（ANTHROPIC_API_KEY 等）     [用户配置]
+  test.env                ← 测试凭证（API Key、测试账号等）      [Agent 可写]
+  playwright-auth.json    ← 浏览器状态（cookies + localStorage） [auth 命令生成]
+```
+
+### 文件生命周期
+
+| 文件 | 创建方 | 写入方 | 回滚保护 | 生命周期 |
+|------|--------|--------|----------|----------|
+| `.env` | `claude-coder setup` | 用户 | 是 | 长期 |
+| `test.env` | Agent 或用户 | Agent + 用户 | 是 | 长期，按需更新 |
+| `playwright-auth.json` | `claude-coder auth` | auth 命令 | 是 | 中期，cookies 过期后需刷新 |
+
+### 回滚保护机制
+
+Harness 在 `git reset --hard` 前备份、后恢复以下文件：
+- `session_result.json` — 会话结果
+- `progress.json` — 历史记录
+- `test.env` — 测试凭证
+- `playwright-auth.json` — 浏览器状态
+
+这确保无论回滚多少次，凭证始终保留。
+
+---
+
+## 核心流程
+
+### 流程 1：Agent 自动发现凭证
+
+```
+Agent 测试 → 发现需要 API Key → 写入 test.env → 下次 session 自动加载
+```
+
+Agent 在 CLAUDE.md Step 5 中被指导：测试中发现的凭证追加到 `.claude-coder/test.env`。Harness 在每次 session 的 prompt 中注入 hint，告知 Agent `test.env` 的存在和用法。
+
+### 流程 2：用户预配置浏览器登录态
+
+```
+用户运行 claude-coder auth → 手动登录 → 状态自动保存 → Agent 测试时使用
+```
+
+适用于需要已登录状态才能测试的前端页面（如后台管理、需要 cookie 的 SPA）。
+
+### 流程 3：用户预配置 API Key
+
+```
+用户编辑 test.env → 填入 API Key → Agent 测试前 source 加载
+```
+
+适用于后端功能依赖真实 API 调用的场景。
+
+---
+
+## CLI 命令
+
+### `claude-coder auth [url]`
+
+一键导出浏览器登录态：
+
+```bash
+# 默认打开 http://localhost:3000
+claude-coder auth
+
+# 指定 URL
+claude-coder auth http://localhost:8080/admin
+```
+
+**自动完成**：
+1. 启动 Playwright 浏览器，用户手动登录后关闭
+2. 保存 cookies + localStorage 到 `.claude-coder/playwright-auth.json`
+3. 创建/更新 `.mcp.json`，配置 `--storage-state`
+4. 添加 `.gitignore` 条目
+5. 启用 `.claude-coder/.env` 中 `MCP_PLAYWRIGHT=true`
+
+### `claude-coder setup`（相关）
+
+配置模型时可启用 Playwright MCP：
+
+```bash
+claude-coder setup
+# 选择启用 MCP_PLAYWRIGHT=true
+```
+
+---
+
+## 场景示例
+
+### 场景 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
+
+# 3. 导出前端登录态（可选，Agent 也能用 Playwright MCP 自动登录）
+claude-coder auth http://localhost:3000
+
+# 4. 开始自动编码和测试
+claude-coder run
+```
+
+### 场景 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 配置持久化
+
+项目的前端将 LLM 服务商配置存储在 localStorage 中：
+
+```bash
+# 启动前后端服务
+# 运行 auth，手动在页面中配置 LLM 设置
+claude-coder auth http://localhost:3000
+
+# playwright-auth.json 中已包含 localStorage 数据
+# 后续 Agent 使用 Playwright MCP 测试时自动加载这些配置
+```
+
+### 场景 4：cookies 过期后刷新
+
+```bash
+# 重新运行 auth 即可
+claude-coder auth http://localhost:3000
+# 新的 cookies 覆盖旧文件，立即生效
+```

package/docs/README.en.md

@@ -55,6 +55,8 @@ Each session, the agent autonomously follows 6 steps: restore context → env ch
 | `claude-coder init` | Initialize project environment |
 | `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/ |
@@ -82,13 +84,16 @@ your-project/
     session_result.json     # Last session result (flat)
     progress.json           # Session history + costs
     tests.json              # Verification records
-    .runtime/               # Temp files
+    test.env                # Test credentials (API keys, optional)
+    playwright-auth.json    # Playwright login state (optional, via auth command)
+    .runtime/               # Temp files (logs)
   requirements.md           # Requirements (optional)
 ```
 
 ## Documentation
 
 - [Architecture](ARCHITECTURE.md) — Module responsibilities, prompt injection architecture, attention mechanism, hook data flow, future roadmap
+- [Playwright Credentials](PLAYWRIGHT_CREDENTIALS.md) — Test cookies and API key management
 
 ## License
 

package/package.json

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

@@ -55,6 +55,9 @@ function paths() {
     sessionResult:    path.join(loopDir, 'session_result.json'),
     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,
@@ -187,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,
@@ -210,5 +203,4 @@ module.exports = {
   buildEnvVars,
   getAllowedTools,
   syncToGlobal,
-  getRequirementsHash,
 };

package/src/prompts.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const fs = require('fs');
-const { paths, loadConfig } = require('./config');
+const { paths, loadConfig, getProjectRoot } = require('./config');
 const { loadTasks, findNextTask, getStats } = require('./tasks');
 
 /**
@@ -72,6 +72,7 @@ function buildCodingPrompt(sessionNum, opts = {}) {
   }
 
   // Hint 6: Task context (harness pre-read, saves Agent 2-3 Read calls)
+  const projectRoot = getProjectRoot();
   let taskHint = '';
   try {
     const taskData = loadTasks();
@@ -82,12 +83,26 @@ function buildCodingPrompt(sessionNum, opts = {}) {
         taskHint = `任务上下文: ${next.id} "${next.description}" (${next.status}), ` +
           `category=${next.category}, steps=${next.steps.length}步。` +
           `进度: ${stats.done}/${stats.total} done, ${stats.failed} failed。` +
-          `运行时目录: .claude-coder/（隐藏目录，ls -a 可见，所有 tasks.json/profile 等文件均在此目录下）。` +
+          `项目绝对路径: ${projectRoot}。运行时目录: ${projectRoot}/.claude-coder/（隐藏目录）。` +
           `第一步无需读取 tasks.json（已注入），直接确认任务后进入 Step 2。`;
       }
     }
   } catch { /* ignore */ }
 
+  // Hint 6b: Test environment variables (readable + writable by Agent)
+  let testEnvHint = '';
+  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)
   let memoryHint = '';
   if (fs.existsSync(p.sessionResult)) {
@@ -127,6 +142,8 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     docsHint,
     envHint,
     taskHint,
+    testEnvHint,
+    playwrightAuthHint,
     memoryHint,
     serviceHint,
     toolGuidance,

package/src/runner.js

@@ -77,17 +77,38 @@ function killServicesByProfile() {
   } catch { /* ignore profile read errors */ }
 }
 
+function sleepSync(ms) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { /* busy wait */ }
+}
+
 function rollback(headBefore, reason) {
   if (!headBefore || headBefore === 'none') return;
 
   killServicesByProfile();
 
+  if (process.platform === 'win32') sleepSync(1500);
+
+  const cwd = getProjectRoot();
+  const gitEnv = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+
   log('warn', `回滚到 ${headBefore} ...`);
-  try {
-    execSync(`git reset --hard ${headBefore}`, { cwd: getProjectRoot(), stdio: 'pipe' });
-    log('ok', '回滚完成');
-  } catch (err) {
-    log('error', `回滚失败: ${err.message}`);
+
+  let success = false;
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    try {
+      execSync(`git reset --hard ${headBefore}`, { cwd, stdio: 'pipe', env: gitEnv });
+      log('ok', '回滚完成');
+      success = true;
+      break;
+    } catch (err) {
+      if (attempt === 1) {
+        log('warn', `回滚首次失败，等待后重试: ${err.message}`);
+        sleepSync(2000);
+      } else {
+        log('error', `回滚失败: ${err.message}`);
+      }
+    }
   }
 
   appendProgress({
@@ -95,6 +116,7 @@ function rollback(headBefore, reason) {
     timestamp: new Date().toISOString(),
     reason: reason || 'harness 校验失败',
     rollbackTo: headBefore,
+    success,
   });
 }
 
@@ -161,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('');
@@ -267,10 +289,13 @@ async function run(requirement, opts = {}) {
     }
 
     const headBefore = getHead();
+    const nextTask = findNextTask(taskData);
+    const taskId = nextTask?.id || 'unknown';
 
     // Run coding session
     const sessionResult = await runCodingSession(session, {
       projectRoot,
+      taskId,
       consecutiveFailures,
       maxSessions,
       lastValidateLog: consecutiveFailures > 0 ? '上次校验失败' : '',
@@ -281,7 +306,11 @@ async function run(requirement, opts = {}) {
     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;
 
@@ -340,10 +369,18 @@ async function add(instruction, opts = {}) {
   ensureLoopDir();
 
   const config = loadConfig();
-  if (config.provider !== 'claude' && config.baseUrl) {
-    log('ok', `模型配置已加载: ${config.provider}${config.model ? ` (${config.model})` : ''}`);
+
+  if (!opts.model) {
+    if (config.defaultOpus) {
+      opts.model = config.defaultOpus;
+    } else if (config.model) {
+      opts.model = config.model;
+    }
   }
 
+  const displayModel = opts.model || config.model || '(default)';
+  log('ok', `模型配置已加载: ${config.provider || 'claude'} (add 使用: ${displayModel})`);
+
   if (!fs.existsSync(p.profile) || !fs.existsSync(p.tasksFile)) {
     log('error', 'add 需要先完成初始化（至少运行一次 claude-coder run）');
     process.exit(1);

package/src/session.js

@@ -51,7 +51,8 @@ function buildQueryOptions(config, opts = {}) {
     env: buildEnvVars(config),
     settingSources: ['project'],
   };
-  if (config.model) base.model = config.model;
+  if (opts.model) base.model = opts.model;
+  else if (config.model) base.model = config.model;
   return base;
 }
 
@@ -62,6 +63,10 @@ function extractResult(messages) {
   return null;
 }
 
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
 function logMessage(message, logStream, indicator) {
   if (message.type === 'assistant' && message.message?.content) {
     for (const block of message.message.content) {
@@ -70,6 +75,9 @@ function logMessage(message, logStream, indicator) {
           const statusLine = indicator.getStatusLine();
           process.stderr.write('\r\x1b[K');
           if (statusLine) process.stderr.write(statusLine + '\n');
+          if (logStream && statusLine) {
+            logStream.write('\n' + stripAnsi(statusLine) + '\n');
+          }
         }
         process.stdout.write(block.text);
         if (logStream) logStream.write(block.text);
@@ -88,7 +96,9 @@ async function runCodingSession(sessionNum, opts = {}) {
   const systemPrompt = buildSystemPrompt(false);
 
   const p = paths();
-  const logFile = path.join(p.logsDir, `session_${sessionNum}_${Date.now()}.log`);
+  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 logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
   indicator.start(sessionNum);
@@ -164,7 +174,7 @@ async function runScanSession(requirement, opts = {}) {
   const systemPrompt = buildSystemPrompt(true);
 
   const p = paths();
-  const logFile = path.join(p.logsDir, `scan_${Date.now()}.log`);
+  const logFile = path.join(p.logsDir, `scan_${new Date().toISOString().slice(0, 10).replace(/-/g, '')}.log`);
   const logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
   indicator.start(0);
@@ -218,7 +228,7 @@ async function runAddSession(instruction, opts = {}) {
   const prompt = buildAddPrompt(instruction);
 
   const p = paths();
-  const logFile = path.join(p.logsDir, `add_tasks_${Date.now()}.log`);
+  const logFile = path.join(p.logsDir, `add_tasks_${new Date().toISOString().slice(0, 10).replace(/-/g, '')}.log`);
   const logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
   indicator.start(0);

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`）