@ats-cx/cx-cli 0.1.0

package/dist/tools/create-run.js

@@ -0,0 +1,273 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { ApmRequestError, createApmConfigError, isApmConfigured, createFileLogProvider, createRunDir, createSemanticsResolver, diffProjectSnapshots, normalizeProjectSnapshot, runDiagnosticRules, writeArtifact, writeStageStatus, } from "@ats-cx/cx-core";
+import { defineTool } from "../contract.js";
+import { UserFacingError } from "../errors.js";
+const inputSchema = z.object({
+    projectId: z.string().min(1),
+    complaint: z.string().default(""),
+    logsFile: z.string().min(1).optional(),
+});
+function selectCoverageCategory(left, right) {
+    if (left === right)
+        return left;
+    if (left === "error" || right === "error")
+        return "error";
+    if (left === "unknown")
+        return right;
+    if (right === "unknown")
+        return left;
+    return [left, right].sort()[0];
+}
+/**
+ * 按 (eventName, source bucket) 聚合三级语义解析结果（spec 组件 B）：inferred 与 unknown 就是待策展队列。
+ * 类别也只在 bucket 内合并；error 优先于 unknown，其他冲突按稳定规则选择，避免日志顺序改变产物。
+ */
+function buildSemanticsCoverage(sessions) {
+    const explicitNames = new Set();
+    const pending = new Map();
+    for (const session of sessions) {
+        for (const event of session.events) {
+            if (event.semantics.source?.explicit) {
+                explicitNames.add(event.eventName);
+                continue;
+            }
+            const inferred = event.semantics.source?.inferred === true;
+            const buckets = pending.get(event.eventName) ?? new Map();
+            const entry = buckets.get(inferred) ?? {
+                count: 0,
+                category: event.semantics.category,
+                payloadKeys: new Set(),
+            };
+            entry.count += 1;
+            entry.category = selectCoverageCategory(entry.category, event.semantics.category);
+            for (const key of Object.keys(event.payload)) {
+                entry.payloadKeys.add(key);
+            }
+            buckets.set(inferred, entry);
+            pending.set(event.eventName, buckets);
+        }
+    }
+    const collect = (inferred) => [...pending.entries()]
+        .flatMap(([eventName, buckets]) => {
+        const value = buckets.get(inferred);
+        return value ? [[eventName, value]] : [];
+    })
+        .map(([eventName, value]) => ({
+        eventName,
+        count: value.count,
+        category: value.category,
+        payloadKeys: [...value.payloadKeys].sort(),
+    }))
+        // count 降序、同 count 按名升序；不截断（ADR 0002 判据 2：不替 Agent 做范围裁剪）
+        .sort((left, right) => right.count - left.count || left.eventName.localeCompare(right.eventName));
+    return {
+        explicitEventCount: explicitNames.size,
+        inferred: collect(true),
+        unknown: collect(false),
+    };
+}
+const CLOCK_SKEW_HINT_THRESHOLD_MINUTES = 30;
+const WHOLE_HOUR_TOLERANCE_MINUTES = 5;
+/**
+ * 计算两钟中位差并给出一行判读提示。只在 brief 出现（ADR 0005）：
+ * timeline/排序/证据引用一律不用 receivedTime。
+ */
+function buildClockSkew(events) {
+    const offsets = events
+        .filter(event => event.logTimestamp > 0 && event.receivedTimestamp > 0)
+        .map(event => (event.logTimestamp - event.receivedTimestamp) / 60_000)
+        .sort((left, right) => left - right);
+    if (offsets.length === 0) {
+        return { medianOffsetMinutes: null, hint: "日志源无 received_time，两钟差值判读不可用" };
+    }
+    const median = Math.round(offsets[Math.floor(offsets.length / 2)]);
+    if (Math.abs(median) < CLOCK_SKEW_HINT_THRESHOLD_MINUTES) {
+        return { medianOffsetMinutes: median, hint: null };
+    }
+    const remainder = Math.abs(median) % 60;
+    const nearWholeHour = remainder <= WHOLE_HOUR_TOLERANCE_MINUTES || remainder >= 60 - WHOLE_HOUR_TOLERANCE_MINUTES;
+    const sign = median > 0 ? "+" : "-";
+    const hint = nearWholeHour
+        ? `log_time 与 received_time 中位差约 ${sign}${Math.round(Math.abs(median) / 60)} 小时（接近整小时，疑似时区差）`
+        : `log_time 与 received_time 中位差约 ${sign}${Math.abs(median)} 分钟（零碎差值，疑似钟漂或上报缓冲）`;
+    return { medianOffsetMinutes: median, hint };
+}
+function buildLogTimeRange(events) {
+    let earliest = null;
+    let latest = null;
+    for (const event of events) {
+        if (!earliest || event.logTimestamp < earliest.logTimestamp)
+            earliest = event;
+        if (!latest || event.logTimestamp > latest.logTimestamp)
+            latest = event;
+    }
+    return { earliest: earliest?.logTime ?? null, latest: latest?.logTime ?? null };
+}
+function buildLogSourceFilter(body) {
+    if (!body)
+        return undefined;
+    const parts = ["type", "project_id", "log_time_start", "log_time_end"].flatMap(key => {
+        const value = body[key];
+        return typeof value === "string" || typeof value === "number" ? [`${key}=${value}`] : [];
+    });
+    return parts.length > 0 ? parts.join(" / ") : undefined;
+}
+function getMetaRequestBody(meta) {
+    if (typeof meta !== "object" || meta === null || Array.isArray(meta))
+        return undefined;
+    const request = meta.request;
+    if (typeof request !== "object" || request === null || Array.isArray(request))
+        return undefined;
+    const body = request.body;
+    return typeof body === "object" && body !== null && !Array.isArray(body)
+        ? body
+        : undefined;
+}
+function buildEvidenceIndex(sessions, diffs, history, signals) {
+    return {
+        logs: sessions.flatMap(session => session.events.map(event => ({
+            evidenceRef: `log:${event.sessionId}:${event.originalIndex}`,
+            sessionId: event.sessionId,
+            eventName: event.eventName,
+            logTime: event.logTime,
+        }))),
+        diffs: diffs.map(diff => ({
+            evidenceRef: `diff:${diff.before}-${diff.after}`,
+            before: diff.before,
+            after: diff.after,
+            summary: diff.summary,
+        })),
+        snapshots: history.map(item => ({
+            evidenceRef: `snapshot:${item.version}`,
+            version: item.version,
+            filePath: item.filePath,
+        })),
+        signals: signals.map(signal => ({
+            evidenceRef: `signal:${signal.ruleId}:${signal.eventName}:${signal.logTime}`,
+            ruleId: signal.ruleId,
+            severity: signal.severity,
+            eventName: signal.eventName,
+            logTime: signal.logTime,
+        })),
+    };
+}
+export const createRunTool = defineTool({
+    name: "create_run",
+    description: "创建诊断 run：拉取日志与项目快照、预计算语义标注/diff/可疑信号，返回 case 摘要",
+    inputSchema,
+    handler: async (input, context) => {
+        const complaint = input.complaint ?? "";
+        if (input.logsFile === undefined &&
+            context.config.logSource.type === "apm" &&
+            !isApmConfigured(context.config.apmProviderState)) {
+            throw createApmConfigError(context.config.apmProviderState);
+        }
+        const run = createRunDir(context.config.runsDir, { projectId: input.projectId, complaint });
+        writeFileSync(join(run.runDir, "config.snapshot.json"), JSON.stringify({ configDir: context.config.configDir, sourceRepos: context.sourceRepos }, null, 2));
+        writeFileSync(join(run.runDir, "artifacts", "hypotheses.jsonl"), "");
+        writeStageStatus(run.runDir, "init_run", "completed");
+        const missingEvidence = [];
+        // collect_context（spec §11：provider 失败不摧毁 run——标记失败阶段后抛出，已写产物保留）
+        const sourceVersions = context.sourceProvider.snapshotVersions();
+        writeFileSync(join(run.runDir, "source-versions.json"), JSON.stringify(sourceVersions, null, 2));
+        let logs;
+        let history;
+        try {
+            const logProvider = input.logsFile ? createFileLogProvider(input.logsFile) : context.logProvider;
+            logs = await logProvider.fetch(input.projectId);
+            history = await context.projectProvider.loadHistory(input.projectId);
+        }
+        catch (error) {
+            const detail = error instanceof ApmRequestError && error.kind === "incomplete"
+                ? `${error.message}；用 apm query --from/--to --out + run new --logs 收窄`
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            writeStageStatus(run.runDir, "collect_context", "failed", detail);
+            throw error;
+        }
+        if (history.length === 0) {
+            const message = [
+                `错误: 未找到项目 ${input.projectId} 的本地快照（${join(context.config.projectHistoryDir, input.projectId)}/ 为空或不存在）。`,
+                "请先拉取项目数据:",
+                `  cx-cli project pull ${input.projectId} --history`,
+            ].join("\n");
+            writeStageStatus(run.runDir, "collect_context", "failed", message);
+            throw new UserFacingError(message);
+        }
+        for (const version of sourceVersions) {
+            if (!version.reachable) {
+                missingEvidence.push(`源码仓库 ${version.repoId} 不可达，源码级证据缺失`);
+            }
+        }
+        const projectIdMatch = logs.normalized.events.reduce((counts, event) => {
+            counts[event.projectId === input.projectId ? "matched" : "other"] += 1;
+            return counts;
+        }, { matched: 0, other: 0 });
+        if (projectIdMatch.other > 0) {
+            console.error(`警告: ${projectIdMatch.other} 行 project_id 与 --projectId 不一致（--logs 文件可能来自 --item 三列 OR 或传错文件）`);
+        }
+        if (logs.normalized.eventCount === 0) {
+            if (logs.provenance.source === "file") {
+                missingEvidence.push("日志源无该项目事件；文件里无该项目事件，核对 project_id");
+            }
+            else if (logs.provenance.flush.attempted && logs.provenance.flush.ok === true) {
+                missingEvidence.push("日志源无该项目事件；或用 apm query --item <id> 对照三列 OR 是否命中");
+            }
+            else {
+                missingEvidence.push("日志源无该项目事件；同步失败，先 apm flush 再重跑 run new");
+            }
+        }
+        writeArtifact(run.runDir, "logs.source.json", { ...logs.provenance, projectIdMatch });
+        writeStageStatus(run.runDir, "collect_context", "completed");
+        // precompute_evidence
+        writeArtifact(run.runDir, "logs.normalized.json", logs.normalized);
+        const resolveSemantics = createSemanticsResolver(context.config.eventSemantics);
+        const annotatedSessions = logs.normalized.sessions.map(session => ({
+            ...session,
+            events: session.events.map((event) => ({ ...event, semantics: resolveSemantics(event) })),
+        }));
+        writeArtifact(run.runDir, "sessions.annotated.json", annotatedSessions);
+        const signals = annotatedSessions.flatMap(session => runDiagnosticRules(session.events, context.config.diagnosticRules));
+        writeArtifact(run.runDir, "signals.json", signals);
+        const historyIndex = history.map(item => ({ version: item.version, filePath: item.filePath }));
+        writeArtifact(run.runDir, "project-history.index.json", historyIndex);
+        const diffs = [];
+        for (let index = 0; index + 1 < history.length; index += 1) {
+            const diff = diffProjectSnapshots(history[index].data, history[index + 1].data);
+            writeArtifact(run.runDir, `project-diff.${history[index].version}-${history[index + 1].version}.json`, diff);
+            diffs.push({ before: history[index].version, after: history[index + 1].version, summary: diff.summary });
+        }
+        writeArtifact(run.runDir, "project-diffs.index.json", diffs);
+        writeArtifact(run.runDir, "evidence.index.json", buildEvidenceIndex(annotatedSessions, diffs, historyIndex, signals));
+        writeArtifact(run.runDir, "project.latest.normalized.json", normalizeProjectSnapshot(history[history.length - 1].data));
+        writeStageStatus(run.runDir, "precompute_evidence", "completed");
+        const logSourceFilter = buildLogSourceFilter(logs.provenance.request?.body ?? getMetaRequestBody(logs.provenance.meta));
+        const allEvents = annotatedSessions.flatMap(session => session.events);
+        const brief = {
+            projectId: input.projectId,
+            complaint,
+            sessionCount: annotatedSessions.length,
+            sessionIds: annotatedSessions.map(session => session.sessionId),
+            eventCount: logs.normalized.eventCount,
+            logTimeRange: buildLogTimeRange(allEvents),
+            clockSkew: buildClockSkew(allEvents),
+            projectVersions: history.map(item => item.version),
+            suspiciousSignals: signals,
+            semanticsCoverage: buildSemanticsCoverage(annotatedSessions),
+            sourceRepos: sourceVersions.map(version => ({ id: version.repoId, reachable: version.reachable })),
+            missingEvidence,
+            logSource: {
+                source: logs.provenance.source,
+                ...(logs.provenance.file ? { file: logs.provenance.file } : {}),
+                ...(logSourceFilter ? { filter: logSourceFilter } : {}),
+                ...projectIdMatch,
+            },
+        };
+        writeArtifact(run.runDir, "brief.json", brief);
+        return { runId: run.runId, brief };
+    },
+});
+//# sourceMappingURL=create-run.js.map

package/dist/tools/log-tools.d.ts

@@ -0,0 +1,68 @@
+import type { AnnotatedEvent, SessionGroup } from "@ats-cx/cx-core";
+import type { CaseBrief } from "./create-run.js";
+type AnnotatedSession = Omit<SessionGroup, "events"> & {
+    events: AnnotatedEvent[];
+};
+/**
+ * 时间线/检索的输出条目：只保留调查需要的字段 + 证据 ID，控制上下文体积。
+ * 默认只给 payloadKeys；`payload: true` 时原样附带 payload——没有这个口子，Agent 会绕过 CLI
+ * 直接 jq 读 artifacts 里的 sessions.annotated.json（真实 case 已出现），证据引用就断了。
+ */
+export interface TimelineItem {
+    evidenceRef: string;
+    logTime: string;
+    eventName: string;
+    category: string;
+    stateChange: string;
+    payloadKeys: string[];
+    message: string | null;
+    payload?: Record<string, unknown>;
+}
+/** session 摘要：时间跨度 + 身份字段，够 Agent 分清「客户本人的会话」和「客服/研发复现的会话」。 */
+export interface SessionSummary {
+    sessionId: string;
+    startedAt: string;
+    endedAt: string;
+    eventCount: number;
+    /** 去重后的 userId（空值剔除）。 */
+    userIds: string[];
+    /** 去重后的 `<deviceType>/<osType>`，如 `pc/Windows`。 */
+    devices: string[];
+    /** 去重后的路由（page_url 的 hash 路径），反映会话进了哪些产品页。 */
+    routes: string[];
+}
+type SessionLike = Pick<AnnotatedSession, "sessionId" | "startedAt" | "endedAt" | "eventCount"> & {
+    events: Array<Pick<AnnotatedEvent, "userId" | "device" | "route">>;
+};
+/**
+ * 按 startedAt 升序：sessions.annotated.json 的顺序来自日志源分组，与时间序无关，
+ * 真实 case 里客服 8/25 的会话排在客户会话前面，Agent 要自己重排才能看出先后。
+ */
+export declare function summarizeSessions(sessions: SessionLike[]): SessionSummary[];
+export declare const getCaseBriefTool: import("../contract.js").ToolDefinition<{
+    runId: string;
+}, CaseBrief>;
+export declare const listSessionsTool: import("../contract.js").ToolDefinition<{
+    runId: string;
+}, {
+    sessions: SessionSummary[];
+}>;
+export declare const getTimelineTool: import("../contract.js").ToolDefinition<{
+    runId: string;
+    sessionId: string;
+    payload?: boolean | undefined;
+    category?: string | undefined;
+    cursor?: number | undefined;
+    pageSize?: number | undefined;
+}, import("../budget.js").Page<TimelineItem>>;
+export declare const searchLogsTool: import("../contract.js").ToolDefinition<{
+    runId: string;
+    eventName?: string | undefined;
+    payload?: boolean | undefined;
+    cursor?: number | undefined;
+    pageSize?: number | undefined;
+    payloadKey?: string | undefined;
+    from?: string | undefined;
+    to?: string | undefined;
+}, import("../budget.js").Page<TimelineItem>>;
+export {};

package/dist/tools/log-tools.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { loadRun, readArtifact } from "@ats-cx/cx-core";
+import { defineTool } from "../contract.js";
+import { paginate } from "../budget.js";
+function toTimelineItem(event, includePayload) {
+    const item = {
+        evidenceRef: `log:${event.sessionId}:${event.originalIndex}`,
+        logTime: event.logTime,
+        eventName: event.eventName,
+        category: event.semantics.category,
+        stateChange: event.semantics.stateChange,
+        payloadKeys: Object.keys(event.payload),
+        message: typeof event.payload.message === "string" ? event.payload.message : null,
+    };
+    if (includePayload) {
+        item.payload = event.payload;
+    }
+    return item;
+}
+function uniqueSorted(values) {
+    return [...new Set(values.filter(value => value.length > 0))].sort();
+}
+/**
+ * 按 startedAt 升序：sessions.annotated.json 的顺序来自日志源分组，与时间序无关，
+ * 真实 case 里客服 8/25 的会话排在客户会话前面，Agent 要自己重排才能看出先后。
+ */
+export function summarizeSessions(sessions) {
+    return sessions
+        .map(session => ({
+        sessionId: session.sessionId,
+        startedAt: session.startedAt,
+        endedAt: session.endedAt,
+        eventCount: session.eventCount,
+        userIds: uniqueSorted(session.events.map(event => event.userId)),
+        devices: uniqueSorted(session.events.map(event => [event.device.deviceType, event.device.osType].filter(Boolean).join("/"))),
+        routes: uniqueSorted(session.events.map(event => event.route)),
+    }))
+        .sort((left, right) => left.startedAt.localeCompare(right.startedAt) || left.sessionId.localeCompare(right.sessionId));
+}
+function loadSessions(runsDir, runId) {
+    const run = loadRun(runsDir, runId);
+    return readArtifact(run.runDir, "sessions.annotated.json");
+}
+export const getCaseBriefTool = defineTool({
+    name: "get_case_brief",
+    description: "读取 run 的 case 摘要：可疑信号、可用证据清单、缺失证据",
+    inputSchema: z.object({ runId: z.string().min(1) }),
+    handler: async (input, context) => {
+        const run = loadRun(context.config.runsDir, input.runId);
+        return readArtifact(run.runDir, "brief.json");
+    },
+});
+export const listSessionsTool = defineTool({
+    name: "list_sessions",
+    description: "列出 run 内标准化后的日志 session 摘要",
+    inputSchema: z.object({ runId: z.string().min(1) }),
+    handler: async (input, context) => {
+        return { sessions: summarizeSessions(loadSessions(context.config.runsDir, input.runId)) };
+    },
+});
+export const getTimelineTool = defineTool({
+    name: "get_timeline",
+    description: "读取某 session 的事件时间线，支持分页与语义类别过滤",
+    inputSchema: z.object({
+        runId: z.string().min(1),
+        sessionId: z.string().min(1),
+        category: z.string().optional(),
+        payload: z.boolean().optional(),
+        cursor: z.number().int().min(0).optional(),
+        pageSize: z.number().int().min(1).max(200).optional(),
+    }),
+    handler: async (input, context) => {
+        const sessions = loadSessions(context.config.runsDir, input.runId);
+        const session = sessions.find(candidate => candidate.sessionId === input.sessionId);
+        if (!session) {
+            throw new Error(`session ${input.sessionId} 不存在，先用 list_sessions 查看可用 session`);
+        }
+        const filtered = input.category
+            ? session.events.filter(event => event.semantics.category === input.category)
+            : session.events;
+        const includePayload = input.payload === true;
+        return paginate(filtered.map(event => toTimelineItem(event, includePayload)), { cursor: input.cursor, pageSize: input.pageSize });
+    },
+});
+export const searchLogsTool = defineTool({
+    name: "search_logs",
+    description: "按事件名 / payload key / 时间范围跨 session 检索日志事件",
+    inputSchema: z.object({
+        runId: z.string().min(1),
+        eventName: z.string().optional(),
+        payloadKey: z.string().optional(),
+        from: z.string().optional(),
+        to: z.string().optional(),
+        payload: z.boolean().optional(),
+        cursor: z.number().int().min(0).optional(),
+        pageSize: z.number().int().min(1).max(200).optional(),
+    }),
+    handler: async (input, context) => {
+        const sessions = loadSessions(context.config.runsDir, input.runId);
+        const all = sessions.flatMap(session => session.events);
+        const filtered = all.filter(event => {
+            if (input.eventName && event.eventName !== input.eventName)
+                return false;
+            if (input.payloadKey && !(input.payloadKey in event.payload))
+                return false;
+            if (input.from && event.logTimestamp < Date.parse(input.from))
+                return false;
+            if (input.to && event.logTimestamp > Date.parse(input.to))
+                return false;
+            return true;
+        });
+        const includePayload = input.payload === true;
+        return paginate(filtered.map(event => toTimelineItem(event, includePayload)), { cursor: input.cursor, pageSize: input.pageSize });
+    },
+});
+//# sourceMappingURL=log-tools.js.map

package/dist/tools/project-tools.d.ts

@@ -0,0 +1,82 @@
+import type { NormalizedProject, ProjectDiffResult } from "@ats-cx/cx-core";
+import { paginate } from "../budget.js";
+declare function buildSnapshotSummary(project: NormalizedProject): {
+    projectMeta: Record<string, unknown>;
+    pageCount: number;
+    elementCount: number;
+    pageCollectionCounts: Record<string, number>;
+    elementTypeCounts: Record<string, number>;
+};
+type PageSectionDiffs = ProjectDiffResult["pageSectionDiffs"];
+/**
+ * 页级属性变化（如 pages[n].type）只存在于 pageSectionDiffs，
+ * 不会出现在元素级 changedElements 里。stdout 若丢弃该结构，
+ * “只有页面 type 变了”的 diff 会被误读成“没有变化”（客诉 23862 案例）。
+ * 这里只透传 summary + changedItems（限量）；各区域的增删明细
+ * 已由顶层 addedPages / removedPages 承载，不重复输出。
+ */
+declare function shapeSectionDiff(section: PageSectionDiffs["pages"]): {
+    key: string;
+    label: string;
+    beforeCount: number;
+    afterCount: number;
+    summary: {
+        addedItemCount: number;
+        removedItemCount: number;
+        changedItemCount: number;
+    };
+    changedItems: import("@ats-cx/cx-core/dist/diff/project-diff.js").ChangedSectionItemDiff[];
+};
+declare function shapeCoverSectionDiff(section: PageSectionDiffs["cover"]): {
+    key: string;
+    label: string;
+    beforeCount: number;
+    afterCount: number;
+    summary: {
+        changedFieldCount: number;
+        addedItemCount: number;
+        removedItemCount: number;
+        changedItemCount: number;
+    };
+    changedFields: import("@ats-cx/cx-core/dist/diff/project-diff.js").FieldChange[];
+    changedItems: import("@ats-cx/cx-core/dist/diff/project-diff.js").ChangedSectionItemDiff[];
+};
+export declare const getProjectSnapshotTool: import("../contract.js").ToolDefinition<{
+    runId: string;
+    version: string;
+    cursor?: number | undefined;
+    pageSize?: number | undefined;
+    detail?: "pages" | "summary" | "elements" | undefined;
+}, {
+    version: string;
+    evidenceRef: string;
+    summary: ReturnType<typeof buildSnapshotSummary>;
+    pages?: ReturnType<typeof paginate<NormalizedProject["pages"][number]>>;
+    elements?: ReturnType<typeof paginate<NormalizedProject["elements"][number]>>;
+}>;
+export declare const diffProjectVersionsTool: import("../contract.js").ToolDefinition<{
+    runId: string;
+    before: string;
+    after: string;
+    cursor?: number | undefined;
+    pageSize?: number | undefined;
+}, {
+    evidenceRef: string;
+    summary: ProjectDiffResult["summary"];
+    pageSectionDiffs: {
+        pages: ReturnType<typeof shapeSectionDiff>;
+        cover: ReturnType<typeof shapeCoverSectionDiff>;
+        frontFlysheet: ReturnType<typeof shapeSectionDiff>;
+        backFlysheet: ReturnType<typeof shapeSectionDiff>;
+        edge: ReturnType<typeof shapeSectionDiff>;
+    };
+    changedProjectMeta: ProjectDiffResult["changedProjectMeta"];
+    addedPages: ProjectDiffResult["addedPages"];
+    removedPages: ProjectDiffResult["removedPages"];
+    changedElements: ProjectDiffResult["changedElements"];
+    addedElements: ProjectDiffResult["addedElements"];
+    removedElements: ProjectDiffResult["removedElements"];
+    truncated: boolean;
+    hint: string | null;
+}>;
+export {};

package/dist/tools/project-tools.js

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { diffProjectSnapshots, loadRun, normalizeProjectSnapshot, readArtifact, writeArtifact, } from "@ats-cx/cx-core";
+import { defineTool } from "../contract.js";
+import { paginate } from "../budget.js";
+const MAX_LIST_ITEMS = 50;
+function loadHistoryIndex(runDir) {
+    return readArtifact(runDir, "project-history.index.json");
+}
+function findVersionEntry(index, version) {
+    const entry = index.find(item => item.version === version);
+    if (!entry) {
+        const available = index.map(item => item.version).join(", ") || "（无）";
+        throw new Error(`project 版本 ${version} 不存在，可用版本：${available}`);
+    }
+    return entry;
+}
+function loadRawSnapshot(entry) {
+    return JSON.parse(readFileSync(entry.filePath, "utf8"));
+}
+function buildSnapshotSummary(project) {
+    return {
+        projectMeta: project.projectMeta,
+        pageCount: project.pageCount,
+        elementCount: project.elementCount,
+        pageCollectionCounts: project.pageCollectionCounts,
+        elementTypeCounts: project.elementTypeCounts,
+    };
+}
+function sliceList(items) {
+    return items.slice(0, MAX_LIST_ITEMS);
+}
+/**
+ * 页级属性变化（如 pages[n].type）只存在于 pageSectionDiffs，
+ * 不会出现在元素级 changedElements 里。stdout 若丢弃该结构，
+ * “只有页面 type 变了”的 diff 会被误读成“没有变化”（客诉 23862 案例）。
+ * 这里只透传 summary + changedItems（限量）；各区域的增删明细
+ * 已由顶层 addedPages / removedPages 承载，不重复输出。
+ */
+function shapeSectionDiff(section) {
+    return {
+        key: section.key,
+        label: section.label,
+        beforeCount: section.beforeCount,
+        afterCount: section.afterCount,
+        summary: section.summary,
+        changedItems: sliceList(section.changedItems),
+    };
+}
+function shapeCoverSectionDiff(section) {
+    return {
+        key: section.key,
+        label: section.label,
+        beforeCount: section.beforeCount,
+        afterCount: section.afterCount,
+        summary: section.summary,
+        changedFields: section.changedFields,
+        changedItems: sliceList(section.changedItems),
+    };
+}
+export const getProjectSnapshotTool = defineTool({
+    name: "get_project_snapshot",
+    description: "读取指定版本的 project 快照摘要，可选分页返回页面或元素明细",
+    inputSchema: z.object({
+        runId: z.string().min(1),
+        version: z.string().min(1),
+        detail: z.enum(["summary", "pages", "elements"]).optional(),
+        cursor: z.number().int().min(0).optional(),
+        pageSize: z.number().int().min(1).max(200).optional(),
+    }),
+    handler: async (input, context) => {
+        const run = loadRun(context.config.runsDir, input.runId);
+        const index = loadHistoryIndex(run.runDir);
+        const entry = findVersionEntry(index, input.version);
+        const project = normalizeProjectSnapshot(loadRawSnapshot(entry), entry.filePath);
+        const detail = input.detail ?? "summary";
+        const output = {
+            version: input.version,
+            evidenceRef: `snapshot:${input.version}`,
+            summary: buildSnapshotSummary(project),
+        };
+        if (detail === "pages") {
+            output.pages = paginate(project.pages, { cursor: input.cursor, pageSize: input.pageSize });
+        }
+        if (detail === "elements") {
+            output.elements = paginate(project.elements, { cursor: input.cursor, pageSize: input.pageSize });
+        }
+        return output;
+    },
+});
+export const diffProjectVersionsTool = defineTool({
+    name: "diff_project_versions",
+    description: "对比两个 project 版本，优先读取预计算 diff，支持 changedElements 分页",
+    inputSchema: z.object({
+        runId: z.string().min(1),
+        before: z.string().min(1),
+        after: z.string().min(1),
+        cursor: z.number().int().min(0).optional(),
+        pageSize: z.number().int().min(1).max(200).optional(),
+    }),
+    handler: async (input, context) => {
+        const run = loadRun(context.config.runsDir, input.runId);
+        const artifactName = `project-diff.${input.before}-${input.after}.json`;
+        const artifactPath = join(run.runDir, "artifacts", artifactName);
+        let diff;
+        if (existsSync(artifactPath)) {
+            diff = readArtifact(run.runDir, artifactName);
+        }
+        else {
+            const index = loadHistoryIndex(run.runDir);
+            const beforeEntry = findVersionEntry(index, input.before);
+            const afterEntry = findVersionEntry(index, input.after);
+            diff = diffProjectSnapshots(loadRawSnapshot(beforeEntry), loadRawSnapshot(afterEntry));
+            writeArtifact(run.runDir, artifactName, diff);
+        }
+        const changedPage = paginate(diff.changedElements, { cursor: input.cursor, pageSize: input.pageSize });
+        return {
+            evidenceRef: `diff:${input.before}-${input.after}`,
+            summary: diff.summary,
+            pageSectionDiffs: {
+                pages: shapeSectionDiff(diff.pageSectionDiffs.pages),
+                cover: shapeCoverSectionDiff(diff.pageSectionDiffs.cover),
+                frontFlysheet: shapeSectionDiff(diff.pageSectionDiffs.frontFlysheet),
+                backFlysheet: shapeSectionDiff(diff.pageSectionDiffs.backFlysheet),
+                edge: shapeSectionDiff(diff.pageSectionDiffs.edge),
+            },
+            changedProjectMeta: diff.changedProjectMeta,
+            addedPages: sliceList(diff.addedPages),
+            removedPages: sliceList(diff.removedPages),
+            changedElements: changedPage.items,
+            addedElements: sliceList(diff.addedElements),
+            removedElements: sliceList(diff.removedElements),
+            truncated: changedPage.truncated,
+            hint: changedPage.hint,
+        };
+    },
+});
+//# sourceMappingURL=project-tools.js.map