dsh-prime-memory 0.11.0

package/dist/store/scenes.js

@@ -0,0 +1,160 @@
+/**
+ * L2 场景块存储:Markdown 文件(含 META 块)+ 场景导航。
+ * LLM 输出 [DELETED] 时由工程侧删除文件(硬删除),list() 对仍含该标记的
+ * 遗留文件容错跳过。
+ *
+ * 分族隔离:目录为 scenes/<family>/;init() 把旧布局(scenes/ 根下散文件)
+ * 一次性迁入 scenes/chat/(历史数据由 chat 档蒸馏产出)。
+ * META 定界符与 [DELETED] 标记是磁盘契约,不可更动。
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { atomicWriteText, ensureDir, readTextIfExists } from '../util/io.js';
+import { NAV_HEADER } from './persona.js';
+const META_START = '-----META-START-----';
+const META_END = '-----META-END-----';
+const DELETED_MARKER = '[DELETED]';
+export class SceneStore {
+    logger;
+    dir;
+    family;
+    constructor(dataDir, family, logger) {
+        this.logger = logger;
+        this.family = family;
+        this.dir = path.join(dataDir, 'scenes', family);
+    }
+    async init() {
+        await ensureDir(this.dir);
+        await this.migrateLegacyLayout();
+    }
+    /** 旧布局迁移:scenes/ 根下的 .md 移入本族目录。仅 chat 族执行(历史数据归属 chat)。 */
+    async migrateLegacyLayout() {
+        if (this.family !== 'chat')
+            return;
+        const legacyDir = path.dirname(this.dir);
+        let files;
+        try {
+            files = await fs.readdir(legacyDir);
+        }
+        catch {
+            return;
+        }
+        let moved = 0;
+        for (const f of files) {
+            if (!f.endsWith('.md'))
+                continue;
+            const from = path.join(legacyDir, f);
+            const to = path.join(this.dir, f);
+            try {
+                await fs.rename(from, to);
+                moved++;
+            }
+            catch {
+                /* 单文件失败跳过(可能被占用),下次启动重试 */
+            }
+        }
+        if (moved > 0)
+            this.logger?.info(`[memory] 场景目录迁移:${moved} 个文件 scenes/ → scenes/chat/`);
+    }
+    listFiles() {
+        return fs.readdir(this.dir).catch(() => []);
+    }
+    /** 列出场景摘要(解析 META 块)。 */
+    async list() {
+        const files = await this.listFiles();
+        const out = [];
+        for (const f of files.sort()) {
+            if (!f.endsWith('.md'))
+                continue;
+            const content = await readTextIfExists(path.join(this.dir, f));
+            if (!content || content.trim() === DELETED_MARKER)
+                continue;
+            out.push(parseMeta(content, f));
+        }
+        return out;
+    }
+    async read(name) {
+        const safe = sanitizeFilename(name);
+        if (!safe)
+            return undefined;
+        return readTextIfExists(path.join(this.dir, safe));
+    }
+    /**
+     * 写入/重写场景文件。content 为 [DELETED] 时删除该文件(LLM 的 delete 操作)。
+     * 文件名自动归一化(空格→短横线、剔除非法字符),非法则抛错。
+     */
+    async write(name, content) {
+        const safe = sanitizeFilename(name);
+        if (!safe)
+            throw new Error(`非法的场景文件名: ${name}`);
+        const file = path.join(this.dir, safe);
+        if (content.trim() === DELETED_MARKER) {
+            await fs.unlink(file).catch(() => undefined);
+            return safe;
+        }
+        await atomicWriteText(file, content);
+        return safe;
+    }
+    /** 场景导航索引(召回注入用)。 */
+    async navigation() {
+        const scenes = await this.list();
+        if (scenes.length === 0)
+            return '';
+        const lines = [
+            NAV_HEADER,
+            '*以下是当前场景记忆索引,可使用 memory_read_scene 读取详细内容。*',
+            '',
+        ];
+        for (const s of scenes) {
+            lines.push(`- \`${s.path}\` — ${s.summary || '(无摘要)'}`);
+        }
+        return lines.join('\n');
+    }
+}
+function parseMeta(content, name) {
+    const s = { path: name, created: '', updated: '', summary: '', heat: 0 };
+    const start = content.indexOf(META_START);
+    const end = content.indexOf(META_END);
+    if (start !== -1 && end !== -1) {
+        const meta = content.slice(start + META_START.length, end);
+        for (const line of meta.split('\n')) {
+            const m = /^\s*([a-zA-Z_]+)\s*:\s*(.*)$/.exec(line);
+            if (!m)
+                continue;
+            const key = m[1].toLowerCase();
+            const value = m[2].trim();
+            if (key === 'created')
+                s.created = value;
+            else if (key === 'updated')
+                s.updated = value;
+            else if (key === 'summary')
+                s.summary = value;
+            else if (key === 'heat')
+                s.heat = Number.parseInt(value, 10) || 0;
+        }
+    }
+    return s;
+}
+/** Windows 保留设备名(CON.md 等带扩展形态同样命中设备语义,须整体避开)。 */
+const RESERVED_NAME_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+/** 文件名归一化:只允许字母数字 CJK - _ .,以 .md 结尾,去空格/标点。
+ *  超长名截断到 120 字符(ENAMETOOLONG 防御);Windows 保留设备名加前缀 _ 避让。 */
+export function sanitizeFilename(name) {
+    let n = name.trim();
+    if (!n.toLowerCase().endsWith('.md'))
+        n = `${n}.md`;
+    n = n
+        .replace(/[^\w\u3400-\u9fff\uf900-\ufaff.\-_]/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/-+\.md$/i, '.md')
+        .replace(/^-+|-+$/g, '');
+    let stem = n.slice(0, -3);
+    if (stem.length > 120)
+        stem = stem.slice(0, 120).replace(/[-._]+$/, '');
+    if (RESERVED_NAME_RE.test(stem))
+        stem = `_${stem}`;
+    n = `${stem}.md`;
+    if (!n || !/^[\w\u3400-\u9fff\uf900-\ufaff.\-_]+\.md$/i.test(n))
+        return '';
+    return n;
+}

package/dist/store/search-utils.d.ts

@@ -0,0 +1,38 @@
+/** 标准 RRF 常数(原论文值);k 越大越偏向低排名项(分布更平滑)。 */
+export declare const RRF_K = 60;
+/** 衰减地板(#29 时效加权的安全边界):老记忆最多损失一半排序分,永不沉底。
+ *  内部常量不进配置——它是安全机制不是调参旋钮。 */
+export declare const DECAY_FLOOR = 0.5;
+/**
+ * 时效衰减加权(#29,读路径专用):score × max(FLOOR, 0.5^(Δ天/半衰期)) 后重排序。
+ *
+ * - Δ 按 updated_at(内容版本时间)起算,缺失/非法按最老 → 地板接管(零特判分支);
+ * - 乘法保相关性主导:只在相关度相近的候选之间轮转名次,不淘汰不硬过滤;
+ *   hit 的原 score 字段不被改写(排序用加权分,展示仍反映检索相关度);
+ * - halfLifeDays ≤ 0 直接原样返回(开关关闭);
+ * - 仅用于召回/工具检索;searchCandidates(去重候选)不得应用——写路径找同语义
+ *   旧记录要无视新旧,衰减会让去重漏检(同事实双记录)。
+ */
+export declare function applyDecayWeight<T extends {
+    score: number;
+}>(hits: T[], halfLifeDays: number, updatedAtOf: (hit: T) => number | undefined, now?: number): T[];
+/**
+ * RRF 融合多个已排序列表:每项得分 = 各列表 1/(k + rank + 1) 之和。
+ * 出现在多个列表的项得分累加,按得分降序返回(附 rrfScore)。
+ */
+export declare function rrfMerge<T>(lists: T[][], getId: (item: T) => string, k?: number): Array<T & {
+    rrfScore: number;
+}>;
+/** FTS5 bm25 rank(负值=更相关)转 0~1 分数。 */
+export declare function bm25RankToScore(rank: number): number;
+/**
+ * 把自然语言查询构造成 FTS5 MATCH 表达式:token 引号化后 OR 连接,
+ * 命中任一 token 即返回,BM25 自然把命中多 token 的文档排前——
+ * 长查询与纯 FTS 模式(无向量)下召回率显著优于整句匹配。
+ */
+export declare function buildFtsQuery(raw: string): string | null;
+/**
+ * 写入侧分词:tokenize 后空格连接,交给 FTS5 unicode61 切词建索引。
+ * 与 buildFtsQuery 用同一分词器,保证查询 token 在索引中可命中。
+ */
+export declare function tokenizeForFts(raw: string): string;

package/dist/store/search-utils.js

@@ -0,0 +1,100 @@
+/**
+ * 检索工具:
+ * - rrfMerge:RRF(Reciprocal Rank Fusion,k=60)多路结果融合,hybrid 检索用;
+ * - bm25RankToScore:FTS5 bm25 rank(负值=更相关)转 0~1 分数;
+ * - applyDecayWeight:#29 时效衰减加权(读路径专用);
+ * - buildFtsQuery / tokenizeForFts:FTS5 查询构造与写入侧分词。
+ *   分词走 util/text.ts 的 tokenize,读写两侧共用同一分词器,保证查询 token
+ *   与索引 token 对齐;FTS 索引按分词器版本戳自动重建(sqlite.ts)。
+ */
+import { tokenize } from '../util/text.js';
+/** 标准 RRF 常数(原论文值);k 越大越偏向低排名项(分布更平滑)。 */
+export const RRF_K = 60;
+/** 衰减地板(#29 时效加权的安全边界):老记忆最多损失一半排序分,永不沉底。
+ *  内部常量不进配置——它是安全机制不是调参旋钮。 */
+export const DECAY_FLOOR = 0.5;
+/**
+ * 时效衰减加权(#29,读路径专用):score × max(FLOOR, 0.5^(Δ天/半衰期)) 后重排序。
+ *
+ * - Δ 按 updated_at(内容版本时间)起算,缺失/非法按最老 → 地板接管(零特判分支);
+ * - 乘法保相关性主导:只在相关度相近的候选之间轮转名次,不淘汰不硬过滤;
+ *   hit 的原 score 字段不被改写(排序用加权分,展示仍反映检索相关度);
+ * - halfLifeDays ≤ 0 直接原样返回(开关关闭);
+ * - 仅用于召回/工具检索;searchCandidates(去重候选)不得应用——写路径找同语义
+ *   旧记录要无视新旧,衰减会让去重漏检(同事实双记录)。
+ */
+export function applyDecayWeight(hits, halfLifeDays, updatedAtOf, now = Date.now()) {
+    if (!(halfLifeDays > 0) || hits.length === 0)
+        return hits;
+    const weight = (h) => {
+        const t = updatedAtOf(h);
+        if (t == null || !Number.isFinite(t))
+            return DECAY_FLOOR;
+        const days = Math.max(0, (now - t) / 86_400_000);
+        return Math.max(DECAY_FLOOR, 0.5 ** (days / halfLifeDays));
+    };
+    return hits
+        .map((h) => ({ h, weighted: h.score * weight(h) }))
+        .sort((a, b) => b.weighted - a.weighted)
+        .map((x) => x.h);
+}
+/**
+ * RRF 融合多个已排序列表:每项得分 = 各列表 1/(k + rank + 1) 之和。
+ * 出现在多个列表的项得分累加,按得分降序返回(附 rrfScore)。
+ */
+export function rrfMerge(lists, getId, k = RRF_K) {
+    const map = new Map();
+    for (const list of lists) {
+        for (let rank = 0; rank < list.length; rank++) {
+            const item = list[rank];
+            const id = getId(item);
+            const score = 1 / (k + rank + 1);
+            const existing = map.get(id);
+            if (existing) {
+                existing.rrfScore += score;
+            }
+            else {
+                map.set(id, { item, rrfScore: score });
+            }
+        }
+    }
+    return [...map.values()]
+        .sort((a, b) => b.rrfScore - a.rrfScore)
+        .map(({ item, rrfScore }) => ({ ...item, rrfScore }));
+}
+/** FTS5 bm25 rank(负值=更相关)转 0~1 分数。 */
+export function bm25RankToScore(rank) {
+    if (!Number.isFinite(rank))
+        return 1 / (1 + 999);
+    if (rank < 0) {
+        const relevance = -rank;
+        return relevance / (1 + relevance);
+    }
+    return 1 / (1 + rank);
+}
+/** 高频中文虚词,进 FTS 查询只添噪声。 */
+const ZH_STOP_WORDS = new Set([
+    '的', '了', '在', '是', '我', '有', '和', '就', '不', '人', '都', '一',
+    '一个', '上', '也', '很', '到', '说', '要', '去', '你', '会', '着',
+    '没有', '看', '好', '自己', '这', '他', '她', '它', '们', '那',
+    '吗', '吧', '呢', '啊', '呀', '哦', '嗯',
+]);
+/**
+ * 把自然语言查询构造成 FTS5 MATCH 表达式:token 引号化后 OR 连接,
+ * 命中任一 token 即返回,BM25 自然把命中多 token 的文档排前——
+ * 长查询与纯 FTS 模式(无向量)下召回率显著优于整句匹配。
+ */
+export function buildFtsQuery(raw) {
+    const tokens = [...new Set(tokenize(raw).filter((t) => !ZH_STOP_WORDS.has(t)))];
+    if (tokens.length === 0)
+        return null;
+    const quoted = tokens.map((t) => `"${t.replaceAll('"', '')}"`);
+    return quoted.join(' OR ');
+}
+/**
+ * 写入侧分词:tokenize 后空格连接,交给 FTS5 unicode61 切词建索引。
+ * 与 buildFtsQuery 用同一分词器,保证查询 token 在索引中可命中。
+ */
+export function tokenizeForFts(raw) {
+    return tokenize(raw).join(' ');
+}

package/dist/store/session-modes.d.ts

@@ -0,0 +1,35 @@
+import type { MemoryLogger, MemoryMode } from '../types.js';
+export declare function isMemoryMode(v: unknown): v is MemoryMode;
+export declare class SessionModeStore {
+    private readonly defaultMode;
+    private readonly logger?;
+    private readonly file;
+    private readonly entries;
+    private readonly loaded;
+    private persistFailed;
+    /** 档位切换回调(index.ts 装配 runner 的同步动作:切片落袋/挂起,ADR-0003)。 */
+    private onModeChange?;
+    /** 串行化持久化写(避免并发原子写撞临时文件名)。 */
+    private writeChain;
+    constructor(dataDir: string, defaultMode: Extract<MemoryMode, 'auto' | 'chat' | 'work'>, logger?: MemoryLogger | undefined);
+    /** 载入持久化映射(index.ts 启动时 await;失败降级内存态)。 */
+    init(): Promise<void>;
+    get default(): MemoryMode;
+    /** 同步读取:未设置过的会话返回默认档。 */
+    get(sessionId: string): MemoryMode;
+    /** 会话级注入覆盖原始值:undefined = 未覆盖,跟随全局。 */
+    getRecall(sessionId: string): boolean | undefined;
+    /** 解析后的注入开关:会话覆盖 ?? 全局运行时开关(部署级 cfg.recall.enabled
+     *  与主闸 s.enabled 不经此处,仍按既有硬门生效——覆盖打不穿部署上限)。 */
+    resolvedRecall(sessionId: string, globalRecall: boolean): boolean;
+    /** 设置会话级注入覆盖(undefined = 清除覆盖跟随全局。写穿持久化)。 */
+    setRecall(sessionId: string, recall: boolean | undefined): void;
+    /** 注册档位切换回调(同步调用;回调异常只记日志不阻断写穿)。 */
+    setModeChangeHandler(cb: (sessionId: string, oldMode: MemoryMode, newMode: MemoryMode) => void): void;
+    /** 设置会话档位(写穿持久化;持久化失败保持内存态生效)。 */
+    set(sessionId: string, mode: MemoryMode): void;
+    /** 等待在途持久化写完成(测试/停机用)。 */
+    flush(): Promise<void>;
+    private persist;
+    private serialize;
+}

package/dist/store/session-modes.js

@@ -0,0 +1,144 @@
+/**
+ * 会话记忆档位存储:sessionId → MemoryMode 的持久化映射。
+ * 热路径(捕获 turn/end、召回 pre-step、工具 execute)需要同步读取,
+ * 因此 init() 一次性载入内存 Map,set() 写穿。
+ * 存储失败只降级为内存态(warn 不崩),与插件的存储降级不变量一致。
+ */
+import * as path from 'node:path';
+import { errDetail } from '../util/filelog.js';
+import { atomicWriteJson, ensureDir, readJsonIfExists } from '../util/io.js';
+const MODES = ['auto', 'chat', 'work', 'off'];
+const PRUNE_MS = 90 * 24 * 3600_000;
+const MAX_ENTRIES = 500;
+export function isMemoryMode(v) {
+    return typeof v === 'string' && MODES.includes(v);
+}
+export class SessionModeStore {
+    defaultMode;
+    logger;
+    file;
+    entries = new Map();
+    loaded;
+    persistFailed = false;
+    /** 档位切换回调(index.ts 装配 runner 的同步动作:切片落袋/挂起,ADR-0003)。 */
+    onModeChange;
+    /** 串行化持久化写(避免并发原子写撞临时文件名)。 */
+    writeChain = Promise.resolve();
+    constructor(dataDir, defaultMode, logger) {
+        this.defaultMode = defaultMode;
+        this.logger = logger;
+        this.file = path.join(dataDir, 'session-modes.json');
+        this.loaded = defaultMode;
+    }
+    /** 载入持久化映射(index.ts 启动时 await;失败降级内存态)。 */
+    async init() {
+        const data = await readJsonIfExists(this.file);
+        if (!data?.sessions || typeof data.sessions !== 'object')
+            return;
+        const now = Date.now();
+        let count = 0;
+        for (const [sid, entry] of Object.entries(data.sessions)) {
+            if (!isMemoryMode(entry?.mode))
+                continue;
+            if (now - (entry.updatedAt ?? 0) > PRUNE_MS)
+                continue;
+            this.entries.set(sid, {
+                mode: entry.mode,
+                // 非布尔视为损坏丢弃(= 跟随全局);旧文件无此键同款兼容
+                recall: typeof entry.recall === 'boolean' ? entry.recall : undefined,
+                updatedAt: entry.updatedAt ?? now,
+            });
+            count++;
+        }
+        if (count > 0)
+            this.logger?.info(`[memory] 会话档位载入 ${count} 条(默认档=${this.defaultMode})`);
+    }
+    get default() {
+        return this.loaded;
+    }
+    /** 同步读取:未设置过的会话返回默认档。 */
+    get(sessionId) {
+        return this.entries.get(sessionId)?.mode ?? this.loaded;
+    }
+    /** 会话级注入覆盖原始值:undefined = 未覆盖,跟随全局。 */
+    getRecall(sessionId) {
+        return this.entries.get(sessionId)?.recall;
+    }
+    /** 解析后的注入开关:会话覆盖 ?? 全局运行时开关(部署级 cfg.recall.enabled
+     *  与主闸 s.enabled 不经此处,仍按既有硬门生效——覆盖打不穿部署上限)。 */
+    resolvedRecall(sessionId, globalRecall) {
+        return this.entries.get(sessionId)?.recall ?? globalRecall;
+    }
+    /** 设置会话级注入覆盖(undefined = 清除覆盖跟随全局。写穿持久化)。 */
+    setRecall(sessionId, recall) {
+        const entry = this.entries.get(sessionId);
+        this.entries.set(sessionId, {
+            mode: entry?.mode ?? this.loaded,
+            recall,
+            updatedAt: Date.now(),
+        });
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    /** 注册档位切换回调(同步调用;回调异常只记日志不阻断写穿)。 */
+    setModeChangeHandler(cb) {
+        this.onModeChange = cb;
+    }
+    /** 设置会话档位(写穿持久化;持久化失败保持内存态生效)。 */
+    set(sessionId, mode) {
+        const old = this.get(sessionId);
+        // 已有注入覆盖跨切档保留(档位与注入正交,切档不动覆盖)
+        const recall = this.entries.get(sessionId)?.recall;
+        this.entries.set(sessionId, { mode, recall, updatedAt: Date.now() });
+        this.writeChain = this.writeChain.then(() => this.persist());
+        if (old !== mode && this.onModeChange) {
+            try {
+                this.onModeChange(sessionId, old, mode);
+            }
+            catch (err) {
+                this.logger?.warn(`[memory] 档位切换回调失败: ${errDetail(err)}`);
+            }
+        }
+    }
+    /** 等待在途持久化写完成(测试/停机用)。 */
+    flush() {
+        return this.writeChain;
+    }
+    async persist() {
+        try {
+            await ensureDir(path.dirname(this.file));
+            await atomicWriteJson(this.file, this.serialize());
+            this.persistFailed = false;
+        }
+        catch (err) {
+            if (!this.persistFailed) {
+                this.persistFailed = true;
+                this.logger?.warn(`[memory] 会话档位持久化失败(降级内存态): ${errDetail(err)}`);
+            }
+        }
+    }
+    serialize() {
+        const now = Date.now();
+        // 超期清理 + 条数上限(按 updatedAt 淘汰最旧)
+        for (const [sid, e] of this.entries) {
+            if (now - e.updatedAt > PRUNE_MS)
+                this.entries.delete(sid);
+        }
+        while (this.entries.size > MAX_ENTRIES) {
+            let oldest;
+            let oldestAt = Infinity;
+            for (const [sid, e] of this.entries) {
+                if (e.updatedAt < oldestAt) {
+                    oldest = sid;
+                    oldestAt = e.updatedAt;
+                }
+            }
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        const sessions = {};
+        for (const [sid, e] of this.entries)
+            sessions[sid] = e;
+        return { version: 1, sessions };
+    }
+}