@zooique/memora 0.1.0

package/dist/config/loader.js

@@ -0,0 +1,194 @@
+/**
+ * 配置加载
+ *
+ * 优先级（高 → 低）：
+ * 1. --config 命令行参数
+ * 2. 项目级 .memora/config.json
+ * 3. 用户级 ~/.memora/config.json
+ * 4. 内置默认值
+ *
+ * API Key 从环境变量读取（不写入配置文件）
+ *
+ * 多 Provider 管理（v1.2）：
+ *   - providers：命名 Provider 映射表，key 为别名（如 "deepseek"、"openai"）
+ *   - active：当前激活的 Provider 别名
+ *   - 不配置 providers 时，回退到旧的单 provider 扁平字段（向后兼容）
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { z } from 'zod';
+// 单个 Provider 配置 schema（用于 providers 映射表的值）
+const ProviderConfigSchema = z.object({
+    provider: z.string(),
+    model: z.string(),
+    baseUrl: z.string().optional(),
+    apiKey: z.string().optional(),
+});
+// 配置 schema（运行时校验）
+// provider 允许任意字符串：预设（mock/deepseek/doubao/openai）开箱即用，
+// 自定义 provider（如 mimo、自部署模型）只要显式配 baseUrl + model 即可
+// 详见 ADR-003
+const ConfigSchema = z.object({
+    llm: z.object({
+        // 旧格式：单一 provider 扁平字段（向后兼容，providers 未配置时生效）
+        provider: z.string().default('mock'),
+        model: z.string().default('deepseek-chat'),
+        baseUrl: z.string().optional(),
+        apiKey: z.string().optional(),
+        temperature: z.number().min(0).max(2).default(0.7),
+        /**
+         * 多 Provider 映射表
+         *
+         * key 为 Provider 别名（如 "deepseek"、"openai"），value 为 Provider 配置。
+         * 配置后，旧扁平字段（provider/model/baseUrl/apiKey）被忽略。
+         * 不配置时回退到旧的单 provider 行为——完全向后兼容。
+         */
+        providers: z.record(z.string(), ProviderConfigSchema).optional(),
+        /**
+         * 当前激活的 Provider 别名
+         *
+         * 必须与 providers 中的某个 key 一致。
+         * 不配置时默认使用 providers 的第一个 key。
+         */
+        active: z.string().optional(),
+        /**
+         * 后台通道配置（多 Provider 路由预留）
+         *
+         * 不配时所有消费者复用前台（llm）配置——零破坏性，完全向后兼容。
+         * 配置后，归档/投影/画像等后台操作使用此通道，降低成本。
+         * 详见接入指南 §九
+         */
+        background: z
+            .object({
+            provider: z.string(),
+            model: z.string(),
+            baseUrl: z.string().optional(),
+            apiKey: z.string().optional(),
+            temperature: z.number().min(0).max(2).default(0.5),
+        })
+            .optional(),
+    }),
+    memory: z.object({
+        dataDir: z.string().default('~/.memora'),
+        maxContextTokens: z.number().default(120000),
+    }),
+    security: z.object({
+        permission: z.enum(['owner', 'guest']).default('owner'),
+        confirmWrites: z.boolean().default(false),
+    }),
+    // 允许的路径白名单（绝对路径）
+    allowedPaths: z.array(z.string()).default([]),
+    // 默认角色名（对应 personas/*.md）
+    persona: z.string().optional(),
+    /**
+     * Embedding 配置（可选，配置后启用向量语义召回）
+     *
+     * 复用 OpenAI 兼容协议的 /embeddings 端点。
+     * 不配置时降级为纯关键词召回（当前行为）。
+     */
+    embedding: z
+        .object({
+        model: z.string(),
+        baseUrl: z.string().optional(),
+        apiKey: z.string().optional(),
+    })
+        .optional(),
+});
+const DEFAULT_CONFIG = {
+    llm: {
+        provider: 'mock',
+        model: 'mock-model',
+        temperature: 0.7,
+    },
+    memory: {
+        dataDir: '~/.memora',
+        maxContextTokens: 120000,
+    },
+    security: {
+        permission: 'owner',
+        confirmWrites: false,
+    },
+    allowedPaths: [],
+    persona: undefined,
+    embedding: undefined,
+};
+/**
+ * 加载配置
+ * @param configPath 显式指定的配置文件路径
+ */
+export async function loadConfig(configPath) {
+    // 1. 显式指定
+    if (configPath) {
+        const config = await readJsonFile(configPath);
+        return expandEnvVars(mergeWithDefaults(config));
+    }
+    // 2. 项目级
+    const projectPath = resolve(process.cwd(), '.memora/config.json');
+    try {
+        const config = await readJsonFile(projectPath);
+        return expandEnvVars(mergeWithDefaults(config));
+    }
+    catch {
+        // 项目级不存在，继续尝试用户级
+    }
+    // 3. 用户级
+    const userPath = resolve(homedir(), '.memora/config.json');
+    try {
+        const config = await readJsonFile(userPath);
+        return expandEnvVars(mergeWithDefaults(config));
+    }
+    catch {
+        // 用户级不存在，使用默认值
+    }
+    // 4. 内置默认
+    return expandEnvVars(DEFAULT_CONFIG);
+}
+/**
+ * 读取并解析 JSON 文件
+ */
+async function readJsonFile(path) {
+    const content = await readFile(path, 'utf-8');
+    return JSON.parse(content);
+}
+/**
+ * 合并用户配置与默认值
+ */
+function mergeWithDefaults(userConfig) {
+    return ConfigSchema.parse({
+        ...DEFAULT_CONFIG,
+        ...userConfig,
+    });
+}
+/**
+ * 展开 ${ENV_VAR} 占位符
+ * 配置文件可写 "apiKey": "${MEMORA_LLM_API_KEY}"
+ * 实际读取时展开为环境变量值
+ *
+ * 同时展开 providers 映射表中每个 Provider 的 apiKey/baseUrl
+ */
+function expandEnvVars(config) {
+    const expand = (val) => {
+        if (!val)
+            return val;
+        return val.replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (_, name) => process.env[name] ?? '');
+    };
+    // 展开 providers 映射表中的环境变量
+    const expandedProviders = config
+        .llm.providers
+        ? Object.fromEntries(Object.entries(config.llm.providers).map(([key, p]) => [
+            key,
+            { ...p, apiKey: expand(p.apiKey), baseUrl: expand(p.baseUrl) },
+        ]))
+        : undefined;
+    return {
+        ...config,
+        llm: {
+            ...config.llm,
+            apiKey: expand(config.llm.apiKey),
+            baseUrl: expand(config.llm.baseUrl),
+            providers: expandedProviders,
+        },
+    };
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

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

package/dist/eval/evalTypes.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Agent 行为评估类型定义
+ *
+ * 定义 EvalScenario 类型，用于 Agent 行为回归测试。
+ * 评估验证的是 Agent 的**行为决策**（工具调用、召回来源），
+ * 而非文本质量（文本质量由宿主项目用真实 LLM 评估）。
+ *
+ * 设计约束（详见 docs/agent-harness-增强方案-v1.0.md §3.5）：
+ *   - 仅使用 Mock LLM（MSW），不发起真实 API 调用
+ *   - 评估运行在 CI 中，作为测试套件的一部分
+ *   - 场景定义通用，不耦合任何领域逻辑
+ */
+import type { AgentChunk } from '../agent/types.js';
+/**
+ * 评估场景定义
+ *
+ * 每个场景描述一个输入 + 期望的 Agent 行为，
+ * 验证召回管线、工具调用决策、护栏效果等维度。
+ */
+export interface EvalScenario {
+    /** 场景名称（用于测试报告） */
+    name: string;
+    /** 场景描述 */
+    description: string;
+    /** 用户输入 */
+    input: string;
+    /** 预设的召回记忆（模拟召回结果） */
+    recalledMemories?: Array<{
+        name: string;
+        content: string;
+        source: string;
+    }>;
+    /**
+     * 期望的行为特征
+     *
+     * 至少定义一项。所有检查项都通过才算场景通过。
+     */
+    expect: EvalExpectation;
+}
+/**
+ * 评估期望
+ *
+ * 定义 Agent 应该（或不应该）表现出的行为。
+ * 所有字段都是可选的——只检查有定义的字段。
+ */
+export interface EvalExpectation {
+    /**
+     * 期望的工具调用名列表
+     *
+     * 如果定义，Agent 在对话过程中必须至少调用这些工具。
+     * 例如：['read_file', 'search_memories']
+     */
+    toolsCalled?: string[];
+    /**
+     * 不应调用的工具名列表
+     *
+     * 例如：不应调用 write_file 的只读场景
+     */
+    toolsNotCalled?: string[];
+    /**
+     * 期望的召回 source 分布
+     *
+     * 验证召回管线是否排除了应排除的 source 类型。
+     * 例如：{ 'rule': 0 } 表示不应召回 rule 类型的记忆
+     */
+    recallSources?: Record<string, number>;
+    /**
+     * 护栏阻断检查
+     *
+     * 如果为 true，期望输入被护栏规则阻断
+     */
+    guardrailBlocked?: boolean;
+    /**
+     * 工具调用次数范围
+     */
+    toolCallCount?: {
+        min?: number;
+        max?: number;
+    };
+}
+/**
+ * 评估结果
+ */
+export interface EvalResult {
+    /** 场景名称 */
+    name: string;
+    /** 是否通过 */
+    passed: boolean;
+    /** 收集到的 Agent 行为数据 */
+    collected: {
+        toolsCalled: string[];
+        recallCount: number;
+        guardrailBlocked: boolean;
+        done: boolean;
+    };
+    /** 失败原因（如果未通过） */
+    failures: string[];
+}
+/**
+ * 从 AgentChunk 流中收集行为数据
+ *
+ * 消费 AgentLoop 的 AsyncGenerator 输出，
+ * 提取工具调用名、召回数量、护栏状态等关键信息。
+ *
+ * @param chunks AgentChunk 异步迭代器
+ * @returns 收集到的行为数据
+ */
+export declare function collectAgentChunks(chunks: AsyncGenerator<AgentChunk, void, unknown>): Promise<EvalResult['collected']>;
+/**
+ * 将收集到的行为数据与期望进行比对
+ *
+ * @param name 场景名称
+ * @param collected 收集到的行为数据
+ * @param expect 期望的行为特征
+ * @returns 评估结果
+ */
+export declare function evaluateResult(name: string, collected: EvalResult['collected'], expect: EvalExpectation): EvalResult;
+//# sourceMappingURL=evalTypes.d.ts.map

package/dist/eval/evalTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evalTypes.d.ts","sourceRoot":"","sources":["../../src/eval/evalTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,gBAAgB,CAAC,EAAE,KAAK,CAAC;QACvB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IACH;;;;OAIG;IACH,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEvC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,aAAa,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,sBAAsB;IACtB,SAAS,EAAE;QACT,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,IAAI,EAAE,OAAO,CAAC;KACf,CAAC;IACF,kBAAkB;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,GAChD,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAgClC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,UAAU,CAAC,WAAW,CAAC,EAClC,MAAM,EAAE,eAAe,GACtB,UAAU,CA+CZ"}

package/dist/eval/evalTypes.js

@@ -0,0 +1,102 @@
+/**
+ * Agent 行为评估类型定义
+ *
+ * 定义 EvalScenario 类型，用于 Agent 行为回归测试。
+ * 评估验证的是 Agent 的**行为决策**（工具调用、召回来源），
+ * 而非文本质量（文本质量由宿主项目用真实 LLM 评估）。
+ *
+ * 设计约束（详见 docs/agent-harness-增强方案-v1.0.md §3.5）：
+ *   - 仅使用 Mock LLM（MSW），不发起真实 API 调用
+ *   - 评估运行在 CI 中，作为测试套件的一部分
+ *   - 场景定义通用，不耦合任何领域逻辑
+ */
+/**
+ * 从 AgentChunk 流中收集行为数据
+ *
+ * 消费 AgentLoop 的 AsyncGenerator 输出，
+ * 提取工具调用名、召回数量、护栏状态等关键信息。
+ *
+ * @param chunks AgentChunk 异步迭代器
+ * @returns 收集到的行为数据
+ */
+export async function collectAgentChunks(chunks) {
+    const collected = {
+        toolsCalled: [],
+        recallCount: 0,
+        guardrailBlocked: false,
+        done: false,
+    };
+    for await (const chunk of chunks) {
+        switch (chunk.type) {
+            case 'recall':
+                // MS-12：recall chunk 改为携带 memories 数组，count 由数组长度得出
+                collected.recallCount = chunk.memories.length;
+                break;
+            case 'tool_start':
+                if (!collected.toolsCalled.includes(chunk.name)) {
+                    collected.toolsCalled.push(chunk.name);
+                }
+                break;
+            case 'text':
+                // 检查护栏阻断/警告消息
+                if (chunk.content.includes('输入被护栏规则') || chunk.content.includes('输出被护栏规则')) {
+                    collected.guardrailBlocked = true;
+                }
+                break;
+            case 'done':
+                collected.done = true;
+                break;
+        }
+    }
+    return collected;
+}
+/**
+ * 将收集到的行为数据与期望进行比对
+ *
+ * @param name 场景名称
+ * @param collected 收集到的行为数据
+ * @param expect 期望的行为特征
+ * @returns 评估结果
+ */
+export function evaluateResult(name, collected, expect) {
+    const failures = [];
+    // 检查工具调用
+    if (expect.toolsCalled) {
+        for (const tool of expect.toolsCalled) {
+            if (!collected.toolsCalled.includes(tool)) {
+                failures.push(`期望调用工具 "${tool}"，但未调用（已调用：${collected.toolsCalled.join(', ') || '无'}）`);
+            }
+        }
+    }
+    // 检查不应调用的工具
+    if (expect.toolsNotCalled) {
+        for (const tool of expect.toolsNotCalled) {
+            if (collected.toolsCalled.includes(tool)) {
+                failures.push(`不应调用工具 "${tool}"，但实际调用了`);
+            }
+        }
+    }
+    // 检查工具调用次数
+    if (expect.toolCallCount) {
+        const count = collected.toolsCalled.length;
+        if (expect.toolCallCount.min !== undefined && count < expect.toolCallCount.min) {
+            failures.push(`工具调用次数 ${count} < 期望最小值 ${expect.toolCallCount.min}`);
+        }
+        if (expect.toolCallCount.max !== undefined && count > expect.toolCallCount.max) {
+            failures.push(`工具调用次数 ${count} > 期望最大值 ${expect.toolCallCount.max}`);
+        }
+    }
+    // 检查护栏阻断
+    if (expect.guardrailBlocked !== undefined) {
+        if (expect.guardrailBlocked !== collected.guardrailBlocked) {
+            failures.push(`期望护栏阻断=${expect.guardrailBlocked}，实际=${collected.guardrailBlocked}`);
+        }
+    }
+    return {
+        name,
+        passed: failures.length === 0,
+        collected,
+        failures,
+    };
+}
+//# sourceMappingURL=evalTypes.js.map

package/dist/eval/evalTypes.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Memora — 通用 Agent 架构（纯逻辑库）
+ *
+ * 零 native 依赖。宿主项目通过注入 IMemoryStorage 实现持久化。
+ * CLI 由宿主项目提供（hosts/memora-sprite/）。
+ *
+ * 设计哲学：万物皆记忆（详见 architecture_philosophy_rules.md §1）
+ * 决策追溯：详见 .trae/rules/decisions/ 下的 ADR
+ */
+export { Agent } from './agent/agent.js';
+export type { AgentChunk, ThinkingPhase, UIMessages } from './agent/types.js';
+export { AGENT_CONSTANTS, LOOP_CONSTANTS } from './agent/constants.js';
+export type { AgentOptions, AgentContext, AgentProjectEntry, } from './agent/agent.js';
+export { type AgentForkResult } from './agent/managers/sessionManager.js';
+export type { ToolDefinition, ToolHandler, ToolContext, WriteExtensions } from './agent/toolExecutor.js';
+export type { PersonaMode, Persona } from './persona/types.js';
+export type { MemoryKeywords } from './agent/managers/insightExtractor.js';
+export type { MemorySnapshot, WorkingMemorySnapshot, BootstrapSnapshot, ArchiveSnapshot, AgentSearchHit, AgentStats, SuggestOptions, SuggestHit, SourceHealthStatus, SourceHealthEntry, SourceHealthReport, } from './agent/managers/memoryInspector.js';
+export type { ConfigSuggestion, ConfigSuggestionHandler } from './agent/managers/configManager.js';
+export type { AutoConfigRefinerOptions } from './agent/managers/autoConfigRefiner.js';
+export type { WorkProjectionEntry } from './agent/managers/workProjection.js';
+export { loadConfig } from './config/loader.js';
+export { createLlmProvider, createProviderFromConfig } from './llm/factory.js';
+export type { ProviderConfig } from './llm/factory.js';
+export type { LlmProvider, ChatOptions } from './llm/provider.js';
+export type { LlmChunk } from './llm/types.js';
+export type { Config } from './config/loader.js';
+export { TypedEventEmitter } from './utils/eventEmitter.js';
+export type { AgentEventMap, AgentEventName, AgentEventHandler } from './utils/eventEmitter.js';
+export type { ITracer, ISpan, AgentMetrics } from './agent/tracer.js';
+export { NOOP_TRACER, TRACE_SPANS } from './agent/tracer.js';
+export { SOURCE_LABELS, inferSource, escapeLike, validateSource } from './memory/types.js';
+export type { Memory, SourceValidationSeverity } from './memory/types.js';
+export { RELATION_TYPES, RELATION_WEIGHTS } from './memory/types.js';
+export type { MemoryRelation, RelationDirection } from './memory/types.js';
+export type { IMemoryStorage } from './memory/storageInterface.js';
+export { InMemoryStorage } from './memory/inMemoryStorage.js';
+export type { IMemoryRelationStore } from './memory/relationStore.js';
+export { InMemoryRelationStore } from './memory/inMemoryRelationStore.js';
+export type { UserProfileEntry, ProfileCategory, ExtractedFact } from './memory/userProfile.js';
+export { VectorStore } from './memory/vectorStore.js';
+export type { EmbeddingService } from './memory/vectorStore.js';
+export { EmbeddingProvider } from './llm/embedding.js';
+export type { EmbeddingConfig, EmbeddingResult } from './llm/embedding.js';
+export type { ISessionStore, SessionMessage } from './memory/sessionStore.js';
+export type { ForkResult } from './agent/messageHistory.js';
+export { recall, extractKeywords } from './memory/recall.js';
+export type { RecallOptions } from './memory/recall.js';
+export type { ILogger } from './logging/loggerInterface.js';
+export { setLogger, logger } from './logging/logger.js';
+export { segmentText, tokenizeKeywords } from './utils/segmenter.js';
+export { parseFrontmatter, serializeFrontmatter } from './utils/frontmatter.js';
+export { safeSetTimeout, safeSetInterval, clearSafeTimeout, clearSafeInterval } from './utils/safeTimer.js';
+export type { SkillEntry, SkillMatch } from './skill/types.js';
+export type { AuditEvent, AuditListener, Permission, WriteDecision, WriteConfirmationInfo, WriteConfirmationRequest, } from './security/pathGuard.js';
+export { MemoraError, ToolErrorCode, isRetryableErrorCode } from './utils/errors.js';
+export { toError } from './utils/toError.js';
+export type { ToolErrorCodeValue } from './utils/errors.js';
+export type { EvalScenario, EvalExpectation, EvalResult } from './eval/evalTypes.js';
+export { collectAgentChunks, evaluateResult } from './eval/evalTypes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,44 @@
+/**
+ * Memora — 通用 Agent 架构（纯逻辑库）
+ *
+ * 零 native 依赖。宿主项目通过注入 IMemoryStorage 实现持久化。
+ * CLI 由宿主项目提供（hosts/memora-sprite/）。
+ *
+ * 设计哲学：万物皆记忆（详见 architecture_philosophy_rules.md §1）
+ * 决策追溯：详见 .trae/rules/decisions/ 下的 ADR
+ */
+// ─── 库导出：供宿主项目 import 接入 ──────────────────────
+export { Agent } from './agent/agent.js';
+export { AGENT_CONSTANTS, LOOP_CONSTANTS } from './agent/constants.js';
+export { loadConfig } from './config/loader.js';
+export { createLlmProvider, createProviderFromConfig } from './llm/factory.js';
+// 事件系统
+export { TypedEventEmitter } from './utils/eventEmitter.js';
+export { NOOP_TRACER, TRACE_SPANS } from './agent/tracer.js';
+// ─── 记忆层导出 ──────────────────────────────────────────
+export { SOURCE_LABELS, inferSource, escapeLike, validateSource } from './memory/types.js';
+// 记忆关系图谱（ADR-014 侧车模型）
+export { RELATION_TYPES, RELATION_WEIGHTS } from './memory/types.js';
+export { InMemoryStorage } from './memory/inMemoryStorage.js';
+export { InMemoryRelationStore } from './memory/inMemoryRelationStore.js';
+// 向量存储：宿主注入 EmbeddingService 后创建 VectorStore，传入 AgentOptions 启用语义搜索
+export { VectorStore } from './memory/vectorStore.js';
+// Embedding Provider：OpenAI 兼容 /embeddings 端点实现（满足 EmbeddingService 接口）
+export { EmbeddingProvider } from './llm/embedding.js';
+// 召回函数：简化关键词搜索
+export { recall, extractKeywords } from './memory/recall.js';
+export { setLogger, logger } from './logging/logger.js';
+// ─── 工具导出 ────────────────────────────────────────────
+// 分词工具：宿主项目（如 SqliteStorage）依赖
+// 工具导出
+export { segmentText, tokenizeKeywords } from './utils/segmenter.js';
+// Frontmatter 解析/序列化：宿主项目（如 skillInstaller）依赖
+export { parseFrontmatter, serializeFrontmatter } from './utils/frontmatter.js';
+// 安全定时器：宿主主进程统一使用 safeSetTimeout/safeSetInterval 跟踪清理
+export { safeSetTimeout, safeSetInterval, clearSafeTimeout, clearSafeInterval } from './utils/safeTimer.js';
+// ─── 错误类型导出 ────────────────────────────────────────
+export { MemoraError, ToolErrorCode, isRetryableErrorCode } from './utils/errors.js';
+// toError 独立导出，浏览器端可直接 import 而不引入 logging（pino）依赖
+export { toError } from './utils/toError.js';
+export { collectAgentChunks, evaluateResult } from './eval/evalTypes.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iDAAiD;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA4BvE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAK/E,OAAO;AACP,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAK5D,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE7D,uDAAuD;AACvD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE3F,uBAAuB;AACvB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAIrE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAG1E,oEAAoE;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,wEAAwE;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAMvD,eAAe;AACf,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAK7D,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAExD,wDAAwD;AACxD,+BAA+B;AAC/B,OAAO;AACP,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACrE,8CAA8C;AAC9C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAChF,sDAAsD;AACtD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAc5G,sDAAsD;AACtD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACrF,mDAAmD;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAK7C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/llm/embedding.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Embedding 配置（与 OpenAICompatibleConfig 共用 baseUrl/apiKey）
+ */
+export interface EmbeddingConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+}
+/**
+ * 单条 embedding 结果
+ */
+export interface EmbeddingResult {
+    /** 原始文本 */
+    text: string;
+    /** 向量（浮点数组，维度由模型决定） */
+    vector: number[];
+}
+/**
+ * Embedding Provider
+ *
+ * 调用 /embeddings 端点将文本转为向量
+ * 支持批量嵌入和本地缓存
+ */
+export declare class EmbeddingProvider {
+    private readonly config;
+    /** 缓存最大条目数（LRU 上限，防止无界增长导致内存泄漏） */
+    private static readonly CACHE_MAX_SIZE;
+    /** 本地缓存：text → vector（LRU，Map 迭代顺序 = 最近访问顺序） */
+    private readonly cache;
+    constructor(config: EmbeddingConfig);
+    /**
+     * LRU 读取：命中时把条目移到末尾，标记为最近访问
+     * Map 保持插入顺序，末尾即最近访问，首部即最久未访问（淘汰候选）
+     */
+    private getCached;
+    /**
+     * LRU 写入：超过容量时淘汰最旧条目（首部）
+     */
+    private setCache;
+    /**
+     * 嵌入单条文本
+     * @param text 待嵌入的文本
+     * @returns 向量
+     */
+    embed(text: string): Promise<number[]>;
+    /**
+     * 批量嵌入多条文本
+     * OpenAI 兼容 API 支持一次请求嵌入多条文本，减少 API 调用
+     * @param texts 待嵌入的文本数组
+     * @returns 嵌入结果数组（顺序与输入一致）
+     */
+    batchEmbed(texts: string[]): Promise<EmbeddingResult[]>;
+    /**
+     * 获取缓存大小（调试用）
+     */
+    get cacheSize(): number;
+    /**
+     * 清空缓存
+     */
+    clearCache(): void;
+}
+//# sourceMappingURL=embedding.d.ts.map

package/dist/llm/embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/llm/embedding.ts"],"names":[],"mappings":"AAkBA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAOhB,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,mCAAmC;IACnC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAQ;IAE9C,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;gBAExB,MAAM,EAAE,eAAe;IAEpD;;;OAGG;IACH,OAAO,CAAC,SAAS;IASjB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAQhB;;;;OAIG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAW5C;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAkF7D;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB"}