claude-coder 1.0.9 → 1.2.0

package/README.md

@@ -50,15 +50,17 @@ claude-coder run "实现用户注册和登录功能"
 |------|------|
 | `claude-coder setup` | 交互式模型配置 |
 | `claude-coder run [需求]` | 自动编码循环 |
+| `claude-coder run --max 1` | 单次执行 |
 | `claude-coder run --dry-run` | 预览模式 |
 | `claude-coder init` | 初始化项目环境 |
-| `claude-coder view [需求]` | 观测模式（交互式单次） |
-| `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/ |
 
-**选项**：`--max N` 限制 session 数（默认 50），`--pause N` 每 N 个 session 暂停（默认 5）。
+**选项**：`--max N` 限制 session 数（默认 50），`--pause N` 每 N 个 session 暂停确认（默认不暂停）。
 
 ## 使用场景
 
@@ -66,9 +68,9 @@ claude-coder run "实现用户注册和登录功能"
 
 **已有项目**：`claude-coder run "新增头像上传功能"` — 先扫描现有代码和技术栈，再增量开发。
 
-**需求文档驱动**：在项目根目录创建 `requirements.md`（可从模板复制），运行 `claude-coder run` — 修改需求后再次运行，自动同步新任务。
+**需求文档驱动**：在项目根目录创建 `requirements.md`，运行 `claude-coder run` — 需求变更后用 `claude-coder add -r` 同步新任务。
 
-**追加任务**：`claude-coder add "新增管理员后台"` — 仅追加到任务列表，下次 run 时执行。
+**追加任务**：`claude-coder add "新增管理员后台"` 或 `claude-coder add -r requirements.md` — 仅追加到任务列表，下次 run 时执行。
 
 ## 模型支持
 
@@ -88,10 +90,11 @@ your-project/
     .env                    # 模型配置
     project_profile.json    # 项目扫描结果
     tasks.json              # 任务列表 + 状态
-    session_result.json     # session 结果 + 历史
-    progress.json           # 会话日志 + 成本
+    session_result.json     # 上次 session 结果（扁平）
+    progress.json           # 会话历史 + 成本
     tests.json              # 验证记录
-    .runtime/               # 临时文件
+    test.env                # 测试凭证（API Key 等，可选）
+    .runtime/               # 临时文件（含日志）
   requirements.md           # 需求文档（可选）
 ```
 
@@ -108,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:      { 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' },
@@ -23,8 +23,12 @@ function showHelp() {
   console.log('\n示例:');
   console.log('  claude-coder setup                   配置模型和 API Key');
   console.log('  claude-coder run "实现用户登录"       开始自动编码');
-  console.log('  claude-coder run --max 1             单次执行（替代旧 view 模式）');
-  console.log('  claude-coder run --max 5 --dry-run   预览模式');
+  console.log('  claude-coder run --max 1             单次执行');
+  console.log('  claude-coder run --max 5 --pause 5   每 5 个 session 暂停确认');
+  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`);
 }
@@ -32,7 +36,7 @@ function showHelp() {
 function parseArgs(argv) {
   const args = argv.slice(2);
   const command = args[0];
-  const opts = { max: 50, pause: 5, dryRun: false };
+  const opts = { max: 50, pause: 0, dryRun: false, readFile: null, model: null };
   const positional = [];
 
   for (let i = 1; i < args.length; i++) {
@@ -46,6 +50,19 @@ 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('-')) {
+          opts.readFile = next;
+          i++;
+        } else {
+          opts.readFile = 'requirements.md';
+        }
+        break;
+      }
       case '--help':
       case '-h':
         showHelp();
@@ -92,12 +109,22 @@ async function main() {
       break;
     }
     case 'add': {
-      if (!positional[0]) {
-        console.error('用法: claude-coder add "任务描述"');
+      let instruction = positional[0] || '';
+      if (opts.readFile) {
+        const reqPath = require('path').resolve(opts.readFile);
+        if (!require('fs').existsSync(reqPath)) {
+          console.error(`文件不存在: ${reqPath}`);
+          process.exit(1);
+        }
+        instruction = require('fs').readFileSync(reqPath, 'utf8');
+        console.log(`已读取需求文件: ${opts.readFile}`);
+      }
+      if (!instruction) {
+        console.error('用法: claude-coder add "任务描述"  或  claude-coder add -r [requirements.md]');
         process.exit(1);
       }
       const runner = require('../src/runner');
-      await runner.add(positional[0], opts);
+      await runner.add(instruction, opts);
       break;
     }
     case 'validate': {

package/docs/ARCHITECTURE.md

@@ -191,16 +191,16 @@ flowchart TB
 
 | # | Hint | 触发条件 | 影响 |
 |---|---|---|---|
-| 1 | `reqSyncHint` | 需求 hash 变化 | Step 1：追加新任务 |
-| 2 | `mcpHint` | MCP_PLAYWRIGHT=true | Step 5：可用 Playwright |
-| 3 | `testHint` | tests.json 有记录 | Step 5：避免重复验证 |
-| 4 | `docsHint` | profile.existing_docs 非空或 profile 有缺陷 | Step 4：读文档后再编码；profile 缺陷时提示 Agent 在 Step 6 补全 services/docs |
-| 5 | `envHint` | 连续成功且 session>1 | Step 2：跳过 init |
-| 6 | `retryContext` | 上次校验失败 | 全局：避免同样错误 |
-| 7 | `taskHint` | tasks.json 存在且有待办任务 | Step 1：跳过读取 tasks.json，harness 已注入当前任务上下文 + .claude-coder/ 路径提示 |
-| 8 | `memoryHint` | session_result.json 存在且有历史记录 | Step 1：跳过读取 session_result.json，harness 已注入上次会话摘要 |
-| 9 | `serviceHint` | 始终注入 | Step 6：单次模式停止服务，连续模式保持服务运行 |
-| 10 | `toolGuidance` | 始终注入 | 全局：工具使用规范（Grep/Glob/Read/LS/MultiEdit/Task 替代 bash 命令），非 Claude 模型必需 |
+| 1 | `mcpHint` | MCP_PLAYWRIGHT=true | Step 5：可用 Playwright |
+| 2 | `retryContext` | 上次校验失败 | 全局：避免同样错误 |
+| 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 已注入当前任务上下文 + 项目绝对路径 |
+| 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 模型必需 |
 
 ---
 
@@ -268,7 +268,7 @@ sequenceDiagram
 | 维度 | 评分 | 说明 |
 |------|------|------|
 | **CLAUDE.md 系统提示** | 8/10 | U 型注意力设计；铁律清晰；状态机和 6 步流程是核心竞争力 |
-| **动态 prompt** | 9/10 | 10 个条件 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,12 +53,14 @@ 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/ |
 
-**Options**: `--max N` limit sessions (default 50), `--pause N` pause every N sessions (default 5).
+**Options**: `--max N` limit sessions (default 50), `--pause N` pause every N sessions (default: no pause).
 
 ## Model Support
 
@@ -78,16 +80,18 @@ your-project/
     .env                    # Model config
     project_profile.json    # Project scan results
     tasks.json              # Task list + status
-    session_result.json     # Session results + history
-    progress.json           # Session log + costs
+    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.0.9",
+  "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,8 +55,7 @@ function paths() {
     sessionResult:    path.join(loopDir, 'session_result.json'),
     profile:          path.join(loopDir, 'project_profile.json'),
     testsFile:        path.join(loopDir, 'tests.json'),
-    syncState:        path.join(loopDir, 'sync_state.json'),
-    reqHashFile:      path.join(loopDir, 'requirements_hash.current'),
+    testEnvFile:      path.join(loopDir, 'test.env'),
     claudeMd:         getTemplatePath('CLAUDE.md'),
     scanProtocol:     getTemplatePath('SCAN_PROTOCOL.md'),
     runtime,

package/src/indicator.js

@@ -59,6 +59,12 @@ class Indicator {
   }
 
   getStatusLine() {
+    const now = new Date();
+    const hh = String(now.getHours()).padStart(2, '0');
+    const mi = String(now.getMinutes()).padStart(2, '0');
+    const sc = String(now.getSeconds()).padStart(2, '0');
+    const clock = `${hh}:${mi}:${sc}`;
+
     const elapsed = Math.floor((Date.now() - this.startTime) / 1000);
     const mm = String(Math.floor(elapsed / 60)).padStart(2, '0');
     const ss = String(elapsed % 60).padStart(2, '0');
@@ -68,7 +74,7 @@ class Indicator {
       ? `${COLOR.yellow}思考中${COLOR.reset}`
       : `${COLOR.green}编码中${COLOR.reset}`;
 
-    let line = `${spinner} [Session ${this.sessionNum}] ${phaseLabel} ${mm}:${ss}`;
+    let line = `${spinner} [Session ${this.sessionNum}] ${clock} ${phaseLabel} ${mm}:${ss}`;
     if (this.step) line += ` | ${this.step}`;
     return line;
   }

package/src/prompts.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const fs = require('fs');
-const { paths, loadConfig, getRequirementsHash } = require('./config');
+const { paths, loadConfig, getProjectRoot } = require('./config');
 const { loadTasks, findNextTask, getStats } = require('./tasks');
 
 /**
@@ -26,40 +26,24 @@ function buildCodingPrompt(sessionNum, opts = {}) {
   const config = loadConfig();
   const consecutiveFailures = opts.consecutiveFailures || 0;
 
-  // Hint 1: Requirements change detection
-  const reqHash = getRequirementsHash();
-  let reqSyncHint = '';
-  if (reqHash) {
-    fs.writeFileSync(p.reqHashFile, reqHash, 'utf8');
-    let lastHash = '';
-    if (fs.existsSync(p.syncState)) {
-      try { lastHash = JSON.parse(fs.readFileSync(p.syncState, 'utf8')).last_requirements_hash || ''; } catch { /* ignore */ }
-    }
-    if (lastHash !== reqHash) {
-      reqSyncHint = '需求已变更：第一步中请读取 requirements.md，将新增需求追加为 pending 任务到 tasks.json。';
-    }
-  } else if (fs.existsSync(p.reqHashFile)) {
-    fs.unlinkSync(p.reqHashFile);
-  }
-
-  // Hint 2: Playwright MCP availability
+  // Hint 1: Playwright MCP availability
   const mcpHint = config.mcpPlaywright
     ? '前端/全栈任务可用 Playwright MCP（browser_navigate、browser_snapshot、browser_click 等）做端到端测试。'
     : '';
 
-  // Hint 3: Retry context from previous failures
+  // Hint 2: Retry context from previous failures
   let retryContext = '';
   if (consecutiveFailures > 0 && opts.lastValidateLog) {
     retryContext = `\n注意：上次会话校验失败，原因：${opts.lastValidateLog}。请避免同样的问题。`;
   }
 
-  // Hint 4: Environment readiness
+  // Hint 3: Environment readiness
   let envHint = '';
   if (consecutiveFailures === 0 && sessionNum > 1) {
     envHint = '环境已就绪，第二步可跳过 claude-coder init，仅确认服务存活。涉及新依赖时仍需运行 claude-coder init。';
   }
 
-  // Hint 5: Existing test records
+  // Hint 4: Existing test records
   let testHint = '';
   if (fs.existsSync(p.testsFile)) {
     try {
@@ -68,7 +52,7 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     } catch { /* ignore */ }
   }
 
-  // Hint 6: Project documentation awareness + profile quality check
+  // Hint 5: Project documentation awareness + profile quality check
   let docsHint = '';
   if (fs.existsSync(p.profile)) {
     try {
@@ -87,9 +71,10 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     } catch { /* ignore */ }
   }
 
-  // Hint 7: Task context (harness pre-read, saves Agent 2-3 Read calls)
+  // 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);
@@ -98,32 +83,38 @@ 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 8: Session memory (last session summary, recency zone for attention)
+  // 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)) {
     try {
       const sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
-      const last = sr.current || (sr.history?.length ? sr.history[sr.history.length - 1] : null);
-      if (last?.task_id) {
-        memoryHint = `上次会话: ${last.task_id} → ${last.status_after || last.session_result}` +
-          (last.notes ? `, 要点: ${last.notes.slice(0, 100)}` : '') + '。';
+      if (sr?.task_id) {
+        memoryHint = `上次会话: ${sr.task_id} → ${sr.status_after || sr.session_result}` +
+          (sr.notes ? `, 要点: ${sr.notes.slice(0, 100)}` : '') + '。';
       }
     } catch { /* ignore */ }
   }
 
-  // Hint 9: Service management (continuous vs single-shot mode)
+  // Hint 8: Service management (continuous vs single-shot mode)
   const maxSessions = opts.maxSessions || 50;
   const serviceHint = maxSessions === 1
     ? '单次模式：收尾时停止所有后台服务。'
     : '连续模式：收尾时不要停止后台服务，保持服务运行以便下个 session 继续使用。';
 
-  // Hint 10: Tool usage guidance (critical for non-Claude models)
+  // Hint 9: Tool usage guidance (critical for non-Claude models)
   const toolGuidance = [
     '可用工具与使用规范（严格遵守）：',
     '- 搜索文件名: Glob（如 **/*.ts），禁止 bash find',
@@ -139,12 +130,12 @@ function buildCodingPrompt(sessionNum, opts = {}) {
   return [
     `Session ${sessionNum}。执行 6 步流程。`,
     '效率要求：先规划后编码，完成全部编码后再统一测试，禁止编码-测试反复跳转。后端任务用 curl 验证，不启动浏览器。',
-    reqSyncHint,
     mcpHint,
     testHint,
     docsHint,
     envHint,
     taskHint,
+    testEnvHint,
     memoryHint,
     serviceHint,
     toolGuidance,

package/src/runner.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
 const { execSync } = require('child_process');
-const { paths, log, COLOR, loadConfig, ensureLoopDir, getProjectRoot, getRequirementsHash } = require('./config');
+const { paths, log, COLOR, loadConfig, ensureLoopDir, getProjectRoot } = require('./config');
 const { loadTasks, saveTasks, getFeatures, getStats, findNextTask } = require('./tasks');
 const { validate } = require('./validator');
 const { scan } = require('./scanner');
@@ -52,22 +52,71 @@ function allTasksDone() {
   return features.every(f => f.status === 'done');
 }
 
+function killServicesByProfile() {
+  const p = paths();
+  if (!fs.existsSync(p.profile)) return;
+  try {
+    const profile = JSON.parse(fs.readFileSync(p.profile, 'utf8'));
+    const services = profile.services || [];
+    const ports = services.map(s => s.port).filter(Boolean);
+    if (ports.length === 0) return;
+
+    const isWin = process.platform === 'win32';
+    for (const port of ports) {
+      try {
+        if (isWin) {
+          const out = execSync(`netstat -ano | findstr :${port} | findstr LISTENING`, { encoding: 'utf8', stdio: 'pipe' }).trim();
+          const pids = [...new Set(out.split('\n').map(l => l.trim().split(/\s+/).pop()).filter(Boolean))];
+          for (const pid of pids) { try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'pipe' }); } catch { /* ignore */ } }
+        } else {
+          execSync(`lsof -ti :${port} | xargs kill -9 2>/dev/null`, { stdio: 'pipe' });
+        }
+      } catch { /* no process on port */ }
+    }
+    log('info', `已停止端口 ${ports.join(', ')} 上的服务`);
+  } 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: 'inherit' });
-    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}`);
+      }
+    }
   }
 
-  // Record failure in progress.json
   appendProgress({
     type: 'rollback',
     timestamp: new Date().toISOString(),
     reason: reason || 'harness 校验失败',
     rollbackTo: headBefore,
+    success,
   });
 }
 
@@ -110,36 +159,6 @@ function appendProgress(entry) {
   fs.writeFileSync(p.progressFile, JSON.stringify(progress, null, 2) + '\n', 'utf8');
 }
 
-function updateSessionHistory(sessionData, sessionNum) {
-  const p = paths();
-  let sr = { current: null, history: [] };
-  if (fs.existsSync(p.sessionResult)) {
-    try {
-      const text = fs.readFileSync(p.sessionResult, 'utf8');
-      sr = JSON.parse(text);
-    } catch { /* reset */ }
-    if (!sr.history && sr.session_result) {
-      sr = { current: sr, history: [] };
-    }
-  }
-
-  // Move current to history
-  if (sr.current) {
-    sr.history.push({
-      session: sessionNum - 1,
-      timestamp: new Date().toISOString(),
-      ...sr.current,
-    });
-    sr.current = null;
-  }
-
-  if (sessionData) {
-    sr.current = sessionData;
-  }
-
-  fs.writeFileSync(p.sessionResult, JSON.stringify(sr, null, 2) + '\n', 'utf8');
-}
-
 function printStats() {
   const data = loadTasks();
   if (!data) return;
@@ -270,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 ? '上次校验失败' : '',
@@ -288,19 +310,6 @@ async function run(requirement, opts = {}) {
       tryPush();
       consecutiveFailures = 0;
 
-      // Update session history
-      updateSessionHistory(validateResult.sessionData, session);
-
-      // Update sync_state.json if requirements exist
-      const reqHash = getRequirementsHash();
-      if (reqHash) {
-        fs.writeFileSync(p.syncState, JSON.stringify({
-          last_requirements_hash: reqHash,
-          last_synced_at: new Date().toISOString(),
-        }, null, 2) + '\n', 'utf8');
-      }
-
-      // Append to progress.json
       appendProgress({
         session,
         timestamp: new Date().toISOString(),
@@ -308,6 +317,7 @@ async function run(requirement, opts = {}) {
         cost: sessionResult.cost,
         taskId: validateResult.sessionData?.task_id || null,
         statusAfter: validateResult.sessionData?.status_after || null,
+        notes: validateResult.sessionData?.notes || null,
       });
 
     } else {
@@ -325,7 +335,7 @@ async function run(requirement, opts = {}) {
     }
 
     // Periodic pause
-    if (session % pauseEvery === 0) {
+    if (pauseEvery > 0 && session % pauseEvery === 0) {
       console.log('');
       printStats();
       const shouldContinue = await promptContinue();
@@ -336,6 +346,9 @@ async function run(requirement, opts = {}) {
     }
   }
 
+  // Cleanup: stop services after loop ends
+  killServicesByProfile();
+
   // Final report
   console.log('');
   console.log('============================================');
@@ -351,6 +364,19 @@ async function add(instruction, opts = {}) {
   const projectRoot = getProjectRoot();
   ensureLoopDir();
 
+  const config = loadConfig();
+
+  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);
@@ -212,28 +222,43 @@ async function runAddSession(instruction, opts = {}) {
   const sdk = await loadSDK();
   const config = loadConfig();
   applyEnvConfig(config);
+  const indicator = new Indicator();
 
   const systemPrompt = buildSystemPrompt(false);
   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);
+  log('info', '正在追加任务...');
+
   try {
     const queryOpts = buildQueryOptions(config, opts);
     queryOpts.systemPrompt = systemPrompt;
+    queryOpts.hooks = {
+      PreToolUse: [{
+        matcher: '*',
+        hooks: [async (input) => {
+          inferPhaseStep(indicator, input.tool_name, input.tool_input);
+          return {};
+        }]
+      }]
+    };
 
     const session = sdk.query({ prompt, options: queryOpts });
 
     for await (const message of session) {
-      logMessage(message, logStream);
+      logMessage(message, logStream, indicator);
     }
 
     logStream.end();
+    indicator.stop();
     log('ok', '任务追加完成');
   } catch (err) {
     logStream.end();
+    indicator.stop();
     log('error', `任务追加失败: ${err.message}`);
   }
 }

package/src/validator.js

@@ -20,37 +20,35 @@ function validateSessionResult() {
     return { valid: false, fatal: true, reason: `JSON 解析失败: ${err.message}` };
   }
 
-  const sr = data.current || data;
-
   const required = ['session_result', 'status_after'];
-  const missing = required.filter(k => !(k in sr));
+  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(', ')}` };
   }
 
-  if (!['success', 'failed'].includes(sr.session_result)) {
-    log('error', `session_result 必须是 success 或 failed，实际是: ${sr.session_result}`);
-    return { valid: false, fatal: true, reason: `无效 session_result: ${sr.session_result}` };
+  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}` };
   }
 
   const validStatuses = ['pending', 'in_progress', 'testing', 'done', 'failed'];
-  if (!validStatuses.includes(sr.status_after)) {
-    log('error', `status_after 不合法: ${sr.status_after}`);
-    return { valid: false, fatal: true, reason: `无效 status_after: ${sr.status_after}` };
+  if (!validStatuses.includes(data.status_after)) {
+    log('error', `status_after 不合法: ${data.status_after}`);
+    return { valid: false, fatal: true, reason: `无效 status_after: ${data.status_after}` };
   }
 
-  if (!sr.task_id) {
+  if (!data.task_id) {
     log('warn', 'session_result.json 缺少 task_id (建议包含)');
   }
 
-  if (sr.session_result === 'success') {
+  if (data.session_result === 'success') {
     log('ok', 'session_result.json 合法 (success)');
   } else {
     log('warn', 'session_result.json 合法，但 Agent 报告失败 (failed)');
   }
 
-  return { valid: true, fatal: false, data: sr };
+  return { valid: true, fatal: false, data };
 }
 
 function checkGitProgress(headBefore) {
@@ -87,13 +85,12 @@ function checkTestCoverage() {
 
   try {
     const sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
-    const current = sr.current || sr;
     const tests = JSON.parse(fs.readFileSync(p.testsFile, 'utf8'));
 
-    const taskId = current.task_id || '';
+    const taskId = sr.task_id || '';
     const testCases = tests.test_cases || [];
 
-    if (current.status_after === 'done' && current.tests_passed) {
+    if (sr.status_after === 'done' && sr.tests_passed) {
       const taskTests = testCases.filter(t => t.feature_id === taskId);
       if (taskTests.length > 0) {
         const failed = taskTests.filter(t => t.last_result === 'fail');

package/templates/CLAUDE.md

@@ -49,7 +49,6 @@
 | `.claude-coder/tasks.json` | 功能任务列表，带状态跟踪 | 只能修改 `status` 字段 |
 | `.claude-coder/progress.json` | 跨会话记忆日志（外部循环自动维护） | 只读 |
 | `.claude-coder/session_result.json` | 本次会话的结构化输出 | 每次会话结束时覆盖写入 |
-| `.claude-coder/sync_state.json` | 需求同步状态（外部循环 session 成功后自动更新） | Agent 无需读写 |
 | `.claude-coder/tests.json` | 功能验证记录（轻量） | 可新增和更新；仅当功能涉及 API 或核心逻辑时记录 |
 
 ### requirements.md 处理原则
@@ -178,10 +177,9 @@ pending ──→ in_progress ──→ testing ──→ done
 1. **检查 prompt 注入的上下文**：
    - 如果 prompt 中包含"任务上下文"（Hint 7），说明 harness 已注入当前任务信息，**跳过读取 tasks.json**，直接确认任务后进入第二步
    - 如果 prompt 中包含"上次会话"（Hint 8），说明 harness 已注入上次会话摘要，**跳过读取 session_result.json 历史**
-2. 批量读取以下文件（一次工具调用，跳过已注入的）：`.claude-coder/project_profile.json`、`.claude-coder/tasks.json`（仅当无 Hint 7 时）、`.claude-coder/session_result.json`（仅当无 Hint 8 时）
-3. 如果 `session_result.json` 不存在或 history 为空且无 Hint 8，运行 `git log --oneline -20` 补充上下文
+2. 批量读取以下文件（一次工具调用，跳过已注入的）：`.claude-coder/project_profile.json`、`.claude-coder/tasks.json`（仅当无 Hint 6 时）
+3. 如果无 Hint 7 且 `session_result.json` 不存在，运行 `git log --oneline -20` 补充上下文
 4. 如果项目根目录存在 `requirements.md`，读取用户的详细需求和偏好（技术约束、样式要求等），作为本次会话的参考依据
-5. **需求同步（条件触发）**：如果 prompt 中提示"需求已变更"，读取 `requirements.md`，对比 `tasks.json`，将新增需求追加为 `pending` 任务。未提示则跳过
 
 ### 第二步：环境与健康检查