alanbox 0.1.2 → 0.1.4

package/1swarmer/src/commands/review-file.js

@@ -0,0 +1,997 @@
+/**
+ * 文件/目录双 provider review 命令。
+ * Codex 与 Claude 并行初审，再用共识链条目写入同一个 Markdown 报告。
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { execPrompt } = require('../runner/codex-runner');
+
+const DEFAULT_PROVIDERS = ['codex', 'claude'];
+const PEER_REPORT_EXCERPT_LIMIT = 8000;
+const DEFAULT_MAX_CONSENSUS_ROUNDS = 4;
+
+async function runReviewFile({ args, config, cwd, timeoutMs, account }) {
+  const target = resolveReviewTarget(args, cwd);
+  const providers = resolveReviewProviders(args);
+  const phase = resolveReviewPhase(args);
+  const reportRoot = resolveReportRoot(args, cwd);
+  const reportPath = resolveReviewReportPath(args, reportRoot, target);
+  const executionCwd = args.cwd || args.C || target.executionCwd;
+  const commonOptions = {
+    config,
+    cwd: executionCwd,
+    timeoutMs,
+    model: args.model || args.m,
+    profile: args.profile || args.p,
+    sandbox: args.sandbox || args.s,
+    account,
+  };
+
+  initializeReport(reportPath);
+  console.error(`[review-file] target: ${target.path}`);
+  console.error(`[review-file] report: ${reportPath}`);
+
+  const initialResults = phase === 'cross-check'
+    ? loadExistingConsensusItems(reportPath, resolveCrossCheckInitialProviders(args, providers))
+    : await Promise.all(providers.map((provider) => runProviderReview({
+        phase: 'initial',
+        provider,
+        target,
+        args,
+        commonOptions,
+        reportPath,
+      })));
+
+  const mergeResults = phase === 'cross-check'
+    ? initialResults
+    : loadProviderInitialResultsFromReports(initialResults);
+
+  const items = phase === 'cross-check'
+    ? mergeResults.items
+    : buildConsensusItems(mergeResults, target, providers);
+
+  appendReportSection(reportPath, buildConsensusItemsSection(items));
+
+  const rounds = phase === 'initial' || providers.length <= 1
+    ? []
+    : await runConsensusRounds({
+        items,
+        providers,
+        target,
+        args,
+        commonOptions,
+        reportPath,
+      });
+
+  if (rounds.length > 0) {
+    appendReportSection(reportPath, buildFinalConsensusSummary({ items }));
+  }
+
+  console.log(`[review-file] report: ${reportPath}`);
+
+  const failed = Array.isArray(initialResults)
+    ? initialResults.some((item) => isInitialExecutionFailure(item))
+    : initialResults.results?.some((item) => isInitialExecutionFailure(item));
+  const requiresFinalConsensus = phase !== 'initial' && providers.length > 1;
+  const incomplete = requiresFinalConsensus && items.some((item) => !isConsensusComplete(item));
+  if (incomplete || failed) {
+    process.exitCode = 1;
+  }
+}
+
+async function runProviderReview({
+  phase,
+  provider,
+  target,
+  args,
+  commonOptions,
+  reportPath,
+  other,
+}) {
+  const startedAt = new Date();
+  const extraContext = buildExtraContext(args);
+  const reviewKind = resolveReviewKind({ args, context: extraContext });
+  const prompt = phase === 'cross-check'
+    ? buildCrossCheckPrompt({ provider, target, other, extraContext })
+    : buildInitialReviewPrompt({ provider, target, extraContext, reviewKind });
+
+  console.error(`[review-file] start ${provider}/${phase}`);
+
+  let result;
+  let error = null;
+  try {
+    result = await execPrompt(prompt, {
+      ...commonOptions,
+      provider,
+      worker: `review-${provider}-${phase}`,
+      stream: false,
+      account: args[`${provider}-account`] || commonOptions.account,
+      permissionMode: resolveProviderPermissionMode(args, provider),
+      claudeArgs: resolveClaudeArgs(args, provider),
+    });
+  } catch (caught) {
+    error = caught;
+    result = {
+      code: 1,
+      signal: '',
+      stdout: '',
+      stderr: caught?.stack || caught?.message || String(caught),
+      cwd: commonOptions.cwd,
+      args: [],
+    };
+  }
+
+  const finishedAt = new Date();
+  const stdout = result.stdout || '';
+  const stderr = result.stderr || '';
+  const findings = parseFindingsFromOutput(`${stdout}\n${stderr}`, provider, target);
+  const invalidReason = findings.length === 0
+    ? detectInvalidInitialReview({ stdout, stderr, error, code: result.code })
+    : '';
+  const item = {
+    phase,
+    provider,
+    reviewKind,
+    code: result.code,
+    signal: result.signal,
+    reportPath,
+    otherReportPath: other?.reportPath || '',
+    error: error ? (error.message || String(error)) : '',
+    startedAt: startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString(),
+    stdout,
+    stderr,
+    findings,
+    invalidReason,
+    providerReportPath: writeProviderReviewReport({
+      reportPath,
+      provider,
+      phase,
+      result,
+      error,
+      findings,
+      target,
+      reviewKind,
+      invalidReason,
+    }),
+  };
+  console.error(`[review-file] finished ${provider}/${phase}`);
+  return item;
+}
+
+function buildInitialReviewPrompt({ provider, target, extraContext, reviewKind = resolveReviewKind({ context: extraContext }) }) {
+  const improvementMode = reviewKind === 'improvements';
+  const findingSchema = '{"findings":[{"title":"...","detail":"...","evidence":"...","severity":"high|medium|low"}]}';
+  return [
+    '你是代码审查 agent。请只做 review，不要修改文件。',
+    '',
+    `当前 provider: ${provider}`,
+    `审查目标: ${target.path}`,
+    `目标类型: ${target.type}`,
+    `审查模式: ${improvementMode ? 'improvements' : 'defects'}`,
+    '',
+    extraContext ? `额外背景:\n${extraContext}` : '',
+    '',
+    '要求:',
+    improvementMode
+      ? '1. 重点找高置信、可落地、值得改的改进项，包括构建体积、依赖清理、部署可复现性、类型安全、可维护性、用户体验、性能和可靠性。'
+      : '1. 重点找高置信的正确性问题、数据丢失、并发/状态错误、命令参数错误、路径/Windows 兼容问题和会让 CLI 无法工作的缺陷。',
+    improvementMode
+      ? '2. 可以把非阻塞但证据明确的改进项写入 findings；每条必须给出文件路径、行号或可定位证据、影响、建议修法和验证方式。'
+      : '2. 发现问题时按严重程度排序，给出文件路径、行号或可定位的代码片段，并解释触发条件和影响。',
+    '3. 不要把纯风格偏好当成问题；不确定、无法落地或没有项目内证据的点不要写入 findings。',
+    improvementMode
+      ? '4. 如果找到可落地改进项，即使不是阻塞 bug，也必须写入 CONSENSUS_JSON findings；如果确实没有，明确写“未发现高置信可落地改进项”，并列出实际检查范围。'
+      : '4. 如果未发现高置信问题，明确写“未发现需要阻塞的 review 问题”，并列出实际检查范围。',
+    `5. 必须在回答末尾输出一个 CONSENSUS_JSON 代码块，格式为 ${findingSchema}。没有可报告项时 findings 为空数组。`,
+    '6. 用中文输出。先列 Findings，再列检查范围、验证建议和结论。',
+  ].filter(Boolean).join('\n');
+}
+
+function buildCrossCheckPrompt({ provider, target, other, extraContext }) {
+  const otherReportText = other?.sectionText
+    ? trimText(other.sectionText, PEER_REPORT_EXCERPT_LIMIT)
+    : readTextWithLimit(other?.reportPath || '', PEER_REPORT_EXCERPT_LIMIT);
+  const otherProvider = other?.provider || '另一个 provider';
+  return [
+    '你是代码审查复核 agent。请只做 review，不要修改文件。',
+    '',
+    `当前 provider: ${provider}`,
+    `审查目标: ${target.path}`,
+    `目标类型: ${target.type}`,
+    `需要复核的对方 provider: ${otherProvider}`,
+    `同一个总报告文件: ${other?.reportPath || '<missing>'}`,
+    '',
+    extraContext ? `额外背景:\n${extraContext}` : '',
+    '',
+    '复核要求:',
+    '1. 检查下方待判断 finding 是否成立。',
+    '2. 如果认同，decision 必须是 "agree"；如果不认同或证据不足，decision 必须是 "disagree"。',
+    '3. 如果不认同，必须给出原因和下一步应检查的证据。',
+    '4. 必须在回答末尾输出一个 CONSENSUS_JSON 代码块，格式为 {"decision":"agree|disagree","reason":"...","detail":"..."}。',
+    '5. 用中文输出。不要简单复述对方报告；要给出你的判断。',
+    '',
+    '待判断 finding 如下：',
+    '```markdown',
+    otherReportText || '<empty report>',
+    '```',
+  ].join('\n');
+}
+
+async function runConsensusRounds({
+  items,
+  providers,
+  target,
+  args,
+  commonOptions,
+  reportPath,
+}) {
+  const parsedMaxRounds = Number(args['max-consensus-rounds'] ?? DEFAULT_MAX_CONSENSUS_ROUNDS);
+  const maxRounds = Number.isFinite(parsedMaxRounds) && parsedMaxRounds >= 0
+    ? Math.floor(parsedMaxRounds)
+    : DEFAULT_MAX_CONSENSUS_ROUNDS;
+  const rounds = [];
+
+  for (let round = 1; round <= maxRounds; round += 1) {
+    const pending = items.filter((item) => !isConsensusComplete(item));
+    if (pending.length === 0) break;
+
+    const tasks = pending.map((item) => {
+      const reviewer = chooseNextReviewer(item, providers);
+      return runConsensusReview({
+        item,
+        reviewer,
+        round,
+        target,
+        args,
+        commonOptions,
+        reportPath,
+      });
+    });
+
+    const results = await Promise.all(tasks);
+    for (const result of results) {
+      applyConsensusReview(result.item, result.review);
+    }
+
+    rounds.push({ round, results });
+    appendReportSection(reportPath, buildConsensusRoundSection(round, results));
+  }
+
+  const unresolved = items.filter((item) => !isConsensusComplete(item));
+  if (unresolved.length > 0) {
+    for (const item of unresolved) {
+      const forcedProvider = chooseNextReviewer(item, providers);
+      applyConsensusReview(item, {
+        provider: forcedProvider,
+        verdict: 'agree',
+        reason: `达到最大共识轮次 ${maxRounds}，按协议强制继续到最终 √；需要人工复查前面的 ❌ 原因。`,
+        code: 0,
+      });
+    }
+    const forcedResults = unresolved.map((item) => ({
+      item,
+      review: item.reviews[item.reviews.length - 1],
+      forced: true,
+    }));
+    rounds.push({ round: maxRounds + 1, results: forcedResults, forced: true });
+    appendReportSection(reportPath, buildConsensusRoundSection(maxRounds + 1, forcedResults));
+  }
+
+  return rounds;
+}
+
+async function runConsensusReview({
+  item,
+  reviewer,
+  round,
+  target,
+  args,
+  commonOptions,
+  reportPath,
+}) {
+  const prompt = buildConsensusPrompt({ item, reviewer, round, target, reportPath, extraContext: buildExtraContext(args) });
+  console.error(`[review-file] consensus round ${round} ${reviewer} item ${item.id}`);
+
+  let result;
+  let error = null;
+  try {
+    result = await execPrompt(prompt, {
+      ...commonOptions,
+      provider: reviewer,
+      worker: `review-${reviewer}-consensus-${round}`,
+      stream: false,
+      account: args[`${reviewer}-account`] || commonOptions.account,
+      permissionMode: resolveProviderPermissionMode(args, reviewer),
+      claudeArgs: resolveClaudeArgs(args, reviewer),
+    });
+  } catch (caught) {
+    error = caught;
+    result = {
+      code: 1,
+      stdout: '',
+      stderr: caught?.stack || caught?.message || String(caught),
+    };
+  }
+
+  const parsed = parseConsensusDecision(result.stdout || '');
+  const review = {
+    provider: reviewer,
+    verdict: parsed.decision === 'agree' && result.code === 0 && !error ? 'agree' : 'disagree',
+    reason: parsed.reason || parsed.detail || result.stderr || error?.message || '未给出有效同意结论',
+    detail: parsed.detail || '',
+    code: result.code,
+    stderr: result.stderr || '',
+  };
+
+  return { item, review };
+}
+
+function buildConsensusPrompt({ item, reviewer, round, target, reportPath, extraContext }) {
+  const hasDisagreement = item.reviews.some((review) => review.verdict === 'disagree');
+  const taskLine = hasDisagreement
+    ? '当前条目已有 ❌。请针对前面的不同意原因继续分析：如果你认为条目经过澄清后成立，输出 agree；如果仍不成立，输出 disagree 并给出下一轮应检查的证据。'
+    : '请检查这个来源于对方 provider 的合并报告条目是否成立；不要简单复述，要给出你的判断。';
+  return [
+    '你是代码审查共识复核 agent。请只做 review，不要修改文件。',
+    '',
+    `当前 provider: ${reviewer}`,
+    `共识轮次: ${round}`,
+    `审查目标: ${target.path}`,
+    `目标类型: ${target.type}`,
+    `合并报告文件: ${reportPath || '<memory>'}`,
+    '',
+    extraContext ? `额外背景:\n${extraContext}` : '',
+    '',
+    taskLine,
+    '',
+    '当前合并报告条目:',
+    `${formatConsensusTag(item)} ${item.title}`,
+    '',
+    `- id: ${item.id}`,
+    `- 来源 provider: ${item.origin}`,
+    `- 标题: ${item.title}`,
+    `- 严重度: ${item.severity}`,
+    `- 详情: ${item.detail}`,
+    `- 证据: ${item.evidence}`,
+    '',
+    '已有判断:',
+    ...item.reviews.map((review) => `- ${review.provider}: ${review.verdict === 'agree' ? '同意' : '不同意'}；${review.reason || review.detail || ''}`),
+    '',
+    '要求:',
+    '1. 判断这个 finding 当前是否应该被确认。',
+    '2. 如果认可该 finding 成立，输出 decision=agree。',
+    '3. 如果不认可、证据不足、描述需要改写，输出 decision=disagree，并说明下一轮应该检查什么。',
+    '4. 必须在回答末尾输出 CONSENSUS_JSON 代码块，格式 {"decision":"agree|disagree","reason":"...","detail":"..."}。',
+  ].join('\n');
+}
+
+function buildConsensusItems(initialResults, target, providers = DEFAULT_PROVIDERS) {
+  const items = [];
+  const reviewKind = initialResults.find((result) => result.reviewKind)?.reviewKind || 'defects';
+  for (const result of initialResults) {
+    const findings = result.findings.length > 0
+      ? result.findings
+      : fallbackFindingFromResult(result, target);
+    for (const finding of findings) {
+      const initialVerdict = finding.initialVerdict || 'agree';
+      const item = {
+        id: `F${String(items.length + 1).padStart(3, '0')}`,
+        origin: result.provider,
+        title: compactText(finding.title || `${result.provider} review finding`).slice(0, 160),
+        detail: compactText(finding.detail || finding.summary || '').slice(0, 4000),
+        evidence: compactText(finding.evidence || finding.file || target.path).slice(0, 1000),
+        severity: normalizeSeverity(finding.severity),
+        reviews: [{
+          provider: result.provider,
+          verdict: initialVerdict,
+          reason: finding.initialReason || (initialVerdict === 'agree' ? '初审提出并确认。' : `初审退出码 ${result.code}`),
+          code: result.code,
+        }],
+      };
+      items.push(item);
+    }
+  }
+
+  if (items.length === 0) {
+    const activeProviders = uniqueStrings(initialResults
+      .filter((result) => !isInitialExecutionFailure(result))
+      .map((result) => result.provider)
+      .filter(Boolean));
+    const reviewedProviders = activeProviders.length > 0 ? activeProviders : ['system'];
+    items.push({
+      id: 'F001',
+      origin: 'system',
+      title: reviewKind === 'improvements'
+        ? '未发现高置信可落地改进项'
+        : '未发现需要阻塞的 review 问题',
+      detail: reviewKind === 'improvements'
+        ? `${reviewedProviders.join(' 和 ')} 初审没有提出结构化高置信可落地改进项。`
+        : `${reviewedProviders.join(' 和 ')} 初审没有提出结构化高置信 finding。`,
+      evidence: target.path,
+      severity: 'low',
+      reviews: reviewedProviders.map((provider) => ({
+        provider,
+        verdict: 'agree',
+        reason: reviewKind === 'improvements' ? '未发现高置信可落地改进项。' : '无阻塞问题。',
+        code: 0,
+      })),
+    });
+  }
+
+  return items;
+}
+
+function fallbackFindingFromResult(result, target) {
+  return [];
+}
+
+function applyConsensusReview(item, review) {
+  item.reviews.push(review);
+}
+
+function chooseNextReviewer(item, providers) {
+  const last = item.reviews[item.reviews.length - 1]?.provider;
+  const candidate = providers.find((provider) => provider !== last);
+  return candidate || providers[0] || DEFAULT_PROVIDERS[0];
+}
+
+function isConsensusComplete(item) {
+  const last = item.reviews[item.reviews.length - 1];
+  if (item.origin === 'system') return last?.verdict === 'agree';
+  return last?.verdict === 'agree' && item.reviews.length >= 2;
+}
+
+function formatConsensusTag(item) {
+  const body = item.reviews
+    .map((review) => `${review.provider}${review.verdict === 'agree' ? '√' : '❌'}`)
+    .join('');
+  return `[${body}]`;
+}
+
+function buildConsensusItemsSection(items) {
+  return items.flatMap((item) => formatConsensusItemLines(item)).join('\n');
+}
+
+function buildConsensusRoundSection(round, results) {
+  return [
+    ...results.flatMap(({ item, review, forced }) => [
+      `${formatConsensusTag(item)} ${item.title}`,
+      '',
+      `- item: ${item.id}`,
+      `- round: ${round}`,
+      `- reviewer: ${review.provider}`,
+      `- verdict: ${review.verdict === 'agree' ? '√' : '❌'}${forced ? ' (forced-final)' : ''}`,
+      `- reason: ${review.reason || ''}`,
+      review.detail ? `- detail: ${review.detail}` : '',
+      '',
+    ].filter(Boolean)),
+  ].join('\n');
+}
+
+function buildFinalConsensusSummary({ items }) {
+  return items.flatMap((item) => formatConsensusItemLines(item)).join('\n');
+}
+
+function formatConsensusItemLines(item) {
+  return [
+    `${formatConsensusTag(item)} ${item.title}`,
+    '',
+    `- id: ${item.id}`,
+    `- severity: ${item.severity}`,
+    `- detail: ${item.detail}`,
+    `- evidence: ${item.evidence}`,
+    '',
+  ];
+}
+
+function initializeReport(reportPath) {
+  fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+  if (fs.existsSync(reportPath) && fs.statSync(reportPath).size > 0) {
+    return;
+  }
+
+  fs.writeFileSync(reportPath, '', 'utf8');
+}
+
+function writeProviderReviewReport({ reportPath, provider, phase, result, error, findings = [], target, reviewKind = 'defects', invalidReason = '' }) {
+  if (!reportPath || phase !== 'initial') return '';
+  const providerReportPath = resolveProviderReportPath(reportPath, provider, phase);
+  const failed = Boolean(error || Number(result?.code || 0) !== 0);
+  const items = findings.map((finding, index) => ({
+    id: `F${String(index + 1).padStart(3, '0')}`,
+    origin: provider,
+    title: compactText(finding.title || `${provider} review finding`).slice(0, 160),
+    detail: compactText(finding.detail || finding.summary || '').slice(0, 4000),
+    evidence: compactText(finding.evidence || finding.file || target?.path || '').slice(0, 1000),
+    severity: normalizeSeverity(finding.severity),
+    reviews: [{
+      provider,
+      verdict: 'agree',
+      reason: '初审提出并确认。',
+      code: result?.code || 0,
+    }],
+  }));
+  const body = items.length > 0
+    ? buildConsensusItemsSection(items)
+    : invalidReason
+      ? [
+          `[${provider}❌] ${provider} 初审无效`,
+          '',
+          '- id: F001',
+          '- severity: medium',
+          `- detail: ${invalidReason}`,
+          `- evidence: ${target?.path || ''}`,
+        ].join('\n')
+    : failed
+      ? [
+          `[${provider}❌] ${provider} 初审执行失败`,
+          '',
+          '- id: F001',
+          '- severity: medium',
+          `- detail: ${compactText(error?.message || result?.stderr || `provider exited with code ${result?.code || 1}`).slice(0, 1000)}`,
+          `- evidence: ${target?.path || ''}`,
+        ].join('\n')
+    : [
+        `[${provider}√] ${reviewKind === 'improvements' ? '未发现高置信可落地改进项' : '未发现结构化 finding'}`,
+        '',
+        '- id: F001',
+        '- severity: low',
+        `- detail: ${provider} 初审没有提出${reviewKind === 'improvements' ? '结构化高置信可落地改进项' : '结构化 finding'}。`,
+        `- evidence: ${target?.path || ''}`,
+      ].join('\n');
+  fs.mkdirSync(path.dirname(providerReportPath), { recursive: true });
+  const diagnostics = [
+    result?.stderr ? `\n\n<!-- ${provider} stderr\n${result.stderr}\n-->` : '',
+    error ? `\n\n<!-- ${provider} error\n${error.stack || error.message || String(error)}\n-->` : '',
+  ].join('');
+  fs.writeFileSync(providerReportPath, `${body}${diagnostics}\n`, 'utf8');
+  return providerReportPath;
+}
+
+function loadProviderInitialResultsFromReports(initialResults) {
+  return initialResults.map((result) => {
+    const items = readProviderInitialItems(result.providerReportPath, result.provider);
+    if (!items.length) {
+      return {
+        ...result,
+        findings: [],
+      };
+    }
+
+    return {
+      ...result,
+      findings: items.map((item) => ({
+        title: item.title,
+        detail: item.detail,
+        evidence: item.evidence,
+        severity: item.severity,
+        initialVerdict: item.reviews[0]?.verdict || 'agree',
+        initialReason: item.reviews[0]?.reason || '从 provider 初审 md 合并。',
+      })),
+    };
+  });
+}
+
+function readProviderInitialItems(providerReportPath, provider) {
+  if (!providerReportPath || !fs.existsSync(providerReportPath)) return [];
+  const markdown = fs.readFileSync(providerReportPath, 'utf8');
+  return parseConsensusItemsFromReport(markdown)
+    .filter((item) => item.reviews[0]?.provider === provider)
+    .filter((item) => item.reviews[0]?.verdict === 'agree')
+    .filter((item) => !isNoFindingMarker(item));
+}
+
+function detectInvalidInitialReview({ stdout = '', stderr = '', error = null, code = 0 } = {}) {
+  if (error || Number(code || 0) !== 0) return '';
+  const text = `${stdout}\n${stderr}`;
+  const patterns = [
+    {
+      pattern: /CreateProcessWithLogonW failed:\s*1326/i,
+      reason: 'provider CLI 无法启动本地只读命令，Windows sandbox 返回 CreateProcessWithLogonW failed: 1326，初审没有有效读取目标文件。',
+    },
+    {
+      pattern: /未能有效读取目标目录文件/u,
+      reason: 'provider 明确说明未能有效读取目标目录文件，空 findings 不能视为项目无改进项。',
+    },
+    {
+      pattern: /所有本地只读命令.*被环境错误阻断/u,
+      reason: 'provider 明确说明本地只读命令被环境错误阻断，初审结果无效。',
+    },
+    {
+      pattern: /MCP 资源没有暴露仓库内容/u,
+      reason: 'provider 无法通过本地命令或 MCP 资源读取仓库内容，初审结果无效。',
+    },
+  ];
+  const match = patterns.find((item) => item.pattern.test(text));
+  return match ? match.reason : '';
+}
+
+function isNoFindingMarker(item) {
+  const title = compactText(item?.title || '');
+  return title === '未发现结构化 finding'
+    || title === '未发现高置信可落地改进项'
+    || title === '未发现需要阻塞的 review 问题';
+}
+
+function resolveProviderReportPath(reportPath, provider, phase) {
+  const parsed = path.parse(reportPath);
+  return path.join(parsed.dir, `${parsed.name}.${provider}.${phase}.md`);
+}
+
+function appendReportSection(reportPath, text) {
+  fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+  const body = String(text || '').replace(/\s+$/u, '');
+  if (!body) return;
+  fs.appendFileSync(reportPath, `${body}\n\n`, 'utf8');
+}
+
+function resolveReviewTarget(args, cwd) {
+  const value = args.target || args.file || args.f || args._[0];
+  if (!value) {
+    throw new Error('missing review target. Example: swarmer review-file C:\\path\\to\\file.ts');
+  }
+
+  const targetPath = path.resolve(cwd || process.cwd(), value);
+  const stat = fs.statSync(targetPath);
+  const type = stat.isDirectory() ? 'directory' : 'file';
+  return {
+    path: targetPath,
+    type,
+    executionCwd: type === 'directory' ? targetPath : path.dirname(targetPath),
+  };
+}
+
+function resolveReviewProviders(args) {
+  if (args.providers) {
+    const providers = String(args.providers)
+      .split(',')
+      .map((item) => item.trim().toLowerCase())
+      .filter(Boolean);
+    validateProviders(providers);
+    return providers;
+  }
+
+  if (args.codex && !args.claude && !args.both) return ['codex'];
+  if (args.claude && !args.codex && !args.both) return ['claude'];
+  return DEFAULT_PROVIDERS.slice();
+}
+
+function resolveReviewPhase(args) {
+  const phase = String(args.phase || 'all').trim().toLowerCase();
+  if (!['all', 'initial', 'cross-check'].includes(phase)) {
+    throw new Error('invalid --phase. Supported: all, initial, cross-check');
+  }
+  return phase;
+}
+
+function resolveCrossCheckInitialProviders(args, providers) {
+  if (args['peer-providers']) {
+    const peers = String(args['peer-providers'])
+      .split(',')
+      .map((item) => item.trim().toLowerCase())
+      .filter(Boolean);
+    validateProviders(peers);
+    return uniqueStrings([...providers, ...peers]);
+  }
+  return uniqueStrings([...providers, ...DEFAULT_PROVIDERS]);
+}
+
+function loadExistingConsensusItems(reportPath, providers) {
+  const fullReport = fs.existsSync(reportPath) ? fs.readFileSync(reportPath, 'utf8') : '';
+  const items = parseConsensusItemsFromReport(fullReport);
+  return {
+    items,
+    results: providers.map((provider) => {
+      const hasProvider = items.some((item) => item.reviews.some((review) => review.provider === provider));
+      return {
+        phase: 'initial',
+        provider,
+        code: hasProvider ? 0 : 1,
+        error: hasProvider ? '' : 'missing provider consensus item',
+      };
+    }),
+  };
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function isInitialExecutionFailure(result) {
+  return Boolean(result?.error || (Number(result?.code || 0) !== 0 && (!result?.findings || result.findings.length === 0)));
+}
+
+function parseFindingsFromOutput(text, provider, target) {
+  const parsed = extractConsensusJson(text);
+  if (parsed && Array.isArray(parsed.findings)) {
+    return parsed.findings
+      .filter((item) => item && typeof item === 'object')
+      .map((item) => ({
+        title: item.title || item.summary || `${provider} review finding`,
+        detail: item.detail || item.description || item.reason || '',
+        evidence: item.evidence || item.file || target.path,
+        severity: item.severity || 'medium',
+      }));
+  }
+  return [];
+}
+
+function resolveReviewKind({ args = {}, context = '' } = {}) {
+  const explicit = String(args['review-kind'] || args.kind || args.mode || '').trim().toLowerCase();
+  if (['improvement', 'improvements', 'improve', 'optimize', 'optimization', '优化', '改进'].includes(explicit)) {
+    return 'improvements';
+  }
+  if (['defect', 'defects', 'bug', 'bugs', 'correctness', 'blocker', 'blocking'].includes(explicit)) {
+    return 'defects';
+  }
+
+  const text = String(context || args.context || '').toLowerCase();
+  if (/(改进|优化|可维护|性能|体验|体积|依赖清理|部署|improvement|improve|optimi[sz]e|performance|maintainability|ux|bundle)/u.test(text)) {
+    return 'improvements';
+  }
+  return 'defects';
+}
+
+function parseConsensusDecision(text) {
+  const parsed = extractConsensusJson(text);
+  if (!parsed || typeof parsed !== 'object') {
+    return { decision: '', reason: '', detail: '' };
+  }
+  return {
+    decision: String(parsed.decision || '').toLowerCase(),
+    reason: compactText(parsed.reason || ''),
+    detail: compactText(parsed.detail || parsed.summary || ''),
+  };
+}
+
+function extractConsensusJson(text) {
+  const source = String(text || '');
+  const patterns = [
+    /```CONSENSUS_JSON\s*([\s\S]*?)```/i,
+    /```json\s*([\s\S]*?"(?:findings|decision)"[\s\S]*?)```/i,
+  ];
+  for (const pattern of patterns) {
+    const match = source.match(pattern);
+    if (!match) continue;
+    try {
+      return JSON.parse(match[1].trim());
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function parseConsensusItemsFromReport(markdown) {
+  const items = [];
+  const pattern = /^\[((?:codex|claude|system)[√✗❌](?:(?:codex|claude|system)[√✗❌])*)\]\s+(.+)$/gm;
+  let match;
+  while ((match = pattern.exec(String(markdown || ''))) !== null) {
+    const tagBody = match[1];
+    const title = match[2].trim();
+    const tail = markdown.slice(match.index, markdown.indexOf('\n[', match.index + 1) > -1
+      ? markdown.indexOf('\n[', match.index + 1)
+      : markdown.length);
+    const fallbackId = `F${String(items.length + 1).padStart(3, '0')}`;
+    const item = {
+      id: extractListValue(tail, 'id') || extractListValue(tail, 'item') || fallbackId,
+      origin: '',
+      title,
+      severity: extractListValue(tail, 'severity') || 'medium',
+      detail: extractListValue(tail, 'detail') || '',
+      evidence: extractListValue(tail, 'evidence') || '',
+      reviews: parseConsensusTagBody(tagBody),
+    };
+    item.origin = item.reviews[0]?.provider || '';
+    items.push(item);
+  }
+  return dedupeConsensusItems(items);
+}
+
+function parseConsensusTagBody(tagBody) {
+  const reviews = [];
+  const pattern = /(codex|claude|system)(√|✗|❌)/g;
+  let match;
+  while ((match = pattern.exec(tagBody)) !== null) {
+    reviews.push({
+      provider: match[1],
+      verdict: match[2] === '√' ? 'agree' : 'disagree',
+      reason: '',
+      code: 0,
+    });
+  }
+  return reviews;
+}
+
+function extractListValue(text, key) {
+  const pattern = new RegExp(`^- ${escapeRegExp(key)}:\\s*(.*)$`, 'm');
+  const match = String(text || '').match(pattern);
+  return match ? match[1].trim() : '';
+}
+
+function dedupeConsensusItems(items) {
+  const byId = new Map();
+  for (const item of items) {
+    const existing = byId.get(item.id);
+    if (!existing) {
+      byId.set(item.id, item);
+      continue;
+    }
+    byId.set(item.id, {
+      ...existing,
+      ...item,
+      severity: item.severity || existing.severity,
+      detail: item.detail || existing.detail,
+      evidence: item.evidence || existing.evidence,
+      reviews: item.reviews.length >= existing.reviews.length ? item.reviews : existing.reviews,
+    });
+  }
+  return [...byId.values()];
+}
+
+function normalizeSeverity(value) {
+  const text = String(value || '').toLowerCase();
+  if (['high', 'medium', 'low'].includes(text)) return text;
+  if (text.includes('高')) return 'high';
+  if (text.includes('低')) return 'low';
+  return 'medium';
+}
+
+function compactText(text) {
+  return String(text || '').replace(/\s+/g, ' ').trim();
+}
+
+function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function validateProviders(providers) {
+  if (providers.length === 0) {
+    throw new Error('providers is empty');
+  }
+  for (const provider of providers) {
+    if (!DEFAULT_PROVIDERS.includes(provider)) {
+      throw new Error(`unsupported review provider "${provider}". Supported: ${DEFAULT_PROVIDERS.join(', ')}`);
+    }
+  }
+}
+
+function resolveProviderPermissionMode(args, provider) {
+  if (provider !== 'claude') return args['permission-mode'] || args.permissionMode || '';
+  return args['claude-permission-mode']
+    || args['permission-mode']
+    || args.permissionMode
+    || 'bypassPermissions';
+}
+
+function resolveClaudeArgs(args, provider) {
+  if (provider !== 'claude') return [];
+  const values = [];
+  if (!args['no-claude-safe-mode']) {
+    values.push('--safe-mode');
+  }
+  if (!args['claude-effort']) {
+    values.push('--effort', 'low');
+  } else if (args['claude-effort'] !== 'default') {
+    values.push('--effort', args['claude-effort']);
+  }
+  if (args['claude-arg']) {
+    const extra = Array.isArray(args['claude-arg']) ? args['claude-arg'] : [args['claude-arg']];
+    values.push(...extra.filter(Boolean));
+  }
+  return values;
+}
+
+function resolveReportRoot(args, cwd) {
+  const explicit = args['report-root'] || args['output-root'];
+  if (explicit) {
+    return path.resolve(cwd || process.cwd(), explicit);
+  }
+
+  if (process.env.ALANBOX_REVIEW_ROOT) {
+    return path.resolve(process.env.ALANBOX_REVIEW_ROOT);
+  }
+
+  const desktopAllProject = path.join(os.homedir(), 'Desktop', 'all-project');
+  if (fs.existsSync(desktopAllProject)) {
+    return path.join(desktopAllProject, '.tmp', 'swarm');
+  }
+
+  return path.resolve(cwd || process.cwd(), '.tmp', 'swarm');
+}
+
+function resolveReviewReportPath(args, reportRoot, target) {
+  if (args['report-file']) {
+    return path.resolve(args['report-file']);
+  }
+  if (args['report-dir']) {
+    return path.join(path.resolve(args['report-dir']), defaultReportFileName(target));
+  }
+
+  return path.join(reportRoot, defaultReportFileName(target));
+}
+
+function defaultReportFileName(target) {
+  return `${formatLocalDateTime(new Date())}-${buildRunHash(target.path)}.md`;
+}
+
+function buildRunHash(targetPath) {
+  return crypto
+    .createHash('sha1')
+    .update([targetPath, Date.now(), process.pid, crypto.randomBytes(8).toString('hex')].join('\n'))
+    .digest('hex')
+    .slice(0, 8);
+}
+
+function formatLocalDateTime(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const hour = String(date.getHours()).padStart(2, '0');
+  const minute = String(date.getMinutes()).padStart(2, '0');
+  const second = String(date.getSeconds()).padStart(2, '0');
+  return `${year}-${month}-${day}-${hour}${minute}${second}`;
+}
+
+function buildExtraContext(args) {
+  const parts = [];
+  if (args.context) parts.push(String(args.context));
+  if (args['context-file']) {
+    parts.push(readTextWithLimit(path.resolve(args['context-file']), PEER_REPORT_EXCERPT_LIMIT));
+  }
+  return parts.join('\n\n').trim();
+}
+
+function readTextWithLimit(filePath, limit) {
+  if (!filePath) return '';
+  let text = '';
+  try {
+    text = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    return `<failed to read ${filePath}: ${error.message}>`;
+  }
+  return trimText(text, limit);
+}
+
+function trimText(text, limit) {
+  const source = String(text || '');
+  if (source.length <= limit) return source;
+  return `${source.slice(0, limit)}\n\n[truncated ${source.length - limit} chars]`;
+}
+
+function escapeMarkdownInline(text) {
+  return String(text || '').replace(/\s+/g, ' ').replace(/\|/g, '\\|');
+}
+
+module.exports = {
+  runReviewFile,
+  resolveReviewTarget,
+  resolveReviewProviders,
+  resolveReviewPhase,
+  resolveCrossCheckInitialProviders,
+  resolveReportRoot,
+  resolveReviewReportPath,
+  resolveProviderPermissionMode,
+  resolveClaudeArgs,
+  buildInitialReviewPrompt,
+  buildCrossCheckPrompt,
+  buildConsensusPrompt,
+  buildConsensusItems,
+  buildConsensusItemsSection,
+  buildConsensusRoundSection,
+  buildFinalConsensusSummary,
+  formatConsensusTag,
+  parseFindingsFromOutput,
+  detectInvalidInitialReview,
+  parseConsensusDecision,
+  extractConsensusJson,
+  parseConsensusItemsFromReport,
+  resolveReviewKind,
+  isConsensusComplete,
+  formatLocalDateTime,
+};