@zooique/memora 0.1.0

package/dist/memory/store.js

@@ -0,0 +1,160 @@
+/**
+ * 记忆文件存储
+ *
+ * 冷热分离中的"热"：文件承载记忆本体
+ * 详见 ADR-002 · IMemoryStorage 接口与宿主注入模式
+ */
+import { readFile, writeFile, mkdir, readdir, stat } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { SOURCE_LABELS, inferSource } from '../memory/types.js';
+import { parseFrontmatter, serializeFrontmatter as serializeFm } from '../utils/frontmatter.js';
+import { logger } from '../logging/logger.js';
+import { toError } from '../utils/errors.js';
+/**
+ * 已知 source 到文件系统目录的映射
+ *
+ * 仅覆盖配置类记忆（启动时扫描的 persona/rule/skill）；
+ * 运行时产生的记忆（insight/profile/work-projection）不由 FileStore 管理
+ */
+const SOURCE_TO_DIR = {
+    [SOURCE_LABELS.PERSONA]: 'personas',
+    [SOURCE_LABELS.RULE]: 'rules',
+    [SOURCE_LABELS.SKILL]: 'skills',
+};
+/** 无 frontmatter 或 score 缺失时的默认 score */
+const DEFAULT_MEMORY_SCORE = 0.5;
+/**
+ * 文件存储类
+ *
+ * 每个 source 对应一个子目录（personas/rules/skills/…）
+ * 读取时通过 inferSource() 从文件路径推断 source
+ */
+export class FileStore {
+    dataDir;
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    /**
+     * 读取记忆文件
+     *
+     * @param source - 来源标签（如 'rule'、'persona'）
+     * @param name - 记忆名（不含扩展名）
+     */
+    async read(source, name) {
+        const filePath = this.getFilePath(source, name);
+        // 异步读取：文件不存在时 readFile 抛 ENOENT，捕获后返回 null（避免 existsSync 的 TOCTOU 竞态）
+        let content;
+        let fileStat;
+        try {
+            content = await readFile(filePath, 'utf-8');
+            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;
+        }
+        // 从文件路径推断 source（frontmatter 可覆盖）
+        return this.parseMemory(source, name, content, filePath, fileStat.mtime);
+    }
+    /**
+     * 写入记忆文件
+     */
+    async write(memory) {
+        const filePath = this.getFilePath(memory.source, memory.name);
+        await mkdir(dirname(filePath), { recursive: true });
+        const frontmatter = serializeFm({
+            id: memory.id,
+            source: memory.source,
+            score: String(memory.score),
+            createdAt: memory.createdAt,
+            accessedAt: memory.accessedAt,
+        });
+        const content = `---\n${frontmatter}\n---\n\n${memory.content}`;
+        await writeFile(filePath, content, 'utf-8');
+    }
+    /**
+     * 列出某个 source 下的所有记忆
+     *
+     * @param source - 来源标签（如 'rule'、'persona'）
+     * @returns 记忆名称列表（不含扩展名）
+     */
+    async list(source) {
+        const dir = join(this.dataDir, this.sourceToDir(source));
+        // 异步读取：目录不存在时 readdir 抛 ENOENT，捕获后返回空数组（避免 existsSync 的 TOCTOU 竞态）
+        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 [];
+        }
+        return files.filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''));
+    }
+    /**
+     * 获取文件路径
+     */
+    getFilePath(source, name) {
+        return join(this.dataDir, this.sourceToDir(source), `${name}.md`);
+    }
+    /**
+     * source 到目录名的映射
+     *
+     * 已知 source 使用预定义目录，未知 source 直接用 source 字符串作目录名
+     */
+    sourceToDir(source) {
+        return SOURCE_TO_DIR[source] ?? source;
+    }
+    /**
+     * 解析记忆文件为 Memory 对象
+     *
+     * @param source - 来源标签
+     * @param name - 记忆名
+     * @param raw - 文件原始内容
+     * @param filePath - 文件路径（用于 inferSource 回退）
+     * @param mtime - 文件修改时间
+     */
+    parseMemory(source, name, raw, filePath, mtime) {
+        const { frontmatter: meta, body } = parseFrontmatter(raw);
+        // 从 frontmatter 读取 source（如有显式声明则覆盖）
+        const resolvedSource = meta['source'] ?? inferSource(filePath, source);
+        // 无 frontmatter 时，使用默认值
+        if (Object.keys(meta).length === 0) {
+            const now = mtime.toISOString();
+            return {
+                id: `${resolvedSource}:${name}`,
+                content: raw,
+                source: resolvedSource,
+                name,
+                createdAt: now,
+                accessedAt: now,
+                score: DEFAULT_MEMORY_SCORE,
+            };
+        }
+        const now = mtime.toISOString();
+        // 修复 #34：校验 score，防止 NaN/越界值违反 zod schema（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
+            ? rawScore
+            : DEFAULT_MEMORY_SCORE;
+        return {
+            id: meta['id'] ?? `${resolvedSource}:${name}`,
+            content: body.trim(),
+            source: resolvedSource,
+            name,
+            createdAt: meta['createdAt'] ?? now,
+            accessedAt: meta['accessedAt'] ?? now,
+            score,
+        };
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/memory/store.js.map

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

package/dist/memory/types.d.ts

@@ -0,0 +1,189 @@
+/**
+ * 记忆类型定义 — 基元驱动模型
+ *
+ * 设计哲学：万物皆是记忆，用 source 开放字符串替代封闭枚举
+ * 详见 ADR-004 · 记忆统一模型
+ */
+import { z } from 'zod';
+/**
+ * 记忆基元 schema
+ *
+ * 7 个核心字段，无封闭枚举，无额外元数据
+ */
+export declare const MemorySchema: z.ZodObject<{
+    /** 唯一标识（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>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    content: string;
+    source: string;
+    name: string;
+    createdAt: string;
+    accessedAt: string;
+    score: number;
+}, {
+    id: string;
+    content: string;
+    source: string;
+    name: string;
+    createdAt: string;
+    accessedAt: string;
+    score?: number | undefined;
+}>;
+export type Memory = z.infer<typeof MemorySchema>;
+/**
+ * 泊文当前使用的 source 标签约定
+ *
+ * 注意：source 是开放字符串，新增来源无需改代码
+ * 只需在存储时指定 source 字符串即可
+ */
+export declare const SOURCE_LABELS: {
+    /** 角色人格（agent-config/personas/*.md） */
+    readonly PERSONA: "persona";
+    /** 创作规则（agent-config/rules/*.md + .memora/rules/*.md） */
+    readonly RULE: "rule";
+    /** 技能定义（agent-config/skills/*.md） */
+    readonly SKILL: "skill";
+    /** 对话洞察（每轮问答结束后 LLM 提取） */
+    readonly INSIGHT: "insight";
+    /** 用户画像（每轮问答中 LLM 实时提取） */
+    readonly PROFILE: "profile";
+    /** 作品投影（Agent 读取用户作品时生成的概要） */
+    readonly WORK_PROJECTION: "work-projection";
+    /** 内容护栏规则（configDir/rules/guardrails/ 下的规则文件） */
+    readonly GUARDRAIL: "guardrail";
+};
+/**
+ * 中文停用词集合
+ * 用于关键词提取时过滤无意义词汇
+ */
+export declare const STOPWORDS: Set<string>;
+/**
+ * 从文件路径自动推断 source（目录映射 + frontmatter 覆盖）
+ *
+ * @param filePath - 文件路径
+ * @param frontmatterSource - frontmatter 中显式声明的 source（可选）
+ * @returns source 字符串
+ */
+export declare function inferSource(filePath: string, frontmatterSource?: string): string;
+/**
+ * 转义 LIKE 通配符，防止注入
+ *
+ * @param str - 原始字符串
+ * @returns 转义后的字符串
+ */
+export declare function escapeLike(str: string): string;
+/**
+ * source 校验严重级别
+ *
+ * - 'block'：安全边界违规，调用方必须拒绝写入（throw）
+ * - 'warn'：调用方 bug 或疑似 typo，应 warn 但允许写入
+ * - undefined：无异常
+ */
+export type SourceValidationSeverity = 'block' | 'warn';
+/**
+ * 校验 source 字段是否为已知标签
+ *
+ * 返回校验结果，包含严重级别与警告信息（如有）。
+ *
+ * 分级策略：
+ * - 路径遍历（`..`）与 null 字节 → severity='block'（安全边界，必须拒绝）
+ * - 空字符串、非字符串、首尾空格 → severity='block'（调用方 bug，必须拒绝）
+ * - 与已知标签 Levenshtein 距离 ≤ 2 的疑似 typo → severity='warn'（保持开放性）
+ * - 其他自定义 source → valid: true（完全允许）
+ *
+ * @param source - 待校验的 source 字符串
+ * @returns 校验结果
+ */
+export declare function validateSource(source: string): {
+    valid: boolean;
+    severity?: SourceValidationSeverity;
+    warning?: string;
+};
+/**
+ * 记忆关系基元 — 独立于 Memory 7 字段的侧车数据结构
+ *
+ * 设计原则（ADR-014）：
+ * - 不侵入 Memory 类型，与 Memory 平行存在
+ * - 关系类型是开放字符串（非枚举），宿主可自由扩展
+ * - 存储有向（sourceId → targetId），查询时按 direction 参数过滤
+ *
+ * 预设关系类型建议值（非强制）：
+ * - 'contradicts'：矛盾（双向对称）
+ * - 'supports'：支持（有向）
+ * - 'follows'：时间先后（有向）
+ * - 'refines'：细化/演化（有向）
+ * - 'caused'：因果（有向）
+ * - 'related'：泛相关（双向对称）
+ */
+export interface MemoryRelation {
+    /** 关系起点（Memory.id） */
+    sourceId: string;
+    /** 关系终点（Memory.id） */
+    targetId: string;
+    /** 关系类型（开放字符串，非枚举） */
+    type: string;
+    /** 关系强度 0-1（LLM 四档：0.0/0.3/0.7/1.0，代码默认 0.5 兜底） */
+    weight: number;
+    /** 创建时间（ISO 8601） */
+    createdAt: string;
+}
+/**
+ * 关系查询方向
+ * - 'outgoing'：只查 sourceId = memoryId 的关系（冲突检测用）
+ * - 'incoming'：只查 targetId = memoryId 的关系
+ * - 'both'：合并两个方向并去重（可视化/召回增强用，默认）
+ */
+export type RelationDirection = 'outgoing' | 'incoming' | 'both';
+/**
+ * weight 四档离散值常量（LLM 输出约束）
+ *
+ * 设计理由（ADR-014 §4）：
+ * - 离散值比连续浮点稳定，LLM 输出可预测
+ * - 0.5 兜底避免 LLM 失败时关系数据缺失
+ */
+export declare const RELATION_WEIGHTS: {
+    /** 几乎无关（LLM 明确判断无关系） */
+    readonly NONE: 0;
+    /** 弱相关（关系存在但强度低） */
+    readonly WEAK: 0.3;
+    /** 未判断（代码默认兜底，LLM 失败或未输出时） */
+    readonly UNDEFINED: 0.5;
+    /** 强相关（关系明确且强度高） */
+    readonly STRONG: 0.7;
+    /** 确定关系（矛盾/等价等强关系） */
+    readonly CERTAIN: 1;
+};
+/**
+ * 预设关系类型建议值（非枚举，仅作约定）
+ *
+ * 注意：type 是开放字符串，新增关系类型无需改代码
+ * 只需在存储时指定 type 字符串即可
+ */
+export declare const RELATION_TYPES: {
+    /** 矛盾（双向对称） */
+    readonly CONTRADICTS: "contradicts";
+    /** 支持（有向） */
+    readonly SUPPORTS: "supports";
+    /** 时间先后（有向） */
+    readonly FOLLOWS: "follows";
+    /** 细化/演化（有向） */
+    readonly REFINES: "refines";
+    /** 因果（有向） */
+    readonly CAUSED: "caused";
+    /** 泛相关（双向对称） */
+    readonly RELATED: "related";
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +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;;;;GAIG;AACH,eAAO,MAAM,YAAY;IACvB,8DAA8D;;IAE9D,wBAAwB;;IAExB,sBAAsB;;IAEtB,qBAAqB;;IAErB,qBAAqB;;IAErB,sBAAsB;;IAEtB,sBAAsB;;;;;;;;;;;;;;;;;;EAEtB,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;AAIX;;;GAGG;AACH,eAAO,MAAM,SAAS,aAOpB,CAAC;AAIH;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,CAWhF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAYD;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,MAAM,CAAC;AAExD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAC9C,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAgDA;AAoCD;;;;;;;;;;;;;;;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"}

package/dist/memory/types.js

@@ -0,0 +1,230 @@
+/**
+ * 记忆类型定义 — 基元驱动模型
+ *
+ * 设计哲学：万物皆是记忆，用 source 开放字符串替代封闭枚举
+ * 详见 ADR-004 · 记忆统一模型
+ */
+import { z } from 'zod';
+// ─── 基元定义 ─────────────────────────────────────────────
+/**
+ * 记忆基元 schema
+ *
+ * 7 个核心字段，无封闭枚举，无额外元数据
+ */
+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),
+});
+// ─── source 标签约定（非枚举，仅为泊文当前使用的约定） ──────
+/**
+ * 泊文当前使用的 source 标签约定
+ *
+ * 注意：source 是开放字符串，新增来源无需改代码
+ * 只需在存储时指定 source 字符串即可
+ */
+export const SOURCE_LABELS = {
+    /** 角色人格（agent-config/personas/*.md） */
+    PERSONA: 'persona',
+    /** 创作规则（agent-config/rules/*.md + .memora/rules/*.md） */
+    RULE: 'rule',
+    /** 技能定义（agent-config/skills/*.md） */
+    SKILL: 'skill',
+    /** 对话洞察（每轮问答结束后 LLM 提取） */
+    INSIGHT: 'insight',
+    /** 用户画像（每轮问答中 LLM 实时提取） */
+    PROFILE: 'profile',
+    /** 作品投影（Agent 读取用户作品时生成的概要） */
+    WORK_PROJECTION: 'work-projection',
+    /** 内容护栏规则（configDir/rules/guardrails/ 下的规则文件） */
+    GUARDRAIL: 'guardrail',
+};
+// ─── 分词相关 ─────────────────────────────────────────────
+/**
+ * 中文停用词集合
+ * 用于关键词提取时过滤无意义词汇
+ */
+export const STOPWORDS = new Set([
+    '的', '了', '是', '在', '我', '有', '和', '就', '不', '人', '都',
+    '一', '一个', '上', '也', '很', '到', '说', '要', '去', '你', '会',
+    '着', '没有', '看', '好', '自己', '这', '那', '什么', '怎么', '可以',
+    '这个', '那个', '他们', '我们', '因为', '所以', '但是', '如果', '虽然',
+    '能', '把', '被', '让', '给', '对', '从', '为', '比', '与', '或',
+    '吗', '呢', '吧', '啊', '哦', '嗯', '呀', '哈',
+]);
+// ─── 工具函数 ─────────────────────────────────────────────
+/**
+ * 从文件路径自动推断 source（目录映射 + frontmatter 覆盖）
+ *
+ * @param filePath - 文件路径
+ * @param frontmatterSource - frontmatter 中显式声明的 source（可选）
+ * @returns source 字符串
+ */
+export function inferSource(filePath, frontmatterSource) {
+    // 优先：frontmatter 中显式声明的 source
+    if (frontmatterSource)
+        return frontmatterSource;
+    // 回退：目录路径映射（使用路径分隔符匹配，避免 'other-personas/' 误匹配）
+    if (/[\\/]personas[\\/]/.test(filePath))
+        return SOURCE_LABELS.PERSONA;
+    if (/[\\/]rules[\\/]/.test(filePath))
+        return SOURCE_LABELS.RULE;
+    if (/[\\/]skills[\\/]/.test(filePath))
+        return SOURCE_LABELS.SKILL;
+    // 默认
+    return 'unknown';
+}
+/**
+ * 转义 LIKE 通配符，防止注入
+ *
+ * @param str - 原始字符串
+ * @returns 转义后的字符串
+ */
+export function escapeLike(str) {
+    return str.replace(/[%_]/g, '\\$&');
+}
+// ─── Source 校验 ────────────────────────────────────────────
+/**
+ * 已知 source 标签集合（用于运行时校验）
+ *
+ * 从 SOURCE_LABELS 常量自动派生，保持同步。
+ * 不是枚举——只用于 typo 检测，不阻止写入。
+ */
+const KNOWN_SOURCES = new Set(Object.values(SOURCE_LABELS));
+/**
+ * 校验 source 字段是否为已知标签
+ *
+ * 返回校验结果，包含严重级别与警告信息（如有）。
+ *
+ * 分级策略：
+ * - 路径遍历（`..`）与 null 字节 → severity='block'（安全边界，必须拒绝）
+ * - 空字符串、非字符串、首尾空格 → severity='block'（调用方 bug，必须拒绝）
+ * - 与已知标签 Levenshtein 距离 ≤ 2 的疑似 typo → severity='warn'（保持开放性）
+ * - 其他自定义 source → valid: true（完全允许）
+ *
+ * @param source - 待校验的 source 字符串
+ * @returns 校验结果
+ */
+export function validateSource(source) {
+    if (!source || typeof source !== 'string') {
+        return {
+            valid: false,
+            severity: 'block',
+            warning: `source 不能为空或非字符串，收到：${String(source)}`,
+        };
+    }
+    if (source.trim() !== source) {
+        return {
+            valid: false,
+            severity: 'block',
+            warning: `source 包含首尾空格："${source}"`,
+        };
+    }
+    if (source.includes('..')) {
+        return {
+            valid: false,
+            severity: 'block',
+            warning: `source 不能包含路径遍历序列："${source}"`,
+        };
+    }
+    if (source.includes('\0')) {
+        return {
+            valid: false,
+            severity: 'block',
+            warning: `source 不能包含 null 字节`,
+        };
+    }
+    // 检查与已知标签的相似度（简单 Levenshtein 距离 ≤ 2）
+    if (!KNOWN_SOURCES.has(source)) {
+        const closeMatch = [...KNOWN_SOURCES].find((known) => levenshtein(source, known) <= 2 && source !== known);
+        if (closeMatch) {
+            return {
+                valid: true,
+                severity: 'warn',
+                warning: `source "${source}" 可能是 "${closeMatch}" 的拼写错误（已知标签：${[...KNOWN_SOURCES].join(', ')}）`,
+            };
+        }
+    }
+    return { valid: true };
+}
+/**
+ * 简单 Levenshtein 距离计算（仅用于短字符串，不做优化）
+ */
+function levenshtein(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++)
+        matrix[i] = [i];
+    // QC-17 移除非空断言：提取局部变量并 null 检查
+    const row0 = matrix[0];
+    if (row0)
+        for (let j = 0; j <= a.length; j++)
+            row0[j] = j;
+    for (let i = 1; i <= b.length; i++) {
+        // QC-17 移除非空断言：提取局部变量，用 ?? 0 兜底（初始化保证值存在）
+        const rowI = matrix[i];
+        const rowPrev = matrix[i - 1];
+        if (!rowI || !rowPrev)
+            continue;
+        for (let j = 1; j <= a.length; j++) {
+            const cost = b[i - 1] === a[j - 1] ? 0 : 1;
+            rowI[j] = Math.min((rowPrev[j] ?? 0) + 1, (rowI[j - 1] ?? 0) + 1, (rowPrev[j - 1] ?? 0) + cost);
+        }
+    }
+    // QC-17 移除非空断言：使用可选链 + 空值合并兜底
+    return matrix[b.length]?.[a.length] ?? 0;
+}
+/**
+ * weight 四档离散值常量（LLM 输出约束）
+ *
+ * 设计理由（ADR-014 §4）：
+ * - 离散值比连续浮点稳定，LLM 输出可预测
+ * - 0.5 兜底避免 LLM 失败时关系数据缺失
+ */
+export const RELATION_WEIGHTS = {
+    /** 几乎无关（LLM 明确判断无关系） */
+    NONE: 0.0,
+    /** 弱相关（关系存在但强度低） */
+    WEAK: 0.3,
+    /** 未判断（代码默认兜底，LLM 失败或未输出时） */
+    UNDEFINED: 0.5,
+    /** 强相关（关系明确且强度高） */
+    STRONG: 0.7,
+    /** 确定关系（矛盾/等价等强关系） */
+    CERTAIN: 1.0,
+};
+/**
+ * 预设关系类型建议值（非枚举，仅作约定）
+ *
+ * 注意：type 是开放字符串，新增关系类型无需改代码
+ * 只需在存储时指定 type 字符串即可
+ */
+export const RELATION_TYPES = {
+    /** 矛盾（双向对称） */
+    CONTRADICTS: 'contradicts',
+    /** 支持（有向） */
+    SUPPORTS: 'supports',
+    /** 时间先后（有向） */
+    FOLLOWS: 'follows',
+    /** 细化/演化（有向） */
+    REFINES: 'refines',
+    /** 因果（有向） */
+    CAUSED: 'caused',
+    /** 泛相关（双向对称） */
+    RELATED: 'related',
+};
+//# sourceMappingURL=types.js.map

package/dist/memory/types.js.map

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