claude-coder 1.6.2 → 1.7.1

package/README.md

@@ -1,127 +1,125 @@
-# Claude Coder
-
-**中文** | [English](docs/README.en.md)
-
-受 [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) 启发，Claude Coder 是一个**自主编码 harness**，依托 Claude Agent SDK 的 `query()` 接口，提供项目扫描、任务分解、多 session 编排、自动校验与 git 回滚的能力，支持一句话需求或 `requirements.md` 驱动，兼容所有 Anthropic API 兼容的模型提供商。
-
-**核心思路**：AI Agent 单次会话上下文有限，大型需求容易丢失进度或产出不可用代码。本工具将 Agent 包装为一个**可靠的、可重试的函数** — harness 管理任务状态、校验每次产出、失败时自动回滚，Agent 只需专注于编码。
-
----
-
-## 快速上手
-
-```bash
-# 前置：安装 Claude Agent SDK
-npm install -g @anthropic-ai/claude-agent-sdk
-
-# 安装
-npm install -g claude-coder
-
-# 配置模型
-claude-coder setup
-
-# 开始自动编码
-cd your-project
-claude-coder run "实现用户注册和登录功能"
-```
-
-## 工作原理
-
-```
-需求输入 ─→ 项目扫描 ─→ 任务分解 ─→ 编码循环
-                                       │
-                                 ┌──────┴──────┐
-                                 │  Session N   │
-                                 │  Claude SDK  │
-                                 │  6 步流程    │
-                                 └──────┬──────┘
-                                        │
-                                   harness 校验
-                                        │
-                              通过 → 下一个任务
-                              失败 → git 回滚 + 重试
-```
-
-每个 session 内，Agent 自主执行 6 步：恢复上下文 → 环境检查 → 选任务 → 编码 → 测试 → 收尾（git commit）。
-
-## 命令
-
-| 命令 | 说明 |
-|------|------|
-| `claude-coder setup` | 交互式模型配置 |
-| `claude-coder run [需求]` | 自动编码循环 |
-| `claude-coder run --max 1` | 单次执行 |
-| `claude-coder run --dry-run` | 预览模式 |
-| `claude-coder init` | 初始化项目环境 |
-| `claude-coder add "指令"` | 追加任务 |
-| `claude-coder add -r [file]` | 从需求文件追加任务 |
-| `claude-coder add "..." --model M` | 指定模型追加任务 |
-| `claude-coder auth [url]` | 导出 Playwright 登录状态 |
-| `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 暂停确认（默认不暂停）。
-
-## 使用场景
-
-**新项目**：`claude-coder run "用 Express + React 做 Todo 应用"` — 自动搭建脚手架、分解任务、逐个实现。
-
-**已有项目**：`claude-coder run "新增头像上传功能"` — 先扫描现有代码和技术栈，再增量开发。
-
-**需求文档驱动**：在项目根目录创建 `requirements.md`，运行 `claude-coder run` — 需求变更后用 `claude-coder add -r` 同步新任务。
-
-**追加任务**：`claude-coder add "新增管理员后台"` 或 `claude-coder add -r requirements.md` — 仅追加到任务列表，下次 run 时执行。
-
-**自动测试 + 凭证持久化**：`claude-coder auth http://localhost:3000` — 导出浏览器登录态（cookies + localStorage），Agent 测试时自动使用。缺 API Key 时 Agent 会自行记录到 `test.env` 并继续推进，不会停工。详见 [测试凭证持久化方案](docs/PLAYWRIGHT_CREDENTIALS.md)。
-
-## 模型支持
-
-| 提供商 | 说明 |
-|--------|------|
-| Claude 官方 | 默认，Anthropic 原版 API |
-| GLM (智谱/Z.AI) | GLM 4.7 / GLM 5 |
-| 阿里云百炼 | qwen3-coder-plus / glm-5 |
-| DeepSeek | deepseek-chat / reasoner |
-| 自定义 | 任何 Anthropic 兼容 API |
-
-## 项目结构
-
-```
-your-project/
-  .claude-coder/              # 运行时数据（gitignored）
-    .env                    # 模型配置
-    project_profile.json    # 项目扫描结果
-    tasks.json              # 任务列表 + 状态
-    session_result.json     # 上次 session 结果（扁平）
-    progress.json           # 会话历史 + 成本
-    tests.json              # 验证记录
-    test.env                # 测试凭证（API Key 等，可选）
-    playwright-auth.json    # 登录状态快照（isolated 模式，auth 命令生成）
-    .runtime/               # 临时文件
-      logs/                 # 每 session 独立日志（含工具调用记录）
-      browser-profile/      # 持久化浏览器 Profile（persistent 模式，auth 命令生成）
-  requirements.md           # 需求文档（可选）
-```
-
-## 常见问题
-
-**"Credit balance is too low"**：运行 `claude-coder setup` 重新配置 API Key。
-
-**中断恢复**：直接重新运行 `claude-coder run`，会从上次中断处继续。
-
-**长时间无响应**：模型处理复杂文件时可能出现 10-20 分钟的思考间隔（spinner 会显示红色警告），这是正常行为。超过 30 分钟无工具调用时 Harness 会自动中断并重试。可通过 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 调整阈值。
-
-**跳过任务**：将 `.claude-coder/tasks.json` 中该任务的 `status` 改为 `done`。
-
-**Windows 支持**：完全支持，纯 Node.js 实现。
-
-## 文档
-
-- [技术架构](docs/ARCHITECTURE.md) — 核心设计规则、模块职责、提示语注入架构、注意力机制、Hook 数据流
-- [测试凭证持久化方案](docs/PLAYWRIGHT_CREDENTIALS.md) — 自动测试的凭证管理：Playwright 登录态导出、API Key 持久化、Agent 缺凭证时的行为策略
-
-## License
-
-MIT
+# Claude Coder
+
+**中文** | [English](docs/README.en.md)
+
+受 [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) 启发，Claude Coder 是一个**自主编码 harness**，依托 Claude Agent SDK 的 `query()` 接口，提供项目扫描、任务分解、多 session 编排、自动校验与 git 回滚的能力，支持一句话需求或 `requirements.md` 驱动，兼容所有 Anthropic API 兼容的模型提供商。
+
+**核心思路**：AI Agent 单次会话上下文有限，大型需求容易丢失进度或产出不可用代码。本工具将 Agent 包装为一个**可靠的、可重试的函数** — harness 管理任务状态、校验每次产出、失败时自动回滚，Agent 只需专注于编码。
+
+---
+
+## 快速上手
+
+```bash
+# 前置：安装 Claude Agent SDK
+npm install -g @anthropic-ai/claude-agent-sdk
+
+# 安装
+npm install -g claude-coder
+
+# 配置模型
+claude-coder setup
+
+# 开始自动编码
+cd your-project
+claude-coder run "实现用户注册和登录功能"
+```
+
+## 工作原理
+
+```
+需求输入 ─→ 项目扫描 ─→ 任务分解 ─→ 编码循环
+                                       │
+                                 ┌──────┴──────┐
+                                 │  Session N   │
+                                 │  Claude SDK  │
+                                 │  6 步流程    │
+                                 └──────┬──────┘
+                                        │
+                                   harness 校验
+                                        │
+                              通过 → 下一个任务
+                              失败 → git 回滚 + 重试
+```
+
+每个 session 内，Agent 自主执行 6 步：恢复上下文 → 环境检查 → 选任务 → 编码 → 测试 → 收尾（git commit）。
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `claude-coder setup` | 交互式模型配置 |
+| `claude-coder run [需求]` | 自动编码循环 |
+| `claude-coder run --max 1` | 单次执行 |
+| `claude-coder run --dry-run` | 预览模式 |
+| `claude-coder init` | 初始化项目环境 |
+| `claude-coder add "指令"` | 追加任务 |
+| `claude-coder add -r [file]` | 从需求文件追加任务 |
+| `claude-coder add "..." --model M` | 指定模型追加任务 |
+| `claude-coder auth [url]` | 导出 Playwright 登录状态 |
+| `claude-coder validate` | 手动校验 |
+| `claude-coder status` | 查看进度和成本 |
+
+**选项**：`--max N` 限制 session 数（默认 50），`--pause N` 每 N 个 session 暂停确认（默认不暂停）。
+
+## 使用场景
+
+**新项目**：`claude-coder run "用 Express + React 做 Todo 应用"` — 自动搭建脚手架、分解任务、逐个实现。
+
+**已有项目**：`claude-coder run "新增头像上传功能"` — 先扫描现有代码和技术栈，再增量开发。
+
+**需求文档驱动**：在项目根目录创建 `requirements.md`，运行 `claude-coder run` — 需求变更后用 `claude-coder add -r` 同步新任务。
+
+**追加任务**：`claude-coder add "新增管理员后台"` 或 `claude-coder add -r requirements.md` — 仅追加到任务列表，下次 run 时执行。
+
+**自动测试 + 凭证持久化**：`claude-coder auth http://localhost:3000` — 导出浏览器登录态（cookies + localStorage），Agent 测试时自动使用。缺 API Key 时 Agent 会自行记录到 `test.env` 并继续推进，不会停工。详见 [测试凭证持久化方案](docs/PLAYWRIGHT_CREDENTIALS.md)。
+
+## 模型支持
+
+| 提供商 | 说明 |
+|--------|------|
+| Claude 官方 | 默认，Anthropic 原版 API |
+| GLM (智谱/Z.AI) | GLM 4.7 / GLM 5 |
+| 阿里云百炼 | qwen3-coder-plus / glm-5 |
+| DeepSeek | deepseek-chat / reasoner |
+| 自定义 | 任何 Anthropic 兼容 API |
+
+## 项目结构
+
+```
+your-project/
+  .claude-coder/              # 运行时数据（gitignored）
+    .env                    # 模型配置
+    project_profile.json    # 项目扫描结果
+    tasks.json              # 任务列表 + 状态
+    session_result.json     # 上次 session 结果（扁平）
+    progress.json           # 会话历史 + 成本
+    tests.json              # 验证记录
+    test.env                # 测试凭证（API Key 等，可选）
+    playwright-auth.json    # 登录状态快照（isolated 模式，auth 命令生成）
+    .runtime/               # 临时文件
+      logs/                 # 每 session 独立日志（含工具调用记录）
+      browser-profile/      # 持久化浏览器 Profile（persistent 模式，auth 命令生成）
+  requirements.md           # 需求文档（可选）
+```
+
+## 常见问题
+
+**"Credit balance is too low"**：运行 `claude-coder setup` 重新配置 API Key。
+
+**中断恢复**：直接重新运行 `claude-coder run`，会从上次中断处继续。
+
+**长时间无响应**：模型处理复杂文件时可能出现 10-20 分钟的思考间隔（spinner 会显示红色警告），这是正常行为。超过 20 分钟无工具调用时 Harness 会自动中断并重试。可通过 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 调整阈值。
+
+**跳过任务**：将 `.claude-coder/tasks.json` 中该任务的 `status` 改为 `done`。
+
+**Windows 支持**：完全支持，纯 Node.js 实现。
+
+## 文档
+
+- [技术架构](docs/ARCHITECTURE.md) — 核心设计规则、模块职责、提示语注入架构、注意力机制、Hook 数据流
+- [测试凭证持久化方案](docs/PLAYWRIGHT_CREDENTIALS.md) — 自动测试的凭证管理：Playwright 登录态导出、API Key 持久化、Agent 缺凭证时的行为策略
+
+## License
+
+MIT

package/bin/cli.js

@@ -1,197 +1,161 @@
-#!/usr/bin/env node
-'use strict';
-
-const pkg = require('../package.json');
-
-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 "指令" [--model M] | add -r [file]' },
-  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 mcp <mode>' },
-};
-
-function showHelp() {
-  console.log(`\nClaude Coder v${pkg.version}\n`);
-  console.log('用法: claude-coder <command> [options]\n');
-  console.log('命令:');
-  for (const [name, info] of Object.entries(COMMANDS)) {
-    console.log(`  ${name.padEnd(10)} ${info.desc}`);
-  }
-  console.log('\n示例:');
-  console.log('  claude-coder setup                   配置模型和 API Key');
-  console.log('  claude-coder 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 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`);
-}
-
-function parseArgs(argv) {
-  const args = argv.slice(2);
-  const command = args[0];
-  const opts = { max: 50, pause: 0, dryRun: false, readFile: null, model: null };
-  const positional = [];
-
-  for (let i = 1; i < args.length; i++) {
-    switch (args[i]) {
-      case '--max':
-        opts.max = parseInt(args[++i], 10) || 50;
-        break;
-      case '--pause':
-        opts.pause = parseInt(args[++i], 10) || 5;
-        break;
-      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();
-        process.exit(0);
-        break;
-      default:
-        if (!args[i].startsWith('--')) {
-          positional.push(args[i]);
-        }
-        break;
-    }
-  }
-
-  return { command, positional, opts };
-}
-
-async function main() {
-  const { command, positional, opts } = parseArgs(process.argv);
-
-  if (!command || command === '--help' || command === '-h') {
-    showHelp();
-    process.exit(0);
-  }
-
-  if (command === '--version' || command === '-v') {
-    console.log(pkg.version);
-    process.exit(0);
-  }
-
-  switch (command) {
-    case 'run': {
-      const runner = require('../src/runner');
-      await runner.run(positional[0] || null, opts);
-      break;
-    }
-    case 'setup': {
-      const setup = require('../src/setup');
-      await setup.setup();
-      break;
-    }
-    case 'init': {
-      const { init } = require('../src/init');
-      await init();
-      break;
-    }
-    case 'add': {
-      const fs = require('fs');
-      const nodePath = require('path');
-      let instruction = positional[0] || '';
-      if (opts.readFile) {
-        const reqPath = nodePath.resolve(opts.readFile);
-        if (!fs.existsSync(reqPath)) {
-          console.error(`文件不存在: ${reqPath}`);
-          process.exit(1);
-        }
-        instruction = 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(instruction, opts);
-      break;
-    }
-    case 'auth': {
-      const { auth } = require('../src/auth');
-      await auth(positional[0] || null);
-      break;
-    }
-    case 'validate': {
-      const validator = require('../src/validator');
-      const result = await validator.validate();
-      process.exit(result.fatal ? 1 : 0);
-      break;
-    }
-    case 'status': {
-      const tasks = require('../src/tasks');
-      tasks.showStatus();
-      break;
-    }
-    case 'config': {
-      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 | config mcp <mode>');
-        process.exit(1);
-      }
-      break;
-    }
-    default:
-      console.error(`未知命令: ${command}`);
-      showHelp();
-      process.exit(1);
-  }
-}
-
-main().catch(err => {
-  console.error(`\n错误: ${err.message}`);
-  if (process.env.DEBUG) console.error(err.stack);
-  process.exit(1);
-});
+#!/usr/bin/env node
+'use strict';
+
+const pkg = require('../package.json');
+
+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: '追加任务并可选自动执行',   usage: 'claude-coder add "指令" [--model M] | add -r [file]' },
+  auth:     { desc: '导出 Playwright 登录状态', usage: 'claude-coder auth [url]' },
+  validate: { desc: '手动校验上次 session',     usage: 'claude-coder validate' },
+  status:   { desc: '查看任务进度和成本',       usage: 'claude-coder status' },
+};
+
+function showHelp() {
+  console.log(`\nClaude Coder v${pkg.version}\n`);
+  console.log('用法: claude-coder <command> [options]\n');
+  console.log('命令:');
+  for (const [name, info] of Object.entries(COMMANDS)) {
+    console.log(`  ${name.padEnd(10)} ${info.desc}`);
+  }
+  console.log('\n示例:');
+  console.log('  claude-coder setup                   配置模型和 API Key');
+  console.log('  claude-coder add "实现用户登录"       添加任务（询问是否自动执行）');
+  console.log('  claude-coder 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 -r                   从 requirements.md 追加任务');
+  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 status                  查看进度和成本');
+  console.log(`\n前置条件: npm install -g @anthropic-ai/claude-agent-sdk`);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+  const opts = { max: 50, pause: 0, dryRun: false, readFile: null, model: null };
+  const positional = [];
+
+  for (let i = 1; i < args.length; i++) {
+    switch (args[i]) {
+      case '--max':
+        opts.max = parseInt(args[++i], 10) || 50;
+        break;
+      case '--pause':
+        { const v = parseInt(args[++i], 10); opts.pause = (v >= 0 && !isNaN(v)) ? v : 5; }
+        break;
+      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();
+        process.exit(0);
+        break;
+      default:
+        if (!args[i].startsWith('--')) {
+          positional.push(args[i]);
+        }
+        break;
+    }
+  }
+
+  return { command, positional, opts };
+}
+
+async function main() {
+  const { command, positional, opts } = parseArgs(process.argv);
+
+  if (!command || command === '--help' || command === '-h') {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (command === '--version' || command === '-v') {
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  switch (command) {
+    case 'run': {
+      const runner = require('../src/runner');
+      await runner.run(opts);
+      break;
+    }
+    case 'setup': {
+      const setup = require('../src/setup');
+      await setup.setup();
+      break;
+    }
+    case 'init': {
+      const { init } = require('../src/init');
+      await init();
+      break;
+    }
+    case 'add': {
+      const fs = require('fs');
+      const nodePath = require('path');
+      let instruction = positional[0] || '';
+      if (opts.readFile) {
+        const reqPath = nodePath.resolve(opts.readFile);
+        if (!fs.existsSync(reqPath)) {
+          console.error(`文件不存在: ${reqPath}`);
+          process.exit(1);
+        }
+        instruction = 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(instruction, opts);
+      break;
+    }
+    case 'auth': {
+      const { auth } = require('../src/auth');
+      await auth(positional[0] || null);
+      break;
+    }
+    case 'validate': {
+      const validator = require('../src/validator');
+      const result = await validator.validate();
+      process.exit(result.fatal ? 1 : 0);
+      break;
+    }
+    case 'status': {
+      const tasks = require('../src/tasks');
+      tasks.showStatus();
+      break;
+    }
+    default:
+      console.error(`未知命令: ${command}`);
+      showHelp();
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(`\n错误: ${err.message}`);
+  if (process.env.DEBUG) console.error(err.stack);
+  process.exit(1);
+});