@zooique/memora 2.0.0 → 3.0.0

package/dist/memory/vectorStore.js

@@ -1,257 +0,0 @@
-/**
- * 向量存储 — 纯 JS 实现，内存 + JSON 持久化
- *
- * 语义检索的向量索引层：
- * - 存储记忆 ID → 向量的映射
- * - 支持余弦相似度搜索（topK）
- * - 持久化到 JSON 文件（冷启动时加载）
- *
- * 设计原则：
- * - 0 新 npm 依赖（不引入 sqlite-vec / LanceDB 等外部向量库）
- * - 单用户本地场景，5k 条记录内纯 JS 余弦相似度 < 10ms
- * - 向量维度由 embedding 模型决定，存储层不关心
- *
- * 加固点：
- * - load() 增加 schema 校验（防止损坏文件污染内存索引）
- * - upsert/batchUpsert 增加维度一致性校验（防止维度错位导致相似度计算崩溃）
- * - save() 串行化（防止并发 save 互相覆盖丢失数据）
- * - delete() JSDoc 明确"需显式 save"约定
- *
- * 详见 ADR-002 · 存储层抽象（向量检索备选方案）
- * 详见 ADR-013 · 记忆归档三步价值过滤
- */
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { logger } from '../logging/logger.js';
-import { configError } from '../utils/errors.js';
-import { cosineSimilarity } from '../utils/math.js';
-/**
- * 校验持久化文件是否符合 VectorStoreFile schema
- *
- * 防止损坏文件 / 旧版格式 / 手动编辑错误污染内存索引。
- * 校验项：
- *   - 顶层为对象
- *   - version === 1（未来版本需迁移逻辑）
- *   - dimension 为非负整数
- *   - entries 为数组，每个条目含字符串 id 和数字数组 vector
- *   - 所有 vector 长度等于 dimension
- *
- * @param data 已 JSON.parse 的对象
- * @returns true 表示通过校验
- */
-function isValidVectorStoreFile(data) {
-    if (typeof data !== 'object' || data === null)
-        return false;
-    const obj = data;
-    if (obj.version !== 1)
-        return false;
-    if (typeof obj.dimension !== 'number' || !Number.isInteger(obj.dimension) || obj.dimension < 0) {
-        return false;
-    }
-    if (!Array.isArray(obj.entries))
-        return false;
-    for (const entry of obj.entries) {
-        if (typeof entry !== 'object' || entry === null)
-            return false;
-        const e = entry;
-        if (typeof e.id !== 'string' || e.id.length === 0)
-            return false;
-        if (!Array.isArray(e.vector))
-            return false;
-        if (!e.vector.every((v) => typeof v === 'number' && Number.isFinite(v)))
-            return false;
-        if (e.vector.length !== obj.dimension)
-            return false;
-    }
-    return true;
-}
-/**
- * JSON 持久化向量存储（IVectorStore 内核内置实现）
- *
- * 纯 JS 实现，内存中维护向量索引，定期持久化到 JSON 文件
- * 适用于单用户本地场景（5k 条记录以内）
- *
- * 依赖 EmbeddingService 接口（依赖倒置，与 llm/ 层解耦）
- * 实现 IVectorStore 接口，宿主可替换为其他实现（如 SqliteVectorStore）
- */
-export class JsonVectorStore {
-    storePath;
-    embeddingProvider;
-    /** 内存中的向量索引 */
-    entries = new Map();
-    /** 向量维度（由第一个插入的向量决定） */
-    dimension = 0;
-    /** 是否有未持久化的变更 */
-    dirty = false;
-    /**
-     * 串行化 save 调用的 Promise 链
-     *
-     * 防止并发 save 互相覆盖：每个 save 等待前一个完成后再执行。
-     * 无并发时为 null，有并发时为正在执行的 Promise。
-     */
-    savePromise = null;
-    constructor(storePath, embeddingProvider) {
-        this.storePath = storePath;
-        this.embeddingProvider = embeddingProvider;
-    }
-    /**
-     * 从 JSON 文件加载向量索引（冷启动）
-     *
-     * 加固：增加 schema 校验，损坏文件视为"从空开始"
-     * 防止部分写入 / 手动编辑错误 / 版本不匹配的文件污染内存索引
-     */
-    async load() {
-        try {
-            const content = await readFile(this.storePath, 'utf-8');
-            const data = JSON.parse(content);
-            // schema 校验：损坏 / 格式错误的文件视为"从空开始"，避免污染内存索引
-            if (!isValidVectorStoreFile(data)) {
-                logger.warn({ path: this.storePath }, '向量索引文件格式无效，从空开始');
-                return;
-            }
-            this.dimension = data.dimension;
-            this.entries.clear();
-            for (const entry of data.entries) {
-                this.entries.set(entry.id, entry.vector);
-            }
-            this.dirty = false;
-            logger.info({ count: this.entries.size, dimension: this.dimension }, '向量索引加载完成');
-        }
-        catch {
-            // 文件不存在或 JSON 解析失败，从空开始
-            logger.info({ path: this.storePath }, '向量索引文件不存在，从空开始');
-        }
-    }
-    /**
-     * 持久化向量索引到 JSON 文件
-     *
-     * 加固：串行化并发 save，防止互相覆盖丢失数据。
-     * 调用方可在并发场景下安全地多次调用 save，每次都会等待前一次完成。
-     *
-     * @returns 等待所有挂起 save 完成的 Promise
-     */
-    async save() {
-        // 串行化：若已有 save 在执行，将本次调用追加到链尾
-        if (this.savePromise !== null) {
-            this.savePromise = this.savePromise.then(() => this.doSave());
-            return this.savePromise;
-        }
-        this.savePromise = this.doSave().finally(() => {
-            // 当前链路完成，清空引用以允许下次独立 save
-            this.savePromise = null;
-        });
-        return this.savePromise;
-    }
-    /**
-     * 实际执行持久化的内部方法
-     *
-     * 由 save() 串行化调度，外部不应直接调用
-     */
-    async doSave() {
-        if (!this.dirty)
-            return;
-        const data = {
-            version: 1,
-            dimension: this.dimension,
-            entries: Array.from(this.entries.entries()).map(([id, vector]) => ({ id, vector })),
-        };
-        await mkdir(dirname(this.storePath), { recursive: true });
-        await writeFile(this.storePath, JSON.stringify(data), 'utf-8');
-        this.dirty = false;
-        logger.info({ count: this.entries.size }, '向量索引持久化完成');
-    }
-    /**
-     * 为文本生成向量并存储
-     *
-     * 加固：维度一致性校验，防止维度错位导致 cosineSimilarity 计算崩溃
-     *
-     * @param id 记忆 ID
-     * @param text 待嵌入的文本
-     * @param options embedding 调用选项（signal 外部取消 + timeoutMs 超时）
-     * @throws {MemoraError} 当 embedding 返回的向量维度与已存维度不一致时抛出 configError
-     */
-    async upsert(id, text, options) {
-        const vector = await this.embeddingProvider.embed(text, options);
-        if (this.dimension === 0) {
-            this.dimension = vector.length;
-        }
-        else if (vector.length !== this.dimension) {
-            // 维度不一致会破坏 cosineSimilarity 计算（长度不匹配返回 0）
-            // 此处主动报错，让调用方感知模型切换或配置错误
-            // G-1：统一 MemoraError 体系，提供中文标题 + 排查建议
-            throw configError('向量维度不一致', `期望 ${this.dimension}，实际 ${vector.length}（id=${id}）。可能是 embedding 模型切换导致。`, ['清空 vectors.json 后重试', '检查 embedding 模型是否切换']);
-        }
-        this.entries.set(id, vector);
-        this.dirty = true;
-    }
-    /**
-     * 批量嵌入并存储
-     *
-     * 加固：维度一致性校验，与 upsert 同契约
-     *
-     * @param items ID + 文本对
-     * @param options embedding 调用选项（signal 外部取消 + timeoutMs 超时）
-     * @throws {MemoraError} 当 embedding 返回的向量维度与已存维度不一致时抛出 configError
-     */
-    async batchUpsert(items, options) {
-        const texts = items.map((item) => item.text);
-        const results = await this.embeddingProvider.batchEmbed(texts, options);
-        for (let i = 0; i < items.length; i++) {
-            const result = results[i];
-            const item = items[i];
-            if (!result || !item)
-                continue;
-            if (this.dimension === 0) {
-                this.dimension = result.vector.length;
-            }
-            else if (result.vector.length !== this.dimension) {
-                // 维度不一致会破坏 cosineSimilarity 计算
-                // G-1：统一 MemoraError 体系，提供中文标题 + 排查建议
-                throw configError('批量插入向量维度不一致', `期望 ${this.dimension}，实际 ${result.vector.length}（id=${item.id}）`, ['清空 vectors.json 后重试', '检查 embedding 模型是否切换']);
-            }
-            this.entries.set(item.id, result.vector);
-        }
-        this.dirty = true;
-    }
-    /**
-     * 删除向量
-     *
-     * 注意：此方法仅标记 dirty=true，不会自动调用 save。
-     * 调用方需在合适的时机显式调用 save() 持久化删除操作，
-     * 否则下次冷启动会重新加载已删除的向量。
-     *
-     * @param id 待删除的记忆 ID
-     */
-    delete(id) {
-        this.entries.delete(id);
-        this.dirty = true;
-    }
-    /**
-     * 语义搜索：基于查询文本的向量，返回 topK 最相似的 ID
-     * @param query 查询文本
-     * @param topK 返回数量上限
-     * @param minSimilarity 最低相似度阈值（0~1）
-     * @param options embedding 调用选项（signal 外部取消 + timeoutMs 超时）
-     * @returns ID + 相似度 对的数组，按相似度降序排列
-     */
-    async search(query, topK = 5, minSimilarity = 0.3, options) {
-        const queryVector = await this.embeddingProvider.embed(query, options);
-        const scored = [];
-        for (const [id, vector] of this.entries) {
-            const similarity = cosineSimilarity(queryVector, vector);
-            if (similarity >= minSimilarity) {
-                scored.push({ id, similarity });
-            }
-        }
-        // 按相似度降序排列，取 topK
-        scored.sort((a, b) => b.similarity - a.similarity);
-        return scored.slice(0, topK);
-    }
-    /**
-     * 获取存储的向量数量
-     */
-    get size() {
-        return this.entries.size;
-    }
-}
-//# sourceMappingURL=vectorStore.js.map

package/dist/memory/vectorStore.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"vectorStore.js","sourceRoot":"","sources":["../../src/memory/vectorStore.ts"],"names":[],"mappings":"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"}

package/dist/persona/personaManager.d.ts

@@ -1,160 +0,0 @@
-import type { IMemoryStorage } from '../memory/storageInterface.js';
-import type { Persona, PersonaMode } from '../persona/types.js';
-/**
- * 角色管理器（personas/ + SQLite + 关键词匹配）
- */
-export declare class PersonaManager {
-    private readonly configDir?;
-    private readonly index?;
-    /** 当前激活的角色 */
-    private activePersona;
-    /** 角色列表缓存（启动时扫描一次） */
-    private personaList;
-    /** 激活模式 */
-    private mode;
-    /** 角色切换时间戳列表（用于时间窗口缓冲） */
-    private switchTimestamps;
-    /** 缓冲区开关（60s 内 3 次切换后锁定） */
-    private switchLocked;
-    /** 锁定恢复计时器 */
-    private unlockTimer;
-    /** 时间窗口：60 秒 */
-    private static readonly SWITCH_WINDOW_MS;
-    /** 窗口内最大切换次数 */
-    private static readonly MAX_SWITCHES_IN_WINDOW;
-    /** 锁定后自动恢复时间：5 分钟 */
-    private static readonly AUTO_UNLOCK_MS;
-    /**
-     * @param configDir 配置目录（角色文件在 <configDir>/personas/ 下）
-     * @param index SQLite 索引（用于写入 persona 记忆）
-     */
-    constructor(configDir?: string | undefined, index?: IMemoryStorage | undefined);
-    /**
-     * 启动时加载：扫描目录 + 激活指定角色 + 写入 SQLite
-     *
-     * @param activePersona 要激活的角色名（可选，不传则使用第一个找到的角色）
-     * @returns 激活角色的 system prompt 段
-     */
-    load(activePersona?: string): Promise<string>;
-    /**
-     * 获取当前激活的角色名（用于 bootstrap 过滤）
-     */
-    get activeName(): string;
-    /**
-     * 获取当前激活角色对象（Phase 2.1：AffectController 需要 traits 字段）
-     *
-     * 返回 null 时表示未加载任何角色（使用默认行为）。
-     */
-    getActive(): Persona | null;
-    /**
-     * 切换角色（带时间窗口缓冲）
-     *
-     * 错误策略统一（IX-03）：角色不存在时抛 MemoraError，与 switchProject 一致。
-     * 交换锁定时仍返回当前 prompt（非错误，是限流保护）。
-     *
-     * @param name 角色名
-     * @returns 新角色的 system prompt 段
-     * @throws MemoraError 如果角色不存在
-     */
-    switchPersona(name: string): string;
-    /**
-     * 根据用户输入自动匹配最合适的角色（关键词高置信度匹配）
-     *
-     * 匹配策略：
-     *   - 关键词匹配高置信度（≥ KEYWORD_HIGH_CONFIDENCE_THRESHOLD）→ 直接返回
-     *   - 关键词低置信度/无匹配 → 返回 null（由 agent 层决定是否调用 LLM 辅助）
-     *
-     * LLM 辅助语义匹配已迁移到 agent 层（agent/personaMatcher.ts），
-     * 遵循 backend_layers_rules §分层职责：persona/ 不直接调 LLM。
-     *
-     * 匹配前置条件：
-     *   - 当前模式为 'auto'（非手动锁定）
-     *   - 缓冲区未锁定
-     *   - 角色列表非空
-     *   - 匹配的角色与当前角色不同
-     *
-     * @param userInput 用户输入文本
-     * @returns 匹配的角色名，无匹配返回 null
-     */
-    autoMatch(userInput: string): Promise<string | null>;
-    /**
-     * 检查是否满足自动匹配的前置条件
-     *
-     * 供 agent 层在调用 matchPersonaByLlm 前判断是否值得尝试 LLM 辅助匹配。
-     * 前置条件与 autoMatch 内部检查一致：
-     *   - 当前模式为 'auto'（非手动锁定）
-     *   - 缓冲区未锁定
-     *   - 角色列表非空
-     *
-     * @returns 是否满足自动匹配前置条件
-     */
-    canAutoMatch(): boolean;
-    /**
-     * 关键词匹配：遍历角色列表，返回得分最高的角色
-     *
-     * @param userInput 用户输入文本
-     * @returns 得分最高的角色和得分，无命中返回 null
-     */
-    private findBestKeywordMatch;
-    /**
-     * 设置激活模式
-     *
-     * @param mode 'auto'（自动匹配）| 'manual'（手动固定）
-     */
-    setMode(mode: PersonaMode): void;
-    /** 获取当前激活模式 */
-    get currentMode(): PersonaMode;
-    /**
-     * 获取角色列表
-     */
-    get list(): Persona[];
-    /**
-     * 清理定时器资源（Agent.close() 时调用）
-     *
-     * PersonaManager 持有 unlockTimer（角色切换防抖锁的自动恢复计时器），
-     * 若不清理，Agent 关闭后定时器仍会触发回调，在已关闭的实例上执行引发异常。
-     */
-    close(): void;
-    /**
-     * 重载角色：清空内存缓存 + 重新扫描目录 + 同步 SQLite 索引 + 保持当前激活角色
-     *
-     * 事件驱动重载：confirmConfigSuggestion 写入 persona 文件后或用户手动编辑
-     * personas/ 目录后，调用此方法使当前会话立即生效，无需重启 Agent。
-     *
-     * 激活角色保持策略：
-     * - 若当前激活角色在重载后仍存在 → 更新为重载后的版本（内容可能已变更）
-     * - 若当前激活角色已被删除 → 回退到列表第一个角色（与 load() 默认行为一致）
-     *
-     * @returns 重载后的角色数量
-     */
-    reload(): Promise<number>;
-    /**
-     * 构建 system prompt 中的角色段
-     */
-    buildSystemPrompt(name?: string): string;
-    /**
-     * 记录一次角色切换（时间窗口缓冲）
-     */
-    private recordSwitch;
-    /**
-     * 扫描单层目录，加载角色列表
-     */
-    private scanPersonas;
-    /**
-     * 将所有角色写入 SQLite 索引
-     *
-     * 本函数循环体内无 await，作为同步函数实现。
-     */
-    private writeAllToIndex;
-    /**
-     * 将单个角色写入 SQLite 索引
-     *
-     * 函数体无 await，作为同步函数实现。index.upsert 是同步方法。
-     */
-    private writePersonaToIndex;
-    /**
-     * 创建默认角色
-     */
-    private createDefaultPersona;
-}
-//# sourceMappingURL=personaManager.d.ts.map

package/dist/persona/personaManager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"personaManager.d.ts","sourceRoot":"","sources":["../../src/persona/personaManager.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAMnE,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAgC/D;;GAEG;AACH,qBAAa,cAAc;IA0BvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IA1BzB,cAAc;IACd,OAAO,CAAC,aAAa,CAAwB;IAC7C,sBAAsB;IACtB,OAAO,CAAC,WAAW,CAAiB;IACpC,WAAW;IACX,OAAO,CAAC,IAAI,CAAuB;IACnC,0BAA0B;IAC1B,OAAO,CAAC,gBAAgB,CAAgB;IACxC,4BAA4B;IAC5B,OAAO,CAAC,YAAY,CAAS;IAC7B,cAAc;IACd,OAAO,CAAC,WAAW,CAA8C;IAEjE,gBAAgB;IAChB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAClD,gBAAgB;IAChB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAK;IACnD,qBAAqB;IACrB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAW;IAEjD;;;OAGG;gBAEgB,SAAS,CAAC,EAAE,MAAM,YAAA,EAClB,KAAK,CAAC,EAAE,cAAc,YAAA;IAGzC;;;;;OAKG;IACG,IAAI,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqCnD;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;OAIG;IACH,SAAS,IAAI,OAAO,GAAG,IAAI;IAI3B;;;;;;;;;OASG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAyBnC;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAiB1D;;;;;;;;;;OAUG;IACH,YAAY,IAAI,OAAO;IAIvB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAUhC,eAAe;IACf,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,OAAO,EAAE,CAEpB;IAED;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAOb;;;;;;;;;;;OAWG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IA4B/B;;OAEG;IACH,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAUxC;;OAEG;IACH,OAAO,CAAC,YAAY;IAqBpB;;OAEG;YACW,YAAY;IAyB1B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;OAEG;IACH,OAAO,CAAC,oBAAoB;CAU7B"}