@zooique/memora 2.0.0 → 2.0.3

package/dist/memory/store.js

@@ -6,11 +6,12 @@
  */
 import { readFile, writeFile, mkdir, readdir, stat } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { SOURCE_LABELS } from '../memory/types.js';
-import { inferSource } from '../memory/sourceValidation.js';
+import { SOURCE_LABELS, DEFAULT_MEMORY_SCORE } from '../memory/types.js';
+import { inferSource, validateSource } from '../memory/sourceValidation.js';
 import { parseFrontmatter, serializeFrontmatter as serializeFm } from '../utils/frontmatter.js';
 import { logger } from '../logging/logger.js';
 import { toError } from '../utils/toError.js';
+import { configError } from '../utils/errors.js';
 /**
  * 已知 source 到文件系统目录的映射
  *
@@ -22,8 +23,6 @@ const SOURCE_TO_DIR = {
     [SOURCE_LABELS.RULE]: 'rules',
     [SOURCE_LABELS.SKILL]: 'skills',
 };
-/** 无 frontmatter 或 score 缺失时的默认 score */
-const DEFAULT_MEMORY_SCORE = 0.5;
 /**
  * 文件存储类
  *
@@ -43,7 +42,8 @@ export class FileStore {
      */
     async read(source, name) {
         const filePath = this.getFilePath(source, name);
-        // 异步读取：文件不存在时 readFile 抛 ENOENT，捕获后返回 null（避免 existsSync 的 TOCTOU 竞态）
+        // 异步读取：文件不存在时 readFile 抛 ENOENT，handleFsError 对 ENOENT 静默返回（read 返回 null）
+        // 其他错误（EACCES/EISDIR 等）由 handleFsError 重新抛出，让调用方感知故障
         let content;
         let fileStat;
         try {
@@ -51,23 +51,32 @@ export class FileStore {
             fileStat = await stat(filePath);
         }
         catch (err) {
-            // ENOENT 属正常情况（文件不存在），静默返回 null；其他错误（EACCES/EISDIR 等）记录警告
-            const error = toError(err);
-            if (error.code !== 'ENOENT') {
-                logger.warn({ path: filePath, code: error.code, err: error.message }, '记忆文件读取失败');
-            }
-            return null;
+            this.handleFsError(err, filePath, '记忆文件读取失败');
+            return null; // 仅 ENOENT 到达此处（其他错误已在 handleFsError 抛出）
         }
         // 从文件路径推断 source（frontmatter 可覆盖）
         return this.parseMemory(source, name, content, filePath, fileStat.mtime);
     }
     /**
      * 写入记忆文件
+     *
+     * frontmatter 包含标准字段（id/source/score/createdAt/accessedAt）
+     * 和 memory.metadata 中的额外元数据（如 keywords/description）。
      */
     async write(memory) {
         const filePath = this.getFilePath(memory.source, memory.name);
         await mkdir(dirname(filePath), { recursive: true });
+        // 标准字段必须优先于 metadata：metadata 中可能含同名键（如恶意的 source='evil'），
+        // 若后展开则劫持 source 语义绕过 sourceValidation。先展开 metadata，再显式覆盖标准字段；
+        // 并过滤掉与标准字段同名的 metadata 键，避免写入重复行（如 source: evil\n source: normal）。
+        const STANDARD_KEYS = new Set(['id', 'source', 'score', 'createdAt', 'accessedAt']);
+        const safeMeta = {};
+        for (const [k, v] of Object.entries(memory.metadata ?? {})) {
+            if (!STANDARD_KEYS.has(k))
+                safeMeta[k] = v;
+        }
         const frontmatter = serializeFm({
+            ...safeMeta,
             id: memory.id,
             source: memory.source,
             score: String(memory.score),
@@ -85,18 +94,15 @@ export class FileStore {
      */
     async list(source) {
         const dir = join(this.dataDir, this.sourceToDir(source));
-        // 异步读取：目录不存在时 readdir 抛 ENOENT，捕获后返回空数组（避免 existsSync 的 TOCTOU 竞态）
+        // 异步读取：目录不存在时 readdir 抛 ENOENT，handleFsError 对 ENOENT 静默返回（list 返回 []）
+        // 其他错误由 handleFsError 重新抛出，让调用方感知故障
         let files;
         try {
             files = await readdir(dir);
         }
         catch (err) {
-            // ENOENT 属正常情况（目录不存在），静默返回空数组；其他错误（EACCES/EISDIR 等）记录警告
-            const error = toError(err);
-            if (error.code !== 'ENOENT') {
-                logger.warn({ dir, code: error.code, err: error.message }, '记忆目录读取失败');
-            }
-            return [];
+            this.handleFsError(err, dir, '记忆目录读取失败');
+            return []; // 仅 ENOENT 到达此处（其他错误已在 handleFsError 抛出）
         }
         return files.filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''));
     }
@@ -109,11 +115,43 @@ export class FileStore {
     /**
      * source 到目录名的映射
      *
-     * 已知 source 使用预定义目录，未知 source 直接用 source 字符串作目录名
+     * 已知 source 使用预定义目录，未知 source 直接用 source 字符串作目录名。
+     * 安全校验：调用 validateSource 拒绝路径遍历（`..`）、null 字节等危险字符，
+     * 防止未知 source 被构造为恶意路径绕过 SOURCE_TO_DIR 白名单。
      */
     sourceToDir(source) {
+        const result = validateSource(source);
+        if (result.severity === 'block') {
+            // 路径遍历 / null 字节 / 空字符串等安全边界违规，必须拒绝
+            throw configError('source 校验失败，拒绝映射到目录', result.warning, ['检查 source 字段是否包含路径遍历序列或特殊字符']);
+        }
         return SOURCE_TO_DIR[source] ?? source;
     }
+    /**
+     * 文件系统错误统一处理
+     *
+     * 区分两类错误：
+     *   - ENOENT（文件/目录不存在）：正常情况，静默返回
+     *   - 其他错误（EACCES/EISDIR 等）：真实故障，抛出异常让调用方感知
+     *
+     * 之前所有错误统一返回 null/[]，导致磁盘故障伪装成"无数据"，
+     * 用户感知不到数据丢失。现区分：ENOENT 静默，其他抛错。
+     *
+     * @param err 捕获的异常
+     * @param path 文件/目录路径（用于日志上下文）
+     * @param label 日志标签（中文，如 "记忆文件读取失败"）
+     * @throws {NodeJS.ErrnoException} 非 ENOENT 错误时重新抛出
+     */
+    handleFsError(err, path, label) {
+        const error = toError(err);
+        if (error.code === 'ENOENT') {
+            // 文件/目录不存在是正常情况（首次启动、新项目等），静默返回
+            return;
+        }
+        // 非 ENOENT 错误：记录警告并重新抛出，让调用方区分"无数据"与"故障"
+        logger.warn({ path, code: error.code, err: error.message }, label);
+        throw error;
+    }
     /**
      * 解析记忆文件为 Memory 对象
      *
@@ -141,7 +179,7 @@ export class FileStore {
             };
         }
         const now = mtime.toISOString();
-        // 修复 #34：校验 score，防止 NaN/越界值违反 zod schema（min(0).max(1)）
+        // 修复 #34：校验 score，防止 NaN/越界值违反校验规则（min(0).max(1)）
         // frontmatter 中 score 字段若为非数字字符串（如 "abc"），Number 返回 NaN 会破坏后续写入
         const rawScore = Number(meta['score'] ?? DEFAULT_MEMORY_SCORE);
         const score = Number.isFinite(rawScore) && rawScore >= 0 && rawScore <= 1

package/dist/memory/store.js.map

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

package/dist/memory/types.d.ts

@@ -4,51 +4,62 @@
  * 设计哲学：万物皆是记忆，用 source 开放字符串替代封闭枚举
  * 详见 ADR-004 · 记忆统一模型
  */
-import { z } from 'zod';
 /**
- * 记忆基元 schema
+ * 记忆基元接口
  *
  * 8 个核心字段（v2.1 软删除扩展），无封闭枚举
  * - 7 个基础字段：id/content/source/name/createdAt/accessedAt/score
  * - 1 个可选字段：deletedAt（软删除时间，undefined 表示活跃记忆）
  */
-export declare const MemorySchema: z.ZodObject<{
+export interface Memory {
     /** 唯一标识（source:name，如 'rule:core'、'insight:1718083200000'） */
-    id: z.ZodString;
-    /** 记忆内容（Markdown 文本） */
-    content: z.ZodString;
-    /** 来源标签（开放字符串，非枚举） */
-    source: z.ZodString;
-    /** 可读名称（文件名或摘要标题） */
-    name: z.ZodString;
-    /** 创建时间（ISO 8601） */
-    createdAt: z.ZodString;
-    /** 最后访问时间（每次召回时刷新） */
-    accessedAt: z.ZodString;
-    /** 权重（0-1，召回时用于排序） */
-    score: z.ZodDefault<z.ZodNumber>;
-    /** 软删除时间（ISO 8601，可选；非 undefined 表示已软删除，回收站保留 30 天后自动物理清理） */
-    deletedAt: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
     id: string;
+    /** 记忆内容（Markdown 文本） */
     content: string;
+    /** 来源标签（开放字符串，非枚举） */
     source: string;
+    /** 可读名称（文件名或摘要标题） */
     name: string;
+    /** 创建时间（ISO 8601） */
     createdAt: string;
+    /** 最后访问时间（每次召回时刷新） */
     accessedAt: string;
+    /** 权重（0-1，召回时用于排序） */
     score: number;
-    deletedAt?: string | undefined;
-}, {
-    id: string;
-    content: string;
-    source: string;
-    name: string;
-    createdAt: string;
-    accessedAt: string;
-    score?: number | undefined;
-    deletedAt?: string | undefined;
-}>;
-export type Memory = z.infer<typeof MemorySchema>;
+    /** 软删除时间（ISO 8601，可选；非 undefined 表示已软删除，回收站保留 30 天后自动物理清理） */
+    deletedAt?: string;
+    /**
+     * 可选：配置文件 frontmatter 的额外元数据
+     *
+     * 仅在写入配置文件时使用（FileStore.write 合并到 frontmatter）。
+     * SQLite index 不存储此字段（运行时检索不需要）。
+     * 典型场景：persona 的 keywords/description，供 PersonaManager 加载时解析。
+     */
+    metadata?: Record<string, string>;
+}
+/** 默认记忆权重（parseMemory 的默认值行为） */
+export declare const DEFAULT_MEMORY_SCORE = 0.5;
+/**
+ * 记忆解析器 — 验证原始数据并转换为 Memory 类型
+ *
+ * 提供与原 MemorySchema.parse() 等效的运行时验证能力：
+ * - 非空对象检查
+ * - 字段类型验证（string/number）
+ * - ISO 8601 日期格式验证
+ * - score 范围检查（0-1）
+ * - 默认值填充（score = 0.5）
+ *
+ * @param raw - 原始数据（通常来自 JSON 解析或数据库查询）
+ * @returns 验证通过的 Memory 对象
+ * @throws Error 当数据不符合 Memory 接口定义时
+ */
+export declare function parseMemory(raw: unknown): Memory;
+/**
+ * 兼容性别名 — 保持原有测试代码 (MemorySchema.parse(...)) 无需修改
+ */
+export declare const MemorySchema: {
+    parse: typeof parseMemory;
+};
 /**
  * 泊文当前使用的 source 标签约定
  *
@@ -70,6 +81,8 @@ export declare const SOURCE_LABELS: {
     readonly WORK_PROJECTION: "work-projection";
     /** 内容护栏规则（configDir/rules/guardrails/ 下的规则文件） */
     readonly GUARDRAIL: "guardrail";
+    /** 未知来源（inferSource 兜底值，文件路径未匹配已知目录时的默认标签） */
+    readonly UNKNOWN: "unknown";
 };
 /**
  * 记忆关系基元 — 独立于 Memory 7 字段的侧车数据结构

package/dist/memory/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;IACvB,8DAA8D;;IAE9D,wBAAwB;;IAExB,sBAAsB;;IAEtB,qBAAqB;;IAErB,qBAAqB;;IAErB,sBAAsB;;IAEtB,sBAAsB;;IAEtB,8DAA8D;;;;;;;;;;;;;;;;;;;;EAE9D,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAIlD;;;;;GAKG;AACH,eAAO,MAAM,aAAa;IACxB,uCAAuC;;IAEvC,yDAAyD;;IAEzD,qCAAqC;;IAErC,2BAA2B;;IAE3B,2BAA2B;;IAE3B,+BAA+B;;IAE/B,iDAAiD;;CAEzC,CAAC;AASX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wBAAwB;;IAExB,oBAAoB;;IAEpB,8BAA8B;;IAE9B,oBAAoB;;IAEpB,sBAAsB;;CAEd,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,cAAc;IACzB,eAAe;;IAEf,aAAa;;IAEb,eAAe;;IAEf,gBAAgB;;IAEhB,aAAa;;IAEb,gBAAgB;;CAER,CAAC;AAIX;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gCAAgC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,cAAc;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;CACpC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,iCAAiC;AACjC,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAoEhD;AAED;;GAEG;AACH,eAAO,MAAM,YAAY;;CAAyB,CAAC;AAInD;;;;;GAKG;AACH,eAAO,MAAM,aAAa;IACxB,uCAAuC;;IAEvC,yDAAyD;;IAEzD,qCAAqC;;IAErC,2BAA2B;;IAE3B,2BAA2B;;IAE3B,+BAA+B;;IAE/B,iDAAiD;;IAEjD,8CAA8C;;CAEtC,CAAC;AASX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wBAAwB;;IAExB,oBAAoB;;IAEpB,8BAA8B;;IAE9B,oBAAoB;;IAEpB,sBAAsB;;CAEd,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,cAAc;IACzB,eAAe;;IAEf,aAAa;;IAEb,eAAe;;IAEf,gBAAgB;;IAEhB,aAAa;;IAEb,gBAAgB;;CAER,CAAC;AAIX;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gCAAgC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,cAAc;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;CACpC"}

package/dist/memory/types.js

@@ -4,33 +4,70 @@
  * 设计哲学：万物皆是记忆，用 source 开放字符串替代封闭枚举
  * 详见 ADR-004 · 记忆统一模型
  */
-import { z } from 'zod';
-// ─── 基元定义 ─────────────────────────────────────────────
+import { configError } from '../utils/errors.js';
+/** 默认记忆权重（parseMemory 的默认值行为） */
+export const DEFAULT_MEMORY_SCORE = 0.5;
 /**
- * 记忆基元 schema
+ * 记忆解析器 — 验证原始数据并转换为 Memory 类型
  *
- * 8 个核心字段（v2.1 软删除扩展），无封闭枚举
- * - 7 个基础字段：id/content/source/name/createdAt/accessedAt/score
- * - 1 个可选字段：deletedAt（软删除时间，undefined 表示活跃记忆）
+ * 提供与原 MemorySchema.parse() 等效的运行时验证能力：
+ * - 非空对象检查
+ * - 字段类型验证（string/number）
+ * - ISO 8601 日期格式验证
+ * - score 范围检查（0-1）
+ * - 默认值填充（score = 0.5）
+ *
+ * @param raw - 原始数据（通常来自 JSON 解析或数据库查询）
+ * @returns 验证通过的 Memory 对象
+ * @throws Error 当数据不符合 Memory 接口定义时
+ */
+export function parseMemory(raw) {
+    if (raw === null || typeof raw !== 'object') {
+        throw configError('Memory 解析失败', '输入必须是非空对象', ['检查数据源（JSON 文件 / 数据库查询）是否返回了有效对象']);
+    }
+    const obj = raw;
+    // 验证必需的 string 字段
+    const stringFields = ['id', 'content', 'source', 'name'];
+    for (const field of stringFields) {
+        if (typeof obj[field] !== 'string') {
+            throw configError('Memory 解析失败', `${field} 必须是字符串`, [`检查数据源中 ${field} 字段的类型（当前为 ${typeof obj[field]}）`]);
+        }
+    }
+    // 验证 ISO 8601 日期字段
+    const dateFields = ['createdAt', 'accessedAt'];
+    for (const field of dateFields) {
+        if (typeof obj[field] !== 'string' || isNaN(Date.parse(obj[field]))) {
+            throw configError('Memory 解析失败', `${field} 必须是有效的 ISO 8601 日期字符串`, [`检查数据源中 ${field} 字段的格式（当前值: ${JSON.stringify(obj[field])}）`]);
+        }
+    }
+    // 验证 score 字段（可选，有默认值）
+    // Number.isFinite 同时排除 NaN/Infinity（对齐 zod z.number() 行为）
+    if (obj.score !== undefined && obj.score !== null) {
+        if (typeof obj.score !== 'number' || !Number.isFinite(obj.score) || obj.score < 0 || obj.score > 1) {
+            throw configError('Memory 解析失败', `score 必须是 0-1 之间的数字（当前值: ${String(obj.score)}）`, ['将 score 调整为 0-1 之间的有效数字']);
+        }
+    }
+    // 验证可选的 deletedAt 字段
+    if (obj.deletedAt !== undefined && obj.deletedAt !== null) {
+        if (typeof obj.deletedAt !== 'string' || isNaN(Date.parse(obj.deletedAt))) {
+            throw configError('Memory 解析失败', `deletedAt 必须是有效的 ISO 8601 日期字符串（当前值: ${JSON.stringify(obj.deletedAt)}）`, ['检查数据源中 deletedAt 字段的格式']);
+        }
+    }
+    return {
+        id: obj.id,
+        content: obj.content,
+        source: obj.source,
+        name: obj.name,
+        createdAt: obj.createdAt,
+        accessedAt: obj.accessedAt,
+        score: obj.score ?? DEFAULT_MEMORY_SCORE,
+        deletedAt: obj.deletedAt,
+    };
+}
+/**
+ * 兼容性别名 — 保持原有测试代码 (MemorySchema.parse(...)) 无需修改
  */
-export const MemorySchema = z.object({
-    /** 唯一标识（source:name，如 'rule:core'、'insight:1718083200000'） */
-    id: z.string(),
-    /** 记忆内容（Markdown 文本） */
-    content: z.string(),
-    /** 来源标签（开放字符串，非枚举） */
-    source: z.string(),
-    /** 可读名称（文件名或摘要标题） */
-    name: z.string(),
-    /** 创建时间（ISO 8601） */
-    createdAt: z.string().datetime(),
-    /** 最后访问时间（每次召回时刷新） */
-    accessedAt: z.string().datetime(),
-    /** 权重（0-1，召回时用于排序） */
-    score: z.number().min(0).max(1).default(0.5),
-    /** 软删除时间（ISO 8601，可选；非 undefined 表示已软删除，回收站保留 30 天后自动物理清理） */
-    deletedAt: z.string().datetime().optional(),
-});
+export const MemorySchema = { parse: parseMemory };
 // ─── source 标签约定（非枚举，仅为泊文当前使用的约定） ──────
 /**
  * 泊文当前使用的 source 标签约定
@@ -53,6 +90,8 @@ export const SOURCE_LABELS = {
     WORK_PROJECTION: 'work-projection',
     /** 内容护栏规则（configDir/rules/guardrails/ 下的规则文件） */
     GUARDRAIL: 'guardrail',
+    /** 未知来源（inferSource 兜底值，文件路径未匹配已知目录时的默认标签） */
+    UNKNOWN: 'unknown',
 };
 /**
  * weight 四档离散值常量（LLM 输出约束）

package/dist/memory/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yDAAyD;AAEzD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,8DAA8D;IAC9D,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,wBAAwB;IACxB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,sBAAsB;IACtB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,qBAAqB;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,qBAAqB;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,sBAAsB;IACtB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,sBAAsB;IACtB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;IAC5C,8DAA8D;IAC9D,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC5C,CAAC,CAAC;AAIH,0CAA0C;AAE1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,uCAAuC;IACvC,OAAO,EAAE,SAAS;IAClB,yDAAyD;IACzD,IAAI,EAAE,MAAM;IACZ,qCAAqC;IACrC,KAAK,EAAE,OAAO;IACd,2BAA2B;IAC3B,OAAO,EAAE,SAAS;IAClB,2BAA2B;IAC3B,OAAO,EAAE,SAAS;IAClB,+BAA+B;IAC/B,eAAe,EAAE,iBAAiB;IAClC,iDAAiD;IACjD,SAAS,EAAE,WAAW;CACd,CAAC;AA8CX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,wBAAwB;IACxB,IAAI,EAAE,GAAG;IACT,oBAAoB;IACpB,IAAI,EAAE,GAAG;IACT,8BAA8B;IAC9B,SAAS,EAAE,GAAG;IACd,oBAAoB;IACpB,MAAM,EAAE,GAAG;IACX,sBAAsB;IACtB,OAAO,EAAE,GAAG;CACJ,CAAC;AAEX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,eAAe;IACf,WAAW,EAAE,aAAa;IAC1B,aAAa;IACb,QAAQ,EAAE,UAAU;IACpB,eAAe;IACf,OAAO,EAAE,SAAS;IAClB,gBAAgB;IAChB,OAAO,EAAE,SAAS;IAClB,aAAa;IACb,MAAM,EAAE,QAAQ;IAChB,gBAAgB;IAChB,OAAO,EAAE,SAAS;CACV,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"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"}

package/dist/memory/userProfile.d.ts

@@ -23,6 +23,13 @@ export interface UserProfileEntry {
     id: string;
     /** 子分类 */
     category: ProfileCategory;
+    /**
+     * 显式字段名
+     *
+     * 标识同 category 下的具体字段（如 identity 下 "姓名"/"住址"/"职业"），
+     * 用于冲突检测——同 category + 同 fieldName 视为同一字段的更新。
+     */
+    fieldName: string;
     /** 事实值（如 "姓名: 张三"） */
     value: string;
     /** 来源（哪一轮对话提到） */
@@ -37,6 +44,14 @@ export interface UserProfileEntry {
 /** extractUserFacts 的原始提取结果 */
 export interface ExtractedFact {
     category: ProfileCategory;
+    /**
+     * 显式字段名
+     *
+     * 由提取器显式填充（如 "姓名"/"住址"/"职业"/"偏好"/"工具"/"专长"），
+     * 冲突检测基于 category + fieldName，即使 value 格式变化（如 LLM 输出无前缀），
+     * 仍能正确识别冲突。
+     */
+    fieldName: string;
     value: string;
     sourceTurn: string;
     /** 置信度 0-1（≥0.8 直接归档，否则标记待确认） */
@@ -118,13 +133,16 @@ export declare class UserProfile {
      */
     private upsertFact;
     /**
-     * 删除同分类的旧条目（用户更新了信息）
+     * 删除同分类同字段的旧条目（用户更新了信息）
+     *
+     * 当用户说"我叫李四"替换之前的"我叫张三"时，移除旧的 identity/姓名 条目。
      *
-     * 当用户说"我叫李四"替换之前的"我叫张三"时，移除旧的 identity 条目。
-     * 策略：同分类（category）下，新值替换旧值。判断标准是旧条目的 value 前缀。
+     * 冲突判定基于 `category + fieldName`：
+     * - 新数据：fact.fieldName 由提取器显式填充，parseContentField 返回 parsed.fieldName
+     * - 旧数据：parseContentField 降级从 value 前缀提取 fieldName（兼容历史持久化数据）
+     * - 同 category + 同 fieldName + 不同 value = 用户更新了该字段，删除旧条目
      *
-     * 从 content JSON 解码 category，替代 name 字段隐式解析。
-     * 构建 contentPrefix → entry 的 Map 索引，冲突检测从 O(n*m) 降为 O(m)。
+     * 构建 `category:fieldName` → Memory[] 的 Map 索引，冲突检测从 O(n*m) 降为 O(m)。
      *
      * @param fact 当前提取到的新事实
      */
@@ -132,20 +150,26 @@ export declare class UserProfile {
     /**
      * 将 UserProfileEntry 转为 Memory（用于写入 SQLite）
      *
-     * content 字段使用 JSON 编码存储 category + value 元数据，
+     * content 字段使用 JSON 编码存储 category + value + fieldName 元数据，
      * name 字段为固定可读标签，category 通过 content 的 JSON 元数据显式编码。
      * 确认状态：仅已确认条目调用此方法（待确认条目不写入存储）
      */
     private toMemory;
     /**
-     * 从 content 字段解析 category 和 value
+     * 从 content 字段解析 category / value / fieldName
      *
      * 优先从 content JSON 解码元数据，降级到旧格式 name 字段解析，
      * 确保已有 SQLite 数据（旧格式 name="${category}: ${value}"）兼容加载。
      *
+     * fieldName 解析优先级：
+     *   1. content JSON 含 fieldName → 直接返回（新数据）
+     *   2. content JSON 无 fieldName → 从 value 前缀提取（旧 JSON 数据，无 fieldName 字段）
+     *   3. name 字段旧格式 → 从 value 前缀提取
+     *   4. 最终降级 → fieldName = 'unknown'（无法识别字段名，冲突检测会跳过）
+     *
      * @param content Memory 的 content 字段（新格式为 JSON，旧格式为纯 value）
      * @param name Memory 的 name 字段（旧格式为 "${category}: ${value}"）
-     * @returns 解析出的 category 和 value
+     * @returns 解析出的 category / value / fieldName
      */
     private parseContentField;
     /**

package/dist/memory/userProfile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"userProfile.d.ts","sourceRoot":"","sources":["../../src/memory/userProfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAOnE,cAAc;AACd,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5F,aAAa;AACb,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,UAAU;IACV,QAAQ,EAAE,eAAe,CAAC;IAC1B,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC,4BAA4B;IAC5B,OAAO,CAAC,KAAK,CAA4C;gBAE5B,KAAK,EAAE,cAAc;IAElD;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgCzC;;;;;;;;OAQG;IACG,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAYvE;;OAEG;IACH,YAAY,IAAI,gBAAgB,EAAE;IAIlC;;;;;OAKG;IACH,UAAU,IAAI,gBAAgB,EAAE;IAIhC;;;;;;;;;OASG;IACH,iBAAiB,IAAI,MAAM;IA0B3B;;;;;;OAMG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxC;;;;OAIG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAavC;;;;;;;;;OASG;YACW,UAAU;IA2CxB;;;;;;;;;;OAUG;YACW,wBAAwB;IA+CtC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAahB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAgCzB;;OAEG;IACH,OAAO,CAAC,aAAa;CAUtB"}
+{"version":3,"file":"userProfile.d.ts","sourceRoot":"","sources":["../../src/memory/userProfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAOnE,cAAc;AACd,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;AAqD5F,aAAa;AACb,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,UAAU;IACV,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC,4BAA4B;IAC5B,OAAO,CAAC,KAAK,CAA4C;gBAE5B,KAAK,EAAE,cAAc;IAElD;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAmCzC;;;;;;;;OAQG;IACG,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAYvE;;OAEG;IACH,YAAY,IAAI,gBAAgB,EAAE;IAIlC;;;;;OAKG;IACH,UAAU,IAAI,gBAAgB,EAAE;IAIhC;;;;;;;;;OASG;IACH,iBAAiB,IAAI,MAAM;IA0B3B;;;;;;OAMG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxC;;;;OAIG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAavC;;;;;;;;;OASG;YACW,UAAU;IAoDxB;;;;;;;;;;;;;OAaG;YACW,wBAAwB;IA2CtC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAmBhB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,iBAAiB;IAoCzB;;OAEG;IACH,OAAO,CAAC,aAAa;CAUtB"}