claude-coder 1.0.5 → 1.0.6

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
 ```
 
@@ -189,8 +184,7 @@ 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 + SCAN_PROTOCOL.md | `buildScanPrompt()` + 任务分解指导 + profile 质量要求 | 首次运行 |
 | **追加** | CLAUDE.md | `buildAddPrompt()` + 任务分解指导 | `claude-coder add` |
 
 ### 编码 Session 的 8 个条件 Hint
@@ -200,7 +194,7 @@ flowchart TB
 | 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 已注入当前任务上下文 |
@@ -429,3 +423,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "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/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 */ }
   }
 
@@ -176,6 +183,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 +198,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 +226,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;
 
@@ -338,18 +338,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 +353,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() {
@@ -204,42 +204,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 +253,6 @@ function hasCodeFiles(projectRoot) {
 module.exports = {
   runCodingSession,
   runScanSession,
-  runViewSession,
   runAddSession,
   hasCodeFiles,
 };

package/templates/CLAUDE.md

@@ -242,9 +242,10 @@ pending ──→ in_progress ──→ testing ──→ done
 ### 第六步：收尾（每次会话必须执行）
 
 1. **停止本次启动的后台服务**：`lsof -ti :端口 | xargs kill`，避免下次 session 端口冲突
-2. **按需更新文档**：
+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