@ats-cx/cx-core 0.1.0

package/dist/providers/remote-project-provider.js

@@ -0,0 +1,167 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * 快照表：列 UIDPK（bigint 主键）/ PROJECT_UID / PROJECT_XML_DATA / CREATE_TIME。
+ *
+ * 两条 SQL 都按 UIDPK 升序取整组，不用 `LIMIT 1`：CREATE_TIME 无小数秒，文件名的序号后缀由记录在
+ * 同秒组内的位次决定，只取一行就无从得知位次——会把组内末条写成无后缀基名，与 `--history` 写的
+ * 组内首条撞名互相覆盖。最新一条改为「查出最新一秒的整组，落其中 UIDPK 最大的那条」，
+ * 两种模式因此共用同一套命名，同一条记录在哪种模式下都得到同一个文件名。
+ */
+const LATEST_SECOND_SQL = "SELECT UIDPK, PROJECT_UID, PROJECT_XML_DATA, CREATE_TIME FROM aprod_failed_project_info WHERE PROJECT_UID = ? AND CREATE_TIME = (SELECT MAX(CREATE_TIME) FROM aprod_failed_project_info WHERE PROJECT_UID = ?) ORDER BY UIDPK ASC";
+const HISTORY_SQL = "SELECT UIDPK, PROJECT_UID, PROJECT_XML_DATA, CREATE_TIME FROM aprod_failed_project_info WHERE PROJECT_UID = ? ORDER BY CREATE_TIME ASC, UIDPK ASC";
+/**
+ * 远端快照拉取：查 DB → 转 JSON → 落盘 `<projectHistoryDir>/<projectId>/<projectId>_<时间>.json`
+ * （同秒的第 2 条起带 `_02` 序号后缀，见 planSnapshots）。
+ *
+ * 逐 projectId 循环执行单项目 SQL（不用 CTE + ROW_NUMBER）：不依赖 MySQL 8，错误定位到单 id；
+ * pull 的 id 数量极小，N 次往返可忽略。
+ * 连接 / SQL 错误一律向上抛（由调用方转 exit 1），只有「查到 0 条」与「单条记录坏数据」降级为警告 / 失败记录。
+ */
+export function createRemoteProjectProvider(client, projectHistoryDir) {
+    async function pull(mode, projectIds) {
+        const projects = [];
+        const warnings = [];
+        for (const projectId of projectIds) {
+            const rows = mode === "latest"
+                ? await client.query(LATEST_SECOND_SQL, [projectId, projectId])
+                : await client.query(HISTORY_SQL, [projectId]);
+            const entry = { projectId, snapshotCount: 0, files: [], failures: [] };
+            projects.push(entry);
+            if (rows.length === 0) {
+                warnings.push(`项目 ${projectId} 未查到任何记录`);
+                continue;
+            }
+            // latest 查的是最新一秒的整组，只落其中最后写入的一条——但沿用它在组内的文件名。
+            const plans = planSnapshots(projectId, rows);
+            const selected = mode === "latest" ? [...plans].sort(byUidpk).slice(-1) : plans;
+            const written = new Set();
+            for (const plan of selected) {
+                if (plan.error !== "") {
+                    entry.failures.push(plan.error);
+                    continue;
+                }
+                const filePath = join(projectHistoryDir, projectId, plan.fileName);
+                // 防御性兜底：planSnapshots 保证同批文件名唯一，真撞上说明有 bug，
+                // 宁可少写一条并显式报错，也不静默覆盖让 snapshotCount 虚高。
+                if (written.has(filePath)) {
+                    entry.failures.push(`快照文件名重复，跳过写入避免覆盖: ${filePath}`);
+                    continue;
+                }
+                try {
+                    await writeSnapshot(filePath, plan.row);
+                }
+                catch (error) {
+                    entry.failures.push(messageOf(error));
+                    continue;
+                }
+                written.add(filePath);
+                entry.files.push(filePath);
+                entry.snapshotCount += 1;
+            }
+        }
+        return { projects, warnings };
+    }
+    return {
+        pullLatest: projectIds => pull("latest", projectIds),
+        pullHistory: projectIds => pull("history", projectIds),
+    };
+}
+/**
+ * 行 → 文件名。`CREATE_TIME` 是 timestamp（无小数秒），同秒多条记录很常见且内容各不相同，
+ * 只按时间命名会让后写的静默覆盖前一条，历史版本真丢。
+ *
+ * 同秒组内按 `UIDPK`（自增主键）升序定位次：第 1 条沿用无后缀命名，其后追加 `_02`、`_03`……
+ * - 位次只由 UIDPK 决定，不受 SQL 返回顺序与其他行是否落盘失败影响，同一批数据两次 pull 得到同样的文件名（幂等）。
+ *   代价是组内首条解析失败时目录里只有 `_02` 而无基名文件——宁可留空位，也不让其余行的文件名跟着漂移。
+ *   幂等依赖历史 SQL 既 SELECT 了 UIDPK 又按它排序：真缺 UIDPK 时 byUidpk 退化成保留返回顺序。
+ * - 字典序仍等于版本时间序（`.` 0x2E < `_` 0x5F，无后缀者排最前），本地快照 provider 靠 `readdir().sort()`
+ *   定版本序，存量文件与 `brief` / `diff-project` 的版本名消费方式都不受影响。
+ *   同秒超过 99 条时序号自然变 3 位，`_100` 会排到 `_11` 前面——仅该秒内排序降级，不丢数据（实测单秒最多 36 条）。
+ */
+function planSnapshots(projectId, rows) {
+    const plans = [];
+    const groups = new Map();
+    for (const row of rows) {
+        let timeKey;
+        try {
+            timeKey = formatCreateTime(row.CREATE_TIME);
+        }
+        catch (error) {
+            plans.push({ row, fileName: "", error: messageOf(error) });
+            continue;
+        }
+        const plan = { row, fileName: "", error: "" };
+        plans.push(plan);
+        const group = groups.get(timeKey);
+        if (group) {
+            group.push(plan);
+        }
+        else {
+            groups.set(timeKey, [plan]);
+        }
+    }
+    for (const [timeKey, group] of groups) {
+        [...group].sort(byUidpk).forEach((plan, index) => {
+            const suffix = index === 0 ? "" : `_${String(index + 1).padStart(2, "0")}`;
+            plan.fileName = `${projectId}_${timeKey}${suffix}.json`;
+        });
+    }
+    return plans;
+}
+/** UIDPK 缺失或非数值时视为相等，交给 sort 的稳定性保留原返回顺序。 */
+function byUidpk(left, right) {
+    const a = uidpkOf(left.row);
+    const b = uidpkOf(right.row);
+    if (a === undefined || b === undefined || a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function uidpkOf(row) {
+    if (row.UIDPK === undefined || row.UIDPK === null) {
+        return undefined;
+    }
+    const value = Number(row.UIDPK);
+    return Number.isFinite(value) ? value : undefined;
+}
+async function writeSnapshot(filePath, row) {
+    const data = await parseSnapshotData(String(row.PROJECT_XML_DATA ?? ""));
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(data, null, 2), "utf8");
+}
+/**
+ * 按「trim 后以 `<` 开头且以 `>` 结尾」判定 XML，否则按 JSON 解析；选中的分支失败即报错。
+ * 不做两个分支互相回退：形状判定互斥（以 `<` 开头结尾的串不可能是合法 JSON，反之亦然），
+ * 回退只会掩盖真实的解析错误。线上数据目前全是 JSON 字符串，XML 分支为防御性保留。
+ */
+async function parseSnapshotData(raw) {
+    const trimmed = raw.trim();
+    const looksXml = trimmed.startsWith("<") && trimmed.endsWith(">");
+    try {
+        return looksXml ? await parseXml(trimmed) : JSON.parse(trimmed);
+    }
+    catch (error) {
+        const format = looksXml ? "XML" : "JSON";
+        throw new Error(`PROJECT_XML_DATA 不是有效 ${format}: ${messageOf(error)}（前 80 字符: ${trimmed.slice(0, 80)}）`);
+    }
+}
+/** xml2js 动态 import：XML 是防御性分支，正常数据不该为它付加载成本。 */
+async function parseXml(raw) {
+    const { parseStringPromise } = await import("xml2js");
+    return (await parseStringPromise(raw, { explicitArray: false, ignoreAttrs: true, trim: true }));
+}
+/** `YYYY-MM-DD_HH-MM-SS`，本地时区；与存量快照文件名格式一致。 */
+function formatCreateTime(value) {
+    const date = value instanceof Date ? value : new Date(String(value ?? ""));
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`CREATE_TIME 无效，无法生成快照文件名（收到: ${String(value)}）`);
+    }
+    const pad = (part) => String(part).padStart(2, "0");
+    const day = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+    return `${day}_${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}`;
+}
+//# sourceMappingURL=remote-project-provider.js.map

package/dist/providers/source-provider.d.ts

@@ -0,0 +1,11 @@
+import type { SourceRepoBinding, SourceVersion } from "../types.js";
+export interface SourceProvider {
+    snapshotVersions(): SourceVersion[];
+}
+/**
+ * 源码仓库的 git 版本探针。
+ *
+ * 只负责在 `run new` 时抓每个仓库的 commit/branch/dirty 写进 `source-versions.json`，
+ * 供 `report.md` 头部统一声明版本漂移。源码检索本身交还宿主 Agent（ADR 0002）。
+ */
+export declare function createSourceProvider(repos: SourceRepoBinding[]): SourceProvider;

package/dist/providers/source-provider.js

@@ -0,0 +1,33 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+/**
+ * 源码仓库的 git 版本探针。
+ *
+ * 只负责在 `run new` 时抓每个仓库的 commit/branch/dirty 写进 `source-versions.json`，
+ * 供 `report.md` 头部统一声明版本漂移。源码检索本身交还宿主 Agent（ADR 0002）。
+ */
+export function createSourceProvider(repos) {
+    return {
+        snapshotVersions() {
+            return repos.map(repo => {
+                if (!repo.path || !existsSync(repo.path)) {
+                    return { repoId: repo.id, commit: null, branch: null, dirty: null, reachable: false };
+                }
+                try {
+                    const git = (...args) => execFileSync("git", ["-C", repo.path, ...args], { encoding: "utf8" }).trim();
+                    return {
+                        repoId: repo.id,
+                        commit: git("rev-parse", "HEAD"),
+                        branch: git("rev-parse", "--abbrev-ref", "HEAD"),
+                        dirty: git("status", "--porcelain").length > 0,
+                        reachable: true,
+                    };
+                }
+                catch {
+                    return { repoId: repo.id, commit: null, branch: null, dirty: null, reachable: true };
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=source-provider.js.map

package/dist/rules/engine.d.ts

@@ -0,0 +1,13 @@
+import type { AnnotatedEvent, DiagnosticRule, SuspiciousSignal } from "../types.js";
+/**
+ * 通用规则引擎。
+ *
+ * 注意这里的规则不直接判断某个 eventName，而是判断：
+ * - 是否是显式错误语义
+ * - 是否是状态变更语义
+ * - 是否是保存语义
+ * - 是否是进入/离开语义
+ *
+ * 这样规则可以跨事件复用。
+ */
+export declare function runDiagnosticRules(timeline: AnnotatedEvent[], rules: DiagnosticRule[]): SuspiciousSignal[];

package/dist/rules/engine.js

@@ -0,0 +1,213 @@
+import { describeStateChange, hasStateChange, isEnterEvent, isErrorEvent, isLeaveEvent, isSaveEvent, } from "../semantics/resolver.js";
+/**
+ * 通用规则引擎。
+ *
+ * 注意这里的规则不直接判断某个 eventName，而是判断：
+ * - 是否是显式错误语义
+ * - 是否是状态变更语义
+ * - 是否是保存语义
+ * - 是否是进入/离开语义
+ *
+ * 这样规则可以跨事件复用。
+ */
+export function runDiagnosticRules(timeline, rules) {
+    const signals = [];
+    for (const rule of rules) {
+        if (!rule.enabled) {
+            continue;
+        }
+        signals.push(...executeRule(rule, timeline));
+    }
+    return uniqBy(signals, signal => `${signal.ruleId}:${signal.type}:${signal.logTime}:${signal.eventName}`);
+}
+/**
+ * 按 rule.kind 分发到具体规则实现。
+ */
+function executeRule(rule, timeline) {
+    switch (rule.kind) {
+        case "explicit_error":
+            return detectExplicitErrorSignals(timeline, rule);
+        case "state_change_without_save":
+            return detectUnsavedStateChangeSignals(timeline, rule);
+        case "reentry_after_leave":
+            return detectReentrySignals(timeline, rule);
+        case "state_change_save_reentry":
+            return detectPersistedStateChangeSignals(timeline, rule);
+        default:
+            return [];
+    }
+}
+/**
+ * 规则一：显式报错类问题。
+ *
+ * 只要事件语义属于 error，或者 payload 明确带 message / stack，
+ * 就可以判定为高置信度失败线索。
+ */
+function detectExplicitErrorSignals(timeline, rule) {
+    const signals = [];
+    for (const item of timeline) {
+        const message = item.payload.message;
+        const stack = item.payload.stack;
+        if (!isErrorEvent(item.semantics) && !message && !stack) {
+            continue;
+        }
+        signals.push({
+            severity: resolveSeverity(rule, "high"),
+            ruleId: rule.id,
+            type: "explicit_error_signal",
+            eventName: item.eventName,
+            logTime: item.logTime,
+            reason: (typeof message === "string" ? message : null) ||
+                renderReason(rule, {
+                    eventName: item.eventName,
+                }, `事件 ${item.eventName} 具有显式失败语义，建议直接查看错误信息、调用栈和相关接口响应。`),
+        });
+    }
+    return signals;
+}
+/**
+ * 规则二：可能修改了状态，但离开前没有看到保存。
+ */
+function detectUnsavedStateChangeSignals(timeline, rule) {
+    const signals = [];
+    let lastStatefulEvent = null;
+    for (const item of timeline) {
+        if (hasStateChange(item.semantics, { includePossible: rule.includePossibleStateChange, includeCommit: false })) {
+            lastStatefulEvent = item;
+            continue;
+        }
+        if (isSaveEvent(item.semantics)) {
+            lastStatefulEvent = null;
+            continue;
+        }
+        if (isLeaveEvent(item.semantics) && lastStatefulEvent) {
+            signals.push({
+                severity: resolveStateChangeSeverity(rule, lastStatefulEvent.semantics.stateChange, "medium"),
+                ruleId: rule.id,
+                type: "state_change_without_save",
+                eventName: item.eventName,
+                logTime: item.logTime,
+                reason: renderReason(rule, {
+                    stateChangeLabel: describeStateChange(lastStatefulEvent.semantics),
+                    lastEventTime: lastStatefulEvent.logTime,
+                    lastEventName: lastStatefulEvent.eventName,
+                }, `最后一个 ${describeStateChange(lastStatefulEvent.semantics)} 是 ${lastStatefulEvent.logTime} 的 ${lastStatefulEvent.eventName}，但在离开页面前没有看到保存事件。`),
+            });
+            lastStatefulEvent = null;
+        }
+    }
+    return signals;
+}
+/**
+ * 规则三：离开后快速重进。
+ */
+function detectReentrySignals(timeline, rule) {
+    const signals = [];
+    for (let index = 0; index < timeline.length - 1; index += 1) {
+        const current = timeline[index];
+        const next = timeline[index + 1];
+        if (!isLeaveEvent(current.semantics) || !isEnterEvent(next.semantics)) {
+            continue;
+        }
+        const seconds = Math.max(0, Math.round((next.logTimestamp - current.logTimestamp) / 1000));
+        if (rule.maxGapSeconds !== null && seconds > rule.maxGapSeconds) {
+            continue;
+        }
+        signals.push({
+            severity: resolveSeverity(rule, "low"),
+            ruleId: rule.id,
+            type: "reentry_after_leave",
+            eventName: `${current.eventName} -> ${next.eventName}`,
+            logTime: current.logTime,
+            reason: renderReason(rule, {
+                gapSeconds: seconds,
+                leaveEventName: current.eventName,
+                enterEventName: next.eventName,
+            }, `用户在离开编辑器 ${seconds} 秒后再次进入，这通常意味着刷新、异常恢复或手动重开。`),
+        });
+    }
+    return signals;
+}
+/**
+ * 规则四：状态变更 -> 保存 -> 重进。
+ */
+function detectPersistedStateChangeSignals(timeline, rule) {
+    const signals = [];
+    for (let index = 0; index < timeline.length; index += 1) {
+        const current = timeline[index];
+        if (!hasStateChange(current.semantics, { includePossible: rule.includePossibleStateChange, includeCommit: false })) {
+            continue;
+        }
+        const laterEvents = timeline.slice(index + 1, index + 1 + rule.lookahead);
+        const saveIndex = laterEvents.findIndex(item => isSaveEvent(item.semantics));
+        if (saveIndex === -1) {
+            continue;
+        }
+        const reopenExists = laterEvents.slice(saveIndex + 1).some(item => isEnterEvent(item.semantics));
+        if (!reopenExists) {
+            continue;
+        }
+        signals.push({
+            severity: resolveStateChangeSeverity(rule, current.semantics.stateChange, "medium"),
+            ruleId: rule.id,
+            type: "state_change_save_reentry",
+            eventName: current.eventName,
+            logTime: current.logTime,
+            reason: renderReason(rule, {
+                stateChangeLabel: describeStateChange(current.semantics),
+                eventName: current.eventName,
+            }, `${describeStateChange(current.semantics)} ${current.eventName} 之后出现了保存，随后又重新进入编辑器。建议对比这个时间点前后的 project 版本，确认状态是否真正落盘。`),
+        });
+    }
+    return signals;
+}
+/**
+ * 解析规则严重级别，优先使用规则配置，缺失时回退到调用方默认值。
+ */
+function resolveSeverity(rule, fallbackSeverity) {
+    return rule.severity || fallbackSeverity;
+}
+/**
+ * 根据 stateChange 粒度覆盖严重级别。
+ */
+function resolveStateChangeSeverity(rule, stateChange, fallbackSeverity) {
+    return rule.severityByStateChange[stateChange] || rule.severity || fallbackSeverity;
+}
+/**
+ * 用规则模板渲染原因文案；没有模板时回退到代码内置文案。
+ */
+function renderReason(rule, variables, fallbackReason) {
+    const template = rule.reasonTemplates.default;
+    if (!template) {
+        return fallbackReason;
+    }
+    return formatTemplate(template, variables);
+}
+/**
+ * 执行简单的 `{key}` 模板替换。
+ */
+function formatTemplate(template, variables) {
+    return template.replace(/\{([A-Za-z0-9_]+)\}/g, (_match, key) => {
+        if (variables[key] === undefined || variables[key] === null) {
+            return "";
+        }
+        return String(variables[key]);
+    });
+}
+/**
+ * 按指定 key 去重，并保留第一次出现的项。
+ */
+function uniqBy(items, iteratee) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const key = iteratee(item);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(item);
+    }
+    return result;
+}
+//# sourceMappingURL=engine.js.map

package/dist/run/result-schema.d.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+export declare const diagnosisResultSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    runId: z.ZodString;
+    status: z.ZodEnum<["completed", "failed"]>;
+    diagnosisStatus: z.ZodEnum<["confirmed", "likely", "inconclusive", "not_a_bug"]>;
+    rootCauses: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        confidence: z.ZodEnum<["confirmed", "likely", "inconclusive"]>;
+        evidenceRefs: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        confidence: "confirmed" | "likely" | "inconclusive";
+        evidenceRefs: string[];
+    }, {
+        description: string;
+        confidence: "confirmed" | "likely" | "inconclusive";
+        evidenceRefs: string[];
+    }>, "many">;
+    confirmedFacts: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        evidenceRefs: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        evidenceRefs: string[];
+    }, {
+        description: string;
+        evidenceRefs: string[];
+    }>, "many">;
+    hypothesesRejected: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        reason: string;
+    }, {
+        description: string;
+        reason: string;
+    }>, "many">;
+    missingEvidence: z.ZodArray<z.ZodString, "many">;
+    recommendedNextActions: z.ZodArray<z.ZodString, "many">;
+    evidenceRefs: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    status: "completed" | "failed";
+    projectId: string;
+    evidenceRefs: string[];
+    runId: string;
+    diagnosisStatus: "confirmed" | "likely" | "inconclusive" | "not_a_bug";
+    rootCauses: {
+        description: string;
+        confidence: "confirmed" | "likely" | "inconclusive";
+        evidenceRefs: string[];
+    }[];
+    confirmedFacts: {
+        description: string;
+        evidenceRefs: string[];
+    }[];
+    hypothesesRejected: {
+        description: string;
+        reason: string;
+    }[];
+    missingEvidence: string[];
+    recommendedNextActions: string[];
+}, {
+    status: "completed" | "failed";
+    projectId: string;
+    evidenceRefs: string[];
+    runId: string;
+    diagnosisStatus: "confirmed" | "likely" | "inconclusive" | "not_a_bug";
+    rootCauses: {
+        description: string;
+        confidence: "confirmed" | "likely" | "inconclusive";
+        evidenceRefs: string[];
+    }[];
+    confirmedFacts: {
+        description: string;
+        evidenceRefs: string[];
+    }[];
+    hypothesesRejected: {
+        description: string;
+        reason: string;
+    }[];
+    missingEvidence: string[];
+    recommendedNextActions: string[];
+}>;
+export type DiagnosisResult = z.infer<typeof diagnosisResultSchema>;
+/**
+ * 校验诊断结论。除 schema 外还执行证据纪律：
+ * diagnosisStatus 为 confirmed 时，必须至少有一个根因，且 confirmed 级根因与
+ * 每条 confirmedFacts 都必须带证据引用。
+ *
+ * 注意：只校验证据引用非空，不校验证据 ID 的格式与来源真实性（见 ADR 0002）。
+ */
+export declare function validateDiagnosisResult(raw: unknown): {
+    ok: boolean;
+    result?: DiagnosisResult;
+    errors?: string[];
+};

package/dist/run/result-schema.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+const confidenceEnum = z.enum(["confirmed", "likely", "inconclusive"]);
+const rootCauseSchema = z.object({
+    description: z.string().min(1),
+    confidence: confidenceEnum,
+    evidenceRefs: z.array(z.string()),
+});
+export const diagnosisResultSchema = z.object({
+    projectId: z.string().min(1),
+    runId: z.string().min(1),
+    status: z.enum(["completed", "failed"]),
+    diagnosisStatus: z.enum(["confirmed", "likely", "inconclusive", "not_a_bug"]),
+    rootCauses: z.array(rootCauseSchema),
+    confirmedFacts: z.array(z.object({ description: z.string().min(1), evidenceRefs: z.array(z.string()) })),
+    hypothesesRejected: z.array(z.object({ description: z.string().min(1), reason: z.string() })),
+    missingEvidence: z.array(z.string()),
+    recommendedNextActions: z.array(z.string()),
+    evidenceRefs: z.array(z.string()),
+});
+/**
+ * 校验诊断结论。除 schema 外还执行证据纪律：
+ * diagnosisStatus 为 confirmed 时，必须至少有一个根因，且 confirmed 级根因与
+ * 每条 confirmedFacts 都必须带证据引用。
+ *
+ * 注意：只校验证据引用非空，不校验证据 ID 的格式与来源真实性（见 ADR 0002）。
+ */
+export function validateDiagnosisResult(raw) {
+    const parsed = diagnosisResultSchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, errors: parsed.error.issues.map(issue => `${issue.path.join(".")}: ${issue.message}`) };
+    }
+    const result = parsed.data;
+    if (result.diagnosisStatus === "confirmed") {
+        const errors = [];
+        if (result.rootCauses.length === 0) {
+            errors.push("confirmed 结论必须至少给出一个根因");
+        }
+        if (result.rootCauses.some(cause => cause.confidence === "confirmed" && cause.evidenceRefs.length === 0)) {
+            errors.push("confirmed 级根因必须提供证据引用（evidenceRefs 不能为空）");
+        }
+        if (result.confirmedFacts.some(fact => fact.evidenceRefs.length === 0)) {
+            errors.push("confirmed 结论的 confirmedFacts 必须逐条提供证据引用");
+        }
+        if (errors.length > 0) {
+            return { ok: false, errors };
+        }
+    }
+    return { ok: true, result };
+}
+//# sourceMappingURL=result-schema.js.map

package/dist/run/store.d.ts

@@ -0,0 +1,23 @@
+export interface RunInput {
+    projectId: string;
+    complaint: string;
+}
+export interface RunHandle {
+    runId: string;
+    runDir: string;
+    input: RunInput;
+}
+export declare function createRunDir(runsDir: string, input: RunInput): RunHandle;
+export declare function loadRun(runsDir: string, runId: string): RunHandle;
+export interface TraceEntry {
+    actor: "cli" | "agent";
+    command: string;
+    /** 已脱敏的参数：调用方保证不含 cookie/token/敏感 header。 */
+    args: Record<string, unknown>;
+    outputSummary: string;
+}
+export declare function appendTrace(runDir: string, entry: TraceEntry): void;
+export declare function writeArtifact(runDir: string, name: string, data: unknown): string;
+export declare function readArtifact<T>(runDir: string, name: string): T;
+export type StageName = "init_run" | "collect_context" | "precompute_evidence" | "investigate" | "finalize";
+export declare function writeStageStatus(runDir: string, stage: StageName, status: "completed" | "failed", detail?: string): void;

package/dist/run/store.js

@@ -0,0 +1,49 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export function createRunDir(runsDir, input) {
+    const now = new Date();
+    const stamp = [
+        now.getFullYear(),
+        String(now.getMonth() + 1).padStart(2, "0"),
+        String(now.getDate()).padStart(2, "0"),
+    ].join("") + "-" + [
+        String(now.getHours()).padStart(2, "0"),
+        String(now.getMinutes()).padStart(2, "0"),
+        String(now.getSeconds()).padStart(2, "0"),
+    ].join("");
+    const suffix = Math.random().toString(36).slice(2, 6);
+    const runId = `r-${stamp}-${suffix}`;
+    const runDir = join(runsDir, runId);
+    mkdirSync(join(runDir, "artifacts"), { recursive: true });
+    writeFileSync(join(runDir, "input.json"), JSON.stringify({ ...input, createdAt: now.toISOString() }, null, 2));
+    return { runId, runDir, input };
+}
+export function loadRun(runsDir, runId) {
+    const runDir = join(runsDir, runId);
+    if (!existsSync(join(runDir, "input.json"))) {
+        throw new Error(`run ${runId} 不存在于 ${runsDir}`);
+    }
+    const input = JSON.parse(readFileSync(join(runDir, "input.json"), "utf8"));
+    return { runId, runDir, input };
+}
+export function appendTrace(runDir, entry) {
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...entry });
+    appendFileSync(join(runDir, "trace.jsonl"), line + "\n");
+}
+export function writeArtifact(runDir, name, data) {
+    const filePath = join(runDir, "artifacts", name);
+    writeFileSync(filePath, JSON.stringify(data, null, 2));
+    return filePath;
+}
+export function readArtifact(runDir, name) {
+    return JSON.parse(readFileSync(join(runDir, "artifacts", name), "utf8"));
+}
+export function writeStageStatus(runDir, stage, status, detail = "") {
+    const filePath = join(runDir, "stage-status.json");
+    const current = existsSync(filePath)
+        ? JSON.parse(readFileSync(filePath, "utf8"))
+        : {};
+    current[stage] = { status, detail, at: new Date().toISOString() };
+    writeFileSync(filePath, JSON.stringify(current, null, 2));
+}
+//# sourceMappingURL=store.js.map