claude-coder 1.1.0 → 1.2.0

package/README.md

@@ -53,8 +53,9 @@ claude-coder run "实现用户注册和登录功能"
 | `claude-coder run --max 1` | 单次执行 |
 | `claude-coder run --dry-run` | 预览模式 |
 | `claude-coder init` | 初始化项目环境 |
-| `claude-coder add "指令"` | 追加任务 |
+| `claude-coder add "指令"` | 追加任务（默认用 opus 级模型推理） |
 | `claude-coder add -r [file]` | 从需求文件追加任务 |
+| `claude-coder add "..." --model M` | 指定模型追加任务 |
 | `claude-coder validate` | 手动校验 |
 | `claude-coder status` | 查看进度和成本 |
 | `claude-coder config sync` | 同步配置到 ~/.claude/ |
@@ -92,7 +93,8 @@ your-project/
     session_result.json     # 上次 session 结果（扁平）
     progress.json           # 会话历史 + 成本
     tests.json              # 验证记录
-    .runtime/               # 临时文件
+    test.env                # 测试凭证（API Key 等，可选）
+    .runtime/               # 临时文件（含日志）
   requirements.md           # 需求文档（可选）
 ```
 
@@ -109,6 +111,7 @@ your-project/
 ## 文档
 
 - [技术架构](docs/ARCHITECTURE.md) — 模块职责、提示语注入架构、注意力机制、Hook 数据流、后续优化方向
+- [Playwright 凭证持久化](docs/PLAYWRIGHT_CREDENTIALS.md) — 测试 cookies 和 API Key 管理方案
 
 ## License
 

package/bin/cli.js

@@ -7,7 +7,7 @@ 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]' },
   validate: { desc: '手动校验上次 session',     usage: 'claude-coder validate' },
   status:   { desc: '查看任务进度和成本',       usage: 'claude-coder status' },
   config:   { desc: '配置管理',                 usage: 'claude-coder config sync' },
@@ -28,6 +28,7 @@ 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 status                  查看进度和成本');
   console.log(`\n前置条件: npm install -g @anthropic-ai/claude-agent-sdk`);
 }
@@ -35,7 +36,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 +50,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('-')) {

package/docs/ARCHITECTURE.md

@@ -183,11 +183,11 @@ flowchart TB
 
 | Session 类型 | systemPrompt | user prompt | 触发条件 |
 |---|---|---|---|
-| **编码** | CLAUDE.md | `buildCodingPrompt()` + 9 个条件 hint | 主循环每次迭代 |
+| **编码** | CLAUDE.md | `buildCodingPrompt()` + 10 个条件 hint | 主循环每次迭代 |
 | **扫描** | CLAUDE.md + SCAN_PROTOCOL.md | `buildScanPrompt()` + 任务分解指导 + profile 质量要求 | 首次运行 |
 | **追加** | CLAUDE.md | `buildAddPrompt()` + 任务分解指导 | `claude-coder add` |
 
-### 编码 Session 的 9 个条件 Hint
+### 编码 Session 的 10 个条件 Hint
 
 | # | Hint | 触发条件 | 影响 |
 |---|---|---|---|
@@ -196,7 +196,8 @@ 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` | .claude-coder/test.env 存在 | 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 +268,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 动态上下文分离干净 |

package/docs/PLAYWRIGHT_CREDENTIALS.md

@@ -0,0 +1,131 @@
+# Playwright MCP 凭证持久化方案
+
+## 背景
+
+在使用 claude-coder 运行涉及前端测试的任务时，Playwright MCP 可能需要：
+1. 已登录状态的 cookies（如后台管理页面）
+2. API Key 等测试凭证（如 AI 生成功能需要真实 API 调用）
+
+本文档描述如何在 claude-coder 工作流中管理这些凭证。
+
+---
+
+## 方案 1: Playwright --storage-state（推荐用于 cookies）
+
+### 原理
+
+`@playwright/mcp` 支持 `--storage-state=<path>` 参数，加载预存的浏览器状态（cookies、localStorage）。
+
+### 步骤
+
+**1. 手动登录并导出状态**
+
+```bash
+# 启动 Playwright，手动登录后导出
+npx playwright codegen --save-storage=.claude-coder/playwright-auth.json http://localhost:3000
+```
+
+登录完成后关闭浏览器，状态自动保存到 `playwright-auth.json`。
+
+**2. 配置 MCP 使用保存的状态**
+
+在项目的 `.mcp.json`（Claude Code MCP 配置）中：
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--storage-state=.claude-coder/playwright-auth.json"
+      ]
+    }
+  }
+}
+```
+
+**3. 安全注意事项**
+
+```gitignore
+# .gitignore
+.claude-coder/playwright-auth.json
+```
+
+### 注意
+
+- 状态文件包含敏感 cookies，必须加入 `.gitignore`
+- cookies 有过期时间，需要定期重新导出
+- `--storage-state` 与 `--isolated` 模式配合使用效果最佳
+
+---
+
+## 方案 2: test.env（推荐用于 API Key）
+
+### 原理
+
+在 `.claude-coder/test.env` 中存放测试专用的环境变量（如 API Key）。claude-coder 会自动检测此文件存在，并通过 Hint 提示 Agent 在测试前加载它。
+
+### 步骤
+
+**1. 创建 test.env**
+
+```bash
+# .claude-coder/test.env
+OPENAI_API_KEY=sk-xxx
+ZHIPU_API_KEY=xxx.xxx
+TEST_USER_TOKEN=xxx
+```
+
+**2. Agent 自动感知**
+
+当 `.claude-coder/test.env` 存在时，harness 在编码 session 的 prompt 中注入提示：
+
+> 测试环境变量在 .claude-coder/test.env（含 API Key 等），测试前用 source .claude-coder/test.env 或 export 加载。
+
+Agent 在执行测试时会自动 `source` 该文件。
+
+**3. 安全注意事项**
+
+```gitignore
+# .gitignore
+.claude-coder/test.env
+```
+
+---
+
+## 方案 3: project_profile.json 中声明测试依赖
+
+在扫描阶段或手动编辑 `project_profile.json`，声明哪些测试需要真实 API Key：
+
+```json
+{
+  "test_dependencies": {
+    "real_api_key": true,
+    "required_env_vars": ["OPENAI_API_KEY", "ZHIPU_API_KEY"],
+    "env_file": ".claude-coder/test.env"
+  }
+}
+```
+
+Agent 在 Step 5 测试时，如果检测到 `preconditions.real_api_key: true`，会先检查环境变量是否可用，不可用则跳过该测试并标记为 `skip`。
+
+---
+
+## 最佳实践
+
+| 场景 | 推荐方案 |
+|------|----------|
+| 需要已登录状态测试页面 | 方案 1 (--storage-state) |
+| 需要 API Key 测试后端功能 | 方案 2 (test.env) |
+| 需要区分 mock 测试和集成测试 | 方案 3 (profile 声明) |
+| 以上组合 | 方案 1 + 2 + 3 |
+
+### 工作流示例
+
+```
+1. claude-coder setup        → 配置模型
+2. 创建 .claude-coder/test.env  → 填入 API Key
+3. npx playwright codegen ...   → 导出登录状态
+4. claude-coder run             → Agent 自动使用凭证测试
+```

package/docs/README.en.md

@@ -53,8 +53,9 @@ Each session, the agent autonomously follows 6 steps: restore context → env ch
 | `claude-coder run --max 1` | Single session (replaces old view mode) |
 | `claude-coder run --dry-run` | Preview mode |
 | `claude-coder init` | Initialize project environment |
-| `claude-coder add "instruction"` | Append tasks |
+| `claude-coder add "instruction"` | Append tasks (defaults to opus-class model) |
 | `claude-coder add -r [file]` | Append tasks from requirements file |
+| `claude-coder add "..." --model M` | Append tasks with specific model |
 | `claude-coder validate` | Manually validate last session |
 | `claude-coder status` | View progress and costs |
 | `claude-coder config sync` | Sync config to ~/.claude/ |
@@ -82,13 +83,15 @@ 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)
+    .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.2.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/config.js

@@ -55,6 +55,7 @@ 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'),
     claudeMd:         getTemplatePath('CLAUDE.md'),
     scanProtocol:     getTemplatePath('SCAN_PROTOCOL.md'),
     runtime,

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');
 
 /**
@@ -74,6 +74,7 @@ function buildCodingPrompt(sessionNum, opts = {}) {
   // Hint 6: Task context (harness pre-read, saves Agent 2-3 Read calls)
   let taskHint = '';
   try {
+    const projectRoot = getProjectRoot();
     const taskData = loadTasks();
     if (taskData) {
       const next = findNextTask(taskData);
@@ -82,12 +83,19 @@ 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
+  let testEnvHint = '';
+  const testEnvFile = paths().testEnvFile;
+  if (testEnvFile && fs.existsSync(testEnvFile)) {
+    testEnvHint = '测试环境变量在 .claude-coder/test.env（含 API Key 等），测试前用 source .claude-coder/test.env 或 export 加载。';
+  }
+
   // Hint 7: Session memory (read flat session_result.json)
   let memoryHint = '';
   if (fs.existsSync(p.sessionResult)) {
@@ -127,6 +135,7 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     docsHint,
     envHint,
     taskHint,
+    testEnvHint,
     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,
   });
 }
 
@@ -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 ? '上次校验失败' : '',
@@ -340,10 +365,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.provider === 'claude' || !config.baseUrl) {
+      opts.model = 'claude-sonnet-4-20250514';
+    }
   }
 
+  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);