claude-coder 1.5.6 → 1.6.2

package/README.md

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

package/bin/cli.js

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

package/docs/ARCHITECTURE.md

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

package/docs/PLAYWRIGHT_CREDENTIALS.md

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

package/docs/README.en.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.5.6",
+  "version": "1.6.2",
   "description": "Claude Coder — Autonomous coding agent harness powered by Claude Code SDK. Scan, plan, code, validate, git-commit in a loop.",
   "bin": {
     "claude-coder": "bin/cli.js"
@@ -38,5 +38,7 @@
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": ">=0.1.0"
   },
-  "dependencies": {}
+  "optionalDependencies": {
+    "playwright": "^1.58.2"
+  }
 }