claude-coder 1.5.5 → 1.5.7

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,7 @@ claude-coder 的核心目标是让 Agent **完全自主测试**，不因凭证
 .claude-coder/
   .env                    ← 模型配置（ANTHROPIC_API_KEY 等）     [用户配置]
   test.env                ← 测试凭证（API Key、测试账号等）      [Agent 可写]
-  playwright-auth.json    ← 浏览器状态（cookies + localStorage） [auth 命令生成]
+  playwright-auth.json    ← 浏览器登录状态（MCP 每次会话加载）   [auth 命令生成]
 ```
 
 ### 文件生命周期
@@ -32,17 +32,26 @@ 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 每次会话自动加载；如需更新重新运行 auth |
+
+### 技术实现：为什么用 `--isolated --storage-state`
+
+| 维度 | `--user-data-dir`（persistent） | `--isolated --storage-state`（当前方案） |
+|------|--------------------------|--------------------------------------|
+| 上下文类型 | 持久化上下文 | 隔离上下文 |
+| localStorage | **已知 Bug #14949：`launchPersistentContext` 不注入 localStorage** | 从 JSON 可靠注入 |
+| Cookies | Profile 自动续期 | 每次从 JSON 加载（静态） |
+| 状态保持 | 跨会话自动保持 | 每次会话从 JSON 重新加载 |
+| 适用场景 | 需要 cookie 自动续期（Google OAuth） | 需要 localStorage 注入（API Key 等） |
+
+> **选择 `--isolated --storage-state` 的原因**：
+> 经实测验证，Playwright 的 `launchPersistentContext` + `storageState` 存在已知缺陷
+>（Issue #14949）：localStorage 完全不注入。而 `--isolated` 模式使用 `newContext({ storageState })`，
+> localStorage 可靠注入。claude-coder 的典型场景是注入 API Key（存储在 localStorage），
+> 因此选择 `--isolated --storage-state` 作为默认方案。
+>
+> 如需 cookie 持久化（Google OAuth/SSO），可手动修改 `.mcp.json` 为 `--user-data-dir` 模式，
+> 但需在 MCP 浏览器中手动登录一次。
 
 ---
 
@@ -54,56 +63,46 @@ 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
+→ 更新 .mcp.json（--isolated --storage-state 指向 playwright-auth.json）
+→ 每次 MCP 会话自动从 JSON 加载状态（无需手动登录）
+→ 如需更新状态，重新运行 claude-coder auth
 ```
 
-适用于需要已登录状态才能测试的前端页面（如后台管理、需要 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. 启动 `playwright codegen`，用户手动登录后关闭浏览器
+2. cookies + localStorage 保存到 `.claude-coder/playwright-auth.json`
+3. 创建/更新 `.mcp.json`，配置 `--isolated --storage-state=.claude-coder/playwright-auth.json`
+4. 添加 `.gitignore` 条目（`playwright-auth.json`）
 5. 启用 `.claude-coder/.env` 中 `MCP_PLAYWRIGHT=true`
 
-### `claude-coder setup`（相关）
-
-配置模型时可启用 Playwright MCP：
-
-```bash
-claude-coder setup
-# 选择启用 MCP_PLAYWRIGHT=true
-```
-
 ---
 
 ## 场景示例
@@ -111,51 +110,36 @@ 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 每次会话自动从 playwright-auth.json 加载 localStorage 和 cookies
 ```
 
-### 场景 2：Agent 自主发现并处理凭证缺失
-
-Agent 在测试 feat-005（AI 内容生成）时发现需要 `OPENAI_API_KEY`：
+### 场景 2：内部系统（Google OAuth / SSO）
 
-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。
+```bash
+claude-coder auth http://testyapi.example.com/group/2245
+# 在弹出的浏览器中完成登录，关闭后状态保存到 JSON
+# MCP 每次会话自动加载此状态
+```
 
-### 场景 3：前端 localStorage 配置持久化
+> **关于 Google OAuth**：`--isolated` 模式每次创建新上下文，Google 可能要求重新验证。
+> 如需 cookie 持久化，可手动修改 `.mcp.json` 为 `--user-data-dir` 模式（但 localStorage 不会注入）。
 
-项目的前端将 LLM 服务商配置存储在 localStorage 中：
+### 场景 3：更新登录状态
 
 ```bash
-# 启动前后端服务
-# 运行 auth，手动在页面中配置 LLM 设置
 claude-coder auth http://localhost:3000
-
-# playwright-auth.json 中已包含 localStorage 数据
-# 后续 Agent 使用 Playwright MCP 测试时自动加载这些配置
+# 重新登录，覆盖 playwright-auth.json
 ```
 
-### 场景 4：cookies 过期后刷新
+### 场景 4：清除登录状态
 
 ```bash
-# 重新运行 auth 即可
-claude-coder auth http://localhost:3000
-# 新的 cookies 覆盖旧文件，立即生效
+rm .claude-coder/playwright-auth.json
+# 下次运行 claude-coder auth 重新配置
 ```

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.5",
+  "version": "1.5.7",
   "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() {
   const p = paths();
   let mcpConfig = {};
   if (fs.existsSync(p.mcpConfig)) {
@@ -31,17 +31,18 @@ function updateMcpConfig(authFilePath) {
 
   if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
 
-  const relAuthPath = path.relative(getProjectRoot(), authFilePath);
+  const relAuthPath = path.relative(getProjectRoot(), p.playwrightAuth).split(path.sep).join('/');
   mcpConfig.mcpServers.playwright = {
     command: 'npx',
     args: [
       '@playwright/mcp@latest',
+      '--isolated',
       `--storage-state=${relAuthPath}`,
     ],
   };
 
   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 (isolated + storage-state: ${relAuthPath})`);
 }
 
 function enableMcpPlaywrightEnv() {
@@ -66,12 +67,12 @@ async function auth(url) {
 
   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('  3. 登录状态（cookies + localStorage）将保存到 playwright-auth.json');
+  console.log('  4. MCP 每次会话自动加载此状态（isolated 模式）');
   console.log('');
 
   try {
@@ -92,16 +93,17 @@ async function auth(url) {
     return;
   }
 
-  log('ok', '登录状态已保存');
+  log('ok', '登录状态已保存到 playwright-auth.json');
 
-  updateMcpConfig(p.playwrightAuth);
+  updateMcpConfig();
   updateGitignore('.claude-coder/playwright-auth.json');
   enableMcpPlaywrightEnv();
 
   console.log('');
-  log('ok', 'Playwright 凭证配置完成！');
-  log('info', '后续运行 claude-coder run 时，Agent 的前端测试将自动使用已认证状态');
-  log('info', '注意: cookies 有过期时间，需要定期重新运行 claude-coder auth 更新');
+  log('ok', '配置完成！');
+  log('info', 'MCP 使用 --isolated --storage-state 模式');
+  log('info', 'localStorage 和 cookies 每次会话自动从 playwright-auth.json 加载');
+  log('info', '如需更新登录状态，重新运行 claude-coder auth');
 }
 
 module.exports = { auth };

package/src/config.js

@@ -60,9 +60,8 @@ function paths() {
     mcpConfig:        path.join(getProjectRoot(), '.mcp.json'),
     claudeMd:         getTemplatePath('CLAUDE.md'),
     scanProtocol:     getTemplatePath('SCAN_PROTOCOL.md'),
+    testRuleTemplate: getTemplatePath('test_rule.md'),
     runtime,
-    phaseFile:        path.join(runtime, 'phase'),
-    stepFile:         path.join(runtime, 'step'),
     logsDir:          path.join(runtime, 'logs'),
   };
 }
@@ -107,6 +106,7 @@ function loadConfig() {
     defaultHaiku: env.ANTHROPIC_DEFAULT_HAIKU_MODEL || '',
     thinkingBudget: env.ANTHROPIC_THINKING_BUDGET || '',
     stallTimeout: parseInt(env.SESSION_STALL_TIMEOUT, 10) || 1800,
+    editThreshold: parseInt(env.EDIT_THRESHOLD, 10) || 15,
     raw: env,
   };
 

package/src/hooks.js

@@ -3,7 +3,7 @@
 const { inferPhaseStep } = require('./indicator');
 const { log } = require('./config');
 
-const EDIT_THRESHOLD = 5;
+const DEFAULT_EDIT_THRESHOLD = 30;
 
 function logToolCall(logStream, input) {
   if (!logStream) return;
@@ -31,6 +31,7 @@ function createSessionHooks(indicator, logStream, options = {}) {
     enableStallDetection = false,
     stallTimeoutMs = 1800000,
     enableEditGuard = false,
+    editThreshold = DEFAULT_EDIT_THRESHOLD,
   } = options;
 
   const editCounts = {};
@@ -62,7 +63,7 @@ function createSessionHooks(indicator, logStream, options = {}) {
           const target = input.tool_input?.file_path || input.tool_input?.path || '';
           if (['Write', 'Edit', 'MultiEdit'].includes(input.tool_name) && target) {
             editCounts[target] = (editCounts[target] || 0) + 1;
-            if (editCounts[target] > EDIT_THRESHOLD) {
+            if (editCounts[target] > editThreshold) {
               return {
                 decision: 'block',
                 message: `已对 ${target} 编辑 ${editCounts[target]} 次，疑似死循环。请重新审视方案后再继续。`,

package/src/indicator.js

@@ -1,7 +1,6 @@
 'use strict';
 
-const fs = require('fs');
-const { paths, COLOR } = require('./config');
+const { COLOR } = require('./config');
 
 const SPINNERS = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 
@@ -16,14 +15,11 @@ class Indicator {
     this.lastToolTime = Date.now();
     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);
   }
 
@@ -37,26 +33,16 @@ class Indicator {
 
   updatePhase(phase) {
     this.phase = phase;
-    this._writePhaseFile();
   }
 
   updateStep(step) {
     this.step = step;
-    this._writeStepFile();
   }
 
   appendActivity(toolName, summary) {
     this.lastActivity = `${toolName}: ${summary}`;
   }
 
-  _writePhaseFile() {
-    try { fs.writeFileSync(paths().phaseFile, this.phase, 'utf8'); } catch { /* ignore */ }
-  }
-
-  _writeStepFile() {
-    try { fs.writeFileSync(paths().stepFile, this.step, 'utf8'); } catch { /* ignore */ }
-  }
-
   getStatusLine() {
     const now = new Date();
     const hh = String(now.getHours()).padStart(2, '0');
@@ -82,28 +68,23 @@ class Indicator {
     }
     if (this.step) {
       line += ` | ${this.step}`;
-      if (this.toolTarget) line += `: ${this.toolTarget}`;
+      if (this.toolTarget) {
+        const cols = process.stderr.columns || 80;
+        const usedWidth = line.replace(/\x1b\[[^m]*m/g, '').length;
+        const availWidth = Math.max(15, cols - usedWidth - 4);
+        const target = this.toolTarget.length > availWidth
+          ? '…' + this.toolTarget.slice(-(availWidth - 1))
+          : this.toolTarget;
+        line += `: ${target}`;
+      }
     }
     return line;
   }
 
   _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;
-
-    process.stderr.write(`\r\x1b[K${truncated}`);
+    process.stderr.write(`\r\x1b[K${line}`);
   }
 }
 
@@ -112,7 +93,7 @@ function extractFileTarget(toolInput) {
     ? (toolInput.file_path || toolInput.path || '')
     : '';
   if (!raw) return '';
-  return raw.split('/').slice(-2).join('/').slice(0, 40);
+  return raw.split('/').slice(-2).join('/');
 }
 
 function extractBashLabel(cmd) {

package/src/prompts.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const fs = require('fs');
+const path = require('path');
 const { paths, loadConfig, getProjectRoot } = require('./config');
 const { loadTasks, findNextTask, getStats } = require('./tasks');
 
@@ -97,10 +98,10 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     testEnvHint = `如需持久化测试凭证（API Key、测试账号密码等），写入 ${projectRoot}/.claude-coder/test.env（KEY=value 格式，每行一个）。后续 session 会自动感知。`;
   }
 
-  // Hint 6c: Playwright authenticated state
+  // Hint 6c: Playwright auth state
   let playwrightAuthHint = '';
-  if (p.playwrightAuth && fs.existsSync(p.playwrightAuth)) {
-    playwrightAuthHint = `已检测到 Playwright 登录状态（${projectRoot}/.claude-coder/playwright-auth.json），前端/全栈测试将使用已认证的浏览器会话（含 cookies 和 localStorage）。`;
+  if (fs.existsSync(p.playwrightAuth)) {
+    playwrightAuthHint = `已检测到 Playwright 登录状态（${projectRoot}/.claude-coder/playwright-auth.json），MCP 使用 --isolated --storage-state 模式，每次会话自动加载 localStorage 和 cookies。`;
   }
 
   // Hint 7: Session memory (read flat session_result.json)
@@ -108,9 +109,9 @@ function buildCodingPrompt(sessionNum, opts = {}) {
   if (fs.existsSync(p.sessionResult)) {
     try {
       const sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
-      if (sr?.task_id) {
-        memoryHint = `上次会话: ${sr.task_id} → ${sr.status_after || sr.session_result}` +
-          (sr.notes ? `, 要点: ${sr.notes.slice(0, 100)}` : '') + '。';
+      if (sr?.session_result) {
+        memoryHint = `上次会话: ${sr.session_result}（${sr.status_before || '?'} → ${sr.status_after || '?'}）` +
+          (sr.notes ? `, 要点: ${sr.notes.slice(0, 150)}` : '') + '。';
       }
     } catch { /* ignore */ }
   }
@@ -198,7 +199,7 @@ function buildScanPrompt(projectType, requirement) {
     'profile 质量要求（必须遵守，harness 会校验）：',
     '- services 数组必须包含所有可启动服务（command、port、health_check），不得为空',
     '- existing_docs 必须列出所有实际存在的文档路径',
-    '- 前后端分离项目必须生成 docs/ARCHITECTURE.md（模块职责、数据流、API 路由），并加入 existing_docs',
+    '- 检查 .claude/CLAUDE.md 是否存在，若无则生成（WHAT/WHY/HOW 格式：技术栈、关键决策、开发命令、关键路径、编码规则），并加入 existing_docs',
     '- scan_files_checked 必须列出所有实际扫描过的文件',
     '',
     '步骤 3：根据以下指导分解任务到 tasks.json（格式见 CLAUDE.md）：',
@@ -263,6 +264,21 @@ function buildAddPrompt(instruction) {
     }
   } catch { /* ignore */ }
 
+  // --- Conditional: Playwright test rule hint ---
+  let testRuleHint = '';
+  const testRulePath = path.join(p.loopDir, 'test_rule.md');
+  const hasMcp = fs.existsSync(p.mcpConfig);
+  if (fs.existsSync(testRulePath) && hasMcp) {
+    testRuleHint = [
+      '【Playwright 测试规则】项目已配置 Playwright MCP（.mcp.json），' +
+      '`.claude-coder/test_rule.md` 中包含通用测试指导规则（Smart Snapshot、Token 预算控制、三步测试方法论、等待策略等）。',
+      '当任务涉及端到端测试时：',
+      '  - 在 steps 中第一步加入「阅读 .claude-coder/test_rule.md 了解测试规范和成本控制」',
+      '  - 测试步骤按 test_rule.md 中的 tasks.json 模板格式编写（含环境检查、优先级标注、预算控制）',
+      '  - 设定合理的 test_tier（unit/smoke/regression/full_e2e）',
+    ].join('\n');
+  }
+
   return [
     // --- Primacy zone: role + identity ---
     '你是资深需求分析师，擅长将模糊需求分解为可执行的原子任务。',
@@ -285,12 +301,13 @@ function buildAddPrompt(instruction) {
     '5. 分解任务：每个任务对应一个独立可测试的功能单元，description 简明（40字内），steps 具体可操作',
     '6. 追加到 tasks.json，id 和 priority 从已有最大值递增，status: pending',
     '7. git add -A && git commit -m "chore: add new tasks"',
-    '8. 写入 session_result.json（格式：{ "session_result": "success", "task_id": "add-tasks", "status_before": "N/A", "status_after": "N/A", "git_commit": "hash", "tests_passed": false, "notes": "追加了 N 个任务：简述" }）',
+    '8. 写入 session_result.json（格式：{ "session_result": "success", "status_before": "N/A", "status_after": "N/A", "notes": "追加了 N 个任务：简述" }）',
     '',
 
     // --- Quality constraints ---
     taskGuide,
     '',
+    testRuleHint,
     '不修改已有任务，不实现代码。',
     '',
 

package/src/runner.js

@@ -286,7 +286,7 @@ async function run(requirement, opts = {}) {
     }
 
     log('info', '开始 harness 校验 ...');
-    const validateResult = await validate(headBefore);
+    const validateResult = await validate(headBefore, taskId);
 
     if (!validateResult.fatal) {
       if (validateResult.hasWarnings) {
@@ -302,7 +302,7 @@ async function run(requirement, opts = {}) {
         timestamp: new Date().toISOString(),
         result: 'success',
         cost: sessionResult.cost,
-        taskId: validateResult.sessionData?.task_id || taskId,
+        taskId,
         statusAfter: validateResult.sessionData?.status_after || null,
         notes: validateResult.sessionData?.notes || null,
       });
@@ -375,8 +375,20 @@ async function add(instruction, opts = {}) {
     process.exit(1);
   }
 
+  deployTestRule(p);
+
   await runAddSession(instruction, { projectRoot, ...opts });
   printStats();
 }
 
+function deployTestRule(p) {
+  const dest = path.join(p.loopDir, 'test_rule.md');
+  if (fs.existsSync(dest)) return;
+  if (!fs.existsSync(p.testRuleTemplate)) return;
+  try {
+    fs.copyFileSync(p.testRuleTemplate, dest);
+    log('ok', '已部署测试指导规则 → .claude-coder/test_rule.md');
+  } catch { /* ignore */ }
+}
+
 module.exports = { run, add };

package/src/session.js

@@ -132,6 +132,7 @@ async function runCodingSession(sessionNum, opts = {}) {
     enableStallDetection: true,
     stallTimeoutMs,
     enableEditGuard: true,
+    editThreshold: config.editThreshold,
   });
 
   indicator.start(sessionNum);

package/src/validator.js

@@ -43,10 +43,6 @@ function validateSessionResult() {
     return { valid: false, fatal: true, recoverable: false, reason: `无效 status_after: ${data.status_after}` };
   }
 
-  if (!data.task_id) {
-    log('warn', 'session_result.json 缺少 task_id (建议包含)');
-  }
-
   if (data.session_result === 'success') {
     log('ok', 'session_result.json 合法 (success)');
   } else {
@@ -83,7 +79,7 @@ function checkGitProgress(headBefore) {
   return { hasCommit: true, warning: false };
 }
 
-function checkTestCoverage() {
+function checkTestCoverage(taskId) {
   const p = paths();
 
   if (!fs.existsSync(p.testsFile) || !fs.existsSync(p.sessionResult)) return;
@@ -91,11 +87,9 @@ function checkTestCoverage() {
   try {
     const sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
     const tests = JSON.parse(fs.readFileSync(p.testsFile, 'utf8'));
-
-    const taskId = sr.task_id || '';
     const testCases = tests.test_cases || [];
 
-    if (sr.status_after === 'done' && sr.tests_passed) {
+    if (sr.status_after === 'done' && taskId) {
       const taskTests = testCases.filter(t => t.feature_id === taskId);
       if (taskTests.length > 0) {
         const failed = taskTests.filter(t => t.last_result === 'fail');
@@ -109,7 +103,7 @@ function checkTestCoverage() {
   } catch { /* ignore */ }
 }
 
-async function validate(headBefore) {
+async function validate(headBefore, taskId) {
   log('info', '========== 开始校验 ==========');
 
   let srResult = validateSessionResult();
@@ -123,7 +117,7 @@ async function validate(headBefore) {
     srResult.fatal = true;
   }
 
-  checkTestCoverage();
+  checkTestCoverage(taskId);
 
   const fatal = srResult.fatal;
   const hasWarnings = gitResult.warning || srResult.recoverable;

package/templates/CLAUDE.md

@@ -51,7 +51,7 @@
 | `.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` | 浏览器登录状态（cookies + localStorage） | 只读；由 `claude-coder auth` 生成，MCP 每次会话自动加载 |
 
 ### requirements.md 处理原则
 
@@ -97,12 +97,9 @@
 ```json
 {
   "session_result": "success | failed",
-  "task_id": "feat-xxx",
   "status_before": "pending | failed",
   "status_after": "done | failed | in_progress | testing",
-  "git_commit": "abc1234 或 null",
-  "tests_passed": true | false,
-  "notes": "本次会话的简要说明"
+  "notes": "本次做了什么 + 遇到的问题 + 给下一个会话的提醒"
 }
 ```
 
@@ -137,38 +134,17 @@
 
 ## 任务状态机（严格遵守）
 
-每个任务在 `tasks.json` 中有一个 `status` 字段，合法状态和迁移规则如下：
+每个任务在 `tasks.json` 中有一个 `status` 字段，合法迁移路径如下：
 
-```
-pending ──→ in_progress ──→ testing ──→ done
-                              │
-                              ▼
-                           failed ──→ in_progress（重试）
-```
-
-### 状态说明
-
-| 状态 | 含义 | 何时设置 |
+| 当前状态 | 可迁移至 | 触发条件 |
 |---|---|---|
-| `pending` | 未开始 | 初始状态 |
-| `in_progress` | 正在实现 | 你开始编码时 |
-| `testing` | 代码已写完，正在测试 | 代码完成、开始验证时 |
-| `done` | 测试通过，功能完成 | 端到端测试通过后 |
-| `failed` | 测试失败或实现有问题 | 测试未通过时 |
-
-### 迁移规则（铁律）
-
-- `pending` → `in_progress`：开始工作
-- `in_progress` → `testing`：代码写完，开始验证
-- `testing` → `done`：所有测试通过
-- `testing` → `failed`：测试未通过
-- `failed` → `in_progress`：重试修复
-
-**禁止的迁移**：
-- `pending` → `done`（不允许跳步）
-- `pending` → `testing`（必须先写代码）
-- `in_progress` → `done`（必须先测试）
-- 任何状态 → `pending`（不允许回退到未开始）
+| `pending` | `in_progress` | 开始编码 |
+| `in_progress` | `testing` | 代码写完，开始验证 |
+| `testing` | `done` | 所有测试通过 |
+| `testing` | `failed` | 测试未通过 |
+| `failed` | `in_progress` | 重试修复 |
+
+**禁止**：跳步（如 `pending` → `done`）、回退到 `pending`、未测试直接 `done`
 
 ---
 
@@ -247,18 +223,15 @@ pending ──→ in_progress ──→ testing ──→ done
 1. **后台服务管理**：根据 prompt 提示决定——单次模式（`--max 1`）时停止所有后台服务（`lsof -ti :端口 | xargs kill`）；连续模式时保持服务运行，下个 session 继续使用
 2. **按需更新文档和 profile**：
    - **README / 用户文档**：仅当对外行为变化（新增功能、API 变更、使用方式变化）时更新
-   - **架构 / API 文档**：如果本次新增了模块、改变了模块职责或新增了 API 端点，更新 `existing_docs` 中对应的架构或 API 文档。同时更新 `project_profile.json` 的 `existing_docs` 列表（若新增了文档文件）
+   - **项目指令文件**：如果本次新增了模块、改变了模块职责或新增了 API 端点，更新 `.claude/CLAUDE.md`。同时确保 `project_profile.json` 的 `existing_docs` 列表包含此文件
    - **profile 补全**：如果 prompt 中提示 `project_profile.json` 有缺陷（如 services 为空、existing_docs 为空），在此步骤补全。Harness 依赖 profile 做环境初始化和上下文注入
 3. **Git 提交**：`git add -A && git commit -m "feat(task-id): 功能描述"`
 4. **写入 session_result.json**（notes 要充分记录上下文供下次恢复）：
    ```json
    {
      "session_result": "success 或 failed",
-     "task_id": "当前任务 ID",
      "status_before": "任务开始时的状态",
      "status_after": "任务结束时的状态",
-     "git_commit": "本次提交的 hash",
-     "tests_passed": true 或 false,
      "notes": "本次做了什么 + 遇到的问题 + 给下一个会话的提醒"
    }
    ```

package/templates/SCAN_PROTOCOL.md

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

package/templates/test_rule.md

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

package/docs/PHASE_INJECTION_RESEARCH.md

@@ -1,325 +0,0 @@
-# 分阶段提示语注入 — 技术调研与方向探讨
-
-> 状态：调研阶段，仅探讨，未实现
-> 日期：2026-03-04
-> 背景：当前所有 10 个 Hint 在 session 开始前一次性注入 user prompt。本文探讨利用 Hook 的 `additionalContext` 能力，将提示语拆分到不同阶段按需注入。
-
----
-
-## 1. 当前架构
-
-### 提示语注入时机
-
-```mermaid
-sequenceDiagram
-    participant H as Harness
-    participant SDK as Claude Agent SDK
-    participant Agent as Agent (Model)
-
-    H->>H: buildSystemPrompt()<br/>CLAUDE.md (~260行)
-    H->>H: buildCodingPrompt()<br/>10 个 Hint 全部拼接
-    H->>SDK: query({ prompt, options })
-    Note over SDK,Agent: 所有提示语一次性加载
-    
-    loop Agent 自主运行
-        Agent->>SDK: 工具调用 (Read/Edit/Bash...)
-        SDK->>H: PreToolUse hook 回调
-        H->>H: inferPhaseStep() 更新 spinner
-        H->>H: 检查编辑循环
-        H-->>SDK: return {} (放行)
-        SDK->>Agent: 工具结果
-    end
-```
-
-### 问题
-
-| 问题 | 说明 |
-|------|------|
-| **Token 浪费** | 10 个 Hint 全部注入 user prompt，但大部分 Hint 仅在特定阶段有用（如 testHint 仅 Step 5 需要） |
-| **注意力稀释** | 一次性注入大量指令，模型在真正需要某条指令时可能已"忘记"（context rot） |
-| **时机错位** | 工具使用指导（Hint 10）在 Agent 还没开始读文件时就注入了，但 Agent 在 Step 4 编码阶段才真正需要这些规则 |
-| **无法纠正** | 当前 Hook 仅用于监控和死循环拦截，无法在 Agent 做出低效工具选择时即时纠正 |
-
----
-
-## 2. Hook 能力盘点
-
-### SDK 内联 Hook（当前使用方式）
-
-通过 `query()` 的 `options.hooks` 定义，进程内回调：
-
-```javascript
-sdk.query({
-  prompt,
-  options: {
-    hooks: {
-      PreToolUse: [{ matcher: '*', hooks: [async (input) => { ... }] }],
-      PostToolUse: [{ matcher: '*', hooks: [async (input) => { ... }] }],
-    }
-  }
-});
-```
-
-| Hook 事件 | SDK 内联支持 | 能力 |
-|-----------|-------------|------|
-| `PreToolUse` | 是 | `permissionDecision` (allow/deny/ask), `message`, **`additionalContext`** (v2.1.9+), `updatedInput` |
-| `PostToolUse` | 是 | `decision` (block), `reason`, **`additionalContext`** |
-| `UserPromptSubmit` | 是 | `decision` (block), `reason`, `additionalContext` |
-| `Stop` | 是 | `decision` (block), `reason` |
-| `SessionStart` | **否** (仅 CLI 声明式) | 不适用 |
-| `SessionEnd` | **否** (仅 CLI 声明式) | 不适用 |
-
-### `additionalContext` 关键特性
-
-- **作用**: 将文本注入 Agent 的 context window，Agent 在后续推理中可以看到并遵循
-- **注入位置**: 作为工具调用的附加上下文出现，紧邻工具结果
-- **注意力**: 因为紧跟当前工具调用，处于模型注意力的高峰区域（recency zone）
-- **限制**: 2026年1月新增，可能存在边缘 bug
-
-### `decision: 'block'` + `message`（当前已在用）
-
-- **作用**: 阻止工具调用，`message` 作为错误反馈传回模型
-- **注意力**: 模型会将其视为"操作失败"信息，遵循率高
-- **适用场景**: 拦截不当操作并引导替代方案
-
----
-
-## 3. 提议架构：分阶段注入
-
-### 核心思想
-
-**按 Agent 的工作阶段，在 Hook 中按需注入对应阶段的提示语。** 初始 prompt 仅包含最核心的内容（身份、任务、约束），其余指导在 Agent 进入相应阶段时即时注入。
-
-```mermaid
-sequenceDiagram
-    participant H as Harness
-    participant SDK as Claude Agent SDK
-    participant Agent as Agent
-
-    H->>SDK: query({ prompt: 精简版 })
-    Note over H: 仅注入: 身份 + 任务上下文 + 约束
-
-    rect rgb(200, 230, 255)
-        Note over Agent: Phase 1: 恢复上下文
-        Agent->>SDK: Read(.claude-coder/profile.json)
-        SDK->>H: PreToolUse
-        H-->>SDK: additionalContext: 路径提示 + 文档指引
-    end
-
-    rect rgb(200, 255, 200)
-        Note over Agent: Phase 2: 编码阶段
-        Agent->>SDK: Edit(src/app.ts)
-        SDK->>H: PreToolUse
-        H-->>SDK: additionalContext: 工具使用规范 + MultiEdit提示
-    end
-
-    rect rgb(255, 230, 200)
-        Note over Agent: Phase 3: 测试阶段
-        Agent->>SDK: Bash(curl ...)
-        SDK->>H: PreToolUse
-        H-->>SDK: additionalContext: 测试效率规则
-    end
-
-    rect rgb(230, 200, 255)
-        Note over Agent: Phase 4: 收尾阶段
-        Agent->>SDK: Bash(git commit)
-        SDK->>H: PreToolUse
-        H-->>SDK: additionalContext: 服务管理 + session_result 格式
-    end
-```
-
-### Hint 拆分方案
-
-| # | Hint | 当前位置 | 建议注入时机 | 注入方式 |
-|---|------|----------|-------------|----------|
-| 1 | `reqSyncHint` | user prompt | **保留在 user prompt** | 需求变更需要在 Step 1 就知道 |
-| 7 | `taskHint` | user prompt | **保留在 user prompt** | 任务上下文是 Agent 开始工作的前提 |
-| 8 | `memoryHint` | user prompt | **保留在 user prompt** | 上次会话记忆需要一开始就有 |
-| 5 | `envHint` | user prompt | **保留在 user prompt** | Step 2 环境检查需要一开始就知道 |
-| 2 | `mcpHint` | user prompt | PreToolUse (Bash: curl/test) | 测试时才需要知道 Playwright 可用 |
-| 3 | `testHint` | user prompt | PreToolUse (Bash: curl/test) | 测试时才需要避免重复验证 |
-| 4 | `docsHint` | user prompt | PreToolUse (Read: 首次读文件) | 读文件时提醒先读文档 |
-| 6 | `retryContext` | user prompt | **保留在 user prompt** | 重试上下文需要一开始就有 |
-| 9 | `serviceHint` | user prompt | PreToolUse (Bash: git) | 收尾时才需要知道是否停服务 |
-| 10 | `toolGuidance` | user prompt | PreToolUse (首次工具调用) | 开始使用工具时注入 |
-
-**结论**: 10 个 Hint 中，5 个适合保留在初始 prompt（1, 5, 6, 7, 8），5 个适合延迟注入到 Hook（2, 3, 4, 9, 10）。
-
-### 实现草案
-
-```javascript
-// session.js - PreToolUse hook 增强版（概念代码，仅供讨论）
-const injected = new Set(); // 跟踪已注入的 Hint，每个仅注入一次
-
-hooks: {
-  PreToolUse: [{
-    matcher: '*',
-    hooks: [async (input) => {
-      const name = input.tool_name;
-      const toolInput = input.tool_input || {};
-      let additionalContext = '';
-
-      // --- Phase: 读取文件 → 注入文档指引 ---
-      if (['Read', 'Glob', 'Grep', 'LS'].includes(name) && !injected.has('docs')) {
-        additionalContext += docsHint;      // Hint 4
-        injected.add('docs');
-      }
-
-      // --- Phase: 首次工具调用 → 注入工具使用规范 ---
-      if (!injected.has('toolGuide')) {
-        additionalContext += '\n' + toolGuidance;  // Hint 10
-        injected.add('toolGuide');
-      }
-
-      // --- Phase: 测试阶段 → 注入测试规则 ---
-      if (name === 'Bash') {
-        const cmd = toolInput.command || '';
-        if ((cmd.includes('curl') || cmd.includes('test') || cmd.includes('pytest'))
-            && !injected.has('test')) {
-          additionalContext += '\n' + testHint;   // Hint 3
-          additionalContext += '\n' + mcpHint;    // Hint 2
-          injected.add('test');
-        }
-
-        // --- Phase: Git 操作 → 注入收尾提示 ---
-        if (cmd.includes('git ') && !injected.has('service')) {
-          additionalContext += '\n' + serviceHint;  // Hint 9
-          injected.add('service');
-        }
-      }
-
-      // --- Bash 命令纠正（进阶） ---
-      if (name === 'Bash') {
-        const cmd = toolInput.command || '';
-        if (/\bgrep\b/.test(cmd) && !cmd.includes('rg ')) {
-          return {
-            permissionDecision: 'deny',
-            permissionDecisionReason: '请使用 Grep 工具替代 bash grep，效率更高且结果格式化更好。',
-          };
-        }
-        if (/\bfind\b/.test(cmd)) {
-          return {
-            permissionDecision: 'deny',
-            permissionDecisionReason: '请使用 Glob 工具替代 bash find。',
-          };
-        }
-        if (/\bcat\b/.test(cmd) && !cmd.includes('<<')) {
-          return {
-            permissionDecision: 'deny',
-            permissionDecisionReason: '请使用 Read 工具替代 bash cat。',
-          };
-        }
-      }
-
-      // --- 编辑循环检测（已有功能） ---
-      // ... existing loop detection code ...
-
-      // 注入上下文
-      if (additionalContext.trim()) {
-        return { additionalContext: additionalContext.trim() };
-      }
-      return {};
-    }]
-  }]
-}
-```
-
----
-
-## 4. Bash 命令拦截：工具纠正的最短路径
-
-在完整的分阶段注入之前，有一个**低成本高收益**的中间步骤：在 PreToolUse hook 中拦截 Agent 使用 Bash 执行低效命令（grep/find/cat/ls/head/tail），引导其使用专用工具。
-
-### 行为矩阵
-
-| Agent 执行 | Hook 行为 | 反馈给 Agent |
-|------------|----------|-------------|
-| `Bash: grep -r "pattern" .` | **deny** | "请使用 Grep 工具替代 bash grep" |
-| `Bash: find . -name "*.ts"` | **deny** | "请使用 Glob 工具替代 bash find" |
-| `Bash: cat src/app.ts` | **deny** | "请使用 Read 工具替代 bash cat" |
-| `Bash: ls -la` | **deny** | "请使用 LS 工具替代 bash ls" |
-| `Bash: head -20 file.txt` | **deny** | "请使用 Read 工具（支持 offset/limit）替代 bash head" |
-| `Bash: npm test` | allow | -- |
-| `Bash: git commit` | allow + additionalContext | 注入收尾提示 |
-
-### 优势
-
-- **确定性**: Hook 拦截是确定性的，不依赖模型是否"记住"了 prompt 中的工具规则
-- **即时纠正**: 在 Agent 犯错的那一刻就纠正，而不是等它浪费完 context
-- **渐进式**: 可以先实现拦截（deny + message），后续再加 additionalContext
-- **非 Claude 模型必需**: qwen/deepseek 等模型对 prompt 的遵循率不如 Claude，但 deny 是硬性拦截，模型无法绕过
-
-### 风险
-
-| 风险 | 缓解方案 |
-|------|----------|
-| 误拦截合法 Bash 命令（如 `cat <<EOF` heredoc） | 正则匹配需要排除 heredoc、管道等场景 |
-| 某些 grep 用法没有 Grep 工具替代（如 `grep -c`） | 只拦截简单模式，复杂 grep 放行 |
-| 过度拦截导致 Agent 陷入循环 | 每种拦截最多触发 2 次，第 3 次放行 |
-
----
-
-## 5. 与现有方案的对比
-
-| 维度 | 当前方案 | 分阶段注入 | Bash 拦截纠正 |
-|------|---------|-----------|-------------|
-| 实现复杂度 | 低 | 高 | 中 |
-| Token 效率 | 低（全量注入） | 高（按需注入） | 不变（不影响初始 prompt） |
-| 注意力效果 | 中（U型优化） | 高（时机精准） | 高（即时纠正，deny 不可忽略） |
-| 非 Claude 模型支持 | 中（靠 prompt） | 高（时机 + prompt） | **最高（硬性拦截）** |
-| 风险 | 低 | 中（additionalContext 较新） | 低（deny 已验证） |
-| 依赖 SDK 版本 | 无 | v2.1.9+（additionalContext） | 无（deny + message 已有） |
-
----
-
-## 6. 建议路线图
-
-### P0 — 立即可做（不依赖新 SDK 特性）
-
-**Bash 命令拦截纠正**
-
-在现有 PreToolUse hook 中增加 bash 命令检测，对 `grep`/`find`/`cat`/`ls`/`head`/`tail` 返回 `deny + message` 引导使用专用工具。这是最短路径、最高确定性的优化。
-
-### P1 — 短期（需要验证 additionalContext）
-
-**工具使用指导延迟注入**
-
-将 Hint 10（toolGuidance）从初始 prompt 移到 PreToolUse hook 的 `additionalContext`，在 Agent 首次使用工具时注入。验证 `additionalContext` 在非 Claude 模型上的效果。
-
-### P2 — 中期
-
-**测试/收尾阶段指导延迟注入**
-
-将 Hint 2/3/9 移到 PreToolUse hook，按阶段（test/git）触发注入。
-
-### P3 — 远期
-
-**完整分阶段注入**
-
-所有可延迟的 Hint 通过 Hook 按需注入。初始 prompt 仅保留身份、任务、约束。配合 `additionalContext` 的 PostToolUse 版本，实现"编码后注入代码审查提示"等高级场景。
-
----
-
-## 7. 学术/行业参考
-
-| 来源 | 核心概念 | 与本方案的关联 |
-|------|----------|---------------|
-| Anthropic Context Engineering (2025) | Context 是有限资源，需精心管理 | 按需注入减少 context 浪费 |
-| Claude Code System Prompt (gist) | 每个工具都有 "when to use / when NOT to use" 指导 | Hint 10 和 Bash 拦截复现这一设计 |
-| SWE-Agent (2024) ACI | Agent-Computer Interface 设计应优化工具发现和使用 | Hook 即时纠正是 ACI 的运行时优化 |
-| Anthropic "Writing effective tools for agents" (2025) | 工具设计影响 Agent 行为，工具在 context 中很显眼 | 扩展 allowedTools 让工具自然出现在模型视野 |
-| ContextBench (2025) | 复杂脚手架边际收益递减 | 不过度设计分阶段注入，先做确定性拦截 |
-
----
-
-## 8. 结论
-
-当前 harness 的提示语架构已经相当成熟（U型注意力 + 10个条件Hint + recency zone 注入）。下一步优化的核心方向是**从"一次性全量注入"向"按需分阶段注入"演进**，但需要渐进式推进：
-
-1. **先做 Bash 命令拦截**（P0）— 零风险，最高确定性，不依赖新 SDK 特性
-2. **验证 `additionalContext`**（P1）— 确认非 Claude 模型是否能看到并遵循
-3. **逐步迁移 Hint**（P2-P3）— 每次迁移一个 Hint，A/B 测试效果
-
-**核心原则：确定性拦截（Hook deny）> 即时注入（additionalContext）> 初始 prompt 指导（Hint）> 系统 prompt 规则（CLAUDE.md）**
-
-这个优先级排序体现了一个关键洞察：**越靠近行为发生的时刻，指导的遵循率越高**。