claude-coder 1.0.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "claude-coder",
+  "version": "1.0.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"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "docs/"
+  ],
+  "keywords": [
+    "claude-coder",
+    "claude",
+    "claude-code",
+    "ai",
+    "agent",
+    "autonomous",
+    "automation",
+    "coding",
+    "harness",
+    "loop",
+    "agent-harness",
+    "task-decomposition",
+    "code-generation"
+  ],
+  "author": "lk19940215",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lk19940215/claude-coder.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.14.0"
+  },
+  "dependencies": {}
+}

package/src/config.js

@@ -0,0 +1,211 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const COLOR = {
+  red: '\x1b[0;31m',
+  green: '\x1b[0;32m',
+  yellow: '\x1b[1;33m',
+  blue: '\x1b[0;34m',
+  reset: '\x1b[0m',
+};
+
+function log(level, msg) {
+  const tags = {
+    info:  `${COLOR.blue}[INFO]${COLOR.reset} `,
+    ok:    `${COLOR.green}[OK]${COLOR.reset}   `,
+    warn:  `${COLOR.yellow}[WARN]${COLOR.reset} `,
+    error: `${COLOR.red}[ERROR]${COLOR.reset}`,
+  };
+  console.error(`${tags[level] || ''} ${msg}`);
+}
+
+function getProjectRoot() {
+  return process.cwd();
+}
+
+function getLoopDir() {
+  return path.join(getProjectRoot(), '.claude-coder');
+}
+
+function ensureLoopDir() {
+  const dir = getLoopDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const runtime = path.join(dir, '.runtime');
+  if (!fs.existsSync(runtime)) fs.mkdirSync(runtime, { recursive: true });
+  const logs = path.join(runtime, 'logs');
+  if (!fs.existsSync(logs)) fs.mkdirSync(logs, { recursive: true });
+  return dir;
+}
+
+function getTemplatePath(name) {
+  return path.join(__dirname, '..', 'templates', name);
+}
+
+function paths() {
+  const loopDir = getLoopDir();
+  const runtime = path.join(loopDir, '.runtime');
+  return {
+    loopDir,
+    envFile:          path.join(loopDir, '.env'),
+    tasksFile:        path.join(loopDir, 'tasks.json'),
+    progressFile:     path.join(loopDir, 'progress.json'),
+    sessionResult:    path.join(loopDir, 'session_result.json'),
+    profile:          path.join(loopDir, 'project_profile.json'),
+    testsFile:        path.join(loopDir, 'tests.json'),
+    syncState:        path.join(loopDir, 'sync_state.json'),
+    reqHashFile:      path.join(loopDir, 'requirements_hash.current'),
+    claudeMd:         getTemplatePath('CLAUDE.md'),
+    scanProtocol:     getTemplatePath('SCAN_PROTOCOL.md'),
+    runtime,
+    phaseFile:        path.join(runtime, 'phase'),
+    stepFile:         path.join(runtime, 'step'),
+    activityLog:      path.join(runtime, 'activity.log'),
+    logsDir:          path.join(runtime, 'logs'),
+  };
+}
+
+// --------------- .env parsing ---------------
+
+function parseEnvFile(filepath) {
+  if (!fs.existsSync(filepath)) return {};
+  const content = fs.readFileSync(filepath, 'utf8');
+  const vars = {};
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (match) {
+      vars[match[1]] = match[2].trim().replace(/^["']|["']$/g, '');
+    }
+  }
+  return vars;
+}
+
+// --------------- Model mapping ---------------
+
+function loadConfig() {
+  const p = paths();
+  const env = parseEnvFile(p.envFile);
+  const config = {
+    provider: env.MODEL_PROVIDER || 'claude',
+    baseUrl: env.ANTHROPIC_BASE_URL || '',
+    apiKey: env.ANTHROPIC_API_KEY || '',
+    authToken: env.ANTHROPIC_AUTH_TOKEN || '',
+    model: env.ANTHROPIC_MODEL || '',
+    timeoutMs: parseInt(env.API_TIMEOUT_MS, 10) || 3000000,
+    mcpToolTimeout: parseInt(env.MCP_TOOL_TIMEOUT, 10) || 30000,
+    mcpPlaywright: env.MCP_PLAYWRIGHT === 'true',
+    debug: env.CLAUDE_DEBUG || '',
+    disableNonessential: env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC || '',
+    effortLevel: env.CLAUDE_CODE_EFFORT_LEVEL || '',
+    smallFastModel: env.ANTHROPIC_SMALL_FAST_MODEL || '',
+    defaultOpus: env.ANTHROPIC_DEFAULT_OPUS_MODEL || '',
+    defaultSonnet: env.ANTHROPIC_DEFAULT_SONNET_MODEL || '',
+    defaultHaiku: env.ANTHROPIC_DEFAULT_HAIKU_MODEL || '',
+    thinkingBudget: env.ANTHROPIC_THINKING_BUDGET || '',
+    raw: env,
+  };
+
+  // GLM: default model if not set
+  if (config.baseUrl && (config.baseUrl.includes('bigmodel.cn') || config.baseUrl.includes('z.ai'))) {
+    if (!config.model) config.model = 'glm-4.7';
+  }
+
+  // DeepSeek chat → haiku shim (prevent reasoner billing)
+  if (config.baseUrl.includes('deepseek') && config.model === 'deepseek-chat') {
+    config.model = 'claude-3-haiku-20240307';
+    config.defaultOpus = 'claude-3-haiku-20240307';
+    config.defaultSonnet = 'claude-3-haiku-20240307';
+    config.defaultHaiku = 'claude-3-haiku-20240307';
+    config.smallFastModel = 'claude-3-haiku-20240307';
+    config.thinkingBudget = '0';
+  }
+
+  return config;
+}
+
+function buildEnvVars(config) {
+  const env = { ...process.env };
+  if (config.baseUrl) env.ANTHROPIC_BASE_URL = config.baseUrl;
+  if (config.apiKey) env.ANTHROPIC_API_KEY = config.apiKey;
+  if (config.authToken) env.ANTHROPIC_AUTH_TOKEN = config.authToken;
+  if (config.model) env.ANTHROPIC_MODEL = config.model;
+  if (config.timeoutMs) env.API_TIMEOUT_MS = String(config.timeoutMs);
+  if (config.mcpToolTimeout) env.MCP_TOOL_TIMEOUT = String(config.mcpToolTimeout);
+  if (config.smallFastModel) env.ANTHROPIC_SMALL_FAST_MODEL = config.smallFastModel;
+  if (config.disableNonessential) env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = config.disableNonessential;
+  if (config.effortLevel) env.CLAUDE_CODE_EFFORT_LEVEL = config.effortLevel;
+  if (config.defaultOpus) env.ANTHROPIC_DEFAULT_OPUS_MODEL = config.defaultOpus;
+  if (config.defaultSonnet) env.ANTHROPIC_DEFAULT_SONNET_MODEL = config.defaultSonnet;
+  if (config.defaultHaiku) env.ANTHROPIC_DEFAULT_HAIKU_MODEL = config.defaultHaiku;
+  if (config.thinkingBudget) env.ANTHROPIC_THINKING_BUDGET = config.thinkingBudget;
+  return env;
+}
+
+// --------------- Allowed tools ---------------
+
+function getAllowedTools(config) {
+  const tools = ['Read', 'Edit', 'Write', 'Bash', 'Glob', 'Grep'];
+  if (config.mcpPlaywright) tools.push('mcp__playwright__*');
+  return tools;
+}
+
+// --------------- Sync to global claude settings ---------------
+
+function syncToGlobal() {
+  const config = loadConfig();
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  const settingsDir = path.dirname(settingsPath);
+
+  if (!fs.existsSync(settingsDir)) fs.mkdirSync(settingsDir, { recursive: true });
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch { /* ignore */ }
+  }
+
+  for (const key of ['apiKey', 'anthropicBaseUrl', 'defaultSonnetModel', 'defaultOpusModel', 'defaultHaikuModel', 'model']) {
+    delete settings[key];
+  }
+
+  if (!settings.env || typeof settings.env !== 'object') settings.env = {};
+
+  const envVars = buildEnvVars(config);
+  for (const [key, value] of Object.entries(envVars)) {
+    if (key.startsWith('ANTHROPIC_') || key.endsWith('_TIMEOUT_MS') || key === 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC') {
+      settings.env[key] = value;
+    }
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+  log('ok', `已同步配置到 ${settingsPath}`);
+}
+
+// --------------- Requirements hash ---------------
+
+function getRequirementsHash() {
+  const crypto = require('crypto');
+  const reqFile = path.join(getProjectRoot(), 'requirements.md');
+  if (!fs.existsSync(reqFile)) return '';
+  const content = fs.readFileSync(reqFile, 'utf8');
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+module.exports = {
+  COLOR,
+  log,
+  getProjectRoot,
+  getLoopDir,
+  ensureLoopDir,
+  getTemplatePath,
+  paths,
+  parseEnvFile,
+  loadConfig,
+  buildEnvVars,
+  getAllowedTools,
+  syncToGlobal,
+  getRequirementsHash,
+};

package/src/indicator.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const fs = require('fs');
+const { paths, COLOR } = require('./config');
+
+const SPINNERS = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+class Indicator {
+  constructor() {
+    this.phase = 'thinking';
+    this.step = '';
+    this.spinnerIndex = 0;
+    this.timer = null;
+    this.lastActivity = '';
+    this.sessionNum = 0;
+    this.startTime = Date.now();
+  }
+
+  start(sessionNum) {
+    this.sessionNum = sessionNum;
+    this.startTime = Date.now();
+    this.timer = setInterval(() => this._render(), 500);
+  }
+
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    process.stderr.write('\r\x1b[K');
+  }
+
+  updatePhase(phase) {
+    this.phase = phase;
+    this._writePhaseFile();
+  }
+
+  updateStep(step) {
+    this.step = step;
+    this._writeStepFile();
+  }
+
+  appendActivity(toolName, summary) {
+    const ts = new Date().toISOString();
+    const entry = `[${ts}] ${toolName}: ${summary}`;
+    this.lastActivity = entry;
+    try {
+      const p = paths();
+      fs.appendFileSync(p.activityLog, entry + '\n', 'utf8');
+    } catch { /* ignore */ }
+  }
+
+  _writePhaseFile() {
+    try { fs.writeFileSync(paths().phaseFile, this.phase, 'utf8'); } catch { /* ignore */ }
+  }
+
+  _writeStepFile() {
+    try { fs.writeFileSync(paths().stepFile, this.step, 'utf8'); } catch { /* ignore */ }
+  }
+
+  _render() {
+    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}`;
+    if (this.step) line += ` | ${this.step}`;
+
+    const maxWidth = process.stderr.columns || 80;
+    if (line.length > maxWidth + 20) line = line.slice(0, maxWidth + 20);
+
+    process.stderr.write(`\r\x1b[K${line}`);
+  }
+}
+
+// Phase-signal logic: infer phase/step from tool calls
+function inferPhaseStep(indicator, toolName, toolInput) {
+  const name = (toolName || '').toLowerCase();
+
+  if (name === 'write' || name === 'edit' || name === 'str_replace_editor' || name === 'strreplace') {
+    indicator.updatePhase('coding');
+  } else if (name === 'bash' || name === 'shell') {
+    const cmd = typeof toolInput === 'object' ? (toolInput.command || '') : String(toolInput || '');
+    if (cmd.includes('git ')) {
+      indicator.updateStep('Git 操作');
+    } else if (cmd.includes('npm ') || cmd.includes('pip ') || cmd.includes('pnpm ')) {
+      indicator.updateStep('安装依赖');
+    } else if (cmd.includes('test') || cmd.includes('curl') || cmd.includes('pytest')) {
+      indicator.updateStep('测试验证');
+      indicator.updatePhase('coding');
+    } else {
+      indicator.updatePhase('coding');
+    }
+  } else if (name === 'read' || name === 'glob' || name === 'grep') {
+    indicator.updatePhase('thinking');
+    indicator.updateStep('读取文件');
+  }
+
+  const summary = typeof toolInput === 'object'
+    ? (toolInput.path || toolInput.command || toolInput.pattern || JSON.stringify(toolInput).slice(0, 80))
+    : String(toolInput || '').slice(0, 80);
+  indicator.appendActivity(toolName, summary);
+}
+
+module.exports = { Indicator, inferPhaseStep };

package/src/init.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const fs = require('fs');
+const net = require('net');
+const http = require('http');
+const { spawn, execSync } = require('child_process');
+const { paths, log, getProjectRoot } = require('./config');
+
+function loadProfile() {
+  const p = paths();
+  if (!fs.existsSync(p.profile)) {
+    log('error', '未找到 project_profile.json，请先运行 claude-coder run 完成项目扫描');
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(p.profile, 'utf8'));
+}
+
+function isPortFree(port) {
+  return new Promise(resolve => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => { server.close(); resolve(true); });
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+function waitForHealth(url, timeoutMs = 15000) {
+  const start = Date.now();
+  return new Promise(resolve => {
+    const check = () => {
+      if (Date.now() - start > timeoutMs) { resolve(false); return; }
+      const req = http.get(url, res => {
+        resolve(res.statusCode < 500);
+      });
+      req.on('error', () => setTimeout(check, 1000));
+      req.setTimeout(3000, () => { req.destroy(); setTimeout(check, 1000); });
+    };
+    check();
+  });
+}
+
+function runCmd(cmd, cwd) {
+  try {
+    execSync(cmd, { cwd: cwd || getProjectRoot(), stdio: 'inherit', shell: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function init() {
+  const profile = loadProfile();
+  const projectRoot = getProjectRoot();
+  let stepCount = 0;
+
+  // 1. Environment activation
+  const envSetup = profile.env_setup || {};
+  if (envSetup.python_env && envSetup.python_env !== 'system' && envSetup.python_env !== 'none') {
+    stepCount++;
+    if (envSetup.python_env.startsWith('conda:')) {
+      const envName = envSetup.python_env.slice(6);
+      log('info', `[${stepCount}] Python 环境: conda activate ${envName}`);
+      runCmd(`conda activate ${envName}`);
+    } else if (envSetup.python_env === 'venv') {
+      log('info', `[${stepCount}] Python 环境: venv`);
+      runCmd('source .venv/bin/activate || .venv\\Scripts\\activate');
+    }
+  }
+  if (envSetup.node_version && envSetup.node_version !== 'none') {
+    stepCount++;
+    log('info', `[${stepCount}] Node.js: v${envSetup.node_version}`);
+    runCmd(`nvm use ${envSetup.node_version}`);
+  }
+
+  // 2. Dependencies
+  const pkgManagers = (profile.tech_stack && profile.tech_stack.package_managers) || [];
+  for (const pm of pkgManagers) {
+    stepCount++;
+    if (pm === 'npm' || pm === 'yarn' || pm === 'pnpm') {
+      if (fs.existsSync(`${projectRoot}/node_modules`)) {
+        log('ok', `[${stepCount}] ${pm} 依赖已安装，跳过`);
+      } else {
+        log('info', `[${stepCount}] 安装依赖: ${pm} install`);
+        runCmd(`${pm} install`, projectRoot);
+      }
+    } else if (pm === 'pip') {
+      const reqFile = fs.existsSync(`${projectRoot}/requirements.txt`);
+      if (reqFile) {
+        log('info', `[${stepCount}] 安装依赖: pip install -r requirements.txt`);
+        runCmd('pip install -r requirements.txt', projectRoot);
+      }
+    }
+  }
+
+  // 3. Custom init commands
+  const customInit = profile.custom_init || [];
+  for (const cmd of customInit) {
+    stepCount++;
+    log('info', `[${stepCount}] 自定义: ${cmd}`);
+    runCmd(cmd, projectRoot);
+  }
+
+  // 4. Services
+  const services = profile.services || [];
+  for (const svc of services) {
+    stepCount++;
+    const free = await isPortFree(svc.port);
+    if (!free) {
+      log('ok', `[${stepCount}] ${svc.name} 已在端口 ${svc.port} 运行，跳过`);
+      continue;
+    }
+
+    log('info', `[${stepCount}] 启动 ${svc.name} (端口 ${svc.port})...`);
+    const cwd = svc.cwd ? `${projectRoot}/${svc.cwd}` : projectRoot;
+    const child = spawn(svc.command, { cwd, shell: true, detached: true, stdio: 'ignore' });
+    child.unref();
+
+    if (svc.health_check) {
+      const healthy = await waitForHealth(svc.health_check);
+      if (healthy) {
+        log('ok', `${svc.name} 就绪: ${svc.health_check}`);
+      } else {
+        log('warn', `${svc.name} 健康检查超时 (${svc.health_check})，继续执行`);
+      }
+    }
+  }
+
+  // Summary
+  if (stepCount === 0) {
+    log('info', '无需初始化操作');
+  } else {
+    log('ok', `初始化完成 (${stepCount} 步)`);
+  }
+
+  if (services.length > 0) {
+    console.log('');
+    for (const svc of services) {
+      console.log(`  ${svc.name}: http://localhost:${svc.port}`);
+    }
+    console.log('');
+  }
+}
+
+module.exports = { init };

package/src/prompts.js

@@ -0,0 +1,189 @@
+'use strict';
+
+const fs = require('fs');
+const { paths, loadConfig, getRequirementsHash } = require('./config');
+
+/**
+ * Build system prompt by combining template files.
+ * @param {boolean} includeScanProtocol - Whether to append SCAN_PROTOCOL.md
+ */
+function buildSystemPrompt(includeScanProtocol = false) {
+  const p = paths();
+  let prompt = fs.readFileSync(p.claudeMd, 'utf8');
+  if (includeScanProtocol && fs.existsSync(p.scanProtocol)) {
+    prompt += '\n\n' + fs.readFileSync(p.scanProtocol, 'utf8');
+  }
+  return prompt;
+}
+
+/**
+ * Build user prompt for coding sessions.
+ * Includes conditional hints based on session state.
+ */
+function buildCodingPrompt(sessionNum, opts = {}) {
+  const p = paths();
+  const config = loadConfig();
+  const consecutiveFailures = opts.consecutiveFailures || 0;
+
+  // Hint 1: Requirements change detection
+  const reqHash = getRequirementsHash();
+  let reqSyncHint = '';
+  if (reqHash) {
+    fs.writeFileSync(p.reqHashFile, reqHash, 'utf8');
+    let lastHash = '';
+    if (fs.existsSync(p.syncState)) {
+      try { lastHash = JSON.parse(fs.readFileSync(p.syncState, 'utf8')).last_requirements_hash || ''; } catch { /* ignore */ }
+    }
+    if (lastHash !== reqHash) {
+      reqSyncHint = '需求已变更：第一步中请读取 requirements.md，将新增需求追加为 pending 任务到 tasks.json。';
+    }
+  } else if (fs.existsSync(p.reqHashFile)) {
+    fs.unlinkSync(p.reqHashFile);
+  }
+
+  // Hint 2: Playwright MCP availability
+  const mcpHint = config.mcpPlaywright
+    ? '前端/全栈任务可用 Playwright MCP（browser_navigate、browser_snapshot、browser_click 等）做端到端测试。'
+    : '';
+
+  // Hint 3: Retry context from previous failures
+  let retryContext = '';
+  if (consecutiveFailures > 0 && opts.lastValidateLog) {
+    retryContext = `\n注意：上次会话校验失败，原因：${opts.lastValidateLog}。请避免同样的问题。`;
+  }
+
+  // Hint 4: Environment readiness
+  let envHint = '';
+  if (consecutiveFailures === 0 && sessionNum > 1) {
+    envHint = '环境已就绪，第二步可跳过 claude-coder init，仅确认服务存活。涉及新依赖时仍需运行 claude-coder init。';
+  }
+
+  // Hint 5: Existing test records
+  let testHint = '';
+  if (fs.existsSync(p.testsFile)) {
+    try {
+      const count = (JSON.parse(fs.readFileSync(p.testsFile, 'utf8')).test_cases || []).length;
+      if (count > 0) testHint = `tests.json 已有 ${count} 条验证记录，Step 5 时先查已有记录避免重复验证。`;
+    } catch { /* ignore */ }
+  }
+
+  // Hint 6: Project documentation awareness
+  let docsHint = '';
+  if (fs.existsSync(p.profile)) {
+    try {
+      const profile = JSON.parse(fs.readFileSync(p.profile, 'utf8'));
+      const docs = profile.existing_docs || [];
+      if (docs.length > 0) {
+        docsHint = `项目文档: ${docs.join(', ')}。Step 4 编码前先读与任务相关的文档，了解接口约定和编码规范。完成后若新增了模块或 API，更新对应文档。`;
+      }
+    } catch { /* ignore */ }
+  }
+
+  return [
+    `Session ${sessionNum}。执行 6 步流程。`,
+    '效率要求：先规划后编码，完成全部编码后再统一测试，禁止编码-测试反复跳转。后端任务用 curl 验证，不启动浏览器。',
+    reqSyncHint,
+    mcpHint,
+    testHint,
+    docsHint,
+    envHint,
+    `完成后写入 session_result.json。${retryContext}`,
+  ].filter(Boolean).join('\n');
+}
+
+/**
+ * Build task decomposition guide for scan and add sessions.
+ * Placed in user prompt (recency zone) for maximum attention.
+ */
+function buildTaskGuide(projectType) {
+  const lines = [
+    '任务分解指导（严格遵守）：',
+    '1. 粒度：每个任务是独立可测试的功能单元，1-3 session 可完成，不超 500 行新增',
+    '2. steps 具体可验证：最后一步必须是 curl/grep 等验证命令',
+    '3. depends_on 形成 DAG（有向无环图），不得循环依赖',
+    '4. 单任务 steps 不超过 5 步，超过则拆分为多个任务',
+    '5. category 准确：backend | frontend | fullstack | infra',
+    '6. 第一个任务从第一个有业务逻辑的功能开始，不重复脚手架内容',
+    '',
+    '验证命令模板：',
+    '  API: curl -s -o /dev/null -w "%{http_code}" http://localhost:PORT/path → 200',
+    '  文件: grep -q "关键内容" path/to/file && echo "pass"',
+    '  构建: npm run build 2>&1 | tail -1 → 无 error',
+    '',
+    '反面案例（禁止出现）：',
+    '  X "实现用户功能" → 太模糊，应拆为具体接口',
+    '  X "编写测试" → 无具体内容，测试应内嵌在 steps 末尾',
+    '  X steps 只有 "实现xxx" 没有验证步骤',
+  ];
+
+  if (projectType === 'new') {
+    lines.push('', '新项目注意：infra 任务合并为尽量少的条目，不拆碎');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build user prompt for scan sessions.
+ */
+function buildScanPrompt(projectType, requirement) {
+  const taskGuide = buildTaskGuide(projectType);
+  return [
+    '你是项目初始化 Agent，同时也是资深的需求分析师。',
+    '',
+    `项目类型: ${projectType}`,
+    `用户需求: ${requirement || '(无指定需求)'}`,
+    '',
+    '步骤 1-2：按「项目扫描协议」扫描项目、生成 project_profile.json。',
+    '步骤 3：根据以下指导分解任务到 tasks.json（格式见 CLAUDE.md）：',
+    '',
+    taskGuide,
+    '',
+    '步骤 4：写入 session_result.json 并 git commit。',
+  ].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.
+ */
+function buildAddPrompt(instruction) {
+  const taskGuide = buildTaskGuide();
+  return [
+    '重要：这是任务追加 session，不是常规编码 session。不执行 6 步流程。',
+    '',
+    '步骤：',
+    '1. 读取 .claude-coder/tasks.json 了解已有任务和最大 id/priority',
+    '2. 读取 .claude-coder/project_profile.json 了解项目技术栈',
+    '3. 根据用户指令追加新任务（status: pending）',
+    '',
+    taskGuide,
+    '',
+    '新任务 id 和 priority 从已有最大值递增。不修改已有任务，不实现代码。',
+    'git add -A && git commit -m "chore: add new tasks"',
+    '写入 session_result.json',
+    '',
+    `用户指令：${instruction}`,
+  ].join('\n');
+}
+
+module.exports = {
+  buildSystemPrompt,
+  buildCodingPrompt,
+  buildTaskGuide,
+  buildScanPrompt,
+  buildViewPrompt,
+  buildAddPrompt,
+};