dsh-prime-memory 0.11.0

package/dist/contract.d.ts

@@ -0,0 +1,820 @@
+/**
+ * RPC 契约单一事实源(types-only,零运行时代码)。
+ *
+ * host(stats 端点路由)与 client(浏览器侧)共用的全部 `dsh-memory/*` 端点
+ * 请求/响应类型收敛于此,两端各自 `import type`,契约漂移在编译期暴露。
+ *
+ * 铁律:
+ * - 本文件只允许 type/interface 与纯类型推导,不 import 任何运行时值
+ *   (tsc 产出空 contract.js,client bundle 里 import type 被 esbuild 擦除);
+ * - 响应类型按端点实际返回逐字段建模,含 `chain.current[].reasoningEffort` 与
+ *   `chain.effectiveChain[].effort` 这对故意不同名的字段——链上两种条目形状
+ *   不同,不合并;
+ * - 端点全集为 26 个(含面板高权限删除 records-delete 与图谱两端点)。
+ */
+import type { MemoryFamily, MemoryMode } from './types.js';
+import type { GraphEdge, GraphNode } from './graph/types.js';
+/** 蒸馏思考档位:'' = 自动(模型默认档 → high)。运行时词汇表源是 config.ts 的
+ *  EFFORT_CHOICES(satisfies readonly EffortChoice[] 反向锁定防漂移)。 */
+export type EffortChoice = '' | 'off' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** 蒸馏用量/成本记账的层标识(调用点口径)。graph = 知识图谱投影调用。 */
+export type DistillLayer = 'l1-extract' | 'l1-dedup' | 'l2' | 'l3' | 'graph';
+/** 分层输出预算的层键(与 DistillLayer 不同:预算按管线阶段,用量按调用点)。 */
+export type DistillBudgetLayer = 'extract' | 'dedup' | 'l2' | 'l3' | 'graph';
+/** 分层输出预算(token):0 = 跟随内置默认。 */
+export type DistillBudgets = Record<DistillBudgetLayer, number>;
+/**
+ * 运行时统一路由链条目:[0] = 主路由(provider/model 双空 = 跟随默认模型),
+ * [1..] = 回退链(按序降级);reasoningEffort 为该路由的档位覆盖('' = 跟随部署全局)。
+ */
+export interface DistillChainEntry {
+    provider: string;
+    model: string;
+    reasoningEffort: EffortChoice;
+}
+/** 部署静态回退链条目(config.llm.fallbacks):reasoningEffort 可选——与运行时链
+ *  DistillChainEntry(必填)形状不同,不共用类型。 */
+export interface StaticFallbackEntry {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/** 按层路由的层键:l1 同管 l1-extract + l1-dedup 两个调用点(与成本看板按层归并同源);
+ *  graph 投影不配层链(回全局解析);预算键(DistillBudgetLayer)是另一套五键词表,不混用。 */
+export type LayerRouteKey = 'l1' | 'l2' | 'l3';
+/** 记忆模式运行时开关(settings-get/set 的 settings 载荷)。 */
+export interface MemoryLiveSettings {
+    /** 总开关:关 = 捕获/蒸馏/召回注入全停(数据保留) */
+    enabled: boolean;
+    /** L0 捕获(原始对话落盘) */
+    capture: boolean;
+    /** L1 抽取 + L2/L3 蒸馏 */
+    distill: boolean;
+    /** 召回注入(画像/记忆上下文) */
+    recall: boolean;
+    /** 蒸馏思考档位运行时覆盖:'' = 跟随静态 config(llm.reasoningEffort) */
+    reasoningEffort: EffortChoice;
+    /** 蒸馏模型运行时覆盖(供应商 id):'' = 跟随静态 config/默认选择。
+     *  与 distillModel 成对生效(单字段不算);部署静态 pin(provider+model 双字段)优先。 */
+    distillProvider: string;
+    /** 蒸馏模型运行时覆盖(模型 id):'' = 跟随静态 config/默认选择。 */
+    distillModel: string;
+    /** 运行时统一路由链;非空即权威(旧 distillProvider/distillModel/reasoningEffort 不再参与),
+     *  空数组 = 跟随部署静态配置与默认模型。 */
+    distillChain: DistillChainEntry[];
+    /** 分层输出预算运行时覆盖(token):extract/dedup/l2/l3/graph 五层,0 = 跟随内置默认;
+     *  思考档 high/max 的 ×4 放大在覆盖值之上照常生效。 */
+    distillBudgets: DistillBudgets;
+    /** 输入预算运行时覆盖(字符,≈token):单次蒸馏调用的输入上限,L1 按此分块、
+     *  超限截断;0 = 跟随静态配置 llm.maxInputChars。 */
+    distillMaxInputChars: number;
+    /** 运行时按层路由链:层键 l1/l2/l3 各一条完整链;非空即完整接管该层解析
+     *  (压过静态 layerRoutes,层内第一优先级);空数组 = 该层跟随(静态层链 → 全局解析逐级兜底)。
+     *  写入经 settings-set 逐层校验(头行必须显式)。 */
+    distillLayerChains: Record<LayerRouteKey, DistillChainEntry[]>;
+    /** 蒸馏通道运行时覆盖:'' = 跟随部署 config(llm.mode);'host' = 复用宿主 ctx.llm;
+     *  'direct' = 插件原生直连 llm.baseURL。经 effectiveCfg 注入 cfg.llm.mode。 */
+    distillMode: '' | 'host' | 'direct';
+    /** 运行时直连端点覆盖(OpenAI 兼容 /v1,'direct' 用):经 effectiveCfg 注入 cfg.llm.baseURL。
+     *  非机密,可原样回显。 */
+    directBaseURL: string;
+    /** 运行时直连 API Key 覆盖(仅 'direct' 用,可空 = 本地免 key):
+     *  经 effectiveCfg 注入 cfg.llm.apiKey。属机密,任何回读/日志须脱敏。 */
+    directApiKey: string;
+    /** 远程嵌入端点运行时覆盖:注入 cfg.embedding.baseUrl。
+     *  (远程嵌入连接从部署 YAML 改为可在设置 UI 编辑——D 系列评审的 UX 缺口。) */
+    embedRemoteBaseURL: string;
+    /** 远程嵌入 API Key 运行时覆盖:注入 cfg.embedding.apiKey。属机密,不回读明文、不落日志。 */
+    embedRemoteApiKey: string;
+    /** 远程嵌入模型名运行时覆盖:注入 cfg.embedding.model。 */
+    embedRemoteModel: string;
+    /** 远程嵌入维度运行时覆盖:注入 cfg.embedding.dimensions;0 = 未配置/跟随部署。 */
+    embedRemoteDimensions: number;
+    /** 记忆写删权限门:true 才允许写删记忆工具(memory_add/memory_delete)与面板高权限删除
+     *  (records-delete)。默认 false(模型写删风险高,须显式在面板开启高权限模式)。 */
+    memoryMutate: boolean;
+}
+/** 召回停用原因(session-stats recall.enabled=false 时带出;短路序第一个为假的因子)。 */
+export type RecallDisabledReason = 'deploy' | 'global' | 'session' | 'mode';
+/** 单会话召回统计(悬浮卡信息区数据源)。 */
+export interface RecallSessionStats {
+    /** 发生过召回检索的轮次数(含零命中、全量压制与超时)。 */
+    injectedTurns: number;
+    /** 命中(≥1 条实际注入,或有命中但被去重全量压制)轮次数。 */
+    hitTurns: number;
+    /** 累计注入条数(去重过滤后、预算截断前)。 */
+    totalHits: number;
+    /** 总预算超时跳过次数。 */
+    timeouts: number;
+    /** 累计被去重压制的命中条数(同会话已注入过,不重复注入)。 */
+    suppressedRecalls: number;
+    /** 最近一轮实际注入条数(0 = 零命中/超时/全量压制;工具指南门控沿用此信号)。 */
+    lastHits: number;
+    /** 最近一轮检索耗时 ms。 */
+    lastDurationMs: number;
+    /** 最近一次记账时间(LRU 清理依据)。 */
+    updatedAt: number;
+}
+/**
+ * 单会话记忆上下文占用(session-stats.memoryOccupancy;悬浮卡与输入栏占用指示器共用)。
+ * 形状与算术的唯一来源是 util/context-occupancy 的 OccupancyLedger,禁止任何一侧另写换算。
+ * null = 本会话从未注入过。
+ */
+export type MemoryOccupancy = import('./util/context-occupancy.js').OccupancyLedger;
+/** 重建阶段。 */
+export type RebuildPhase = 'idle' | 'preparing' | 'distilling' | 'finalizing' | 'done' | 'cancelled' | 'failed';
+/** 重建状态(rebuild-status/start/cancel 端点返回值)。 */
+export interface RebuildStatus {
+    running: boolean;
+    phase: RebuildPhase;
+    /** 已完成的会话块数 / 总块数。 */
+    done: number;
+    total: number;
+    /** L0 体量(idle 时为实时预估,运行中为快照值)。 */
+    sessionCount: number;
+    messageCount: number;
+    /** 预计 LLM 抽取调用次数(下界估算:块数与字符预算取大)。 */
+    estCalls: number;
+    /** 重建产出的 L1 记录累计条数。 */
+    recordsBuilt: number;
+    cancelRequested: boolean;
+    startedAt: number | null;
+    finishedAt: number | null;
+    error: string | null;
+    /** 归档产物名(提示用户可手工找回)。 */
+    archiveNote: string | null;
+}
+/** 反刍阶段。 */
+export type RuminatePhase = 'idle' | 'refreshing' | 'distilling' | 'consolidating' | 'updating' | 'done' | 'cancelled' | 'failed';
+/** 反刍状态(ruminate-status/start/cancel 端点返回值)。 */
+export interface RuminateStatus {
+    running: boolean;
+    phase: RuminatePhase;
+    /** 已完成的会话数(反刍中为已完成蒸馏的切片数,轻量刷新为已完成步骤数)。 */
+    done: number;
+    /** 待处理会话数(distilling 阶段为会话组数;轻量刷新为待执行步骤数)。 */
+    total: number;
+    /** 反刍产出的 L1 记录累计条数(反刍控制器追踪)。 */
+    recordsBuilt: number;
+    /** 当前动作的人类可读描述(L2/L3 单次调用可达分钟级,无此字段界面只能显示"运行中")。 */
+    detail?: string | null;
+    cancelRequested: boolean;
+    startedAt: number | null;
+    finishedAt: number | null;
+    error: string | null;
+}
+/** 反刍结果(含按族分组摘要)。 */
+export interface RuminateResult {
+    status: RuminateStatus;
+    byFamily: {
+        chat: {
+            l1Extracted: number;
+            l2Scenes: number;
+            l3Updated: boolean;
+        };
+        work: {
+            l1Extracted: number;
+            l2Scenes: number;
+            l3Updated: boolean;
+        };
+    };
+}
+/** 概览统计(dsh-memory/stats 端点返回值)。 */
+export interface MemoryStats {
+    ok: boolean;
+    dataDir: string;
+    /** 新会话默认记忆档位(auto/chat/work)。 */
+    family: string;
+    version: string;
+    l0Today: number;
+    l1Count: number;
+    l1TotalExtracted: number;
+    sceneCount: number;
+    personaChars: number;
+    hasPersona: boolean;
+    lastExtractAt: string | null;
+    lastL2At: string | null;
+    lastL3At: string | null;
+    memoriesSinceL2: number;
+    memoriesSinceL3: number;
+    pendingExtract: number;
+    message: string;
+    /** 实际生效的阈值(概览进度分母用,避免 UI 硬编码与部署配置脱节)。 */
+    thresholds: {
+        l2MinNewMemories: number;
+        l3Interval: number;
+    };
+}
+/** 成本看板时间粒度(趋势图 + 统计口径共用)。 */
+export type Granularity = 'day' | 'week' | 'month';
+/** 成本看板单个时间窗口(day/week/month/all)。 */
+export interface CostWindow {
+    range: 'day' | 'week' | 'month' | 'all';
+    /** 窗口起点(毫秒;all 为 0)。 */
+    since: number;
+    calls: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    avgOutputTokens: number;
+    medianOutputTokens: number;
+}
+/** 每模型统计指标(层级表格行;均值/中位数按 since=0 全量历史的活跃桶口径)。 */
+export interface ModelMetrics {
+    model: string;
+    dayCalls: number;
+    weekCalls: number;
+    monthCalls: number;
+    dayOutput: number;
+    dayMedian: number;
+    weekOutput: number;
+    weekMedian: number;
+    monthOutput: number;
+    monthMedian: number;
+}
+/** 每层级(l1/l2/l3)的模型统计(层级表格)。 */
+export interface LayerMetrics {
+    layer: 'l1' | 'l2' | 'l3';
+    models: ModelMetrics[];
+}
+/** 层级 × 窗口矩阵里的单个窗口格子。 */
+export interface LayerWindow {
+    range: 'day' | 'week' | 'month' | 'all';
+    calls: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    avgOutputTokens: number;
+    medianOutputTokens: number;
+}
+/** 单个层级在四个窗口的聚合(层级×窗口表格行)。 */
+export interface LayerCost {
+    layer: 'l1' | 'l2' | 'l3';
+    windows: LayerWindow[];
+}
+/** 趋势单桶。 */
+export interface TrendBucket {
+    ts: number;
+    total: number;
+    byModel: Record<string, number>;
+}
+/** 趋势快照:三个层级各一份连续桶序列。 */
+export interface TrendSnapshot {
+    granularity: Granularity;
+    byLayer: Record<'l1' | 'l2' | 'l3', TrendBucket[]>;
+}
+/** 按 model 分组的成本行(成本看板用)。 */
+export interface CostByModel {
+    provider: string;
+    model: string;
+    calls: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+}
+/** 成本快照(dsh-memory/token-cost 端点返回值)。 */
+export interface CostSnapshot {
+    /** day/week/month/all 四窗口聚合。 */
+    windows: CostWindow[];
+    /** 全量窗口(all)按 model 分组。 */
+    byModel: CostByModel[];
+    /** 按层级(l1/l2/l3 归并)在四个窗口的聚合(层级×窗口表格)。 */
+    byLayer: LayerCost[];
+    /** 每层级的模型统计指标(层级表格)。 */
+    byLayerStats: LayerMetrics[];
+    /** 趋势图数据。 */
+    trend: TrendSnapshot;
+}
+/** 嵌入源:远程 / 本地 / 关闭。 */
+export type EmbeddingSourceKind = 'remote' | 'local' | 'off';
+/** 嵌入运行时安装进度(runtime-installer)。 */
+export interface RuntimeProgress {
+    phase: 'idle' | 'installing' | 'ready' | 'error' | 'cancelled';
+    /** 插件钉死的目标版本。 */
+    targetVersion: string;
+    /** runtime 里实际就位的版本(未安装为 null)。 */
+    installedVersion: string | null;
+    startedAt: number;
+    /** 已运行毫秒(读时计算)。 */
+    elapsedMs: number;
+    /** npm 输出尾行(最近 5 行,让用户看到 npm 在干什么)。 */
+    lastLines: string[];
+    error?: string;
+}
+/** 下载阶段。 */
+export type DownloadPhase = 'downloading' | 'verifying' | 'done' | 'cancelled' | 'error';
+/** 模型下载进度(下载器 getProgress;无活动下载为 null)。 */
+export interface DownloadProgress {
+    modelId: string;
+    phase: DownloadPhase;
+    /** 当前文件序号(1-based)。 */
+    fileIndex: number;
+    fileCount: number;
+    /** 当前文件已收字节(含续传基线)。 */
+    fileReceived: number;
+    fileTotal: number;
+    /** 整模型累计字节(含已完成文件;分母 = 目录总大小)。 */
+    overallReceived: number;
+    overallTotal: number;
+    /** EMA 平滑速度(字节/秒)。 */
+    speedBps: number;
+    startedAt: number;
+    /** phase=error 时的原因。 */
+    error?: string;
+}
+/** 嵌入源活切换阶段。 */
+export type ApplyPhase = 'idle' | 'installing-runtime' | 'warming' | 'switching' | 'reindexing' | 'done' | 'error';
+/** 重嵌入进度。 */
+export interface ReindexProgressState {
+    running: boolean;
+    l1Done: number;
+    l1Total: number;
+    l0Done: number;
+    l0Total: number;
+    startedAt: number;
+    cancelled: boolean;
+    error?: string;
+}
+/** 嵌入源状态视图(embedding-state-get 端点的主体)。 */
+export interface EmbeddingStateView {
+    source: EmbeddingSourceKind;
+    activeModel: string | null;
+    ceilings: {
+        remote: boolean;
+        local: boolean;
+    };
+    /** 生效的远程嵌入连接(运行时覆盖优先于部署;key 明文不回传只给布尔)。 */
+    remote: {
+        baseURL: string;
+        model: string;
+        dimensions: number;
+        apiKeySet: boolean;
+    };
+    runtime: RuntimeProgress;
+    models: Array<{
+        id: string;
+        name: string;
+        dims: number;
+        contextTokens: number;
+        tags: string[];
+        description: string;
+        totalBytes: number;
+        bytesOnDisk: number;
+        state: 'none' | 'partial' | 'downloaded';
+    }>;
+    download: DownloadProgress | null;
+    apply: {
+        phase: ApplyPhase;
+        message: string;
+        startedAt: number;
+        busy: boolean;
+    };
+    local: {
+        state: 'idle' | 'loading' | 'ready' | 'failed' | 'terminated';
+        error: string | null;
+    } | null;
+    reindex: ReindexProgressState;
+    activeNote?: string;
+}
+/** dsh-memory/stats */
+export interface StatsResponse extends MemoryStats {
+}
+/** dsh-memory/token-cost */
+export interface TokenCostRequest {
+    granularity?: Granularity;
+    /** 正整数且 ≤ 明细保留期(0/非法回退全量窗口)。 */
+    rangeDays?: number;
+}
+export interface TokenCostResponse extends CostSnapshot {
+}
+/** dsh-memory/session-mode-get | set */
+export interface SessionModeGetRequest {
+    sessionId: string;
+}
+export interface SessionModeGetResponse {
+    sessionId: string;
+    mode: MemoryMode;
+    defaultMode: MemoryMode;
+    /** 会话级注入覆盖:null = 未覆盖(跟随全局)——线上 JSON 用 null 不用 undefined(序列化丢包)。 */
+    recall: boolean | null;
+    /** host 解析后的注入生效值(会话覆盖 ?? 全局开关):pill 面文直接消费。 */
+    recallResolved: boolean;
+}
+export interface SessionModeSetRequest {
+    sessionId: string;
+    mode: MemoryMode;
+    /** 会话级注入覆盖:布尔 = 设置覆盖;显式 null = 清除(跟随全局);缺省 = 不动
+     *  (旧 client 纯切档兼容,覆盖不丢)。mode 与 recall 可独立设置。 */
+    recall?: boolean | null;
+}
+export interface SessionModeSetResponse {
+    sessionId: string;
+    mode: MemoryMode;
+    /** 设置后的覆盖态(null = 跟随全局)。 */
+    recall: boolean | null;
+    /** 设置后的注入生效值(client 面文直接消费;清除覆盖后由 host 告知解析结果)。 */
+    recallResolved: boolean;
+}
+/** dsh-memory/session-stats(悬浮卡信息区;热路径端点)。 */
+export interface SessionStatsRequest {
+    sessionId: string;
+}
+/** 蒸馏管线会话视图(runner 投影,lastDistillAt 已转 ISO)。 */
+export interface SessionDistillView {
+    pendingSlice: number;
+    parkedSlices: number;
+    threshold: number | null;
+    producedRecords: number;
+    lastDistillAt: string | null;
+}
+export type SessionStatsResponse = {
+    supported: false;
+} | {
+    supported: true;
+    sessionId: string;
+    mode: MemoryMode;
+    defaultMode: MemoryMode;
+    /** 注入统计 + 生效位;enabled=false 时 reason 带短路序第一个为假因子
+     *  (deploy 部署上限 / global 全局开关 / session 会话只写 / mode 档位关闭)。 */
+    recall: {
+        enabled: boolean;
+        reason?: RecallDisabledReason;
+    } & RecallSessionStats;
+    /** 记忆上下文占用账本(未注入过的会话为 null)。 */
+    memoryOccupancy: MemoryOccupancy | null;
+    /** 旧会话回填:host 侧估出的双通道份额——召回按 live 会话 surface 现扫
+     *  (null = 会话不在 store),稳定区按当前组词折算。账本存在时客户端取两者较大值。 */
+    occupancyBackfill: {
+        recallTokens: number | null;
+        profileTokens: number;
+    } | null;
+    /** 主对话模型的官方声明上下文窗口(占用占比分母;null = 未声明/解析失败,UI 降级隐藏占比)。 */
+    contextWindowTokens: number | null;
+    distill: SessionDistillView;
+    l0Count: number;
+    retrieval: 'hybrid' | 'vector' | 'keyword' | 'none';
+    global: {
+        degraded: boolean;
+        pendingTotal: number;
+        lastExtractAt: string | null;
+    };
+};
+/** dsh-memory/settings-get */
+export interface SettingsGetResponse {
+    supported: boolean;
+    settings: MemoryLiveSettings;
+    /** 静态部署上限(cordis.patch.yml):运行时开关与它取 AND。 */
+    ceilings: {
+        capture: boolean;
+        distill: boolean;
+        recall: boolean;
+    };
+    effort: {
+        current: EffortChoice;
+        effective: EffortChoice;
+        fallback: EffortChoice;
+        options: string[];
+        route?: {
+            provider: string;
+            model: string;
+        };
+    };
+    budgets: {
+        current: DistillBudgets;
+        defaults: DistillBudgets;
+        effective: DistillBudgets;
+    };
+    inputBudget: {
+        current: number;
+        fallback: number;
+        effective: number;
+    };
+}
+/** dsh-memory/settings-set(patch 语义:只带要改的键)。 */
+export interface SettingsSetRequest {
+    enabled?: boolean;
+    capture?: boolean;
+    distill?: boolean;
+    recall?: boolean;
+    distillChain?: DistillChainEntry[];
+    /** 运行时按层路由链:逐层 patch(只带要改的层;空数组 = 该层回到跟随)。 */
+    distillLayerChains?: Partial<Record<LayerRouteKey, DistillChainEntry[]>>;
+    reasoningEffort?: EffortChoice;
+    distillProvider?: string;
+    distillModel?: string;
+    distillBudgets?: {
+        extract: number;
+        dedup: number;
+        l2: number;
+        l3: number;
+        graph: number;
+    };
+    distillMaxInputChars?: number;
+    /** 蒸馏通道运行时覆盖:'' = 跟随部署 config;'host' = 复用宿主;'direct' = 插件原生直连。 */
+    distillMode?: '' | 'host' | 'direct';
+    /** 运行时直连端点覆盖('direct' 用;非机密,可回显)。 */
+    directBaseURL?: string;
+    /** 运行时直连 API Key 覆盖('direct' 用;属机密,写入后不回读、不落日志)。 */
+    directApiKey?: string;
+    /** 远程嵌入端点/模型运行时覆盖(非机密可回显)。 */
+    embedRemoteBaseURL?: string;
+    embedRemoteModel?: string;
+    /** 远程嵌入维度运行时覆盖(0 = 未配置)。 */
+    embedRemoteDimensions?: number;
+    /** 远程嵌入 API Key 运行时覆盖(属机密,写入后不回读、不落日志)。 */
+    embedRemoteApiKey?: string;
+    /** 记忆写删权限门(true = 允许写删工具与面板高权限删除)。 */
+    memoryMutate?: boolean;
+}
+export interface SettingsSetResponse {
+    ok: true;
+    settings: MemoryLiveSettings;
+}
+/** dsh-memory/list-records(记忆浏览器;hitToUiRecord 投影)。 */
+export interface ListRecordsRequest {
+    query?: string;
+    type?: string;
+    scene?: string;
+    /** Hall 过滤(metadata.hall == 该值;空 = 不过滤)。 */
+    hall?: string;
+    /** 1~200,默认 50。 */
+    limit?: number;
+    /** 0~1_000_000。 */
+    offset?: number;
+}
+/** 浏览器卡片字段(比 MemoryRecord 精简,去掉大 metadata;epoch→ISO、snake→camel)。 */
+export interface UiRecord {
+    id: string;
+    content: string;
+    type: string;
+    priority: number;
+    scene: string;
+    family: MemoryFamily | null;
+    /** Hall 标签(metadata.hall,可空)。 */
+    hall: string | null;
+    timestamps: string[];
+    createdAt: string | null;
+    updatedAt: string | null;
+    version: number;
+    sourceMessageIds: string[];
+    /** 检索相关度(列表路径无 score → null)。 */
+    score: number | null;
+}
+export interface ListRecordsResponse {
+    items: UiRecord[];
+    hasMore: boolean;
+    /** 列表路径给总数;检索路径无法便宜计数 → null。 */
+    total: number | null;
+    /** 检索单次上限截断(结果可能不完整)。 */
+    truncated: boolean;
+    /** 场景筛选下拉选项(仅 offset===0 时附带)。 */
+    scenes?: string[];
+}
+/** dsh-memory/records-delete(面板高权限删除指定记忆;须 memoryMutate 开启)。 */
+export interface RecordsDeleteRequest {
+    /** 要删除的 L1 record id 列表(≤200)。 */
+    ids: string[];
+}
+export interface RecordsDeleteResponse {
+    deleted: number;
+}
+/** dsh-memory/graph-search(图谱节点检索;紧凑节点卡)。 */
+export interface GraphSearchRequest {
+    /** 自然语言查询(≤4096 字符;空查询返回空)。 */
+    query?: string;
+    /** 1~20,默认 8。 */
+    limit?: number;
+}
+export interface GraphSearchResponse {
+    items: Array<{
+        node: GraphNode;
+        /** 排序分(仅排序语义,非事实置信度)。 */
+        score: number;
+        matchedFields: string[];
+        matchReason: string;
+    }>;
+}
+/** dsh-memory/graph-node-get(节点详情展开;悬挂 id 返回 node=null 不解析)。 */
+export interface GraphNodeGetRequest {
+    id: string;
+}
+export interface GraphNodeGetResponse {
+    node: GraphNode | null;
+    /** 与该节点相连的 active 边。 */
+    edges: GraphEdge[];
+}
+/** dsh-memory/scenes(两族拼接的混合视图)。 */
+export interface ScenesResponse {
+    items: Array<{
+        path: string;
+        family: MemoryFamily;
+        summary: string;
+        updated: string;
+        heat: number;
+        content: string;
+    }>;
+}
+/** dsh-memory/persona(两族以 family 注释 + 分隔线拼接)。 */
+export interface PersonaResponse {
+    content: string;
+}
+/** dsh-memory/log-tail */
+export interface LogTailRequest {
+    /** 1~1000,默认 200。 */
+    lines?: number;
+}
+export interface LogTailResponse {
+    lines: string[];
+}
+/** dsh-memory/rebuild-* */
+export type RebuildStatusResponse = {
+    supported: false;
+    running: false;
+    phase: 'idle';
+} | RebuildStatus;
+/** dsh-memory/ruminate-* */
+export type RuminateStatusResponse = {
+    supported: false;
+    running: false;
+    phase: 'idle';
+} | RuminateStatus;
+/** dsh-memory/llm-providers(蒸馏路由链编辑器数据源)。 */
+/** 生效链条目:effort 与 DistillChainEntry.reasoningEffort 不同名不合并(链上两种条目形状的事实)。 */
+export interface EffectiveChainRoute {
+    provider: string;
+    model: string;
+    effort: string;
+}
+/** 按层层链视图:runtime = 设置页运行时层链(pinned 下不生效,视图照实返回存量);
+ *  static = 部署 YAML layerRoutes;effectiveChain = 该层实际链(层链完整替换,或跟随全局时
+ *  与全局链同值);source 三态:runtime 接管 / static 生效 / global 跟随全局解析。 */
+export interface LayerChainView {
+    runtime: DistillChainEntry[];
+    static: StaticFallbackEntry[];
+    effectiveChain: EffectiveChainRoute[];
+    source: 'runtime' | 'static' | 'global';
+}
+export interface LlmProvidersResponse {
+    supported: true;
+    providers: Array<{
+        id: string;
+        name: string;
+    }>;
+    default: {
+        provider: string;
+        model: string;
+    } | null;
+    /** 部署静态 pin(provider+model 双字段)优先于运行时选择,UI 据此禁用选择器。 */
+    pinned: boolean;
+    current: {
+        provider: string;
+        model: string;
+    };
+    /** 所选供应商是否仍在已注册路由中(用户删掉供应商后提示回退)。 */
+    currentRegistered: boolean;
+    effective: {
+        provider: string;
+        model: string;
+    } | null;
+    chain: {
+        current: DistillChainEntry[];
+        static: StaticFallbackEntry[];
+        effectiveChain: EffectiveChainRoute[];
+        source: 'runtime' | 'static';
+    };
+    /** 按层层链(l1/l2/l3;l1 同管抽取+去重两个调用点)。 */
+    layerChains: Record<LayerRouteKey, LayerChainView>;
+    /** 蒸馏通道视图(direct 解耦通道的运行时/部署态)。apiKey 不回传明文,只给布尔。 */
+    channel: DirectChannelView;
+}
+/** 蒸馏通道视图(llm-providers 的 channel 块数据源)。 */
+export interface DirectChannelView {
+    /** 运行时覆盖档:'' = 跟随部署 config;'host'/'direct' = 运行时锁定。 */
+    runtime: '' | 'host' | 'direct';
+    /** 实际生效档(runtime override → 部署 cfg.llm.mode,缺省 'host')。 */
+    effective: 'host' | 'direct';
+    /** 运行时直连端点覆盖值(settings 存;非机密可回显)。 */
+    runtimeBaseURL: string;
+    /** 部署直连端点(cfg.llm.baseURL,供「跟随部署」预览)。 */
+    deployedBaseURL: string;
+    /** 部署通道档(cfg.llm.mode)。 */
+    deployed: 'host' | 'direct';
+    /** 运行时直连 apiKey 是否已填(明文不回传)。 */
+    runtimeApiKeySet: boolean;
+    /** 部署直连 apiKey 是否已配置(cfg.llm.apiKey 非空?)。 */
+    deployedApiKeySet: boolean;
+    /** 生效为 direct 时是否配置齐(directBaseURL+model 都非空);未齐时给 tooltip 提示。 */
+    directReady: boolean;
+}
+/** dsh-memory/llm-models */
+export interface LlmModelsRequest {
+    provider: string;
+}
+/** 模型条目(附思考档位能力表,探询失败/未声明 → 空表)。 */
+export interface ModelWithEfforts {
+    id: string;
+    name: string;
+    description: string | null;
+    efforts: string[];
+}
+export interface LlmModelsResponse {
+    provider: string;
+    models: ModelWithEfforts[];
+}
+/** dsh-memory/embedding-state-get */
+export type EmbeddingStateResponse = {
+    supported: false;
+} | ({
+    supported: true;
+} & EmbeddingStateView);
+/** dsh-memory/embedding-source-set */
+export interface EmbeddingSourceSetRequest {
+    source: EmbeddingSourceKind;
+    activeModel?: string | null;
+}
+export interface EmbeddingSourceSetResponse {
+    accepted: true;
+}
+/** dsh-memory/embedding-download-start */
+export interface EmbeddingDownloadStartRequest {
+    modelId: string;
+}
+export interface EmbeddingDownloadStartResponse {
+    accepted: true;
+}
+/** dsh-memory/embedding-download-cancel | runtime-cancel | reindex-cancel */
+export interface EmbeddingCancelResponse {
+    cancelled: boolean;
+}
+/** dsh-memory/embedding-model-delete */
+export interface EmbeddingModelDeleteRequest {
+    modelId: string;
+}
+export interface EmbeddingModelDeleteResponse {
+    ok: boolean;
+    error?: string;
+}
+export interface DshMemoryRequestMap {
+    'dsh-memory/stats': Record<string, never>;
+    'dsh-memory/token-cost': TokenCostRequest;
+    'dsh-memory/session-mode-get': SessionModeGetRequest;
+    'dsh-memory/session-mode-set': SessionModeSetRequest;
+    'dsh-memory/session-stats': SessionStatsRequest;
+    'dsh-memory/settings-get': Record<string, never>;
+    'dsh-memory/settings-set': SettingsSetRequest;
+    'dsh-memory/list-records': ListRecordsRequest;
+    'dsh-memory/records-delete': RecordsDeleteRequest;
+    'dsh-memory/graph-search': GraphSearchRequest;
+    'dsh-memory/graph-node-get': GraphNodeGetRequest;
+    'dsh-memory/scenes': Record<string, never>;
+    'dsh-memory/persona': Record<string, never>;
+    'dsh-memory/log-tail': LogTailRequest;
+    'dsh-memory/rebuild-status': Record<string, never>;
+    'dsh-memory/rebuild-start': Record<string, never>;
+    'dsh-memory/rebuild-cancel': Record<string, never>;
+    'dsh-memory/ruminate-status': Record<string, never>;
+    'dsh-memory/ruminate-start': Record<string, never>;
+    'dsh-memory/ruminate-cancel': Record<string, never>;
+    'dsh-memory/llm-providers': Record<string, never>;
+    'dsh-memory/llm-models': LlmModelsRequest;
+    'dsh-memory/embedding-state-get': Record<string, never>;
+    'dsh-memory/embedding-source-set': EmbeddingSourceSetRequest;
+    'dsh-memory/embedding-download-start': EmbeddingDownloadStartRequest;
+    'dsh-memory/embedding-download-cancel': Record<string, never>;
+    'dsh-memory/embedding-model-delete': EmbeddingModelDeleteRequest;
+    'dsh-memory/embedding-runtime-cancel': Record<string, never>;
+    'dsh-memory/embedding-reindex-cancel': Record<string, never>;
+}
+export interface DshMemoryResponseMap {
+    'dsh-memory/stats': StatsResponse;
+    'dsh-memory/token-cost': TokenCostResponse;
+    'dsh-memory/session-mode-get': SessionModeGetResponse;
+    'dsh-memory/session-mode-set': SessionModeSetResponse;
+    'dsh-memory/session-stats': SessionStatsResponse;
+    'dsh-memory/settings-get': SettingsGetResponse;
+    'dsh-memory/settings-set': SettingsSetResponse;
+    'dsh-memory/list-records': ListRecordsResponse;
+    'dsh-memory/records-delete': RecordsDeleteResponse;
+    'dsh-memory/graph-search': GraphSearchResponse;
+    'dsh-memory/graph-node-get': GraphNodeGetResponse;
+    'dsh-memory/scenes': ScenesResponse;
+    'dsh-memory/persona': PersonaResponse;
+    'dsh-memory/log-tail': LogTailResponse;
+    'dsh-memory/rebuild-status': RebuildStatusResponse;
+    'dsh-memory/rebuild-start': RebuildStatus;
+    'dsh-memory/rebuild-cancel': RebuildStatus;
+    'dsh-memory/ruminate-status': RuminateStatusResponse;
+    'dsh-memory/ruminate-start': RuminateStatus;
+    'dsh-memory/ruminate-cancel': RuminateStatus;
+    'dsh-memory/llm-providers': LlmProvidersResponse;
+    'dsh-memory/llm-models': LlmModelsResponse;
+    'dsh-memory/embedding-state-get': EmbeddingStateResponse;
+    'dsh-memory/embedding-source-set': EmbeddingSourceSetResponse;
+    'dsh-memory/embedding-download-start': EmbeddingDownloadStartResponse;
+    'dsh-memory/embedding-download-cancel': EmbeddingCancelResponse;
+    'dsh-memory/embedding-model-delete': EmbeddingModelDeleteResponse;
+    'dsh-memory/embedding-runtime-cancel': EmbeddingCancelResponse;
+    'dsh-memory/embedding-reindex-cancel': EmbeddingCancelResponse;
+}
+/** 全部端点名(client 调用与 host case 表的共用字面量来源)。 */
+export type DshMemoryEndpoint = keyof DshMemoryResponseMap;