claude-coder 1.0.0

package/src/setup.js

@@ -0,0 +1,385 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { ensureLoopDir, paths, log, COLOR, getProjectRoot } = require('./config');
+
+function createInterface() {
+  return readline.createInterface({ input: process.stdin, output: process.stdout });
+}
+
+function ask(rl, question) {
+  return new Promise(resolve => rl.question(question, resolve));
+}
+
+async function askChoice(rl, prompt, min, max, defaultVal) {
+  while (true) {
+    const raw = await ask(rl, prompt);
+    const val = raw.trim() || String(defaultVal || '');
+    const num = parseInt(val, 10);
+    if (num >= min && num <= max) return num;
+    console.log(`请输入 ${min}-${max}`);
+  }
+}
+
+async function askApiKey(rl, platform, apiUrl, existingKey) {
+  if (existingKey) {
+    console.log('保留当前 API Key 请直接回车，或输入新 Key:');
+  } else {
+    console.log(`请输入 ${platform} 的 API Key:`);
+  }
+  if (apiUrl) {
+    console.log(`  ${COLOR.blue}获取入口: ${apiUrl}${COLOR.reset}`);
+    console.log('');
+  }
+  const key = await ask(rl, '  API Key: ');
+  if (!key.trim()) {
+    if (existingKey) return existingKey;
+    console.error('API Key 不能为空');
+    process.exit(1);
+  }
+  return key.trim();
+}
+
+function writeConfig(filePath, lines) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  // Backup existing
+  if (fs.existsSync(filePath)) {
+    const ts = new Date().toISOString().replace(/[:\-T]/g, '').slice(0, 14);
+    const backup = `${filePath}.bak.${ts}`;
+    fs.copyFileSync(filePath, backup);
+    log('info', `已备份旧配置到: ${backup}`);
+  }
+
+  fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf8');
+}
+
+function ensureGitignore() {
+  const gitignore = path.join(getProjectRoot(), '.gitignore');
+  const patterns = ['.claude-coder/.env', '.claude-coder/.runtime/'];
+  let content = '';
+  if (fs.existsSync(gitignore)) {
+    content = fs.readFileSync(gitignore, 'utf8');
+  }
+  const toAdd = patterns.filter(p => !content.includes(p));
+  if (toAdd.length > 0) {
+    const block = '\n# Claude Coder（含 API Key 和临时文件）\n' + toAdd.join('\n') + '\n';
+    fs.appendFileSync(gitignore, block, 'utf8');
+    log('info', '已将 .claude-coder/.env 添加到 .gitignore');
+  }
+}
+
+async function setup() {
+  const p = paths();
+  ensureLoopDir();
+  const rl = createInterface();
+
+  // Load existing config for defaults
+  let existing = {};
+  if (fs.existsSync(p.envFile)) {
+    const { parseEnvFile } = require('./config');
+    existing = parseEnvFile(p.envFile);
+  }
+
+  console.log('');
+  console.log('============================================');
+  console.log('  Claude Coder 前置配置');
+  console.log('============================================');
+  console.log('');
+  console.log('  第一步: 模型提供商配置');
+  console.log('  第二步: MCP 工具 + 调试输出（可选）');
+  console.log('');
+
+  // Detect existing config
+  if (fs.existsSync(p.envFile)) {
+    log('warn', `检测到已有配置文件: ${p.envFile}`);
+    console.log(`  当前模型提供商: ${existing.MODEL_PROVIDER || '未知'}`);
+    console.log(`  当前 BASE_URL: ${existing.ANTHROPIC_BASE_URL || '默认'}`);
+    console.log(`  Playwright MCP: ${existing.MCP_PLAYWRIGHT || '未配置'}`);
+    console.log('');
+    const reply = await ask(rl, '是否重新配置？(y/n) ');
+    if (!/^[Yy]/.test(reply.trim())) {
+      log('info', '保留现有配置，退出');
+      rl.close();
+      return;
+    }
+    console.log('');
+  }
+
+  // Provider selection
+  console.log('请选择模型提供商:');
+  console.log('');
+  console.log('  1) Claude 官方');
+  console.log(`  2) GLM Coding Plan (智谱/Z.AI)      ${COLOR.blue}https://open.bigmodel.cn${COLOR.reset}`);
+  console.log(`  3) 阿里云 Coding Plan (百炼)         ${COLOR.blue}https://bailian.console.aliyun.com${COLOR.reset}`);
+  console.log(`  4) DeepSeek                          ${COLOR.blue}https://platform.deepseek.com${COLOR.reset}`);
+  console.log('  5) 自定义 (Anthropic 兼容)');
+  console.log('');
+
+  const choice = await askChoice(rl, '选择 [1-5]: ', 1, 5);
+  console.log('');
+
+  let configLines = [];
+
+  switch (choice) {
+    case 1: {
+      configLines = [
+        '# Claude Coder 模型配置',
+        '# 提供商: Claude 官方',
+        '',
+        'MODEL_PROVIDER=claude',
+        'API_TIMEOUT_MS=3000000',
+        'MCP_TOOL_TIMEOUT=30000',
+      ];
+      log('ok', '已配置为 Claude 官方模型');
+      break;
+    }
+    case 2: {
+      // GLM platform
+      console.log('请选择 GLM 平台:');
+      console.log('');
+      console.log('  1) 智谱开放平台 (open.bigmodel.cn) - 国内直连');
+      console.log('  2) Z.AI (api.z.ai) - 海外节点');
+      console.log('');
+      const platChoice = await askChoice(rl, '选择 [1-2，默认 1]: ', 1, 2, 1);
+      const isBigmodel = platChoice === 1;
+      const glmProvider = isBigmodel ? 'glm-bigmodel' : 'glm-zai';
+      const glmBaseUrl = isBigmodel
+        ? 'https://open.bigmodel.cn/api/anthropic'
+        : 'https://api.z.ai/api/anthropic';
+      const glmApiUrl = isBigmodel
+        ? 'https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys'
+        : 'https://z.ai/manage-apikey/apikey-list';
+
+      // GLM model
+      console.log('');
+      console.log('请选择 GLM 模型版本:');
+      console.log('');
+      console.log('  1) GLM 4.7  - 旗舰模型，推理与代码能力强');
+      console.log('  2) GLM 5    - 最新模型（2026），能力更强');
+      console.log('');
+      const modelChoice = await askChoice(rl, '选择 [1-2，默认 1]: ', 1, 2, 1);
+      const glmModel = modelChoice === 1 ? 'glm-4.7' : 'glm-5';
+
+      const existingKey = existing.MODEL_PROVIDER === glmProvider ? existing.ANTHROPIC_API_KEY : '';
+      const apiKey = await askApiKey(rl, glmProvider, glmApiUrl, existingKey);
+
+      configLines = [
+        '# Claude Coder 模型配置',
+        `# 提供商: GLM (${glmProvider})`,
+        `# 模型: ${glmModel}`,
+        '',
+        `MODEL_PROVIDER=${glmProvider}`,
+        `ANTHROPIC_MODEL=${glmModel}`,
+        `ANTHROPIC_BASE_URL=${glmBaseUrl}`,
+        `ANTHROPIC_API_KEY=${apiKey}`,
+        'API_TIMEOUT_MS=3000000',
+        'MCP_TOOL_TIMEOUT=30000',
+      ];
+      log('ok', `已配置为 GLM 模型 (${glmProvider}, ${glmModel})`);
+      log('info', `BASE_URL: ${glmBaseUrl}`);
+      break;
+    }
+    case 3: {
+      // Aliyun
+      console.log('请选择阿里云百炼区域:');
+      console.log('');
+      console.log('  1) 国内版 (coding.dashscope.aliyuncs.com)');
+      console.log('  2) 国际版 (coding-intl.dashscope.aliyuncs.com)');
+      console.log('');
+      const regionChoice = await askChoice(rl, '选择 [1-2，默认 1]: ', 1, 2, 1);
+      const aliyunBaseUrl = regionChoice === 1
+        ? 'https://coding.dashscope.aliyuncs.com/apps/anthropic'
+        : 'https://coding-intl.dashscope.aliyuncs.com/apps/anthropic';
+
+      const existingKey = existing.MODEL_PROVIDER === 'aliyun-coding' ? existing.ANTHROPIC_API_KEY : '';
+      const apiKey = await askApiKey(rl, '阿里云百炼', 'https://bailian.console.aliyun.com/?tab=model#/api-key', existingKey);
+
+      configLines = [
+        '# Claude Coder 模型配置',
+        '# 提供商: 阿里云 Coding Plan (百炼)',
+        '# Opus: glm-5 | Sonnet/Haiku: qwen3-coder-plus | Fallback: qwen3.5-plus',
+        '',
+        'MODEL_PROVIDER=aliyun-coding',
+        `ANTHROPIC_BASE_URL=${aliyunBaseUrl}`,
+        `ANTHROPIC_API_KEY=${apiKey}`,
+        '',
+        'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1',
+        '# Planner (规划/推理) → glm-5',
+        'ANTHROPIC_DEFAULT_OPUS_MODEL=glm-5',
+        '# Executor (写代码/编辑/工具调用) → qwen3-coder-plus',
+        'ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder-plus',
+        'ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder-plus',
+        'ANTHROPIC_SMALL_FAST_MODEL=qwen3-coder-plus',
+        '# Fallback (通用) → qwen3.5-plus',
+        'ANTHROPIC_MODEL=qwen3.5-plus',
+        'API_TIMEOUT_MS=3000000',
+        'MCP_TOOL_TIMEOUT=30000',
+      ];
+      log('ok', '已配置为阿里云 Coding Plan (百炼)');
+      log('info', `BASE_URL: ${aliyunBaseUrl}`);
+      log('info', '模型映射: Opus=glm-5 / Sonnet+Haiku=qwen3-coder-plus / Fallback=qwen3.5-plus');
+      break;
+    }
+    case 4: {
+      // DeepSeek
+      const existingKey = existing.MODEL_PROVIDER === 'deepseek' ? existing.ANTHROPIC_API_KEY : '';
+      const apiKey = await askApiKey(rl, 'DeepSeek', 'https://platform.deepseek.com/api_keys', existingKey);
+
+      console.log('');
+      console.log('请选择 DeepSeek 模型:');
+      console.log('');
+      console.log('  1) deepseek-chat     - 通用对话 (V3)，速度快成本低 [推荐日常使用]');
+      console.log('  2) deepseek-reasoner - 纯推理模式 (R1)，全链路使用 R1，成本最高 [适合攻坚]');
+      console.log('  3) deepseek-hybrid   - 混合模式 (R1 + V3)，规划用 R1，执行用 V3 [性价比之选]');
+      console.log('');
+      const dsChoice = await askChoice(rl, '选择 [1-3，默认 1]: ', 1, 3, 1);
+      const dsModel = ['deepseek-chat', 'deepseek-reasoner', 'deepseek-hybrid'][dsChoice - 1];
+
+      configLines = [
+        '# Claude Coder 模型配置',
+        `# 提供商: DeepSeek`,
+        `# 模型: ${dsModel} | API_TIMEOUT_MS=600000 防止长输出超时（10分钟）`,
+        '',
+        'MODEL_PROVIDER=deepseek',
+        'ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic',
+        `ANTHROPIC_API_KEY=${apiKey}`,
+        `ANTHROPIC_AUTH_TOKEN=${apiKey}`,
+        '',
+        'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1',
+      ];
+
+      if (dsModel === 'deepseek-chat') {
+        configLines.push(
+          '# [DeepSeek Chat 降本策略]',
+          'ANTHROPIC_MODEL=deepseek-chat',
+          'ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat',
+          'ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-chat',
+          'ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-chat',
+          'ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-chat',
+        );
+      } else if (dsModel === 'deepseek-reasoner') {
+        configLines.push(
+          '# [DeepSeek Pure Reasoner 模式]',
+          'ANTHROPIC_MODEL=deepseek-reasoner',
+          'ANTHROPIC_SMALL_FAST_MODEL=deepseek-reasoner',
+          'ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-reasoner',
+          'ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-reasoner',
+          'ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-reasoner',
+        );
+      } else {
+        configLines.push(
+          '# [DeepSeek Hybrid 混合模式]',
+          'ANTHROPIC_MODEL=deepseek-reasoner',
+          'ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-reasoner',
+          'ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat',
+          'ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-chat',
+          'ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-chat',
+        );
+      }
+
+      configLines.push('API_TIMEOUT_MS=600000', 'MCP_TOOL_TIMEOUT=30000');
+      log('ok', `已配置为 DeepSeek (${dsModel}，Anthropic 兼容)`);
+      log('info', 'BASE_URL: https://api.deepseek.com/anthropic');
+      break;
+    }
+    case 5: {
+      // Custom
+      const defaultUrl = existing.MODEL_PROVIDER === 'custom' ? existing.ANTHROPIC_BASE_URL || '' : '';
+      console.log(`请输入 Anthropic 兼容的 BASE_URL${defaultUrl ? `（回车保留: ${defaultUrl}）` : ''}:`);
+      let baseUrl = await ask(rl, '  URL: ');
+      baseUrl = baseUrl.trim() || defaultUrl;
+      console.log('');
+
+      const existingKey = existing.MODEL_PROVIDER === 'custom' ? existing.ANTHROPIC_API_KEY : '';
+      const apiKey = await askApiKey(rl, '自定义平台', '', existingKey);
+
+      configLines = [
+        '# Claude Coder 模型配置',
+        '# 提供商: 自定义',
+        '',
+        'MODEL_PROVIDER=custom',
+        `ANTHROPIC_BASE_URL=${baseUrl}`,
+        `ANTHROPIC_API_KEY=${apiKey}`,
+        'API_TIMEOUT_MS=3000000',
+        'MCP_TOOL_TIMEOUT=30000',
+      ];
+      log('ok', '已配置为自定义模型');
+      log('info', `BASE_URL: ${baseUrl}`);
+      break;
+    }
+  }
+
+  // === Step 2: MCP tools ===
+  console.log('');
+  console.log('============================================');
+  console.log('  MCP 工具配置（可选）');
+  console.log('============================================');
+  console.log('');
+
+  console.log('是否启用 Playwright MCP（浏览器自动化测试）？');
+  console.log('');
+  console.log('  Playwright MCP 由微软官方维护 (github.com/microsoft/playwright-mcp)');
+  console.log('  提供 browser_click、browser_snapshot 等 25+ 浏览器自动化工具');
+  console.log('  适用于有 Web 前端的项目，Agent 可用它做端到端测试');
+  console.log('');
+  console.log('  1) 是 - 启用 Playwright MCP（项目有 Web 前端）');
+  console.log('  2) 否 - 跳过（纯后端 / CLI 项目）');
+  console.log('');
+
+  const mcpChoice = await askChoice(rl, '选择 [1-2]: ', 1, 2);
+
+  configLines.push('', '# MCP 工具配置');
+  if (mcpChoice === 1) {
+    configLines.push('MCP_PLAYWRIGHT=true');
+    log('ok', 'Playwright MCP 已启用');
+    console.log('');
+    console.log('  请确保已安装 Playwright MCP：');
+    console.log(`  ${COLOR.blue}npx @anthropic-ai/claude-code mcp add playwright -- npx @anthropic-ai/playwright-mcp${COLOR.reset}`);
+    console.log(`  ${COLOR.blue}详见: https://github.com/microsoft/playwright-mcp${COLOR.reset}`);
+  } else {
+    configLines.push('MCP_PLAYWRIGHT=false');
+    log('info', '已跳过 Playwright MCP');
+  }
+
+  // Debug output
+  console.log('');
+  console.log('是否开启 Claude 调试输出（便于排查问题，输出较多）？');
+  console.log('');
+  console.log('  1) 否 - 静默（默认，推荐）');
+  console.log('  2) 是 - verbose（完整每轮输出）');
+  console.log('  3) 是 - mcp（MCP 调用，如 Playwright Click）');
+  console.log('');
+
+  const debugChoice = await askChoice(rl, '选择 [1-3，默认 1]: ', 1, 3, 1);
+  configLines.push('', '# Claude 调试（可随时修改）');
+  if (debugChoice === 2) {
+    configLines.push('CLAUDE_DEBUG=verbose');
+    log('info', '已启用 CLAUDE_DEBUG=verbose');
+  } else if (debugChoice === 3) {
+    configLines.push('CLAUDE_DEBUG=mcp');
+    log('info', '已启用 CLAUDE_DEBUG=mcp');
+  } else {
+    configLines.push('# CLAUDE_DEBUG=verbose  # 取消注释可开启');
+  }
+
+  // Write config
+  writeConfig(p.envFile, configLines);
+  ensureGitignore();
+
+  rl.close();
+
+  console.log('');
+  log('ok', '配置完成！');
+  console.log('');
+  console.log(`  配置文件: ${p.envFile}`);
+  console.log('  使用方式: claude-coder run "你的需求"');
+  console.log('  详细需求: 创建 requirements.md 后运行 claude-coder run');
+  console.log('  重新配置: claude-coder setup');
+  console.log('');
+}
+
+module.exports = { setup };

package/src/tasks.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const fs = require('fs');
+const { paths, log, COLOR } = require('./config');
+
+const VALID_STATUSES = ['pending', 'in_progress', 'testing', 'done', 'failed'];
+
+const TRANSITIONS = {
+  pending:     ['in_progress'],
+  in_progress: ['testing'],
+  testing:     ['done', 'failed'],
+  failed:      ['in_progress'],
+  done:        [],
+};
+
+function loadTasks() {
+  const p = paths();
+  if (!fs.existsSync(p.tasksFile)) return null;
+  return JSON.parse(fs.readFileSync(p.tasksFile, 'utf8'));
+}
+
+function saveTasks(data) {
+  const p = paths();
+  fs.writeFileSync(p.tasksFile, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+function getFeatures(data) {
+  return data?.features || [];
+}
+
+function findNextTask(data) {
+  const features = getFeatures(data);
+  const failed = features.filter(f => f.status === 'failed')
+    .sort((a, b) => (a.priority || 999) - (b.priority || 999));
+  if (failed.length > 0) return failed[0];
+
+  const pending = features.filter(f => f.status === 'pending')
+    .filter(f => {
+      const deps = f.depends_on || [];
+      return deps.every(depId => {
+        const dep = features.find(x => x.id === depId);
+        return dep && dep.status === 'done';
+      });
+    })
+    .sort((a, b) => (a.priority || 999) - (b.priority || 999));
+  return pending[0] || null;
+}
+
+function setStatus(data, taskId, newStatus) {
+  const features = getFeatures(data);
+  const task = features.find(f => f.id === taskId);
+  if (!task) throw new Error(`任务不存在: ${taskId}`);
+  if (!VALID_STATUSES.includes(newStatus)) throw new Error(`无效状态: ${newStatus}`);
+
+  const allowed = TRANSITIONS[task.status];
+  if (!allowed || !allowed.includes(newStatus)) {
+    throw new Error(`非法状态迁移: ${task.status} → ${newStatus}`);
+  }
+
+  task.status = newStatus;
+  saveTasks(data);
+  return task;
+}
+
+function addTask(data, task) {
+  if (!data) {
+    data = { project: '', created_at: new Date().toISOString().slice(0, 10), features: [] };
+  }
+  data.features.push(task);
+  saveTasks(data);
+  return data;
+}
+
+function getStats(data) {
+  const features = getFeatures(data);
+  return {
+    total:       features.length,
+    done:        features.filter(f => f.status === 'done').length,
+    failed:      features.filter(f => f.status === 'failed').length,
+    in_progress: features.filter(f => f.status === 'in_progress').length,
+    testing:     features.filter(f => f.status === 'testing').length,
+    pending:     features.filter(f => f.status === 'pending').length,
+  };
+}
+
+function showStatus() {
+  const p = paths();
+  const data = loadTasks();
+  if (!data) {
+    log('warn', '未找到 .claude-coder/tasks.json，请先运行 claude-coder run');
+    return;
+  }
+
+  const stats = getStats(data);
+  const features = getFeatures(data);
+
+  console.log(`\n${COLOR.blue}═══════════════════════════════════════════════${COLOR.reset}`);
+  console.log(`  ${COLOR.blue}📋 任务状态${COLOR.reset}   项目: ${data.project || '(未命名)'}`);
+  console.log(`${COLOR.blue}═══════════════════════════════════════════════${COLOR.reset}`);
+
+  const bar = stats.total > 0
+    ? `[${'█'.repeat(Math.floor(stats.done / stats.total * 30))}${'░'.repeat(30 - Math.floor(stats.done / stats.total * 30))}]`
+    : '[░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]';
+  console.log(`  进度: ${bar} ${stats.done}/${stats.total}`);
+
+  console.log(`\n  ${COLOR.green}✔ done: ${stats.done}${COLOR.reset}  ${COLOR.yellow}⏳ pending: ${stats.pending}${COLOR.reset}  ${COLOR.red}✘ failed: ${stats.failed}${COLOR.reset}`);
+
+  if (stats.in_progress > 0 || stats.testing > 0) {
+    console.log(`  ▸ in_progress: ${stats.in_progress}  ▸ testing: ${stats.testing}`);
+  }
+
+  // Cost summary from progress.json (harness records SDK cost per session)
+  if (fs.existsSync(p.progressFile)) {
+    try {
+      const progress = JSON.parse(fs.readFileSync(p.progressFile, 'utf8'));
+      const sessions = (progress.sessions || []).filter(s => typeof s.cost === 'number');
+      if (sessions.length > 0) {
+        const totalCost = sessions.reduce((sum, s) => sum + s.cost, 0);
+        console.log(`\n  ${COLOR.blue}💰 累计成本${COLOR.reset}: $${totalCost.toFixed(4)} (${sessions.length} sessions)`);
+      }
+    } catch { /* ignore parse errors */ }
+  }
+
+  // Task list
+  console.log(`\n  ${'─'.repeat(45)}`);
+  for (const f of features) {
+    const icon = { done: '✔', pending: '○', in_progress: '▸', testing: '⟳', failed: '✘' }[f.status] || '?';
+    const color = { done: COLOR.green, failed: COLOR.red, in_progress: COLOR.blue, testing: COLOR.yellow }[f.status] || '';
+    console.log(`  ${color}${icon}${COLOR.reset} [${f.id}] ${f.description} (${f.status})`);
+  }
+
+  console.log(`${COLOR.blue}═══════════════════════════════════════════════${COLOR.reset}\n`);
+}
+
+module.exports = {
+  VALID_STATUSES,
+  TRANSITIONS,
+  loadTasks,
+  saveTasks,
+  getFeatures,
+  findNextTask,
+  setStatus,
+  addTask,
+  getStats,
+  showStatus,
+};

package/src/validator.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const fs = require('fs');
+const { execSync } = require('child_process');
+const { paths, log, getProjectRoot } = require('./config');
+
+function validateSessionResult() {
+  const p = paths();
+
+  if (!fs.existsSync(p.sessionResult)) {
+    log('error', 'Agent 未生成 session_result.json');
+    return { valid: false, fatal: true, reason: 'session_result.json 不存在' };
+  }
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
+  } catch {
+    log('error', 'session_result.json JSON 格式错误');
+    return { valid: false, fatal: true, reason: 'JSON 格式错误' };
+  }
+
+  const sr = data.current || data;
+
+  const required = ['session_result', 'status_after'];
+  const missing = required.filter(k => !(k in sr));
+  if (missing.length > 0) {
+    log('error', `session_result.json 缺少字段: ${missing.join(', ')}`);
+    return { valid: false, fatal: true, reason: `缺少字段: ${missing.join(', ')}` };
+  }
+
+  if (!['success', 'failed'].includes(sr.session_result)) {
+    log('error', `session_result 必须是 success 或 failed，实际是: ${sr.session_result}`);
+    return { valid: false, fatal: true, reason: `无效 session_result: ${sr.session_result}` };
+  }
+
+  const validStatuses = ['pending', 'in_progress', 'testing', 'done', 'failed'];
+  if (!validStatuses.includes(sr.status_after)) {
+    log('error', `status_after 不合法: ${sr.status_after}`);
+    return { valid: false, fatal: true, reason: `无效 status_after: ${sr.status_after}` };
+  }
+
+  if (!sr.task_id) {
+    log('warn', 'session_result.json 缺少 task_id (建议包含)');
+  }
+
+  if (sr.session_result === 'success') {
+    log('ok', 'session_result.json 合法 (success)');
+  } else {
+    log('warn', 'session_result.json 合法，但 Agent 报告失败 (failed)');
+  }
+
+  return { valid: true, fatal: false, data: sr };
+}
+
+function checkGitProgress(headBefore) {
+  if (!headBefore) {
+    log('info', '未提供 head_before，跳过 git 检查');
+    return { hasCommit: false, warning: false };
+  }
+
+  const projectRoot = getProjectRoot();
+  let headAfter;
+  try {
+    headAfter = execSync('git rev-parse HEAD', { cwd: projectRoot, encoding: 'utf8' }).trim();
+  } catch {
+    headAfter = 'none';
+  }
+
+  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() {
+  const p = paths();
+
+  if (!fs.existsSync(p.testsFile) || !fs.existsSync(p.sessionResult)) return;
+
+  try {
+    const sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
+    const current = sr.current || sr;
+    const tests = JSON.parse(fs.readFileSync(p.testsFile, 'utf8'));
+
+    const taskId = current.task_id || '';
+    const testCases = tests.test_cases || [];
+
+    if (current.status_after === 'done' && current.tests_passed) {
+      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}`);
+        }
+      }
+    }
+  } catch { /* ignore */ }
+}
+
+async function validate(headBefore) {
+  log('info', '========== 开始校验 ==========');
+
+  const srResult = validateSessionResult();
+  const gitResult = checkGitProgress(headBefore);
+  checkTestCoverage();
+
+  const fatal = srResult.fatal;
+  const hasWarnings = gitResult.warning;
+
+  if (fatal) {
+    log('error', '========== 校验失败 (致命) ==========');
+  } else if (hasWarnings) {
+    log('warn', '========== 校验通过 (有警告) ==========');
+  } else {
+    log('ok', '========== 校验全部通过 ==========');
+  }
+
+  return { fatal, hasWarnings, sessionData: srResult.data };
+}
+
+module.exports = { validate, validateSessionResult, checkGitProgress };