claude-coder 1.7.1 → 1.8.0

package/README.md

@@ -1,125 +1,177 @@
-# 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
+# Claude Coder
+
+**中文** | [English](docs/README.en.md)
+
+一个**长时间自运行的自主编码 Agent Harness**：基于 Claude Agent SDK，通过 Hook 提示注入引导模型行为，倒计时活跃度监控保障稳定运行，多 session 编排实现一句话需求到完整项目的全自动交付。
+
+### 亮点
+
+- **自动编码**：多 session 编排 + 倒计时活跃度监控 + git 回滚重试，Agent 可持续编码数小时不中断（[守护机制](design/session-guard.md)）
+- **自动审查**：定期自动运行代码审查（simplify），注入当前任务上下文，确保代码质量和任务对齐
+- **自动维护**：tasks.json 里程碑归档保持文件精简；文件损坏时 AI 自动修复，无需人工干预
+- **Hook 提示注入**：通过 JSON 配置在工具调用时向模型注入上下文引导，零代码修改即可扩展规则（[机制详解](design/hook-mechanism.md)）
+- **配置驱动**：支持 Claude 官方、Coding Plan 多模型路由、DeepSeek 等任意 Anthropic 兼容 API
+
+---
+
+## 快速上手
+
+```bash
+# 前置：安装 Claude Agent SDK
+npm install -g @anthropic-ai/claude-agent-sdk
+
+# 安装
+npm install -g claude-coder
+
+# 配置模型
+claude-coder setup
+
+# 进入项目目录
+cd your-project
+
+# 初始化项目（扫描技术栈、生成 profile）
+claude-coder init
+
+# 开始自动编码
+claude-coder run "实现用户注册和登录功能"
+```
+
+## 命令列表
+
+| 命令 | 说明 |
+|------|------|
+| `claude-coder setup` | 交互式配置（模型、MCP、安全限制、自动审查） |
+| `claude-coder init` | 初始化项目环境（扫描技术栈、生成 profile） |
+| `claude-coder plan "需求"` | 生成计划方案 |
+| `claude-coder plan -r [file]` | 从需求文件生成计划 |
+| `claude-coder plan --planOnly` | 仅生成计划文档，不分解任务 |
+| `claude-coder plan -i "需求"` | 交互模式，允许模型提问 |
+| `claude-coder run [需求]` | 自动编码循环 |
+| `claude-coder run --max 1` | 单次执行 |
+| `claude-coder run --dry-run` | 预览模式（查看任务队列） |
+| `claude-coder simplify [focus]` | 代码审查和简化 |
+| `claude-coder auth [url]` | 导出 Playwright 登录状态（session cookie 自动持久化） |
+| `claude-coder status` | 查看进度和成本 |
+
+**选项**：`--max N` 限制 session 数（默认 50），`--pause N` 每 N 个 session 暂停确认，`--model M` 指定模型。
+
+## 工作原理
+
+```
+需求输入 ─→ 项目扫描 ─→ 任务分解 ─→ 编码循环
+                                       │
+                                 ┌──────┴──────┐
+                                 │  Session N   │
+                                 │  Claude SDK  │
+                                 │  6 步流程    │
+                                 └──────┬──────┘
+                                        │
+                                   harness 校验
+                                        │
+                              通过 ─┬→ 下一个任务
+                                    │
+                              (定期) 自动审查 simplify
+                              (自动) 里程碑归档
+                                    │
+                              失败 → git 回滚 + 重试
+                              JSON 损坏 → AI 自动修复
+```
+
+每个 session 内，Agent 自主执行 6 步：恢复上下文 → 环境检查 → 选任务 → 编码 → 测试 → 收尾（git commit）。
+
+Harness 在循环间自动维护：
+- **自动审查**：每 N 个 session 运行 simplify，审查最近代码变更并注入当前任务上下文
+- **里程碑归档**：完成任务自动归档到 `completed_milestones`，保持 tasks.json 精简
+- **AI 修复**：tasks.json 等关键文件损坏时，自动启动 AI session 修复
+
+## 机制文档
+
+| 文档 | 说明 |
+|------|------|
+| [Hook 注入机制](design/hook-mechanism.md) | SDK Hook 调研、GuidanceInjector 三级匹配、配置格式、副作用评估 |
+| [Session 守护机制](design/session-guard.md) | 中断策略、倒计时活跃度检测、工具运行状态追踪、防刷屏 |
+| [技术架构](design/ARCHITECTURE.md) | 核心设计规则、模块职责、提示语注入架构 |
+| [测试凭证方案](docs/PLAYWRIGHT_CREDENTIALS.md) | Playwright 登录态导出、API Key 持久化 |
+| [SDK 使用指南](docs/CLAUDE_AGENT_SDK_GUIDE.md) | Claude Agent SDK 接口参考 |
+
+## 使用场景
+
+**新项目**：`claude-coder run "用 Express + React 做 Todo 应用"` — 自动搭建脚手架、分解任务、逐个实现。
+
+**已有项目**：`claude-coder run "新增头像上传功能"` — 先扫描现有代码和技术栈，再增量开发。
+
+**需求文档驱动**：`claude-coder plan -r requirements.md` 从需求文件生成计划并分解任务，再运行 `claude-coder run` 自动执行。
+
+**自动测试 + 登录态持久化**：
+
+```bash
+# 首次登录：浏览器打开 → 手动登录 → 关闭浏览器
+claude-coder auth http://localhost:9991
+
+# 验证登录态：再次运行，浏览器应直接进入已登录状态
+claude-coder auth http://localhost:9991
+```
+
+Session cookie 自动转为持久化（30 天有效），Agent 测试时通过 Playwright MCP 自动复用。详见 [测试凭证方案](docs/PLAYWRIGHT_CREDENTIALS.md)。
+
+## 模型支持
+
+| 提供商 | 说明 |
+|--------|------|
+| 默认 | Claude 官方模型，使用系统登录态 |
+| Coding Plan | 自建 API，推荐的多模型路由配置 |
+| API | DeepSeek 或其他 Anthropic 兼容 API |
+
+## 建议配置
+
+### 长时间自运行 Agent（最稳）
+
+```bash
+ANTHROPIC_DEFAULT_OPUS_MODEL=glm-5
+ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder-next
+ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder-plus
+ANTHROPIC_MODEL=kimi-k2.5
+```
+
+### 自用 Claude Code（最强）
+
+```bash
+ANTHROPIC_DEFAULT_OPUS_MODEL=qwen3-max-2026-01-23
+ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder-next
+ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder-plus
+ANTHROPIC_MODEL=glm-5
+```
+
+## 项目结构
+
+```
+your-project/
+  .claude-coder/              # 运行时数据（gitignored）
+    .env                    # 模型配置
+    project_profile.json    # 项目扫描结果
+    tasks.json              # 任务列表 + 状态
+    session_result.json     # 上次 session 结果
+    progress.json           # 会话历史 + 成本
+    tests.json              # 验证记录
+    test.env                # 测试凭证（Agent 按需创建）
+    .runtime/
+      logs/                 # 每 session 独立日志
+```
+
+## 常见问题
+
+**"Credit balance is too low"**：运行 `claude-coder setup` 重新配置 API Key。
+
+**中断恢复**：直接重新运行 `claude-coder run`，从上次中断处继续。
+
+**长时间无响应**：模型处理复杂任务时可能出现长思考间隔（indicator 显示黄色"工具执行中"或红色"无响应"），这是正常行为。超过阈值后 harness 自动中断并重试。通过 `claude-coder setup` 的安全限制配置或 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 调整。
+
+**跳过任务**：将 `.claude-coder/tasks.json` 中该任务的 `status` 改为 `done`。
+
+## 参考文章
+
+[Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+
+## License
+
+MIT

package/bin/cli.js

@@ -1,161 +1,159 @@
-#!/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);
-});
+#!/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' },
+  plan:      { desc: '生成计划方案',             usage: 'claude-coder plan "需求" | plan -r requirements.md [--planOnly] [-i]' },
+  simplify:  { desc: '代码审查和简化',           usage: 'claude-coder simplify [focus]' },
+  auth:      { desc: '导出 Playwright 登录状态', usage: 'claude-coder auth [url]' },
+  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 plan "实现用户登录"      生成计划方案');
+  console.log('  claude-coder plan -r requirements.md 从文件读取需求');
+  console.log('  claude-coder plan --planOnly         仅生成计划文档');
+  console.log('  claude-coder plan -i "优化系统"      交互模式，允许模型提问');
+  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 simplify               代码审查和简化');
+  console.log('  claude-coder simplify "内存效率"     聚焦特定领域审查');
+  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, n: 3, planOnly: false, interactive: false };
+  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 '-n':
+      case '--n':
+        opts.n = parseInt(args[++i], 10) || 3;
+        break;
+      case '-r': {
+        const next = args[i + 1];
+        if (next && !next.startsWith('-')) {
+          opts.readFile = next;
+          i++;
+        } else {
+          opts.readFile = 'requirements.md';
+        }
+        break;
+      }
+      case '--planOnly':
+        opts.planOnly = true;
+        break;
+      case '-i':
+      case '--interactive':
+        opts.interactive = true;
+        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/core/runner');
+      await runner.run(opts);
+      break;
+    }
+    case 'setup': {
+      const setup = require('../src/commands/setup');
+      await setup.setup();
+      break;
+    }
+    case 'init': {
+      const { init } = require('../src/core/init');
+      await init();
+      break;
+    }
+    case 'plan': {
+      const { run: planRun } = require('../src/core/plan');
+      const input = positional[0] || '';
+      await planRun(input, opts);
+      break;
+    }
+    case 'simplify': {
+      const { simplify } = require('../src/core/simplify');
+      await simplify(positional[0] || null, { n: opts.n });
+      break;
+    }
+    case 'auth': {
+      const { auth } = require('../src/commands/auth');
+      await auth(positional[0] || null);
+      break;
+    }
+    case 'status': {
+      const tasks = require('../src/common/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);
+});