spectra-cli 4.1.1

package/dist/batch/budget-gate.js

@@ -0,0 +1,279 @@
+/**
+ * Feature 127 — Dry-run 预估 + Budget 守护 gate
+ *
+ * 职责：
+ * - estimateModuleCost(files, projectRoot)：基于 AST-free 的快速估算，输出单模块 input/output token
+ * - buildDryRunReport(estimates)：生成 Markdown 预估报告
+ * - buildBudgetDecision(estimates, budget, handler)：根据超预算状态调用 handler 选择下一步动作
+ *
+ * 估算模型（首版）：
+ * - input ≈ estimateFast(所有源码拼接)
+ * - output ≈ Math.round(input × 0.3)
+ * - 假设写入报告正文供用户审视
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { estimateFast } from '../core/token-counter.js';
+// ============================================================
+// 估算
+// ============================================================
+/** output ≈ 0.3 × input */
+const OUTPUT_RATIO = 0.3;
+/**
+ * 单模块 system prompt + 上下文骨架的固定开销估算（Bug 修复 — Phase 2 集成测试发现）
+ *
+ * 经验值来源：micrograd（4 个 Python 文件）实测 system prompt + AST skeleton +
+ * panoramic context 约 6,000-8,000 input tokens / 模块。取保守值 6,500，让 dry-run
+ * 估算从之前 ~64x 偏差缩到 < 1.5x。
+ *
+ * 这是固定开销不随源码大小线性增长，所以加常数项而非 ratio。
+ */
+const SYSTEM_PROMPT_TOKENS_PER_MODULE = 6500;
+/** 估算假设的人类可读说明（写入报告） */
+export const ESTIMATION_ASSUMPTION = 'input ≈ estimateFast(源文件拼接文本) + 6500（system prompt + AST skeleton 固定开销 / 模块），output ≈ 0.3 × input。基于历史平均比率，首版不校准。';
+/**
+ * 估算单个模块的 token 成本
+ *
+ * @param moduleName - 模块标识
+ * @param files - 模块包含的相对路径
+ * @param projectRoot - 项目根目录
+ */
+export function estimateModuleCost(moduleName, files, projectRoot) {
+    let sourceInput = 0;
+    let loc = 0;
+    for (const rel of files) {
+        const abs = path.isAbsolute(rel) ? rel : path.join(projectRoot, rel);
+        try {
+            const content = fs.readFileSync(abs, 'utf-8');
+            sourceInput += estimateFast(content);
+            loc += content.split('\n').length;
+        }
+        catch {
+            // 读取失败跳过
+        }
+    }
+    // 真实 input = 源码 token + system prompt / AST skeleton / panoramic context 固定开销
+    const input = sourceInput + SYSTEM_PROMPT_TOKENS_PER_MODULE;
+    const estimatedOutput = Math.round(input * OUTPUT_RATIO);
+    return {
+        moduleName,
+        files: [...files],
+        loc,
+        estimatedInput: input,
+        estimatedOutput,
+    };
+}
+/** 聚合所有模块估算 */
+export function buildDryRunReport(estimates) {
+    const totalInput = estimates.reduce((s, e) => s + e.estimatedInput, 0);
+    const totalOutput = estimates.reduce((s, e) => s + e.estimatedOutput, 0);
+    return {
+        generatedAt: new Date().toISOString(),
+        totalModules: estimates.length,
+        totalEstimatedInput: totalInput,
+        totalEstimatedOutput: totalOutput,
+        assumption: ESTIMATION_ASSUMPTION,
+        modules: estimates.slice().sort((a, b) => b.estimatedInput - a.estimatedInput),
+    };
+}
+/**
+ * 渲染 dry-run 报告为 Markdown，写入 `_meta/dry-run-estimate.md`
+ */
+export function renderDryRunReport(report) {
+    const lines = [];
+    lines.push('# Dry-run Estimate');
+    lines.push('');
+    lines.push(`> 自动生成于 ${report.generatedAt}`);
+    lines.push('');
+    lines.push(`**本次估算未调用 LLM，未生成任何 \`.spec.md\` 文件。**`);
+    lines.push('');
+    lines.push('## 总估算');
+    lines.push('');
+    lines.push('| 指标 | 数值 |');
+    lines.push('|------|------|');
+    lines.push(`| 模块数 | ${report.totalModules} |`);
+    lines.push(`| 预估 input tokens | ${report.totalEstimatedInput.toLocaleString()} |`);
+    lines.push(`| 预估 output tokens | ${report.totalEstimatedOutput.toLocaleString()} |`);
+    lines.push(`| 预估总 tokens | ${(report.totalEstimatedInput + report.totalEstimatedOutput).toLocaleString()} |`);
+    lines.push('');
+    lines.push(`_估算假设：${report.assumption}_`);
+    lines.push('');
+    lines.push('## 按模块明细');
+    lines.push('');
+    lines.push('| 模块 | 文件数 | LOC | 预估 input | 预估 output |');
+    lines.push('|------|--------|-----|-----------|------------|');
+    for (const m of report.modules) {
+        lines.push(`| ${m.moduleName} | ${m.files.length} | ${m.loc} | ${m.estimatedInput.toLocaleString()} | ${m.estimatedOutput.toLocaleString()} |`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+// ============================================================
+// 预算决策
+// ============================================================
+/**
+ * 判断是否超预算，并选择后续动作（FR-013 / FR-014 / Edge Case 8）
+ */
+export async function buildBudgetDecision(input) {
+    const { totalEstimate, budget, preset, isTTY, attempt = 0 } = input;
+    if (totalEstimate <= budget) {
+        return {
+            policy: 'continue',
+            interactive: false,
+            message: `预估 ${totalEstimate.toLocaleString()} tokens ≤ 预算 ${budget.toLocaleString()}，继续执行`,
+        };
+    }
+    const overMessage = `预估 ${totalEstimate.toLocaleString()} tokens > 预算 ${budget.toLocaleString()}`;
+    // 显式 preset 优先
+    if (preset) {
+        return {
+            policy: preset,
+            interactive: false,
+            message: `${overMessage}；非交互策略: ${preset}`,
+        };
+    }
+    // Edge Case 8：已重估 1 次后仍超预算，强制 cancel
+    if (attempt >= 1) {
+        return {
+            policy: 'cancel',
+            interactive: false,
+            message: `${overMessage}；已重估 ${attempt} 次仍超预算，默认 cancel 以防循环`,
+        };
+    }
+    // 非 TTY 未给 preset：视为 cancel
+    if (!isTTY) {
+        return {
+            policy: 'cancel',
+            interactive: false,
+            message: `${overMessage}；非交互环境未传 --on-over-budget，默认 cancel`,
+        };
+    }
+    // TTY 交互
+    const prompt = input.promptPolicy ?? defaultInteractivePrompt;
+    const policy = await prompt();
+    return {
+        policy,
+        interactive: true,
+        message: `${overMessage}；用户交互选择: ${policy}`,
+    };
+}
+/**
+ * 根据降级 policy 调整估算值（Feature 127 Codex review 修复）
+ *
+ * - skip-enrichment：enrichment 是 Section 2 的二次 LLM 调用，平均约占
+ *   整体 token 消耗的 30%；跳过后估算减为 70%
+ * - cheaper-model：tokens 数不变（budget 以 token 为单位），返回原值
+ * - continue / cancel：返回原值
+ */
+export function applyPolicyToEstimate(baseEstimate, policy) {
+    switch (policy) {
+        case 'skip-enrichment':
+            return Math.round(baseEstimate * 0.7);
+        case 'cheaper-model':
+        case 'continue':
+        case 'cancel':
+        default:
+            return baseEstimate;
+    }
+}
+/**
+ * 驱动完整的预算 gate 循环（Feature 127 Codex review 修复 — Finding 1）
+ *
+ * 与 buildBudgetDecision 的差别：
+ * - buildBudgetDecision 只做一次性决策（policy 选择）
+ * - runBudgetGate 负责把"降级 policy → 重估 → 二次 gate"的闭环跑完
+ *
+ * 语义：
+ * 1. attempt 0：用 baseEstimate 做首次 gate
+ * 2. policy 是 continue / cancel：立即返回
+ * 3. policy 是 cheaper-model / skip-enrichment：应用 policy → 重估 → attempt++ 再进
+ * 4. attempt ≥ 1（Edge Case 8）：即便还是超预算，也强制 cancel 避免循环
+ *
+ * 任一成功降级后得到 ≤ 预算的估算 → 返回 continue + 记录所采纳的降级
+ */
+export async function runBudgetGate(args) {
+    const attempts = [];
+    let estimate = args.baseEstimate;
+    let skipEnrichmentApplied = false;
+    let cheaperModelApplied = false;
+    for (let attempt = 0; attempt <= 1; attempt++) {
+        const decision = await buildBudgetDecision({
+            totalEstimate: estimate,
+            budget: args.budget,
+            preset: args.preset,
+            isTTY: args.isTTY,
+            promptPolicy: args.promptPolicy,
+            attempt,
+        });
+        attempts.push({
+            attempt,
+            estimate,
+            policy: decision.policy,
+            message: decision.message,
+        });
+        // 终态 policy：直接返回
+        if (decision.policy === 'continue' || decision.policy === 'cancel') {
+            return {
+                finalPolicy: decision.policy,
+                finalEstimate: estimate,
+                skipEnrichmentApplied,
+                cheaperModelApplied,
+                attempts,
+            };
+        }
+        // 降级 policy：应用调整后进入下一轮 gate
+        if (decision.policy === 'skip-enrichment') {
+            skipEnrichmentApplied = true;
+        }
+        else if (decision.policy === 'cheaper-model') {
+            cheaperModelApplied = true;
+        }
+        estimate = applyPolicyToEstimate(estimate, decision.policy);
+    }
+    // Edge Case 8：两轮仍超预算（例如 cheaper-model 不减 tokens），强制 cancel
+    attempts.push({
+        attempt: 2,
+        estimate,
+        policy: 'cancel',
+        message: `两轮降级后估算 ${estimate.toLocaleString()} tokens 仍 > 预算 ${args.budget.toLocaleString()}，强制 cancel`,
+    });
+    return {
+        finalPolicy: 'cancel',
+        finalEstimate: estimate,
+        skipEnrichmentApplied,
+        cheaperModelApplied,
+        attempts,
+    };
+}
+async function defaultInteractivePrompt() {
+    // 动态引入，避免 test 环境的 readline 副作用
+    const readline = await import('node:readline/promises');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        process.stdout.write('\n超预算。请选择后续动作：\n' +
+            '  1) continue           — 继续执行（放弃预算）\n' +
+            '  2) cheaper-model      — 降级到更便宜的 model 重估\n' +
+            '  3) skip-enrichment    — 跳过 Section 2 二次增强重估\n' +
+            '  4) cancel             — 立即取消\n');
+        const answer = (await rl.question('选择 [1-4]: ')).trim();
+        switch (answer) {
+            case '1':
+            case 'continue':
+                return 'continue';
+            case '2':
+            case 'cheaper-model':
+                return 'cheaper-model';
+            case '3':
+            case 'skip-enrichment':
+                return 'skip-enrichment';
+            case '4':
+            case 'cancel':
+            default:
+                return 'cancel';
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=budget-gate.js.map

package/dist/batch/budget-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-gate.js","sourceRoot":"","sources":["../../src/batch/budget-gate.ts"],"names":[],"mappings":"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"}

package/dist/batch/checkpoint.d.ts

@@ -0,0 +1,25 @@
+import { type BatchState } from '../models/module-spec.js';
+/** 默认检查点路径（Constitution IV：位于 specs/ 内） */
+export declare const DEFAULT_CHECKPOINT_PATH = "specs/.spectra-checkpoint.json";
+/**
+ * 加载已有检查点以恢复执行
+ *
+ * @param checkpointPath - 检查点文件路径
+ * @returns BatchState 或 null（未找到）
+ */
+export declare function loadCheckpoint(checkpointPath: string): BatchState | null;
+/**
+ * 原子写入检查点状态
+ * 先写临时文件再重命名，防止写入中断导致数据损坏
+ *
+ * @param state - 当前批处理状态
+ * @param checkpointPath - 检查点文件路径
+ */
+export declare function saveCheckpoint(state: BatchState, checkpointPath: string): void;
+/**
+ * 批处理成功完成后删除检查点
+ *
+ * @param checkpointPath - 检查点文件路径
+ */
+export declare function clearCheckpoint(checkpointPath: string): void;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/batch/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/batch/checkpoint.ts"],"names":[],"mappings":"AAOA,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE7E,2CAA2C;AAC3C,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAiBxE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,cAAc,EAAE,MAAM,GACrB,IAAI,CAaN;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAY5D"}

package/dist/batch/checkpoint.js

@@ -0,0 +1,68 @@
+/**
+ * 断点恢复检查点持久化（FR-017）
+ * 原子写入（临时文件+重命名）防止数据损坏
+ * 参见 contracts/batch-module.md
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { BatchStateSchema } from '../models/module-spec.js';
+/** 默认检查点路径（Constitution IV：位于 specs/ 内） */
+export const DEFAULT_CHECKPOINT_PATH = 'specs/.spectra-checkpoint.json';
+/**
+ * 加载已有检查点以恢复执行
+ *
+ * @param checkpointPath - 检查点文件路径
+ * @returns BatchState 或 null（未找到）
+ */
+export function loadCheckpoint(checkpointPath) {
+    const resolvedPath = path.resolve(checkpointPath);
+    if (!fs.existsSync(resolvedPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(resolvedPath, 'utf-8');
+        const data = JSON.parse(content);
+        // 使用 Zod 验证
+        return BatchStateSchema.parse(data);
+    }
+    catch {
+        // 损坏的检查点文件，返回 null
+        console.warn(`检查点文件损坏或无效: ${checkpointPath}，将重新开始`);
+        return null;
+    }
+}
+/**
+ * 原子写入检查点状态
+ * 先写临时文件再重命名，防止写入中断导致数据损坏
+ *
+ * @param state - 当前批处理状态
+ * @param checkpointPath - 检查点文件路径
+ */
+export function saveCheckpoint(state, checkpointPath) {
+    const resolvedPath = path.resolve(checkpointPath);
+    const dir = path.dirname(resolvedPath);
+    // 确保目录存在
+    fs.mkdirSync(dir, { recursive: true });
+    // 原子写入：先写临时文件
+    const tmpPath = `${resolvedPath}.tmp`;
+    const content = JSON.stringify(state, null, 2);
+    fs.writeFileSync(tmpPath, content, 'utf-8');
+    fs.renameSync(tmpPath, resolvedPath);
+}
+/**
+ * 批处理成功完成后删除检查点
+ *
+ * @param checkpointPath - 检查点文件路径
+ */
+export function clearCheckpoint(checkpointPath) {
+    const resolvedPath = path.resolve(checkpointPath);
+    if (fs.existsSync(resolvedPath)) {
+        fs.unlinkSync(resolvedPath);
+    }
+    // 清理临时文件
+    const tmpPath = `${resolvedPath}.tmp`;
+    if (fs.existsSync(tmpPath)) {
+        fs.unlinkSync(tmpPath);
+    }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/batch/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../src/batch/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAmB,MAAM,0BAA0B,CAAC;AAE7E,2CAA2C;AAC3C,MAAM,CAAC,MAAM,uBAAuB,GAAG,gCAAgC,CAAC;AAExE;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,cAAsB;IACnD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAElD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,YAAY;QACZ,OAAO,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,mBAAmB;QACnB,OAAO,CAAC,IAAI,CAAC,eAAe,cAAc,QAAQ,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAiB,EACjB,cAAsB;IAEtB,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAEvC,SAAS;IACT,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,cAAc;IACd,MAAM,OAAO,GAAG,GAAG,YAAY,MAAM,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAE/C,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,cAAsB;IACpD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAElD,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAChC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC9B,CAAC;IAED,SAAS;IACT,MAAM,OAAO,GAAG,GAAG,YAAY,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;AACH,CAAC"}

package/dist/batch/cost-summary.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Feature 127 — Batch 成本汇总
+ *
+ * 提供：
+ * - CostSummary 类型定义
+ * - aggregateCostSummary() 聚合每模块 CostMetadata 为批级汇总
+ * - renderSummaryCostSection() / renderQualityCostSection() 渲染 Markdown
+ *
+ * 职责边界：
+ * - 只负责聚合与渲染；不触碰 LLM 调用、不落盘
+ * - 渲染出的 Markdown 由调用方追加到 batch-summary.md / quality-report.md
+ */
+import type { CostMetadata } from '../models/module-spec.js';
+/** 单个模块的成本记录 */
+export interface ModuleCostRecord {
+    moduleName: string;
+    /** 总代码行数（用于 tokens/kLOC 指标；未知时传 0） */
+    loc: number;
+    cost: CostMetadata;
+}
+/** 预估成本（dry-run / budget 场景） */
+export interface EstimatedCost {
+    /** 所有模块预估 input token 总和 */
+    totalInput: number;
+    /** 所有模块预估 output token 总和 */
+    totalOutput: number;
+    /** 用户可读的假设说明（例如 "output ≈ 0.3 × input"） */
+    assumption: string;
+}
+/** 批处理成本汇总 */
+export interface CostSummary {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalDurationMs: number;
+    /** 按模块的明细，降序排列 */
+    byModule: Array<{
+        moduleName: string;
+        input: number;
+        output: number;
+        durationMs: number;
+        llmModel: string;
+        fallbackReason: string | null;
+        loc: number;
+    }>;
+    /** 按生成器（实际 llmModel）的聚合 */
+    byGenerator: Array<{
+        generator: string;
+        input: number;
+        output: number;
+        /** 该生成器 token 总量占总量的百分比（0-100，保留一位小数） */
+        share: number;
+        moduleCount: number;
+    }>;
+    /** 总代码行数（用于 tokens/kLOC） */
+    totalLoc: number;
+    /** 预估（若传入） */
+    estimated?: EstimatedCost;
+    /** 实际 vs 预估偏差百分比（仅 estimated 存在时计算；> 20 时告警） */
+    actualVsEstimatedDelta?: number;
+}
+/**
+ * 聚合每模块 CostMetadata 为 CostSummary
+ *
+ * @param records - 模块级成本记录；允许为空（返回全零 summary）
+ * @param estimated - 预估值（可选，来自 dry-run / budget 预检）
+ */
+export declare function aggregateCostSummary(records: ModuleCostRecord[], estimated?: EstimatedCost): CostSummary;
+/**
+ * 渲染给 batch-summary.md 的 "LLM 成本汇总" 节
+ * FR-008
+ */
+export declare function renderSummaryCostSection(summary: CostSummary): string;
+/**
+ * 渲染给 quality-report.md 的 "LLM 成本与预算" 节
+ * FR-009
+ */
+export declare function renderQualityCostSection(summary: CostSummary): string;
+//# sourceMappingURL=cost-summary.d.ts.map

package/dist/batch/cost-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-summary.d.ts","sourceRoot":"","sources":["../../src/batch/cost-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAM7D,gBAAgB;AAChB,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,gCAAgC;AAChC,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,cAAc;AACd,MAAM,WAAW,WAAW;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB;IAClB,QAAQ,EAAE,KAAK,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,GAAG,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;IACH,2BAA2B;IAC3B,WAAW,EAAE,KAAK,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,yCAAyC;QACzC,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc;IACd,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gDAAgD;IAChD,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,CAAC,EAAE,aAAa,GACxB,WAAW,CA0Eb;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CA2ErE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CA6CrE"}

package/dist/batch/cost-summary.js

@@ -0,0 +1,191 @@
+// ============================================================
+// 聚合
+// ============================================================
+/**
+ * 聚合每模块 CostMetadata 为 CostSummary
+ *
+ * @param records - 模块级成本记录；允许为空（返回全零 summary）
+ * @param estimated - 预估值（可选，来自 dry-run / budget 预检）
+ */
+export function aggregateCostSummary(records, estimated) {
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalDuration = 0;
+    let totalLoc = 0;
+    for (const rec of records) {
+        totalInput += rec.cost.tokenUsage.input;
+        totalOutput += rec.cost.tokenUsage.output;
+        totalDuration += rec.cost.durationMs;
+        totalLoc += rec.loc;
+    }
+    // 按模块明细：按 input+output 降序
+    const byModule = records
+        .map((rec) => ({
+        moduleName: rec.moduleName,
+        input: rec.cost.tokenUsage.input,
+        output: rec.cost.tokenUsage.output,
+        durationMs: rec.cost.durationMs,
+        llmModel: rec.cost.llmModel,
+        fallbackReason: rec.cost.fallbackReason,
+        loc: rec.loc,
+    }))
+        .sort((a, b) => b.input + b.output - (a.input + a.output));
+    // 按生成器分组：llmModel 为空字符串时归入 'ast-only'
+    const generatorMap = new Map();
+    for (const rec of records) {
+        const key = rec.cost.llmModel || 'ast-only';
+        const existing = generatorMap.get(key) ?? { input: 0, output: 0, moduleCount: 0 };
+        existing.input += rec.cost.tokenUsage.input;
+        existing.output += rec.cost.tokenUsage.output;
+        existing.moduleCount += 1;
+        generatorMap.set(key, existing);
+    }
+    const totalTokens = totalInput + totalOutput;
+    const byGenerator = [...generatorMap.entries()]
+        .map(([generator, v]) => ({
+        generator,
+        input: v.input,
+        output: v.output,
+        share: totalTokens > 0
+            ? Math.round(((v.input + v.output) / totalTokens) * 1000) / 10
+            : 0,
+        moduleCount: v.moduleCount,
+    }))
+        .sort((a, b) => b.input + b.output - (a.input + a.output));
+    const summary = {
+        totalInputTokens: totalInput,
+        totalOutputTokens: totalOutput,
+        totalDurationMs: totalDuration,
+        byModule,
+        byGenerator,
+        totalLoc,
+    };
+    // 预估对比
+    if (estimated) {
+        summary.estimated = estimated;
+        const estimatedTotal = estimated.totalInput + estimated.totalOutput;
+        if (estimatedTotal > 0) {
+            const actualTotal = totalTokens;
+            summary.actualVsEstimatedDelta =
+                Math.round(((actualTotal - estimatedTotal) / estimatedTotal) * 1000) / 10;
+        }
+    }
+    return summary;
+}
+// ============================================================
+// 渲染
+// ============================================================
+/**
+ * 渲染给 batch-summary.md 的 "LLM 成本汇总" 节
+ * FR-008
+ */
+export function renderSummaryCostSection(summary) {
+    const lines = [];
+    lines.push('## LLM 成本汇总');
+    lines.push('');
+    const totalTokens = summary.totalInputTokens + summary.totalOutputTokens;
+    if (totalTokens === 0) {
+        lines.push('本次 batch 未调用 LLM（可能为 AST-only 或 dry-run 模式）。');
+        lines.push('');
+        return lines.join('\n');
+    }
+    lines.push('| 指标 | 数值 |');
+    lines.push('|------|------|');
+    lines.push(`| 总 input tokens | ${summary.totalInputTokens.toLocaleString()} |`);
+    lines.push(`| 总 output tokens | ${summary.totalOutputTokens.toLocaleString()} |`);
+    lines.push(`| 总 token 数 | ${totalTokens.toLocaleString()} |`);
+    lines.push(`| LLM 总耗时 | ${(summary.totalDurationMs / 1000).toFixed(1)}s |`);
+    if (summary.totalLoc > 0) {
+        const tokensPerKLoc = Math.round((totalTokens / summary.totalLoc) * 1000);
+        lines.push(`| tokens / kLOC | ${tokensPerKLoc.toLocaleString()} |`);
+    }
+    lines.push('');
+    // 按生成器
+    lines.push('### 按生成器分组');
+    lines.push('');
+    lines.push('| 生成器 / Model | 模块数 | input | output | 占比 |');
+    lines.push('|----------------|--------|-------|--------|------|');
+    for (const g of summary.byGenerator) {
+        lines.push(`| \`${g.generator}\` | ${g.moduleCount} | ${g.input.toLocaleString()} | ${g.output.toLocaleString()} | ${g.share.toFixed(1)}% |`);
+    }
+    lines.push('');
+    // 按模块（从高到低，最多 20 条，避免报告过长）
+    lines.push('### 按模块分组（Top 20，从高到低）');
+    lines.push('');
+    lines.push('| 模块 | Model | input | output | 耗时 | 降级 |');
+    lines.push('|------|-------|-------|--------|------|------|');
+    for (const m of summary.byModule.slice(0, 20)) {
+        const fb = m.fallbackReason ? `⚠ ${m.fallbackReason}` : '—';
+        const model = m.llmModel || 'ast-only';
+        lines.push(`| ${m.moduleName} | \`${model}\` | ${m.input.toLocaleString()} | ${m.output.toLocaleString()} | ${(m.durationMs / 1000).toFixed(1)}s | ${fb} |`);
+    }
+    if (summary.byModule.length > 20) {
+        lines.push('');
+        lines.push(`_...另有 ${summary.byModule.length - 20} 个模块未展示_`);
+    }
+    lines.push('');
+    // 预估对比
+    if (summary.estimated) {
+        const est = summary.estimated;
+        lines.push('### 预估 vs 实际');
+        lines.push('');
+        lines.push('| 指标 | 预估 | 实际 |');
+        lines.push('|------|------|------|');
+        lines.push(`| input tokens | ${est.totalInput.toLocaleString()} | ${summary.totalInputTokens.toLocaleString()} |`);
+        lines.push(`| output tokens | ${est.totalOutput.toLocaleString()} | ${summary.totalOutputTokens.toLocaleString()} |`);
+        lines.push('');
+        lines.push(`- 预估假设：${est.assumption}`);
+        if (typeof summary.actualVsEstimatedDelta === 'number') {
+            const delta = summary.actualVsEstimatedDelta;
+            const sign = delta > 0 ? '+' : '';
+            const warn = Math.abs(delta) > 20 ? ' ⚠ 偏差超 20%，估算模型需调整' : '';
+            lines.push(`- 偏差：${sign}${delta.toFixed(1)}%${warn}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * 渲染给 quality-report.md 的 "LLM 成本与预算" 节
+ * FR-009
+ */
+export function renderQualityCostSection(summary) {
+    const lines = [];
+    lines.push('## LLM 成本与预算');
+    lines.push('');
+    const totalTokens = summary.totalInputTokens + summary.totalOutputTokens;
+    if (totalTokens === 0) {
+        lines.push('本次 batch 未调用 LLM。成本为 0。');
+        lines.push('');
+        return lines.join('\n');
+    }
+    lines.push('### 本次总成本');
+    lines.push('');
+    lines.push(`- 总 input tokens: **${summary.totalInputTokens.toLocaleString()}**`);
+    lines.push(`- 总 output tokens: **${summary.totalOutputTokens.toLocaleString()}**`);
+    lines.push(`- 总耗时: **${(summary.totalDurationMs / 1000).toFixed(1)}s**`);
+    if (summary.totalLoc > 0) {
+        const tokensPerKLoc = Math.round((totalTokens / summary.totalLoc) * 1000);
+        lines.push(`- 性价比: **${tokensPerKLoc.toLocaleString()} tokens / kLOC** (${summary.totalLoc.toLocaleString()} LOC)`);
+    }
+    lines.push('');
+    lines.push('### 按生成器占比');
+    lines.push('');
+    lines.push('| 生成器 | 占比 | 模块数 |');
+    lines.push('|--------|------|--------|');
+    for (const g of summary.byGenerator) {
+        lines.push(`| \`${g.generator}\` | ${g.share.toFixed(1)}% | ${g.moduleCount} |`);
+    }
+    lines.push('');
+    if (summary.estimated &&
+        typeof summary.actualVsEstimatedDelta === 'number' &&
+        Math.abs(summary.actualVsEstimatedDelta) > 20) {
+        lines.push('> ⚠ 本次估算与实际偏差超 20%（' +
+            (summary.actualVsEstimatedDelta > 0 ? '+' : '') +
+            summary.actualVsEstimatedDelta.toFixed(1) +
+            '%），估算可靠性低，建议校准估算模型。');
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=cost-summary.js.map