claude-coder 1.4.0 → 1.5.0

package/README.md

@@ -98,7 +98,8 @@ your-project/
     tests.json              # 验证记录
     test.env                # 测试凭证（API Key 等，可选）
     playwright-auth.json    # Playwright 登录状态（可选，auth 命令生成）
-    .runtime/               # 临时文件（含日志）
+    .runtime/               # 临时文件
+      logs/                 # 每 session 独立日志 + activity log
   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_N.activity.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=秒数` 自定义。
 
 ### 文件权限模型
 

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 + activity logs
   requirements.md           # Requirements (optional)
 ```
 

package/package.json

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

@@ -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,15 +9,18 @@ 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();
   }
 
-  start(sessionNum) {
+  start(sessionNum, activityLogPath) {
     this.sessionNum = sessionNum;
+    this.activityLogPath = activityLogPath || null;
     this.startTime = Date.now();
     this.timer = setInterval(() => this._render(), 500);
   }
@@ -45,8 +48,9 @@ class Indicator {
     const entry = `[${ts}] ${toolName}: ${summary}`;
     this.lastActivity = entry;
     try {
-      const p = paths();
-      fs.appendFileSync(p.activityLog, entry + '\n', 'utf8');
+      if (this.activityLogPath) {
+        fs.appendFileSync(this.activityLogPath, entry + '\n', 'utf8');
+      }
     } catch { /* ignore */ }
   }
 
@@ -74,8 +78,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 +107,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 +140,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/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

@@ -99,12 +99,23 @@ async function runCodingSession(sessionNum, opts = {}) {
   const taskId = opts.taskId || 'unknown';
   const dateStr = new Date().toISOString().slice(0, 10).replace(/-/g, '');
   const logFile = path.join(p.logsDir, `${taskId}_session_${sessionNum}_${dateStr}.log`);
+  const activityLogFile = path.join(p.logsDir, `session_${sessionNum}.activity.log`);
   const logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
-  indicator.start(sessionNum);
+  indicator.start(sessionNum, activityLogFile);
 
   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 +126,18 @@ 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 toolSummary = target ? target.split('/').slice(-2).join('/') : '';
+          if (toolSummary) {
+            logStream.write(`[${new Date().toISOString()}] ${input.tool_name}: ${toolSummary}\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 +151,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}`);