koishi-plugin-chatluna-studio 1.0.0

package/lib/model-evidence/index.d.ts

@@ -0,0 +1,15 @@
+import type { ModelEvidenceProjection, ModelEvidenceSlice } from './types';
+export * from './types';
+export { countMessageCharacters, countToolCallCharacters, countToolDefinitionCharacters, } from './metrics';
+/**
+ * 模型证据投影的唯一对外入口。也是唯一从请求体读取协议结构的地方。
+ *
+ * 输入只有一条模型请求记录的证据切片（请求体、响应原文、响应 transport 格式）。
+ * provider、URL、生命周期状态、HTTP 状态、空间归属、耗时、最终用量、模型名称
+ * 与原始请求体的字段数都不参与协议识别，它们继续由模型请求记录与现有读取 module 拥有：
+ * 模型名称是采集那一刻观察到的记录事实，字段数是原始 JSON 事实，两者都不是协议事实。
+ *
+ * 协议识别完全由内部 shape-driven adapter 完成；调用方不注册也不选择具体 adapter。
+ * 投影每次处理当前可用证据，不做全局缓存，也不深拷贝原始子树。
+ */
+export declare function projectModelEvidence(slice: ModelEvidenceSlice): ModelEvidenceProjection;

package/lib/model-evidence/metrics.d.ts

@@ -0,0 +1,11 @@
+import type { ModelEvidenceMessage, ModelEvidenceToolCall, ModelEvidenceToolDefinition } from './types';
+/**
+ * 证据字符数度量。
+ *
+ * 请求组成图与分析卡片头部必须使用同一个公式，否则同一条证据会在两个视图里显示不同字符数。
+ * 每项只统计它自己能证明的内容：消息不含工具调用参数，工具调用只算参数，工具定义算整段声明。
+ */
+export declare function countMessageCharacters(message: ModelEvidenceMessage): number;
+export declare function countToolCallCharacters(call: ModelEvidenceToolCall): number;
+export declare function countToolDefinitionCharacters(definition: ModelEvidenceToolDefinition): number;
+export declare function serializedLength(value: unknown): number;

package/lib/model-evidence/request.d.ts

@@ -0,0 +1,7 @@
+import type { ModelEvidenceDiagnostic, ModelEvidenceMessage, ModelEvidenceToolDefinition } from './types';
+export interface RequestEvidence {
+    messages: ModelEvidenceMessage[];
+    toolDefinitions: ModelEvidenceToolDefinition[];
+    diagnostics: ModelEvidenceDiagnostic[];
+}
+export declare function projectRequestEvidence(body: unknown): RequestEvidence;

package/lib/model-evidence/response.d.ts

@@ -0,0 +1,7 @@
+import type { ModelEvidenceDiagnostic, ModelEvidenceResponseEvent, ModelEvidenceTransport } from './types';
+export interface ResponseEvidence {
+    transport: ModelEvidenceTransport;
+    events: ModelEvidenceResponseEvent[];
+    diagnostics: ModelEvidenceDiagnostic[];
+}
+export declare function projectResponseEvidence(raw: string | undefined, format: 'json' | 'text' | 'sse' | undefined): ResponseEvidence;

package/lib/model-evidence/shared.d.ts

@@ -0,0 +1,37 @@
+import type { ModelEvidenceContentPart, ModelEvidenceRegion, ModelEvidenceSource } from './types';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function stringValue(value: unknown): string | undefined;
+export declare function stringifyValue(value: unknown): string;
+export declare function source(region: ModelEvidenceRegion, path: readonly string[], value: unknown): ModelEvidenceSource;
+/**
+ * 证据身份由区域、语义种类和原始结构路径派生。
+ *
+ * 不使用角色内序号：同一份原始证据在轨迹、组成图和分析视图里必须得到同一个 id，
+ * 而角色内序号会随折叠条件、会话聚合范围和分组顺序变化。
+ * 语义种类参与身份，让同一个父节点上的消息与工具调用不会互相覆盖。
+ */
+export declare function evidenceId(region: ModelEvidenceRegion, kind: string, path: readonly string[]): string;
+export declare function semanticText(parts: readonly ModelEvidenceContentPart[]): string;
+/** 通用（OpenAI / Anthropic / AI SDK）内容分片归一化，保留原始顺序与多模态种类。 */
+export declare function normalizeContentParts(value: unknown): ModelEvidenceContentPart[];
+/** Gemini part 归一化：inlineData / fileData 与 OpenAI 的多模态字段完全不同。 */
+export declare function normalizeGeminiPart(value: unknown): ModelEvidenceContentPart[];
+/** AI SDK 工具输出是 typed 值（`{type:'json'|'text', value}`），不能直接 stringify 整个包装。 */
+export declare function normalizeToolOutput(value: unknown): string;
+/**
+ * 读取显式调用标识。
+ *
+ * 只认专门表示“配对到哪次调用”的字段。裸 `id` 不在其中：消息、Responses item 和 AI SDK part
+ * 都带自己的条目 id，把条目 id 当调用标识会凭空造出工具调用与工具结果的配对关系，
+ * 而领域约定要求缺少显式调用标识时不做任何推断配对。
+ */
+export declare function readCallId(value: Record<string, unknown>): string | undefined;
+/**
+ * 读取工具调用/工具结果对象自身的调用标识。
+ *
+ * 仅当传入记录本身就是调用或结果对象时才可用：OpenAI `tool_calls[i]`、Anthropic `tool_use`、
+ * Gemini `functionCall` / `functionResponse` 的 `id` 就是调用标识本身。
+ * 传入消息或 item 包装对象会退化成按条目 id 推断配对，是错误用法。
+ */
+export declare function readCallObjectId(value: Record<string, unknown>): string | undefined;
+export declare function readToolName(value: Record<string, unknown>): string | undefined;

package/lib/model-evidence/transport.d.ts

@@ -0,0 +1,13 @@
+import type { ModelEvidenceDiagnostic, ModelEvidenceTransport } from './types';
+/** 一个待语义解释的响应 payload。`streaming` 说明它来自 SSE 分片而不是完整响应体。 */
+export interface ResponsePayload {
+    path: readonly string[];
+    value: unknown;
+    streaming: boolean;
+}
+export interface ResponseTransportEvidence {
+    transport: ModelEvidenceTransport;
+    payloads: ResponsePayload[];
+    diagnostics: ModelEvidenceDiagnostic[];
+}
+export declare function parseResponseTransport(raw: string | undefined, format: 'json' | 'text' | 'sse' | undefined): ResponseTransportEvidence;

package/lib/model-evidence/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 模型证据投影的对外契约。
+ *
+ * 这里只描述“从原始模型证据能证明什么”，不描述任何展示目标、DOM、排序或交互状态。
+ * 调用方（模型请求轨迹、模型请求对话视图）只依赖本文件的类型和 `projectModelEvidence` 一个入口。
+ */
+/** 证据所属区域。请求体与响应原文是两份独立的权威事实，不建立跨区域总顺序。 */
+export type ModelEvidenceRegion = 'request' | 'response';
+/**
+ * 一条规范项的原始来源。
+ *
+ * `path` 是原始结构路径（对象键或数组下标），`value` 是原始子树的只读引用；
+ * 投影不深拷贝原始请求和响应，避免大响应被重复放大。
+ */
+export interface ModelEvidenceSource {
+    region: ModelEvidenceRegion;
+    path: readonly string[];
+    value: unknown;
+}
+export type ModelEvidenceContentPartKind = 'text' | 'image' | 'file' | 'audio' | 'video' | 'other';
+export interface ModelEvidenceContentPart {
+    kind: ModelEvidenceContentPartKind;
+    value: string;
+    mimeType?: string;
+}
+export type ModelEvidenceMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/** 请求体中的工具调用证据。只有存在显式调用标识时才带 `callId`。 */
+export interface ModelEvidenceToolCall {
+    evidenceId: string;
+    name: string;
+    callId?: string;
+    arguments?: string;
+    sources: readonly ModelEvidenceSource[];
+}
+export interface ModelEvidenceMessage {
+    evidenceId: string;
+    role: ModelEvidenceMessageRole;
+    /** 语义正文：文本与无法归类的分片，按原始顺序拼接。 */
+    text: string;
+    contentParts: readonly ModelEvidenceContentPart[];
+    reasoning?: string;
+    toolCalls: readonly ModelEvidenceToolCall[];
+    /** 工具结果消息的显式调用标识。缺失时不得按名称或位置推断配对。 */
+    toolCallId?: string;
+    toolName?: string;
+    sources: readonly ModelEvidenceSource[];
+}
+export interface ModelEvidenceToolDefinition {
+    evidenceId: string;
+    name: string;
+    description: string;
+    parameters?: unknown;
+    propertyCount: number;
+    requiredFields: readonly string[];
+    sources: readonly ModelEvidenceSource[];
+}
+export type ModelEvidenceResponseEventKind = 'content' | 'reasoning' | 'tool-call' | 'tool-result' | 'finish-reason' | 'usage' | 'unknown';
+export interface ModelEvidenceUsageCandidate {
+    inputTokens?: number;
+    outputTokens?: number;
+    reasoningTokens?: number;
+    cachedTokens?: number;
+    totalTokens?: number;
+}
+export interface ModelEvidenceResponseEvent {
+    evidenceId: string;
+    kind: ModelEvidenceResponseEventKind;
+    /** content / reasoning / finish-reason 的文本事实。 */
+    text?: string;
+    name?: string;
+    callId?: string;
+    arguments?: string;
+    /** 响应体中的原始用量对象，仅作为候选证据。 */
+    usage?: Record<string, unknown>;
+    normalizedUsage?: ModelEvidenceUsageCandidate;
+    sources: readonly ModelEvidenceSource[];
+}
+export type ModelEvidenceDiagnosticCode = 'request-body-unsupported' | 'request-container-ambiguous' | 'response-body-malformed' | 'response-payload-unsupported' | 'response-payload-ambiguous';
+export type ModelEvidenceDiagnosticSeverity = 'info' | 'warning' | 'error';
+/** 结构化诊断只表达代码、严重程度和来源，不包含任何页面文案。 */
+export interface ModelEvidenceDiagnostic {
+    code: ModelEvidenceDiagnosticCode;
+    severity: ModelEvidenceDiagnosticSeverity;
+    source: ModelEvidenceSource;
+}
+export type ModelEvidenceTransportKind = 'json' | 'sse' | 'text' | 'empty';
+/** 响应 transport 解析结果。原始 JSON / SSE / TEXT 查看能力直接消费 `value`。 */
+export interface ModelEvidenceTransport {
+    kind: ModelEvidenceTransportKind;
+    value?: unknown;
+}
+/** 投影入口接收的证据切片：只有请求体、响应原文和响应 transport 格式。 */
+export interface ModelEvidenceSlice {
+    requestBody?: unknown;
+    responseBodyRaw?: string;
+    responseBodyFormat?: 'json' | 'text' | 'sse';
+}
+export interface ModelEvidenceProjection {
+    requestMessages: readonly ModelEvidenceMessage[];
+    toolDefinitions: readonly ModelEvidenceToolDefinition[];
+    responseEvents: readonly ModelEvidenceResponseEvent[];
+    responseTransport: ModelEvidenceTransport;
+    diagnostics: readonly ModelEvidenceDiagnostic[];
+}

package/lib/model-evidence/usage.d.ts

@@ -0,0 +1,10 @@
+import type { ModelEvidenceUsageCandidate } from './types';
+/**
+ * 响应体用量候选归一化。
+ *
+ * 这是协议知识（`prompt_tokens` / `input_tokens` / `promptTokenCount` 各家命名不同），
+ * 因此归属共享投影；最终采用哪个用量仍由调用方按 ADR-0059 的优先级决定。
+ */
+export declare function normalizeUsageCandidate(usage: Record<string, unknown> | undefined): ModelEvidenceUsageCandidate | undefined;
+/** 流式响应会分批上报用量；后到的残缺片段不得把已知数值覆盖成更小值。 */
+export declare function mergeUsage(current: Record<string, unknown> | undefined, incoming: Record<string, unknown>): Record<string, unknown>;

package/lib/model-request-collector.d.ts

@@ -0,0 +1,32 @@
+import type { ChatLunaTurnResolution } from './chatluna/session-tracker';
+import { type StudioModelRequestStore } from './model-request';
+import type { StudioModelRequestRecord, StudioPresetRuntimeSnapshot } from './types';
+export interface ChatLunaPluginLike {
+    prototype: {
+        fetch: (...args: any[]) => Promise<any>;
+    };
+}
+/** 预设运行时快照的查询目标：一次归属成功的模型请求所属的（机器人，会话）。 */
+export interface ModelRequestPresetSnapshotTarget {
+    botId: string;
+    conversationId: string;
+}
+export declare function isKnownChatModelRequestUrl(url: string): boolean;
+export declare function sanitizeModelRequestUrl(raw: string): string;
+export declare function resolveChatLunaPluginClass(baseDir?: string): ChatLunaPluginLike | undefined;
+export interface InstallModelRequestCollectorOptions {
+    plugin?: ChatLunaPluginLike;
+    baseDir?: string;
+    /** 全部模型请求都写进同一个记录库；归属与否只是记录上的一个字段。 */
+    store: StudioModelRequestStore;
+    /**
+     * 这次请求属于哪一轮对话，以及要不要记下来。
+     *
+     * 判不出归属时记成未归属；确定由虚拟机器人触发时整条记录都不写。
+     */
+    resolveTurn: () => ChatLunaTurnResolution;
+    getActivePresetSnapshots?: (target: ModelRequestPresetSnapshotTarget) => StudioPresetRuntimeSnapshot[];
+    onRecordAppended?: (record: StudioModelRequestRecord) => void;
+}
+export declare function inferModelResponseBodyFormat(contentType: string | undefined, raw: string): 'json' | 'text' | 'sse';
+export declare function installModelRequestCollector(options: InstallModelRequestCollectorOptions): () => void;

package/lib/model-request-trajectory.d.ts

@@ -0,0 +1,21 @@
+import type { StudioModelRequestDetail, StudioModelRequestRecord, StudioModelRequestStatus, StudioModelRequestTrajectory } from './types';
+import { type StudioModelRequestStore } from './model-request';
+interface BuildStudioModelRequestTrajectoryOptions {
+    record: StudioModelRequestDetail;
+    mode: 'request' | 'conversation';
+    /** 会话模式下同会话的原始记录，按 sequence 正序；缺省表示无法聚合，只呈现当前请求。 */
+    conversationRecords?: readonly StudioModelRequestRecord[];
+}
+/**
+ * 读取会话模式需要的同会话记录。记录库的读取是异步的，而轨迹投影本身是纯函数；
+ * 这个薄封装是唯一需要 Store 的地方，投影因此保持可单测、可复用。
+ */
+export declare function readStudioModelRequestConversationRecords(record: Pick<StudioModelRequestDetail, 'entities'>, store: StudioModelRequestStore | undefined): Promise<StudioModelRequestRecord[] | undefined>;
+export declare function buildStudioModelRequestTrajectoryFromStore(options: {
+    record: StudioModelRequestDetail;
+    mode: 'request' | 'conversation';
+    store?: StudioModelRequestStore;
+}): Promise<StudioModelRequestTrajectory>;
+export declare function buildStudioModelRequestTrajectory(options: BuildStudioModelRequestTrajectoryOptions): StudioModelRequestTrajectory;
+export declare function statusLabel(status: StudioModelRequestStatus): string;
+export {};

package/lib/model-request-variables.d.ts

@@ -0,0 +1,16 @@
+import type { ModelEvidenceProjection } from './model-evidence';
+import type { StudioModelRequestVariable, StudioPresetRuntimeSnapshot } from './types';
+/**
+ * 从运行时预设快照与一份已算好的模型证据投影派生模型请求变量。
+ *
+ * 本函数只读投影的请求消息，不解释请求体、响应原文或响应 transport 格式，
+ * 因此不接收模型请求记录，也不自己决定是否运行投影——那由调用方（模型请求记录的读取投影）决定。
+ */
+export declare function deriveModelRequestVariables(snapshots: readonly StudioPresetRuntimeSnapshot[], evidence: ModelEvidenceProjection): StudioModelRequestVariable[];
+/**
+ * 模型请求变量未被唯一证明时的状态说明文案。
+ *
+ * 轨迹行预览、分析导航项的搜索文本与右侧变量卡片正文共用这一份文案；
+ * 任何一侧自己再写一份，搜索这些文案时就会出现一侧命中、另一侧置灰。
+ */
+export declare function modelRequestVariableStatusLabel(status: StudioModelRequestVariable['status']): string;

package/lib/model-request.d.ts

@@ -0,0 +1,158 @@
+import { InMemoryRecordRows, type StudioRecordScopeSummary } from './record-store';
+import type { GetStudioModelRequestRecordsInput, StudioChatLunaRequestError, StudioModelRequestAttribution, StudioModelRequestCapacity, StudioModelRequestDetail, StudioModelRequestEntities, StudioModelRequestError, StudioModelRequestFacets, StudioModelRequestListItem, StudioModelRequestRecord, StudioModelRequestRecordsPage, StudioModelRequestStatus, StudioModelResponseBodyFormat, StudioPresetRuntimeSnapshot, StudioModelResponseBodyStatus } from './types';
+export declare const DEFAULT_MODEL_REQUEST_RECORD_LIMIT = 500;
+export declare const DEFAULT_MODEL_REQUEST_RECORD_MAX_BYTES: number;
+export declare const DEFAULT_MODEL_REQUEST_PAGE_SIZE = 50;
+export declare const MAX_MODEL_REQUEST_PAGE_SIZE = 200;
+/** 筛选下拉聚合扫描的记录条数上限；只读记录头，不触碰请求体与响应原文。 */
+export declare const MODEL_REQUEST_FACET_SCAN_LIMIT = 500;
+export interface StudioModelRequestPersistenceQuery {
+    attribution?: StudioModelRequestAttribution;
+    botId?: string;
+    conversationId?: string;
+    interactionId?: string;
+    model?: string;
+    errorsOnly?: boolean;
+    order: 'asc' | 'desc';
+    beforeSequence?: number;
+    beforeCreatedAt?: string;
+    beforeId?: string;
+    /** 调用方会多取一条用于判断 hasMore。 */
+    limit: number;
+}
+export type StudioModelRequestScopeSummary = StudioRecordScopeSummary;
+/**
+ * 列表读取真正需要的记录切片。
+ *
+ * 请求体与响应原文是记录里唯一没有上限的两个字段，而列表投影从来不读它们；把这个切片
+ * 提升成一个具名类型，读取路径就能在适配器一侧把它们留在存储里，而不是先取出整条记录再丢掉。
+ */
+export type StudioModelRequestRecordHeader = Omit<StudioModelRequestRecord, 'requestBody' | 'responseBodyRaw'>;
+/** 从完整记录取出列表读取需要的切片。适配器与内存行库共用同一份口径。 */
+export declare function toModelRequestRecordHeader(record: StudioModelRequestRecord): StudioModelRequestRecordHeader;
+/**
+ * 模型请求记录按行持久化：追加是单行 insert，补充响应体或错误是单行 update，容量回收是
+ * 按序号区间 delete，读取由适配器完成过滤、排序与分页。
+ */
+export interface StudioModelRequestPersistence {
+    /** 读取作用域摘要，不加载任何记录正文。 */
+    summarize(): Promise<StudioModelRequestScopeSummary>;
+    append(record: StudioModelRequestRecord, bytes: number, nextSequence: number): Promise<StudioModelRequestScopeSummary>;
+    find(recordId: string): Promise<StudioModelRequestRecord | undefined>;
+    /** 覆盖单行，按 sequence 定位；不触碰其他行。 */
+    replace(record: StudioModelRequestRecord, bytes: number): Promise<StudioModelRequestScopeSummary>;
+    query(query: StudioModelRequestPersistenceQuery): Promise<StudioModelRequestRecord[]>;
+    /** 与 query 同一套过滤、排序与分页，但不取出请求体与响应原文。 */
+    queryHeaders(query: StudioModelRequestPersistenceQuery): Promise<StudioModelRequestRecordHeader[]>;
+    /** 从最旧开始按序号区间删除，直到同时满足条数与字节上限。 */
+    reclaim(limits: {
+        maxRecords: number;
+        maxBytes: number;
+    }): Promise<StudioModelRequestScopeSummary>;
+    /** 清空作用域记录，但保留 nextSequence 高水位。 */
+    clear(nextSequence: number): Promise<StudioModelRequestScopeSummary>;
+}
+/** 内存适配器与数据库适配器必须给出等价结果；内存侧直接复用这个谓词。 */
+export declare function matchesModelRequestQuery(record: StudioModelRequestRecord, query: StudioModelRequestPersistenceQuery): boolean;
+/** 进程内模型请求行库；行库机制来自共享实现，这里只注入模型请求的过滤谓词与列表切片。 */
+export declare class InMemoryModelRequestRecords extends InMemoryRecordRows<StudioModelRequestRecord, StudioModelRequestPersistenceQuery> implements StudioModelRequestPersistence {
+    constructor();
+    queryHeaders(query: StudioModelRequestPersistenceQuery): Promise<StudioModelRequestRecordHeader[]>;
+}
+export interface AppendModelRequestRecordInput {
+    status: StudioModelRequestStatus;
+    durationMs: number;
+    method?: string;
+    url?: string;
+    provider?: string;
+    model?: string;
+    headers?: Record<string, string>;
+    attribution: 'attributed' | 'unattributed';
+    entities: StudioModelRequestEntities;
+    requestBody?: unknown;
+    requestBodyAvailable: boolean;
+    responseBodyStatus?: StudioModelResponseBodyStatus;
+    responseBodyFormat?: StudioModelResponseBodyFormat;
+    responseStatus?: number;
+    responseBodyRaw?: string;
+    responseBodyError?: string;
+    interactionId?: string;
+    chatlunaRequestId?: string;
+    presetSnapshots?: StudioPresetRuntimeSnapshot[];
+    error?: StudioModelRequestError;
+    chatlunaError?: StudioChatLunaRequestError;
+}
+export interface UpdateModelRequestRecordInput {
+    status?: StudioModelRequestStatus;
+    durationMs?: number;
+    headers?: Record<string, string>;
+    responseBodyStatus?: StudioModelResponseBodyStatus;
+    responseBodyFormat?: StudioModelResponseBodyFormat;
+    responseStatus?: number;
+    responseBodyRaw?: string;
+    responseBodyError?: string;
+    chatlunaRequestId?: string;
+    error?: StudioModelRequestError;
+    chatlunaError?: StudioChatLunaRequestError;
+}
+export interface StudioModelRequestStoreOptions {
+    maxRecords?: number;
+    maxBytes?: number;
+    persistence?: StudioModelRequestPersistence;
+}
+export declare function estimateModelRequestRecordBytes(record: StudioModelRequestRecord): number;
+export declare function createModelRequestError(error: unknown, traceId?: string): StudioModelRequestError;
+/**
+ * 列表投影。入参允许带请求体与响应原文（轨迹从完整记录派生同会话列表项），但它们既不参与
+ * 投影也不参与拷贝：列表路径深拷贝整条记录再丢掉这两个字段，是列表读取里最大的一次无用功。
+ */
+export declare function presentModelRequestListItem(record: StudioModelRequestRecordHeader & Partial<Pick<StudioModelRequestRecord, 'requestBody' | 'responseBodyRaw'>>): StudioModelRequestListItem;
+export declare function presentModelRequestDetail(record: StudioModelRequestRecord): StudioModelRequestDetail;
+export declare class StudioModelRequestStore {
+    private nextSequence;
+    private summary;
+    private readonly maxRecords;
+    private readonly maxBytes;
+    private persistence;
+    private readonly ready;
+    private readonly writes;
+    /** 已分配序号但尚未落盘的记录；恢复完成时按持久化高水位重新编号。 */
+    private staged;
+    private readonly pendingUpdates;
+    constructor(options?: StudioModelRequestStoreOptions);
+    waitForReady(): Promise<void>;
+    waitForPersistence(): Promise<void>;
+    /**
+     * 等到已入队的写入全部提交。读取只需要这一层：pendingUpdates 里是尚未产生写入的
+     * 外部 Promise（例如仍在流式传输的响应体），读取等待它们会与写入方互相死锁。
+     */
+    private settle;
+    /** 登记会在稍后触发 update 的外部 Promise（响应体旁路采集），让收尾等待能覆盖它。 */
+    trackUpdate(task: Promise<void>): void;
+    getCapacity(): Promise<StudioModelRequestCapacity>;
+    append(input: AppendModelRequestRecordInput): StudioModelRequestRecord;
+    update(recordId: string, input: UpdateModelRequestRecordInput): Promise<StudioModelRequestRecord | undefined>;
+    getRecords(input?: GetStudioModelRequestRecordsInput): Promise<StudioModelRequestRecordsPage>;
+    getRecord(recordId: string): Promise<StudioModelRequestDetail | undefined>;
+    /**
+     * 「这条模型请求记录在不在」由本记录库判定，取不到就抛。
+     *
+     * 与 `getRecord` 并存而不是替代它：本成员服务于「调用方就是要这条记录」，`getRecord` 服务于
+     * 跨记录域遍历——遍历必须能区分「这个记录域里没有」与「这个记录域的持久化坏了」，用异常表达
+     * 未命中会让一次真实故障被当成「这里没有」静默跳过。
+     */
+    requireRecord(recordId: string): Promise<StudioModelRequestDetail>;
+    getRawRecords(input?: GetStudioModelRequestRecordsInput): Promise<StudioModelRequestRecord[]>;
+    clear(): Promise<number>;
+    /**
+     * 筛选下拉的可选值。
+     *
+     * 只扫最近一段记录头而不是全表：这是一份用于「点开筛选看看有哪些会话」的辅助清单，
+     * 而记录库的保留上限本来就会淘汰更早的记录，为它引入一条新的存储查询不划算。
+     */
+    getFacets(limit?: number): Promise<StudioModelRequestFacets>;
+    private toFilter;
+    private readCapacity;
+    private reclaimOverflow;
+}
+export declare function resolveModelRequestOrder(input: Pick<GetStudioModelRequestRecordsInput, 'order'>): 'asc' | 'desc';

package/lib/persistence.d.ts

@@ -0,0 +1,85 @@
+import type { Context } from 'koishi';
+import type { StudioModelRequestAttribution, StudioModelRequestRecord, StudioModelRequestStatus } from './types';
+import { type StudioModelRequestPersistence, type StudioModelRequestPersistenceQuery, type StudioModelRequestRecordHeader, type StudioModelRequestScopeSummary } from './model-request';
+/** 记录里唯一没有上限的两个字段；列表读取从不投影它们。 */
+export interface StudioModelRequestRecordBodies {
+    requestBody?: unknown;
+    responseBodyRaw?: string;
+}
+/**
+ * 记录库状态行：只保存 nextSequence 高水位，永远只有一行。
+ *
+ * 记录条数与字节数由记录行的 bytes 列现算，避免计数漂移；序号必须独立保存，否则清空记录后
+ * max(sequence)+1 会回退并复用旧序号，而列表游标正是按序号翻页的。
+ */
+export interface StudioModelRequestStateRow {
+    id: string;
+    nextSequence: number;
+    updatedAt: Date;
+}
+/**
+ * 一条模型请求记录一行。
+ *
+ * 记录被拆成两列：`header` 是列表读取需要的全部字段，`bodies` 只装请求体与响应原文。
+ * 这两个字段是记录里唯一没有上限的部分，单列存放时列表读取会连它们一起取出并反序列化；
+ * 拆列之后列表查询只投影 `header`，翻页与自动刷新不再按请求体体积付代价。
+ */
+export interface StudioModelRequestRecordRow {
+    sequence: number;
+    id: string;
+    createdAt: string;
+    attribution: StudioModelRequestAttribution;
+    botId: string;
+    conversationId: string;
+    interactionId: string;
+    model: string;
+    status: StudioModelRequestStatus;
+    bytes: number;
+    header: StudioModelRequestRecordHeader;
+    bodies: StudioModelRequestRecordBodies;
+}
+declare module '@koishijs/core' {
+    interface Tables {
+        'chatluna-studio.model-request': StudioModelRequestRecordRow;
+        'chatluna-studio.model-request-state': StudioModelRequestStateRow;
+    }
+}
+type StudioRecordRowQuery = Record<string, unknown>;
+interface StudioRecordRowCursor {
+    limit?: number;
+    offset?: number;
+    fields?: string[];
+    sort?: Record<string, 'asc' | 'desc'>;
+}
+export interface StudioModelRequestDatabase {
+    get(table: 'chatluna-studio.model-request', query: StudioRecordRowQuery, cursor?: StudioRecordRowCursor): Promise<StudioModelRequestRecordRow[]>;
+    get(table: 'chatluna-studio.model-request-state', query: {
+        id: string;
+    }): Promise<StudioModelRequestStateRow[]>;
+    upsert(table: 'chatluna-studio.model-request', rows: StudioModelRequestRecordRow[]): Promise<unknown>;
+    upsert(table: 'chatluna-studio.model-request-state', rows: StudioModelRequestStateRow[]): Promise<unknown>;
+    remove(table: 'chatluna-studio.model-request', query: StudioRecordRowQuery): Promise<unknown>;
+}
+export declare function registerStudioModelRequestModel(ctx: Context): void;
+export declare class KoishiDatabaseModelRequestPersistence implements StudioModelRequestPersistence {
+    private getDatabase;
+    private readyTimeoutMs;
+    private index;
+    constructor(getDatabase: () => StudioModelRequestDatabase | undefined, readyTimeoutMs?: number);
+    summarize(): Promise<StudioModelRequestScopeSummary>;
+    append(record: StudioModelRequestRecord, bytes: number, nextSequence: number): Promise<import("./record-store").StudioRecordScopeSummary>;
+    find(recordId: string): Promise<StudioModelRequestRecord | undefined>;
+    replace(record: StudioModelRequestRecord, bytes: number): Promise<import("./record-store").StudioRecordScopeSummary>;
+    query(query: StudioModelRequestPersistenceQuery): Promise<StudioModelRequestRecord[]>;
+    queryHeaders(query: StudioModelRequestPersistenceQuery): Promise<StudioModelRequestRecordHeader[]>;
+    reclaim(limits: {
+        maxRecords: number;
+        maxBytes: number;
+    }): Promise<import("./record-store").StudioRecordScopeSummary>;
+    clear(nextSequence: number): Promise<import("./record-store").StudioRecordScopeSummary>;
+    private toRow;
+    private toRowQuery;
+    private saveState;
+    private requireDatabase;
+}
+export {};

package/lib/presets/evidence-match.d.ts

@@ -0,0 +1,9 @@
+import type { ModelEvidenceProjection } from '../model-evidence';
+import type { PresetEvidenceMatchResult, PresetRuntimeSnapshot, PresetSourceDocument, PresetTemplateExpression } from './types';
+export interface MatchPresetExpressionEvidenceInput {
+    document: PresetSourceDocument;
+    expression: PresetTemplateExpression;
+    snapshot: PresetRuntimeSnapshot;
+    evidence: ModelEvidenceProjection;
+}
+export declare function matchPresetExpressionEvidence(input: MatchPresetExpressionEvidenceInput): PresetEvidenceMatchResult;

package/lib/presets/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './source-document';
+export * from './repository';
+export * from './runtime-correlation';
+export * from './evidence-match';
+export * from './service';

package/lib/presets/repository.d.ts

@@ -0,0 +1,86 @@
+import type { PresetDocumentKind, PresetSourceDocument } from './types';
+export type PresetRepositoryErrorCode = 'already-exists' | 'confirmation-required' | 'invalid-file-name' | 'not-found' | 'revision-conflict' | 'unsafe-file' | 'unsafe-root';
+export declare class PresetRepositoryError extends Error {
+    readonly code: PresetRepositoryErrorCode;
+    readonly cause?: unknown | undefined;
+    readonly name = "PresetRepositoryError";
+    constructor(code: PresetRepositoryErrorCode, message: string, cause?: unknown | undefined);
+}
+export interface PresetRepositoryRoots {
+    coreRoot: string;
+    characterRoot: string;
+}
+export interface PresetFile {
+    kind: PresetDocumentKind;
+    fileName: string;
+    revision: string;
+    size: number;
+    modifiedAt: string;
+    source: string;
+    document: PresetSourceDocument;
+}
+export interface CreatePresetInput {
+    kind: PresetDocumentKind;
+    fileName: string;
+    source: string;
+}
+export interface SavePresetInput extends CreatePresetInput {
+    expectedRevision: string;
+}
+export interface RenamePresetInput {
+    kind: PresetDocumentKind;
+    fileName: string;
+    newFileName: string;
+    expectedRevision: string;
+    confirmed: boolean;
+}
+export interface DeletePresetInput {
+    kind: PresetDocumentKind;
+    fileName: string;
+    expectedRevision: string;
+    confirmed: boolean;
+}
+export interface PresetRepository {
+    readAll(kind: PresetDocumentKind): Promise<PresetFile[]>;
+    read(kind: PresetDocumentKind, fileName: string): Promise<PresetFile>;
+    create(input: CreatePresetInput): Promise<PresetFile>;
+    save(input: SavePresetInput): Promise<PresetFile>;
+    rename(input: RenamePresetInput): Promise<PresetFile>;
+    delete(input: DeletePresetInput): Promise<void>;
+}
+export interface FileSystemPresetRepositoryOptions {
+    beforeMutationCommit?: (context: {
+        operation: 'create' | 'save' | 'rename' | 'delete';
+        sourcePath?: string;
+        destinationPath?: string;
+    }) => Promise<void> | void;
+}
+export declare class FileSystemPresetRepository implements PresetRepository {
+    private readonly options;
+    private readonly rootPaths;
+    private roots?;
+    constructor(roots: PresetRepositoryRoots, options?: FileSystemPresetRepositoryOptions);
+    readAll(kind: PresetDocumentKind): Promise<PresetFile[]>;
+    read(kind: PresetDocumentKind, fileName: string): Promise<PresetFile>;
+    create(input: CreatePresetInput): Promise<PresetFile>;
+    save(input: SavePresetInput): Promise<PresetFile>;
+    rename(input: RenamePresetInput): Promise<PresetFile>;
+    delete(input: DeletePresetInput): Promise<void>;
+    private initializeRoots;
+    private initializeRoot;
+    private requireRoot;
+    private revalidateRoot;
+    private filePath;
+    private readPresetFile;
+    private readRegularFileSnapshot;
+    private readRegularFileAfterRevision;
+    private revalidateSnapshot;
+    private assertSameSnapshot;
+    private assertDestinationMissing;
+    private atomicWrite;
+    private beforeMutationCommit;
+    private toPresetFile;
+    private requireConfirmation;
+    private revisionConflict;
+    private fileReplaced;
+}

package/lib/presets/runtime-correlation.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from 'koishi';
+import type { PresetRuntimeSessionTarget, PresetRuntimeSnapshot } from './types';
+export declare class PresetRuntimeSnapshotTracker {
+    private ctx;
+    private readonly active;
+    private readonly coreTurnKeys;
+    private readonly characterSessionTurnKeys;
+    private readonly disposers;
+    private nextCoreTurn;
+    private nextCharacterTurn;
+    constructor(ctx: Context);
+    getActiveSnapshots(target: PresetRuntimeSessionTarget): PresetRuntimeSnapshot[];
+    dispose(): void;
+    private resolveSession;
+    private finishCore;
+}