@dsh-edge/dsh-edge-agent 0.0.0-stage → 0.1.1

package/lib/dsh-adapter/llm-trace-store.js

@@ -0,0 +1,205 @@
+/**
+ * llm-trace-store — §7.133 LLM request/response trace 的**正文存储**
+ *
+ * ## 为什么正文不进 audit 行
+ *
+ * §7.118 的 trace 走 `ctx.logger.info` → ops log 文件。而 Edge 面板的数据
+ * 源是 **audit-log**（edge-context-view 的 fold）—— 两条通路不相通，所以
+ * 面板看不到任何 request/response 正文。
+ *
+ * 修法有两条路：
+ *
+ *   A. 正文直接进 audit 行 —— 面板立刻能看到，但单轮主对话的 request
+ *      正文实测 **22.5 万字符**（promptLength=225630）。几十轮之后，
+ *      面板的常驻内存和渲染压力线性膨胀。
+ *   B. 面板只放**索引**（每次调用一行摘要），正文按需拉取 —— 索引行是
+ *      几十字节的标量，正文存在独立的 store 里，点开才取。
+ *
+ * 选 B。这与本仓一贯的纪律一致（§7.107「面板不得断言与审计数据相矛盾
+ * 的事」、§7.129「宁可漏显示也不能显示一件没发生过的事」）：面板常驻
+ * 的永远是**便宜的索引**，正文是**要才取**。
+ *
+ * ## store 的形状
+ *
+ * `traceId` → { kind: 'REQ' | 'RESP', caller?, trace }。ring buffer：
+ * 条数与总字节双上限 —— 单条 trace 正文上限 2 万字符（trace 模块自己
+ * 已按 maxChars 截断），所以 64 条 ≈ 1.3 MB 上界。
+ *
+ * ## 谁来写
+ *
+ * adapter（主对话出网）+ prompt-guard（安检）+ intent-router（分类器）。
+ * 三处都经 `emitTrace()` —— 它同时落 **audit 索引行**（进面板）与
+ * **正文**（进本 store）。
+ *
+ * 检测调用的标记沿用 §7.132 的 `edgeInternalCaller`：安检 = prompt-guard，
+ * 分类器 = intent-classifier，主对话没有这个字段。面板据此把「检测调用」
+ * 与「主对话出网」分开显示。
+ *
+ * @module dsh-edge-agent/llm-trace-store
+ */
+/** 默认值：64 条 / 2 MB。 */
+export const DEFAULT_TRACE_STORE_OPTIONS = {
+    maxEntries: 64,
+    maxBytes: 2 * 1024 * 1024,
+};
+/** 一条 trace 的粗略字节数（够用即可，不追求精确）。 */
+function approxBytes(value) {
+    try {
+        return JSON.stringify(value)?.length ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * trace 正文存储。
+ *
+ * 纯内存 —— 进程退出即消失，这是对的：正文是**当轮**的观测数据，不是
+ * 审计记录（审计记录在 audit.plain.jsonl 里，且只存标量）。
+ */
+export class LlmTraceStore {
+    entries = new Map();
+    order = [];
+    bytes = 0;
+    opts;
+    constructor(options = DEFAULT_TRACE_STORE_OPTIONS) {
+        this.opts = options;
+    }
+    /** 存一条 trace，返回它的 id（调用方拿去写索引行）。 */
+    put(id, entry) {
+        if (this.entries.has(id)) {
+            // 同 id 重写（理论上不会）：先扣掉旧的字节数。
+            this.bytes -= approxBytes(this.entries.get(id)?.trace);
+            this.entries.set(id, entry);
+            this.bytes += approxBytes(entry.trace);
+            return;
+        }
+        this.entries.set(id, entry);
+        this.order.push(id);
+        this.bytes += approxBytes(entry.trace);
+        this.evict();
+    }
+    /** 取一条 trace；不存在返回 undefined。 */
+    get(id) {
+        return this.entries.get(id);
+    }
+    /** 当前条数（面板显示「已记录 N 次调用」用）。 */
+    size() {
+        return this.entries.size;
+    }
+    /** 丢掉最旧的直到双双回到上限内。 */
+    evict() {
+        while (this.order.length > 0
+            && (this.entries.size > this.opts.maxEntries || this.bytes > this.opts.maxBytes)) {
+            const oldest = this.order.shift();
+            if (oldest === undefined)
+                break;
+            const removed = this.entries.get(oldest);
+            this.entries.delete(oldest);
+            this.bytes -= approxBytes(removed?.trace);
+            if (this.bytes < 0)
+                this.bytes = 0;
+        }
+    }
+}
+/* ── trace id ───────────────────────────────────────────────────────────── */
+/** trace id 的进程内计数器。 */
+let traceSeq = 0;
+/**
+ * §7.133: 生成 trace id。
+ *
+ * 单调计数 + 时间戳 —— 同一进程内唯一，且排序有意义（面板按时间排）。
+ */
+export function formatTraceId(seq, ts = Date.now()) {
+    return `t${ts.toString(36)}-${seq.toString(36)}`;
+}
+/** §7.133: 取下一个 trace id（进程内单调）。 */
+export function nextTraceId() {
+    return formatTraceId(traceSeq++);
+}
+/* ── call id（REQ/RESP 配对键）────────────────────────────────────────────── */
+/** call id 的进程内计数器。 */
+let callSeq = 0;
+/**
+ * §7.134: 生成 call id —— **一次 LLM 往返**的配对键。
+ *
+ * ## 为什么需要它
+ *
+ * §7.133 的索引行里，REQ 与 RESP 各自有独立的 `traceId`，于是面板上一次
+ * 调用显示成**两行不相干的条目** —— 主人在 §7.134 里要求「请求和响应成对
+ * 显示，上面是请求下面是响应」。配对需要一个跨 REQ/RESP 的共同键。
+ *
+ * ## 键的粒度：一次 `stream()` = 一个 call
+ *
+ * - local adapter：一次 `stream()` 一发一收，天然一对。
+ * - cloud adapter（直连）：`traceRequest` 在**重试循环之前**只调一次，
+ *   而 `traceResponse` 有三个出口（network error / HTTP error / 成功）。
+ *   重试时可能出现「一次失败 RESP + 一次成功 RESP」—— 它们共用同一个
+ *   callId，面板取**最后一个** RESP（那才是这次调用的最终结果）。
+ * - jev（裸 fetch）：REQ/RESP 在同一个方法内。
+ *
+ * ## 用 `options` 对象身份当键
+ *
+ * 宿主每次 `stream()` 传一个新的 `options` 对象，而 REQ 与 RESP 拿到的是
+ * **同一个**对象引用 —— 所以 `WeakMap<options, callId>` 就能把两半配上，
+ * 且不需要改 `traceResponse` 的三个调用点的签名。
+ *
+ * `WeakMap` 不会泄漏：`options` 被回收，条目随之消失。
+ */
+const callIds = new WeakMap();
+/** §7.134: 取一个新的 call id（进程内单调）。 */
+export function nextCallId() {
+    return `c${callSeq++}`;
+}
+/**
+ * §7.134: 取这次调用的 call id（第一次调用时创建，之后复用）。
+ *
+ * 传入的不是对象时（理论上不会发生）退化成「每次一个新 call id」——
+ * 宁可配不上，也不把两个不相干的调用错配成一对。
+ */
+export function callIdFor(options) {
+    if (options === null || typeof options !== 'object') {
+        return nextCallId();
+    }
+    const existing = callIds.get(options);
+    if (existing !== undefined)
+        return existing;
+    const id = nextCallId();
+    callIds.set(options, id);
+    return id;
+}
+/** 进程内唯一的 store 实例。 */
+let singleton;
+/** §7.133: 取进程内的 trace store（不存在则创建）。 */
+export function getTraceStore() {
+    if (singleton === undefined)
+        singleton = new LlmTraceStore();
+    return singleton;
+}
+/**
+ * 把 store 注册成 cordis service（名字固定为 `llmTraceStore`）。
+ *
+ * 独立于 plugin 的 apply() —— 由**首个使用者**惰性创建并注册，这样
+ * 不需要在 cordis.patch.yml 里加一行（那个 patch row 的形状门禁很严）。
+ * 注册是 best-effort：ctx 不是 plugin-level proxy 时静默跳过，写入方照常
+ * 用模块单例。
+ */
+export function provideTraceStore(ctx) {
+    const store = getTraceStore();
+    const c = ctx;
+    try {
+        const existing = typeof c.get === 'function' ? c.get('llmTraceStore') : undefined;
+        if (existing !== undefined && existing !== null)
+            return existing;
+    }
+    catch { /* not provided yet — fall through to register */ }
+    try {
+        if (typeof c.provide === 'function')
+            c.provide('llmTraceStore', store);
+    }
+    catch {
+        // 提供失败（ctx 不是 plugin-level proxy）→ 调用方降级，trace 正文不存，
+        // 但索引行与 ops log 照旧（面板仍能看到「调了几次、多大、多久」）。
+    }
+    return store;
+}

package/lib/dsh-adapter/llm-trace.d.ts

@@ -0,0 +1,450 @@
+/**
+ * llm-trace — 详细的 LLM request / response 追踪，写进 ops log。
+ *
+ * ## 为什么需要这个模块
+ *
+ * 现状（§7.118, 2026-10-26）：adapters 只在 ops log 里记**长度**——
+ * `promptLen=121853 systemLen=225 resultLen=5006`。真正想看"到底发了什么、
+ * 回了什么"的时候，唯一去处是把 `DSH_EDGE_LOG_LEVEL` 降到 `debug`，而
+ * `LLM_MESSAGES` / `LLM_RESPONSE_TEXT` 那两条全量 dump 才会出现：
+ *
+ *   - 全量 dump 没有脱敏 → 用户原文、工具回显、可能夹带的凭据直接落盘；
+ *   - 全量 dump 没有截断 → 一条 120KB 的 prompt 能撑爆一行日志；
+ *   - `debug` 级别默认被压制 → 运维默认看不到，而需要看的人往往是在出事之后。
+ *
+ * 这个模块把"详细"拆成三个**可独立关闭**的维度，并给每一维加上硬边界：
+ *
+ *   1. **脱敏**（`redactPii` / `redactSecrets`）——PII 走 `pii-utils` 的
+ *      10 类规则，凭据走本模块自己的密钥掩码（`pii-utils` 的 api-key 规则
+ *      匹配不到 `sk-cp-` / `tvly-` 这类带前缀的厂商密钥，见
+ *      `SECRET_PATTERNS`）。
+ *   2. **截断**（`maxChars` / `maxMessages`）——每个字段独立上限，且**截断
+ *      必须显式可见**（`truncated: true` + `…[+N chars]`），绝不让"日志里
+ *      看起来是完整的"成为可能。
+ *   3. **分级**（`includeRequest` / `includeResponse`）——只要 request 或
+ *      只要 response，各自可关。
+ *
+ * ## 落盘位置
+ *
+ * 走 `ctx.logger.info` —— 即 ops log 的默认级别。**不是** debug：运维在
+ * 出事后 tail 的是 ops log，不是 debug 日志。
+ *
+ * ## 安全边界
+ *
+ * - 本模块**不**写明文密钥：`authorization` 头、`apiKey` 参数一律不进 trace。
+ * - 本模块**不**改变任何出网行为：它只在本地组装一个日志对象。
+ * - 本模块对畸形输入**永不抛错**：trace 是观测手段，不能把主链路带崩。
+ *
+ * @module dsh-edge-agent/llm-trace
+ */
+import type { EdgeConfig } from './edge-config.js';
+import type { StoredTrace, TraceCaller } from './llm-trace-store.js';
+/**
+ * LLM trace 的行为开关。落在 `config/edge.json` 的 `audit.llmTrace` 段
+ * （§7.102「只有一个配置文件」——bundle patch 不再读 process.env）。
+ */
+export interface LlmTraceConfig {
+    /** 总开关。false 时 adapters 完全不构造 trace。 */
+    enabled: boolean;
+    /** 是否记录 request（messages + system + 参数）。 */
+    includeRequest: boolean;
+    /** 是否记录 response（content + tool calls + finish reason）。 */
+    includeResponse: boolean;
+    /** 单个文本字段的最大保留字符数。0 = 不截断（不推荐）。 */
+    maxChars: number;
+    /** request 里最多保留多少条 message。 */
+    maxMessages: number;
+    /**
+     * §7.144: **完整请求体 / 响应体**快照的字符上限。
+     *
+     * 为什么要单独一个上限：`maxChars` 是给「单条 message 正文」用的（2000 足够看清
+     * 上下文），而 body 快照装的是**真正发出去的那一坨**（system + 全部 message +
+     * 工具表 + 参数；jev 那种还有整份分类体系）。主对话实测 promptLength 22.5 万
+     * 字符，按 2000 截就只剩一句话 —— 面板上看到的与实际发出去的对不上。
+     *
+     * 20000 字符 ≈ 20KB/条，store 的 64 条 / 2MB 双上限仍然成立。超出时**显式标注**
+     * 截断了多少（`truncated: true` + `…[+N chars]`），绝不假装完整。
+     */
+    maxBodyChars: number;
+    /** 是否做 PII 脱敏（pii-utils 的 10 类规则）。 */
+    redactPii: boolean;
+    /** 是否做凭据掩码（本模块的 SECRET_PATTERNS）。 */
+    redactSecrets: boolean;
+}
+/**
+ * 出厂默认。
+ *
+ * `maxChars=2000` 的取舍：一条 message 的正文通常在几百字，2000 足够看清
+ * 上下文；整轮 12 条 message × 2000 字 ≈ 24KB 一行，日志文件按 50MB 轮转，
+ * 完全可控。想看全量请走 `DSH_EDGE_LOG_LEVEL=debug` 的旧通道，不要把这个值
+ * 调到很大 —— 那是拿磁盘换眼睛。
+ */
+export declare const DEFAULT_LLM_TRACE_CONFIG: LlmTraceConfig;
+/**
+ * 从 `config/edge.json` 解析 trace 配置。
+ *
+ * 缺省逐字段回落到 `DEFAULT_LLM_TRACE_CONFIG`；`maxChars<=0` 视为"不截断"
+ * 但会在 trace 里标注 `truncated:false`，让读日志的人知道这是显式选择。
+ */
+export declare function resolveLlmTraceConfig(cfg?: EdgeConfig): LlmTraceConfig;
+/**
+ * 凭据字面量掩码（不依赖 pii-utils）。
+ *
+ * `pii-utils` 的 `api-key` 规则是
+ * `sk-(?:proj-|ant-|live-|test-|org-)?[a-zA-Z0-9]{20,}`，它**匹配不到**
+ * 厂商自定义前缀的密钥：`sk-cp-…`（MiniMax）在 `cp-` 处断了，且下一段含
+ * `_` 也不在字符类里；`tvly-…`（Tavily）、`sk-ws-…`（DashScope）同理。
+ * 实测 `config/edge.json` 里的三把真 key 全部逃逸。
+ *
+ * 所以这里独立覆盖"厂商前缀 + 通用形态"两类，并加两条**收敛条件**避免误伤
+ * 普通英文词：
+ *
+ *   - 厂商前缀密钥要求"长度 ≥16 **且** 至少含一个数字"。真密钥几乎必然带
+ *     数字；而 `key-representation`、`api-key-description` 这类正常词不含
+ *     数字，不会被误掩。字符类放宽到 `[A-Za-z0-9._-]`（含 `.`），否则
+ *     DashScope 的 `sk-ws-EXAMPLE0.dot0.…`（JWS 风格带点）会在第一个
+ *     点处断掉而逃逸。
+ *   - 另加一条全大写形态（`tvly-PLACEHOLDER_REPLACE_ME`），这类占位符不含
+ *     数字但仍是凭据位。
+ */
+export declare const SECRET_PATTERNS: Array<{
+    name: string;
+    pattern: RegExp;
+}>;
+/** 掩码后的固定占位符。 */
+export declare const SECRET_MASK = "[REDACTED]";
+export interface SecretMaskResult {
+    text: string;
+    /** 命中的规则名（去重）。 */
+    hits: string[];
+}
+/**
+ * 把文本里的凭据字面量替换成 `SECRET_MASK`。
+ *
+ * 顺序有意义：先打标签式（`apiKey=…`），再打 `Bearer`，最后打裸厂商前缀 ——
+ * 否则 `Bearer sk-cp-xxx` 会被前两条先吃掉，留下一截尾巴。
+ */
+export declare function maskSecrets(text: string): SecretMaskResult;
+export interface TraceText {
+    /** 实际写入日志的文本。 */
+    text: string;
+    /** 截断前的原始长度。 */
+    length: number;
+    /** 是否发生了截断。 */
+    truncated: boolean;
+}
+/**
+ * 按字符数截断，**显式标注**溢出了多少。
+ *
+ * 不用 `…` 单字符收尾 —— 它和原文里的省略号没法区分。统一用
+ * `…[+N chars]`，`grep` 得到的就是真的。
+ */
+export declare function truncateForLog(text: string, maxChars: number): TraceText;
+/**
+ * 对一段要进日志的文本走完整条链：凭据掩码 → PII 脱敏 → 截断。
+ *
+ * 顺序同样有讲究：先掩码再脱敏，避免 PII 规则把密钥的一部分改写成别的形态
+ * 而逃过掩码；截断放最后，保证掩码与脱敏作用在**完整**文本上（否则密钥可能
+ * 恰好落在被切掉的那一段里……不对，那样反而安全了，但 PII 的部分掩码会因
+ * 截断而失配。结论：先处理完再截，语义最直观）。
+ */
+export declare function sanitizeTraceText(text: string, cfg: LlmTraceConfig): TraceText;
+/**
+ * 把任意 body 序列化成**可安全记录**的文本。
+ *
+ * 三个坑：
+ *   - **循环引用** → `JSON.stringify` 直接抛 `TypeError`。body 里出现循环
+ *     （宿主 options 被塞回 body 这类）就会把观测路径变成故障源。
+ *   - **BigInt** → 同样抛。
+ *   - **不可序列化的值**（函数 / Symbol）→ `JSON.stringify` 会静默丢掉，
+ *     让人以为"没发这个字段"。用 replacer 把它们替换成占位符，**显式**告诉
+ *     读日志的人「这里有个记不住的值」，而不是让它凭空消失。
+ */
+export declare function serializeTraceBody(value: unknown): string;
+/**
+ * body 快照的脱敏 + 截断。
+ *
+ * 走与正文同一条链（凭据掩码 → PII 脱敏 → 截断），只是上限换成
+ * `maxBodyChars`（body 比单条 message 大得多，按 2000 截就没意义了）。
+ */
+export declare function buildBodySnapshot(value: unknown, config: LlmTraceConfig): TraceText | undefined;
+/** 一条 message 的 trace 视图。 */
+export interface LlmMessageTrace {
+    index: number;
+    role: string;
+    /** `source.kind`（`tool` / `user` / …），能区分"工具回显"和"用户输入"。 */
+    kind?: string;
+    /**
+     * §7.131: `source.provider` —— 产出这条 assistant 消息的 provider 路由。
+     * 出网裁剪（cloud-egress）按它把会话历史切成「云段 / 本地段」，所以把它
+     * 也透出到 trace 里：operator 一眼能看出「这段历史是本地池的还是云端的」。
+     */
+    provider?: string;
+    /** 正文原始长度。 */
+    length: number;
+    /** 正文（已脱敏 + 截断）。 */
+    text?: TraceText;
+}
+export interface LlmRequestTrace {
+    sessionId: string;
+    provider: string;
+    model: string;
+    baseUrl?: string;
+    /** 实际发出的 message 条数（不是 trace 里保留的条数）。 */
+    messageCount: number;
+    /** trace 里因 maxMessages 截掉了几条。 */
+    droppedMessages: number;
+    /** 全部 message 正文的总长度（未截断前）。 */
+    promptLength: number;
+    system?: TraceText;
+    messages: LlmMessageTrace[];
+    /** 本次请求带的工具名（不含 schema）。 */
+    tools?: string[];
+    /**
+     * §7.144: **真正发出去的那一坨**（完整请求体的 JSON 快照）。
+     *
+     * 为什么必须有它：上面的 `system` / `messages` / `tools` 只是请求体的**投影**，
+     * 而实际 body 里还有投影装不下的东西 —— jev 的整份分类体系（questions.*）、
+     * adapter 的 `chat_template_kwargs` / `reasoning_effort` / 工具 schema ……
+     * 主人现场问的就是这个：「request 里只发了那段 system 吗？」（答案：不是，
+     * 但 trace 当时只**记**了那两段，面板上看不出真相）。
+     *
+     * 脱敏 + 截断照旧（凭据 → PII → 截断），上限独立（`maxBodyChars`）。
+     */
+    body?: TraceText;
+    params?: {
+        temperature?: number;
+        maxTokens?: number;
+        stream?: boolean;
+    };
+}
+/** 构造 request trace 时的输入。 */
+export interface LlmRequestTraceInput {
+    sessionId: string;
+    provider: string;
+    model: string;
+    baseUrl?: string;
+    system?: string;
+    messages: Array<{
+        role: string;
+        content: unknown;
+        source?: {
+            kind?: string;
+            provider?: string;
+        };
+    }>;
+    tools?: Array<{
+        name?: string;
+        function?: {
+            name?: string;
+        };
+    }>;
+    /**
+     * §7.144: **实际发出的请求体**（原样对象）—— 记进 `trace.body`。
+     *
+     * 传字符串时按「已经序列化好的正文」处理（jev 的裸 fetch 直接给 body 对象，
+     * 而某些路径手里只有一段文本）。
+     */
+    rawBody?: unknown;
+    params?: LlmRequestTrace['params'];
+    config: LlmTraceConfig;
+}
+/**
+ * 把 `options.messages` 的 content 摊平成纯文本。
+ *
+ * dsh-llm 的 `Message.content` 有两种形态：content-block 数组（`{type:'text',
+ * text}`）和裸字符串。两种都要认，否则一半消息在 trace 里是空的。
+ */
+export declare function messageContentToText(content: unknown): string;
+/**
+ * 构造 request trace。
+ *
+ * 保留**最后** `maxMessages` 条 message（而不是前 `maxMessages` 条）：多轮
+ * 对话里真正决定这次请求的是最近几轮，开头的 system 指令已经被压进
+ * `system` 字段了。
+ */
+export declare function buildRequestTrace(input: LlmRequestTraceInput): LlmRequestTrace;
+export interface LlmToolCallTrace {
+    id?: string;
+    name: string;
+    arguments?: TraceText;
+}
+export interface LlmResponseTrace {
+    sessionId: string;
+    provider: string;
+    model: string;
+    /** 第几次尝试（重试计数从 1 开始）。 */
+    attempt?: number;
+    durationMs?: number;
+    finishReason?: string;
+    /** 助手正文（已脱敏 + 截断）。 */
+    content?: TraceText;
+    toolCalls: LlmToolCallTrace[];
+    /**
+     * §7.144: **完整响应体**快照（上游真正回来的东西）。
+     *
+     * `content` + `toolCalls` 是响应体的**投影**；投影装不下的部分（jev 的
+     * `usage` / `answers` 全量结构、上游的原始错误体、SSE 帧里的额外字段）
+     * 只有完整 body 才有。主人要「请求和响应记录完全」，这一栏就是那个"完全"。
+     */
+    body?: TraceText;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    /** 上游错误信息（已截断）。 */
+    error?: string;
+}
+export interface LlmResponseTraceInput {
+    sessionId: string;
+    provider: string;
+    model: string;
+    attempt?: number;
+    durationMs?: number;
+    finishReason?: string;
+    content?: string;
+    toolCalls?: Array<{
+        id?: string;
+        name: string;
+        arguments?: string;
+    }>;
+    /**
+     * §7.144: **完整响应体**（原样对象或已经序列化好的文本）。
+     *
+     * jev 的响应是一整段 JSON（`answers` / `usage` 都在里面），adapter 的响应
+     * 是「正文 + tool_calls + finish_reason」的组装体 —— 两者都传进来，面板上
+     * 才看得到完整往返。
+     */
+    rawBody?: unknown;
+    usage?: LlmResponseTrace['usage'];
+    error?: string;
+    config: LlmTraceConfig;
+}
+/** 构造 response trace。 */
+export declare function buildResponseTrace(input: LlmResponseTraceInput): LlmResponseTrace;
+/**
+ * 把 trace 压成**单行**字符串。
+ *
+ * ops log 的 `formatLine` 会把换行折成 `⏎`，所以这里自己保证单行：
+ * `JSON.stringify` 已经把字符串内的换行转义成 `\n`，但仍可能出现裸的
+ * 控制字符（U+2028/2029 等），统一替换掉，避免日志文件出现"一行日志占了
+ * 三行物理行"的破事。
+ */
+export declare function formatTraceLine(tag: string, trace: unknown): string;
+/**
+ * §7.133: trace 的**索引行**（进 Edge 面板）+ **正文**（按需拉取）。
+ *
+ * §7.118 的 trace 只走 `ctx.logger.info` → ops log 文件，而 Edge 面板的
+ * 数据源是 audit-log —— 两条通路不相通，面板看不到任何 request/response。
+ *
+ * 这里把一次调用拆成两半：
+ *
+ *   - **索引行**（`llm.trace.index`）：几十字节的标量摘要，进 audit 行，
+ *     于是面板能列出「这一轮调了哪几次 LLM、各自多大、多久」。
+ *   - **正文**：完整的 trace（12 条 message 的正文 / response 的正文与
+ *     tool calls），存在 `LlmTraceStore` 里，点开才取。
+ *
+ * 为什么不把正文直接塞进 audit 行：单轮主对话的 request 正文实测 **22.5 万
+ * 字符**，几十轮后面板常驻内存线性膨胀。索引 + 按需拉取是本仓一贯的
+ * 纪律（§7.107 / §7.129：宁可漏显示，也不能显示一件没发生过的事）。
+ */
+/** 索引行的 payload（全部是标量，可安全进面板）。 */
+export interface TraceIndexPayload {
+    /** 与 store 里的正文对应。 */
+    traceId: string;
+    /** REQ = 请求，RESP = 响应。 */
+    kind: 'REQ' | 'RESP';
+    provider: string;
+    model: string;
+    /**
+     * §7.147：这次调用属于哪个会话。
+     *
+     * 没有就是**没有这个键** —— 索引行于是落全局桶（面板标它「全局信号」）。
+     * 载荷里带 sessionId 才是会话行（`turn >= 0`），路由面板才能说「这一轮」。
+     * 实测：本仓 195 条 `llm.trace.index` **无一带** sessionId ⇒ 路由面板此前
+     * 结构上不可能归属任何一轮。
+     */
+    sessionId?: string;
+    /** §7.132：内部调用标记；undefined = 主对话出网。 */
+    caller?: string;
+    /** 请求：实际发出的 message 条数 / 正文总长 / 因 maxMessages 丢掉几条。 */
+    messageCount?: number;
+    droppedMessages?: number;
+    promptLength?: number;
+    /** 响应：助手正文长度 / tool call 数 / 用时 / finish reason。 */
+    contentLength?: number;
+    toolCallCount?: number;
+    durationMs?: number;
+    finishReason?: string;
+    /** 出错时的原因。 */
+    error?: string;
+    /**
+     * 本次请求带的工具数。
+     *
+     * §7.132 的判据：主对话恒带 30+ 件工具，一切内部调用（安检 / 分类器 /
+     * 宿主会话标题生成）**一件都不带**。索引行带上这个数，面板就能把
+     * 「没有 caller 标记、也没带工具」的调用认成**宿主的内部调用**而不是
+     * 冒充主对话出网。
+     */
+    toolCount?: number;
+    /** 本条 trace 的正文总字节（面板可据此提示「点开看 N KB」）。 */
+    bodyBytes?: number;
+    /** 底座 URL —— 判断这一轮发去了哪。 */
+    baseUrl?: string;
+    /**
+     * §7.134: **一次 LLM 往返**的配对键。
+     *
+     * REQ 与 RESP 各有自己的 `traceId`（正文存储的键），但同一次往返的两半
+     * 共用这个 `callId` —— 面板据此把「请求 / 响应」配成一对，上下排列。
+     */
+    callId?: string;
+}
+/**
+ * 构造索引行 payload。
+ *
+ * 从 trace 对象里**提取标量**——不复制正文。正文另存 store。
+ */
+export declare function buildTraceIndex(traceId: string, kind: 'REQ' | 'RESP', trace: unknown, caller?: string, extra?: {
+    toolCount?: number;
+    callId?: string;
+}): TraceIndexPayload;
+/** emitTrace 需要的最小依赖面。 */
+export interface TraceSink {
+    /** audit-log 的 log() —— 索引行走这里。 */
+    log(entry: {
+        level: 'debug' | 'info' | 'warn' | 'error' | 'security';
+        kind: string;
+        source: string;
+        payload: Record<string, unknown>;
+    }): Promise<unknown>;
+    /** 正文存储 —— 正文走这里（可缺省：那就只有 ops log 的老通路）。 */
+    store?: {
+        put(id: string, entry: StoredTrace): void;
+    };
+    /** ops log 的 logger —— 保持 §7.118 的老通路不变。 */
+    logger?: {
+        info?: (msg: string) => void;
+    };
+    /** 生成 trace id（测试可注入固定值）。 */
+    nextTraceId?: () => string;
+}
+/**
+ * §7.133: 一次 LLM 调用的**统一出口**。
+ *
+ * 三条通路同时写：
+ *   1. ops log（§7.118 的老行为，`LLM_REQUEST` / `LLM_RESPONSE` 单行）
+ *   2. audit 索引行（`llm.trace.index`）→ Edge 面板列出这次调用
+ *   3. 正文 store（`LlmTraceStore`）→ 面板点开时取
+ *
+ * 检测调用（安检 / 分类器）经 `caller` 标出来 —— §7.132 的
+ * `edgeInternalCaller` 是同一个标记体系。**标记的来源是 options**：
+ * adapter 调 `emitTrace` 时把 `options` 传进来，由 `internalCallerOf()`
+ * 读出标记。所以检测调用的 trace 与主对话的 trace 走的是**同一段代码**，
+ * 不存在「检测调用忘了记」的第二套实现。
+ */
+export declare function emitTrace(sink: TraceSink, kind: 'REQ' | 'RESP', tag: string, trace: unknown, caller?: TraceCaller, extra?: {
+    toolCount?: number;
+    callId?: string;
+}): string | undefined;
+//# sourceMappingURL=llm-trace.d.ts.map

package/lib/dsh-adapter/llm-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-trace.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/llm-trace.ts"],"names":[],"mappings":"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"}