claude-coder 1.0.8 → 1.1.0

package/README.md

@@ -50,15 +50,16 @@ 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 -r [file]` | 从需求文件追加任务 |
 | `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 +67,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,8 +89,8 @@ your-project/
     .env                    # 模型配置
     project_profile.json    # 项目扫描结果
     tasks.json              # 任务列表 + 状态
-    session_result.json     # session 结果 + 历史
-    progress.json           # 会话日志 + 成本
+    session_result.json     # 上次 session 结果（扁平）
+    progress.json           # 会话历史 + 成本
     tests.json              # 验证记录
     .runtime/               # 临时文件
   requirements.md           # 需求文档（可选）

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 "指令" | 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,11 @@ 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 status                  查看进度和成本');
   console.log(`\n前置条件: npm install -g @anthropic-ai/claude-agent-sdk`);
 }
@@ -32,7 +35,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 };
   const positional = [];
 
   for (let i = 1; i < args.length; i++) {
@@ -46,6 +49,16 @@ function parseArgs(argv) {
       case '--dry-run':
         opts.dryRun = true;
         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 +105,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

@@ -183,24 +183,23 @@ flowchart TB
 
 | Session 类型 | systemPrompt | user prompt | 触发条件 |
 |---|---|---|---|
-| **编码** | CLAUDE.md | `buildCodingPrompt()` + 10 个条件 hint | 主循环每次迭代 |
+| **编码** | CLAUDE.md | `buildCodingPrompt()` + 9 个条件 hint | 主循环每次迭代 |
 | **扫描** | CLAUDE.md + SCAN_PROTOCOL.md | `buildScanPrompt()` + 任务分解指导 + profile 质量要求 | 首次运行 |
 | **追加** | CLAUDE.md | `buildAddPrompt()` + 任务分解指导 | `claude-coder add` |
 
-### 编码 Session 的 10 个条件 Hint
+### 编码 Session 的 9 个条件 Hint
 
 | # | 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 已注入当前任务上下文 + .claude-coder/ 路径提示 |
+| 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 +267,7 @@ sequenceDiagram
 | 维度 | 评分 | 说明 |
 |------|------|------|
 | **CLAUDE.md 系统提示** | 8/10 | U 型注意力设计；铁律清晰；状态机和 6 步流程是核心竞争力 |
-| **动态 prompt** | 9/10 | 10 个条件 hint 精准注入，含 task/memory 上下文注入 + 服务管理 + 工具使用指导，减少 Agent 冗余操作 |
+| **动态 prompt** | 9/10 | 9 个条件 hint 精准注入，含 task/memory 上下文注入 + 服务管理 + 工具使用指导，减少 Agent 冗余操作 |
 | **SCAN_PROTOCOL.md** | 8.5/10 | 新旧项目分支完整，profile 格式全面 |
 | **tests.json 设计** | 7.5/10 | 精简字段，核心目的（防反复测试）明确 |
 | **注入时机** | 9/10 | 静态规则 vs 动态上下文分离干净 |

package/docs/PHASE_INJECTION_RESEARCH.md

@@ -0,0 +1,325 @@
+# 分阶段提示语注入 — 技术调研与方向探讨
+
+> 状态：调研阶段，仅探讨，未实现
+> 日期：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）**
+
+这个优先级排序体现了一个关键洞察：**越靠近行为发生的时刻，指导的遵循率越高**。

package/docs/README.en.md

@@ -54,11 +54,12 @@ Each session, the agent autonomously follows 6 steps: restore context → env ch
 | `claude-coder run --dry-run` | Preview mode |
 | `claude-coder init` | Initialize project environment |
 | `claude-coder add "instruction"` | Append tasks |
+| `claude-coder add -r [file]` | Append tasks from requirements file |
 | `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,8 +79,8 @@ 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
   requirements.md           # Requirements (optional)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.0.8",
+  "version": "1.1.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,6 @@ 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'),
     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,19 +1,9 @@
 'use strict';
 
 const fs = require('fs');
-const { paths, loadConfig, getRequirementsHash } = require('./config');
+const { paths, loadConfig } = require('./config');
 const { loadTasks, findNextTask, getStats } = require('./tasks');
 
-function safeJsonParse(text) {
-  try {
-    return JSON.parse(text);
-  } catch {
-    return JSON.parse(
-      text.replace(/[\u201c\u201d]/g, '"').replace(/[\u2018\u2019]/g, "'")
-    );
-  }
-}
-
 /**
  * Build system prompt by combining template files.
  * @param {boolean} includeScanProtocol - Whether to append SCAN_PROTOCOL.md
@@ -36,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 {
@@ -78,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 {
@@ -97,7 +71,7 @@ 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 taskData = loadTasks();
@@ -114,26 +88,25 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     }
   } catch { /* ignore */ }
 
-  // Hint 8: Session memory (last session summary, recency zone for attention)
+  // Hint 7: Session memory (read flat session_result.json)
   let memoryHint = '';
   if (fs.existsSync(p.sessionResult)) {
     try {
-      const sr = safeJsonParse(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)}` : '') + '。';
+      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)}` : '') + '。';
       }
     } 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',
@@ -149,7 +122,6 @@ function buildCodingPrompt(sessionNum, opts = {}) {
   return [
     `Session ${sessionNum}。执行 6 步流程。`,
     '效率要求：先规划后编码，完成全部编码后再统一测试，禁止编码-测试反复跳转。后端任务用 curl 验证，不启动浏览器。',
-    reqSyncHint,
     mcpHint,
     testHint,
     docsHint,

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,17 +52,44 @@ 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 rollback(headBefore, reason) {
   if (!headBefore || headBefore === 'none') return;
+
+  killServicesByProfile();
+
   log('warn', `回滚到 ${headBefore} ...`);
   try {
-    execSync(`git reset --hard ${headBefore}`, { cwd: getProjectRoot(), stdio: 'inherit' });
+    execSync(`git reset --hard ${headBefore}`, { cwd: getProjectRoot(), stdio: 'pipe' });
     log('ok', '回滚完成');
   } catch (err) {
     log('error', `回滚失败: ${err.message}`);
   }
 
-  // Record failure in progress.json
   appendProgress({
     type: 'rollback',
     timestamp: new Date().toISOString(),
@@ -102,7 +129,7 @@ function appendProgress(entry) {
   if (fs.existsSync(p.progressFile)) {
     try {
       const text = fs.readFileSync(p.progressFile, 'utf8');
-      try { progress = JSON.parse(text); } catch { progress = JSON.parse(text.replace(/[\u201c\u201d]/g, '"')); }
+      progress = JSON.parse(text);
     } catch { /* reset */ }
   }
   if (!Array.isArray(progress.sessions)) progress.sessions = [];
@@ -110,36 +137,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');
-      try { sr = JSON.parse(text); } catch { sr = JSON.parse(text.replace(/[\u201c\u201d]/g, '"')); }
-    } 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;
@@ -247,6 +244,12 @@ async function run(requirement, opts = {}) {
     log('info', `Session ${session} / ${maxSessions}`);
     console.log('--------------------------------------------');
 
+    const taskData = loadTasks();
+    if (!taskData) {
+      log('error', 'tasks.json 无法读取，终止循环');
+      break;
+    }
+
     if (allTasksDone()) {
       console.log('');
       log('ok', '所有任务已完成！');
@@ -282,19 +285,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(),
@@ -302,6 +292,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 {
@@ -319,7 +310,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();
@@ -330,6 +321,9 @@ async function run(requirement, opts = {}) {
     }
   }
 
+  // Cleanup: stop services after loop ends
+  killServicesByProfile();
+
   // Final report
   console.log('');
   console.log('============================================');
@@ -345,6 +339,11 @@ async function add(instruction, opts = {}) {
   const projectRoot = getProjectRoot();
   ensureLoopDir();
 
+  const config = loadConfig();
+  if (config.provider !== 'claude' && config.baseUrl) {
+    log('ok', `模型配置已加载: ${config.provider}${config.model ? ` (${config.model})` : ''}`);
+  }
+
   if (!fs.existsSync(p.profile) || !fs.existsSync(p.tasksFile)) {
     log('error', 'add 需要先完成初始化（至少运行一次 claude-coder run）');
     process.exit(1);

package/src/session.js

@@ -212,6 +212,7 @@ 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);
@@ -220,20 +221,34 @@ async function runAddSession(instruction, opts = {}) {
   const logFile = path.join(p.logsDir, `add_tasks_${Date.now()}.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/tasks.js

@@ -13,20 +13,15 @@ const TRANSITIONS = {
   done:        [],
 };
 
-function safeJsonParse(text) {
-  try {
-    return JSON.parse(text);
-  } catch {
-    return JSON.parse(
-      text.replace(/[\u201c\u201d]/g, '"').replace(/[\u2018\u2019]/g, "'")
-    );
-  }
-}
-
 function loadTasks() {
   const p = paths();
   if (!fs.existsSync(p.tasksFile)) return null;
-  return safeJsonParse(fs.readFileSync(p.tasksFile, 'utf8'));
+  try {
+    return JSON.parse(fs.readFileSync(p.tasksFile, 'utf8'));
+  } catch (err) {
+    log('error', `tasks.json 解析失败: ${err.message}`);
+    return null;
+  }
 }
 
 function saveTasks(data) {

package/src/validator.js

@@ -4,16 +4,6 @@ const fs = require('fs');
 const { execSync } = require('child_process');
 const { paths, log, getProjectRoot } = require('./config');
 
-function safeJsonParse(text) {
-  try {
-    return JSON.parse(text);
-  } catch {
-    return JSON.parse(
-      text.replace(/[\u201c\u201d]/g, '"').replace(/[\u2018\u2019]/g, "'")
-    );
-  }
-}
-
 function validateSessionResult() {
   const p = paths();
 
@@ -24,43 +14,41 @@ function validateSessionResult() {
 
   let data;
   try {
-    data = safeJsonParse(fs.readFileSync(p.sessionResult, 'utf8'));
-  } catch {
-    log('error', 'session_result.json JSON 格式错误');
-    return { valid: false, fatal: true, reason: 'JSON 格式错误' };
+    data = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
+  } catch (err) {
+    log('error', `session_result.json 解析失败: ${err.message}`);
+    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) {
@@ -96,14 +84,13 @@ function checkTestCoverage() {
   if (!fs.existsSync(p.testsFile) || !fs.existsSync(p.sessionResult)) return;
 
   try {
-    const sr = safeJsonParse(fs.readFileSync(p.sessionResult, 'utf8'));
-    const current = sr.current || sr;
-    const tests = safeJsonParse(fs.readFileSync(p.testsFile, 'utf8'));
+    const sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
+    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` 任务。未提示则跳过
 
 ### 第二步：环境与健康检查