claude-coder 1.0.3 → 1.0.5

package/docs/ARCHITECTURE.md

@@ -188,21 +188,23 @@ flowchart TB
 
 | Session 类型 | systemPrompt | user prompt | 触发条件 |
 |---|---|---|---|
-| **编码** | CLAUDE.md | `buildCodingPrompt()` + 6 个条件 hint | 主循环每次迭代 |
+| **编码** | CLAUDE.md | `buildCodingPrompt()` + 8 个条件 hint | 主循环每次迭代 |
 | **扫描** | CLAUDE.md + SCAN_PROTOCOL.md | `buildScanPrompt()` + 任务分解指导 | 首次运行 |
 | **观测** | CLAUDE.md (± SCAN_PROTOCOL.md) | `buildViewPrompt()` | `claude-coder view` |
 | **追加** | CLAUDE.md | `buildAddPrompt()` + 任务分解指导 | `claude-coder add` |
 
-### 编码 Session 的 6 个条件 Hint
+### 编码 Session 的 8 个条件 Hint
 
-| Hint | 触发条件 | 影响 |
-|---|---|---|
-| `reqSyncHint` | 需求 hash 变化 | Step 1：追加新任务 |
-| `mcpHint` | MCP_PLAYWRIGHT=true | Step 5：可用 Playwright |
-| `testHint` | tests.json 有记录 | Step 5：避免重复验证 |
-| `docsHint` | profile.existing_docs 非空 | Step 4：读文档后再编码，完成后更新文档 |
-| `envHint` | 连续成功且 session>1 | Step 2：跳过 init |
-| `retryContext` | 上次校验失败 | 全局：避免同样错误 |
+| # | 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 非空 | Step 4：读文档后再编码，完成后更新文档 |
+| 5 | `envHint` | 连续成功且 session>1 | Step 2：跳过 init |
+| 6 | `retryContext` | 上次校验失败 | 全局：避免同样错误 |
+| 7 | `taskHint` | tasks.json 存在且有待办任务 | Step 1：跳过读取 tasks.json，harness 已注入当前任务上下文 |
+| 8 | `memoryHint` | session_result.json 存在且有历史记录 | Step 1：跳过读取 session_result.json，harness 已注入上次会话摘要 |
 
 ---
 
@@ -270,7 +272,7 @@ sequenceDiagram
 | 维度 | 评分 | 说明 |
 |------|------|------|
 | **CLAUDE.md 系统提示** | 8/10 | U 型注意力设计；铁律清晰；状态机和 6 步流程是核心竞争力 |
-| **动态 prompt** | 8/10 | 5 个条件 hint 精准注入，不浪费 token |
+| **动态 prompt** | 8.5/10 | 8 个条件 hint 精准注入，含 task/memory 上下文注入，减少 Agent 冗余 Read 调用 |
 | **SCAN_PROTOCOL.md** | 8.5/10 | 新旧项目分支完整，profile 格式全面 |
 | **tests.json 设计** | 7.5/10 | 精简字段，核心目的（防反复测试）明确 |
 | **注入时机** | 9/10 | 静态规则 vs 动态上下文分离干净 |
@@ -278,7 +280,59 @@ sequenceDiagram
 
 ---
 
-## 9. Claude Agent SDK V1/V2 对比与迁移计划
+## 9. Context Injection 架构（v1.0.4+）
+
+### 设计原则
+
+**Harness 准备上下文，Agent 直接执行。** Agent 不应浪费工具调用读取 harness 已知的数据。
+
+### 优化前后对比
+
+```mermaid
+flowchart TD
+    subgraph before ["优化前：Agent 自行读取"]
+        A1[Agent starts] --> A2["Read tasks.json"]
+        A2 --> A3["Read profile.json"]
+        A3 --> A4["Read session_result.json"]
+        A4 --> A5["Read requirements.md"]
+        A5 --> A6["Read tests.json"]
+        A6 --> A7["开始编码（5+ Read 调用浪费）"]
+    end
+
+    subgraph after ["优化后：Harness 注入上下文"]
+        B1["Harness 预读文件"] --> B2["注入 Hint 7: 任务上下文"]
+        B1 --> B3["注入 Hint 8: 会话记忆"]
+        B2 --> B4["Agent prompt 就绪"]
+        B3 --> B4
+        B4 --> B5["Agent 直接开始编码"]
+    end
+```
+
+### Hint 7: 任务上下文注入
+
+Harness 在 `buildCodingPrompt()` 中预读 `tasks.json`，将下一个待办任务的 id、description、category、steps 数量和整体进度注入 user prompt。Agent 无需自行读取 `tasks.json`。
+
+### Hint 8: 会话记忆注入
+
+Harness 在 `buildCodingPrompt()` 中预读 `session_result.json`，将上次会话的 task_id、结果和 notes 摘要注入 user prompt。Agent 无需自行读取历史 session 数据。
+
+### Loop Detection（编辑死循环检测）
+
+PreToolUse hook 中追踪每个文件的编辑次数。当同一文件被 Write/Edit 超过 5 次时，hook 返回 `decision: "block"` 阻止操作并提示 Agent 重新审视方案。
+
+### 文件权限模型
+
+| 文件 | 写入方 | Agent 权限 |
+|------|--------|-----------|
+| `progress.json` | Harness | 只读 |
+| `sync_state.json` | Harness | 只读 |
+| `session_result.json` | Agent 写 `current`，Harness 归档到 `history` | 写 `current` |
+| `tasks.json` | Agent（仅 `status` 字段） | 修改 `status` |
+| `project_profile.json` | Agent（仅扫描阶段） | 扫描时写入 |
+
+---
+
+## 10. Claude Agent SDK V1/V2 对比与迁移计划
 
 当前使用 **V1 稳定 API**（`query()`），V2 为 preview 状态（`unstable_` 前缀）。
 
@@ -336,14 +390,13 @@ query({
 
 ---
 
-## 10. 后续优化方向
+## 11. 后续优化方向
 
 ### P0 — 近期
 
 | 方向 | 说明 |
 |------|------|
 | **文件保护 Deny-list** | PreToolUse hook 拦截对保护文件的写入（比文字规则更硬性） |
-| **TUI 终端监控** | 基于 ANSI 的全屏界面，替代单行 spinner |
 | **成本预算控制** | `.env` 新增 `MAX_COST_USD`，超预算自动停止 |
 
 ### P1 — 中期
@@ -359,6 +412,7 @@ query({
 
 | 方向 | 说明 |
 |------|------|
+| **TUI 终端监控** | 基于 ANSI 的全屏界面，替代单行 spinner |
 | **Web UI 监控** | 可选插件包 `@claude-coder/web-ui` |
 | **PR/CI 集成** | Session 完成后自动创建 PR、监控 CI |
 | **Prompt A/B 测试** | 多版本 CLAUDE.md 并行对比效果 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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/prompts.js

@@ -2,6 +2,17 @@
 
 const fs = require('fs');
 const { paths, loadConfig, getRequirementsHash } = 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.
@@ -79,6 +90,35 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     } catch { /* ignore */ }
   }
 
+  // Hint 7: Task context (harness pre-read, saves Agent 2-3 Read calls)
+  let taskHint = '';
+  try {
+    const taskData = loadTasks();
+    if (taskData) {
+      const next = findNextTask(taskData);
+      const stats = getStats(taskData);
+      if (next) {
+        taskHint = `任务上下文: ${next.id} "${next.description}" (${next.status}), ` +
+          `category=${next.category}, steps=${next.steps.length}步。` +
+          `进度: ${stats.done}/${stats.total} done, ${stats.failed} failed。` +
+          `第一步无需读取 tasks.json（已注入），直接确认任务后进入 Step 2。`;
+      }
+    }
+  } catch { /* ignore */ }
+
+  // Hint 8: Session memory (last session summary, recency zone for attention)
+  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)}` : '') + '。';
+      }
+    } catch { /* ignore */ }
+  }
+
   return [
     `Session ${sessionNum}。执行 6 步流程。`,
     '效率要求：先规划后编码，完成全部编码后再统一测试，禁止编码-测试反复跳转。后端任务用 curl 验证，不启动浏览器。',
@@ -87,6 +127,8 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     testHint,
     docsHint,
     envHint,
+    taskHint,
+    memoryHint,
     `完成后写入 session_result.json。${retryContext}`,
   ].filter(Boolean).join('\n');
 }

package/src/runner.js

@@ -100,7 +100,10 @@ function appendProgress(entry) {
   const p = paths();
   let progress = { sessions: [] };
   if (fs.existsSync(p.progressFile)) {
-    try { progress = JSON.parse(fs.readFileSync(p.progressFile, 'utf8').replace(/[\u201c\u201d]/g, '"')); } catch { /* reset */ }
+    try {
+      const text = fs.readFileSync(p.progressFile, 'utf8');
+      try { progress = JSON.parse(text); } catch { progress = JSON.parse(text.replace(/[\u201c\u201d]/g, '"')); }
+    } catch { /* reset */ }
   }
   if (!Array.isArray(progress.sessions)) progress.sessions = [];
   progress.sessions.push(entry);
@@ -111,7 +114,10 @@ function updateSessionHistory(sessionData, sessionNum) {
   const p = paths();
   let sr = { current: null, history: [] };
   if (fs.existsSync(p.sessionResult)) {
-    try { sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8').replace(/[\u201c\u201d]/g, '"')); } catch { /* reset */ }
+    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: [] };
     }

package/src/session.js

@@ -89,6 +89,9 @@ async function runCodingSession(sessionNum, opts = {}) {
 
   indicator.start(sessionNum);
 
+  const editCounts = {};
+  const EDIT_THRESHOLD = 5;
+
   try {
     const queryOpts = buildQueryOptions(config, opts);
     queryOpts.systemPrompt = systemPrompt;
@@ -97,6 +100,18 @@ async function runCodingSession(sessionNum, opts = {}) {
         matcher: '*',
         hooks: [async (input) => {
           inferPhaseStep(indicator, input.tool_name, input.tool_input);
+
+          const filePath = input.tool_input?.file_path || input.tool_input?.path || '';
+          if (['Write', 'Edit', 'MultiEdit'].includes(input.tool_name) && filePath) {
+            editCounts[filePath] = (editCounts[filePath] || 0) + 1;
+            if (editCounts[filePath] > EDIT_THRESHOLD) {
+              return {
+                decision: 'block',
+                message: `已对 ${filePath} 编辑 ${editCounts[filePath]} 次，疑似死循环。请重新审视方案后再继续。`,
+              };
+            }
+          }
+
           return {};
         }]
       }]

package/src/tasks.js

@@ -13,16 +13,20 @@ const TRANSITIONS = {
   done:        [],
 };
 
-function normalizeJson(text) {
-  return text
-    .replace(/[\u201c\u201d]/g, '"')
-    .replace(/[\u2018\u2019]/g, "'");
+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 JSON.parse(normalizeJson(fs.readFileSync(p.tasksFile, 'utf8')));
+  return safeJsonParse(fs.readFileSync(p.tasksFile, 'utf8'));
 }
 
 function saveTasks(data) {

package/src/validator.js

@@ -4,8 +4,14 @@ const fs = require('fs');
 const { execSync } = require('child_process');
 const { paths, log, getProjectRoot } = require('./config');
 
-function normalizeJson(text) {
-  return text.replace(/[\u201c\u201d]/g, '"').replace(/[\u2018\u2019]/g, "'");
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return JSON.parse(
+      text.replace(/[\u201c\u201d]/g, '"').replace(/[\u2018\u2019]/g, "'")
+    );
+  }
 }
 
 function validateSessionResult() {
@@ -18,7 +24,7 @@ function validateSessionResult() {
 
   let data;
   try {
-    data = JSON.parse(normalizeJson(fs.readFileSync(p.sessionResult, 'utf8')));
+    data = safeJsonParse(fs.readFileSync(p.sessionResult, 'utf8'));
   } catch {
     log('error', 'session_result.json JSON 格式错误');
     return { valid: false, fatal: true, reason: 'JSON 格式错误' };
@@ -90,9 +96,9 @@ function checkTestCoverage() {
   if (!fs.existsSync(p.testsFile) || !fs.existsSync(p.sessionResult)) return;
 
   try {
-    const sr = JSON.parse(normalizeJson(fs.readFileSync(p.sessionResult, 'utf8')));
+    const sr = safeJsonParse(fs.readFileSync(p.sessionResult, 'utf8'));
     const current = sr.current || sr;
-    const tests = JSON.parse(normalizeJson(fs.readFileSync(p.testsFile, 'utf8')));
+    const tests = safeJsonParse(fs.readFileSync(p.testsFile, 'utf8'));
 
     const taskId = current.task_id || '';
     const testCases = tests.test_cases || [];

package/templates/CLAUDE.md

@@ -175,10 +175,13 @@ pending ──→ in_progress ──→ testing ──→ done
 
 ### 第一步：恢复上下文
 
-1. 批量读取以下文件（一次工具调用）：`.claude-coder/project_profile.json`、`.claude-coder/tasks.json`、`.claude-coder/session_result.json`
-2. 如果 `session_result.json` 不存在或 history 为空，运行 `git log --oneline -20` 补充上下文
-3. 如果项目根目录存在 `requirements.md`，读取用户的详细需求和偏好（技术约束、样式要求等），作为本次会话的参考依据
-4. **需求同步（条件触发）**：如果 prompt 中提示"需求已变更"，读取 `requirements.md`，对比 `tasks.json`，将新增需求追加为 `pending` 任务。未提示则跳过
+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` 补充上下文
+4. 如果项目根目录存在 `requirements.md`，读取用户的详细需求和偏好（技术约束、样式要求等），作为本次会话的参考依据
+5. **需求同步（条件触发）**：如果 prompt 中提示"需求已变更"，读取 `requirements.md`，对比 `tasks.json`，将新增需求追加为 `pending` 任务。未提示则跳过
 
 ### 第二步：环境与健康检查