claude-coder 1.5.4 → 1.5.6

package/README.md

@@ -97,7 +97,8 @@ your-project/
     progress.json           # 会话历史 + 成本
     tests.json              # 验证记录
     test.env                # 测试凭证（API Key 等，可选）
-    playwright-auth.json    # Playwright 登录状态（可选，auth 命令生成）
+    playwright-auth.json    # 登录状态快照（备份参考，auth 命令生成）
+    browser-profile/        # 持久化浏览器 Profile（MCP 实际使用）
     .runtime/               # 临时文件
       logs/                 # 每 session 独立日志（含工具调用记录）
   requirements.md           # 需求文档（可选）

package/docs/ARCHITECTURE.md

@@ -31,7 +31,7 @@ Agent 在单次 session 中应最大化推进任务进度。**任何非致命问
 
 `git reset --hard` 是全量回滚，不做部分文件保护。
 
-- 凭证文件（`test.env`、`playwright-auth.json`）应通过 `.gitignore` 排除在 git 之外
+- 凭证文件（`test.env`、`playwright-auth.json`、`browser-profile/`）应通过 `.gitignore` 排除在 git 之外
 - 如果回滚发生，说明 session 确实失败，代码应全部还原
 - 不需要 backup/restore 机制 — 这是过度设计
 
@@ -51,7 +51,8 @@ Agent 在单次 session 中应最大化推进任务进度。**任何非致命问
 | 文件 | git 状态 | 说明 |
 |------|---------|------|
 | `test.env` | .gitignore | Agent 可写入发现的 API Key、测试账号 |
-| `playwright-auth.json` | .gitignore | 用户通过 `claude-coder auth` 生成 |
+| `playwright-auth.json` | .gitignore | 登录状态快照备份（`claude-coder auth` 生成） |
+| `browser-profile/` | .gitignore | 持久化浏览器 Profile（MCP 实际使用） |
 | `session_result.json` | git-tracked | Agent 每次 session 覆盖写入 |
 | `tasks.json` | git-tracked | Agent 修改 status 字段 |
 
@@ -207,7 +208,8 @@ templates/
 | `tasks.json` | 首次扫描 | 任务列表 + 状态跟踪 |
 | `progress.json` | 每次 session 结束 | 结构化会话日志 + 成本记录 |
 | `session_result.json` | 每次 session 结束 | 当前 session 结果（扁平格式，向后兼容旧 `current` 包装） |
-| `playwright-auth.json` | `claude-coder auth` | Playwright 登录状态（cookies + localStorage） |
+| `playwright-auth.json` | `claude-coder auth` | 登录状态快照（备份参考） |
+| `browser-profile/` | `claude-coder auth` | 持久化浏览器 Profile（MCP 通过 `--user-data-dir` 使用） |
 | `tests.json` | 首次测试时 | 验证记录（防止反复测试） |
 | `.runtime/` | 运行时 | 临时文件（phase、step、logs/）；工具调用记录合并到 session log |
 
@@ -265,7 +267,7 @@ flowchart TB
 | 5 | `docsHint` | profile.existing_docs 非空或 profile 有缺陷 | Step 4：读文档后再编码；profile 缺陷时提示 Agent 在 Step 6 补全 services/docs |
 | 6 | `taskHint` | tasks.json 存在且有待办任务 | Step 1：跳过读取 tasks.json，harness 已注入当前任务上下文 + 项目绝对路径 |
 | 6b | `testEnvHint` | 始终注入（内容因 test.env 是否存在而不同） | Step 5：存在时提示加载；不存在时告知可创建 |
-| 6c | `playwrightAuthHint` | .claude-coder/playwright-auth.json 存在 | Step 5：提示 Agent 前端测试可使用已认证的浏览器状态 |
+| 6c | `playwrightAuthHint` | .claude-coder/browser-profile/ 存在 | Step 5：提示 Agent MCP 使用持久化浏览器 Profile，首次需手动登录 |
 | 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 模型必需 |
@@ -406,7 +408,8 @@ Harness 在 `buildCodingPrompt()` 中预读 `session_result.json`，将上次会
 | `tasks.json` | Agent（仅 `status` 字段） | 修改 `status` | tracked |
 | `project_profile.json` | Agent（仅扫描阶段） | 扫描时写入 | tracked |
 | `test.env` | Agent + 用户 | 可追加写入 | .gitignore |
-| `playwright-auth.json` | 用户（`claude-coder auth`） | 只读 | .gitignore |
+| `playwright-auth.json` | 用户（`claude-coder auth`） | 快照备份 | .gitignore |
+| `browser-profile/` | 用户（`claude-coder auth`） | MCP 自动维护 | .gitignore |
 
 ---
 

package/docs/PLAYWRIGHT_CREDENTIALS.md

@@ -13,7 +13,7 @@ claude-coder 的核心目标是让 Agent **完全自主测试**，不因凭证
 **核心原则**：
 1. **Agent 可自行发现并持久化凭证** — 测试中发现需要的 API Key 或账号，直接写入 `test.env`
 2. **凭证不受回滚影响** — `git reset --hard` 不会摧毁已保存的凭证
-3. **零手动干预** — 除首次浏览器登录态外，其余由 Agent 自动处理
+3. **零手动干预** — 首次浏览器登录后，后续由持久化 profile 自动处理
 
 ---
 
@@ -23,7 +23,8 @@ claude-coder 的核心目标是让 Agent **完全自主测试**，不因凭证
 .claude-coder/
   .env                    ← 模型配置（ANTHROPIC_API_KEY 等）     [用户配置]
   test.env                ← 测试凭证（API Key、测试账号等）      [Agent 可写]
-  playwright-auth.json    ← 浏览器状态（cookies + localStorage） [auth 命令生成]
+  playwright-auth.json    ← 登录状态快照（备份参考）             [auth 命令生成]
+  browser-profile/        ← 持久化浏览器 Profile（MCP 实际使用） [auth 命令创建]
 ```
 
 ### 文件生命周期
@@ -32,17 +33,25 @@ claude-coder 的核心目标是让 Agent **完全自主测试**，不因凭证
 |------|--------|--------|----------|----------|
 | `.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` — 浏览器状态
-
-这确保无论回滚多少次，凭证始终保留。
+| `playwright-auth.json` | `claude-coder auth` | auth 命令 | 是 | 快照备份，不被 MCP 直接使用 |
+| `browser-profile/` | `claude-coder auth` | MCP 自动维护 | 是 | 长期，自动续期 |
+
+### 技术实现：为什么用 `--user-data-dir` 而不是 `--storage-state`
+
+| 维度 | `--storage-state`（旧方案） | `--user-data-dir`（当前方案） |
+|------|-------------------------|--------------------------|
+| 上下文类型 | 隔离上下文（isolated） | 持久化上下文（persistent） |
+| 状态保持 | 每次从 JSON 文件加载，会话结束丢弃 | Profile 自动保存，跨会话保持 |
+| Cookies 续期 | 不支持（JSON 文件静态） | 支持（浏览器自动刷新的 cookies 被保留） |
+| localStorage | 从 JSON 注入（可靠） | 持久保存在 Profile 中 |
+| Google OAuth | 每次创建新上下文 → Google 检测到自动化 | 持久 Profile → Google 视为常规浏览器 |
+| 长期运行 | 差（cookies 过期后必须重新 auth） | 优（Profile 随浏览器使用自动演进） |
+
+> **源码依据**：Playwright MCP `contextFactory()` 在 `isolated=false` 时使用 `PersistentContextFactory`，
+> 调用 `launchPersistentContext(userDataDir, options)` 创建持久化浏览器上下文。
+> `--storage-state` 虽然不强制 `isolated=true`，但官方文档明确描述其为 "load into an isolated browser context"，
+> 且 `launchPersistentContext` 的 `storageState` 参数存在已知缺陷（Issue #14949）：localStorage 不注入，
+> 旧 cookies 可能覆盖 Profile 中已刷新的 cookies。
 
 ---
 
@@ -54,56 +63,47 @@ Harness 在 `git reset --hard` 前备份、后恢复以下文件：
 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 测试时使用
+用户运行 claude-coder auth url
+→ playwright codegen 打开浏览器 → 手动登录 → 关闭浏览器
+→ cookies + localStorage 保存为快照备份（playwright-auth.json）
+→ 创建 browser-profile/ 目录
+→ 更新 .mcp.json（--user-data-dir 指向 browser-profile/）
+→ 首次 MCP 会话时在浏览器窗口中登录一次
+→ 之后 MCP 自动使用持久化 Profile，无需再次登录
 ```
 
-适用于需要已登录状态才能测试的前端页面（如后台管理、需要 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
+# 指定 URL（如内部 API 文档平台）
+claude-coder auth http://testyapi.example.com/group/2245
 ```
 
 **自动完成**：
-1. 启动 Playwright 浏览器，用户手动登录后关闭
-2. 保存 cookies + localStorage 到 `.claude-coder/playwright-auth.json`
-3. 创建/更新 `.mcp.json`，配置 `--storage-state`
-4. 添加 `.gitignore` 条目
+1. 创建 `.claude-coder/browser-profile/` 持久化 Profile 目录
+2. 启动 `playwright codegen`，用户手动登录后关闭浏览器（保存快照备份）
+3. 创建/更新 `.mcp.json`，配置 `--user-data-dir=.claude-coder/browser-profile`
+4. 添加 `.gitignore` 条目（`playwright-auth.json` + `browser-profile/`）
 5. 启用 `.claude-coder/.env` 中 `MCP_PLAYWRIGHT=true`
 
-### `claude-coder setup`（相关）
-
-配置模型时可启用 Playwright MCP：
-
-```bash
-claude-coder setup
-# 选择启用 MCP_PLAYWRIGHT=true
-```
-
 ---
 
 ## 场景示例
@@ -111,51 +111,42 @@ claude-coder setup
 ### 场景 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
+# 首次 MCP 访问需登录的页面时，在浏览器窗口登录一次
+# 之后所有 session 自动保持登录状态
 ```
 
-### 场景 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`（等待凭证后完整验证）
+### 场景 2：内部系统（Google OAuth / SSO）
 
-**核心原则**：缺少凭证不等于任务失败。Agent 应最大化推进，将凭证问题记录为后续补充项，而非阻塞整个 session。
+```bash
+claude-coder auth http://testyapi.example.com/group/2245
+# 在弹出的浏览器中完成 Google 登录（快照备份）
+# 首次 MCP 会话时在浏览器窗口中再次登录
+# 之后持久化 Profile 自动保持 Google 登录状态
+```
 
-### 场景 3：前端 localStorage 配置持久化
+> **关于 Google OAuth 检测**：使用 `--user-data-dir` 持久化 Profile 后，Google 将浏览器视为
+> "回访用户"而非"新自动化会话"，大幅降低重复登录要求。如果仍被检测，可在 `.mcp.json` 中
+> 添加 `--browser chrome` 使用真实 Chrome 进一步降低检测率。
 
-项目的前端将 LLM 服务商配置存储在 localStorage 中：
+### 场景 3：长期运行（核心优势）
 
 ```bash
-# 启动前后端服务
-# 运行 auth，手动在页面中配置 LLM 设置
-claude-coder auth http://localhost:3000
-
-# playwright-auth.json 中已包含 localStorage 数据
-# 后续 Agent 使用 Playwright MCP 测试时自动加载这些配置
+claude-coder run --max-sessions 50
+# 浏览器 Profile 自动保持：
+#   - cookies 被网站刷新时，新 cookies 自动写入 Profile
+#   - 不依赖静态 JSON 文件，状态持续演进
+#   - 即使中途重启 claude-coder，Profile 中的登录状态仍然有效
 ```
 
-### 场景 4：cookies 过期后刷新
+### 场景 4：清除登录状态
 
 ```bash
-# 重新运行 auth 即可
-claude-coder auth http://localhost:3000
-# 新的 cookies 覆盖旧文件，立即生效
+rm -rf .claude-coder/browser-profile/
+# 下次 MCP 会话时将创建全新 Profile，需重新登录
 ```

package/docs/README.en.md

@@ -85,7 +85,8 @@ your-project/
     progress.json           # Session history + costs
     tests.json              # Verification records
     test.env                # Test credentials (API keys, optional)
-    playwright-auth.json    # Playwright login state (optional, via auth command)
+    playwright-auth.json    # Login state snapshot (backup, via auth command)
+    browser-profile/        # Persistent browser profile (used by MCP)
     .runtime/               # Temp files
       logs/                 # Per-session logs (with tool call traces)
   requirements.md           # Requirements (optional)

package/package.json

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

@@ -18,7 +18,7 @@ function updateGitignore(entry) {
   log('ok', `.gitignore 已添加: ${entry}`);
 }
 
-function updateMcpConfig(authFilePath) {
+function updateMcpConfig(browserProfileDir) {
   const p = paths();
   let mcpConfig = {};
   if (fs.existsSync(p.mcpConfig)) {
@@ -31,17 +31,17 @@ function updateMcpConfig(authFilePath) {
 
   if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
 
-  const relAuthPath = path.relative(getProjectRoot(), authFilePath);
+  const relProfileDir = path.relative(getProjectRoot(), browserProfileDir);
   mcpConfig.mcpServers.playwright = {
     command: 'npx',
     args: [
       '@playwright/mcp@latest',
-      `--storage-state=${relAuthPath}`,
+      `--user-data-dir=${relProfileDir}`,
     ],
   };
 
   fs.writeFileSync(p.mcpConfig, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf8');
-  log('ok', `.mcp.json 已配置 Playwright MCP (storage-state: ${relAuthPath})`);
+  log('ok', `.mcp.json 已配置 Playwright MCP (user-data-dir: ${relProfileDir})`);
 }
 
 function enableMcpPlaywrightEnv() {
@@ -64,14 +64,17 @@ async function auth(url) {
   const p = paths();
   const targetUrl = url || 'http://localhost:3000';
 
+  if (!fs.existsSync(p.browserProfile))
+    fs.mkdirSync(p.browserProfile, { recursive: true });
+
   log('info', '启动 Playwright 浏览器，请手动登录...');
   log('info', `目标 URL: ${targetUrl}`);
-  log('info', `登录状态将保存到: ${p.playwrightAuth}`);
+  log('info', `浏览器配置将持久化到: ${p.browserProfile}`);
   console.log('');
   console.log('操作步骤:');
   console.log('  1. 浏览器将自动打开，请手动完成登录');
   console.log('  2. 登录成功后关闭浏览器窗口');
-  console.log('  3. 登录状态（cookies + localStorage）将自动保存');
+  console.log('  3. 登录状态（cookies + localStorage）将保存为快照备份');
   console.log('');
 
   try {
@@ -92,16 +95,18 @@ async function auth(url) {
     return;
   }
 
-  log('ok', '登录状态已保存');
+  log('ok', '登录状态快照已保存（备份参考）');
 
-  updateMcpConfig(p.playwrightAuth);
+  updateMcpConfig(p.browserProfile);
   updateGitignore('.claude-coder/playwright-auth.json');
+  updateGitignore('.claude-coder/browser-profile/');
   enableMcpPlaywrightEnv();
 
   console.log('');
-  log('ok', 'Playwright 凭证配置完成！');
-  log('info', '后续运行 claude-coder run 时，Agent 的前端测试将自动使用已认证状态');
-  log('info', '注意: cookies 有过期时间，需要定期重新运行 claude-coder auth 更新');
+  log('ok', '持久化浏览器配置完成！');
+  log('info', 'MCP 使用 --user-data-dir 持久化模式，登录状态跨会话保持');
+  log('info', '首次 MCP 会话时需在浏览器窗口中登录一次，之后永久保持');
+  log('info', 'cookies 自动续期，无需手动重新运行 claude-coder auth');
 }
 
 module.exports = { auth };

package/src/config.js

@@ -57,6 +57,7 @@ function paths() {
     testsFile:        path.join(loopDir, 'tests.json'),
     testEnvFile:      path.join(loopDir, 'test.env'),
     playwrightAuth:   path.join(loopDir, 'playwright-auth.json'),
+    browserProfile:   path.join(loopDir, 'browser-profile'),
     mcpConfig:        path.join(getProjectRoot(), '.mcp.json'),
     claudeMd:         getTemplatePath('CLAUDE.md'),
     scanProtocol:     getTemplatePath('SCAN_PROTOCOL.md'),

package/src/indicator.js

@@ -17,11 +17,13 @@ class Indicator {
     this.sessionNum = 0;
     this.startTime = Date.now();
     this._lastContentKey = '';
+    this._lastRenderTime = 0;
   }
 
   start(sessionNum) {
     this.sessionNum = sessionNum;
     this.startTime = Date.now();
+    this._lastRenderTime = Date.now();
     this.timer = setInterval(() => this._render(), 500);
   }
 
@@ -87,6 +89,16 @@ class Indicator {
 
   _render() {
     this.spinnerIndex++;
+    const contentKey = `${this.phase}|${this.step}|${this.toolTarget}`;
+    const now = Date.now();
+    const contentChanged = contentKey !== this._lastContentKey;
+
+    if (!contentChanged && now - this._lastRenderTime < 3000) {
+      return;
+    }
+    this._lastContentKey = contentKey;
+    this._lastRenderTime = now;
+
     const line = this.getStatusLine();
     const maxWidth = process.stderr.columns || 80;
     const truncated = line.length > maxWidth + 20 ? line.slice(0, maxWidth + 20) : line;

package/src/prompts.js

@@ -97,10 +97,12 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     testEnvHint = `如需持久化测试凭证（API Key、测试账号密码等），写入 ${projectRoot}/.claude-coder/test.env（KEY=value 格式，每行一个）。后续 session 会自动感知。`;
   }
 
-  // Hint 6c: Playwright authenticated state
+  // Hint 6c: Playwright persistent browser profile
   let playwrightAuthHint = '';
-  if (p.playwrightAuth && fs.existsSync(p.playwrightAuth)) {
-    playwrightAuthHint = `已检测到 Playwright 登录状态（${projectRoot}/.claude-coder/playwright-auth.json），前端/全栈测试将使用已认证的浏览器会话（含 cookies 和 localStorage）。`;
+  if (fs.existsSync(p.browserProfile)) {
+    playwrightAuthHint = `已检测到持久化浏览器配置（${projectRoot}/.claude-coder/browser-profile/），MCP 使用 --user-data-dir 模式，登录状态跨会话自动保持。首次访问需登录的页面时，用户需在浏览器窗口中手动完成登录。`;
+  } else if (fs.existsSync(p.playwrightAuth)) {
+    playwrightAuthHint = `已检测到 Playwright 登录状态快照（${projectRoot}/.claude-coder/playwright-auth.json），建议运行 claude-coder auth 升级到持久化浏览器模式以获得更好的登录保持效果。`;
   }
 
   // Hint 7: Session memory (read flat session_result.json)

package/templates/CLAUDE.md

@@ -51,7 +51,8 @@
 | `.claude-coder/session_result.json` | 本次会话的结构化输出 | 每次会话结束时覆盖写入 |
 | `.claude-coder/tests.json` | 功能验证记录（轻量） | 可新增和更新；仅当功能涉及 API 或核心逻辑时记录 |
 | `.claude-coder/test.env` | 测试凭证（API Key、测试账号等） | **可追加写入**；发现测试需要的凭证时持久化到此文件 |
-| `.claude-coder/playwright-auth.json` | 浏览器登录状态（cookies + localStorage） | 只读；由用户通过 `claude-coder auth` 预配置 |
+| `.claude-coder/playwright-auth.json` | 登录状态快照（备份参考） | 只读；由 `claude-coder auth` 生成 |
+| `.claude-coder/browser-profile/` | 持久化浏览器 Profile | MCP 自动维护；首次需手动登录，之后永久保持 |
 
 ### requirements.md 处理原则