@zooique/memora 0.3.0 → 1.0.1

package/dist/agent/managers/relationBuilder.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 关系构建器 — ADR-014 记忆关系构建的专职 Manager
+ *
+ * 从 InsightExtractor 拆分出来（P1-3），负责：
+ *   - 召回关系判断候选记忆（top-5 关键词搜索）
+ *   - 构建关系判断 prompt 片段（候选列表 + 关系类型说明）
+ *   - 解析 LLM 输出的 relations 字段并写入 IMemoryRelationStore
+ *   - contradicts 关系检测 + onConflict 回调通知
+ *
+ * 设计原则：
+ *   - 独立于 InsightExtractor 生命周期，仅依赖 IMemoryStorage + IMemoryRelationStore
+ *   - 静默降级——relationStore 未注入时所有方法返回空/no-op（ADR-014 降级优先）
+ *   - 薄层代理——关系写入直接透传到 IMemoryRelationStore，仅增加 weight 推断 + targetId 校验
+ *
+ * 与 InsightExtractor 的分工（P1-3 拆分，1.0 接口稳定化）：
+ *   - InsightExtractor：insight 提取 + 去重 + 写入 + 输入分类
+ *   - RelationBuilder：候选召回 + prompt 构建 + 关系写入 + 冲突检测
+ *
+ * 详见 ADR-014（记忆关系侧车模型）+ 迭代文档 P1-3
+ */
+import type { Memory } from '../../memory/types.js';
+import type { IMemoryStorage } from '../../memory/storageInterface.js';
+import type { IMemoryRelationStore } from '../../memory/relationStore.js';
+/**
+ * 冲突信息（contradicts 关系检测到时传递给宿主）
+ *
+ * 由 RelationBuilder.buildRelations 检测到 contradicts 关系时构造，
+ * 通过 onConflict 回调传递给 Agent，Agent emit('conflictDetected') 通知宿主。
+ */
+export interface ConflictInfo {
+    /** 新写入的 insight 记忆 ID */
+    newMemoryId: string;
+    /** 新洞察内容（用于 UI 展示） */
+    newInsight: string;
+    /** 被矛盾的已有记忆 ID */
+    targetId: string;
+    /** 被矛盾的已有记忆内容（用于 UI 展示） */
+    targetContent: string;
+}
+/**
+ * 关系构建器
+ *
+ * 封装 ADR-014 记忆关系构建的全部逻辑，从 InsightExtractor 拆分（P1-3）。
+ * relationStore 未注入时所有方法静默降级（返回空/no-op）。
+ */
+export declare class RelationBuilder {
+    private readonly index;
+    private readonly relationStore;
+    /** 冲突检测回调（由 Agent 通过 bindOnConflict 注入，检测到 contradicts 时触发） */
+    private onConflict;
+    /**
+     * @param index 记忆存储（用于候选召回的关键词搜索）
+     * @param relationStore 记忆关系存储（可选，未注入时所有方法静默降级）
+     */
+    constructor(index: IMemoryStorage, relationStore?: IMemoryRelationStore | null);
+    /** 关系构建是否启用（relationStore 已注入时为 true） */
+    get enabled(): boolean;
+    /**
+     * 绑定冲突检测回调
+     *
+     * 由 Agent.init() 在创建 InsightExtractor 后调用（与 bindGetRecentHistory 同模式），
+     * 解决 Agent 实例晚于 InsightExtractor 创建的时序循环依赖。
+     * buildRelations 检测到 contradicts 关系时调用此回调，Agent 在回调中 emit('conflictDetected')。
+     *
+     * @param fn 冲突检测回调（传入 null 可解除绑定）
+     */
+    bindOnConflict(fn: ((info: ConflictInfo) => void) | null): void;
+    /**
+     * 召回关系判断候选记忆（top-5）
+     *
+     * 用用户输入关键词搜索已有记忆，作为 LLM 关系判断的参考。
+     * 用户输入与提取出的 insight 通常相关，候选记忆也相关。
+     * relationStore 未注入时返回空数组（降级）。
+     *
+     * @param userInput 用户输入（用于关键词搜索）
+     * @returns 候选记忆列表（id + content 截断）
+     */
+    recallRelationCandidates(userInput: string): Memory[];
+    /**
+     * 构建候选记忆列表的 prompt 片段
+     *
+     * 格式：
+     *   已有记忆（供关系判断参考）：
+     *   [1] id: xxx, content: xxx
+     *   [2] id: xxx, content: xxx
+     *
+     * @param candidates 候选记忆列表
+     * @returns prompt 片段（空候选时返回空字符串）
+     */
+    buildCandidatesPrompt(candidates: Memory[]): string;
+    /**
+     * 构建关系判断的 prompt 指令片段
+     *
+     * 包含 relations 字段格式说明 + 关系类型说明 + 注意事项。
+     * relationStore 未注入时返回空字符串（降级，不影响 insight 提取主流程）。
+     *
+     * @returns prompt 指令片段（relationStore 未注入时为空字符串）
+     */
+    buildRelationsPrompt(): string;
+    /**
+     * 构建关系（写入 IMemoryRelationStore）
+     *
+     * 解析 LLM 输出的 relations 字段，验证 targetId 在候选列表中，写入关系存储。
+     * 降级策略：relationStore 未注入/relations 为空/targetId 无效 → 跳过，不阻塞主流程。
+     *
+     * 检测到 contradicts 关系时，通过 onConflict 回调通知 Agent，
+     * Agent emit('conflictDetected') 触发宿主消费链路（ProactiveBanner 通知用户）。
+     *
+     * @param insightId 新写入的 insight ID
+     * @param insightContent 新写入的 insight 内容（用于冲突通知 UI 展示）
+     * @param relations LLM 输出的关系列表
+     * @param candidates 候选记忆列表（用于验证 targetId + 查找 targetContent）
+     */
+    buildRelations(insightId: string, insightContent: string, relations: Array<{
+        targetId?: unknown;
+        type?: unknown;
+    }>, candidates: Memory[]): void;
+    /**
+     * 根据关系类型推断 weight（ADR-014 §4）
+     *
+     * LLM 只输出 type，weight 由代码层推断：
+     * - contradicts → 1.0（确定关系，矛盾是强关系）
+     * - supports/follows/refines/caused → 0.7（强相关）
+     * - related → 0.3（弱相关）
+     * - 未知类型 → 0.5（未判断兜底）
+     *
+     * 设计理由：降低 LLM 认知负担，离散值比连续浮点稳定
+     */
+    private weightByType;
+}
+//# sourceMappingURL=relationBuilder.d.ts.map

package/dist/agent/managers/relationBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationBuilder.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/relationBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AActE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAC;CACvB;AAID;;;;;GAKG;AACH,qBAAa,eAAe;IASxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAThC,+DAA+D;IAC/D,OAAO,CAAC,UAAU,CAA+C;IAEjE;;;OAGG;gBAEgB,KAAK,EAAE,cAAc,EACrB,aAAa,GAAE,oBAAoB,GAAG,IAAW;IAGpE,yCAAyC;IACzC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAM/D;;;;;;;;;OASG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAMrD;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM;IAWnD;;;;;;;OAOG;IACH,oBAAoB,IAAI,MAAM;IAqB9B;;;;;;;;;;;;;OAaG;IACH,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,KAAK,CAAC;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,EACxD,UAAU,EAAE,MAAM,EAAE,GACnB,IAAI;IA4CP;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;CAYrB"}

package/dist/agent/managers/relationBuilder.js

@@ -0,0 +1,191 @@
+import { RELATION_WEIGHTS } from '../../memory/types.js';
+import { escapeLike } from '../../memory/sourceValidation.js';
+import { logger } from '../../logging/logger.js';
+import { nowIso } from '../../utils/time.js';
+// ─── 常量 ────────────────────────────────────────────────
+/** 关系判断：召回候选记忆数量上限（top-5） */
+const RELATION_CANDIDATE_LIMIT = 5;
+/** 关系判断：候选记忆 content 注入 prompt 的截断上限（字符） */
+const RELATION_CANDIDATE_CONTENT_LIMIT = 100;
+// ─── 类 ──────────────────────────────────────────────────
+/**
+ * 关系构建器
+ *
+ * 封装 ADR-014 记忆关系构建的全部逻辑，从 InsightExtractor 拆分（P1-3）。
+ * relationStore 未注入时所有方法静默降级（返回空/no-op）。
+ */
+export class RelationBuilder {
+    index;
+    relationStore;
+    /** 冲突检测回调（由 Agent 通过 bindOnConflict 注入，检测到 contradicts 时触发） */
+    onConflict = null;
+    /**
+     * @param index 记忆存储（用于候选召回的关键词搜索）
+     * @param relationStore 记忆关系存储（可选，未注入时所有方法静默降级）
+     */
+    constructor(index, relationStore = null) {
+        this.index = index;
+        this.relationStore = relationStore;
+    }
+    /** 关系构建是否启用（relationStore 已注入时为 true） */
+    get enabled() {
+        return this.relationStore !== null;
+    }
+    /**
+     * 绑定冲突检测回调
+     *
+     * 由 Agent.init() 在创建 InsightExtractor 后调用（与 bindGetRecentHistory 同模式），
+     * 解决 Agent 实例晚于 InsightExtractor 创建的时序循环依赖。
+     * buildRelations 检测到 contradicts 关系时调用此回调，Agent 在回调中 emit('conflictDetected')。
+     *
+     * @param fn 冲突检测回调（传入 null 可解除绑定）
+     */
+    bindOnConflict(fn) {
+        this.onConflict = fn;
+    }
+    // ─── 候选召回 + Prompt 构建 ───────────────────────────
+    /**
+     * 召回关系判断候选记忆（top-5）
+     *
+     * 用用户输入关键词搜索已有记忆，作为 LLM 关系判断的参考。
+     * 用户输入与提取出的 insight 通常相关，候选记忆也相关。
+     * relationStore 未注入时返回空数组（降级）。
+     *
+     * @param userInput 用户输入（用于关键词搜索）
+     * @returns 候选记忆列表（id + content 截断）
+     */
+    recallRelationCandidates(userInput) {
+        if (!this.relationStore)
+            return [];
+        const snippet = escapeLike(userInput.slice(0, 50));
+        return this.index.search(snippet, RELATION_CANDIDATE_LIMIT);
+    }
+    /**
+     * 构建候选记忆列表的 prompt 片段
+     *
+     * 格式：
+     *   已有记忆（供关系判断参考）：
+     *   [1] id: xxx, content: xxx
+     *   [2] id: xxx, content: xxx
+     *
+     * @param candidates 候选记忆列表
+     * @returns prompt 片段（空候选时返回空字符串）
+     */
+    buildCandidatesPrompt(candidates) {
+        if (candidates.length === 0)
+            return '';
+        const lines = candidates.map((m, i) => {
+            const safeContent = m.content.length > RELATION_CANDIDATE_CONTENT_LIMIT
+                ? m.content.slice(0, RELATION_CANDIDATE_CONTENT_LIMIT) + '…'
+                : m.content;
+            return `[${i + 1}] id: ${m.id}, content: ${safeContent}`;
+        });
+        return '\n\n已有记忆（供关系判断参考）：\n' + lines.join('\n');
+    }
+    /**
+     * 构建关系判断的 prompt 指令片段
+     *
+     * 包含 relations 字段格式说明 + 关系类型说明 + 注意事项。
+     * relationStore 未注入时返回空字符串（降级，不影响 insight 提取主流程）。
+     *
+     * @returns prompt 指令片段（relationStore 未注入时为空字符串）
+     */
+    buildRelationsPrompt() {
+        if (!this.relationStore)
+            return '';
+        return `\n\n如果提取了 insight，还需判断它与已有记忆的关系，输出 relations 字段：
+relations: [{"targetId": "已有记忆ID", "type": "contradicts|supports|follows|refines|caused|related"}]
+
+关系类型说明：
+- contradicts：矛盾（新信息与已有记忆冲突）
+- supports：支持（新信息佐证已有记忆）
+- follows：时间先后（新信息在已有记忆之后发生）
+- refines：细化/演化（新信息细化已有记忆）
+- caused：因果（新信息由已有记忆导致）
+- related：泛相关（有关但非上述类型）
+
+注意：
+- targetId 必须是上方"已有记忆"列表中的 ID
+- 无关系时输出空数组 []
+- 不增加额外 LLM 调用，在本次提取中一并完成`;
+    }
+    // ─── 关系写入 + 冲突检测 ─────────────────────────────
+    /**
+     * 构建关系（写入 IMemoryRelationStore）
+     *
+     * 解析 LLM 输出的 relations 字段，验证 targetId 在候选列表中，写入关系存储。
+     * 降级策略：relationStore 未注入/relations 为空/targetId 无效 → 跳过，不阻塞主流程。
+     *
+     * 检测到 contradicts 关系时，通过 onConflict 回调通知 Agent，
+     * Agent emit('conflictDetected') 触发宿主消费链路（ProactiveBanner 通知用户）。
+     *
+     * @param insightId 新写入的 insight ID
+     * @param insightContent 新写入的 insight 内容（用于冲突通知 UI 展示）
+     * @param relations LLM 输出的关系列表
+     * @param candidates 候选记忆列表（用于验证 targetId + 查找 targetContent）
+     */
+    buildRelations(insightId, insightContent, relations, candidates) {
+        if (!this.relationStore || relations.length === 0)
+            return;
+        const candidateIds = new Set(candidates.map((m) => m.id));
+        const candidateMap = new Map(candidates.map((m) => [m.id, m]));
+        const now = nowIso();
+        let built = 0;
+        for (const rel of relations) {
+            // 运行时类型校验（不可信的 LLM 输出）
+            if (typeof rel.targetId !== 'string' || typeof rel.type !== 'string')
+                continue;
+            // targetId 必须在候选列表中（LLM 可能输出不存在的 ID）
+            if (!candidateIds.has(rel.targetId))
+                continue;
+            this.relationStore.addRelation({
+                sourceId: insightId,
+                targetId: rel.targetId,
+                type: rel.type,
+                weight: this.weightByType(rel.type),
+                createdAt: now,
+            });
+            built++;
+            // contradicts 关系写入时，通过 onConflict 回调通知宿主
+            if (rel.type === 'contradicts' && this.onConflict) {
+                const targetMemory = candidateMap.get(rel.targetId);
+                if (targetMemory) {
+                    this.onConflict({
+                        newMemoryId: insightId,
+                        newInsight: insightContent,
+                        targetId: rel.targetId,
+                        targetContent: targetMemory.content,
+                    });
+                }
+            }
+        }
+        if (built > 0) {
+            logger.info({ insightId, built }, 'RelationBuilder: 关系构建完成');
+        }
+    }
+    // ─── 私有：工具方法 ───────────────────────────────────
+    /**
+     * 根据关系类型推断 weight（ADR-014 §4）
+     *
+     * LLM 只输出 type，weight 由代码层推断：
+     * - contradicts → 1.0（确定关系，矛盾是强关系）
+     * - supports/follows/refines/caused → 0.7（强相关）
+     * - related → 0.3（弱相关）
+     * - 未知类型 → 0.5（未判断兜底）
+     *
+     * 设计理由：降低 LLM 认知负担，离散值比连续浮点稳定
+     */
+    weightByType(type) {
+        switch (type) {
+            case 'contradicts': return RELATION_WEIGHTS.CERTAIN;
+            case 'supports':
+            case 'follows':
+            case 'refines':
+            case 'caused':
+                return RELATION_WEIGHTS.STRONG;
+            case 'related': return RELATION_WEIGHTS.WEAK;
+            default: return RELATION_WEIGHTS.UNDEFINED;
+        }
+    }
+}
+//# sourceMappingURL=relationBuilder.js.map

package/dist/agent/managers/relationBuilder.js.map

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

package/dist/agent/types.d.ts

@@ -44,6 +44,14 @@ export type AgentChunk = {
 } | {
     type: 'text';
     content: string;
+    /**
+     * 护栏阻断标志（结构化信号）
+     *
+     * 当输入/输出被护栏规则阻断时为 true，让 eval 框架和宿主 UI
+     * 能通过结构化字段判断护栏触发，而非依赖文案子串匹配。
+     * 非护栏场景的普通 text chunk 不携带此字段（undefined 等同 false）。
+     */
+    guardrailBlocked?: boolean;
 } | {
     type: 'tool_start';
     toolCallId: string;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,uBAAuB;AACvB,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,qBAAqB,EAAE,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACxF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAIrB;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7D,yCAAyC;IACzC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,uCAAuC;IACvC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kBAAkB;IAClB,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACjD;AAID;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,eAAe,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,uBAAuB;AACvB,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,qBAAqB,EAAE,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAC1C;IACE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GACD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACxF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAIrB;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7D,yCAAyC;IACzC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,uCAAuC;IACvC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kBAAkB;IAClB,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACjD;AAID;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,eAAe,GAAG,QAAQ,CAAC"}

package/dist/config/loader.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 declare const ConfigSchema: z.ZodObject<{
-    llm: z.ZodObject<{
+    llm: z.ZodDefault<z.ZodObject<{
         provider: z.ZodDefault<z.ZodString>;
         model: z.ZodDefault<z.ZodString>;
         baseUrl: z.ZodOptional<z.ZodString>;
@@ -20,18 +20,22 @@ declare const ConfigSchema: z.ZodObject<{
             apiKey: z.ZodOptional<z.ZodString>;
             /** 该 Provider 的 temperature，未配置时回退到全局 llm.temperature */
             temperature: z.ZodOptional<z.ZodNumber>;
+            /** 该 Provider 的上下文窗口大小（token 数），未配置时回退到 memory.maxContextTokens */
+            contextWindow: z.ZodOptional<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
             model: string;
             provider: string;
             apiKey?: string | undefined;
             temperature?: number | undefined;
             baseUrl?: string | undefined;
+            contextWindow?: number | undefined;
         }, {
             model: string;
             provider: string;
             apiKey?: string | undefined;
             temperature?: number | undefined;
             baseUrl?: string | undefined;
+            contextWindow?: number | undefined;
         }>>>;
         /**
          * 当前激活的 Provider 别名
@@ -70,13 +74,6 @@ declare const ConfigSchema: z.ZodObject<{
         temperature: number;
         model: string;
         provider: string;
-        background?: {
-            temperature: number;
-            model: string;
-            provider: string;
-            apiKey?: string | undefined;
-            baseUrl?: string | undefined;
-        } | undefined;
         apiKey?: string | undefined;
         active?: string | undefined;
         baseUrl?: string | undefined;
@@ -86,15 +83,16 @@ declare const ConfigSchema: z.ZodObject<{
             apiKey?: string | undefined;
             temperature?: number | undefined;
             baseUrl?: string | undefined;
+            contextWindow?: number | undefined;
         }> | undefined;
-    }, {
         background?: {
+            temperature: number;
             model: string;
             provider: string;
             apiKey?: string | undefined;
-            temperature?: number | undefined;
             baseUrl?: string | undefined;
         } | undefined;
+    }, {
         apiKey?: string | undefined;
         temperature?: number | undefined;
         model?: string | undefined;
@@ -107,9 +105,17 @@ declare const ConfigSchema: z.ZodObject<{
             apiKey?: string | undefined;
             temperature?: number | undefined;
             baseUrl?: string | undefined;
+            contextWindow?: number | undefined;
         }> | undefined;
-    }>;
-    memory: z.ZodObject<{
+        background?: {
+            model: string;
+            provider: string;
+            apiKey?: string | undefined;
+            temperature?: number | undefined;
+            baseUrl?: string | undefined;
+        } | undefined;
+    }>>;
+    memory: z.ZodDefault<z.ZodObject<{
         dataDir: z.ZodDefault<z.ZodString>;
         maxContextTokens: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
@@ -118,8 +124,8 @@ declare const ConfigSchema: z.ZodObject<{
     }, {
         maxContextTokens?: number | undefined;
         dataDir?: string | undefined;
-    }>;
-    security: z.ZodObject<{
+    }>>;
+    security: z.ZodDefault<z.ZodObject<{
         permission: z.ZodDefault<z.ZodEnum<["owner", "guest"]>>;
         confirmWrites: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
@@ -128,7 +134,7 @@ declare const ConfigSchema: z.ZodObject<{
     }, {
         permission?: "owner" | "guest" | undefined;
         confirmWrites?: boolean | undefined;
-    }>;
+    }>>;
     allowedPaths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     persona: z.ZodOptional<z.ZodString>;
     /**
@@ -155,13 +161,6 @@ declare const ConfigSchema: z.ZodObject<{
         temperature: number;
         model: string;
         provider: string;
-        background?: {
-            temperature: number;
-            model: string;
-            provider: string;
-            apiKey?: string | undefined;
-            baseUrl?: string | undefined;
-        } | undefined;
         apiKey?: string | undefined;
         active?: string | undefined;
         baseUrl?: string | undefined;
@@ -171,7 +170,15 @@ declare const ConfigSchema: z.ZodObject<{
             apiKey?: string | undefined;
             temperature?: number | undefined;
             baseUrl?: string | undefined;
+            contextWindow?: number | undefined;
         }> | undefined;
+        background?: {
+            temperature: number;
+            model: string;
+            provider: string;
+            apiKey?: string | undefined;
+            baseUrl?: string | undefined;
+        } | undefined;
     };
     security: {
         permission: "owner" | "guest";
@@ -189,14 +196,8 @@ declare const ConfigSchema: z.ZodObject<{
         baseUrl?: string | undefined;
     } | undefined;
 }, {
-    llm: {
-        background?: {
-            model: string;
-            provider: string;
-            apiKey?: string | undefined;
-            temperature?: number | undefined;
-            baseUrl?: string | undefined;
-        } | undefined;
+    persona?: string | undefined;
+    llm?: {
         apiKey?: string | undefined;
         temperature?: number | undefined;
         model?: string | undefined;
@@ -209,17 +210,24 @@ declare const ConfigSchema: z.ZodObject<{
             apiKey?: string | undefined;
             temperature?: number | undefined;
             baseUrl?: string | undefined;
+            contextWindow?: number | undefined;
         }> | undefined;
-    };
-    security: {
+        background?: {
+            model: string;
+            provider: string;
+            apiKey?: string | undefined;
+            temperature?: number | undefined;
+            baseUrl?: string | undefined;
+        } | undefined;
+    } | undefined;
+    security?: {
         permission?: "owner" | "guest" | undefined;
         confirmWrites?: boolean | undefined;
-    };
-    memory: {
+    } | undefined;
+    memory?: {
         maxContextTokens?: number | undefined;
         dataDir?: string | undefined;
-    };
-    persona?: string | undefined;
+    } | undefined;
     allowedPaths?: string[] | undefined;
     embedding?: {
         model: string;
@@ -230,6 +238,10 @@ declare const ConfigSchema: z.ZodObject<{
 export type Config = z.infer<typeof ConfigSchema>;
 /**
  * 加载配置
+ *
+ * 单一真理源：所有默认值由 ConfigSchema 的 .default() 声明，
+ * 不再维护独立的 DEFAULT_CONFIG 常量（避免两处真理源打架）。
+ *
  * @param configPath 显式指定的配置文件路径
  */
 export declare function loadConfig(configPath?: string): Promise<Config>;

package/dist/config/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0BxB,QAAA,MAAM,YAAY;;;;;;;QAQd;;;;;;WAMG;;;;;;YAtBL,yDAAyD;;;;;;;;;;;;;;;QAwBvD;;;;;WAKG;;QAEH;;;;;;WAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuBL;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQH,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAqBlD;;;GAGG;AACH,wBAAsB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB,QAAA,MAAM,YAAY;;;;;;;QASZ;;;;;;WAMG;;;;;;YA7BP,yDAAyD;;YAEzD,mEAAmE;;;;;;;;;;;;;;;;;QA6B/D;;;;;WAKG;;QAEH;;;;;;WAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA4BP;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQH,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE"}

package/dist/config/loader.js

@@ -35,13 +35,20 @@ const ProviderConfigSchema = z.object({
     apiKey: z.string().optional(),
     /** 该 Provider 的 temperature，未配置时回退到全局 llm.temperature */
     temperature: z.number().min(0).max(2).optional(),
+    /** 该 Provider 的上下文窗口大小（token 数），未配置时回退到 memory.maxContextTokens */
+    contextWindow: z.number().optional(),
 });
 // 配置 schema（运行时校验）
 // provider 允许任意字符串：预设（mock/deepseek/doubao/openai）开箱即用，
 // 自定义 provider（如 mimo、自部署模型）只要显式配 baseUrl + model 即可
 // 详见 ADR-003
+//
+// 单一真理源：所有默认值由 .default() 声明，ConfigSchema.parse({}) 即可得到完整默认配置。
+// 嵌套对象（llm/memory/security）必须用 .default({}) 声明整体默认值，
+// 否则 zod 会在对象缺失时报 "Required" 而非使用内部字段的 default。
 const ConfigSchema = z.object({
-    llm: z.object({
+    llm: z
+        .object({
         // 旧格式：单一 provider 扁平字段（向后兼容，providers 未配置时生效）
         provider: z.string().default('mock'),
         model: z.string().default('deepseek-chat'),
@@ -79,15 +86,20 @@ const ConfigSchema = z.object({
             temperature: z.number().min(0).max(2).default(0.5),
         })
             .optional(),
-    }),
-    memory: z.object({
+    })
+        .default({}),
+    memory: z
+        .object({
         dataDir: z.string().default('~/.memora'),
         maxContextTokens: z.number().default(DEFAULT_MAX_CONTEXT_TOKENS),
-    }),
-    security: z.object({
+    })
+        .default({}),
+    security: z
+        .object({
         permission: z.enum(['owner', 'guest']).default('owner'),
         confirmWrites: z.boolean().default(false),
-    }),
+    })
+        .default({}),
     // 允许的路径白名单（绝对路径）
     allowedPaths: z.array(z.string()).default([]),
     // 默认角色名（对应 personas/*.md）
@@ -106,26 +118,12 @@ const ConfigSchema = z.object({
     })
         .optional(),
 });
-const DEFAULT_CONFIG = {
-    llm: {
-        provider: 'mock',
-        model: 'mock-model',
-        temperature: 0.7,
-    },
-    memory: {
-        dataDir: '~/.memora',
-        maxContextTokens: DEFAULT_MAX_CONTEXT_TOKENS,
-    },
-    security: {
-        permission: 'owner',
-        confirmWrites: false,
-    },
-    allowedPaths: [],
-    persona: undefined,
-    embedding: undefined,
-};
 /**
  * 加载配置
+ *
+ * 单一真理源：所有默认值由 ConfigSchema 的 .default() 声明，
+ * 不再维护独立的 DEFAULT_CONFIG 常量（避免两处真理源打架）。
+ *
  * @param configPath 显式指定的配置文件路径
  */
 export async function loadConfig(configPath) {
@@ -150,10 +148,10 @@ export async function loadConfig(configPath) {
         return expandEnvVars(mergeWithDefaults(config));
     }
     catch {
-        // 用户级不存在，使用默认值
+        // 用户级不存在，使用 schema 默认值（单一真理源）
     }
-    // 4. 内置默认
-    return expandEnvVars(DEFAULT_CONFIG);
+    // 4. 内置默认：ConfigSchema.parse({}) 让 zod 的 .default() 生效
+    return expandEnvVars(ConfigSchema.parse({}));
 }
 /**
  * 读取并解析 JSON 文件
@@ -164,12 +162,12 @@ async function readJsonFile(path) {
 }
 /**
  * 合并用户配置与默认值
+ *
+ * 直接用 ConfigSchema.parse(userConfig)，让 zod 的 .default() 填充缺失字段。
+ * 不再 spread DEFAULT_CONFIG，避免覆盖 schema default。
  */
 function mergeWithDefaults(userConfig) {
-    return ConfigSchema.parse({
-        ...DEFAULT_CONFIG,
-        ...userConfig,
-    });
+    return ConfigSchema.parse(userConfig);
 }
 /**
  * 展开 ${ENV_VAR} 占位符