dsh-prime-memory 0.22.1 → 0.24.0

package/dist/store/memory-sources.js

@@ -0,0 +1,214 @@
+/**
+ * 外部记忆来源注册表（轨3 Connect 路径的一等实体）。
+ *
+ * 动机：此前"其他 agent → 记忆库"的取内容路径只装配到 `memory_import` 这最后一寸，
+ * 前面十一寸（发现来源、记录来源、按来源管理）全外包给 skill 文本 + 用户手填路径。
+ * 本注册表把"来源"升为可持久、可枚举、可按来源撤销的一等实体。
+ *
+ * **路径指针不复制**（Connect 语义，援引 `slots.refs` 先例）：每条只存 `path` + 摘要，
+ * 正文**永不落进插件目录**——既是"移动房子家具先消毒"的卫生边界，也让带 ext_key 的
+ * 外部记忆"来源仍在、可重放"（可重建性显式化）。
+ *
+ * 存储：rooms-registry 同款 sidecar（`memory-sources.json`），全量载入内存 + 写穿原子持久化，
+ * `rev` 乐观计数。文件缺失 = 合法空表；损坏/不可读 → 告警 + 只读降级（内存态照常、停止回写），
+ * **绝不阻塞扫描/导入/面板**（降级即回退"无注册来源"，非破坏性）。上限防刷。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+/** sidecar 版本常量（file-versions 同款集中纪律）。 */
+export const MEMORY_SOURCES_FILE_VERSION = 1;
+/** 已知外部 agent 来源类别（与 memport foreign-agent.md 对齐）；'file' = 任意路径。 */
+export const SOURCE_KINDS = ['trae', 'qoder', 'codex', 'claude', 'workbuddy', 'golutra', 'cursor', 'file'];
+/** 来源上限（防刷；一个工作区通常 <20 个外部工具记忆落点）。 */
+const SOURCES_CAP = 100;
+const PATH_MAX = 500;
+const LABEL_MAX = 80;
+function isSourceId(s) {
+    return /^[a-z0-9][a-z0-9-]{0,63}$/.test(s);
+}
+function normKind(k) {
+    return SOURCE_KINDS.includes(String(k)) ? k : 'file';
+}
+export class MemorySourceStore {
+    logger;
+    file;
+    entries = [];
+    rev = 0;
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'memory-sources.json');
+    }
+    /** 载入（启动 await 一次）。缺失 = 合法空表；损坏 = 只读降级（回退"无来源"）。 */
+    async init() {
+        await ensureDir(path.dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] 外部来源注册表只读降级: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        if (read.value.version !== MEMORY_SOURCES_FILE_VERSION) {
+            this.logger?.warn(`[memory] 外部来源注册表版本 ${String(read.value.version)} 未知，按当前形状读取`);
+        }
+        const sources = Array.isArray(read.value.sources) ? read.value.sources : [];
+        for (const s of sources) {
+            if (!s || typeof s.id !== 'string' || !isSourceId(s.id))
+                continue; // 非法 id 丢弃
+            if (typeof s.path !== 'string' || !s.path)
+                continue; // 无路径指针的来源无意义，丢弃
+            this.entries.push({
+                id: s.id,
+                kind: normKind(s.kind),
+                path: s.path.slice(0, PATH_MAX),
+                label: typeof s.label === 'string' ? s.label : undefined,
+                lastScanAt: typeof s.lastScanAt === 'string' ? s.lastScanAt : '',
+                lastImportAt: typeof s.lastImportAt === 'string' ? s.lastImportAt : '',
+                disabled: s.disabled === true,
+                status: s.status === 'retired' ? 'retired' : 'active',
+                createdAt: typeof s.createdAt === 'string' ? s.createdAt : '',
+                updatedAt: typeof s.updatedAt === 'string' ? s.updatedAt : '',
+            });
+        }
+        this.rev = typeof read.value.rev === 'number' ? read.value.rev : 0;
+        this.loaded = true;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('外部来源注册表未初始化（先 await init()）');
+    }
+    /** 全量条目（含 retired；副本返回，活引用纪律）。 */
+    list() {
+        this.ensureLoaded();
+        return this.entries.map((e) => ({ ...e }));
+    }
+    /** active 且未停用的来源（扫描/导入遍历用）。 */
+    listEnabled() {
+        return this.list().filter((e) => e.status === 'active' && !e.disabled);
+    }
+    byId(id) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.id === id);
+        return found ? { ...found } : undefined;
+    }
+    /** 登记来源（幂等：同 id 已存在则原地补全 kind/path/label，不新建）。上限防刷。 */
+    async register(input) {
+        this.ensureLoaded();
+        const id = String(input.id ?? '').trim().toLowerCase();
+        if (!isSourceId(id))
+            throw new Error(`非法来源 id: ${String(input.id)}（小写字母数字连字符，≤64）`);
+        const p = String(input.path ?? '').trim();
+        if (!p)
+            throw new Error('来源 path 不能为空（路径指针不复制，但必须指向真实落点）');
+        if (p.length > PATH_MAX)
+            throw new Error(`来源 path 过长（>${PATH_MAX}）`);
+        const found = this.entries.find((e) => e.id === id);
+        if (found) {
+            let changed = false;
+            const kind = normKind(input.kind);
+            if (found.kind !== kind) {
+                found.kind = kind;
+                changed = true;
+            }
+            if (found.path !== p) {
+                found.path = p;
+                changed = true;
+            }
+            if (typeof input.label === 'string' && input.label.trim() && found.label !== input.label.trim().slice(0, LABEL_MAX)) {
+                found.label = input.label.trim().slice(0, LABEL_MAX);
+                changed = true;
+            }
+            if (found.status === 'retired') {
+                found.status = 'active';
+                changed = true;
+            }
+            if (changed) {
+                found.updatedAt = new Date().toISOString();
+                this.rev++;
+                await this.persist();
+            }
+            return { entry: { ...found }, created: false };
+        }
+        if (this.entries.length >= SOURCES_CAP)
+            throw new Error(`外部来源已达上限（${SOURCES_CAP}），请先退役部分来源`);
+        const now = new Date().toISOString();
+        const entry = {
+            id,
+            kind: normKind(input.kind),
+            path: p.slice(0, PATH_MAX),
+            label: typeof input.label === 'string' && input.label.trim() ? input.label.trim().slice(0, LABEL_MAX) : undefined,
+            lastScanAt: '',
+            lastImportAt: '',
+            disabled: false,
+            status: 'active',
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.entries.push(entry);
+        this.rev++;
+        await this.persist();
+        return { entry: { ...entry }, created: true };
+    }
+    /** 记一次扫描时间。 */
+    async markScanned(id, at) {
+        return this.patch(id, (e) => {
+            e.lastScanAt = at;
+        });
+    }
+    /** 记一次导入时间。 */
+    async markImported(id, at) {
+        return this.patch(id, (e) => {
+            e.lastImportAt = at;
+        });
+    }
+    /** 启用/停用（停用保留条目、只是不参与自动扫描）。 */
+    async setDisabled(id, disabled) {
+        return this.patch(id, (e) => {
+            e.disabled = disabled;
+        });
+    }
+    /** 退役/恢复（status 迁移）。 */
+    async setStatus(id, status) {
+        return this.patch(id, (e) => {
+            e.status = status;
+        });
+    }
+    async patch(id, mut) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.id === id);
+        if (!found)
+            return false;
+        mut(found);
+        found.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /** 写穿持久化（串行链；失败降级内存态并告警一次，绝不抛出阻塞调用方）。 */
+    async persist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(async () => {
+            const data = { version: MEMORY_SOURCES_FILE_VERSION, rev: this.rev + 1, sources: this.entries };
+            try {
+                await ensureDir(path.dirname(this.file));
+                await atomicWriteText(this.file, JSON.stringify(data, null, 2));
+                this.rev = data.rev;
+            }
+            catch (err) {
+                this.degraded = err instanceof Error ? err.message : String(err);
+                if (!this.degradedLogged) {
+                    this.degradedLogged = true;
+                    this.logger?.warn(`[memory] 外部来源注册表写入失败，只读降级: ${this.degraded}`);
+                }
+            }
+        });
+        await this.writeChain;
+    }
+}

package/dist/store/obsolete-notices.d.ts

@@ -0,0 +1,39 @@
+import type { MemoryLogger } from '../types.js';
+export declare const OBSOLETE_NOTICES_FILE_VERSION: 1;
+/** 一条待播报的过时声明。 */
+export interface ObsoleteNotice {
+    /** 被退场的 L1 记录 id。 */
+    id: string;
+    /** 正文首行（注入时供模型定位是哪条；截断至 TITLE_MAX）。 */
+    title: string;
+    /** 用户声明时刻(epoch ms)。 */
+    at: number;
+}
+export declare class ObsoleteNoticeStore {
+    private readonly logger?;
+    private readonly file;
+    private buckets;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    private rev;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    private normalize;
+    private ensureLoaded;
+    /** 判脏序号(测试/观测用;注入侧靠 drain 的返回值判断有无)。 */
+    revision(): number;
+    /** 入队一条(幂等由调用方保证:同 id 重复入队只会多播一行，故这里去重)。 */
+    push(sessionKey: string, notice: ObsoleteNotice): void;
+    /** 出队并清空该会话的待播报(一次性语义:取走即离开 outbox)。 */
+    drain(sessionKey: string): ObsoleteNotice[];
+    /** 只看不取(测试/诊断)。 */
+    peek(sessionKey: string): ObsoleteNotice[];
+    size(): number;
+    private prune;
+    private schedulePersist;
+    private persist;
+    /** 等待在途写完成(测试/停机用)。 */
+    flush(): Promise<void>;
+}

package/dist/store/obsolete-notices.js

@@ -0,0 +1,153 @@
+/**
+ * 「记忆已声明过时」待播报队列（outbox，`obsolete-notices.json`）。
+ *
+ * 为什么需要它：用户在召回卡上打 `-1` 之后，**记忆库那一侧当场就改了**（退场），
+ * 但模型此刻的上下文里那条记忆还在——它得被告知"这条已由用户判定过时、别再依据它
+ * 作答"。这个告知是一次性的：下一轮注入即出队，不常驻（常驻是槽位的语义，见
+ * `hooks/slot-recall.ts`）。
+ *
+ * 落盘而非纯内存：打 `-1` 到下一轮之间若进程重启，纯内存会**静默丢掉这一票**——
+ * 记忆已经退场了，而模型从没被告知。所以 outbox 必须持久化（与 session-recalled
+ * 同款纪律：写穿 + 版本 + 损坏只读降级，绝不抛进注入热路径）。
+ *
+ * 键 = sessionKey（`agent.session?.id ?? agent.id`），与活召回集、pill 的 sessionId
+ * 同源；三处不同键会直接导致"播报错会话"，见 store/session-recalled.ts 头注。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+export const OBSOLETE_NOTICES_FILE_VERSION = 1;
+/** 单会话待播报上限（超出丢最旧：模型只需知道"这些别再信"，不需历史）。 */
+const PER_SESSION_CAP = 8;
+/** 会话数上限，按最近写入时间淘汰。 */
+const SESSION_CAP = 200;
+const TITLE_MAX = 120;
+export class ObsoleteNoticeStore {
+    logger;
+    file;
+    buckets = new Map();
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    rev = 0;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'obsolete-notices.json');
+    }
+    async init() {
+        await ensureDir(path.dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] 过时播报队列只读降级: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        const raw = read.value.sessions ?? {};
+        for (const [sid, list] of Object.entries(raw)) {
+            const kept = this.normalize(list);
+            if (kept.length > 0)
+                this.buckets.set(sid, kept);
+        }
+        this.loaded = true;
+    }
+    normalize(list) {
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        for (const raw of list) {
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const e = raw;
+            if (typeof e.id !== 'string' || !e.id || typeof e.title !== 'string' || typeof e.at !== 'number')
+                continue;
+            out.push({ id: e.id, title: e.title, at: e.at });
+            if (out.length >= PER_SESSION_CAP)
+                break;
+        }
+        return out;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('过时播报队列未初始化(先 await init())');
+    }
+    /** 判脏序号(测试/观测用;注入侧靠 drain 的返回值判断有无)。 */
+    revision() {
+        return this.rev;
+    }
+    /** 入队一条(幂等由调用方保证:同 id 重复入队只会多播一行，故这里去重)。 */
+    push(sessionKey, notice) {
+        this.ensureLoaded();
+        if (!sessionKey)
+            return;
+        const list = this.buckets.get(sessionKey) ?? [];
+        if (list.some((n) => n.id === notice.id))
+            return;
+        const title = notice.title.length > TITLE_MAX ? `${notice.title.slice(0, TITLE_MAX)}…` : notice.title;
+        const next = [...list, { ...notice, title }];
+        this.buckets.set(sessionKey, next.slice(-PER_SESSION_CAP));
+        this.rev += 1;
+        this.prune();
+        this.schedulePersist();
+    }
+    /** 出队并清空该会话的待播报(一次性语义:取走即离开 outbox)。 */
+    drain(sessionKey) {
+        this.ensureLoaded();
+        const list = this.buckets.get(sessionKey);
+        if (list === undefined || list.length === 0)
+            return [];
+        this.buckets.delete(sessionKey);
+        this.rev += 1;
+        this.schedulePersist();
+        return list;
+    }
+    /** 只看不取(测试/诊断)。 */
+    peek(sessionKey) {
+        this.ensureLoaded();
+        return [...(this.buckets.get(sessionKey) ?? [])];
+    }
+    size() {
+        this.ensureLoaded();
+        let n = 0;
+        for (const list of this.buckets.values())
+            n += list.length;
+        return n;
+    }
+    prune() {
+        if (this.buckets.size <= SESSION_CAP)
+            return;
+        const newestAt = (list) => list.reduce((m, n) => Math.max(m, n.at), 0);
+        const byOldest = [...this.buckets.entries()].sort((a, b) => newestAt(a[1]) - newestAt(b[1]));
+        for (const [sid] of byOldest.slice(0, this.buckets.size - SESSION_CAP))
+            this.buckets.delete(sid);
+    }
+    schedulePersist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(() => this.persist(), () => this.persist());
+    }
+    async persist() {
+        if (this.degraded)
+            return;
+        const body = {
+            version: OBSOLETE_NOTICES_FILE_VERSION,
+            sessions: Object.fromEntries(this.buckets),
+        };
+        try {
+            await atomicWriteText(this.file, JSON.stringify(body, null, 2));
+        }
+        catch (err) {
+            this.degraded = err instanceof Error ? err.message : String(err);
+            if (!this.degradedLogged) {
+                this.degradedLogged = true;
+                this.logger?.warn(`[memory] 过时播报队列落盘失败,转只读降级: ${this.degraded}`);
+            }
+        }
+    }
+    /** 等待在途写完成(测试/停机用)。 */
+    flush() {
+        return this.writeChain;
+    }
+}

package/dist/store/recall-feedback.d.ts

@@ -0,0 +1,75 @@
+import type { MemoryLogger } from '../types.js';
+export declare const RECALL_FEEDBACK_FILE_VERSION: 1;
+/** 合法打分：-1（声明过时）与 0..5（相关度）。 */
+export declare const FEEDBACK_SCORES: readonly [-1, 0, 1, 2, 3, 4, 5];
+export type FeedbackScore = (typeof FEEDBACK_SCORES)[number];
+/** 单条记忆的反馈聚合。 */
+export interface RecallFeedbackEntry {
+    /** 最近一次打分(-1..5)。 */
+    last: FeedbackScore;
+    /** 有效相关度评分次数(不含 -1)。 */
+    rated: number;
+    /** 0..5 评分均值(rated=0 时为 0)。 */
+    mean: number;
+    /** 被声明过时的次数(-1 计数)。 */
+    obsolete: number;
+    /** 最近一次打分时刻(epoch ms)。 */
+    updatedAt: number;
+    /** 最近若干条打分轨迹(旧→新，截断至 HISTORY_CAP)。 */
+    history: Array<{
+        s: FeedbackScore;
+        at: number;
+    }>;
+}
+/** 是否合法打分(供端点入参校验复用)。 */
+export declare function isFeedbackScore(v: unknown): v is FeedbackScore;
+export declare class RecallFeedbackStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    /** 判脏序号:每次有效写入 +1(投影 view 带 rating，靠它决定要不要重建)。 */
+    private rev;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    /** 读侧逐条收窄:形状不符的条目丢弃，不让一条坏数据拖垮整表。 */
+    private normalize;
+    private ensureLoaded;
+    /** 判脏序号(供投影 O(1) 决定要不要重建 view)。 */
+    revision(): number;
+    /**
+     * 记一次打分。返回聚合后的条目(供端点回执)。
+     * 只聚合不裁决:`-1` 进 obsolete 计数、不进均值(过时不是"不相关",两回事)。
+     */
+    rate(id: string, score: FeedbackScore, at?: number): RecallFeedbackEntry;
+    get(id: string): RecallFeedbackEntry | undefined;
+    /** 均值(0..5);无有效评分 → undefined(缺席 ≠ 0 分)。 */
+    meanOf(id: string): number | undefined;
+    /** 最近一次打分(-1..5);未标注 → undefined。 */
+    lastOf(id: string): FeedbackScore | undefined;
+    /**
+     * 把一条记录的人工标注搬到新 id（merge 之后由管线调用，P0-d）。
+     *
+     * 不搬的后果比使用史更直接：成熟度只吃“人工最近一笔”，而 `last` 留在旧 id 上
+     * 就等于新记录**看起来从没被人打过**；更坏的是旧 id 上那一笔 `-1`（已判过时）
+     * 会跟着旧行一起沉进垃圾堆，新行反而以“未标注”的活状态回到召回里。
+     *
+     * 计数按相加、不按轨迹重算：`history` 截断到 12 条，拿它反推 `obsolete` 必然少算。
+     * 两侧都有条目时取较新一侧的 `last`，轨迹按时间归并。
+     */
+    rekey(oldId: string, newId: string): boolean;
+    summary(): {
+        tracked: number;
+        rated: number;
+        obsolete: number;
+    };
+    private prune;
+    /** 立即落盘(串行链上排队,不与在途写交错)。 */
+    private schedulePersist;
+    private persist;
+    /** 等待在途写完成(测试/停机用)。 */
+    flush(): Promise<void>;
+}