dsh-prime-memory 0.26.5 → 0.26.9

package/dist/util/json-repair.js

@@ -0,0 +1,285 @@
+/**
+ * 容错 JSON 解析:LLM 输出常带小语法毛刺,一次 JSON.parse 定生死会把整批记忆全丢。
+ *
+ * 三级链(见 #10):
+ *   strict   → 原样 JSON.parse,零回归;
+ *   repaired → 字符串态扫描,做四类**只动语法不动内容**的确定性修复:
+ *              1) 内容里的裸 ASCII `"` → `\"`(判据:该 `"` 后第一个非空白字符不是 `,` `}` `]` `:` `"` EOF)
+ *              2) 字符串里的裸 `\n` `\r` `\t` → 转义
+ *              3) `,` 紧跟 `}` `]` 的尾逗号 → 删
+ *              4) 结尾未闭合的字符串与括号 → 补齐(对应 finish=length 截断)
+ *   salvaged → 整体修不动时按顶层元素边界逐个 parse,保住坏点前后已完整的对象,
+ *              尾巴丢掉(不猜)。
+ *
+ * 修复/救援发生时会带上 `notes`,由调用方决定是否 warn 落盘(便于回溯:修复是兜底不是常态)。
+ */
+/** 判断 idx 处的 `"` 是否是「真结束」:后一个非空白字符是结构字符或 EOF。 */
+function isRealStringClose(src, idx) {
+    for (let j = idx + 1; j < src.length; j++) {
+        const c = src[j];
+        if (c === ' ' || c === '\t' || c === '\n' || c === '\r')
+            continue;
+        return c === ',' || c === '}' || c === ']' || c === ':';
+    }
+    return true; // EOF
+}
+/**
+ * 字符串态扫描修复:只动语法,字段名与值内容字节一个不改。
+ * 返回 null 表示扫描中遇到无法处理的结构错误(交给上层救援)。
+ */
+export function repairJson(src) {
+    const out = [];
+    const notes = [];
+    const stack = [];
+    let inStr = false;
+    let escaped = false;
+    let bareQuoteFixed = 0;
+    let ctrlCharEscaped = 0;
+    let trailingCommaDropped = 0;
+    for (let i = 0; i < src.length; i++) {
+        const c = src[i];
+        if (inStr) {
+            if (escaped) {
+                // 上一个字符是 `\`,当前是转义内容的一部分,原样输出并复位
+                out.push(c);
+                escaped = false;
+                continue;
+            }
+            if (c === '\\') {
+                out.push(c);
+                escaped = true;
+                continue;
+            }
+            if (c === '"') {
+                if (isRealStringClose(src, i)) {
+                    out.push(c);
+                    inStr = false;
+                }
+                else {
+                    out.push('\\"');
+                    bareQuoteFixed++;
+                }
+                continue;
+            }
+            if (c === '\n') {
+                out.push('\\n');
+                ctrlCharEscaped++;
+                continue;
+            }
+            if (c === '\r') {
+                out.push('\\r');
+                ctrlCharEscaped++;
+                continue;
+            }
+            if (c === '\t') {
+                out.push('\\t');
+                ctrlCharEscaped++;
+                continue;
+            }
+            out.push(c);
+            continue;
+        }
+        // ── 结构态 ──
+        if (c === '"') {
+            inStr = true;
+            out.push(c);
+            continue;
+        }
+        if (c === '{' || c === '[') {
+            stack.push(c);
+            out.push(c);
+            continue;
+        }
+        if (c === '}' || c === ']') {
+            // 弹出匹配的 opener;若不匹配也尽力弹一层(常见于模型写错一层)
+            if (stack.length > 0)
+                stack.pop();
+            // 处理尾逗号:回删 out 末尾的 `,` 与其前面的空白
+            const before = trimTrailingComma(out);
+            if (before > 0)
+                trailingCommaDropped += before;
+            out.push(c);
+            continue;
+        }
+        if (c === ',') {
+            // 前瞻:下一个非空白字符若是 `}` `]` → 尾逗号,吞掉
+            let j = i + 1;
+            while (j < src.length && (src[j] === ' ' || src[j] === '\t' || src[j] === '\n' || src[j] === '\r'))
+                j++;
+            if (j < src.length && (src[j] === '}' || src[j] === ']')) {
+                trailingCommaDropped++;
+                continue; // 不输出这个逗号
+            }
+            out.push(c);
+            continue;
+        }
+        out.push(c);
+    }
+    let tail = out.join('');
+    // 结尾未闭合的字符串 → 补 `"`
+    if (inStr) {
+        tail += '"';
+        notes.push('补闭合未终止的字符串');
+    }
+    // 结尾未闭合的括号 → 按栈反向补齐
+    while (stack.length > 0) {
+        const opener = stack.pop();
+        tail += opener === '{' ? '}' : ']';
+    }
+    if (bareQuoteFixed > 0)
+        notes.push(`转义裸引号 ${bareQuoteFixed} 处`);
+    if (ctrlCharEscaped > 0)
+        notes.push(`转义控制字符 ${ctrlCharEscaped} 处`);
+    if (trailingCommaDropped > 0)
+        notes.push(`删尾逗号 ${trailingCommaDropped} 处`);
+    return { out: tail, notes };
+}
+/** out buffer 尾部若为 `,...` 结构(已推入的字符),移除尾部逗号与空白,返回删除的逗号数。 */
+function trimTrailingComma(out) {
+    let dropped = 0;
+    while (out.length > 0) {
+        const top = out[out.length - 1];
+        if (top === ' ' || top === '\t' || top === '\n' || top === '\r') {
+            out.pop();
+            continue;
+        }
+        if (top === ',') {
+            out.pop();
+            dropped++;
+            continue;
+        }
+        break;
+    }
+    // 处理 `,,}` 双逗号:递归检查
+    if (dropped > 0)
+        dropped += trimTrailingComma(out);
+    return dropped;
+}
+/**
+ * 顶层逐元素救援:仅当输入是 `[...]` 且整体 parse 失败时启用。
+ * 按结构态(非字符串)找顶层逗号,切片成一个个元素,分别 JSON.parse,失败的丢掉。
+ */
+export function salvageTopLevelElements(src) {
+    const first = src.indexOf('[');
+    if (first < 0)
+        return null;
+    const items = [];
+    let dropped = 0;
+    let depth = 0;
+    let inStr = false;
+    let escaped = false;
+    let segStart = first + 1;
+    for (let i = first; i < src.length; i++) {
+        const c = src[i];
+        if (inStr) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (c === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"') {
+            inStr = true;
+            continue;
+        }
+        if (c === '[' || c === '{') {
+            depth++;
+            continue;
+        }
+        if (c === ']' || c === '}') {
+            depth--;
+            if (depth === 0 && i === src.length - 1) { /* 数组收尾 */ }
+            continue;
+        }
+        if (c === ',' && depth === 1) {
+            const seg = src.slice(segStart, i).trim();
+            if (seg) {
+                try {
+                    items.push(JSON.parse(seg));
+                }
+                catch {
+                    dropped++;
+                }
+            }
+            segStart = i + 1;
+        }
+    }
+    // 最后一段(到 `]` 前)
+    const closing = src.lastIndexOf(']');
+    const lastSeg = src.slice(segStart, closing > segStart ? closing : src.length).trim();
+    if (lastSeg) {
+        try {
+            items.push(JSON.parse(lastSeg));
+        }
+        catch {
+            dropped++;
+        }
+    }
+    if (items.length === 0)
+        return null;
+    return { items, dropped };
+}
+/**
+ * 预处理:剥 ```json```围栏 + 切到首个 `[`/`{` 直到末尾 `]`/`}`，兼容 LLM 前后附的散文。
+ * 与旧版 parseJson 逐字行为一致（零回归）。
+ */
+export function preprocessLLMJson(raw) {
+    let s = raw.trim();
+    if (s.startsWith('```')) {
+        s = s.replace(/^```[a-zA-Z]*\n?/, '').replace(/```$/, '').trim();
+    }
+    const start = s.indexOf('[');
+    const brace = s.indexOf('{');
+    let begin;
+    if (start === -1)
+        begin = brace;
+    else if (brace === -1)
+        begin = start;
+    else
+        begin = Math.min(start, brace);
+    if (begin > 0)
+        s = s.slice(begin);
+    const end = s.lastIndexOf(']') > s.lastIndexOf('}') ? s.lastIndexOf(']') + 1 : s.lastIndexOf('}') + 1;
+    if (end > 0)
+        s = s.slice(0, end);
+    return s;
+}
+/**
+ * 三级容错入口。传入已通过「剥围栏 + 切片」的字符串,返回解析结果与档位说明。
+ * 若三级皆失败,抛出 strict JSON.parse 的原始错误。
+ */
+export function parseJsonTolerant(raw) {
+    const s = preprocessLLMJson(raw);
+    // L1 strict
+    try {
+        return { value: JSON.parse(s), level: 'strict', notes: [] };
+    }
+    catch (strictErr) {
+        // L2 repaired
+        const rep = repairJson(s);
+        if (rep) {
+            try {
+                return { value: JSON.parse(rep.out), level: 'repaired', notes: rep.notes };
+            }
+            catch { /* fall through */ }
+        }
+        // L3 salvaged(仅当形如数组时启用)
+        if (s.trim().startsWith('[')) {
+            // 先试修复后再救援
+            const salv = salvageTopLevelElements(rep?.out ?? s);
+            if (salv) {
+                const notes = [`逐元素救援成功,保住 ${salv.items.length} 条、丢弃 ${salv.dropped} 条`];
+                if (rep?.notes.length)
+                    notes.unshift(...rep.notes);
+                return { value: salv.items, level: 'salvaged', notes };
+            }
+        }
+        throw strictErr;
+    }
+}

package/dist/validity-backfill.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 存量 `dsh_validity` 标注回填（expiry-tiering task_6.2 / 6.3 / 7.7）。
+ *
+ * 与 keyword/wing 回填同族但**零 LLM**——classifyValidity 是纯函数，本回填是
+ * 本地派生：分批扫存量 L1，对"缺标注或标注与现算不符"的行写回 `dsh_validity`
+ * 快照，每攒一批对被改记录调 `forceReprojectRecord` 让图谱保鲜（task_7.7 的接缝）。
+ *
+ * 安全边界（继承回填族四件套）：
+ * - 单飞：同时最多一个任务（重复触发返回 running，不排队不叠加）；
+ * - 后台执行 + 可中断：逐页推进、`shouldCancel`/墙钟预算/条数上限三闸，跑了多少算多少，
+ *   其余 deferred 留待下次触发（低频周期或面板）；
+ * - 失败可退：单行 patch 失败只计数，原记录零改动；
+ * - 门控：`validity.tieringEnabled`（部署 ∨ 面板）关时不跑——标注面与消费面同开同关，
+ *   功能关着时存量 metadata 逐字不变（零漂移）。
+ */
+import type { L1Store } from './store/l1.js';
+import { stateOfRecord } from './store/validity.js';
+import type { MemoryLogger } from './types.js';
+export interface ValidityBackfillOutcome {
+    started: boolean;
+    running: boolean;
+    scanned: number;
+    updated: number;
+    failed: number;
+    /** 预算/上限用尽留下的条数（下次周期续跑）。 */
+    deferred: number;
+    cancelled: boolean;
+    /** 累计因本次回填而被重投入队的记录数（图谱保鲜面）。 */
+    reprojected: number;
+}
+interface RunState extends ValidityBackfillOutcome {
+    scanned: number;
+}
+/** 当前进度快照（面板/日志读;无任务在跑返回 null）。 */
+export declare function validityBackfillState(): RunState | null;
+/** 请求中止本轮（在跑的任务在下一个检查点收工;空闲时零效果）。 */
+export declare function cancelValidityBackfill(): {
+    cancelled: boolean;
+    running: boolean;
+};
+export interface ValidityBackfillDeps {
+    l1: L1Store;
+    logger: MemoryLogger;
+    /**
+     * 强制重投缝（runner.reprojectGraph：图谱未启用时自己回零,本模块不碰图谱门）。
+     * 只对被改过标注的记录调用——没动的记录不需要重投（图谱读时派生不吃 dsh_validity）。
+     */
+    reproject: (recordIds: readonly string[]) => void;
+    maxRecords?: number;
+    timeBudgetMs?: number;
+    /** 外部中止判据（宿主 dispose / 面板取消）；每行前检查一次。 */
+    shouldCancel?: () => boolean;
+}
+/**
+ * 启动后台回填；已在运行返回 {started:false}（单飞）。
+ * 完成状态留在 `validityBackfillState()` 供最后一次读取（下轮启动时重置）。
+ */
+export declare function startValidityBackfill(deps: ValidityBackfillDeps): {
+    started: boolean;
+    running: boolean;
+};
+/**
+ * 回填主体（导出供单测 await 到完成；生产走 `startValidityBackfill` 的单飞包装）。
+ * 同步扫描 + 同步写回（L1Store 的读面都是同步的），只在页间 `yieldLoop` 让位——
+ * 没有 LLM 的回填不需要并发池，串行就是最快且最不会打脏的形状。
+ */
+export declare function runValidityBackfillOnce(deps: ValidityBackfillDeps): Promise<ValidityBackfillOutcome>;
+/** 单行是否需要补标/重标（导出供单测钉判据；生产路径走 runValidityBackfillOnce）。 */
+export declare function validityBackfillNeeds(metadata: unknown, record: Parameters<typeof stateOfRecord>[0], now: number): boolean;
+/** 内部常量导出（测试钉预算/批形）。 */
+export declare const VALIDITY_BACKFILL_TUNING: {
+    readonly PAGE: 200;
+    readonly DEFAULT_MAX_RECORDS: 5000;
+    readonly DEFAULT_TIME_BUDGET_MS: 120000;
+    readonly REPROJECT_BATCH: 50;
+    readonly VALIDITY_METADATA_KEY: "dsh_validity";
+};
+export {};

package/dist/validity-backfill.js

@@ -0,0 +1,160 @@
+import { readValidity, VALIDITY_METADATA_KEY, stampValidity, stateOfRecord } from './store/validity.js';
+import { yieldLoop } from './util/yield.js';
+/** 扫描页大小（轻量投影分页；与 keyword-backfill 一致）。 */
+const PAGE = 200;
+/** 单次任务默认处理上限（真机库 ~千级,一轮可清完大半;剩余 defer）。 */
+const DEFAULT_MAX_RECORDS = 5_000;
+/** 默认墙钟预算(ms)：纯本地派生 + 索引点查,比 LLM 回填便宜几个量级。 */
+const DEFAULT_TIME_BUDGET_MS = 120_000;
+/** 每攒多少条被改记录触发一次图谱重投（task_7.7 的"每批"）。 */
+const REPROJECT_BATCH = 50;
+let current = null;
+let abortRequested = false;
+/** 当前进度快照（面板/日志读;无任务在跑返回 null）。 */
+export function validityBackfillState() {
+    return current === null ? null : { ...current };
+}
+/** 请求中止本轮（在跑的任务在下一个检查点收工;空闲时零效果）。 */
+export function cancelValidityBackfill() {
+    if (current === null || !current.running)
+        return { cancelled: false, running: false };
+    abortRequested = true;
+    return { cancelled: true, running: true };
+}
+/**
+ * 启动后台回填；已在运行返回 {started:false}（单飞）。
+ * 完成状态留在 `validityBackfillState()` 供最后一次读取（下轮启动时重置）。
+ */
+export function startValidityBackfill(deps) {
+    if (current?.running)
+        return { started: false, running: true };
+    current = {
+        started: true, running: true, scanned: 0, updated: 0, failed: 0,
+        deferred: 0, cancelled: false, reprojected: 0,
+    };
+    abortRequested = false;
+    void runValidityBackfillOnce(deps).finally(() => {
+        if (current !== null) {
+            current.running = false;
+            deps.logger.info(`[memory] validity 回填结束:扫描 ${current.scanned} 行,补标 ${current.updated} 条` +
+                (current.failed > 0 ? `,失败 ${current.failed} 条` : '') +
+                (current.reprojected > 0 ? `,重投 ${current.reprojected} 条` : '') +
+                (current.deferred > 0 ? `,留待下次 ${current.deferred} 条` : ''));
+        }
+    });
+    return { started: true, running: true };
+}
+/**
+ * 回填主体（导出供单测 await 到完成；生产走 `startValidityBackfill` 的单飞包装）。
+ * 同步扫描 + 同步写回（L1Store 的读面都是同步的），只在页间 `yieldLoop` 让位——
+ * 没有 LLM 的回填不需要并发池，串行就是最快且最不会打脏的形状。
+ */
+export async function runValidityBackfillOnce(deps) {
+    const { l1, logger } = deps;
+    abortRequested = false;
+    const maxRecords = Math.max(1, deps.maxRecords ?? DEFAULT_MAX_RECORDS);
+    const timeBudgetMs = Math.max(1_000, deps.timeBudgetMs ?? DEFAULT_TIME_BUDGET_MS);
+    const startedAt = Date.now();
+    // 新一轮必须重置计数:上一轮的 current 只置 running=false 不清空(留面板终读)——
+    // 直接调 runOnce(不经 start 的重置)若复用旧对象,scanned/updated 会跨轮累加。
+    const st = (current === null || current.running === false)
+        ? {
+            started: true, running: true, scanned: 0, updated: 0, failed: 0, deferred: 0, cancelled: false, reprojected: 0,
+        }
+        : current;
+    current = st;
+    const flushReproject = (ids) => {
+        if (ids.length === 0)
+            return;
+        // task_7.7：每批标注写完即保鲜——forceReprojectRecord 自身的 PK 去重保证
+        // "在途不堆重"，回填重复跑同一批也只会多投一次凭证删除，不会堆 job。
+        try {
+            deps.reproject(ids);
+            st.reprojected += ids.length;
+        }
+        catch (err) {
+            logger.warn(`[memory] validity 回填补投失败(忽略,图谱由周期 sweep 兜底): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const dirty = [];
+    let offset = 0;
+    let hitCeil = false;
+    for (;;) {
+        if (abortRequested || deps.shouldCancel?.() === true) {
+            st.cancelled = true;
+            break;
+        }
+        if (st.scanned >= maxRecords) {
+            hitCeil = true;
+            break;
+        }
+        if (Date.now() - startedAt > timeBudgetMs) {
+            hitCeil = true;
+            break;
+        }
+        const page = l1.allLite(PAGE, offset);
+        if (page.length === 0)
+            break;
+        offset += page.length;
+        // allLite 只有 id/type/metadata——classify 要吃 validTo/persistence,整页 hydrate
+        const byId = new Map(l1.getByIds(page.map((p) => p.id)).map((r) => [r.id, r]));
+        const now = Date.now();
+        for (const lite of page) {
+            // 逐行检查点("可中断"承诺的粒度):页间检查在千行页上形同虚设。
+            if (abortRequested || deps.shouldCancel?.() === true) {
+                st.cancelled = true;
+                break;
+            }
+            const rec = byId.get(lite.id);
+            if (rec === undefined)
+                continue; // 行在扫描瞬间被删:回填不追墓碑
+            st.scanned++;
+            const existing = readValidity(rec.metadata);
+            const state = stateOfRecord(rec, now);
+            // 需要写回的两种情形:①从没标过;②state 变了(时间流逝把 current 熬成 expired 等)。
+            // validToSource 只在"从没标过"时按现算补;已标过的保留源头证据链(不就地升级证据等级)。
+            const needs = existing === undefined || existing.state !== state;
+            if (!needs)
+                continue;
+            const copy = { ...rec, metadata: { ...(rec.metadata ?? {}) } };
+            stampValidity(copy, now);
+            try {
+                if (l1.patchMetadata(copy.id, copy.metadata)) {
+                    st.updated++;
+                    dirty.push(copy.id);
+                    if (dirty.length >= REPROJECT_BATCH) {
+                        flushReproject(dirty.splice(0, dirty.length));
+                    }
+                }
+                else {
+                    st.failed++;
+                }
+            }
+            catch (err) {
+                st.failed++;
+                logger.warn(`[memory] validity 回填单行失败(id=${copy.id},原记录未改): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        await yieldLoop();
+    }
+    flushReproject(dirty.splice(0, dirty.length));
+    if (!st.cancelled && hitCeil) {
+        const total = l1.size;
+        st.deferred = Math.max(0, total - st.scanned);
+    }
+    else if (st.cancelled) {
+        st.deferred = Math.max(0, l1.size - st.scanned);
+    }
+    st.running = false;
+    // 让最后一次状态可被面板读到：current 不在这里清，下轮 start 重置。
+    return { ...st };
+}
+/** 单行是否需要补标/重标（导出供单测钉判据；生产路径走 runValidityBackfillOnce）。 */
+export function validityBackfillNeeds(metadata, record, now) {
+    const existing = readValidity(metadata);
+    if (existing === undefined)
+        return true;
+    return existing.state !== stateOfRecord(record, now);
+}
+/** 内部常量导出（测试钉预算/批形）。 */
+export const VALIDITY_BACKFILL_TUNING = { PAGE, DEFAULT_MAX_RECORDS, DEFAULT_TIME_BUDGET_MS, REPROJECT_BATCH, VALIDITY_METADATA_KEY };

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-prime-memory",
   "name": "dsh-prime-memory",
-  "version": "0.26.5-beta.0",
+  "version": "0.26.9",
   "description": {
     "en": "Layered distilled memory plugin (L0 capture → L1 atomic memory → L2 scenes → L3 persona) with automatic recall injection before each model step.",
     "zh": "L0~L3 分层蒸馏记忆插件:自动捕获对话、抽取原子记忆、整合场景块、蒸馏核心画像,并在模型步骤前自动召回注入。"
@@ -19,4 +19,4 @@
     "host": "dist/index.js",
     "client": "dist/client.js"
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-prime-memory",
-  "version": "0.26.5",
+  "version": "0.26.9",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public",
@@ -64,7 +64,7 @@
   },
   "engines": {
     "node": ">=22.16.0",
-    "dsh": "0.1.0-rc.2 || 0.1.0-rc.3 || 0.1.0-rc.6 || 0.1.0-rc.7 || 0.1.0-rc.8 || 0.1.1-rc.1 || 0.1.1-rc.2 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.1 || 0.2.1-rc.2"
+    "dsh": "0.1.0-rc.2 || 0.1.0-rc.3 || 0.1.0-rc.6 || 0.1.0-rc.7 || 0.1.0-rc.8 || 0.1.1-rc.1 || 0.1.1-rc.2 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.1 || 0.2.1-rc.2"
   },
   "keywords": [
     "dsh",
@@ -152,4 +152,4 @@
     "typescript-eslint": "^8.69.0",
     "vitest": "^4.1.11"
   }
-}
+}