dsh-prime-memory 0.22.2 → 0.24.1

package/dist/pipeline/ruminate.js

@@ -1,4 +1,6 @@
+import { resolveDataDir } from '../config.js';
 import { InProcMemoryBackend } from '../store/memory-backend.js';
+import { syncFiles } from '../store/memory-md-sync.js';
 import { groupPendingBySession, loadPending, } from '../store/pending.js';
 import { errDetail } from '../util/filelog.js';
 import { runSceneConsolidation } from './l2.js';
@@ -49,6 +51,13 @@ export class RuminateController {
     pendingFile;
     /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
     roomRegistry;
+    /**
+     * 本轮起始时的库快照（id → updatedAt），供收尾算「本轮新增/变更」增量集（task_2.8）。
+     * `undefined` = 本轮没拍（投射门未开或拍失败）→ 收尾一律不做全库重导。
+     */
+    mdBaseline;
+    /** 投射旁路失败累计次数（只 warn 不抛，计数供诊断/测试读取）。 */
+    mdFailures = 0;
     /** 记忆后端:未注入时包 l1(进程内,行为与改造前等价)。 */
     backend() {
         return this.stores.backend ?? new InProcMemoryBackend(this.stores.l1);
@@ -90,6 +99,9 @@ export class RuminateController {
             this.sessions = groupSessions(buckets);
             this.cancelRequested = false;
             this.totalL1 = 0;
+            // md 投射基线（task_2.8）：两条收尾路径（finalize / doLightRefresh）共用同一份起点，
+            // 所以必须在这里拍——放在 `sessions.length === 0` 分支之前，轻量刷新才覆盖得到。
+            this.snapshotMdBaseline();
             if (this.sessions.length === 0) {
                 // 没有 pending 切片 → 做 L2/L3 轻量刷新
                 return await this.doLightRefresh();
@@ -275,6 +287,8 @@ export class RuminateController {
             catch (err) {
                 this.logger.warn(`[memory] 孤儿候选预标记失败(忽略): ${errDetail(err)}`);
             }
+            // md 投射收尾（task_2.8）：只导本轮新增/变更的记录；旁路，失败不影响本次产物。
+            await this.projectMd('反刍收尾');
             this.status.phase = 'done';
             this.finish(null);
         }
@@ -410,6 +424,9 @@ export class RuminateController {
         if (this.stores.slots !== undefined) {
             await migrateLegacySlots(this.stores.slots, this.stores.l1, this.cfg.slots.migrateLegacy === true, this.logger);
         }
+        // md 投射收尾（task_2.8）：与 finalize 同一动作的两个挂载点之一——历史教训是
+        // `sessions.length === 0` 走本路径，只挂 finalize 等于没挂。
+        await this.projectMd('轻量刷新');
         this.status.running = false;
         this.status.detail = null;
         this.status.phase = this.cancelRequested ? 'cancelled' : 'done';
@@ -418,6 +435,98 @@ export class RuminateController {
         this.logger.info(`[memory] 反刍轻量刷新结束(${this.status.phase}):${this.status.done}/${this.status.total} 步,耗时 ${Math.round(cost / 1000)}s`);
         return this.getStatus();
     }
+    /**
+     * 投射侧诊断计数（只增不减；不进任何端点，避开契约五处齐改的面）。
+     */
+    getMdFailures() {
+        return this.mdFailures;
+    }
+    /**
+     * 拍本轮起始基线（id → updatedAt）。三道门任一不满足就**一个动作都不做**：
+     * 连 `l1.all()` 都不调，这样“投射关着”时的产物与改动前逐字一致（本仓红线）。
+     *
+     * 为什么用基线 diff 而不是 `updatedAt >= startedAt`：relabel / 退场等改写走的是
+     * `patchMetadata` 那类最小写回，**不碰 `updated_time`**（它在快照哈希字段表里），
+     * 按时间戳筛会把这批真变了的记录漏掉。
+     */
+    snapshotMdBaseline() {
+        this.mdBaseline = undefined;
+        const exp = this.cfg.memExport;
+        if (exp === undefined || exp.enabled !== true)
+            return;
+        if (this.stores.mdLedger === undefined)
+            return;
+        try {
+            const map = new Map();
+            for (const r of this.stores.l1.all())
+                map.set(r.id, r.updatedAt);
+            this.mdBaseline = map;
+        }
+        catch (err) {
+            // 拍不上基线 = 本轮不投射（而不是退回全库重导）；旁路失败不拖垮反刍。
+            this.mdFailures++;
+            this.logger.warn(`[memory] 反刍 md 投射基线失败(本次不做投射): ${errDetail(err)}`);
+        }
+    }
+    /**
+     * 反刍收尾的增量 md 投射（task_2.8）：库 → 文件 + 账本 + 后缀对齐，**只碰本轮新增/变更的那批**。
+     *
+     * 与手动的 `dsh-memory/mem-export` 端点的区别：
+     * - 不跑命名回填（`assignMissingNames` 会写库，反刍是只读旁路，不能在那里改库）；
+     *   本轮新记录的 `name` 已在写入前由管线单一真源分配，未命名的按 `fileStemFor` 回落。
+     * - 不建类型目录骨架（`ensureTypeSkeleton`），那是面板显式触发的动作。
+     * 护栏全部复用 `cfg.memExport` 既有值（`maxRecords`/`timeBudgetMs`），**不新增配置项**。
+     *
+     * 一轮投射走 `syncFiles`（与 `L1Store` 钩子同一函数）：导出之后紧跟后缀收敛，
+     * 所以本轮被合并取代/冲突判负的增量记录不会停在未改名的 `.memory.md` 上。
+     *
+     * 失败面：整个方法自吞异常，只 warn + 计数，绝不抛给调用方、绝不改变反刍结果。
+     * @param stage - 日志里的路径名（区分 finalize 与轻量刷新两条挂载点）。
+     */
+    async projectMd(stage) {
+        const baseline = this.mdBaseline;
+        if (baseline === undefined)
+            return;
+        const exp = this.cfg.memExport;
+        const ledger = this.stores.mdLedger;
+        if (exp === undefined || exp.enabled !== true || ledger === undefined)
+            return;
+        try {
+            const changed = [];
+            for (const r of this.stores.l1.all()) {
+                const prev = baseline.get(r.id);
+                // 新 id（本轮蒸馏产出）或 updatedAt 变了（合并/改写）才算变更；其余不重导。
+                if (prev === undefined || prev !== r.updatedAt)
+                    changed.push(r);
+            }
+            if (changed.length === 0)
+                return;
+            const deps = {
+                exportCfg: () => ({
+                    enabled: exp.enabled === true,
+                    root: exp.root,
+                    maxRecords: exp.maxRecords,
+                    timeBudgetMs: exp.timeBudgetMs,
+                }),
+                dataDir: resolveDataDir(this.cfg),
+                ledger: () => this.stores.mdLedger,
+                logger: this.logger,
+            };
+            const out = await syncFiles(deps, changed);
+            if (out === undefined)
+                return;
+            const { exported: rep, suffix } = out;
+            this.logger.info(`[memory] 反刍 md 投射(${stage}):增量 ${changed.length} 条,写 ${rep.written},未变 ${rep.unchanged},跳过 ${rep.skipped},改名 ${suffix.renamed},落点 ${rep.root}${rep.capped ? `,预算用尽剩 ${rep.remaining} 个文件(下轮反刍继续)` : ''}`);
+        }
+        catch (err) {
+            this.mdFailures++;
+            this.logger.warn(`[memory] 反刍 md 投射失败(旁路忽略,不影响本次产物,累计 ${this.mdFailures} 次): ${errDetail(err)}`);
+        }
+        finally {
+            // 基线一次性消费：同一次运行不重投射同一批（两条挂载点互斥，这里只防异常复用）。
+            this.mdBaseline = undefined;
+        }
+    }
     finish(error) {
         this.status.running = false;
         this.status.detail = null;

package/dist/pipeline/runner.d.ts

@@ -30,6 +30,16 @@ export interface MemoryStores {
     state: StateStore;
     /** 图谱存储(可选:测试缝/未装配时图谱泵整体停用;GraphStore 自带降级 no-op)。 */
     graph?: GraphStore;
+    /**
+     * 派生数据搬运面（P0-d）：merge 后把使用史与人工标注搬到新 id。
+     * 只声明用到的那个方法（不拉整个类入参）——未装配时不搬，行为与改动前一致。
+     */
+    usage?: {
+        rekey(oldId: string, newId: string): boolean;
+    };
+    feedback?: {
+        rekey(oldId: string, newId: string): boolean;
+    };
 }
 /** 管线任务(优先级调度:live > graph > rebuild)。 */
 export interface PipelineTask {

package/dist/pipeline/runner.js

@@ -121,12 +121,17 @@ export function effectiveCfg(cfg, live) {
     const cfOverride = s?.conflictFreeze !== undefined
         ? { conflictFreeze: { ...(cfg.conflictFreeze ?? {}), enabled: s.conflictFreeze } }
         : null;
-    if (!override && !budgets && !maxInput && !fallbacksTakeover && !chainEffort && !chainFallbacks && !effortInject && !layerChains && !hasChannel && !embedOverride && !cfOverride)
+    // md 投射/后缀收敛的单次动作护栏运行时覆盖(0 = 跟随部署 cfg.memExport.maxRecords)。
+    // 只覆盖条数护栏，不动 enabled/root——开关与根路径仍属部署配置。
+    const mdx = s?.mdExportMaxRecords ?? 0;
+    const memExportOverride = mdx > 0 ? { memExport: { ...(cfg.memExport ?? {}), maxRecords: mdx } } : null;
+    if (!override && !budgets && !maxInput && !fallbacksTakeover && !chainEffort && !chainFallbacks && !effortInject && !layerChains && !hasChannel && !embedOverride && !cfOverride && !memExportOverride)
         return cfg;
     return {
         ...cfg,
         ...(embedOverride ?? {}),
         ...(cfOverride ?? {}),
+        ...(memExportOverride ?? {}),
         llm: {
             ...cfg.llm,
             ...(effortInject ?? {}),
@@ -662,7 +667,13 @@ export class MemoryRunner {
             // §E 写入侧工作区:后台蒸馏手上只有 sessionId(没有 exec),经
             // `ctx.get('agents')` 宽容解析——与 §A 的多级父链解析同一招。
             // 拿不到 → undefined → 归属回落 global(pipeline 侧 `resolveRecordScope` 兜底)。
-            sessionWorkspaceIdOf(this.ctx, sessionId), anchorMap);
+            sessionWorkspaceIdOf(this.ctx, sessionId), anchorMap, 
+            // 派生数据跟着搬（P0-d）：不搬等于每次合并把这条记忆的使用史与人工标注清零。
+            // 两个 sidecar 都是后装上的（`stores.usage` 在装配段才填），故在调用时点现取。
+            (oldId, newId) => {
+                this.stores.usage?.rekey(oldId, newId);
+                this.stores.feedback?.rekey(oldId, newId);
+            });
             if (!result.skipped) {
                 this.pending[mode] = rest;
                 // 重建轮(force)不是有机对话,不推进爬坡

package/dist/pipeline/workspace-relink.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 存量记忆的 workspace re-link（内容路由回填）。
+ *
+ * 为什么需要它：新写入的路由只覆盖此后产生的记忆，而库里已有的记录归属列全空
+ * （实测 1279 条活跃记录里 `workspace_id` 非空为 0）。不回填，「按项目看记忆」这件事
+ * 就永远只有增量、没有存量。
+ *
+ * 三条设计约束：
+ * 1. **只写 `workspace_id`，不动 `scope`、不动 `updated_time`**。前者保可见性零变化
+ *    （`cfg.scope='global'` 下 `isScopeVisible` 直接放行），后者保快照哈希零失配
+ *    （见 `store/sqlite.ts` 的 `setL1WorkspaceIds` 注释，三条硬约束都在那儿）。
+ * 2. **宁缺勿猜**：路由不命中的记录保持原样，绝不给一个"默认归属"。归错项目会让记忆
+ *    在错误的工作区可见/不可见，比不归难查得多。
+ * 3. **有界可重入**：照 `wing-backfill` 的双护栏 + 扫描阶段也查墙钟 + 剩余留待再次触发；
+ *    且因不写 `updated_time`，按更新时间倒序分页**不会边扫边漂**。
+ */
+import type { MemoryRecord } from '../types.js';
+import type { WorkspaceRoute } from '../workspace-route.js';
+/** re-link 需要的存储面（结构化声明，便于单测注入）。 */
+export interface RelinkStoreFace {
+    list(opts: {
+        limit: number;
+        offset: number;
+    }): {
+        items: MemoryRecord[];
+        total: number;
+    };
+    setWorkspaceIds(items: ReadonlyArray<{
+        id: string;
+        workspaceId: string;
+    }>): number;
+}
+export interface RelinkReport {
+    dryRun: boolean;
+    /** 扫过的记录数（含未命中）。 */
+    scanned: number;
+    /** 路由命中的记录数。 */
+    matched: number;
+    /** 归属已是目标值、无需写的记录数（幂等重跑时等于 matched）。 */
+    unchanged: number;
+    /** 干跑时“若真跑会写多少条”；真写时恒为 0（那一步看 written）。 */
+    toWrite: number;
+    /** 实际写入条数（dryRun 时恒为 0）。 */
+    written: number;
+    /** 因预算未处理、留待下次触发的条数。 */
+    remaining: number;
+    /** 命中记录按归属的分布（先看这个数就知道路由表合不合口味）。 */
+    byWorkspace: Record<string, number>;
+}
+export declare function relinkWorkspaces(deps: {
+    l1: RelinkStoreFace;
+    routes: readonly WorkspaceRoute[];
+    dryRun?: boolean;
+    maxRecords?: number;
+    timeBudgetMs?: number;
+    logger?: {
+        info: (m: string) => void;
+        warn: (m: string) => void;
+    };
+}): Promise<RelinkReport>;

package/dist/pipeline/workspace-relink.js

@@ -0,0 +1,73 @@
+import { routeWorkspace } from '../workspace-route.js';
+import { yieldLoop } from '../util/yield.js';
+const PAGE = 200;
+/** 攒够一批再写：一批一个事务，避免逐条开事务的 fsync 开销。 */
+const FLUSH = 500;
+export async function relinkWorkspaces(deps) {
+    const { l1, routes, logger } = deps;
+    const dryRun = deps.dryRun !== false; // 缺省干跑：先看报告，再决定真写
+    const maxRecords = Math.max(1, Math.floor(deps.maxRecords ?? 300));
+    const budgetMs = Math.max(1000, Math.floor(deps.timeBudgetMs ?? 120_000));
+    const started = Date.now();
+    const overBudget = () => Date.now() - started > budgetMs;
+    const report = {
+        dryRun, scanned: 0, matched: 0, unchanged: 0, toWrite: 0, written: 0, remaining: 0, byWorkspace: {},
+    };
+    if (routes.length === 0)
+        return report;
+    let offset = 0;
+    let batch = [];
+    // 计数在此结算：`flush()` 会清空 batch，调用点再拿 `batch.length` 必然归零。
+    const flush = () => {
+        if (batch.length === 0)
+            return;
+        if (dryRun)
+            report.toWrite += batch.length;
+        else
+            report.written += l1.setWorkspaceIds(batch);
+        batch = [];
+    };
+    for (;;) {
+        if (report.scanned >= maxRecords)
+            break;
+        // 扫描阶段本身也查墙钟：1279 条不慢，但同一个护栏要能扛住更大的库。
+        if (overBudget())
+            break;
+        const page = l1.list({ limit: PAGE, offset });
+        if (page.items.length === 0)
+            break;
+        for (const rec of page.items) {
+            // 上限检查必须在**循环顶部**：放在末尾时，未命中的记录会先 `continue` 掉，
+            // 于是 maxRecords=1 实际能扫 2 条（实测翻出）——有界性得对所有分支都成立。
+            if (report.scanned >= maxRecords)
+                break;
+            report.scanned++;
+            const routed = routeWorkspace(`${rec.content}\n${rec.scene_name}`, routes);
+            if (routed === undefined)
+                continue;
+            report.matched++;
+            report.byWorkspace[routed] = (report.byWorkspace[routed] ?? 0) + 1;
+            if (rec.workspaceId === routed) {
+                report.unchanged++;
+                continue;
+            }
+            batch.push({ id: rec.id, workspaceId: routed });
+            if (batch.length >= FLUSH)
+                flush();
+        }
+        offset += page.items.length;
+        if (offset >= page.total)
+            break;
+        await yieldLoop(); // 让出事件循环：面板 RPC / 状态查询优先
+    }
+    flush();
+    // 剩余 = 总数 - 实扫条数。**不能用 offset 算**：中途按 maxRecords/预算 break 时，
+    // offset 已推进整个页（一页 PAGE 条），会把“还剩 2 条没扫”算成 0，
+    // 于是报告谎称已扫完——下次也就不会再触发续扫了。
+    const totalRows = l1.list({ limit: 1, offset: 0 }).total;
+    report.remaining = Math.max(0, totalRows - report.scanned);
+    logger?.info(`[memory] workspace re-link${dryRun ? '(干跑)' : ''}：扫 ${report.scanned} 条，命中 ${report.matched} 条，`
+        + `待写 ${report.toWrite} 条，实写 ${report.written} 条，`
+        + `剩 ${report.remaining} 条未扫(下次触发续)；分布 ${JSON.stringify(report.byWorkspace)}`);
+    return report;
+}

package/dist/projection/recall.d.ts

@@ -1,9 +1,14 @@
 /**
  * 会话「活召回集」服务端投影(memoryRecall)。
  *
- * 语义：本会话**已注入、且目前仍在上下文里**的记忆（= 模型此刻真正看到的几条）。
- * 上下文被压缩/清空时注入内容离开模型，集合随之清空——数据源是
- * `SessionRecalledStore`（sessionKey 键、写穿持久化），所以**旧会话重开也读得到**。
+ * 语义：本会话**已注入**的记忆，以及其中「此刻仍在上下文里」的那部分。
+ * 数据源是 `SessionRecalledStore`（sessionKey 键、写穿持久化），所以**旧会话重开也读得到**。
+ *
+ * 压缩/清空对这张表的作用不同（2026-10-13 用户口径）：
+ * - `clear`（主动清空）整表清，view 随之空；
+ * - `compact`（摘要替换）**不删条目**，只把当时在列表里的那批标成 `superseded`（正文已被
+ *   摘要取代、已不在上下文里）。读侧据此把旧召回与当前召回区分开，而不是继续谎报“还在”。
+ *   已退场（`retired`）的条目必须留在列表里（人的裁决凭证），取代标记与它正交。
  *
  * 与 memorySlots 的分工（两条轴，互不替代）：
  * - `memorySlots` = 用户手动 pin 的**常驻约定**（每轮硬注入，注册表语义）；
@@ -19,6 +24,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { SessionRecalledStore } from '../store/session-recalled.js';
+import type { MemoryRecord } from '../types.js';
 export declare const MEMORY_RECALL_KEY = "memoryRecall";
 /** view 最多透出条数（最近在上；超出部分只计入 count，防 wire 体量失控）。 */
 export declare const RECALL_VIEW_CAP = 20;
@@ -31,13 +37,44 @@ export interface RecallItemView {
     priority: number;
     /** 使用场景（metadata.dsh_usage_scenario）；无则缺席（附加字段，旧帧没有也整条通过）。 */
     scenario?: string[];
+    /**
+     * 人给的最近一次打分(-1..5)；未标注则缺席。
+     * 卡片靠它把已打的那一笔显示成选中态；均值等细粒度数据走 `session-recalled` 端点。
+     */
+    rating?: number;
+    /**
+     * 正文全文（截断至 BODY_MAX）；消费方悬停泡泡直接读它，不再回查端点。
+     * 缺席 = 旧帧（读侧退化成只显示 title）。
+     */
+    body?: string;
+    /**
+     * 该记录已被判定过时（`isRetired`）。只写 true：未退场时字段缺席，
+     * 读侧按「缺席即活跃」处理，旧帧自然兼容。
+     */
+    retired?: true;
+    /**
+     * 该条目的正文**已被摘要取代**（压缩发生时时它就在列表里），即不在模型上下文里了。
+     * 只写 true（同 `retired` 的兼容手法）；与 `retired` 正交，两者可共存。
+     * 读侧据此把「已被摘要取代的旧召回」与「此刻仍在上下文里的召回」区分开。
+     */
+    superseded?: true;
 }
 /** 持久态：本会话的活召回 id 集 + 判脏序号。 */
 export interface RecallProjectionState {
     rev: number;
+    /**
+     * 反馈 sidecar 的序号（打分也会让 view 变：条目要显示已打的那一笔）。
+     * 可选：旧 checkpoint 帧里没这个字段，读侧必须容忍。
+     */
+    fb?: number;
     sessionId: string;
     /** 注入序（旧→新），由 store 保证。 */
     ids: string[];
+    /**
+     * 已被摘要取代的 id（压缩水位之上的那批）。可选：旧 checkpoint 没有这个字段，
+     * 读侧必须容忍（缺席 = 无取代，与改动前逐字一致）。
+     */
+    superseded?: string[];
 }
 /** wire view：count 是总数，items 是**最近在上**的截断视图。 */
 export interface RecallView {
@@ -54,21 +91,22 @@ interface SchemaLike<T> {
 export declare const stateSchema: SchemaLike<RecallProjectionState>;
 /** view 校验（出网前调用；未知键容忍，同 slots 投影的语义边界）。 */
 export declare const viewSchema: SchemaLike<RecallView>;
-/** 投影需要的 L1 只读面（结构化声明，避免跨模块类型耦合）。 */
+/** 投影需要的 L1 只读面（结构化声明，避免跨模块类型耦合）。
+ *  判退场要 `validTo`/`metadata`，故直接 Pick 自 MemoryRecord，不在投影里自写时间比较。 */
 export interface RecallL1Face {
-    getByIds(ids: string[]): Array<{
-        id: string;
-        type: string;
-        content: string;
-        priority: number;
-        metadata?: Record<string, unknown>;
-    }>;
+    getByIds(ids: string[]): Array<Pick<MemoryRecord, 'id' | 'type' | 'content' | 'priority' | 'metadata' | 'validTo'>>;
+}
+/** 投影需要的反馈只读面（缺席 = view 不带 rating，旧行为）。 */
+export interface RecallFeedbackFace {
+    revision(): number;
+    lastOf(id: string): number | undefined;
 }
 /**
  * 注册 memoryRecall 投影。
  *
  * 缺席降级同 slots 投影：`ctx.inject` 在服务未提供时不回调；形状不符静默不注册。
- * apply 是 O(1) 判脏（store.revision() 比对），任意已提交事件都会带进来看一眼。
+ * apply 是 O(1) 判脏（store.revision() 与反馈序号比对），任意已提交事件都会带进来看一眼。
+ * @param feedback - 相关度反馈只读面；缺席时 view 不带 rating（旧行为）。
  */
-export declare function registerRecallProjection(ctx: Context, store: SessionRecalledStore, l1?: RecallL1Face): void;
+export declare function registerRecallProjection(ctx: Context, store: SessionRecalledStore, l1?: RecallL1Face, feedback?: RecallFeedbackFace): void;
 export {};

package/dist/projection/recall.js

@@ -1,8 +1,11 @@
+import { isRetired } from '../store/supersede.js';
 export const MEMORY_RECALL_KEY = 'memoryRecall';
 /** view 最多透出条数（最近在上；超出部分只计入 count，防 wire 体量失控）。 */
 export const RECALL_VIEW_CAP = 20;
 /** 单条标题（正文首行）最大长度。 */
 const TITLE_MAX = 160;
+/** 单条全文最大长度（泡泡里显示的正文；超出截断并补省略号，防 wire 体量失控）。 */
+const BODY_MAX = 700;
 function invalid(what, detail) {
     throw new Error(`${what}: ${detail}`);
 }
@@ -31,6 +34,11 @@ export const stateSchema = {
         if (!Array.isArray(root.ids))
             invalid(what, 'ids 必须是字符串数组');
         root.ids.forEach((id, i) => requireString(id, `${what}.ids[${i}]`, 'id'));
+        if (root.superseded !== undefined) {
+            if (!Array.isArray(root.superseded))
+                invalid(what, 'superseded 必须是字符串数组');
+            root.superseded.forEach((id, i) => requireString(id, `${what}.superseded[${i}]`, 'id'));
+        }
         return value;
     },
 };
@@ -56,6 +64,15 @@ export const viewSchema = {
                     invalid(at, 'scenario 必须是字符串数组');
                 item.scenario.forEach((s, j) => requireString(s, `${at}.scenario[${j}]`, 'scenario'));
             }
+            if (item.rating !== undefined && typeof item.rating !== 'number')
+                invalid(at, 'rating 必须是数字');
+            // 附加字段：旧帧没有 → 容忍；有 → 必须成形状。retired 只认 true，false 视为脏帧。
+            if (item.body !== undefined)
+                requireString(item.body, at, 'body');
+            if (item.retired !== undefined && item.retired !== true)
+                invalid(at, 'retired 只能是 true 或缺席');
+            if (item.superseded !== undefined && item.superseded !== true)
+                invalid(at, 'superseded 只能是 true 或缺席');
         });
         return value;
     },
@@ -66,14 +83,22 @@ function firstLine(content) {
     const trimmed = line.trim();
     return trimmed.length > TITLE_MAX ? trimmed.slice(0, TITLE_MAX) : trimmed;
 }
+/** 正文全文 → 泡泡用（去首尾空白，超长截断补省略号）。 */
+function clampBody(content) {
+    const s = content.trim();
+    return s.length > BODY_MAX ? `${s.slice(0, BODY_MAX)}…` : s;
+}
 /** 读 store 建态；ids 与旧态一致时返回旧引用（避免无谓 republish）。 */
-function buildState(sessionId, store, prev) {
+function buildState(sessionId, store, feedbackRev, prev) {
     const ids = store.list(sessionId);
-    if (prev !== undefined && prev.rev === store.revision() && sameIds(prev.ids, ids))
+    const superseded = [...store.supersededOf(sessionId)];
+    const sameCounters = prev !== undefined && prev.rev === store.revision() && (prev.fb ?? 0) === feedbackRev;
+    if (sameCounters && sameIds(prev.ids, ids) && sameIds(prev.superseded ?? [], superseded))
         return prev;
-    const next = { rev: store.revision(), sessionId, ids };
-    // rev 变了但本会话集合没变（别的会话写了）→ 仍复用旧引用，防跨会话 thrash。
-    if (prev !== undefined && prev.sessionId === sessionId && sameIds(prev.ids, ids))
+    const next = { rev: store.revision(), fb: feedbackRev, sessionId, ids, superseded };
+    // rev 变了但本会话集合、取代集与反馈都没变（别的会话写了）→ 仍复用旧引用，防跨会话 thrash。
+    if (prev !== undefined && prev.sessionId === sessionId && sameIds(prev.ids, ids)
+        && sameIds(prev.superseded ?? [], superseded) && (prev.fb ?? 0) === feedbackRev)
         return prev;
     return next;
 }
@@ -87,13 +112,14 @@ function sameIds(a, b) {
 }
 /** view 引用稳定：同一 state 恒返回同一对象（registry 按 Object.is 判发布）。 */
 const viewMemo = new WeakMap();
-function makeView(state, l1) {
+function makeView(state, l1, feedback) {
     const memoized = viewMemo.get(state);
     if (memoized !== undefined)
         return memoized;
     const recentFirst = [...state.ids].reverse();
     const picked = recentFirst.slice(0, RECALL_VIEW_CAP);
     const byId = new Map((l1?.getByIds(picked) ?? []).map((r) => [r.id, r]));
+    const superseded = new Set(state.superseded ?? []);
     const items = [];
     for (const id of picked) {
         const r = byId.get(id);
@@ -102,12 +128,19 @@ function makeView(state, l1) {
         const scenario = Array.isArray(r.metadata?.dsh_usage_scenario)
             ? r.metadata?.dsh_usage_scenario
             : undefined;
+        const rating = feedback?.lastOf(id);
         items.push({
             id: r.id,
             type: r.type,
             title: firstLine(r.content),
             priority: r.priority,
+            body: clampBody(r.content),
             ...(scenario !== undefined && scenario.length > 0 ? { scenario } : {}),
+            ...(typeof rating === 'number' ? { rating } : {}),
+            // 退场记录仍留在列表里（文本曾是上下文的一部分，且判过时是人的裁决凭证），只是该打上删除线。
+            ...(isRetired(r) ? { retired: true } : {}),
+            // 已被摘要取代：正文已不在上下文里。与 retired 正交，两者可同时在。
+            ...(superseded.has(id) ? { superseded: true } : {}),
         });
     }
     const next = { rev: state.rev, sessionId: state.sessionId, count: state.ids.length, items };
@@ -125,22 +158,24 @@ function sessionIdOf(header) {
  * 注册 memoryRecall 投影。
  *
  * 缺席降级同 slots 投影：`ctx.inject` 在服务未提供时不回调；形状不符静默不注册。
- * apply 是 O(1) 判脏（store.revision() 比对），任意已提交事件都会带进来看一眼。
+ * apply 是 O(1) 判脏（store.revision() 与反馈序号比对），任意已提交事件都会带进来看一眼。
+ * @param feedback - 相关度反馈只读面；缺席时 view 不带 rating（旧行为）。
  */
-export function registerRecallProjection(ctx, store, l1) {
+export function registerRecallProjection(ctx, store, l1, feedback) {
     ctx.inject(['sessionProjections'], (injected) => {
         const registry = injected.sessionProjections;
         if (registry === undefined || typeof registry.register !== 'function')
             return;
+        const fbRev = () => feedback?.revision() ?? 0;
         // 双代平面（同 slots 投影）：0.1.0-rc.8 的 registry 走平面 schema/view，0.1.1+ 走 wire。
         const definition = {
             key: MEMORY_RECALL_KEY,
             stateSchema,
-            init: (header) => buildState(sessionIdOf(header), store),
-            apply: (state) => buildState(state.sessionId, store, state),
-            wire: { viewSchema, view: (state) => makeView(state, l1) },
+            init: (header) => buildState(sessionIdOf(header), store, fbRev()),
+            apply: (state) => buildState(state.sessionId, store, fbRev(), state),
+            wire: { viewSchema, view: (state) => makeView(state, l1, feedback) },
             schema: viewSchema,
-            view: (state) => makeView(state, l1),
+            view: (state) => makeView(state, l1, feedback),
             stateVersion: 0,
         };
         registry.register(definition);

package/dist/prompts/examples.d.ts

@@ -0,0 +1,73 @@
+/** 示例集总长预算（字符）。超了就该减条数，而不是悄悄放宽。 */
+export declare const FEW_SHOT_BUDGET = 1400;
+/** 一条止例：会话片段 → 模型该产出的 title/content 对。 */
+interface GoodExample {
+    /** 类型（与 G2 骨架同名，方便对照）。 */
+    type: string;
+    title: string;
+    content: string;
+}
+/**
+ * 止例集。每条的 content 都按 G2 骨架写成"前因后果"，title 是它的名词短语摘要。
+ *
+ * 刻意覆盖到 title 的四种难头：含英文标识符（吃字符额度）、含数字（容易被当 id 残片）、
+ * 纯中文短语、以及"主语是团队/用户"的正当名词短语（这几个词作**短语**开头是合法的，
+ * 只有叙述引子才算话头）。
+ */
+export declare const TITLE_GOOD_EXAMPLES: readonly GoodExample[];
+/** 反例：模型最常犯的三种错，各给一条"不要这样"。 */
+export declare const TITLE_BAD_EXAMPLES: ReadonlyArray<{
+    title: string;
+    why: string;
+}>;
+/** 供用例与提示词共用：把止例渲染成"输入 → 输出对象"的示范块。 */
+export declare function renderGoodExample(g: GoodExample): string;
+/**
+ * 追加到抽取系统提示尾部的示例段。
+ *
+ * 只在 `cfg.naming.fewShot` 为真时拼上（默认关）：它每轮都收固定成本，值不值要靠
+ * A/B 的 fallback 率说话，不能靠"看起来更专业"。
+ */
+export declare const EXTRACTION_FEW_SHOT: string;
+/**
+ * 各类型的"前因后果"要素表（照 G2 `NARRATIVE_CLAUSE` 写，不另造一套定义）。
+ *
+ * 为什么需要它：可用性判据是用户定的——"content 没前因后果、写不全就不算可用"。
+ * 那句活若只留在提示词里就永远没法判定、也没法拿它定默认值，所以每个类型拆 3 个要素，
+ * 每个要素给一组词元（命中任一即算在）。
+ *
+ * **这是关键词启发式，不是语义判定**：要素换个说法就接不住；G2 自己也允许"信息不足则省略该节"。
+ * 因此它只能用于**同一输入下两臂相对比较**，不能当绝对质量分。
+ */
+export declare const SKELETON_ELEMENTS: Readonly<Record<string, ReadonlyArray<{
+    name: string;
+    anyOf: readonly string[];
+}>>>;
+/** 骨架打分结果。 */
+export interface SkeletonScore {
+    类型: string;
+    要素数: number;
+    命中数: number;
+    缺: string[];
+    /** 所有要素都命中（且正文非空）。 */
+    齐备: boolean;
+    /** 该类型不在要素表里（分数仅供参考，不拿它下结论）。 */
+    无表可依: boolean;
+}
+/**
+ * 按类型给 content 打骨架分（关键词启发式，局限见 {@link SKELETON_ELEMENTS}）。
+ *
+ * @param type - 记忆类型。
+ * @param content - 模型产出的正文。
+ * @returns 命中情况；空正文算 0 命中而不是"齐备"。
+ */
+export declare function scoreSkeleton(type: string, content: string): SkeletonScore;
+/** 自检：示例本身是否合格（用例直接吃这个函数，不在用例里手抄判据）。 */
+export declare function auditFewShot(): {
+    超预算: boolean;
+    长度: number;
+    不合格title: string[];
+    抄content开头: string[];
+    止例骨架不全: string[];
+};
+export {};