claude-coder 1.7.1 → 1.8.1

package/src/core/plan.js

@@ -0,0 +1,325 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { runSession } = require('./session');
+const { buildQueryOptions } = require('./query');
+const { buildSystemPrompt, buildPlanPrompt } = require('./prompts');
+const { log, loadConfig } = require('../common/config');
+const { assets } = require('../common/assets');
+const { extractResultText } = require('../common/logging');
+const { printStats } = require('../common/tasks');
+const { syncAfterPlan } = require('./harness');
+
+const EXIT_TIMEOUT_MS = 300000;
+const PLANS_DIR = path.join(os.homedir(), '.claude', 'plans');
+
+function buildPlanOnlyPrompt(instruction, opts = {}) {
+  const interactive = opts.interactive || false;
+  const reqFile = opts.reqFile || null;
+
+  const inputSection = reqFile
+    ? `需求文件路径: ${reqFile}\n先读取该文件，理解用户需求和约束。`
+    : `用户需求:\n${instruction}`;
+
+  const interactionRule = interactive
+    ? '如有不确定的关键决策点，向用户提问对话确认方案。'
+    : '不要提问，默认使用最佳推荐方案。';
+
+  return `你是一个资深技术架构师。根据以下需求，探索项目代码库后输出完整的技术方案文档。
+
+${inputSection}
+
+【流程】
+1. 探索项目代码库，理解结构和技术栈
+2. ${interactionRule}
+3. 使用 Write 工具将完整计划写入 ~/.claude/plans/ 目录（.md 格式）
+4. 写入后输出标记（独占一行）：PLAN_FILE_PATH: <计划文件绝对路径>
+5. 简要总结计划要点
+`;
+}
+
+/**
+ * 从文本中提取计划文件路径
+ * 优先级：PLAN_FILE_PATH 标记 > .claude/plans/*.md > 反引号包裹 .md > 任意绝对 .md
+ */
+function extractPlanPath(text) {
+  if (!text) return null;
+
+  const tagMatch = text.match(/PLAN_FILE_PATH:\s*(\S+\.md)/);
+  if (tagMatch) return tagMatch[1];
+
+  const plansMatch = text.match(/([^\s`'"(]*\.claude\/plans\/[^\s`'"()]+\.md)/);
+  if (plansMatch) return plansMatch[1];
+
+  const backtickMatch = text.match(/`([^`]+\.md)`/);
+  if (backtickMatch) return backtickMatch[1];
+
+  const absMatch = text.match(/(\/[^\s`'"]+\.md)/);
+  if (absMatch) return absMatch[1];
+
+  return null;
+}
+
+/**
+ * 多源提取计划路径（按可靠性从高到低）
+ * 1. Write 工具调用参数（最可靠）
+ * 2. assistant 消息流文本
+ * 3. result.result 文本
+ * 4. plans 目录最新文件（兜底）
+ */
+function extractPlanPathFromCollected(collected, startTime) {
+  // 第一层：从 Write 工具调用参数中直接获取
+  for (const msg of collected) {
+    if (msg.type !== 'assistant' || !msg.message?.content) continue;
+    for (const block of msg.message.content) {
+      if (block.type === 'tool_use' && block.name === 'Write') {
+        const target = block.input?.file_path || block.input?.path || '';
+        if (target.includes('.claude/plans/') && target.endsWith('.md')) {
+          if (fs.existsSync(target)) return target;
+        }
+      }
+    }
+  }
+
+  // 第二层：从所有 assistant 文本中提取
+  let fullText = '';
+  for (const msg of collected) {
+    if (msg.type === 'assistant' && msg.message?.content) {
+      for (const block of msg.message.content) {
+        if (block.type === 'text' && block.text) fullText += block.text;
+      }
+    }
+  }
+  if (fullText) {
+    const p = extractPlanPath(fullText);
+    if (p && fs.existsSync(p)) return p;
+  }
+
+  // 第三层：从 result.result 中提取
+  const resultText = extractResultText(collected);
+  if (resultText) {
+    const p = extractPlanPath(resultText);
+    if (p && fs.existsSync(p)) return p;
+  }
+
+  // 第四层：扫描 plans 目录，找 session 期间新建的文件
+  if (fs.existsSync(PLANS_DIR)) {
+    try {
+      const files = fs.readdirSync(PLANS_DIR)
+        .filter(f => f.endsWith('.md'))
+        .map(f => {
+          const fp = path.join(PLANS_DIR, f);
+          return { path: fp, mtime: fs.statSync(fp).mtimeMs };
+        })
+        .filter(f => f.mtime >= startTime)
+        .sort((a, b) => b.mtime - a.mtime);
+      if (files.length > 0) {
+        log('info', `从 plans 目录发现新文件: ${path.basename(files[0].path)}`);
+        return files[0].path;
+      }
+    } catch { /* ignore */ }
+  }
+
+  return null;
+}
+
+function copyPlanToProject(generatedPath) {
+  const filename = path.basename(generatedPath);
+  const targetDir = path.join(assets.projectRoot, '.claude-coder', 'plan');
+  const targetPath = path.join(targetDir, filename);
+
+  try {
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+    fs.copyFileSync(generatedPath, targetPath);
+    return targetPath;
+  } catch {
+    return generatedPath;
+  }
+}
+
+async function _executePlanGen(sdk, ctx, instruction, opts = {}) {
+  const prompt = buildPlanOnlyPrompt(instruction, opts);
+  const queryOpts = {
+    permissionMode: 'plan',
+    cwd: opts.projectRoot || assets.projectRoot,
+    hooks: ctx.hooks,
+  };
+  if (!opts.interactive) {
+    queryOpts.disallowedTools = ['askUserQuestion'];
+  }
+  if (opts.model) queryOpts.model = opts.model;
+
+  const startTime = Date.now();
+  let exitPlanModeDetected = false;
+  let exitPlanModeTime = null;
+
+  const collected = [];
+  const session = sdk.query({ prompt, options: queryOpts });
+
+  for await (const msg of session) {
+    if (ctx._isStalled && ctx._isStalled()) {
+      log('warn', '停顿超时，中断 plan 生成');
+      break;
+    }
+
+    if (exitPlanModeDetected && exitPlanModeTime) {
+      const elapsed = Date.now() - exitPlanModeTime;
+      if (elapsed > EXIT_TIMEOUT_MS && msg.type !== 'result') {
+        log('warn', '检测到 ExitPlanMode，等待审批超时，尝试从已收集消息中提取路径');
+        break;
+      }
+    }
+
+    collected.push(msg);
+    ctx._logMessage(msg);
+
+    if (msg.type === 'assistant' && msg.message?.content) {
+      for (const block of msg.message.content) {
+        if (block.type === 'tool_use' && block.name === 'ExitPlanMode') {
+          exitPlanModeDetected = true;
+          exitPlanModeTime = Date.now();
+        }
+      }
+    }
+  }
+
+  const planPath = extractPlanPathFromCollected(collected, startTime);
+
+  if (planPath) {
+    const targetPath = copyPlanToProject(planPath);
+    return { success: true, targetPath, generatedPath: planPath };
+  }
+
+  log('warn', '无法从输出中提取计划路径');
+  log('info', `请手动查看: ${PLANS_DIR}`);
+  return { success: false, reason: 'no_path', targetPath: null };
+}
+
+async function runPlanSession(instruction, opts = {}) {
+  const planOnly = opts.planOnly || false;
+  const interactive = opts.interactive || false;
+  const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 12);
+  const label = planOnly ? 'plan_only' : 'plan_tasks';
+  const hookType = interactive ? 'plan_interactive' : 'plan';
+
+  return runSession(hookType, {
+    opts,
+    sessionNum: 0,
+    logFileName: `plan_${ts}.log`,
+    label,
+
+    async execute(sdk, ctx) {
+      log('info', '正在生成计划方案...');
+
+      const planResult = await _executePlanGen(sdk, ctx, instruction, opts);
+
+      if (!planResult.success) {
+        log('error', `\n计划生成失败: ${planResult.reason || planResult.error}`);
+        return { success: false, reason: planResult.reason };
+      }
+
+      log('ok', `\n计划已生成: ${planResult.targetPath}`);
+
+      if (planOnly) {
+        return { success: true, planPath: planResult.targetPath };
+      }
+
+      log('info', '正在生成任务列表...');
+
+      const tasksPrompt = buildPlanPrompt(planResult.targetPath);
+      const queryOpts = buildQueryOptions(ctx.config, opts);
+      queryOpts.systemPrompt = buildSystemPrompt('plan');
+      queryOpts.hooks = ctx.hooks;
+      queryOpts.abortController = ctx.abortController;
+
+      await ctx.runQuery(sdk, tasksPrompt, queryOpts);
+
+      syncAfterPlan();
+      log('ok', '任务追加完成');
+      return { success: true, planPath: planResult.targetPath };
+    },
+  });
+}
+
+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 run(input, opts = {}) {
+  const instruction = input || '';
+
+  assets.ensureDirs();
+  const projectRoot = assets.projectRoot;
+
+  if (opts.readFile) {
+    const reqPath = path.resolve(projectRoot, opts.readFile);
+    if (!fs.existsSync(reqPath)) {
+      log('error', `文件不存在: ${reqPath}`);
+      process.exit(1);
+    }
+    opts.reqFile = reqPath;
+    if (instruction) {
+      log('info', `-r 模式下忽略文本输入，使用需求文件: ${reqPath}`);
+    } else {
+      console.log(`需求文件: ${reqPath}`);
+    }
+  }
+
+  if (!instruction && !opts.reqFile) {
+    log('error', '用法: claude-coder plan "需求内容"  或  claude-coder plan -r [requirements.md]');
+    process.exit(1);
+  }
+
+  const config = loadConfig();
+  // if opts.model is not set, use the default opus model or default model, make sure the model is set.
+  if (!opts.model) {
+    if (config.defaultOpus) {
+      opts.model = config.defaultOpus;
+    } else if (config.model) {
+      opts.model = config.model;
+    }
+  }
+
+  const displayModel = opts.model || config.model || '(default)';
+  log('ok', `模型配置已加载: ${config.provider || 'claude'} (plan 使用: ${displayModel})`);
+  if (opts.interactive) {
+    log('info', '交互模式已启用，模型可能会向您提问');
+  }
+
+  if (!assets.exists('profile')) {
+    log('error', 'profile 不存在，请先运行 claude-coder init 初始化项目');
+    process.exit(1);
+  }
+
+  let shouldAutoRun = false;
+  if (!opts.planOnly) {
+    shouldAutoRun = await promptAutoRun();
+  }
+
+  const result = await runPlanSession(instruction, { projectRoot, ...opts });
+
+  if (result.success) {
+    printStats();
+
+    if (shouldAutoRun) {
+      console.log('');
+      log('info', '开始自动执行任务...');
+      const { run: runCoding } = require('./runner');
+      await runCoding(opts);
+    }
+  }
+}
+
+module.exports = { runPlanSession, run };

package/src/core/prompts.js

@@ -0,0 +1,226 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadConfig } = require('../common/config');
+const { assets } = require('../common/assets');
+const { loadTasks, getStats } = require('../common/tasks');
+const { loadState, selectNextTask } = require('./harness');
+
+// --------------- System Prompt ---------------
+
+function buildSystemPrompt(type) {
+  const core = assets.read('coreProtocol') || '';
+  let specific = '';
+  switch (type) {
+    case 'scan':    specific = assets.read('scanSystem') || ''; break;
+    case 'coding':  specific = assets.read('codingSystem') || ''; break;
+    case 'plan':    specific = assets.read('planSystem') || ''; break;
+  }
+  return specific ? `${specific}\n\n${core}` : core;
+}
+
+// --------------- Task Type Detection ---------------
+
+const WEB_CATEGORIES = new Set(['frontend', 'fullstack', 'test', 'e2e']);
+const WEB_KEYWORDS = /playwright|browser|页面|前端|UI|端到端|e2e/i;
+
+function needsWebTools(task) {
+  if (!task) return true;
+  if (WEB_CATEGORIES.has(task.category)) return true;
+  const text = [task.description || '', ...(task.steps || [])].join(' ');
+  return WEB_KEYWORDS.test(text);
+}
+
+// --------------- Hint Builders ---------------
+
+function buildMcpHint(config, task) {
+  if (!config.mcpPlaywright) return '';
+  if (!needsWebTools(task)) return '';
+  return '前端/全栈任务可用 Playwright MCP（browser_navigate、browser_snapshot、browser_click 等）做端到端测试。';
+}
+
+function buildRetryHint(consecutiveFailures, lastValidateLog) {
+  if (consecutiveFailures > 0 && lastValidateLog) {
+    return `注意：上次会话校验失败，原因：${lastValidateLog}。请避免同样的问题。`;
+  }
+  return '';
+}
+
+function buildEnvHint(consecutiveFailures, sessionNum) {
+  if (sessionNum <= 1) return '首次会话，需要时执行 claude-coder init 初始化环境。';
+  if (consecutiveFailures > 0) return '上次失败，建议先确认环境状态。';
+  return '';
+}
+
+function buildDocsHint() {
+  const profile = assets.readJson('profile', null);
+  if (!profile) return '';
+  const docs = profile.existing_docs || [];
+  if (docs.length > 0) {
+    return `项目文档: ${docs.join(', ')}。编码前先读与任务相关的文档，了解接口约定和编码规范。`;
+  }
+  return '';
+}
+
+function buildTaskContext(projectRoot, taskId) {
+  try {
+    const taskData = loadTasks();
+    if (!taskData) return '无法读取 tasks.json，请手动检查。';
+    const features = taskData.features || [];
+    const stats = getStats(taskData);
+
+    const task = taskId
+      ? features.find(f => f.id === taskId)
+      : selectNextTask(taskData);
+
+    if (!task) return '无待处理任务。';
+
+    const steps = (task.steps || [])
+      .map((s, i) => `  ${i + 1}. ${s}`)
+      .join('\n');
+
+    const deps = (task.depends_on || []).length > 0
+      ? `depends_on: [${task.depends_on.join(', ')}]`
+      : '';
+
+    return [
+      `**${task.id}**: "${task.description}"`,
+      `状态: ${task.status}, category: ${task.category}, priority: ${task.priority || 'N/A'} ${deps}`,
+      `步骤:\n${steps}`,
+      `进度: ${stats.done}/${stats.total} done, ${stats.failed} failed`,
+      `项目路径: ${projectRoot}`,
+    ].join('\n');
+  } catch {
+    return '任务上下文加载失败，请读取 .claude-coder/tasks.json 自行确认。';
+  }
+}
+
+function buildTestEnvHint(projectRoot) {
+  if (assets.exists('testEnv')) {
+    return `测试凭证文件: ${projectRoot}/.claude-coder/test.env（含 API Key、测试账号等），测试前用 source 加载。`;
+  }
+  return '';
+}
+
+function buildPlaywrightAuthHint(config, task) {
+  if (!config.mcpPlaywright) return '';
+  if (!needsWebTools(task)) return '';
+  const mode = config.playwrightMode;
+  switch (mode) {
+    case 'persistent':
+      return 'Playwright MCP 使用 persistent 模式，浏览器登录状态持久保存，无需额外登录操作。';
+    case 'isolated':
+      return assets.exists('playwrightAuth')
+        ? 'Playwright MCP 使用 isolated 模式，已检测到登录状态文件，每次会话自动加载。'
+        : 'Playwright MCP 使用 isolated 模式，未检测到登录状态文件。如需登录，请先运行 claude-coder auth <URL>。';
+    case 'extension':
+      return 'Playwright MCP 使用 extension 模式，已连接用户真实浏览器，直接复用已有登录态。';
+    default:
+      return '';
+  }
+}
+
+function buildMemoryHint() {
+  const sr = assets.readJson('sessionResult', null);
+  if (!sr?.session_result) return '';
+  const base = `上次会话 ${sr.session_result}（${sr.status_before || '?'} → ${sr.status_after || '?'}）。`;
+  if (!sr.notes || !sr.notes.trim()) return base;
+  return `${base}遗留: ${sr.notes.slice(0, 200)}`;
+}
+
+function buildServiceHint(maxSessions) {
+  return maxSessions === 1
+    ? '单次模式：收尾时停止所有后台服务。'
+    : '连续模式：收尾时不要停止后台服务，保持服务运行以便下个 session 继续使用。';
+}
+
+// --------------- Context Builders ---------------
+
+function _resolveTask(taskId) {
+  try {
+    const taskData = loadTasks();
+    if (!taskData) return null;
+    const features = taskData.features || [];
+    return taskId ? features.find(f => f.id === taskId) : selectNextTask(taskData);
+  } catch { return null; }
+}
+
+/**
+ * 构建 coding session 的完整上下文（user prompt）
+ */
+function buildCodingContext(sessionNum, opts = {}) {
+  const config = loadConfig();
+  const consecutiveFailures = opts.consecutiveFailures || 0;
+  const projectRoot = assets.projectRoot;
+  const task = _resolveTask(opts.taskId);
+
+  return assets.render('codingUser', {
+    sessionNum,
+    taskContext: buildTaskContext(projectRoot, opts.taskId),
+    mcpHint: buildMcpHint(config, task),
+    retryContext: buildRetryHint(consecutiveFailures, opts.lastValidateLog),
+    envHint: buildEnvHint(consecutiveFailures, sessionNum),
+    docsHint: buildDocsHint(),
+    testEnvHint: buildTestEnvHint(projectRoot),
+    playwrightAuthHint: buildPlaywrightAuthHint(config, task),
+    memoryHint: buildMemoryHint(),
+    serviceHint: buildServiceHint(opts.maxSessions || 50),
+  });
+}
+
+// --------------- Scan Session ---------------
+
+function buildScanPrompt(projectType) {
+  return assets.render('scanUser', { projectType });
+}
+
+// --------------- Plan Session ---------------
+
+function buildPlanPrompt(planPath) {
+  const projectRoot = assets.projectRoot;
+
+  let taskContext = '';
+  let recentExamples = '';
+  try {
+    const taskData = loadTasks();
+    if (taskData) {
+      const features = taskData.features || [];
+      const state = loadState();
+      const nextId = `feat-${String(state.next_task_id).padStart(3, '0')}`;
+      const categories = [...new Set(features.map(f => f.category))].join(', ');
+
+      taskContext = `新任务 ID 从 ${nextId} 开始，priority 从 ${state.next_priority} 开始。已有 category: ${categories || '无'}。`;
+
+      const recent = features.slice(-3);
+      if (recent.length) {
+        recentExamples = '已有任务格式参考（保持一致性）：\n' +
+          recent.map(f => `  ${f.id}: "${f.description}" (category=${f.category}, steps=${(f.steps || []).length}步, depends_on=[${(f.depends_on || []).join(',')}])`).join('\n');
+      }
+    }
+  } catch { /* ignore */ }
+
+  let testRuleHint = '';
+  if (assets.exists('testRule') && assets.exists('mcpConfig')) {
+    testRuleHint = '【Playwright 测试规则】项目已配置 Playwright MCP（.mcp.json），' +
+      '`.claude-coder/assets/test_rule.md` 包含测试规范（Smart Snapshot、等待策略、步骤模板等）。' +
+      '前端页面 test 类任务 steps 首步加入 `【规则】阅读 .claude-coder/assets/test_rule.md`。';
+  }
+
+  return assets.render('planUser', {
+    taskContext,
+    recentExamples,
+    projectRoot,
+    planPath,
+    testRuleHint,
+  });
+}
+
+// --------------- Exports ---------------
+
+module.exports = {
+  buildSystemPrompt,
+  buildCodingContext,
+  buildScanPrompt,
+  buildPlanPrompt,
+};

package/src/core/query.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { buildEnvVars } = require('../common/config');
+const { assets } = require('../common/assets');
+
+/**
+ * 检查项目是否包含代码文件
+ */
+function hasCodeFiles(projectRoot) {
+  const markers = [
+    'package.json', 'pyproject.toml', 'requirements.txt', 'setup.py',
+    'Cargo.toml', 'go.mod', 'pom.xml', 'build.gradle',
+    'Makefile', 'Dockerfile', 'docker-compose.yml',
+    'README.md', 'main.py', 'app.py', 'index.js', 'index.ts',
+  ];
+  for (const m of markers) {
+    if (fs.existsSync(path.join(projectRoot, m))) return true;
+  }
+  for (const d of ['src', 'lib', 'app', 'backend', 'frontend', 'web', 'server', 'client']) {
+    if (fs.existsSync(path.join(projectRoot, d)) && fs.statSync(path.join(projectRoot, d)).isDirectory()) return true;
+  }
+  return false;
+}
+
+/**
+ * 构建 SDK query 选项
+ */
+function buildQueryOptions(config, opts = {}) {
+  const mode = opts.permissionMode || 'bypassPermissions';
+  const base = {
+    permissionMode: mode,
+    cwd: opts.projectRoot || assets.projectRoot,
+    env: buildEnvVars(config),
+    settingSources: ['project'],
+  };
+  if (mode === 'bypassPermissions') {
+    base.allowDangerouslySkipPermissions = true;
+  }
+  if (config.maxTurns > 0) base.maxTurns = config.maxTurns;
+  if (opts.model) base.model = opts.model;
+  else if (config.model) base.model = config.model;
+  return base;
+}
+
+module.exports = {
+  hasCodeFiles,
+  buildQueryOptions,
+};

package/src/core/repair.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { runSession } = require('./session');
+const { buildQueryOptions } = require('./query');
+const { log } = require('../common/config');
+
+/**
+ * 使用 AI 修复损坏的 JSON 文件
+ * @param {string} filePath - 文件绝对路径
+ * @param {object} [opts] - 透传给 runSession 的选项
+ */
+async function repairJsonFile(filePath, opts = {}) {
+  if (!fs.existsSync(filePath)) return;
+
+  const rawContent = fs.readFileSync(filePath, 'utf8');
+  if (!rawContent || !rawContent.trim()) return;
+
+  const fileName = path.basename(filePath);
+  log('info', `正在使用 AI 修复 ${fileName}...`);
+
+  const prompt = `文件 ${filePath} 的 JSON 格式已损坏，请修复并用 Write 工具写入原路径。\n\n当前损坏内容：\n${rawContent}`;
+
+  try {
+    await runSession('repair', {
+      opts,
+      sessionNum: 0,
+      logFileName: `repair_${fileName.replace('.json', '')}.log`,
+      label: `repair:${fileName}`,
+
+      async execute(sdk, ctx) {
+        const queryOpts = buildQueryOptions(ctx.config, opts);
+        queryOpts.hooks = ctx.hooks;
+        queryOpts.abortController = ctx.abortController;
+        await ctx.runQuery(sdk, prompt, queryOpts);
+        log('ok', `AI 修复 ${fileName} 完成`);
+        return {};
+      },
+    });
+  } catch (err) {
+    log('warn', `AI 修复 ${fileName} 失败: ${err.message}`);
+  }
+}
+
+module.exports = { repairJsonFile };