claude-coder 1.7.0 → 1.8.0

package/src/core/scan.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { log } = require('../common/config');
+const { assets } = require('../common/assets');
+const { runSession } = require('./base');
+const { buildQueryOptions, hasCodeFiles } = require('./query');
+const { buildSystemPrompt, buildScanPrompt } = require('./prompts');
+const { extractResult } = require('../common/logging');
+const { RETRY } = require('../common/constants');
+
+function validateProfile() {
+  if (!assets.exists('profile')) return { valid: false, issues: ['profile 不存在'] };
+
+  const profile = assets.readJson('profile', null);
+  if (!profile) return { valid: false, issues: ['profile 解析失败'] };
+  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 _runScanSession(requirement, opts = {}) {
+  const projectType = hasCodeFiles(opts.projectRoot || assets.projectRoot) ? 'existing' : 'new';
+  const dateStr = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+
+  return runSession('scan', {
+    opts,
+    sessionNum: 0,
+    logFileName: `scan_${dateStr}.log`,
+    label: `scan (${projectType})`,
+
+    async execute(sdk, ctx) {
+      log('info', `正在调用 Claude Code 执行项目扫描（${projectType}项目）...`);
+
+      const prompt = buildScanPrompt(projectType, requirement);
+      const queryOpts = buildQueryOptions(ctx.config, opts);
+      queryOpts.systemPrompt = buildSystemPrompt(true);
+      queryOpts.hooks = ctx.hooks;
+      queryOpts.abortController = ctx.abortController;
+
+      const collected = await ctx.runQuery(sdk, prompt, queryOpts);
+      const result = extractResult(collected);
+
+      return { cost: result?.total_cost_usd ?? null };
+    },
+  });
+}
+
+async function scan(requirement, opts = {}) {
+  assets.ensureDirs();
+
+  const maxAttempts = RETRY.SCAN_ATTEMPTS;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    log('info', `初始化尝试 ${attempt} / ${maxAttempts} ...`);
+
+    const result = await _runScanSession(requirement, opts);
+
+    if (assets.exists('profile')) {
+      const profileCheck = validateProfile();
+      if (!profileCheck.valid) {
+        log('warn', `profile 质量问题: ${profileCheck.issues.join('; ')}`);
+      }
+      log('ok', '项目扫描完成');
+      return { success: true, cost: result.cost };
+    }
+
+    if (attempt < maxAttempts) {
+      log('warn', '初始化未完成，将重试...');
+    }
+  }
+
+  log('error', `初始化失败：已重试 ${maxAttempts} 次，关键文件仍未生成`);
+  return { success: false, cost: null };
+}
+
+module.exports = {
+  scan,
+  validateProfile,
+  _runScanSession,
+};

package/src/core/simplify.js

@@ -0,0 +1,59 @@
+"use strict";
+
+const { runSession } = require("./base");
+const { buildQueryOptions } = require("./query");
+const { log } = require("../common/config");
+const { assets } = require("../common/assets");
+const { execSync } = require("child_process");
+
+async function _runSimplifySession(n = 3, focus = null, opts = {}) {
+  const projectRoot = assets.projectRoot;
+  let diff = "";
+  try {
+    diff = execSync(`git diff HEAD~${n}..HEAD`, {
+      cwd: projectRoot,
+      encoding: "utf8",
+      maxBuffer: 50 * 1024 * 1024,
+    });
+  } catch (err) {
+    log("warn", `无法获取最近 ${n} 个 commit 的 diff: ${err.message}`);
+  }
+
+  const focusLine = focus ? `\n审查聚焦方向：${focus}` : "";
+  const tasksPath = assets.path('tasks');
+  const taskLine = tasksPath ? `\n任务文件: ${tasksPath}（可读取了解当前项目任务上下文）` : '';
+  const prompt = `/simplify\n\n审查范围：最近 ${n} 个 commit${taskLine}${focusLine}\n不要向用户提问，默认使用推荐方式直接执行。\n\n${diff.slice(0, 50000)}`;
+  const dateStr = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+
+  return runSession("simplify", {
+    opts,
+    sessionNum: 0,
+    logFileName: `simplify_${dateStr}.log`,
+    label: "simplify",
+
+    async execute(sdk, ctx) {
+      log("info", `正在审查最近 ${n} 个 commit 的代码变更...`);
+
+      const queryOpts = buildQueryOptions(ctx.config, opts);
+      queryOpts.hooks = ctx.hooks;
+      queryOpts.abortController = ctx.abortController;
+      queryOpts.disallowedTools = ['askUserQuestion'];
+
+      await ctx.runQuery(sdk, prompt, queryOpts);
+      log("ok", "代码审查完成");
+
+      return {};
+    },
+  });
+}
+
+async function simplify(focus = null, opts = {}) {
+  assets.ensureDirs();
+  const n = opts.n || 3;
+  return _runSimplifySession(n, focus, opts);
+}
+
+module.exports = {
+  simplify,
+  _runSimplifySession,
+};

package/src/core/validator.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const { log } = require('../common/config');
+const { getGitHead } = require('../common/utils');
+const { assets } = require('../common/assets');
+const { TASK_STATUSES } = require('../common/constants');
+const { loadTasks, getFeatures } = require('../common/tasks');
+
+function inferFromTasks(taskId) {
+  if (!taskId) return null;
+  const data = loadTasks();
+  if (!data) return null;
+  const task = getFeatures(data).find(f => f.id === taskId);
+  return task ? task.status : null;
+}
+
+function validateSessionResult() {
+  if (!assets.exists('sessionResult')) {
+    log('error', 'Agent 未生成 session_result.json');
+    return { valid: false, fatal: true, recoverable: false, reason: 'session_result.json 不存在' };
+  }
+
+  const data = assets.readJson('sessionResult', null);
+  if (data === null) {
+    log('warn', 'session_result.json 解析失败');
+    return { valid: false, fatal: false, recoverable: true, reason: 'JSON 解析失败' };
+  }
+
+  const sessionData = data.current && typeof data.current === 'object' ? data.current : data;
+
+  const required = ['session_result', 'status_after'];
+  const missing = required.filter(k => !(k in sessionData));
+  if (missing.length > 0) {
+    log('warn', `session_result.json 缺少字段: ${missing.join(', ')}`);
+    return { valid: false, fatal: false, recoverable: true, reason: `缺少字段: ${missing.join(', ')}` };
+  }
+
+  if (!['success', 'failed'].includes(sessionData.session_result)) {
+    log('warn', `session_result 必须是 success 或 failed，实际是: ${sessionData.session_result}`);
+    return { valid: false, fatal: false, recoverable: true, reason: `无效 session_result: ${sessionData.session_result}`, data: sessionData };
+  }
+
+  if (!TASK_STATUSES.includes(sessionData.status_after)) {
+    log('warn', `status_after 不合法: ${sessionData.status_after}`);
+    return { valid: false, fatal: false, recoverable: true, reason: `无效 status_after: ${sessionData.status_after}`, data: sessionData };
+  }
+
+  if (sessionData.session_result === 'success') {
+    log('ok', 'session_result.json 合法 (success)');
+  } else {
+    log('warn', 'session_result.json 合法，但 Agent 报告失败 (failed)');
+  }
+
+  return { valid: true, fatal: false, recoverable: false, data: sessionData };
+}
+
+function checkGitProgress(headBefore) {
+  if (!headBefore) {
+    log('info', '未提供 head_before，跳过 git 检查');
+    return { hasCommit: false, warning: false };
+  }
+
+  const projectRoot = assets.projectRoot;
+  const headAfter = getGitHead(projectRoot);
+
+  if (headBefore === headAfter) {
+    log('warn', '本次会话没有新的 git 提交');
+    return { hasCommit: false, warning: true };
+  }
+
+  try {
+    const msg = execSync('git log --oneline -1', { cwd: projectRoot, encoding: 'utf8' }).trim();
+    log('ok', `检测到新提交: ${msg}`);
+  } catch { /* ignore */ }
+
+  return { hasCommit: true, warning: false };
+}
+
+function checkTestCoverage(taskId, statusAfter) {
+  if (statusAfter !== 'done' || !taskId) return;
+  if (!assets.exists('tests')) return;
+
+  const tests = assets.readJson('tests', null);
+  if (!tests) return;
+  const testCases = tests.test_cases || [];
+  const taskTests = testCases.filter(t => t.feature_id === taskId);
+  if (taskTests.length > 0) {
+    const failed = taskTests.filter(t => t.last_result === 'fail');
+    if (failed.length > 0) {
+      log('warn', `tests.json 中有失败的验证记录: ${failed.map(t => t.id).join(', ')}`);
+    } else {
+      log('ok', `${taskTests.length} 条验证记录覆盖任务 ${taskId}`);
+    }
+  }
+}
+
+function validate(headBefore, taskId) {
+  log('info', '========== 开始校验 ==========');
+
+  const srResult = validateSessionResult();
+  const gitResult = checkGitProgress(headBefore);
+
+  let fatal = false;
+  let hasWarnings = false;
+
+  if (srResult.valid) {
+    hasWarnings = gitResult.warning;
+  } else {
+    if (gitResult.hasCommit) {
+      const taskStatus = inferFromTasks(taskId);
+      if (taskStatus === 'done' || taskStatus === 'testing') {
+        log('warn', `session_result.json 异常，但 tasks.json 显示 ${taskId} 已 ${taskStatus}，且有新提交，降级为警告`);
+      } else {
+        log('warn', 'session_result.json 异常，但有新提交，降级为警告（不回滚代码）');
+      }
+      hasWarnings = true;
+    } else {
+      log('error', '无新提交且 session_result.json 异常，视为致命');
+      fatal = true;
+    }
+  }
+
+  const statusAfter = srResult.data?.status_after || inferFromTasks(taskId) || null;
+  checkTestCoverage(taskId, statusAfter);
+
+  if (fatal) {
+    log('error', '========== 校验失败 (致命) ==========');
+  } else if (hasWarnings) {
+    log('warn', '========== 校验通过 (有警告) ==========');
+  } else {
+    log('ok', '========== 校验全部通过 ==========');
+  }
+
+  return { fatal, hasWarnings, sessionData: srResult.data };
+}
+
+module.exports = { validate, validateSessionResult, checkGitProgress };

package/{prompts/ADD_GUIDE.md → templates/addGuide.md}

@@ -1,98 +1,98 @@
-# 任务分解指南
-
-> 本文档是 `claude-coder add` 指令的参考文档。
-> ADD Agent 的唯一职责：分解需求为结构化任务，追加到 tasks.json。不实现任何代码。
-
----
-
-## tasks.json 格式
-
-```json
-{
-  "project": "项目名称",
-  "created_at": "2026-02-13",
-  "features": [
-    {
-      "id": "feat-001",
-      "category": "backend | frontend | fullstack | infra",
-      "priority": 1,
-      "description": "功能的简要描述（40字内）",
-      "steps": [
-        "具体步骤 1",
-        "具体步骤 2",
-        "端到端测试：验证方法"
-      ],
-      "status": "pending",
-      "depends_on": []
-    }
-  ]
-}
-```
-
-### 字段规范
-
-| 字段 | 规则 |
-|------|------|
-| `id` | 格式 `feat-NNN`，从已有最大值递增 |
-| `category` | `backend` / `frontend` / `fullstack` / `infra`，准确归类 |
-| `priority` | 数字越小越优先，从已有最大值递增 |
-| `description` | 简明扼要，40 字内，说明"做什么"而非"怎么做" |
-| `steps` | 具体可操作步骤，最后一步必须是可验证的测试命令，单任务不超过 5 步 |
-| `status` | 新增任务一律 `"pending"` |
-| `depends_on` | 引用前置任务的 `id`，形成 DAG（有向无环图），不得循环依赖 |
-
----
-
-## 任务分解规则
-
-### 粒度控制
-
-- 每个任务是独立可测试的功能单元，1-3 session 可完成，新增不超 500 行
-- 单任务 steps 不超过 5 步，超过则拆分为多个任务
-- 第一个任务从第一个有业务逻辑的功能开始，不重复脚手架内容
-- 新项目：infra 任务合并为尽量少的条目，不拆碎
-
-### 验证命令模板
-
-steps 的最后一步必须包含可执行的验证命令：
-
-```
-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
-页面:  Playwright MCP snapshot 验证关键元素存在
-```
-
-### 反面案例（禁止出现）
-
-- `"实现用户功能"` → 太模糊，应拆为具体接口
-- `"编写测试"` → 测试应内嵌在 steps 末尾，不是独立任务
-- steps 只有 `"实现xxx"` 没有验证步骤
-
----
-
-## requirements.md 处理原则
-
-`requirements.md` 是用户的需求输入，**绝对不能修改它**。但"不能改"不等于"必须盲从"。遇到以下情况时，在 `session_result.json` 的 `notes` 中记录问题，按最合理的方式继续分解：
-
-| 场景 | 处理方式 |
-|------|----------|
-| 需求自相矛盾 | 记录矛盾，按技术可行的方案分解，说明选择理由 |
-| 需求与已有代码冲突 | 记录冲突，说明重构成本，按现有架构分解，建议用户确认 |
-| 需求太模糊无法执行 | 自行做出合理决策，在 notes 中记录选择，供用户确认 |
-| 需求中途变更 | 记录变更影响，基于最新需求分解 |
-| 需求引用了不可访问的资源 | 记录问题，根据文字描述尽力分解 |
-| 需求指定了不存在的依赖 | 记录问题，使用最接近的可用版本 |
-
-**核心原则：不停工、不擅改、留记录。**
-
----
-
-## Playwright MCP 测试任务
-
-当任务涉及前端或全栈端到端测试，且项目已配置 Playwright MCP 时，测试步骤的详细规范（结构化标签、Smart Snapshot 策略、SSE 等待模式、步骤模板等）统一参见 `.claude-coder/test_rule.md` 第五节（等待策略）和第八节（步骤模板）。
-
-此处只列关键原则：
-- steps 首步加入 `【规则】阅读 .claude-coder/test_rule.md`
-- 使用 `【P0】【P1】【P2】` 标记优先级，预算不足时可按优先级裁剪
-- 长等待操作使用 `browser_wait_for` 而非轮询 snapshot
+# 任务分解指南
+
+> 本文档是 `claude-coder add` 指令的参考文档。
+> ADD Agent 的唯一职责：分解需求为结构化任务，追加到 tasks.json。不实现任何代码。
+
+---
+
+## tasks.json 格式
+
+```json
+{
+  "project": "项目名称",
+  "created_at": "2026-02-13",
+  "features": [
+    {
+      "id": "feat-001",
+      "category": "backend | frontend | fullstack | infra",
+      "priority": 1,
+      "description": "功能的简要描述（40字内）",
+      "steps": [
+        "具体步骤 1",
+        "具体步骤 2",
+        "端到端测试：验证方法"
+      ],
+      "status": "pending",
+      "depends_on": []
+    }
+  ]
+}
+```
+
+### 字段规范
+
+| 字段 | 规则 |
+|------|------|
+| `id` | 格式 `feat-NNN`，从已有最大值递增 |
+| `category` | `backend` / `frontend` / `fullstack` / `infra`，准确归类 |
+| `priority` | 数字越小越优先，从已有最大值递增 |
+| `description` | 简明扼要，40 字内，说明"做什么"而非"怎么做" |
+| `steps` | 具体可操作步骤，最后一步必须是可验证的测试命令，单任务不超过 5 步 |
+| `status` | 新增任务一律 `"pending"` |
+| `depends_on` | 引用前置任务的 `id`，形成 DAG（有向无环图），不得循环依赖 |
+
+---
+
+## 任务分解规则
+
+### 粒度控制
+
+- 每个任务是独立可测试的功能单元，1-3 session 可完成，新增不超 500 行
+- 单任务 steps 不超过 5 步，超过则拆分为多个任务
+- 第一个任务从第一个有业务逻辑的功能开始，不重复脚手架内容
+- 新项目：infra 任务合并为尽量少的条目，不拆碎
+
+### 验证命令模板
+
+steps 的最后一步必须包含可执行的验证命令：
+
+```
+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
+页面:  Playwright MCP snapshot 验证关键元素存在
+```
+
+### 反面案例（禁止出现）
+
+- `"实现用户功能"` → 太模糊，应拆为具体接口
+- `"编写测试"` → 测试应内嵌在 steps 末尾，不是独立任务
+- steps 只有 `"实现xxx"` 没有验证步骤
+
+---
+
+## requirements.md 处理原则
+
+`requirements.md` 是用户的需求输入，**绝对不能修改它**。但"不能改"不等于"必须盲从"。遇到以下情况时，在 `session_result.json` 的 `notes` 中记录问题，按最合理的方式继续分解：
+
+| 场景 | 处理方式 |
+|------|----------|
+| 需求自相矛盾 | 记录矛盾，按技术可行的方案分解，说明选择理由 |
+| 需求与已有代码冲突 | 记录冲突，说明重构成本，按现有架构分解，建议用户确认 |
+| 需求太模糊无法执行 | 自行做出合理决策，在 notes 中记录选择，供用户确认 |
+| 需求中途变更 | 记录变更影响，基于最新需求分解 |
+| 需求引用了不可访问的资源 | 记录问题，根据文字描述尽力分解 |
+| 需求指定了不存在的依赖 | 记录问题，使用最接近的可用版本 |
+
+**核心原则：不停工、不擅改、留记录。**
+
+---
+
+## Playwright MCP 测试任务
+
+当任务涉及前端或全栈端到端测试，且项目已配置 Playwright MCP 时，测试步骤的详细规范（结构化标签、Smart Snapshot 策略、SSE 等待模式、步骤模板等）统一参见 `.claude-coder/test_rule.md` 第五节（等待策略）和第八节（步骤模板）。
+
+此处只列关键原则：
+- steps 首步加入 `【规则】阅读 .claude-coder/test_rule.md`
+- 使用 `【P0】【P1】【P2】` 标记优先级，预算不足时可按优先级裁剪
+- 长等待操作使用 `browser_wait_for` 而非轮询 snapshot

package/templates/addUser.md

@@ -0,0 +1,26 @@
+你是资深需求分析师，擅长将模糊需求分解为可执行的原子任务。
+这是任务追加 session，不是编码 session。你只分解任务，不实现代码。
+
+{{profileContext}}
+{{taskContext}}
+{{recentExamples}}
+项目绝对路径: {{projectRoot}}
+
+【方案文件】
+{{planPath}}
+
+执行步骤（按顺序，不可跳过）：
+1. 读取方案文件（{{planPath}}），理解技术方案和任务规划
+2. 读取 .claude-coder/tasks.json 和 .claude-coder/project_profile.json，了解项目现状
+3. 分析方案中的任务列表：识别核心功能点，判断是单任务还是需要拆分为多任务
+4. 检查重复：对比已有任务，避免功能重叠
+5. 确定依赖：新任务的 depends_on 引用已有或新增任务的 id，形成 DAG
+6. 分解任务：按下方任务分解指南的规则，每个任务独立可测试
+7. 追加到 tasks.json，id 和 priority 从已有最大值递增，status: pending
+8. git add -A && git commit -m "chore: add new tasks"
+9. 写入 session_result.json（格式：{ "session_result": "success", "status_before": "N/A", "status_after": "N/A", "notes": "追加了 N 个任务：简述" }）
+
+{{addGuide}}
+
+{{testRuleHint}}
+不修改已有任务，不实现代码。