claude-coder 1.4.0 → 1.5.1

package/README.md

@@ -98,7 +98,8 @@ your-project/
     tests.json              # 验证记录
     test.env                # 测试凭证（API Key 等，可选）
     playwright-auth.json    # Playwright 登录状态（可选，auth 命令生成）
-    .runtime/               # 临时文件（含日志）
+    .runtime/               # 临时文件
+      logs/                 # 每 session 独立日志（含工具调用记录）
   requirements.md           # 需求文档（可选）
 ```
 
@@ -108,6 +109,8 @@ your-project/
 
 **中断恢复**：直接重新运行 `claude-coder run`，会从上次中断处继续。
 
+**长时间无响应**：模型处理复杂文件时可能出现 10-20 分钟的思考间隔（spinner 会显示红色警告），这是正常行为。超过 30 分钟无工具调用时 Harness 会自动中断并重试。可通过 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 调整阈值。
+
 **跳过任务**：将 `.claude-coder/tasks.json` 中该任务的 `status` 改为 `done`。
 
 **Windows 支持**：完全支持，纯 Node.js 实现。

package/docs/ARCHITECTURE.md

@@ -21,9 +21,12 @@ Agent 在单次 session 中应最大化推进任务进度。**任何非致命问
 - 缺少 API Key → 用 mock 或代码逻辑验证替代，记录到 `test.env`，继续推进
 - 测试环境未就绪 → 跳过该测试步骤，完成其余可验证的步骤
 - 服务启动失败 → 尝试排查修复，无法修复则记录问题后推进代码实现
+- **长时间思考是正常行为**：模型处理大文件（如 500+ 行的代码文件）时可能出现 10-20 分钟的思考间隔，不代表卡死
 
 **反面案例**：Agent 因 `OPENAI_API_KEY` 缺失直接标记任务 `failed` → 浪费整个 session
 
+> Harness 兜底机制：当工具调用间隔超过 `SESSION_STALL_TIMEOUT`（默认 30 分钟）时自动中断 session 并触发 rollback + 重试。此阈值设计为远超正常思考时长，仅捕捉真正的卡死场景。
+
 ### 规则 2：回滚即彻底回滚
 
 `git reset --hard` 是全量回滚，不做部分文件保护。
@@ -56,6 +59,16 @@ Agent 在单次 session 中应最大化推进任务进度。**任何非致命问
 
 Agent 不应浪费工具调用读取 harness 已知的数据。所有可预读的上下文通过 prompt hint 注入（见第 5 节 Prompt 注入架构）。
 
+### 规则 6：停顿检测 — 模型卡死自动恢复
+
+模型可能长时间「思考」但不调用工具（20+ 分钟无进展）。Harness 通过 PreToolUse hook 追踪最后一次工具调用时间：
+
+- 无工具调用 > `SESSION_STALL_TIMEOUT`（默认 1800 秒 / 30 分钟） → 自动中断 session
+- 中断后进入 runner 的重试逻辑（连续失败 ≥ 3 次 → 标记 task failed）
+- Spinner 在无工具调用 > 2 分钟时显示红色警告
+
+配置方式：`.claude-coder/.env` 中设置 `SESSION_STALL_TIMEOUT=1800`（秒）
+
 ---
 
 ## 1. 核心架构
@@ -79,7 +92,7 @@ flowchart TB
         direction TB
         profile["project_profile.json<br/>tasks.json"]
         runtime["session_result.json<br/>progress.json"]
-        phase[".runtime/<br/>phase / step / activity.log"]
+        phase[".runtime/<br/>phase / step / logs/"]
     end
 
     scan -->|"systemPrompt =<br/>CLAUDE.md + SCAN_PROTOCOL.md"| query
@@ -96,7 +109,8 @@ flowchart TB
 **核心特征：**
 - **项目无关**：项目信息由 Agent 扫描后存入 `project_profile.json`，harness 不含项目特定逻辑
 - **可恢复**：通过 `session_result.json` 跨会话记忆，任意 session 可断点续跑
-- **可观测**：SDK 内联 `PreToolUse` hook 实时显示 Agent 当前步骤和工具调用
+- **可观测**：SDK 内联 `PreToolUse` hook 实时显示当前工具、操作目标和停顿警告
+- **自愈**：编辑死循环检测 + 停顿超时自动中断 + runner 重试机制
 - **跨平台**：纯 Node.js 实现，macOS / Linux / Windows 通用
 - **零依赖**：`dependencies` 为空，Claude Agent SDK 作为 peerDependency
 
@@ -144,14 +158,14 @@ bin/cli.js          CLI 入口：参数解析、命令路由、SDK peerDep 检
 src/
   config.js         配置管理：.env 加载、模型映射、环境变量构建、全局同步
   runner.js         主循环：scan → session → validate → retry/rollback
-  session.js        SDK 交互：query() 调用、hook 绑定、日志流
+  session.js        SDK 交互：query() 调用、hook 绑定、停顿检测、日志流
   prompts.js        提示语构建：系统 prompt 组合 + 条件 hint + 任务分解指导
   init.js           环境初始化：读取 profile 执行依赖安装、服务启动、健康检查
   scanner.js        初始化扫描：调用 runScanSession + 重试
   validator.js      校验引擎：分层校验（fatal/recoverable/pass）+ git 检查 + 测试覆盖
   tasks.js          任务管理：CRUD + 状态机 + 进度展示
   auth.js           Playwright 凭证：导出登录状态 + MCP 配置 + gitignore
-  indicator.js      进度指示：终端 spinner + phase/step 文件写入
+  indicator.js      进度指示：终端 spinner + 工具目标显示 + 停顿警告 + phase/step 文件写入
   setup.js          交互式配置：模型选择、API Key、MCP 工具
 templates/
   CLAUDE.md         Agent 协议（注入为 systemPrompt）
@@ -193,7 +207,7 @@ templates/
 | `session_result.json` | 每次 session 结束 | 当前 session 结果（扁平格式，向后兼容旧 `current` 包装） |
 | `playwright-auth.json` | `claude-coder auth` | Playwright 登录状态（cookies + localStorage） |
 | `tests.json` | 首次测试时 | 验证记录（防止反复测试） |
-| `.runtime/` | 运行时 | 临时文件（phase、step、activity.log、logs/） |
+| `.runtime/` | 运行时 | 临时文件（phase、step、logs/）；工具调用记录合并到 session log |
 
 ---
 
@@ -299,17 +313,27 @@ sequenceDiagram
     participant SDK as Claude Agent SDK
     participant Hook as inferPhaseStep()
     participant Ind as Indicator (setInterval)
+    participant Stall as stallChecker (30s)
     participant Term as 终端
 
     SDK->>Hook: PreToolUse 回调<br/>{tool_name: "Edit", tool_input: {path: "src/app.tsx"}}
     Hook->>Hook: 推断阶段: Edit → coding
     Hook->>Ind: updatePhase("coding")
+    Hook->>Ind: lastToolTime = now
+    Hook->>Ind: toolTarget = "src/app.tsx"
     Hook->>Ind: appendActivity("Edit", "src/app.tsx")
 
     Note over SDK,Hook: 同步回调，return {decision: "allow"}
 
     loop 每 500ms
-        Ind->>Term: ⠋ [Session 3] 编码中 02:15 | Git 操作
+        Ind->>Term: ⠋ [Session 3] 编码中 02:15 | 读取文件: ppt_generator.py
+    end
+
+    loop 每 30s
+        Stall->>Ind: 检查 now - lastToolTime
+        alt 超过 STALL_TIMEOUT
+            Stall->>SDK: stallDetected = true → break for-await
+        end
     end
 ```
 
@@ -364,9 +388,12 @@ Harness 在 `buildCodingPrompt()` 中预读 `tasks.json`，将下一个待办任
 
 Harness 在 `buildCodingPrompt()` 中预读 `session_result.json`，将上次会话的 task_id、结果和 notes 摘要注入 user prompt。Agent 无需自行读取历史 session 数据。
 
-### Loop Detection（编辑死循环检测）
+### 自愈机制
+
+**编辑死循环检测**：PreToolUse hook 追踪每个文件的编辑次数，同一文件 Write/Edit 超 5 次 → `decision: "block"`。
 
-PreToolUse hook 中追踪每个文件的编辑次数。当同一文件被 Write/Edit 超过 5 次时，hook 返回 `decision: "block"` 阻止操作并提示 Agent 重新审视方案。
+**停顿超时检测**：每 30 秒检查 `indicator.lastToolTime`，若距上次工具调用超过 `SESSION_STALL_TIMEOUT`（默认 1800 秒 / 30 分钟），自动 `break` 退出并触发 rollback + 重试。
+> 注意：模型在处理复杂文件时可能出现 10-20 分钟的长时间思考，这是正常行为。超时设为 30 分钟以避免误杀正常思考。可通过 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 自定义。
 
 ### 文件权限模型
 
@@ -423,7 +450,7 @@ query({
 ### V2 迁移条件（等待稳定后）
 
 1. V2 去掉 `unstable_` 前缀，正式发布
-2. V2 支持 Hooks（当前项目依赖 PreToolUse 做 spinner 和 activity log）
+2. V2 支持 Hooks（当前项目依赖 PreToolUse 做 spinner 和日志记录）
 3. V2 支持 Subagents（未来可能用于扫描 Agent / 编码 Agent 分离）
 
 ### 可利用但尚未使用的 V1 特性

package/docs/README.en.md

@@ -86,7 +86,8 @@ your-project/
     tests.json              # Verification records
     test.env                # Test credentials (API keys, optional)
     playwright-auth.json    # Playwright login state (optional, via auth command)
-    .runtime/               # Temp files (logs)
+    .runtime/               # Temp files
+      logs/                 # Per-session logs (with tool call traces)
   requirements.md           # Requirements (optional)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "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

@@ -63,7 +63,6 @@ function paths() {
     runtime,
     phaseFile:        path.join(runtime, 'phase'),
     stepFile:         path.join(runtime, 'step'),
-    activityLog:      path.join(runtime, 'activity.log'),
     logsDir:          path.join(runtime, 'logs'),
   };
 }
@@ -107,6 +106,7 @@ function loadConfig() {
     defaultSonnet: env.ANTHROPIC_DEFAULT_SONNET_MODEL || '',
     defaultHaiku: env.ANTHROPIC_DEFAULT_HAIKU_MODEL || '',
     thinkingBudget: env.ANTHROPIC_THINKING_BUDGET || '',
+    stallTimeout: parseInt(env.SESSION_STALL_TIMEOUT, 10) || 1800,
     raw: env,
   };
 

package/src/indicator.js

@@ -9,9 +9,11 @@ class Indicator {
   constructor() {
     this.phase = 'thinking';
     this.step = '';
+    this.toolTarget = '';
     this.spinnerIndex = 0;
     this.timer = null;
     this.lastActivity = '';
+    this.lastToolTime = Date.now();
     this.sessionNum = 0;
     this.startTime = Date.now();
   }
@@ -41,13 +43,7 @@ class Indicator {
   }
 
   appendActivity(toolName, summary) {
-    const ts = new Date().toISOString();
-    const entry = `[${ts}] ${toolName}: ${summary}`;
-    this.lastActivity = entry;
-    try {
-      const p = paths();
-      fs.appendFileSync(p.activityLog, entry + '\n', 'utf8');
-    } catch { /* ignore */ }
+    this.lastActivity = `${toolName}: ${summary}`;
   }
 
   _writePhaseFile() {
@@ -74,8 +70,17 @@ class Indicator {
       ? `${COLOR.yellow}思考中${COLOR.reset}`
       : `${COLOR.green}编码中${COLOR.reset}`;
 
+    const idleMs = Date.now() - this.lastToolTime;
+    const idleMin = Math.floor(idleMs / 60000);
+
     let line = `${spinner} [Session ${this.sessionNum}] ${clock} ${phaseLabel} ${mm}:${ss}`;
-    if (this.step) line += ` | ${this.step}`;
+    if (idleMin >= 2) {
+      line += ` | ${COLOR.red}${idleMin}分无工具调用${COLOR.reset}`;
+    }
+    if (this.step) {
+      line += ` | ${this.step}`;
+      if (this.toolTarget) line += `: ${this.toolTarget}`;
+    }
     return line;
   }
 
@@ -94,6 +99,14 @@ class Indicator {
 function inferPhaseStep(indicator, toolName, toolInput) {
   const name = (toolName || '').toLowerCase();
 
+  indicator.lastToolTime = Date.now();
+
+  const rawTarget = typeof toolInput === 'object'
+    ? (toolInput.file_path || toolInput.path || toolInput.command || toolInput.pattern || '')
+    : String(toolInput || '');
+  const shortTarget = rawTarget.split('/').slice(-2).join('/').slice(0, 40);
+  indicator.toolTarget = shortTarget;
+
   if (name === 'write' || name === 'edit' || name === 'multiedit' || name === 'str_replace_editor' || name === 'strreplace') {
     indicator.updatePhase('coding');
   } else if (name === 'bash' || name === 'shell') {
@@ -119,9 +132,23 @@ function inferPhaseStep(indicator, toolName, toolInput) {
     indicator.updateStep('查阅文档');
   }
 
-  const summary = typeof toolInput === 'object'
-    ? (toolInput.path || toolInput.command || toolInput.pattern || JSON.stringify(toolInput).slice(0, 80))
-    : String(toolInput || '').slice(0, 80);
+  let summary;
+  if (typeof toolInput === 'object') {
+    const target = toolInput.file_path || toolInput.path || '';
+    const cmd = toolInput.command || '';
+    const pattern = toolInput.pattern || '';
+    if (target) {
+      summary = target;
+    } else if (cmd) {
+      summary = cmd.slice(0, 200);
+    } else if (pattern) {
+      summary = `pattern: ${pattern}`;
+    } else {
+      summary = JSON.stringify(toolInput).slice(0, 200);
+    }
+  } else {
+    summary = String(toolInput || '').slice(0, 200);
+  }
   indicator.appendActivity(toolName, summary);
 }
 

package/src/prompts.js

@@ -211,25 +211,83 @@ function buildScanPrompt(projectType, requirement) {
 
 /**
  * Build user prompt for add sessions.
+ * Structure: Role (primacy) → Context → CoT → TaskGuide → Instruction (recency)
  */
 function buildAddPrompt(instruction) {
+  const p = paths();
+  const projectRoot = getProjectRoot();
   const taskGuide = buildTaskGuide();
+
+  // --- Context injection: pre-read project state ---
+  let profileContext = '';
+  if (fs.existsSync(p.profile)) {
+    try {
+      const profile = JSON.parse(fs.readFileSync(p.profile, 'utf8'));
+      const stack = profile.tech_stack || {};
+      const parts = [];
+      if (stack.backend?.framework) parts.push(`后端: ${stack.backend.framework}`);
+      if (stack.frontend?.framework) parts.push(`前端: ${stack.frontend.framework}`);
+      if (stack.backend?.language) parts.push(`语言: ${stack.backend.language}`);
+      if (parts.length) profileContext = `项目技术栈: ${parts.join(', ')}`;
+    } catch { /* ignore */ }
+  }
+
+  let taskContext = '';
+  let recentExamples = '';
+  try {
+    const taskData = loadTasks();
+    if (taskData) {
+      const stats = getStats(taskData);
+      const features = taskData.features || [];
+      const maxId = features.length ? features[features.length - 1].id : 'feat-000';
+      const maxPriority = features.length ? Math.max(...features.map(f => f.priority || 0)) : 0;
+      const categories = [...new Set(features.map(f => f.category))].join(', ');
+
+      taskContext = `已有 ${stats.total} 个任务（${stats.done} done, ${stats.pending} pending, ${stats.failed} failed）。` +
+        `最大 id: ${maxId}, 最大 priority: ${maxPriority}。已有 category: ${categories}。`;
+
+      const recent = features.slice(-3);
+      if (recent.length) {
+        recentExamples = '已有任务格式参考（保持一致性）：\n' +
+          recent.map(f => `  ${f.id}: "${f.description}" (category=${f.category}, steps=${f.steps.length}步, depends_on=[${f.depends_on.join(',')}])`).join('\n');
+      }
+    }
+  } catch { /* ignore */ }
+
   return [
-    '重要：这是任务追加 session，不是常规编码 session。不执行 6 步流程。',
+    // --- Primacy zone: role + identity ---
+    '你是资深需求分析师，擅长将模糊需求分解为可执行的原子任务。',
+    '这是任务追加 session，不是编码 session。你只分解任务，不实现代码。',
     '',
-    '步骤：',
-    '1. 读取 .claude-coder/tasks.json 了解已有任务和最大 id/priority',
-    '2. 读取 .claude-coder/project_profile.json 了解项目技术栈',
-    '3. 根据用户指令追加新任务（status: pending）',
+
+    // --- Context layer ---
+    profileContext,
+    taskContext,
+    recentExamples,
+    `项目绝对路径: ${projectRoot}`,
     '',
+
+    // --- CoT: explicit thinking steps ---
+    '执行步骤（按顺序，不可跳过）：',
+    '1. 读取 .claude-coder/tasks.json 和 .claude-coder/project_profile.json，全面了解项目现状',
+    '2. 分析用户指令：识别核心功能点，判断是单任务还是需要拆分为多任务',
+    '3. 检查重复：对比已有任务，避免功能重叠',
+    '4. 确定依赖：新任务的 depends_on 引用已有或新增任务的 id，形成 DAG',
+    '5. 分解任务：每个任务对应一个独立可测试的功能单元，description 简明（40字内），steps 具体可操作',
+    '6. 追加到 tasks.json，id 和 priority 从已有最大值递增，status: pending',
+    '7. git add -A && git commit -m "chore: add new tasks"',
+    '8. 写入 session_result.json',
+    '',
+
+    // --- Quality constraints ---
     taskGuide,
     '',
-    '新任务 id 和 priority 从已有最大值递增。不修改已有任务，不实现代码。',
-    'git add -A && git commit -m "chore: add new tasks"',
-    '写入 session_result.json',
+    '不修改已有任务，不实现代码。',
     '',
+
+    // --- Recency zone: user instruction (highest attention) ---
     `用户指令：${instruction}`,
-  ].join('\n');
+  ].filter(Boolean).join('\n');
 }
 
 module.exports = {

package/src/runner.js

@@ -301,6 +301,25 @@ async function run(requirement, opts = {}) {
       lastValidateLog: consecutiveFailures > 0 ? '上次校验失败' : '',
     });
 
+    if (sessionResult.stalled) {
+      log('warn', `Session ${session} 因停顿超时中断，跳过校验直接重试`);
+      consecutiveFailures++;
+      rollback(headBefore, '停顿超时');
+      if (consecutiveFailures >= MAX_RETRY) {
+        log('error', `连续失败 ${MAX_RETRY} 次，跳过当前任务`);
+        markTaskFailed();
+        consecutiveFailures = 0;
+      }
+      appendProgress({
+        session,
+        timestamp: new Date().toISOString(),
+        result: 'stalled',
+        cost: sessionResult.cost,
+        taskId,
+      });
+      continue;
+    }
+
     // Validate
     log('info', '开始 harness 校验 ...');
     const validateResult = await validate(headBefore);

package/src/session.js

@@ -105,6 +105,16 @@ async function runCodingSession(sessionNum, opts = {}) {
 
   const editCounts = {};
   const EDIT_THRESHOLD = 5;
+  const stallTimeoutMs = config.stallTimeout * 1000;
+  let stallDetected = false;
+
+  const stallChecker = setInterval(() => {
+    const idleMs = Date.now() - indicator.lastToolTime;
+    if (idleMs > stallTimeoutMs && !stallDetected) {
+      stallDetected = true;
+      log('warn', `无新工具调用超过 ${Math.floor(idleMs / 60000)} 分钟，自动中断 session`);
+    }
+  }, 30000);
 
   try {
     const queryOpts = buildQueryOptions(config, opts);
@@ -115,13 +125,20 @@ async function runCodingSession(sessionNum, opts = {}) {
         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) {
+          const target = input.tool_input?.file_path || input.tool_input?.path || '';
+          const cmd = input.tool_input?.command || '';
+          const pattern = input.tool_input?.pattern || '';
+          const detail = target || cmd.slice(0, 200) || (pattern ? `pattern: ${pattern}` : '');
+          if (detail) {
+            logStream.write(`[${new Date().toISOString()}] ${input.tool_name}: ${detail}\n`);
+          }
+
+          if (['Write', 'Edit', 'MultiEdit'].includes(input.tool_name) && target) {
+            editCounts[target] = (editCounts[target] || 0) + 1;
+            if (editCounts[target] > EDIT_THRESHOLD) {
               return {
                 decision: 'block',
-                message: `已对 ${filePath} 编辑 ${editCounts[filePath]} 次，疑似死循环。请重新审视方案后再继续。`,
+                message: `已对 ${target} 编辑 ${editCounts[target]} 次，疑似死循环。请重新审视方案后再继续。`,
               };
             }
           }
@@ -135,21 +152,28 @@ async function runCodingSession(sessionNum, opts = {}) {
 
     const collected = [];
     for await (const message of session) {
+      if (stallDetected) {
+        log('warn', '停顿超时，中断消息循环');
+        break;
+      }
       collected.push(message);
       logMessage(message, logStream, indicator);
     }
 
+    clearInterval(stallChecker);
     logStream.end();
     indicator.stop();
 
     const result = extractResult(collected);
     return {
-      exitCode: 0,
+      exitCode: stallDetected ? 2 : 0,
       cost: result?.total_cost_usd ?? null,
       tokenUsage: result?.usage ?? null,
       logFile,
+      stalled: stallDetected,
     };
   } catch (err) {
+    clearInterval(stallChecker);
     logStream.end();
     indicator.stop();
     log('error', `Claude SDK 错误: ${err.message}`);