claude-coder 1.0.5 → 1.0.8

package/bin/cli.js

@@ -7,7 +7,6 @@ const COMMANDS = {
   run:      { desc: '自动编码循环',             usage: 'claude-coder run [需求] [--max N] [--pause N] [--dry-run]' },
   setup:    { desc: '交互式模型配置',           usage: 'claude-coder setup' },
   init:     { desc: '初始化项目环境',           usage: 'claude-coder init' },
-  view:     { desc: '观测模式（交互式单次）',   usage: 'claude-coder view [需求]' },
   add:      { desc: '追加任务到 tasks.json',    usage: 'claude-coder add "指令"' },
   validate: { desc: '手动校验上次 session',     usage: 'claude-coder validate' },
   status:   { desc: '查看任务进度和成本',       usage: 'claude-coder status' },
@@ -24,6 +23,7 @@ function showHelp() {
   console.log('\n示例:');
   console.log('  claude-coder setup                   配置模型和 API Key');
   console.log('  claude-coder run "实现用户登录"       开始自动编码');
+  console.log('  claude-coder run --max 1             单次执行（替代旧 view 模式）');
   console.log('  claude-coder run --max 5 --dry-run   预览模式');
   console.log('  claude-coder status                  查看进度和成本');
   console.log(`\n前置条件: npm install -g @anthropic-ai/claude-agent-sdk`);
@@ -46,9 +46,6 @@ function parseArgs(argv) {
       case '--dry-run':
         opts.dryRun = true;
         break;
-      case '--view':
-        opts.viewMode = true;
-        break;
       case '--help':
       case '-h':
         showHelp();
@@ -81,11 +78,7 @@ async function main() {
   switch (command) {
     case 'run': {
       const runner = require('../src/runner');
-      if (opts.viewMode) {
-        await runner.view(positional[0] || null, opts);
-      } else {
-        await runner.run(positional[0] || null, opts);
-      }
+      await runner.run(positional[0] || null, opts);
       break;
     }
     case 'setup': {
@@ -98,11 +91,6 @@ async function main() {
       await init();
       break;
     }
-    case 'view': {
-      const runner = require('../src/runner');
-      await runner.view(positional[0] || null, opts);
-      break;
-    }
     case 'add': {
       if (!positional[0]) {
         console.error('用法: claude-coder add "任务描述"');

package/docs/ARCHITECTURE.md

@@ -60,9 +60,6 @@ flowchart TB
 flowchart LR
     start(["claude-coder run ..."]) --> mode{模式?}
 
-    mode -->|view| view["runViewSession()"]
-    view --> exit_view([exit 0])
-
     mode -->|"add 指令"| add["runAddSession()"]
     add --> exit_add([exit 0])
 
@@ -165,7 +162,6 @@ flowchart TB
         coding_p["buildCodingPrompt()<br/>编码 session prompt"]
         task_g["buildTaskGuide()<br/>任务分解指导"]
         scan_p["buildScanPrompt()<br/>扫描 session prompt"]
-        view_p["buildViewPrompt()"]
         add_p["buildAddPrompt()"]
     end
 
@@ -180,7 +176,6 @@ flowchart TB
     task_g --> scan_p
     task_g --> add_p
     scan_p --> query
-    view_p --> query
     add_p --> query
 ```
 
@@ -188,23 +183,24 @@ flowchart TB
 
 | Session 类型 | systemPrompt | user prompt | 触发条件 |
 |---|---|---|---|
-| **编码** | CLAUDE.md | `buildCodingPrompt()` + 8 个条件 hint | 主循环每次迭代 |
-| **扫描** | CLAUDE.md + SCAN_PROTOCOL.md | `buildScanPrompt()` + 任务分解指导 | 首次运行 |
-| **观测** | CLAUDE.md (± SCAN_PROTOCOL.md) | `buildViewPrompt()` | `claude-coder view` |
+| **编码** | 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 | 触发条件 | 影响 |
 |---|---|---|---|
 | 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：读文档后再编码，完成后更新文档 |
+| 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 模型必需 |
 
 ---
 
@@ -272,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 动态上下文分离干净 |
@@ -429,3 +425,14 @@ query({
 5. **跨平台**：纯 Node.js + `child_process` 调用 git，无平台特定脚本
 6. **运行时隔离**：每个项目的 `.claude-coder/` 独立，不同项目互不干扰
 7. **Prompt 架构分离**：静态规则在 `templates/`，动态上下文在 `src/prompts.js`
+8. **文档即上下文**：文档在 harness 中分两层角色——Blueprint（`project_profile.json`，给 harness 的结构化元数据）和 Context Docs（`docs/ARCHITECTURE.md` 等，给 Agent 的人类可读文档）。Harness 通过 Hint 6 动态提醒 Agent 读取相关文档，并在 profile 有缺陷时提示补全
+
+### 文档架构的学术依据
+
+| 来源 | 核心概念 | 本项目映射 |
+|------|----------|-----------|
+| DeepCode (arXiv 2512.07921) | Blueprint Distillation — 源文档压缩为结构化蓝图 | `project_profile.json` 是项目蓝图 |
+| CodeMem (arXiv 2512.15813) | Procedural Memory — 验证过的逻辑持久化为可索引技能库 | 架构文档记录"决策"供 Agent 按需检索 |
+| Anthropic Memory Tool | Just-in-time 检索 — 按需从文件系统拉取 | Hint 6 按需提示 Agent 读文档 |
+| ContextBench (arXiv 2602.05892) | 复杂脚手架边际收益递减 | 不过度设计文档体系，关键信息必须准确 |
+| LangChain Harness Engineering | Build-Verify + Context on behalf of Agent | Harness 准备上下文，Agent 专注编码 |

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.5",
+  "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

@@ -78,7 +78,7 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     } catch { /* ignore */ }
   }
 
-  // Hint 6: Project documentation awareness
+  // Hint 6: Project documentation awareness + profile quality check
   let docsHint = '';
   if (fs.existsSync(p.profile)) {
     try {
@@ -87,6 +87,13 @@ function buildCodingPrompt(sessionNum, opts = {}) {
       if (docs.length > 0) {
         docsHint = `项目文档: ${docs.join(', ')}。Step 4 编码前先读与任务相关的文档，了解接口约定和编码规范。完成后若新增了模块或 API，更新对应文档。`;
       }
+      if (profile.tech_stack?.backend?.framework &&
+          (!profile.services || profile.services.length === 0)) {
+        docsHint += ' 注意：project_profile.json 的 services 为空，请在本次 session 末尾补全 services 数组（command, port, health_check）。';
+      }
+      if (!docs.length) {
+        docsHint += ' 注意：project_profile.json 的 existing_docs 为空，请在 Step 6 收尾时补全文档列表。';
+      }
     } catch { /* ignore */ }
   }
 
@@ -101,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。`;
       }
     }
@@ -119,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 验证，不启动浏览器。',
@@ -129,6 +156,8 @@ function buildCodingPrompt(sessionNum, opts = {}) {
     envHint,
     taskHint,
     memoryHint,
+    serviceHint,
+    toolGuidance,
     `完成后写入 session_result.json。${retryContext}`,
   ].filter(Boolean).join('\n');
 }
@@ -176,6 +205,13 @@ function buildScanPrompt(projectType, requirement) {
     `用户需求: ${requirement || '(无指定需求)'}`,
     '',
     '步骤 1-2：按「项目扫描协议」扫描项目、生成 project_profile.json。',
+    '',
+    'profile 质量要求（必须遵守，harness 会校验）：',
+    '- services 数组必须包含所有可启动服务（command、port、health_check），不得为空',
+    '- existing_docs 必须列出所有实际存在的文档路径',
+    '- 前后端分离项目必须生成 docs/ARCHITECTURE.md（模块职责、数据流、API 路由），并加入 existing_docs',
+    '- scan_files_checked 必须列出所有实际扫描过的文件',
+    '',
     '步骤 3：根据以下指导分解任务到 tasks.json（格式见 CLAUDE.md）：',
     '',
     taskGuide,
@@ -184,20 +220,6 @@ function buildScanPrompt(projectType, requirement) {
   ].join('\n');
 }
 
-/**
- * Build user prompt for view sessions.
- * @param {Object} opts - { needsScan, projectType, requirement, allDone }
- */
-function buildViewPrompt(opts = {}) {
-  if (opts.needsScan) {
-    return `你是项目初始化 Agent。项目类型: ${opts.projectType}。用户需求: ${opts.requirement || ''}。按照「项目扫描协议」执行。`;
-  }
-  if (opts.allDone) {
-    return '所有任务已完成，无需执行 6 步流程。直接与用户对话，按需回答问题或执行临时请求。';
-  }
-  return '执行 6 步流程，完成下一个任务。';
-}
-
 /**
  * Build user prompt for add sessions.
  */
@@ -226,6 +248,5 @@ module.exports = {
   buildCodingPrompt,
   buildTaskGuide,
   buildScanPrompt,
-  buildViewPrompt,
   buildAddPrompt,
 };

package/src/runner.js

@@ -8,7 +8,7 @@ const { paths, log, COLOR, loadConfig, ensureLoopDir, getProjectRoot, getRequire
 const { loadTasks, saveTasks, getFeatures, getStats, findNextTask } = require('./tasks');
 const { validate } = require('./validator');
 const { scan } = require('./scanner');
-const { runCodingSession, runViewSession, runAddSession } = require('./session');
+const { runCodingSession, runAddSession } = require('./session');
 
 const MAX_RETRY = 3;
 
@@ -269,6 +269,7 @@ async function run(requirement, opts = {}) {
     const sessionResult = await runCodingSession(session, {
       projectRoot,
       consecutiveFailures,
+      maxSessions,
       lastValidateLog: consecutiveFailures > 0 ? '上次校验失败' : '',
     });
 
@@ -338,18 +339,6 @@ async function run(requirement, opts = {}) {
   printStats();
 }
 
-async function view(requirement, opts = {}) {
-  await requireSdk();
-  const projectRoot = getProjectRoot();
-  ensureLoopDir();
-
-  log('info', '观测模式：交互式运行，实时显示工具调用和决策过程');
-  log('info', '退出：Ctrl+C');
-  console.log('--------------------------------------------');
-
-  await runViewSession(requirement, { projectRoot, ...opts });
-}
-
 async function add(instruction, opts = {}) {
   await requireSdk();
   const p = paths();
@@ -365,4 +354,4 @@ async function add(instruction, opts = {}) {
   printStats();
 }
 
-module.exports = { run, view, add };
+module.exports = { run, add };

package/src/scanner.js

@@ -4,6 +4,33 @@ const fs = require('fs');
 const { paths, log, ensureLoopDir } = require('./config');
 const { runScanSession } = require('./session');
 
+function validateProfile() {
+  const p = paths();
+  if (!fs.existsSync(p.profile)) return { valid: false, issues: ['profile 不存在'] };
+
+  let profile;
+  try {
+    profile = JSON.parse(fs.readFileSync(p.profile, 'utf8'));
+  } catch {
+    return { valid: false, issues: ['profile JSON 格式错误'] };
+  }
+
+  const issues = [];
+
+  if (!profile.tech_stack?.backend?.framework && !profile.tech_stack?.frontend?.framework) {
+    issues.push('tech_stack 缺少 backend 或 frontend 框架');
+  }
+  if (profile.tech_stack?.backend?.framework &&
+      (!profile.services || profile.services.length === 0)) {
+    issues.push('有后端框架但 services 为空（缺少启动命令和端口）');
+  }
+  if (!profile.existing_docs || profile.existing_docs.length === 0) {
+    issues.push('existing_docs 为空（至少需要 README.md）');
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+
 async function scan(requirement, opts = {}) {
   const p = paths();
   ensureLoopDir();
@@ -15,6 +42,10 @@ async function scan(requirement, opts = {}) {
     const result = await runScanSession(requirement, opts);
 
     if (fs.existsSync(p.profile) && fs.existsSync(p.tasksFile)) {
+      const profileCheck = validateProfile();
+      if (!profileCheck.valid) {
+        log('warn', `profile 质量问题: ${profileCheck.issues.join('; ')}`);
+      }
       log('ok', '初始化完成');
       return { success: true, cost: result.cost };
     }
@@ -28,4 +59,4 @@ async function scan(requirement, opts = {}) {
   return { success: false, cost: null };
 }
 
-module.exports = { scan };
+module.exports = { scan, validateProfile };

package/src/session.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const { paths, loadConfig, buildEnvVars, getAllowedTools, log } = require('./config');
 const { Indicator, inferPhaseStep } = require('./indicator');
-const { buildSystemPrompt, buildCodingPrompt, buildScanPrompt, buildViewPrompt, buildAddPrompt } = require('./prompts');
+const { buildSystemPrompt, buildCodingPrompt, buildScanPrompt, buildAddPrompt } = require('./prompts');
 
 let _sdkModule = null;
 async function loadSDK() {
@@ -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);
       }
@@ -204,42 +208,6 @@ async function runScanSession(requirement, opts = {}) {
   }
 }
 
-async function runViewSession(requirement, opts = {}) {
-  const sdk = await loadSDK();
-  const p = paths();
-  const config = loadConfig();
-  applyEnvConfig(config);
-
-  let systemPrompt;
-  let prompt;
-
-  if (!fs.existsSync(p.profile) || !fs.existsSync(p.tasksFile)) {
-    systemPrompt = buildSystemPrompt(true);
-    const projectType = hasCodeFiles(opts.projectRoot || process.cwd()) ? 'existing' : 'new';
-    prompt = buildViewPrompt({ needsScan: true, projectType, requirement });
-  } else {
-    systemPrompt = buildSystemPrompt(false);
-    const { loadTasks, getFeatures } = require('./tasks');
-    const data = loadTasks();
-    const features = getFeatures(data);
-    const allDone = features.length > 0 && features.every(f => f.status === 'done');
-    prompt = buildViewPrompt({ allDone });
-  }
-
-  try {
-    const queryOpts = buildQueryOptions(config, opts);
-    queryOpts.systemPrompt = systemPrompt;
-
-    const session = sdk.query({ prompt, options: queryOpts });
-
-    for await (const message of session) {
-      logMessage(message, null);
-    }
-  } catch (err) {
-    log('error', `观测模式错误: ${err.message}`);
-  }
-}
-
 async function runAddSession(instruction, opts = {}) {
   const sdk = await loadSDK();
   const config = loadConfig();
@@ -289,7 +257,6 @@ function hasCodeFiles(projectRoot) {
 module.exports = {
   runCodingSession,
   runScanSession,
-  runViewSession,
   runAddSession,
   hasCodeFiles,
 };

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,10 +242,11 @@ pending ──→ in_progress ──→ testing ──→ done
 
 ### 第六步：收尾（每次会话必须执行）
 
-1. **停止本次启动的后台服务**：`lsof -ti :端口 | xargs kill`，避免下次 session 端口冲突
-2. **按需更新文档**：
+1. **后台服务管理**：根据 prompt 提示决定——单次模式（`--max 1`）时停止所有后台服务（`lsof -ti :端口 | xargs kill`）；连续模式时保持服务运行，下个 session 继续使用
+2. **按需更新文档和 profile**：
    - **README / 用户文档**：仅当对外行为变化（新增功能、API 变更、使用方式变化）时更新
    - **架构 / API 文档**：如果本次新增了模块、改变了模块职责或新增了 API 端点，更新 `existing_docs` 中对应的架构或 API 文档。同时更新 `project_profile.json` 的 `existing_docs` 列表（若新增了文档文件）
+   - **profile 补全**：如果 prompt 中提示 `project_profile.json` 有缺陷（如 services 为空、existing_docs 为空），在此步骤补全。Harness 依赖 profile 做环境初始化和上下文注入
 3. **Git 提交**：`git add -A && git commit -m "feat(task-id): 功能描述"`
 4. **写入 session_result.json**（notes 要充分记录上下文供下次恢复）：
    ```json