claude-coder 1.0.6 → 1.0.8

package/docs/ARCHITECTURE.md

@@ -183,11 +183,11 @@ flowchart TB
 
 | Session 类型 | systemPrompt | user prompt | 触发条件 |
 |---|---|---|---|
-| **编码** | CLAUDE.md | `buildCodingPrompt()` + 8 个条件 hint | 主循环每次迭代 |
+| **编码** | CLAUDE.md | `buildCodingPrompt()` + 10 个条件 hint | 主循环每次迭代 |
 | **扫描** | CLAUDE.md + SCAN_PROTOCOL.md | `buildScanPrompt()` + 任务分解指导 + profile 质量要求 | 首次运行 |
 | **追加** | CLAUDE.md | `buildAddPrompt()` + 任务分解指导 | `claude-coder add` |
 
-### 编码 Session 的 8 个条件 Hint
+### 编码 Session 的 10 个条件 Hint
 
 | # | Hint | 触发条件 | 影响 |
 |---|---|---|---|
@@ -197,8 +197,10 @@ flowchart TB
 | 4 | `docsHint` | profile.existing_docs 非空或 profile 有缺陷 | Step 4：读文档后再编码；profile 缺陷时提示 Agent 在 Step 6 补全 services/docs |
 | 5 | `envHint` | 连续成功且 session>1 | Step 2：跳过 init |
 | 6 | `retryContext` | 上次校验失败 | 全局：避免同样错误 |
-| 7 | `taskHint` | tasks.json 存在且有待办任务 | Step 1：跳过读取 tasks.json，harness 已注入当前任务上下文 |
+| 7 | `taskHint` | tasks.json 存在且有待办任务 | Step 1：跳过读取 tasks.json，harness 已注入当前任务上下文 + .claude-coder/ 路径提示 |
 | 8 | `memoryHint` | session_result.json 存在且有历史记录 | Step 1：跳过读取 session_result.json，harness 已注入上次会话摘要 |
+| 9 | `serviceHint` | 始终注入 | Step 6：单次模式停止服务，连续模式保持服务运行 |
+| 10 | `toolGuidance` | 始终注入 | 全局：工具使用规范（Grep/Glob/Read/LS/MultiEdit/Task 替代 bash 命令），非 Claude 模型必需 |
 
 ---
 
@@ -266,7 +268,7 @@ sequenceDiagram
 | 维度 | 评分 | 说明 |
 |------|------|------|
 | **CLAUDE.md 系统提示** | 8/10 | U 型注意力设计；铁律清晰；状态机和 6 步流程是核心竞争力 |
-| **动态 prompt** | 8.5/10 | 8 个条件 hint 精准注入，含 task/memory 上下文注入，减少 Agent 冗余 Read 调用 |
+| **动态 prompt** | 9/10 | 10 个条件 hint 精准注入，含 task/memory 上下文注入 + 服务管理 + 工具使用指导，减少 Agent 冗余操作 |
 | **SCAN_PROTOCOL.md** | 8.5/10 | 新旧项目分支完整，profile 格式全面 |
 | **tests.json 设计** | 7.5/10 | 精简字段，核心目的（防反复测试）明确 |
 | **注入时机** | 9/10 | 静态规则 vs 动态上下文分离干净 |

package/docs/README.en.md

@@ -50,9 +50,9 @@ Each session, the agent autonomously follows 6 steps: restore context → env ch
 |---------|-------------|
 | `claude-coder setup` | Interactive model configuration |
 | `claude-coder run [requirement]` | Auto-coding loop |
+| `claude-coder run --max 1` | Single session (replaces old view mode) |
 | `claude-coder run --dry-run` | Preview mode |
 | `claude-coder init` | Initialize project environment |
-| `claude-coder view [requirement]` | Observation mode (single session) |
 | `claude-coder add "instruction"` | Append tasks |
 | `claude-coder validate` | Manually validate last session |
 | `claude-coder status` | View progress and costs |

package/package.json

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

@@ -148,7 +148,12 @@ function buildEnvVars(config) {
 // --------------- Allowed tools ---------------
 
 function getAllowedTools(config) {
-  const tools = ['Read', 'Edit', 'Write', 'Bash', 'Glob', 'Grep'];
+  const tools = [
+    'Read', 'Edit', 'MultiEdit', 'Write',
+    'Bash', 'Glob', 'Grep', 'LS',
+    'Task',
+    'WebSearch', 'WebFetch',
+  ];
   if (config.mcpPlaywright) tools.push('mcp__playwright__*');
   return tools;
 }

package/src/indicator.js

@@ -58,24 +58,29 @@ class Indicator {
     try { fs.writeFileSync(paths().stepFile, this.step, 'utf8'); } catch { /* ignore */ }
   }
 
-  _render() {
+  getStatusLine() {
     const elapsed = Math.floor((Date.now() - this.startTime) / 1000);
     const mm = String(Math.floor(elapsed / 60)).padStart(2, '0');
     const ss = String(elapsed % 60).padStart(2, '0');
     const spinner = SPINNERS[this.spinnerIndex % SPINNERS.length];
-    this.spinnerIndex++;
 
     const phaseLabel = this.phase === 'thinking'
       ? `${COLOR.yellow}思考中${COLOR.reset}`
       : `${COLOR.green}编码中${COLOR.reset}`;
 
-    let line = `\r${spinner} [Session ${this.sessionNum}] ${phaseLabel} ${mm}:${ss}`;
+    let line = `${spinner} [Session ${this.sessionNum}] ${phaseLabel} ${mm}:${ss}`;
     if (this.step) line += ` | ${this.step}`;
+    return line;
+  }
+
+  _render() {
+    this.spinnerIndex++;
+    const line = this.getStatusLine();
 
     const maxWidth = process.stderr.columns || 80;
-    if (line.length > maxWidth + 20) line = line.slice(0, maxWidth + 20);
+    const truncated = line.length > maxWidth + 20 ? line.slice(0, maxWidth + 20) : line;
 
-    process.stderr.write(`\r\x1b[K${line}`);
+    process.stderr.write(`\r\x1b[K${truncated}`);
   }
 }
 
@@ -83,7 +88,7 @@ class Indicator {
 function inferPhaseStep(indicator, toolName, toolInput) {
   const name = (toolName || '').toLowerCase();
 
-  if (name === 'write' || name === 'edit' || name === 'str_replace_editor' || name === 'strreplace') {
+  if (name === 'write' || name === 'edit' || name === 'multiedit' || name === 'str_replace_editor' || name === 'strreplace') {
     indicator.updatePhase('coding');
   } else if (name === 'bash' || name === 'shell') {
     const cmd = typeof toolInput === 'object' ? (toolInput.command || '') : String(toolInput || '');
@@ -97,9 +102,15 @@ function inferPhaseStep(indicator, toolName, toolInput) {
     } else {
       indicator.updatePhase('coding');
     }
-  } else if (name === 'read' || name === 'glob' || name === 'grep') {
+  } else if (name === 'read' || name === 'glob' || name === 'grep' || name === 'ls') {
     indicator.updatePhase('thinking');
     indicator.updateStep('读取文件');
+  } else if (name === 'task') {
+    indicator.updatePhase('thinking');
+    indicator.updateStep('子 Agent 搜索');
+  } else if (name === 'websearch' || name === 'webfetch') {
+    indicator.updatePhase('thinking');
+    indicator.updateStep('查阅文档');
   }
 
   const summary = typeof toolInput === 'object'

package/src/prompts.js

@@ -108,6 +108,7 @@ function buildCodingPrompt(sessionNum, opts = {}) {
         taskHint = `任务上下文: ${next.id} "${next.description}" (${next.status}), ` +
           `category=${next.category}, steps=${next.steps.length}步。` +
           `进度: ${stats.done}/${stats.total} done, ${stats.failed} failed。` +
+          `运行时目录: .claude-coder/（隐藏目录，ls -a 可见，所有 tasks.json/profile 等文件均在此目录下）。` +
           `第一步无需读取 tasks.json（已注入），直接确认任务后进入 Step 2。`;
       }
     }
@@ -126,6 +127,25 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     } catch { /* ignore */ }
   }
 
+  // Hint 9: Service management (continuous vs single-shot mode)
+  const maxSessions = opts.maxSessions || 50;
+  const serviceHint = maxSessions === 1
+    ? '单次模式：收尾时停止所有后台服务。'
+    : '连续模式：收尾时不要停止后台服务，保持服务运行以便下个 session 继续使用。';
+
+  // Hint 10: Tool usage guidance (critical for non-Claude models)
+  const toolGuidance = [
+    '可用工具与使用规范（严格遵守）：',
+    '- 搜索文件名: Glob（如 **/*.ts），禁止 bash find',
+    '- 搜索文件内容: Grep（正则，基于 ripgrep），禁止 bash grep',
+    '- 读文件: Read（支持批量多文件同时读取），禁止 bash cat/head/tail',
+    '- 列目录: LS，禁止 bash ls',
+    '- 编辑文件: 同一文件多处修改用 MultiEdit（一次原子调用），单处用 Edit',
+    '- 复杂搜索: Task（启动子 Agent 并行搜索，不消耗主 context），适合开放式探索',
+    '- 查文档/API: WebSearch + WebFetch',
+    '- 效率: 多个 Read/Glob/Grep 尽量合并为一次批量调用，减少工具轮次',
+  ].join('\n');
+
   return [
     `Session ${sessionNum}。执行 6 步流程。`,
     '效率要求：先规划后编码，完成全部编码后再统一测试，禁止编码-测试反复跳转。后端任务用 curl 验证，不启动浏览器。',
@@ -136,6 +156,8 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     envHint,
     taskHint,
     memoryHint,
+    serviceHint,
+    toolGuidance,
     `完成后写入 session_result.json。${retryContext}`,
   ].filter(Boolean).join('\n');
 }

package/src/runner.js

@@ -269,6 +269,7 @@ async function run(requirement, opts = {}) {
     const sessionResult = await runCodingSession(session, {
       projectRoot,
       consecutiveFailures,
+      maxSessions,
       lastValidateLog: consecutiveFailures > 0 ? '上次校验失败' : '',
     });
 

package/src/session.js

@@ -66,7 +66,11 @@ 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');
+        if (indicator) {
+          const statusLine = indicator.getStatusLine();
+          process.stderr.write('\r\x1b[K');
+          if (statusLine) process.stderr.write(statusLine + '\n');
+        }
         process.stdout.write(block.text);
         if (logStream) logStream.write(block.text);
       }

package/templates/CLAUDE.md

@@ -210,7 +210,8 @@ pending ──→ in_progress ──→ testing ──→ done
    - 确认方案完整后，**一次性**完成所有编码
    - **禁止边写边试**：完成全部编码后再进入第五步统一测试
 4. **高效执行**：禁止碎片化操作（读一个文件、思考、再读一个），批量读取、批量修改、减少工具调用轮次
-5. **跳过已完成的步骤**：文件已存在且内容正确的步骤直接跳过
+5. **工具优先**：用 Grep/Glob 替代 bash grep/find，用 Read/LS 替代 bash cat/ls，同一文件多处修改用 MultiEdit
+6. **跳过已完成的步骤**：文件已存在且内容正确的步骤直接跳过
 
 ### 第五步：测试验证
 
@@ -241,7 +242,7 @@ pending ──→ in_progress ──→ testing ──→ done
 
 ### 第六步：收尾（每次会话必须执行）
 
-1. **停止本次启动的后台服务**：`lsof -ti :端口 | xargs kill`，避免下次 session 端口冲突
+1. **后台服务管理**：根据 prompt 提示决定——单次模式（`--max 1`）时停止所有后台服务（`lsof -ti :端口 | xargs kill`）；连续模式时保持服务运行，下个 session 继续使用
 2. **按需更新文档和 profile**：
    - **README / 用户文档**：仅当对外行为变化（新增功能、API 变更、使用方式变化）时更新
    - **架构 / API 文档**：如果本次新增了模块、改变了模块职责或新增了 API 端点，更新 `existing_docs` 中对应的架构或 API 文档。同时更新 `project_profile.json` 的 `existing_docs` 列表（若新增了文档文件）