@zooique/memora 0.1.0

package/dist/llm/openaiCompatible.js

@@ -0,0 +1,340 @@
+/**
+ * OpenAI Chat Completions 兼容实现
+ *
+ * 适用于：DeepSeek / 豆包 / 通义 / Ollama / 任何兼容 OpenAI 协议的 API
+ * 详见 ADR-003
+ */
+import { LlmProvider } from '../llm/provider.js';
+import { llmError, networkError, configError, toError } from '../utils/errors.js';
+import { logger } from '../logging/logger.js';
+/**
+ * 通用 OpenAI 兼容 Provider
+ * 通过 baseUrl 适配不同厂商
+ */
+export class OpenAICompatibleProvider extends LlmProvider {
+    config;
+    name;
+    constructor(name, config) {
+        super();
+        this.config = config;
+        this.name = name;
+    }
+    /** 默认请求超时：120 秒 */
+    static DEFAULT_TIMEOUT_MS = 120_000;
+    async *chat(messages, opts = {}) {
+        const url = `${this.config.baseUrl}/chat/completions`;
+        const model = opts.model ?? this.config.defaultModel;
+        // 请求超时控制：默认 120s，可通过 opts.timeoutMs 覆盖
+        const timeoutMs = opts.timeoutMs ?? OpenAICompatibleProvider.DEFAULT_TIMEOUT_MS;
+        const body = {
+            model,
+            messages: this.formatMessages(messages),
+            temperature: opts.temperature ?? 0.7,
+            stream: true,
+        };
+        if (opts.tools)
+            body['tools'] = opts.tools;
+        if (opts.maxTokens)
+            body['max_tokens'] = opts.maxTokens;
+        // 校验 API Key（M-103：缺失时给友好提示，不暴露 undefined 报错）
+        if (!this.config.apiKey) {
+            throw configError('API Key 未配置', `provider: ${this.name}，baseUrl: ${this.config.baseUrl}`, [
+                '检查 ~/.memora/config.json 的 llm.apiKey 字段',
+                '确认已设置环境变量 MEMORA_LLM_API_KEY',
+                '查看文档：config.example.md',
+            ]);
+        }
+        // 合并 AbortSignal：外部取消信号 + 超时信号
+        // 确保用户取消和请求超时都能中断 fetch 和流读取
+        const abortController = new AbortController();
+        const timeoutId = setTimeout(() => abortController.abort(new DOMException('LLM 请求超时', 'TimeoutError')), timeoutMs);
+        const { signal: optsSignal } = opts;
+        const onOptsAbort = () => abortController.abort(optsSignal?.reason);
+        if (optsSignal) {
+            if (optsSignal.aborted) {
+                abortController.abort(optsSignal.reason);
+            }
+            else {
+                optsSignal.addEventListener('abort', onOptsAbort, { once: true });
+            }
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: abortController.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (optsSignal)
+                optsSignal.removeEventListener('abort', onOptsAbort);
+            const e = toError(err);
+            // 区分超时错误和网络错误
+            if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+                throw networkError('LLM 请求超时', `${this.config.baseUrl} 请求超过 ${timeoutMs / 1000}s 未响应`, [
+                    '检查网络连接稳定性',
+                    '如频繁超时，考虑切换 provider 或在 config.json 调整 timeoutMs',
+                    '稍后重试',
+                ], e);
+            }
+            throw networkError('LLM 服务连接失败', `无法访问 ${this.config.baseUrl}：${e.message}`, [
+                '检查网络连接（是否能访问 baseUrl）',
+                '确认 baseUrl 配置正确',
+                '如使用 VPN/代理，检查代理设置',
+            ], e);
+        }
+        // fetch 成功后保留 optsSignal 监听：用户在 SSE 流式阶段取消时，
+        // 仍需通过 onOptsAbort 触发 abortController.abort() 中断 reader.read()。
+        // 注意：{ once: true } 仅在 optsSignal 自身 abort 时移除监听器；
+        // 正常完成或异常路径必须显式 removeEventListener，否则监听器常驻泄漏。
+        // 下方外层 try-finally 统一清理 timeoutId 与 optsSignal 监听器，覆盖所有抛错路径。
+        try {
+            if (!response.ok) {
+                await this.handleResponseError(response);
+            }
+            if (!response.body) {
+                throw llmError('LLM API 返回空 body', `${this.config.baseUrl} 返回了 200 但无 body`, [
+                    '重试一次',
+                    '如持续出现，联系厂商',
+                ]);
+            }
+            try {
+                // 将 abortController.signal 传入 SSE 解析器，使超时/取消能中断流读取
+                yield* this.parseSseStream(response.body, abortController.signal);
+            }
+            catch (err) {
+                // SSE 解析异常时也要 cancel stream（Node 24 + undici 同上）
+                try {
+                    await response.body?.cancel();
+                }
+                catch (err) {
+                    logger.debug({ err: toError(err).message }, 'response.body.cancel 失败');
+                }
+                throw err;
+            }
+        }
+        finally {
+            // 统一清理：覆盖 HTTP 错误、空 body、SSE 异常、正常完成所有路径
+            // 修复 LLM-01：原实现仅在 fetch 网络异常 catch 移除监听器，
+            // handleResponseError/空body/SSE 抛错路径均泄漏监听器与定时器
+            clearTimeout(timeoutId);
+            if (optsSignal)
+                optsSignal.removeEventListener('abort', onOptsAbort);
+        }
+    }
+    /**
+     * 处理 HTTP 错误响应
+     *
+     * 消费并释放 body，根据状态码抛出相应的错误类型。
+     */
+    async handleResponseError(response) {
+        const errorText = await response.text().catch(() => '<无法读取响应体>');
+        try {
+            await response.body?.cancel();
+        }
+        catch (err) {
+            logger.debug({ err: toError(err).message }, 'response.body.cancel 失败');
+        }
+        const status = response.status;
+        if (status === 401 || status === 403) {
+            throw configError('LLM API Key 无效', `HTTP ${status}：${errorText.slice(0, 200)}`, [
+                '检查 API Key 是否正确（注意 ${MEMORA_LLM_API_KEY} 占位符是否已展开）',
+                '确认 Key 未过期',
+                '如使用 DeepSeek/豆包，确认 Key 来自对应平台',
+            ]);
+        }
+        if (status === 429) {
+            throw llmError('LLM 服务限流', `HTTP 429：${errorText.slice(0, 200)}`, [
+                '稍后重试',
+                '如频繁触发考虑升级套餐或换用其他 provider',
+            ]);
+        }
+        if (status >= 400 && status < 500) {
+            throw llmError('LLM 请求格式错误', `HTTP ${status}：${errorText.slice(0, 200)}`, [
+                '检查消息内容是否含特殊字符',
+                '确认 model 名称正确',
+                '如使用 tools，确认 tool schema 有效',
+            ]);
+        }
+        throw llmError('LLM 服务端错误', `HTTP ${status}：${errorText.slice(0, 200)}`, [
+            '稍后重试',
+            '如持续失败，访问厂商状态页确认服务状态',
+            '可在 config.json 切换 provider 兜底',
+        ]);
+    }
+    /**
+     * 格式化消息为 OpenAI 协议格式
+     *
+     * 关键兼容性处理：
+     *   - assistant 消息带 tool_calls 时，若 content 为空字符串，转为 null
+     *     （部分 LLM provider 对空字符串 content 处理异常，导致请求挂起或报错）
+     *   - tool 消息必须包含 tool_call_id 关联对应的工具调用
+     */
+    formatMessages(messages) {
+        return messages.map((m) => {
+            if (m.role === 'tool') {
+                return { role: 'tool', tool_call_id: m.toolCallId, content: m.content };
+            }
+            if (m.role === 'assistant' && m.toolCalls) {
+                return {
+                    role: 'assistant',
+                    // OpenAI 协议：有 tool_calls 时 content 应为 null（而非空字符串），
+                    // 空字符串会导致部分 provider 请求异常或无响应
+                    content: m.content && m.content.length > 0 ? m.content : null,
+                    tool_calls: m.toolCalls,
+                };
+            }
+            return { role: m.role, content: m.content };
+        });
+    }
+    /**
+     * 解析 SSE 流
+     * OpenAI 协议：data: {...}\n\n
+     *
+     * 支持解析 tool_calls delta（流式工具调用）：
+     * OpenAI 协议中 tool_calls 以 delta 形式分片传输，
+     * 需要跨 chunk 累积 function.name 和 function.arguments，
+     * 在 finish_reason='tool_calls' 或流结束时输出完整的 toolCalls。
+     *
+     * @param body - SSE 响应流
+     * @param signal - 中止信号（超时/用户取消），中断 reader.read() 等待
+     */
+    async *parseSseStream(body, signal) {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        // 流式 tool_calls 累积器：按 index 分片累积 name + arguments
+        // OpenAI 协议：同一个 tool_call 的 name/arguments 可能跨多个 delta 分片到达
+        const toolCallAccumulators = new Map();
+        // 修复 P1-C：chunk 级读超时
+        // 原实现 reader.read() 阻塞时无超时，连接半挂（NAT/代理/服务端慢响应不关 TCP）会永久等待
+        // abort signal 也只能在新 chunk 到达后检查，无法中断正在 await 的 read()
+        // 改用 setTimeout + reader.cancel：超时则 cancel reader 让 read() reject 退出
+        const CHUNK_READ_TIMEOUT_MS = 30_000;
+        try {
+            while (true) {
+                // 检查中止信号：超时或用户取消时立即退出
+                if (signal?.aborted) {
+                    throw new DOMException('LLM 流读取被中止', signal.reason?.name ?? 'AbortError');
+                }
+                // chunk 级读超时：超时则 cancel reader，让正在 await 的 read() 立即 reject
+                // reader.cancel() 会让 pending 的 reader.read() 抛 AbortError（DOMException）
+                const chunkTimer = setTimeout(() => {
+                    // cancel 失败也不影响（reader 可能已 done 或被其他路径 cancel）
+                    reader.cancel(new DOMException('LLM chunk 读取超时', 'TimeoutError')).catch(() => { });
+                }, CHUNK_READ_TIMEOUT_MS);
+                let readResult;
+                try {
+                    readResult = await reader.read();
+                }
+                finally {
+                    // read 完成（无论成功/失败）都清理 chunk timer，避免泄漏
+                    clearTimeout(chunkTimer);
+                }
+                const { done, value } = readResult;
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed.startsWith('data:'))
+                        continue;
+                    const data = trimmed.slice(5).trim();
+                    if (data === '[DONE]') {
+                        // 流结束：输出累积的 tool_calls（如果有）
+                        if (toolCallAccumulators.size > 0) {
+                            yield this.buildToolCallsChunk(toolCallAccumulators);
+                        }
+                        return;
+                    }
+                    try {
+                        const json = JSON.parse(data);
+                        const choice = json.choices?.[0];
+                        if (!choice)
+                            continue;
+                        const chunk = {};
+                        // delta.content 可能为 null（tool_calls 场景），!= null 排除 null/undefined
+                        // 空字符串在流式中极少出现，但不影响语义，保持原有 truthy 检查即可
+                        if (choice.delta?.content)
+                            chunk.content = choice.delta.content;
+                        // 累积 tool_calls delta
+                        if (choice.delta?.tool_calls) {
+                            for (const tc of choice.delta.tool_calls) {
+                                const idx = tc.index ?? 0;
+                                const acc = toolCallAccumulators.get(idx) ?? { id: '', name: '', arguments: '' };
+                                if (tc.id)
+                                    acc.id = tc.id;
+                                if (tc.function?.name)
+                                    acc.name += tc.function.name;
+                                if (tc.function?.arguments)
+                                    acc.arguments += tc.function.arguments;
+                                toolCallAccumulators.set(idx, acc);
+                            }
+                        }
+                        // finish_reason='tool_calls' 时输出完整的 toolCalls
+                        if (choice.finish_reason === 'tool_calls') {
+                            chunk.toolCalls = this.buildToolCallsFromAccumulators(toolCallAccumulators);
+                            toolCallAccumulators.clear();
+                        }
+                        else if (choice.finish_reason && toolCallAccumulators.size > 0) {
+                            // finish_reason 为 stop/length 等非 tool_calls 值时，清空累积器防止污染下一次调用
+                            // （某些模型可能在 stop 时残留不完整的 tool_calls 碎片）
+                            toolCallAccumulators.clear();
+                        }
+                        if (choice.finish_reason) {
+                            chunk.finishReason = choice.finish_reason;
+                        }
+                        yield chunk;
+                    }
+                    catch (err) {
+                        logger.debug({ line: line.slice(0, 80), err: toError(err).message }, 'SSE 行解析失败');
+                    }
+                }
+            }
+        }
+        finally {
+            // 修复 P1-C：releaseLock 不会取消流，只是释放锁让其他 reader 能 getReader()
+            // 改用 reader.cancel() 彻底释放底层 TCP 连接，避免 generator 提前 break 时
+            // 底层连接悬挂（CallLlmWithRetry 无 finally 触发 abort 时的兜底）
+            // 已 done/cancel 的 reader 调 cancel 是 no-op，安全
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // cancel 失败不阻塞，reader 会被 GC 回收
+            }
+        }
+    }
+    /**
+     * 从累积器构建完整的 toolCalls 数组（用于 finish_reason='tool_calls' 场景）
+     */
+    buildToolCallsFromAccumulators(accs) {
+        const calls = [];
+        for (const [idx, acc] of accs) {
+            calls.push({
+                id: acc.id || `call_${idx}`,
+                type: 'function',
+                function: { name: acc.name, arguments: acc.arguments },
+            });
+        }
+        return calls;
+    }
+    /**
+     * 从累积器构建 LlmChunk（用于流结束时的兜底输出）
+     */
+    buildToolCallsChunk(accs) {
+        return {
+            toolCalls: this.buildToolCallsFromAccumulators(accs),
+            finishReason: 'tool_calls',
+        };
+    }
+}
+//# sourceMappingURL=openaiCompatible.js.map

package/dist/llm/openaiCompatible.js.map

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

package/dist/llm/provider.d.ts

@@ -0,0 +1,91 @@
+/**
+ * LLM Provider 抽象接口
+ * 所有 LLM 实现（DeepSeek / 豆包 / OpenAI / Mock）必须实现此接口
+ * 详见 ADR-003
+ */
+import type { LlmChunk } from '../llm/types.js';
+export interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    toolCallId?: string;
+}
+export interface ChatOptions {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    tools?: Array<{
+        type: 'function';
+        function: {
+            name: string;
+            description: string;
+            parameters: Record<string, unknown>;
+        };
+    }>;
+    /**
+     * 结构化输出约束（OpenAI response_format 兼容协议）
+     *
+     * 当 Provider 支持 structured output 且工具定义标记 strict 时，
+     * AgentLoop 自动生成 json_schema 约束，强制 LLM 输出合法 tool_call。
+     * 不支持的 Provider 静默跳过，fallback 到纯文本 tool_call 模式。
+     */
+    response_format?: {
+        type: 'json_schema';
+        json_schema: {
+            name: string;
+            strict: boolean;
+            schema: Record<string, unknown>;
+        };
+    };
+    stream?: boolean;
+    /**
+     * LLM 通道选择（多 Provider 路由预留）
+     *
+     * - 'chat'：前台通道，用于用户对话（高质量、低延迟）
+     * - 'background'：后台通道，用于归档/投影/画像（中等质量、低成本）
+     *
+     * 不指定时使用默认 chat 通道。
+     * 多 Provider 路由功能处于设计阶段，当前所有消费者共用同一 Provider。
+     * 详见接入指南 §九
+     */
+    channel?: 'chat' | 'background';
+    /**
+     * 中止信号：用于取消正在进行的 LLM 请求
+     *
+     * AgentLoop 在用户取消对话时传入 AbortSignal，
+     * Provider 应将 signal 传给底层 fetch/stream 读取，确保请求可被中断。
+     */
+    signal?: AbortSignal;
+    /**
+     * 请求超时（毫秒）。默认 120 秒。
+     * 超时后抛出 networkError，由 callLlmWithRetry 决定是否重试。
+     */
+    timeoutMs?: number;
+}
+/**
+ * LLM Provider 抽象类
+ * 实现类需实现 chat() 流式方法
+ */
+export declare abstract class LlmProvider {
+    abstract readonly name: string;
+    /**
+     * 是否支持结构化输出（response_format json_schema）
+     *
+     * 默认 false，子类可覆盖。AgentLoop 在构建工具调用时检查此标记，
+     * 不支持时自动降级为纯文本 tool_call 模式。
+     */
+    readonly supportsStructuredOutput: boolean;
+    /**
+     * 流式对话
+     * 返回 AsyncIterable，每项是一个增量块
+     */
+    abstract chat(messages: Message[], opts?: ChatOptions): AsyncIterable<LlmChunk>;
+}
+//# sourceMappingURL=provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAEhB,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,UAAU,CAAC;QACjB,QAAQ,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAC/C,CAAC,CAAC;IAEH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,UAAU,CAAC;QACjB,QAAQ,EAAE;YACR,IAAI,EAAE,MAAM,CAAC;YACb,WAAW,EAAE,MAAM,CAAC;YACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACrC,CAAC;KACH,CAAC,CAAC;IACH;;;;;;OAMG;IACH,eAAe,CAAC,EAAE;QAChB,IAAI,EAAE,aAAa,CAAC;QACpB,WAAW,EAAE;YACX,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,OAAO,CAAC;YAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACjC,CAAC;KACH,CAAC;IAEF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAChC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,8BAAsB,WAAW;IAC/B,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE/B;;;;;OAKG;IACH,QAAQ,CAAC,wBAAwB,EAAE,OAAO,CAAS;IAEnD;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;CAChF"}

package/dist/llm/provider.js

@@ -0,0 +1,14 @@
+/**
+ * LLM Provider 抽象类
+ * 实现类需实现 chat() 流式方法
+ */
+export class LlmProvider {
+    /**
+     * 是否支持结构化输出（response_format json_schema）
+     *
+     * 默认 false，子类可覆盖。AgentLoop 在构建工具调用时检查此标记，
+     * 不支持时自动降级为纯文本 tool_call 模式。
+     */
+    supportsStructuredOutput = false;
+}
+//# sourceMappingURL=provider.js.map

package/dist/llm/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AA2EA;;;GAGG;AACH,MAAM,OAAgB,WAAW;IAG/B;;;;;OAKG;IACM,wBAAwB,GAAY,KAAK,CAAC;CAOpD"}

package/dist/llm/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * LLM 适配层类型定义
+ *
+ * 详见 ADR-003 · LLM 适配层使用 OpenAI Chat Completions 兼容协议
+ */
+/**
+ * 工具调用描述
+ */
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * LLM 响应块
+ */
+export interface LlmChunk {
+    content?: string;
+    toolCalls?: ToolCall[];
+    finishReason?: 'stop' | 'tool_calls' | 'length' | 'error';
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;CAC3D"}

package/dist/llm/types.js

@@ -0,0 +1,7 @@
+/**
+ * LLM 适配层类型定义
+ *
+ * 详见 ADR-003 · LLM 适配层使用 OpenAI Chat Completions 兼容协议
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/llm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/logging/logger.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 结构化日志 — 全局单例 + 可替换 ILogger
+ *
+ * 内核零第三方依赖：pino 为可选 peerDependency，通过动态 import 加载。
+ * 宿主可注入自定义 logger（setLogger），完全绕过 pino。
+ *
+ * 降级策略：
+ *   1. pino 可用 → 双流输出（stderr + 文件日志）
+ *   2. pino 不可用 → console 零依赖 fallback（仅 stderr）
+ *   3. 宿主注入 → 优先使用宿主实现
+ *
+ * 使用方式：
+ *   import { logger } from '../logging/logger.js';
+ *   logger.info({ key: val }, 'message');
+ *
+ * 注入自定义 logger：
+ *   import { setLogger } from '../logging/logger.js';
+ *   setLogger(myCustomLogger);
+ */
+import type { ILogger } from '../logging/loggerInterface.js';
+/**
+ * 全局日志访问器
+ *
+ * 20+ 个内核模块统一通过此变量输出日志。
+ * 宿主注入自定义 logger 后，所有模块自动使用新实现。
+ */
+export declare const logger: ILogger;
+/**
+ * 替换全局日志实现
+ *
+ * 宿主项目在 Agent 初始化前调用此函数注入自定义 logger。
+ * 传入 undefined 则恢复为默认（pino 或 console fallback）。
+ *
+ * 注意：此函数修改全局状态。在单 Agent 模型下（ADR-011），
+ * 同一进程只有一个 Agent 实例，不会冲突。若同一进程创建多个
+ * Agent 实例并分别注入 logger，后者会覆盖前者——此时会输出警告。
+ */
+export declare function setLogger(newLogger: ILogger | undefined): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAS,MAAM,8BAA8B,CAAC;AAsPnE;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,OAapB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAqB9D"}