claude-coder 1.7.0 → 1.7.1

package/bin/cli.js

@@ -4,10 +4,10 @@
 const pkg = require('../package.json');
 
 const COMMANDS = {
-  run:      { desc: '自动编码循环',             usage: 'claude-coder run [需求] [--max N] [--pause N] [--dry-run]' },
+  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 "指令" [--model M] | add -r [file]' },
+  add:      { desc: '追加任务并可选自动执行',   usage: 'claude-coder add "指令" [--model M] | add -r [file]' },
   auth:     { desc: '导出 Playwright 登录状态', usage: 'claude-coder auth [url]' },
   validate: { desc: '手动校验上次 session',     usage: 'claude-coder validate' },
   status:   { desc: '查看任务进度和成本',       usage: 'claude-coder status' },
@@ -22,11 +22,11 @@ function showHelp() {
   }
   console.log('\n示例:');
   console.log('  claude-coder setup                   配置模型和 API Key');
-  console.log('  claude-coder run "实现用户登录"       开始自动编码');
+  console.log('  claude-coder add "实现用户登录"       添加任务（询问是否自动执行）');
+  console.log('  claude-coder 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 add "..." --model opus-4 指定模型追加任务');
   console.log('  claude-coder auth                    导出 Playwright 登录状态');
@@ -97,7 +97,7 @@ async function main() {
   switch (command) {
     case 'run': {
       const runner = require('../src/runner');
-      await runner.run(positional[0] || null, opts);
+      await runner.run(opts);
       break;
     }
     case 'setup': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.7.0",
+  "version": "1.7.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/prompts/CLAUDE.md

@@ -182,7 +182,7 @@
 
 ### 第六步：收尾（每次会话必须执行）
 
-1. **后台服务管理**：根据 prompt 提示决定——单次模式（`--max 1`）时停止所有后台服务（`lsof -ti :端口 | xargs kill`）；连续模式时保持服务运行，下个 session 继续使用
+1. **后台服务管理**：根据 prompt 提示决定——单次模式（`--max 1`）时停止所有后台服务，连续模式时保持服务运行。停止服务的跨平台命令见 coding prompt 中的「进程管理规范」
 2. **按需更新文档和 profile**：
    - **README / 用户文档**：仅当对外行为变化（新增功能、API 变更、使用方式变化）时更新
    - **项目指令文件**：如果本次新增了模块、改变了模块职责或新增了 API 端点，更新 `.claude/CLAUDE.md`。同时确保 `project_profile.json` 的 `existing_docs` 列表包含此文件

package/prompts/coding_user.md

@@ -20,4 +20,12 @@ Session {{sessionNum}}。执行 6 步流程。
 - 查文档/API: WebSearch + WebFetch
 - 效率: 多个 Read/Glob/Grep 尽量合并为一次批量调用，减少工具轮次
 
+进程管理规范（跨平台，严格遵守）：
+- 停止端口服务（Windows）: `netstat -ano | findstr :PORT` 获取 PID，然后 `taskkill /F /T /PID <PID>`（/T 杀进程树，必须带 /T）
+- 停止端口服务（Linux/Mac）: `lsof -ti :PORT | xargs kill -9`
+- 备选方案: `npx kill-port PORT`（跨平台）或 `powershell -Command "Get-NetTCPConnection -LocalPort PORT -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }"`
+- 杀进程失败时不要反复重试同一命令（最多 2 次），立即换用其他方法
+- 重启服务前必须先确认端口已释放（netstat/lsof 无输出），再启动新进程
+- Python venv 环境注意：uvicorn --reload 会创建父子进程树，必须用 /T 参数或杀父进程
+
 完成后写入 session_result.json。{{retryContext}}

package/src/hooks.js

@@ -67,35 +67,39 @@ function createSessionHooks(indicator, logStream, options = {}) {
   if (enableStallDetection) {
     stallChecker = setInterval(() => {
       const now = Date.now();
-      const idleMs = now - indicator.lastToolTime;
+      const idleMs = now - indicator.lastActivityTime; // 使用活动时间而非工具调用时间
 
+      // 优先检测 completion 超时（session_result 写入后的缩短超时）
       if (completionDetectedAt > 0) {
         const sinceCompletion = now - completionDetectedAt;
         if (sinceCompletion > completionTimeoutMs && !stallDetected) {
           stallDetected = true;
-          const secSince = Math.floor(sinceCompletion / 1000);
-          log('warn', `session_result 已写入 ${secSince} 秒前，模型未自行终止，自动中断`);
+          const shortMin = Math.ceil(completionTimeoutMs / 60000);
+          const actualMin = Math.floor(sinceCompletion / 60000);
+          log('warn', `\nsession_result 已写入 ${actualMin} 分钟，超过 ${shortMin} 分钟上限，自动中断`);
           if (logStream) {
-            logStream.write(`[${new Date().toISOString()}] COMPLETION_TIMEOUT: session_result 写入后 ${secSince}s 无终止，自动中断\n`);
+            logStream.write(`\n[${new Date().toISOString()}] STALL: session_result 写入后 ${actualMin} 分钟（上限 ${shortMin} 分钟），自动中断\n`);
           }
           if (abortController) {
             abortController.abort();
-            log('warn', '已发送中断信号（完成检测）');
+            log('warn', '\n已发送中断信号');
           }
-          return;
         }
+        // 已检测到 completion，不再执行 stall 检测，等待 completion 超时
+        return;
       }
 
+      // 正常 stall 检测（仅在未检测到 completion 时执行）
       if (idleMs > stallTimeoutMs && !stallDetected) {
         stallDetected = true;
         const idleMin = Math.floor(idleMs / 60000);
-        log('warn', `无新工具调用超过 ${idleMin} 分钟，自动中断 session`);
+        log('warn', `\n无响应超过 ${idleMin} 分钟，自动中断 session`);
         if (logStream) {
-          logStream.write(`[${new Date().toISOString()}] STALL: 无工具调用 ${idleMin} 分钟，自动中断\n`);
+          logStream.write(`\n[${new Date().toISOString()}] STALL: 无响应 ${idleMin} 分钟，自动中断\n`);
         }
         if (abortController) {
           abortController.abort();
-          log('warn', '已发送中断信号');
+          log('warn', '\n已发送中断信号');
         }
       }
     }, 30000);
@@ -138,9 +142,11 @@ function createSessionHooks(indicator, logStream, options = {}) {
           if (isSessionResultWrite(input.tool_name, input.tool_input)) {
             completionDetectedAt = Date.now();
             const shortMin = Math.ceil(completionTimeoutMs / 60000);
+            indicator.setCompletionDetected(shortMin);
+            log('info', '');
             log('info', `检测到 session_result 写入，${shortMin} 分钟内模型未终止将自动中断`);
             if (logStream) {
-              logStream.write(`[${new Date().toISOString()}] COMPLETION_DETECTED: session_result.json written, ${shortMin}min grace period\n`);
+              logStream.write(`\n[${new Date().toISOString()}] COMPLETION_DETECTED: session_result.json written, ${shortMin}min grace period\n`);
             }
           }
         }

package/src/indicator.js

@@ -57,14 +57,17 @@ class Indicator {
     this.timer = null;
     this.lastActivity = '';
     this.lastToolTime = Date.now();
+    this.lastActivityTime = Date.now(); // 最后活动时间（包括文字输出）
     this.sessionNum = 0;
     this.startTime = Date.now();
     this.stallTimeoutMin = 30;
+    this.completionTimeoutMin = null; // session_result 写入后的缩短超时
   }
 
   start(sessionNum, stallTimeoutMin) {
     this.sessionNum = sessionNum;
     this.startTime = Date.now();
+    this.lastActivityTime = Date.now();
     if (stallTimeoutMin > 0) this.stallTimeoutMin = stallTimeoutMin;
     this.timer = setInterval(() => this._render(), 1000);
   }
@@ -89,6 +92,14 @@ class Indicator {
     this.lastActivity = `${toolName}: ${summary}`;
   }
 
+  setCompletionDetected(timeoutMin) {
+    this.completionTimeoutMin = timeoutMin;
+  }
+
+  updateActivity() {
+    this.lastActivityTime = Date.now();
+  }
+
   getStatusLine() {
     const now = new Date();
     const hh = String(now.getHours()).padStart(2, '0');
@@ -105,12 +116,16 @@ class Indicator {
       ? `${COLOR.yellow}思考中${COLOR.reset}`
       : `${COLOR.green}编码中${COLOR.reset}`;
 
-    const idleMs = Date.now() - this.lastToolTime;
+    const idleMs = Date.now() - this.lastActivityTime;
     const idleMin = Math.floor(idleMs / 60000);
 
     let line = `${spinner} [Session ${this.sessionNum}] ${clock} ${phaseLabel} ${mm}:${ss}`;
     if (idleMin >= 2) {
-      line += ` | ${COLOR.red}${idleMin}分无工具调用（等待模型响应, ${this.stallTimeoutMin}分钟超时自动中断）${COLOR.reset}`;
+      if (this.completionTimeoutMin) {
+        line += ` | ${COLOR.red}${idleMin}分无响应（session_result 已写入, ${this.completionTimeoutMin}分钟超时自动中断）${COLOR.reset}`;
+      } else {
+        line += ` | ${COLOR.red}${idleMin}分无响应（等待模型响应, ${this.stallTimeoutMin}分钟超时自动中断）${COLOR.reset}`;
+      }
     }
     if (this.step) {
       line += ` | ${this.step}`;
@@ -172,6 +187,7 @@ function inferPhaseStep(indicator, toolName, toolInput) {
   const name = (toolName || '').toLowerCase();
 
   indicator.lastToolTime = Date.now();
+  indicator.lastActivityTime = Date.now();
 
   if (name === 'write' || name === 'edit' || name === 'multiedit' || name === 'str_replace_editor' || name === 'strreplace') {
     indicator.updatePhase('coding');

package/src/runner.js

@@ -148,7 +148,7 @@ async function promptContinue() {
   });
 }
 
-async function run(requirement, opts = {}) {
+async function run(opts = {}) {
   const p = paths();
   const projectRoot = getProjectRoot();
   ensureLoopDir();
@@ -168,12 +168,6 @@ async function run(requirement, opts = {}) {
     log('ok', `模型配置已加载: ${config.provider}${config.model ? ` (${config.model})` : ''}`);
   }
 
-  const reqFile = path.join(projectRoot, 'requirements.md');
-  if (fs.existsSync(reqFile) && !requirement) {
-    requirement = fs.readFileSync(reqFile, 'utf8');
-    log('ok', '已读取需求文件: requirements.md');
-  }
-
   try {
     execSync('git rev-parse --is-inside-work-tree', { cwd: projectRoot, stdio: 'ignore' });
   } catch {
@@ -185,66 +179,18 @@ async function run(requirement, opts = {}) {
     });
   }
 
-  // --- Phase 1: 项目扫描（生成 profile） ---
+  // 检查前置条件
   if (!fs.existsSync(p.profile)) {
-    if (!requirement) {
-      log('error', '首次运行需要提供需求描述');
-      console.log('');
-      console.log('用法（二选一）:');
-      console.log('  方式 1: 在项目根目录创建 requirements.md');
-      console.log('          claude-coder run');
-      console.log('');
-      console.log('  方式 2: 直接传入一句话需求');
-      console.log('          claude-coder run "你的需求描述"');
-      process.exit(1);
-    }
-
-    if (dryRun) {
-      log('info', '[DRY-RUN] 将执行初始化扫描（跳过）');
-      const reqPreview = (requirement || '').slice(0, 100);
-      log('info', `[DRY-RUN] 需求: ${reqPreview}${reqPreview.length >= 100 ? '...' : ''}`);
-      return;
-    }
-
-    await loadSDK();
-    const scanResult = await scan(requirement, { projectRoot });
-    if (!scanResult.success) {
-      console.log('');
-      console.log(`${COLOR.yellow}═══════════════════════════════════════════════${COLOR.reset}`);
-      console.log(`${COLOR.yellow}  若出现 "Credit balance is too low"，请运行:${COLOR.reset}`);
-      console.log(`  ${COLOR.green}claude-coder setup${COLOR.reset}`);
-      console.log(`${COLOR.yellow}═══════════════════════════════════════════════${COLOR.reset}`);
-      process.exit(1);
-    }
-  }
-
-  // --- Phase 2: 任务分解（scan 后衔接 add） ---
-  if (!fs.existsSync(p.tasksFile)) {
-    if (requirement) {
-      console.log('');
-      log('ok', '项目扫描完成，是否根据需求分解任务？');
-      const shouldAdd = await promptContinue();
-      if (shouldAdd) {
-        if (!dryRun) await loadSDK();
-        deployTestRule(p);
-        log('info', '正在分解任务...');
-        await runAddSession(requirement, { projectRoot });
-      } else {
-        log('info', '跳过任务分解。后续可通过 claude-coder add 手动添加任务。');
-      }
-    } else {
-      log('warn', 'tasks.json 不存在且无需求描述，请运行 claude-coder add 添加任务');
-    }
+    log('error', 'profile.json 不存在，请先运行 claude-coder add 添加任务');
+    process.exit(1);
   }
 
   if (!fs.existsSync(p.tasksFile)) {
-    log('error', 'tasks.json 不存在，无法进入编码循环。请先运行 claude-coder add 添加任务。');
+    log('error', 'tasks.json 不存在，请先运行 claude-coder add 添加任务');
     process.exit(1);
   }
 
-  if (fs.existsSync(p.profile) && fs.existsSync(p.tasksFile)) {
-    printStats();
-  }
+  printStats();
 
   if (!dryRun) await loadSDK();
   log('info', `开始编码循环 (最多 ${maxSessions} 个会话) ...`);
@@ -377,6 +323,17 @@ async function run(requirement, opts = {}) {
   printStats();
 }
 
+async function promptAutoRun() {
+  if (!process.stdin.isTTY) return false;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question('任务分解完成后是否自动开始执行？(y/n) ', answer => {
+      rl.close();
+      resolve(/^[Yy]/.test(answer.trim()));
+    });
+  });
+}
+
 async function add(instruction, opts = {}) {
   await loadSDK();
   const p = paths();
@@ -396,15 +353,34 @@ async function add(instruction, opts = {}) {
   const displayModel = opts.model || config.model || '(default)';
   log('ok', `模型配置已加载: ${config.provider || 'claude'} (add 使用: ${displayModel})`);
 
+  // 如果 profile 不存在，先执行项目扫描
   if (!fs.existsSync(p.profile)) {
-    log('error', 'add 需要先完成项目扫描（至少运行一次 claude-coder run）');
-    process.exit(1);
+    log('info', '首次使用，正在执行项目扫描...');
+    const scanResult = await scan(instruction, { projectRoot });
+    if (!scanResult.success) {
+      console.log('');
+      console.log(`${COLOR.yellow}═══════════════════════════════════════════════${COLOR.reset}`);
+      console.log(`${COLOR.yellow}  若出现 "Credit balance is too low"，请运行:${COLOR.reset}`);
+      console.log(`  ${COLOR.green}claude-coder setup${COLOR.reset}`);
+      console.log(`${COLOR.yellow}═══════════════════════════════════════════════${COLOR.reset}`);
+      process.exit(1);
+    }
   }
 
+  // 询问用户是否在完成后自动运行
+  const shouldAutoRun = await promptAutoRun();
+
   deployTestRule(p);
 
   await runAddSession(instruction, { projectRoot, ...opts });
   printStats();
+
+  // 如果用户选择自动运行，则调用 run()
+  if (shouldAutoRun) {
+    console.log('');
+    log('info', '开始自动执行任务...');
+    await run(opts);
+  }
 }
 
 function deployTestRule(p) {

package/src/session.js

@@ -88,6 +88,8 @@ 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) indicator.updateActivity();
         if (indicator) {
           process.stderr.write('\r\x1b[K');
           const contentKey = `${indicator.phase}|${indicator.step}|${indicator.toolTarget}`;