claude-coder 1.0.2 → 1.0.4

package/bin/cli.js

@@ -46,6 +46,9 @@ function parseArgs(argv) {
       case '--dry-run':
         opts.dryRun = true;
         break;
+      case '--view':
+        opts.viewMode = true;
+        break;
       case '--help':
       case '-h':
         showHelp();
@@ -78,7 +81,11 @@ async function main() {
   switch (command) {
     case 'run': {
       const runner = require('../src/runner');
-      await runner.run(positional[0] || null, opts);
+      if (opts.viewMode) {
+        await runner.view(positional[0] || null, opts);
+      } else {
+        await runner.run(positional[0] || null, opts);
+      }
       break;
     }
     case 'setup': {

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,14 +280,123 @@ sequenceDiagram
 
 ---
 
-## 9. 后续优化方向
+## 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_` 前缀）。
+
+### V1 vs V2 API 对比
+
+| 维度 | V1 `query()` | V2 `send()/stream()` |
+|------|-------------|---------------------|
+| **状态** | 稳定，生产可用 | `unstable_` 前缀，preview |
+| **入口函数** | `query({ prompt, options })` | `unstable_v2_createSession(opts)` / `unstable_v2_prompt()` |
+| **多轮会话** | 需手动管理 AsyncGenerator | `session.send()` + `session.stream()`，更简洁 |
+| **会话恢复** | `options.resume: sessionId` | `unstable_v2_resumeSession(id)` |
+| **Hooks** | `options.hooks: { PreToolUse, PostToolUse, ... }` | 未支持 |
+| **Subagents** | `options.agents: { name: AgentDefinition }` | 未支持 |
+| **Session Fork** | `options.forkSession: true` | 未支持 |
+| **Plugins** | `options.plugins: [{ type, path }]` | 未支持 |
+| **结构化输出** | `options.outputFormat: { type: 'json_schema', schema }` | 支持 |
+| **文件检查点** | `options.enableFileCheckpointing + rewindFiles()` | 未明确 |
+| **Cost Tracking** | `SDKResultMessage.total_cost_usd` | `SDKResultMessage.total_cost_usd` |
+| **权限控制** | `canUseTool`, `permissionMode`, `allowedTools`, `disallowedTools` | 继承 |
+
+### 当前实现使用的 V1 特性
+
+```javascript
+query({
+  prompt,
+  options: {
+    systemPrompt,                      // 注入 CLAUDE.md
+    allowedTools,                      // 工具白名单
+    permissionMode: 'bypassPermissions',
+    allowDangerouslySkipPermissions: true,
+    model,                             // 从 .env 传入
+    env,                               // 环境变量透传
+    settingSources: ['project'],       // 加载项目 CLAUDE.md
+    hooks: { PreToolUse: [...] },      // 实时 spinner 监控
+  }
+})
+```
+
+### V2 迁移条件（等待稳定后）
+
+1. V2 去掉 `unstable_` 前缀，正式发布
+2. V2 支持 Hooks（当前项目依赖 PreToolUse 做 spinner 和 activity log）
+3. V2 支持 Subagents（未来可能用于扫描 Agent / 编码 Agent 分离）
+
+### 可利用但尚未使用的 V1 特性
+
+| 特性 | 说明 | 优先级 |
+|------|------|--------|
+| `maxBudgetUsd` | SDK 内置成本上限，替代自研追踪 | P0 |
+| `effort` | 控制思考深度（`low`/`medium`/`high`/`max`） | P1 |
+| `enableFileCheckpointing` | 文件操作检查点，比 git reset 更精细 | P1 |
+| `outputFormat` | 结构化输出，让 Agent 直接输出 JSON 格式 | P1 |
+| `agents` | 定义子 Agent，不同模型/工具集 | P2 |
+| `betas` | 扩展上下文窗口 | P2 |
+
+---
+
+## 11. 后续优化方向
 
 ### P0 — 近期
 
 | 方向 | 说明 |
 |------|------|
 | **文件保护 Deny-list** | PreToolUse hook 拦截对保护文件的写入（比文字规则更硬性） |
-| **TUI 终端监控** | 基于 ANSI 的全屏界面，替代单行 spinner |
 | **成本预算控制** | `.env` 新增 `MAX_COST_USD`，超预算自动停止 |
 
 ### P1 — 中期
@@ -301,6 +412,7 @@ sequenceDiagram
 
 | 方向 | 说明 |
 |------|------|
+| **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.2",
+  "version": "1.0.4",
   "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,11 @@
 
 const fs = require('fs');
 const { paths, loadConfig, getRequirementsHash } = require('./config');
+const { loadTasks, findNextTask, getStats } = require('./tasks');
+
+function normalizeJson(text) {
+  return text.replace(/[\u201c\u201d]/g, '"').replace(/[\u2018\u2019]/g, "'");
+}
 
 /**
  * Build system prompt by combining template files.
@@ -79,6 +84,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 = JSON.parse(normalizeJson(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 +121,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,7 @@ function appendProgress(entry) {
   const p = paths();
   let progress = { sessions: [] };
   if (fs.existsSync(p.progressFile)) {
-    try { progress = JSON.parse(fs.readFileSync(p.progressFile, 'utf8')); } catch { /* reset */ }
+    try { progress = JSON.parse(fs.readFileSync(p.progressFile, 'utf8').replace(/[\u201c\u201d]/g, '"')); } catch { /* reset */ }
   }
   if (!Array.isArray(progress.sessions)) progress.sessions = [];
   progress.sessions.push(entry);
@@ -111,7 +111,7 @@ 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')); } catch { /* reset */ }
+    try { sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8').replace(/[\u201c\u201d]/g, '"')); } catch { /* reset */ }
     if (!sr.history && sr.session_result) {
       sr = { current: sr, history: [] };
     }

package/src/session.js

@@ -62,10 +62,11 @@ function extractResult(messages) {
   return null;
 }
 
-function logMessage(message, logStream) {
+function logMessage(message, logStream, indicator) {
   if (message.type === 'assistant' && message.message?.content) {
     for (const block of message.message.content) {
       if (block.type === 'text' && block.text) {
+        if (indicator) process.stderr.write('\r\x1b[K');
         process.stdout.write(block.text);
         if (logStream) logStream.write(block.text);
       }
@@ -88,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;
@@ -96,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 {};
         }]
       }]
@@ -106,7 +122,7 @@ async function runCodingSession(sessionNum, opts = {}) {
     const collected = [];
     for await (const message of session) {
       collected.push(message);
-      logMessage(message, logStream);
+      logMessage(message, logStream, indicator);
     }
 
     logStream.end();
@@ -168,7 +184,7 @@ async function runScanSession(requirement, opts = {}) {
     const collected = [];
     for await (const message of session) {
       collected.push(message);
-      logMessage(message, logStream);
+      logMessage(message, logStream, indicator);
     }
 
     logStream.end();

package/src/tasks.js

@@ -13,10 +13,16 @@ const TRANSITIONS = {
   done:        [],
 };
 
+function normalizeJson(text) {
+  return text
+    .replace(/[\u201c\u201d]/g, '"')
+    .replace(/[\u2018\u2019]/g, "'");
+}
+
 function loadTasks() {
   const p = paths();
   if (!fs.existsSync(p.tasksFile)) return null;
-  return JSON.parse(fs.readFileSync(p.tasksFile, 'utf8'));
+  return JSON.parse(normalizeJson(fs.readFileSync(p.tasksFile, 'utf8')));
 }
 
 function saveTasks(data) {

package/src/validator.js

@@ -4,6 +4,10 @@ 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 validateSessionResult() {
   const p = paths();
 
@@ -14,7 +18,7 @@ function validateSessionResult() {
 
   let data;
   try {
-    data = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
+    data = JSON.parse(normalizeJson(fs.readFileSync(p.sessionResult, 'utf8')));
   } catch {
     log('error', 'session_result.json JSON 格式错误');
     return { valid: false, fatal: true, reason: 'JSON 格式错误' };
@@ -86,9 +90,9 @@ function checkTestCoverage() {
   if (!fs.existsSync(p.testsFile) || !fs.existsSync(p.sessionResult)) return;
 
   try {
-    const sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
+    const sr = JSON.parse(normalizeJson(fs.readFileSync(p.sessionResult, 'utf8')));
     const current = sr.current || sr;
-    const tests = JSON.parse(fs.readFileSync(p.testsFile, 'utf8'));
+    const tests = JSON.parse(normalizeJson(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` 任务。未提示则跳过
 
 ### 第二步：环境与健康检查