soloforge 1.1.2 → 1.1.30

package/dist/engine/audit/mutation_audit.js

@@ -0,0 +1,136 @@
+/**
+ * 变异审计真实化 — 需求绑定变异点 + mutant killed 证据。
+ * R9 advisory: 不 hard block，只产出 advisory 报告。
+ *
+ * 职责:
+ * - computeMutationAudit: 从变更文件 + 需求点 + 源码计算变异证据
+ * - 产出 MutationAuditEvidence: mutant_killed_count / mutant_total_count / per-requirement 绑定
+ */
+import { debug } from "../core/logger.js";
+const CANDIDATE_PATTERNS = [
+    /\b(if|else|switch|case)\b/.source,
+    /(===|!==|==|!=|>=|<=|>|<)/.source,
+    /(&&|\|\|)/.source,
+    /\breturn\b/.source,
+];
+const CANDIDATE_RE = new RegExp(CANDIDATE_PATTERNS.join("|"));
+const EXCLUDE_PATTERNS = [
+    /^\s*\/\//,
+    /^\s*\*/,
+    /^\s*\/\*/,
+    /^\s*import /,
+    /^\s*export /,
+    /^\s*console\./,
+    /^\s*(interface|type|enum|declare) /,
+    /^\s*debugger/,
+];
+function isCandidateLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return false;
+    if (EXCLUDE_PATTERNS.some((p) => p.test(trimmed)))
+        return false;
+    return CANDIDATE_RE.test(trimmed);
+}
+/**
+ * 从源码中提取变异候选点，并尝试关联到需求点。
+ * 关联策略: 文件路径与需求点描述关键词匹配。
+ *
+ * @param sourceFiles - 源文件列表，包含文件路径和内容
+ * @param requirementPoints - 需求点列表
+ * @returns 变异候选点数组
+ */
+export function extractMutationPoints(sourceFiles, requirementPoints) {
+    const points = [];
+    debug("变异审计", "extractMutationPoints() 开始执行，源文件数:", sourceFiles.length, "，需求点数:", requirementPoints.length);
+    for (const file of sourceFiles) {
+        const lines = file.content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            if (!isCandidateLine(lines[i]))
+                continue;
+            const matchedRp = requirementPoints.find((rp) => {
+                const keywords = rp.description.toLowerCase().split(/\s+/);
+                return keywords.some((kw) => kw.length > 2 && file.file_path.toLowerCase().includes(kw));
+            });
+            points.push({
+                file_path: file.file_path,
+                line_number: i + 1,
+                original_line: lines[i].trim(),
+                requirement_point_id: matchedRp?.id,
+            });
+        }
+    }
+    debug("变异审计", "提取到变异候选点", points.length, "个");
+    return points;
+}
+/**
+ * 计算变异审计证据 — 每个需求点的变异覆盖状态。
+ *
+ * @param mutationPoints - 变异候选点数组
+ * @param requirementPoints - 需求点列表
+ * @param killedCount - 已 killed 的变异数
+ * @param totalCount - 变异总数
+ * @returns 变异审计证据
+ */
+export function computeMutationAudit(mutationPoints, requirementPoints, killedCount, totalCount) {
+    const perRequirement = [];
+    const coveredRpIds = new Set();
+    debug("变异审计", "computeMutationAudit() 开始执行，需求点数:", requirementPoints.length, "变异点数:", mutationPoints.length, "killed:", killedCount, "/", totalCount);
+    for (const rp of requirementPoints) {
+        const rpPoints = mutationPoints.filter((mp) => mp.requirement_point_id === rp.id);
+        const rpTotal = rpPoints.length;
+        if (rpTotal > 0) {
+            coveredRpIds.add(rp.id);
+            // 按比例分配 killed 计数
+            const rpKilled = Math.min(Math.round((rpTotal / Math.max(totalCount, 1)) * killedCount), rpTotal);
+            perRequirement.push({
+                requirement_point_id: rp.id,
+                mutation_points: rpTotal,
+                mutants_killed: rpKilled,
+                mutants_total: rpTotal,
+                advisory: rpKilled === rpTotal
+                    ? "all mutants killed"
+                    : `advisory: ${rpTotal - rpKilled}/${rpTotal} mutants not killed for ${rp.id}`,
+            });
+        }
+        else {
+            perRequirement.push({
+                requirement_point_id: rp.id,
+                mutation_points: 0,
+                mutants_killed: 0,
+                mutants_total: 0,
+                advisory: `advisory: no mutation points found for requirement ${rp.id}`,
+            });
+        }
+    }
+    // 同时包含未绑定到任何需求点的变异点
+    const unboundPoints = mutationPoints.filter((mp) => !mp.requirement_point_id);
+    if (unboundPoints.length > 0) {
+        perRequirement.push({
+            requirement_point_id: "_unbound",
+            mutation_points: unboundPoints.length,
+            mutants_killed: 0,
+            mutants_total: unboundPoints.length,
+            advisory: `advisory: ${unboundPoints.length} mutation points not bound to any requirement`,
+        });
+    }
+    const uncoveredRequirements = requirementPoints
+        .filter((rp) => !coveredRpIds.has(rp.id))
+        .map((rp) => rp.id);
+    if (uncoveredRequirements.length > 0) {
+        debug("变异审计", "发现未覆盖的需求点:", uncoveredRequirements.join(", "));
+    }
+    const killRatio = totalCount > 0 ? killedCount / totalCount : 1;
+    debug("变异审计", "计算完成 — kill_ratio:", (killRatio * 100).toFixed(0) + "%", "，未覆盖需求:", uncoveredRequirements.length);
+    return {
+        mutant_killed_count: killedCount,
+        mutant_total_count: totalCount,
+        kill_ratio: killRatio,
+        per_requirement: perRequirement,
+        uncovered_requirements: uncoveredRequirements,
+        summary: uncoveredRequirements.length > 0
+            ? `advisory: ${uncoveredRequirements.length} requirement(s) have no killed mutants: ${uncoveredRequirements.join(", ")}`
+            : `mutation audit: ${killedCount}/${totalCount} killed (ratio: ${(killRatio * 100).toFixed(0)}%)`,
+    };
+}
+//# sourceMappingURL=mutation_audit.js.map

package/dist/engine/audit/mutation_audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation_audit.js","sourceRoot":"","sources":["../../../src/engine/audit/mutation_audit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AA0B1C,MAAM,kBAAkB,GAAG;IACzB,2BAA2B,CAAC,MAAM;IAClC,2BAA2B,CAAC,MAAM;IAClC,WAAW,CAAC,MAAM;IAClB,YAAY,CAAC,MAAM;CACpB,CAAC;AAEF,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE9D,MAAM,gBAAgB,GAAG;IACvB,UAAU;IACV,QAAQ;IACR,UAAU;IACV,aAAa;IACb,aAAa;IACb,eAAe;IACf,oCAAoC;IACpC,cAAc;CACf,CAAC;AAEF,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAChE,OAAO,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAA0D,EAC1D,iBAAqC;IAErC,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,KAAK,CAAC,MAAM,EAAE,oCAAoC,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAE5G,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAAE,SAAS;YAEzC,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE;gBAC9C,MAAM,QAAQ,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC3D,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;YAC3F,CAAC,CAAC,CAAC;YAEH,MAAM,CAAC,IAAI,CAAC;gBACV,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,WAAW,EAAE,CAAC,GAAG,CAAC;gBAClB,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;gBAC9B,oBAAoB,EAAE,SAAS,EAAE,EAAE;aACpC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,cAA+B,EAC/B,iBAAqC,EACrC,WAAmB,EACnB,UAAkB;IAElB,MAAM,cAAc,GAAyB,EAAE,CAAC;IAChD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,CAAC,MAAM,EAAE,mCAAmC,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IAEtJ,KAAK,MAAM,EAAE,IAAI,iBAAiB,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CACpC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,oBAAoB,KAAK,EAAE,CAAC,EAAE,CAC1C,CAAC;QACF,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC;QAEhC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACxB,kBAAkB;YAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CACvB,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,EAC7D,OAAO,CACR,CAAC;YACF,cAAc,CAAC,IAAI,CAAC;gBAClB,oBAAoB,EAAE,EAAE,CAAC,EAAE;gBAC3B,eAAe,EAAE,OAAO;gBACxB,cAAc,EAAE,QAAQ;gBACxB,aAAa,EAAE,OAAO;gBACtB,QAAQ,EACN,QAAQ,KAAK,OAAO;oBAClB,CAAC,CAAC,oBAAoB;oBACtB,CAAC,CAAC,aAAa,OAAO,GAAG,QAAQ,IAAI,OAAO,2BAA2B,EAAE,CAAC,EAAE,EAAE;aACnF,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,cAAc,CAAC,IAAI,CAAC;gBAClB,oBAAoB,EAAE,EAAE,CAAC,EAAE;gBAC3B,eAAe,EAAE,CAAC;gBAClB,cAAc,EAAE,CAAC;gBACjB,aAAa,EAAE,CAAC;gBAChB,QAAQ,EAAE,sDAAsD,EAAE,CAAC,EAAE,EAAE;aACxE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,oBAAoB;IACpB,MAAM,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,oBAAoB,CAAC,CAAC;IAC9E,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,cAAc,CAAC,IAAI,CAAC;YAClB,oBAAoB,EAAE,UAAU;YAChC,eAAe,EAAE,aAAa,CAAC,MAAM;YACrC,cAAc,EAAE,CAAC;YACjB,aAAa,EAAE,aAAa,CAAC,MAAM;YACnC,QAAQ,EAAE,aAAa,aAAa,CAAC,MAAM,+CAA+C;SAC3F,CAAC,CAAC;IACL,CAAC;IAGD,MAAM,qBAAqB,GAAG,iBAAiB;SAC5C,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;SACxC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACtB,IAAI,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhE,KAAK,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,EAAE,SAAS,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACjH,OAAO;QACL,mBAAmB,EAAE,WAAW;QAChC,kBAAkB,EAAE,UAAU;QAC9B,UAAU,EAAE,SAAS;QACrB,eAAe,EAAE,cAAc;QAC/B,sBAAsB,EAAE,qBAAqB;QAC7C,OAAO,EACL,qBAAqB,CAAC,MAAM,GAAG,CAAC;YAC9B,CAAC,CAAC,aAAa,qBAAqB,CAAC,MAAM,2CAA2C,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YACxH,CAAC,CAAC,mBAAmB,WAAW,IAAI,UAAU,mBAAmB,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;KACtG,CAAC;AACJ,CAAC"}

package/dist/engine/audit/observability.d.ts

@@ -0,0 +1,68 @@
+import type { MetricsSnapshot, AlertItem, ObservabilityReport, CostBudget, CostAlert } from "../../types/index.js";
+import type { MetricSample } from "../contracts/extension_platform_contracts.js";
+/**
+ * 采集任务目录下的所有 TaskContext，计算聚合指标。
+ * 包括通过率、重试率、平均耗时和知识匹配率。
+ * @param stateDir - 任务状态文件目录路径
+ * @returns 指标快照，包含通过率、重试率、平均耗时、知识匹配率
+ */
+export declare function collectMetrics(stateDir: string): Promise<MetricsSnapshot>;
+/**
+ * 基于阈值检测指标异常，生成告警列表。
+ * 告警规则：
+ *   - 失败率 >= 30% → critical
+ *   - 失败率 >= 15% → warning
+ *   - 重试率 > 40% → warning
+ *   - 平均耗时 > 5 分钟 → warning
+ *   - 知识匹配率 < 50% → warning
+ * @param snapshot - 采集到的指标快照
+ * @returns 告警条目列表（按检测顺序排列）
+ */
+export declare function checkAlerts(snapshot: MetricsSnapshot): AlertItem[];
+/**
+ * 从真实 TaskContext 状态目录生成交付指标治理样本。
+ * @description 该函数用于 sf_deliver 主链路，把 observability 聚合指标转换为
+ *              metric_governance.evaluateMetrics 可消费的 MetricSample。
+ *              样本来自 .soloforge/state 中的真实 TaskContext，不允许调用方传空数组冒充通过。
+ *              历史样本不足时只输出"数据源可用"样本，避免把缺少历史数据伪装成业务指标通过。
+ * @param stateDir - TaskContext 状态目录
+ * @param minCompletedTasks - 启用质量指标门控所需的最小已完成任务数
+ */
+export declare function collectDeliveryMetricSamples(stateDir: string, minCompletedTasks?: number): Promise<MetricSample[]>;
+/**
+ * 生成指定周期内的完整可观测性报告。
+ * 包含聚合指标、告警、每日趋势数据和中文摘要。
+ * @param stateDir - 任务状态文件目录路径
+ * @param periodDays - 报告回溯天数，默认 30 天
+ * @returns 可观测性报告，包含时间范围、指标快照、告警、趋势和摘要
+ */
+export declare function generateReport(stateDir: string, periodDays?: number): Promise<ObservabilityReport>;
+/**
+ * 根据任务数量和类型粗略估算 Token 消耗。
+ * @param stateDir - 任务状态文件目录路径
+ * @returns 包含总估算 Token 数和按任务类型分组的估算明细
+ */
+export declare function estimateCost(stateDir: string): Promise<{
+    total_estimated_tokens: number;
+    by_task_type: Record<string, number>;
+}>;
+/**
+ * 检查 Token 用量是否超出预算，生成超支或接近预算（>=80%）的告警。
+ * 分别检查日、周、月三个维度的预算。
+ * @param stateDir - 任务状态文件目录路径
+ * @param budget - 成本预算配置（含日/周/月 Token 限额）
+ * @returns 成本告警列表
+ */
+export declare function checkCostBudget(stateDir: string, budget: CostBudget): Promise<CostAlert[]>;
+/**
+ * 获取最近指定天数的每日 Token 用量趋势。
+ * 缺失的日期填充为 0，确保时间线连续。
+ * @param stateDir - 任务状态文件目录路径
+ * @param days - 回溯天数，默认 30 天
+ * @returns 按日期排列的每日 Token 消耗估算数组
+ */
+export declare function getCostTrend(stateDir: string, days?: number): Promise<Array<{
+    date: string;
+    estimated_tokens: number;
+}>>;
+//# sourceMappingURL=observability.d.ts.map

package/dist/engine/audit/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../../src/engine/audit/observability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAe,eAAe,EAAE,SAAS,EAAE,mBAAmB,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAChI,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAC;AAwFjF;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAiD/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,EAAE,CA+DlE;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,MAAM,EAChB,iBAAiB,GAAE,MAAU,GAC5B,OAAO,CAAC,YAAY,EAAE,CAAC,CAgDzB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAAW,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAoE9B;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IACX,sBAAsB,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAetE;AAoBD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAmFhG;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAW,GAChB,OAAO,CAAC,KAAK,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAkCzC"}

package/dist/engine/audit/observability.js

@@ -0,0 +1,435 @@
+import fs from "node:fs/promises";
+import fss from "node:fs";
+import path from "node:path";
+import { debug } from "../core/logger.js";
+/**
+ * 系统可观测模块 — 采集任务指标、检测异常告警、生成周期报告和成本估算。
+ * 基于 TaskContext JSON 文件聚合计算，零外部依赖。
+ */
+// ── 各任务类型的单次 Token 消耗估算值 ──
+// 用于成本预估和预算检查，单位为 token 数
+const TOKEN_ESTIMATES = {
+    feature: 8_000, // 新功能：涉及上下文理解和代码生成，估算较高
+    bugfix: 5_000, // 缺陷修复：上下文范围相对集中
+    refactor: 10_000, // 重构：需要全局理解和多文件修改，估算最高
+    hotfix: 4_000, // 紧急修复：范围明确，耗时较短
+};
+/** 未知任务类型的默认 Token 估算值 */
+const DEFAULT_TOKEN_ESTIMATE = 3_000;
+/**
+ * 从指定目录加载所有 TaskContext JSON 文件。
+ * 跳过损坏或格式不正确的文件，忽略无 task_id 或 created_at 的无效条目。
+ * @param stateDir - 任务状态文件目录路径
+ * @returns 有效的任务上下文列表（附加文件 mtime 信息）
+ */
+async function loadTasks(stateDir) {
+    const tasks = [];
+    let files;
+    try {
+        files = fss.readdirSync(stateDir);
+    }
+    catch (e) {
+        debug("observability", "读取任务状态目录失败", e);
+        return tasks;
+    }
+    const jsonFiles = files.filter((f) => f.endsWith(".json"));
+    for (const file of jsonFiles) {
+        try {
+            const filePath = path.join(stateDir, file);
+            const raw = await fs.readFile(filePath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed.task_id === "string" && typeof parsed.created_at === "string") {
+                const stat = fss.statSync(filePath);
+                parsed._mtimeMs = stat.mtimeMs;
+                tasks.push(parsed);
+            }
+        }
+        catch {
+            // 跳过损坏或不可读的文件
+        }
+    }
+    return tasks;
+}
+/**
+ * 计算单个任务的持续时间（毫秒）。
+ * 已完成任务使用文件修改时间作为结束时间的近似值，避免 "now - created" 一直增长的问题。
+ * 进行中任务使用当前时间作为结束时间。
+ * @param task - 任务上下文
+ * @param now - 当前时间戳（毫秒）
+ * @param fileMtimeMs - 任务文件最后修改时间（毫秒），用于已完成任务的精确耗时计算
+ * @returns 任务持续时间（毫秒）
+ */
+function taskDurationMs(task, now, fileMtimeMs) {
+    const created = new Date(task.created_at).getTime();
+    // 已完成任务：用文件 mtime 近似任务完成时刻，比 "now - created_at" 更准确
+    if (task.status === "done" && fileMtimeMs && fileMtimeMs > created) {
+        return fileMtimeMs - created;
+    }
+    // 进行中任务：用当前时间作为截止点
+    return now - created;
+}
+// ── 公开接口 ──
+/**
+ * 采集任务目录下的所有 TaskContext，计算聚合指标。
+ * 包括通过率、重试率、平均耗时和知识匹配率。
+ * @param stateDir - 任务状态文件目录路径
+ * @returns 指标快照，包含通过率、重试率、平均耗时、知识匹配率
+ */
+export async function collectMetrics(stateDir) {
+    const tasks = await loadTasks(stateDir);
+    debug("可观测", "开始采集指标, stateDir=" + stateDir);
+    const now = Date.now();
+    if (tasks.length === 0) {
+        return {
+            timestamp: new Date(now).toISOString(),
+            total_tasks: 0,
+            pass_rate: 0,
+            retry_rate: 0,
+            avg_duration_ms: 0,
+            knowledge_hit_rate: 0,
+        };
+    }
+    const total = tasks.length;
+    const doneCount = tasks.filter((t) => t.status === "done").length;
+    const passRate = doneCount / total;
+    // 统计有过失败历史的任务（即经历过重试的任务）
+    const retriedCount = tasks.filter((t) => t.execution && t.execution.failure_history && t.execution.failure_history.length > 0).length;
+    const retryRate = retriedCount / total;
+    // 计算所有任务的平均持续时间
+    const durations = tasks.map((t) => taskDurationMs(t, now, t._mtimeMs));
+    const avgDuration = durations.reduce((a, b) => a + b, 0) / total;
+    // 知识匹配率：在有过 expansion 的任务中，匹配到知识条目的比例
+    const tasksWithExpansion = tasks.filter((t) => !!t.expansion);
+    const knowledgeHitCount = tasksWithExpansion.filter((t) => t.expansion.matched_knowledge && t.expansion.matched_knowledge.length > 0).length;
+    // 避免除零：无 expansion 记录时知识匹配率为 0
+    const knowledgeHitRate = tasksWithExpansion.length > 0 ? knowledgeHitCount / tasksWithExpansion.length : 0;
+    // 保留 3 位小数精度
+    return {
+        timestamp: new Date(now).toISOString(),
+        total_tasks: total,
+        pass_rate: Math.round(passRate * 1000) / 1000,
+        retry_rate: Math.round(retryRate * 1000) / 1000,
+        avg_duration_ms: Math.round(avgDuration),
+        knowledge_hit_rate: Math.round(knowledgeHitRate * 1000) / 1000,
+    };
+}
+/**
+ * 基于阈值检测指标异常，生成告警列表。
+ * 告警规则：
+ *   - 失败率 >= 30% → critical
+ *   - 失败率 >= 15% → warning
+ *   - 重试率 > 40% → warning
+ *   - 平均耗时 > 5 分钟 → warning
+ *   - 知识匹配率 < 50% → warning
+ * @param snapshot - 采集到的指标快照
+ * @returns 告警条目列表（按检测顺序排列）
+ */
+export function checkAlerts(snapshot) {
+    debug("可观测性", "checkAlerts() 开始执行");
+    const alerts = [];
+    // 失败率超过 30% 时触发严重告警
+    if (snapshot.pass_rate < 0.7 && snapshot.total_tasks > 0) {
+        alerts.push({
+            level: "critical",
+            metric: "fail_rate",
+            current: Math.round((1 - snapshot.pass_rate) * 1000) / 1000,
+            threshold: 0.3,
+            message: "近期任务失败率过高",
+        });
+    }
+    // 失败率超过 15% 时触发警告告警
+    else if (snapshot.pass_rate < 0.85 && snapshot.total_tasks > 0) {
+        alerts.push({
+            level: "warning",
+            metric: "fail_rate",
+            current: Math.round((1 - snapshot.pass_rate) * 1000) / 1000,
+            threshold: 0.15,
+            message: "任务失败率呈上升趋势",
+        });
+    }
+    // 重试率超过 40% 说明任务首次执行成功率偏低
+    if (snapshot.retry_rate > 0.4) {
+        alerts.push({
+            level: "warning",
+            metric: "retry_rate",
+            current: snapshot.retry_rate,
+            threshold: 0.4,
+            message: "任务重试率偏高",
+        });
+    }
+    // 平均耗时超过 5 分钟（300,000ms）说明任务可能过重
+    if (snapshot.avg_duration_ms > 300_000) {
+        alerts.push({
+            level: "warning",
+            metric: "avg_duration_ms",
+            current: snapshot.avg_duration_ms,
+            threshold: 300_000,
+            message: "平均任务耗时过长",
+        });
+    }
+    // 知识匹配率低于 50% 提示需要补充项目知识
+    if (snapshot.knowledge_hit_rate < 0.5 && snapshot.total_tasks > 0) {
+        alerts.push({
+            level: "warning",
+            metric: "knowledge_hit_rate",
+            current: snapshot.knowledge_hit_rate,
+            threshold: 0.5,
+            message: "知识匹配率偏低，考虑补充项目知识",
+        });
+    }
+    return alerts;
+    if (alerts.length > 0) {
+        debug("可观测", "检测到 " + alerts.length + " 条告警");
+    }
+}
+/**
+ * 从真实 TaskContext 状态目录生成交付指标治理样本。
+ * @description 该函数用于 sf_deliver 主链路，把 observability 聚合指标转换为
+ *              metric_governance.evaluateMetrics 可消费的 MetricSample。
+ *              样本来自 .soloforge/state 中的真实 TaskContext，不允许调用方传空数组冒充通过。
+ *              历史样本不足时只输出"数据源可用"样本，避免把缺少历史数据伪装成业务指标通过。
+ * @param stateDir - TaskContext 状态目录
+ * @param minCompletedTasks - 启用质量指标门控所需的最小已完成任务数
+ */
+export async function collectDeliveryMetricSamples(stateDir, minCompletedTasks = 3) {
+    debug("可观测", "采集交付指标治理样本, stateDir=" + stateDir);
+    const snapshot = await collectMetrics(stateDir);
+    const sampledAt = snapshot.timestamp;
+    const completedTaskCount = Math.round(snapshot.pass_rate * snapshot.total_tasks);
+    const samples = [
+        {
+            metric_id: "observability.data_source_available",
+            value: snapshot.total_tasks,
+            sampled_at: sampledAt,
+            sample_status: "passed",
+        },
+    ];
+    if (completedTaskCount < minCompletedTasks) {
+        return samples;
+    }
+    samples.push({
+        metric_id: "delivery.pass_rate",
+        value: snapshot.pass_rate,
+        sampled_at: sampledAt,
+        sample_status: snapshot.pass_rate >= 0.85 ? "passed" : snapshot.pass_rate >= 0.7 ? "degraded" : "manual_required",
+    });
+    samples.push({
+        metric_id: "delivery.retry_rate",
+        value: snapshot.retry_rate,
+        sampled_at: sampledAt,
+        sample_status: snapshot.retry_rate <= 0.4 ? "passed" : "degraded",
+    });
+    samples.push({
+        metric_id: "delivery.avg_duration_ms",
+        value: snapshot.avg_duration_ms,
+        sampled_at: sampledAt,
+        sample_status: snapshot.avg_duration_ms <= 300_000 ? "passed" : "degraded",
+    });
+    samples.push({
+        metric_id: "delivery.knowledge_hit_rate",
+        value: snapshot.knowledge_hit_rate,
+        sampled_at: sampledAt,
+        sample_status: snapshot.knowledge_hit_rate >= 0.5 ? "passed" : "degraded",
+    });
+    return samples;
+}
+/**
+ * 生成指定周期内的完整可观测性报告。
+ * 包含聚合指标、告警、每日趋势数据和中文摘要。
+ * @param stateDir - 任务状态文件目录路径
+ * @param periodDays - 报告回溯天数，默认 30 天
+ * @returns 可观测性报告，包含时间范围、指标快照、告警、趋势和摘要
+ */
+export async function generateReport(stateDir, periodDays = 30) {
+    debug("可观测", "生成报告, 回溯天数=" + periodDays);
+    const now = new Date();
+    // 计算报告起始时间点
+    const start = new Date(now.getTime() - periodDays * 24 * 60 * 60 * 1000);
+    const period = {
+        start: start.toISOString(),
+        end: now.toISOString(),
+    };
+    const snapshot = await collectMetrics(stateDir);
+    const alerts = checkAlerts(snapshot);
+    // 按创建日期将任务分桶，构建每日趋势数据
+    const tasks = await loadTasks(stateDir);
+    const dailyMap = new Map();
+    for (const task of tasks) {
+        const taskDate = new Date(task.created_at);
+        if (taskDate >= start && taskDate <= now) {
+            const dayKey = taskDate.toISOString().slice(0, 10); // YYYY-MM-DD 格式作为分桶键
+            const bucket = dailyMap.get(dayKey) ?? [];
+            bucket.push(task);
+            dailyMap.set(dayKey, bucket);
+        }
+    }
+    // 按日期升序排列
+    const sortedDays = Array.from(dailyMap.keys()).sort();
+    const passRateValues = [];
+    const retryRateValues = [];
+    const avgDurationValues = [];
+    for (const day of sortedDays) {
+        const dayTasks = dailyMap.get(day);
+        const dayTotal = dayTasks.length;
+        const dayDone = dayTasks.filter((t) => t.status === "done").length;
+        passRateValues.push(dayTotal > 0 ? Math.round((dayDone / dayTotal) * 1000) / 1000 : 0);
+        const dayRetried = dayTasks.filter((t) => t.execution && t.execution.failure_history && t.execution.failure_history.length > 0).length;
+        retryRateValues.push(dayTotal > 0 ? Math.round((dayRetried / dayTotal) * 1000) / 1000 : 0);
+        const nowMs = now.getTime();
+        const dayDurations = dayTasks.map((t) => taskDurationMs(t, nowMs, t._mtimeMs));
+        avgDurationValues.push(dayTotal > 0 ? Math.round(dayDurations.reduce((a, b) => a + b, 0) / dayTotal) : 0);
+    }
+    const trends = [
+        { metric: "pass_rate", values: passRateValues },
+        { metric: "retry_rate", values: retryRateValues },
+        { metric: "avg_duration_ms", values: avgDurationValues },
+    ];
+    const passPercent = (snapshot.pass_rate * 100).toFixed(1);
+    const retryPercent = (snapshot.retry_rate * 100).toFixed(1);
+    const knowledgePercent = (snapshot.knowledge_hit_rate * 100).toFixed(1);
+    const summary = `过去${periodDays}天共执行 ${snapshot.total_tasks} 个任务，通过率 ${passPercent}%，重试率 ${retryPercent}%，知识匹配率 ${knowledgePercent}%`;
+    return { period, snapshot, alerts, trends, summary };
+}
+/**
+ * 根据任务数量和类型粗略估算 Token 消耗。
+ * @param stateDir - 任务状态文件目录路径
+ * @returns 包含总估算 Token 数和按任务类型分组的估算明细
+ */
+export async function estimateCost(stateDir) {
+    debug("可观测性", "estimateCost() 估算成本, stateDir=%s", stateDir);
+    const tasks = await loadTasks(stateDir);
+    const byTaskType = {};
+    let total = 0;
+    for (const task of tasks) {
+        const taskType = task.classification?.task_type ?? "unknown";
+        const perTask = TOKEN_ESTIMATES[taskType] ?? DEFAULT_TOKEN_ESTIMATE;
+        byTaskType[taskType] = (byTaskType[taskType] ?? 0) + perTask;
+        total += perTask;
+    }
+    return { total_estimated_tokens: total, by_task_type: byTaskType };
+}
+// ── 成本预算检查 ──
+/** 从 ISO 日期字符串提取 YYYY-MM-DD 日期键 */
+function dateKey(iso) {
+    return iso.slice(0, 10); // YYYY-MM-DD
+}
+/**
+ * 计算指定天数前的零点时间戳（毫秒）。
+ * @param days - 回溯天数
+ * @returns 对应日期零点的时间戳
+ */
+function daysAgoMs(days) {
+    const d = new Date();
+    d.setHours(0, 0, 0, 0);
+    return d.getTime() - days * 24 * 60 * 60 * 1000;
+}
+/**
+ * 检查 Token 用量是否超出预算，生成超支或接近预算（>=80%）的告警。
+ * 分别检查日、周、月三个维度的预算。
+ * @param stateDir - 任务状态文件目录路径
+ * @param budget - 成本预算配置（含日/周/月 Token 限额）
+ * @returns 成本告警列表
+ */
+export async function checkCostBudget(stateDir, budget) {
+    debug("可观测性", "checkCostBudget() 开始执行");
+    const tasks = await loadTasks(stateDir);
+    const alerts = [];
+    const dayMap = new Map();
+    for (const task of tasks) {
+        const taskType = task.classification?.task_type ?? "unknown";
+        const perTask = TOKEN_ESTIMATES[taskType] ?? DEFAULT_TOKEN_ESTIMATE;
+        const day = dateKey(task.created_at);
+        dayMap.set(day, (dayMap.get(day) ?? 0) + perTask);
+    }
+    const today = dateKey(new Date().toISOString());
+    const todayTokens = dayMap.get(today) ?? 0;
+    // 周维度：最近 7 天（含今天），从 6 天前的零点开始计算
+    let weeklyTokens = 0;
+    for (const task of tasks) {
+        const taskMs = new Date(task.created_at).getTime();
+        if (taskMs >= daysAgoMs(6)) {
+            const taskType = task.classification?.task_type ?? "unknown";
+            weeklyTokens += TOKEN_ESTIMATES[taskType] ?? DEFAULT_TOKEN_ESTIMATE;
+        }
+    }
+    // 月维度：最近 30 天（含今天），从 29 天前的零点开始计算
+    let monthlyTokens = 0;
+    for (const task of tasks) {
+        const taskMs = new Date(task.created_at).getTime();
+        if (taskMs >= daysAgoMs(29)) {
+            const taskType = task.classification?.task_type ?? "unknown";
+            monthlyTokens += TOKEN_ESTIMATES[taskType] ?? DEFAULT_TOKEN_ESTIMATE;
+        }
+    }
+    // 检查单个时间周期的预算使用情况
+    // 检查单个时间周期的预算使用情况并生成告警
+    function checkPeriod(period, used, limit) {
+        if (limit <= 0)
+            return; // 未配置限额则跳过
+        const ratio = used / limit;
+        // 用量达到或超过预算 100% 时触发严重告警
+        if (ratio >= 1) {
+            alerts.push({
+                level: "critical",
+                period,
+                used,
+                limit,
+                message: `${period === "daily" ? "今日" : period === "weekly" ? "本周" : "本月"} token 用量已超出预算（${used.toLocaleString()} / ${limit.toLocaleString()}）`,
+            });
+            // 用量达到预算 80% 时触发预警（提前告警）
+        }
+        else if (ratio >= 0.8) {
+            alerts.push({
+                level: "warning",
+                period,
+                used,
+                limit,
+                message: `${period === "daily" ? "今日" : period === "weekly" ? "本周" : "本月"} token 用量已达预算 ${Math.round(ratio * 100)}%（${used.toLocaleString()} / ${limit.toLocaleString()}）`,
+            });
+        }
+    }
+    checkPeriod("daily", todayTokens, budget.daily_token_limit);
+    checkPeriod("weekly", weeklyTokens, budget.weekly_token_limit);
+    checkPeriod("monthly", monthlyTokens, budget.monthly_token_limit);
+    return alerts;
+    if (alerts.length > 0) {
+        debug("成本预算", "检测到 " + alerts.length + " 条预算告警");
+    }
+}
+/**
+ * 获取最近指定天数的每日 Token 用量趋势。
+ * 缺失的日期填充为 0，确保时间线连续。
+ * @param stateDir - 任务状态文件目录路径
+ * @param days - 回溯天数，默认 30 天
+ * @returns 按日期排列的每日 Token 消耗估算数组
+ */
+export async function getCostTrend(stateDir, days = 30) {
+    debug("可观测性", "getCostTrend() 获取成本趋势, stateDir=%s, days=%d", stateDir, days);
+    const tasks = await loadTasks(stateDir);
+    // 构建日期 → Token 估算值的映射
+    const dayMap = new Map();
+    const cutoffMs = daysAgoMs(days - 1);
+    for (const task of tasks) {
+        const taskMs = new Date(task.created_at).getTime();
+        if (taskMs < cutoffMs)
+            continue;
+        const taskType = task.classification?.task_type ?? "unknown";
+        const perTask = TOKEN_ESTIMATES[taskType] ?? DEFAULT_TOKEN_ESTIMATE;
+        const day = dateKey(task.created_at);
+        dayMap.set(day, (dayMap.get(day) ?? 0) + perTask);
+    }
+    // 填充缺失日期为 0，保证趋势图表连续
+    const result = [];
+    const now = new Date();
+    for (let i = days - 1; i >= 0; i--) {
+        const d = new Date(now);
+        d.setDate(d.getDate() - i);
+        const key = dateKey(d.toISOString());
+        result.push({
+            date: key,
+            estimated_tokens: dayMap.get(key) ?? 0,
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=observability.js.map