dsh-prime-memory 0.22.2 → 0.24.0

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

@@ -662,7 +662,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 {};

package/dist/prompts/examples.js

@@ -0,0 +1,178 @@
+/**
+ * 名称蒸馏（Phase 3）的标准格式示例集。
+ *
+ * 为什么必须有示例而不是只给定义：只写"6–14 字名词短语"这句散文，模型就是照着它自由
+ * 发挥——真机 `deriveName` 那批名字正是"看起来像定义、实际是句子残片"。示例是唯一能让
+ * 模型看清 **title 与 content 边界**的形状：两者必须在同一个例子里并列可见。
+ *
+ * 三条硬约束（都有对应用例钉着，不靠自觉）：
+ * 1. **每个止例的 title 都必须过 `validateTitle`**——否则等于示范一个会被自己闸门拒掉的名字；
+ * 2. **每个止例的 content 都必须就是 `narrativeTemplates`（G2）那套骨架的产物**——否则同时开
+ *    两个开关时，模型在一份提示里看到两套互相矛盾的示范；
+ * 3. **总长有预算上限**：这份示例每轮蒸馏都要付，是固定成本，不是免费午餐。
+ *
+ * 反例同样必要：模型最容易犯的三类错（抄句首、塞路径、留话头）各给一条"不要这样"。
+ */
+import { NAME_MAX, validateTitle } from '../util/md-name.js';
+/** 示例集总长预算（字符）。超了就该减条数，而不是悄悄放宽。 */
+export const FEW_SHOT_BUDGET = 1400;
+/**
+ * 止例集。每条的 content 都按 G2 骨架写成"前因后果"，title 是它的名词短语摘要。
+ *
+ * 刻意覆盖到 title 的四种难头：含英文标识符（吃字符额度）、含数字（容易被当 id 残片）、
+ * 纯中文短语、以及"主语是团队/用户"的正当名词短语（这几个词作**短语**开头是合法的，
+ * 只有叙述引子才算话头）。
+ */
+export const TITLE_GOOD_EXAMPLES = [
+    {
+        type: 'work_fact',
+        title: 'npm发布必须显式指定registry',
+        content: '结论：npm publish 必须显式带 --registry=https://registry.npmjs.org。依据：默认 registry 指向镜像时发布打到镜像会失败或错投，本机 ~/.npmrc 实测如此。适用范围：所有对外发包；镜像有同步延迟，view 也必须钉源。',
+    },
+    {
+        type: 'work_method',
+        title: '记忆改名后的孤儿文件归档流程',
+        content: '目标：把改名后无人认领的投射文件收掉，避免活档案堆积。步骤：先按账本双指纹判定谁变了，回灌或重写使两侧一致，再扫描账本键与记录落点的差集，把孤儿搬进归档目录（不删，保留相对形状）。注意：来路不明的文件一律不动，那可能是人放进来等着同步的输入。',
+    },
+    {
+        type: 'work_task',
+        title: '六线宿主兼容冒烟任务状态',
+        content: '任务：为 dsh 插件做六线宿主冒烟。当前状态：0.2.0 与 0.1.7 两线已跑通，其余四线未跑。下一步/阻塞：需要保留场格子里的凭据刷新，负责人为仓库维护者，截止未定。',
+    },
+    {
+        type: 'work_artifact',
+        title: '宿主子系统解读文档集',
+        content: '交付物：宿主内部架构的 digest 分片文档集。位置：仓库 docs 目录下的模块化分片。用途/结论：给插件作者定位"要改哪一层"，源码锚点侧车标注 file:line 与对应宿主版本。',
+    },
+    {
+        type: 'instruction',
+        title: '修改用户环境前须确认可逆性与影响范围',
+        content: '规则：任何改动用户环境（配置、依赖、profile、运行中实例）之前必须先说明可逆性与爆炸范围并获确认。触发时机：需要重启服务、改写配置、安装依赖、发布到 registry 时。反例/边界：只读取证与临时目录内的自检不受此限，不必为读操作索要许可。',
+    },
+    {
+        type: 'persona',
+        title: '偏好短命令先行后解释的沟通风格',
+        content: '偏好：回复要先给可执行的下一步，再给理由。表现：长铺垫会被打断，明确要求"别写前言和收尾"。强度：跨多个会话稳定成立，属硬性偏好。',
+    },
+];
+/** 反例：模型最常犯的三种错，各给一条"不要这样"。 */
+export const TITLE_BAD_EXAMPLES = [
+    { title: '用户要求以后所有 npm publish 必须显式带参数', why: '是个句子，且以叙述引子开头——title 回答"讲的是什么"，不是"谁说了什么"' },
+    { title: '保存到 docs/report.md 的调研结论', why: '含路径分隔符，且"保存到…"是动作不是主题' },
+    { title: '会话-session-44332549-f05e', why: '残留 id 片段，换一批记录就换个名字，不能当身份' },
+];
+/** 止例里最不该出现的一件事：title 直接抄 content 开头。挑一条做自检。 */
+function copiesContentStart(g) {
+    const c = g.content.trim();
+    return c.startsWith(g.title) || g.title.length >= NAME_MAX;
+}
+/** 供用例与提示词共用：把止例渲染成"输入 → 输出对象"的示范块。 */
+export function renderGoodExample(g) {
+    return `type=${g.type}\ntitle：${g.title}\ncontent：${g.content}`;
+}
+/**
+ * 追加到抽取系统提示尾部的示例段。
+ *
+ * 只在 `cfg.naming.fewShot` 为真时拼上（默认关）：它每轮都收固定成本，值不值要靠
+ * A/B 的 fallback 率说话，不能靠"看起来更专业"。
+ */
+export const EXTRACTION_FEW_SHOT = `
+
+【标准格式示例】下面每例的 title 与 content 是**并列的两个产物**：title 是名词短语（回答"这条讲的是什么"），content 是完整叙述正文。**不要**把 content 的开头抄成 title。
+
+${TITLE_GOOD_EXAMPLES.map(renderGoodExample).join('\n\n')}
+
+【不要这样】
+${TITLE_BAD_EXAMPLES.map((b) => `- ✗ ${b.title}　→ ${b.why}`).join('\n')}
+`;
+/**
+ * 各类型的"前因后果"要素表（照 G2 `NARRATIVE_CLAUSE` 写，不另造一套定义）。
+ *
+ * 为什么需要它：可用性判据是用户定的——"content 没前因后果、写不全就不算可用"。
+ * 那句活若只留在提示词里就永远没法判定、也没法拿它定默认值，所以每个类型拆 3 个要素，
+ * 每个要素给一组词元（命中任一即算在）。
+ *
+ * **这是关键词启发式，不是语义判定**：要素换个说法就接不住；G2 自己也允许"信息不足则省略该节"。
+ * 因此它只能用于**同一输入下两臂相对比较**，不能当绝对质量分。
+ */
+export const SKELETON_ELEMENTS = {
+    work_method: [
+        { name: '目标', anyOf: ['目标', '目的', '为了', '旨在'] },
+        { name: '步骤', anyOf: ['步骤', '做法', '先', '再', '然后', '流程', '执行'] },
+        { name: '前置/注意', anyOf: ['前置', '注意', '前提', '坑', '风险', '必须', '不能'] },
+    ],
+    work_fact: [
+        { name: '结论/事实', anyOf: ['结论', '事实', '必须', '只能', '会', '导致', '默认'] },
+        { name: '依据', anyOf: ['因为', '由于', '实测', '验证', '确认', '依据', '来源', '试过'] },
+        { name: '适用范围/失效', anyOf: ['适用', '范围', '失效', '仅', '除非', '例外'] },
+    ],
+    work_task: [
+        { name: '任务', anyOf: ['任务', '需求', '要做', '目标', '工作'] },
+        { name: '当前状态', anyOf: ['当前', '状态', '进度', '已', '未', '完成', '跑通'] },
+        { name: '下一步/阻塞', anyOf: ['下一步', '阻塞', '待', '计划', '负责人', '截止', '尚需'] },
+    ],
+    work_artifact: [
+        { name: '交付物', anyOf: ['交付', '文档', '报告', '产物', '脚本', '清单', '模块'] },
+        { name: '位置', anyOf: ['位置', '路径', '目录', '链接', '存放', '落到', '位于'] },
+        { name: '用途/结论', anyOf: ['用途', '供', '用于', '结论', '便于', '可用'] },
+    ],
+    instruction: [
+        { name: '规则', anyOf: ['规则', '必须', '不得', '禁止', '要求', '一律'] },
+        { name: '触发时机', anyOf: ['触发', '时机', '当', '若', '之前', '之后'] },
+        { name: '反例/边界', anyOf: ['反例', '边界', '例外', '不适用', '除非', '不必', '豁免'] },
+    ],
+    episodic: [
+        { name: '事件', anyOf: ['发生', '做了', '完成', '处理', '排查', '提交'] },
+        { name: '时间/参与者', anyOf: ['时间', '于', '日', '当天', '用户', '团队', '会话'] },
+        { name: '结果', anyOf: ['结果', '产出', '导致', '得以'] },
+    ],
+    persona: [
+        { name: '偏好/习惯', anyOf: ['偏好', '习惯', '喜欢', '倾向', '风格'] },
+        { name: '表现/例子', anyOf: ['表现', '例子', '例如', '总是', '会'] },
+        { name: '强度', anyOf: ['一直', '从不', '总是', '硬性', '强烈', '优先', '稳定'] },
+    ],
+};
+/** 不在表里的类型（宿主那 29 类新词）共用一个兼容要素集，不拿未知类型假判完备。 */
+const GENERIC_ELEMENTS = [
+    { name: '事实', anyOf: ['是', '为', '必须', '会', '有'] },
+    { name: '原因', anyOf: ['因为', '由于', '原因', '实测', '验证'] },
+    { name: '边界', anyOf: ['适用', '范围', '仅', '除非', '注意'] },
+];
+/**
+ * 按类型给 content 打骨架分（关键词启发式，局限见 {@link SKELETON_ELEMENTS}）。
+ *
+ * @param type - 记忆类型。
+ * @param content - 模型产出的正文。
+ * @returns 命中情况；空正文算 0 命中而不是"齐备"。
+ */
+export function scoreSkeleton(type, content) {
+    const spec = SKELETON_ELEMENTS[type] ?? GENERIC_ELEMENTS;
+    const text = typeof content === 'string' ? content : '';
+    const 缺 = [];
+    for (const el of spec) {
+        if (!el.anyOf.some((k) => text.includes(k)))
+            缺.push(el.name);
+    }
+    return {
+        类型: type,
+        要素数: spec.length,
+        命中数: spec.length - 缺.length,
+        缺,
+        齐备: text.trim().length > 0 && 缺.length === 0,
+        无表可依: SKELETON_ELEMENTS[type] === undefined,
+    };
+}
+/** 自检：示例本身是否合格（用例直接吃这个函数，不在用例里手抄判据）。 */
+export function auditFewShot() {
+    const badTitles = TITLE_GOOD_EXAMPLES.filter((g) => !validateTitle(g.title).ok).map((g) => g.title);
+    // 止例自己必须骨架齐备：否则示例就是在示范"只写一句"，而定义与判据全部白写。
+    const thin = TITLE_GOOD_EXAMPLES.filter((g) => !scoreSkeleton(g.type, g.content).齐备)
+        .map((g) => `${g.type}:${scoreSkeleton(g.type, g.content).缺.join('/')}`);
+    return {
+        超预算: EXTRACTION_FEW_SHOT.length > FEW_SHOT_BUDGET,
+        长度: EXTRACTION_FEW_SHOT.length,
+        不合格title: badTitles,
+        抄content开头: TITLE_GOOD_EXAMPLES.filter(copiesContentStart).map((g) => g.title),
+        止例骨架不全: thin,
+    };
+}