dsh-prime-memory 0.11.0

package/dist/store/embedding.js

@@ -0,0 +1,206 @@
+/** 空实现:向量能力关闭/不可用时使用,一切调用安全返回。 */
+export class NoopEmbeddingService {
+    getDimensions() {
+        return 0;
+    }
+    getProviderInfo() {
+        return { provider: 'noop', model: 'disabled', dimensions: 0 };
+    }
+    isReady() {
+        return false;
+    }
+    async embed() {
+        return new Float32Array(0);
+    }
+    async embedBatch(texts) {
+        return texts.map(() => new Float32Array(0));
+    }
+}
+/** 计数信号量(嵌入调用并发受限;防批量抽取候选召回打爆上游)。 */
+class Semaphore {
+    limit;
+    active = 0;
+    waiters = [];
+    constructor(limit) {
+        this.limit = limit;
+    }
+    async acquire() {
+        if (this.active < this.limit) {
+            this.active++;
+            return () => this.release();
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(() => {
+                this.active++;
+                resolve(() => this.release());
+            });
+        });
+    }
+    release() {
+        this.active--;
+        this.waiters.shift()?.();
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** 判定是否值得重试:网络层错误 / 5xx / 429;4xx 参数类错误立即失败。 */
+function isRetryable(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/HTTP 5\d\d|HTTP 429|fetch failed|terminated|ECONN|ETIMEDOUT|abort/i.test(msg))
+        return true;
+    return !/HTTP 4\d\d/.test(msg) && !/不匹配/.test(msg);
+}
+/**
+ * OpenAI 兼容远程 embedding:POST {baseUrl}/embeddings。
+ * 向量在客户端做 L2 归一化(与余弦度量配套)。
+ */
+export class RemoteEmbeddingService {
+    opts;
+    sem;
+    constructor(opts) {
+        this.opts = { maxInputChars: 5000, timeoutMs: 10_000, maxRetries: 2, concurrency: 4, ...opts };
+        this.sem = new Semaphore(Math.max(1, this.opts.concurrency));
+    }
+    getDimensions() {
+        return this.opts.dimensions;
+    }
+    getProviderInfo() {
+        return { provider: 'remote', model: this.opts.model, dimensions: this.opts.dimensions };
+    }
+    isReady() {
+        return true;
+    }
+    async embed(text, callOpts) {
+        const [vec] = await this.embedBatch([text], callOpts);
+        return vec;
+    }
+    async embedBatch(texts, callOpts) {
+        if (texts.length === 0)
+            return [];
+        const release = await this.sem.acquire();
+        try {
+            return await this.callWithRetry(texts, callOpts);
+        }
+        finally {
+            release();
+        }
+    }
+    async callWithRetry(texts, callOpts) {
+        const maxRetries = Math.max(0, this.opts.maxRetries);
+        let lastErr;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await this.callOnce(texts, callOpts);
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt === maxRetries || !isRetryable(err))
+                    break;
+                // 指数退避带抖动:250ms → 500ms → …,±25% 抖动防同刻重试踩踏
+                const base = 250 * 2 ** attempt;
+                await sleep(Math.round(base * (0.75 + Math.random() * 0.5)));
+            }
+        }
+        throw lastErr;
+    }
+    async callOnce(texts, callOpts) {
+        const input = texts.map((t) => t.slice(0, this.opts.maxInputChars));
+        const base = this.opts.baseUrl.replace(/\/+$/, '');
+        // 内层钳制只缩短不放大:召回路径传短超时,给 FTS 降级留时间
+        const timeoutMs = Math.min(this.opts.timeoutMs, callOpts?.timeoutMs ?? this.opts.timeoutMs);
+        const headers = { 'content-type': 'application/json' };
+        // 免 key 自托管不设鉴权头(空 Bearer 会被部分服务拒绝)
+        if (this.opts.apiKey)
+            headers.authorization = `Bearer ${this.opts.apiKey}`;
+        const res = await fetch(`${base}/embeddings`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ model: this.opts.model, input }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`embeddings HTTP ${res.status}: ${body.slice(0, 200)}`);
+        }
+        const json = (await res.json());
+        const data = json.data ?? [];
+        if (data.length !== texts.length) {
+            throw new Error(`embeddings 返回数量不匹配:期望 ${texts.length},得到 ${data.length}`);
+        }
+        // 按 index 还原顺序(部分服务商不保序)
+        const byIndex = new Map();
+        for (const d of data)
+            byIndex.set(d.index, d.embedding);
+        return input.map((_, i) => {
+            const raw = byIndex.get(i);
+            if (!raw || raw.length !== this.opts.dimensions) {
+                throw new Error(`embedding 维度不匹配:期望 ${this.opts.dimensions},得到 ${raw?.length ?? 0}`);
+            }
+            return sanitizeAndNormalize(raw);
+        });
+    }
+}
+/** 清洗 NaN/Inf 并 L2 归一化(零向量原样返回,写入侧会跳过)。 */
+function sanitizeAndNormalize(vec) {
+    const arr = Array.from(vec).map((v) => (Number.isFinite(v) ? v : 0));
+    const magnitude = Math.sqrt(arr.reduce((sum, v) => sum + v * v, 0));
+    if (magnitude < 1e-10)
+        return new Float32Array(arr);
+    return new Float32Array(arr.map((v) => v / magnitude));
+}
+/**
+ * 嵌入调用降级助手(L0/L1 Store 共用):查询向量失败 → undefined(调用方降级 FTS);
+ * 批量嵌入失败 → 全 undefined(跳过向量写入,由周期性 backfill 补齐)。
+ * 同类失败只告警一次,避免刷屏。
+ */
+export class EmbedHelper {
+    embed;
+    logger;
+    warned = false;
+    constructor(embed, logger) {
+        this.embed = embed;
+        this.logger = logger;
+    }
+    /** 活切换嵌入源:换掉底层服务并复位一次性告警(新服务重新获得告警机会)。 */
+    setService(svc) {
+        this.embed = svc;
+        this.warned = false;
+    }
+    vectorReady() {
+        return this.embed.isReady();
+    }
+    /** 查询向量;失败或空向量返回 undefined(调用方降级 FTS)。
+     *  timeoutMs 为内层钳制(仅缩短服务超时),召回路径使用。 */
+    async query(text, timeoutMs) {
+        try {
+            const vec = await this.embed.embed(text, timeoutMs != null ? { timeoutMs } : undefined);
+            return vec.length > 0 ? vec : undefined;
+        }
+        catch (err) {
+            this.warn(`查询向量计算失败,降级 FTS: ${errMsg(err)}`);
+            return undefined;
+        }
+    }
+    /** 批量嵌入;服务未就绪或失败时返回全 undefined(不阻断元数据/FTS 写入)。 */
+    async batch(texts) {
+        if (!this.embed.isReady())
+            return texts.map(() => undefined);
+        try {
+            return await this.embed.embedBatch(texts);
+        }
+        catch (err) {
+            this.warn(`批量嵌入失败,本批暂不写向量(后台 backfill 会补齐): ${errMsg(err)}`);
+            return texts.map(() => undefined);
+        }
+    }
+    warn(msg) {
+        if (this.warned)
+            return;
+        this.warned = true;
+        this.logger?.warn(`[memory] ${msg}`);
+    }
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/store/graph-store.d.ts

@@ -0,0 +1,94 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { GraphEdge, GraphNode, GraphNodeSearchResult, GraphProjectionJob, GraphProjectionResult } from '../graph/types.js';
+import type { MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+/** claim 的产出:job 元数据 + 本批真实存在的来源记录(已剔除被删者)。 */
+export interface GraphClaim {
+    job: GraphProjectionJob;
+    records: MemoryRecord[];
+}
+/** complete 的注入缝(测试回滚路径 / 确定性断言用)。 */
+export interface CompleteOptions {
+    now?: string;
+    idFactory?: (prefix: 'node' | 'edge' | 'gfact') => string;
+}
+export declare class GraphStore {
+    private db;
+    private logger;
+    private stmtInsertNode;
+    private stmtInsertEdge;
+    /** init 是否就绪(未就绪 = 图谱域整体 no-op,不抛错不传染)。 */
+    get ready(): boolean;
+    /**
+     * 建表 + 语句缓存(MemoryDb.initSchema 内调用)。任何一步失败都只告警并保持
+     * 未就绪——图谱域整体降级 no-op,检索主链路(L0/L1/FTS/向量)不受影响。
+     */
+    init(db: DatabaseSync, logger?: MemoryLogger): void;
+    /** 插件停机时清空连接引用(dispose 序调用,防悬空引用)。 */
+    close(): void;
+    /** 统一事务边界(immediate 供 complete 全程持写锁)。 */
+    private tx;
+    /** 事务内的 upsert 体(upsertTouched 与 complete 共用;调用方负责事务)。 */
+    private upsertTouchedInTx;
+    /** 全量读图谱(apply scope 与检索的统一入口;图谱量级为可重建投影,百~千级)。 */
+    loadGraph(): {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    /** 事务内的全图读取(complete 用;调用方负责事务)。 */
+    private loadGraphInTx;
+    /** 事务内按 id 装载 L1 记录(claim 与 complete 共用;调用方负责事务)。 */
+    private loadRecordsInTx;
+    /** 单节点详情(expand 用;不存在/未就绪返回 null)。 */
+    getNode(id: string): GraphNode | null;
+    /** 与某节点相连的 active 边(expand 用;悬挂 id 返回空数组,不解析不抛)。 */
+    edgesOf(nodeId: string): GraphEdge[];
+    /**
+     * 图谱检索(纯函数 searchGraphNodes 的存储缝;可选族过滤)。
+     * families 非空时只返回本族衍生的节点(档位隔离;无族信息节点一律不可见——
+     * 宁可漏不可串)。降级/异常返回空数组。
+     */
+    searchNodes(query: string, limit: number, families?: readonly MemoryFamily[]): GraphNodeSearchResult[];
+    private newJobId;
+    /**
+     * 投影入队(按 GRAPH_JOB_BATCH 分片成多个 job;去重下推 SQL):
+     * 已有在途 mapping(pending/running/failed 退避中)或已按当前版本完成投影的
+     * 记录跳过。返回实际新建的 job 数。
+     */
+    queueGraphProjection(recordIds: readonly string[], priority: number): number;
+    /**
+     * 取下一个可执行 job 并置 running(attempts +1):只认当前 projectorVersion,
+     * attempts 封顶与退避窗口在 WHERE 里过滤;来源全缺失 → job 判 dead 返 null
+     * (不可重试不抛)。部分缺失时 job 收缩到真实存在的记录子集。
+     */
+    claimNext(): GraphClaim | null;
+    /**
+     * 提交投影结果(单事务,BEGIN IMMEDIATE):读全图 scope → 纯函数 apply(硬
+     * 校验)→ 写回 touched 行 → job 置 completed + 登记已投影记录 + 放掉 mapping。
+     * job 非 running 态(已完成/已 dead/已回收)一律幂等 no-op;任何一步抛错整体
+     * 回滚,不留半写。
+     */
+    complete(jobId: string, result: GraphProjectionResult, opts?: CompleteOptions): void;
+    /**
+     * 投影失败收尾:attempts 已在 claim 时 +1——封顶转 dead(放掉 mapping,允许
+     * 重新入队);未封顶转 failed + 指数退避 nextAttemptAt(mapping 保留防重复入队)。
+     */
+    fail(jobId: string, error: string): void;
+    /** 启动回收:上次进程退出时卡在 running 的 job 放回 pending(dispose 缝不永久卡批)。 */
+    recoverRunning(): number;
+    /** 最近 job 列表(诊断/面板用;未就绪返回空)。 */
+    listJobs(limit?: number): GraphProjectionJob[];
+    /**
+     * 存量补投影:从未投影(当前版本)且无在途 mapping 的 L1 记录里按创建时间
+     * 升序取最多 limit 条分片入队(优先级 GRAPH_PRIORITY_BACKFILL,恒低于新蒸馏)。
+     * 返回新建 job 数。
+     */
+    queueMissing(limit: number): number;
+    /**
+     * 删除传播(L1 批量删除后的惰性墓碑):来源在 L1 已全部不存在的 active/disputed
+     * 节点与边标 archived(保留行,expand 可见墓碑)。挂在 MemoryDb.deleteL1Batch
+     * 之后;按 L1 存活集判定(而非本次删除集合),跨多次删除与历史孤儿一并收敛。
+     */
+    markSourcesDeleted(deletedIds: readonly string[]): void;
+    /** 清空全部图谱数据(L1 重建时调用——图谱是 L1 的投影,记录清空即图谱作废)。 */
+    resetAll(): void;
+}