@zooique/memora 2.0.0 → 3.0.0

package/dist/llm/provider.d.ts

@@ -1,12 +1,16 @@
-/**
- * LLM Provider 抽象接口
- * 所有 LLM 实现（DeepSeek / 豆包 / OpenAI / Mock）必须实现此接口
- * 详见 ADR-003
- */
+/** LLM Provider 抽象接口：所有 LLM 实现（DeepSeek/豆包/OpenAI/Mock）必须实现 */
 import type { LlmChunk } from '../llm/types.js';
 export interface Message {
     role: 'system' | 'user' | 'assistant' | 'tool';
     content: string;
+    /**
+     * 轮次 ID（可选）：标识该消息归属的「问答轮次」。
+     * 由 loop 在写入 user/assistant/tool 消息时附上当前 currentRoundId，
+     * 作为替换式压缩（第一级 LRU）取 round-summary 的单一真理源——
+     * roundId 随消息携带，不依赖任何外部序列的尾部对齐，杜绝错位替换。
+     */
+    roundId?: string;
+    name?: string;
     toolCalls?: Array<{
         id: string;
         type: 'function';
@@ -30,11 +34,10 @@ export interface ChatOptions {
         };
     }>;
     /**
-     * 结构化输出约束（OpenAI response_format 兼容协议）
-     *
-     * 当 Provider 支持 structured output 且工具定义标记 strict 时，
-     * AgentLoop 自动生成 json_schema 约束，强制 LLM 输出合法 tool_call。
-     * 不支持的 Provider 静默跳过，fallback 到纯文本 tool_call 模式。
+     * 结构化输出约束（OpenAI Function Calling 响应格式约束）。
+     * 注意：response_format 不能与 tools 同时使用（OpenAI 协议限制），故 AgentLoop 默认不生成它
+     * （见 loop.ts buildChatOptions 注释）——此处仅为调用方显式传入时的可选能力孔，不宣称任何
+     * 「fallback 到纯文本 tool_call」的静默降级（文本出口不是可调用通道）。
      */
     response_format?: {
         type: 'json_schema';
@@ -44,48 +47,32 @@ export interface ChatOptions {
             schema: Record<string, unknown>;
         };
     };
-    /**
-     * 强制不使用流式（预留字段，当前无消费者）
-     *
-     * openaiCompatible 始终以 stream:true 发起请求（chat() 返回 AsyncIterable）。
-     * 本字段保留用于未来"非流式回退"场景（如低延迟短回复或 Provider 不支持 SSE 时）。
-     * 保留在公共 API 中以维持 ChatOptions 契约稳定。
-     */
-    stream?: boolean;
-    /**
-     * 中止信号：用于取消正在进行的 LLM 请求
-     *
-     * AgentLoop 在用户取消对话时传入 AbortSignal，
-     * Provider 应将 signal 传给底层 fetch/stream 读取，确保请求可被中断。
-     */
+    /** 推理深度控制：'low'|'medium'|'high'，Provider 不支持时静默忽略 */
+    reasoning_effort?: 'low' | 'medium' | 'high';
+    /** 中止信号：用户取消时传入，Provider 应传给底层 fetch/stream 以支持中断 */
     signal?: AbortSignal;
-    /**
-     * 请求超时（毫秒）。默认 120 秒。
-     * 超时后抛出 networkError，由 callLlmWithRetry 决定是否重试。
-     */
+    /** 请求超时（毫秒，默认 120s）：超时抛 networkError，由 callLlmWithRetry 决定是否重试 */
     timeoutMs?: number;
 }
-/**
- * LLM Provider 抽象类
- * 实现类需实现 chat() 流式方法
- */
+/** LLM Provider 抽象类：实现类需实现 chat() 流式方法 */
 export declare abstract class LlmProvider {
     abstract readonly name: string;
     /**
-     * 是否支持结构化输出（response_format json_schema）
+     * 是否支持原生工具调用（OpenAI Function Calling 的 tools 协议）。
      *
-     * 默认 false，子类可覆盖。用于非 tool_call 场景的结构化输出约束
-     * （如归档摘要强制 JSON、配置建议提取等）。调用方在构造 ChatOptions
-     * 时显式传入 response_format，Provider 应将其透传到请求 body。
+     * 与 supportsStructuredOutput 互斥（response_format 不能与 tools 同时使用，OpenAI 协议限制）：
+     * - 支持 tools → loop 走原生工具通道（列工具 + 传 tools 参数）。
+     * - 支持 structured → loop 传 response_format（JSON mode 回落）。
+     * - 两者皆 false → 无工具能力，loop 收起工具清单并显式告知（可观测，不静默）。
      *
-     * 注意：response_format 不能与 tools 同时使用（OpenAI 协议限制），
-     * tool_calls 走独立的 SSE delta 流式协议，无需此约束。
+     * 默认 **true**（存量行为）：云 LLM 绝大多数支持原生 FC（有工具集就传 tools，与历史一致）。
+     * 本地运行时（Ollama/LM Studio 等）是否支持原生 FC 无法从 baseUrl 推断，须在宿主配置时
+     * 显式置 false（互斥双能力位）。
      */
+    readonly supportsToolCalling: boolean;
+    /** 是否支持结构化输出（默认 false）。注意：response_format 不能与 tools 同时使用（OpenAI 协议限制） */
     readonly supportsStructuredOutput: boolean;
-    /**
-     * 流式对话
-     * 返回 AsyncIterable，每项是一个增量块
-     */
+    /** 流式对话：返回 AsyncIterable，每项是一个增量块 */
     abstract chat(messages: Message[], opts?: ChatOptions): AsyncIterable<LlmChunk>;
 }
 //# sourceMappingURL=provider.d.ts.map

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

@@ -1 +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;IACF;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;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;;;;;;;;;OASG;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"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,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;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,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;IACH,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;;;;;OAKG;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;IACF,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC7C,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0CAA0C;AAC1C,8BAAsB,WAAW;IAC/B,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAQ;IAE7C,yEAAyE;IACzE,QAAQ,CAAC,wBAAwB,EAAE,OAAO,CAAS;IAEnD,qCAAqC;IACrC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;CAChF"}

package/dist/llm/provider.js

@@ -1,18 +1,19 @@
-/**
- * LLM Provider 抽象类
- * 实现类需实现 chat() 流式方法
- */
+/** LLM Provider 抽象类：实现类需实现 chat() 流式方法 */
 export class LlmProvider {
     /**
-     * 是否支持结构化输出（response_format json_schema）
+     * 是否支持原生工具调用（OpenAI Function Calling 的 tools 协议）。
      *
-     * 默认 false，子类可覆盖。用于非 tool_call 场景的结构化输出约束
-     * （如归档摘要强制 JSON、配置建议提取等）。调用方在构造 ChatOptions
-     * 时显式传入 response_format，Provider 应将其透传到请求 body。
+     * 与 supportsStructuredOutput 互斥（response_format 不能与 tools 同时使用，OpenAI 协议限制）：
+     * - 支持 tools → loop 走原生工具通道（列工具 + 传 tools 参数）。
+     * - 支持 structured → loop 传 response_format（JSON mode 回落）。
+     * - 两者皆 false → 无工具能力，loop 收起工具清单并显式告知（可观测，不静默）。
      *
-     * 注意：response_format 不能与 tools 同时使用（OpenAI 协议限制），
-     * tool_calls 走独立的 SSE delta 流式协议，无需此约束。
+     * 默认 **true**（存量行为）：云 LLM 绝大多数支持原生 FC（有工具集就传 tools，与历史一致）。
+     * 本地运行时（Ollama/LM Studio 等）是否支持原生 FC 无法从 baseUrl 推断，须在宿主配置时
+     * 显式置 false（互斥双能力位）。
      */
+    supportsToolCalling = true;
+    /** 是否支持结构化输出（默认 false）。注意：response_format 不能与 tools 同时使用（OpenAI 协议限制） */
     supportsStructuredOutput = false;
 }
 //# sourceMappingURL=provider.js.map

package/dist/llm/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AAsEA;;;GAGG;AACH,MAAM,OAAgB,WAAW;IAG/B;;;;;;;;;OASG;IACM,wBAAwB,GAAY,KAAK,CAAC;CAOpD"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AA0DA,0CAA0C;AAC1C,MAAM,OAAgB,WAAW;IAG/B;;;;;;;;;;;OAWG;IACM,mBAAmB,GAAY,IAAI,CAAC;IAE7C,yEAAyE;IAChE,wBAAwB,GAAY,KAAK,CAAC;CAIpD"}

package/dist/llm/types.d.ts

@@ -1,11 +1,5 @@
-/**
- * LLM 适配层类型定义
- *
- * 详见 ADR-003 · LLM 适配层使用 OpenAI Chat Completions 兼容协议
- */
-/**
- * 工具调用描述
- */
+/** LLM 适配层类型定义（OpenAI Chat Completions 兼容协议） */
+import type { LlmProvider } from '../llm/provider.js';
 export interface ToolCall {
     id: string;
     type: 'function';
@@ -14,12 +8,61 @@ export interface ToolCall {
         arguments: string;
     };
 }
-/**
- * LLM 响应块
- */
 export interface LlmChunk {
     content?: string;
     toolCalls?: ToolCall[];
     finishReason?: 'stop' | 'tool_calls' | 'length' | 'error';
+    /**
+     * 模型思考内容增量片段（对应协议 `delta.reasoning_content`，deepseek 等思考模型）。
+     * 与 content 同为增量语义（消费侧自行累积）；仅供 UI 折叠展示，**不进正文/记忆**（CoT 防护）。
+     * 非思考模型恒 undefined，自然降级。命名用 thought 而非 reasoning/thinking：与多模型路由任务
+     * 类型 `TaskType='reasoning'` 语义分离，也避开 ProcessEvent 既有 `type:'thinking'` 相位事件。
+     */
+    thought?: string;
+    /**
+     * 流式工具意图预告：tool_call 的 name 在流式 delta 中**成形即上报**，
+     * 无需等到 finish_reason='tool_calls'。写文件等大参数工具的参数生成段可能长达数十秒，
+     * 此字段让 UI 提前渲染「准备中」工具行，消除事件真空期。瞬态展示轨，不落盘。
+     * 非 tool_calls 流 / 非 OpenAI 兼容 provider 恒 undefined，自然降级。
+     */
+    partialToolCall?: {
+        id: string;
+        name: string;
+    };
+    /** 实际 API 用量统计（仅在流结束时的最终 chunk 携带，部分 Provider 不支持） */
+    usage?: {
+        /** 输入 token 数（prompt_tokens） */
+        inputTokens: number;
+        /** 输出 token 数（completion_tokens） */
+        outputTokens: number;
+        /** 总 token 数（total_tokens） */
+        totalTokens?: number;
+    };
+}
+/** 单个 Provider 配置（providers 映射表的值）；内核仅透传 provider 字段，不做路由决策 */
+export interface ProviderEntryConfig {
+    /** 标识（仅用于日志，不影响路由） */
+    provider: string;
+    model: string;
+    /** API 基础 URL（可选——内核不做预设回退，缺失时工厂会报错） */
+    baseUrl?: string;
+    /** API 密钥（可选，从环境变量读取。本地 LLM 如 Ollama 可为空字符串） */
+    apiKey?: string;
+    /** temperature，未配置时回退到全局 llm.temperature */
+    temperature?: number;
+    /** 上下文窗口（token），未配置时回退到 memory.maxContextTokens */
+    contextWindow?: number;
+    /**
+     * 是否支持原生工具调用（OpenAI Function Calling tools 协议）。
+     * 本地运行时（Ollama/LM Studio 等）是否支持原生 FC 无法从 baseUrl 推断，搬到配置显式声明。
+     * 与 supportsStructuredOutput 互斥（response_format 不能与 tools 同用）。
+     */
+    supportsToolCalling?: boolean;
+    /** 是否支持结构化输出（response_format / JSON mode） */
+    supportsStructuredOutput?: boolean;
 }
+/** LLM 任务类型：按任务复杂度路由到不同 Provider/模型（simple/reasoning/code/summary） */
+export type TaskType = 'simple' | 'reasoning' | 'code' | 'summary';
+/** Provider 路由选择器：按任务类型返回 Provider；不配置路由时所有任务类型复用同一 Provider */
+export type ProviderRouter = (taskType: TaskType) => LlmProvider;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,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,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;IAC1D;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,eAAe,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,sDAAsD;IACtD,KAAK,CAAC,EAAE;QACN,gCAAgC;QAChC,WAAW,EAAE,MAAM,CAAC;QACpB,oCAAoC;QACpC,YAAY,EAAE,MAAM,CAAC;QACrB,8BAA8B;QAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAID,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,6CAA6C;IAC7C,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,sEAAsE;AACtE,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;AAEnE,gEAAgE;AAChE,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,WAAW,CAAC"}

package/dist/llm/types.js

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

package/dist/llm/types.js.map

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

package/dist/logging/logger.d.ts

@@ -1,40 +1,19 @@
 /**
  * 结构化日志 — 全局单例 + 可替换 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);
+ * 零第三方依赖、零 fs 副作用：默认 console fallback（写 stderr）；宿主经 setLogger() 注入自定义实现。
+ * 内核只持有日志「接口」职责——不加载任何三方日志库，不决定日志落盘位置（通道/落盘归宿主）。
  */
 import type { ILogger } from '../logging/loggerInterface.js';
 /**
- * 全局日志访问器
- *
- * 20+ 个内核模块统一通过此变量输出日志。
- * 首次访问任一方法时懒触发 pino 升级（确保 import 零 fs 副作用）。
- * 宿主注入自定义 logger 后，所有模块自动使用新实现。
+ * 全局日志访问器：20+ 内核模块统一经此输出；每个方法为对当前 `_logger` 的**普通委托闭包**，
+ * 宿主注入/复位后所有持有者自动切换到新实现（函数身份稳定，外部可将 `logger.info` 直接作回调传递）。
  */
 export declare const logger: ILogger;
 /**
- * 替换全局日志实现
- *
- * 宿主项目在 Agent 初始化前调用此函数注入自定义 logger。
- * 传入 undefined 则恢复为默认（pino 或 console fallback）。
- *
- * 注意：此函数修改全局状态。在单 Agent 模型下（ADR-011），
- * 同一进程只有一个 Agent 实例，不会冲突。若同一进程创建多个
- * Agent 实例并分别注入 logger，后者会覆盖前者——此时会输出警告。
+ * 替换全局日志实现：宿主在 Agent 初始化前调用注入自定义 logger；传入 undefined 恢复默认。
+ * 注入即成为内核**唯一**日志出口：同时桥接 utils 层（`loggerHolder`），
+ * 使 scanner / eventEmitter / rolePackManager 等 utils 侧模块也走注入实现（而非停留在 console fallback）。
+ * 修改全局状态：单 Agent 模型下不会冲突；若多处注入，后者覆盖前者并输出警告。
  */
 export declare function setLogger(newLogger: ILogger | undefined): void;
 //# sourceMappingURL=logger.d.ts.map

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

@@ -1 +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;AAyQnE;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAE,OAiBpB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAmB9D"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAS,MAAM,8BAA8B,CAAC;AAoFnE;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,OAKpB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAgB9D"}

package/dist/logging/logger.js

@@ -1,33 +1,12 @@
-import { toError } from '../utils/toError.js';
-// 桥接 utils 层 loggerHolder：utils 运行时不依赖 logging/，
-// 由本模块在加载和 setLogger 时反向注入 logger 实例。
+// 反向注入 utils 层 loggerHolder：utils 运行时不依赖 logging/，由本模块桥接 logger 实例
 import { setLogger as setUtilsLogger } from '../utils/loggerHolder.js';
-/**
- * 从 unknown 值提取错误消息（复用零依赖的 toError，避免类型断言）
- */
-function errMsg(err) {
-    return toError(err).message;
-}
-/** 日志级别（从环境变量读取，默认 info） */
+/** 日志级别（环境变量，默认 info） */
 const level = process.env['MEMORA_LOG_LEVEL'] ?? 'info';
-/** 敏感键模式（匹配时值被替换为 [REDACTED]） */
+/** 敏感键名匹配（命中时值被替换为 [REDACTED]） */
 const SENSITIVE_KEY_PATTERN = /api[_-]?key|token|password|secret|authorization|credential/i;
 /**
- * pino redact 路径配置（与 console fallback 的 SENSITIVE_KEY_PATTERN 保持一致）
- *
- * 支持嵌套对象脱敏：`*.apiKey` 匹配任意层级的 apiKey 字段
- */
-const PINO_REDACT_PATHS = [
-    'apiKey', 'token', 'password', 'secret', 'authorization', 'credential',
-    '*.apiKey', '*.token', '*.password', '*.secret',
-    '*.authorization', '*.credential',
-    '*.*.apiKey', '*.*.token', '*.*.password', '*.*.secret',
-];
-/**
- * 对象脱敏：深拷贝对象并将敏感键的值替换为 [REDACTED]
- *
- * 仅用于 console fallback logger 的 JSON.stringify 路径，
- * 防止 API Key 等敏感数据泄漏到 stderr。
+ * 对象脱敏：深拷贝并将敏感键值替换为 [REDACTED]
+ * 单一脱敏实现：console fallback 输出对象前统一经此脱敏（任意嵌套层级 + 变体 + 大小写不敏感）。
  */
 function redactSensitiveKeys(obj) {
     const redacted = {};
@@ -44,11 +23,7 @@ function redactSensitiveKeys(obj) {
     }
     return redacted;
 }
-/** 是否生产环境 */
-const isProd = process.env['NODE_ENV'] === 'production';
-/** 是否启用文件日志 */
-const fileEnabled = process.env['MEMORA_LOG_FILE'] !== '0';
-/** 日志级别优先级（用于 console fallback 的级别过滤） */
+/** 日志级别优先级（console fallback 级别过滤用） */
 const LEVEL_PRIORITY = {
     trace: 0,
     debug: 1,
@@ -62,238 +37,73 @@ const LEVEL_PRIORITY = {
 function shouldLog(targetLevel) {
     return (LEVEL_PRIORITY[targetLevel] ?? 2) >= (LEVEL_PRIORITY[level] ?? 2);
 }
-/**
- * Console 零依赖 fallback logger
- *
- * pino 不可用时使用。仅输出到 stderr，不写文件。
- * 满足 ILogger 接口，所有内核模块透明使用。
- */
+/** Console 零依赖 fallback logger：仅 stderr，满足 ILogger 接口 */
 function createConsoleLogger() {
     return {
-        info: (objOrMsg, msg) => {
-            if (!shouldLog('info'))
-                return;
-            const text = typeof objOrMsg === 'string' ? objOrMsg : msg ?? '';
-            if (typeof objOrMsg === 'object') {
-                console.error(`[INFO] ${text}`, JSON.stringify(redactSensitiveKeys(objOrMsg)));
-            }
-            else {
-                console.error(`[INFO] ${text}`);
-            }
-        },
-        warn: (objOrMsg, msg) => {
-            if (!shouldLog('warn'))
-                return;
-            const text = typeof objOrMsg === 'string' ? objOrMsg : msg ?? '';
-            if (typeof objOrMsg === 'object') {
-                console.error(`[WARN] ${text}`, JSON.stringify(redactSensitiveKeys(objOrMsg)));
-            }
-            else {
-                console.error(`[WARN] ${text}`);
-            }
-        },
-        error: (objOrMsg, msg) => {
-            if (!shouldLog('error'))
-                return;
-            const text = typeof objOrMsg === 'string' ? objOrMsg : msg ?? '';
-            if (typeof objOrMsg === 'object') {
-                console.error(`[ERROR] ${text}`, JSON.stringify(redactSensitiveKeys(objOrMsg)));
-            }
-            else {
-                console.error(`[ERROR] ${text}`);
-            }
-        },
-        debug: (objOrMsg, msg) => {
-            if (!shouldLog('debug'))
-                return;
-            const text = typeof objOrMsg === 'string' ? objOrMsg : msg ?? '';
-            if (typeof objOrMsg === 'object') {
-                console.error(`[DEBUG] ${text}`, JSON.stringify(redactSensitiveKeys(objOrMsg)));
-            }
-            else {
-                console.error(`[DEBUG] ${text}`);
-            }
-        },
+        info: createConsoleLogFn('info'),
+        warn: createConsoleLogFn('warn'),
+        error: createConsoleLogFn('error'),
+        debug: createConsoleLogFn('debug'),
     };
 }
 /**
- * pino → ILogger 包装器
- *
- * pino 通过动态 import 加载，实例类型未知。
- * 包装器显式提取 4 个日志方法，避免 as unknown as ILogger 双重断言。
- *
- * @param pinoInst pino 实例（动态导入）
- * @returns ILogger 兼容对象
+ * 创建 console fallback 单级别日志方法
+ * 消除 4 处 info/warn/error/debug 方法同构实现；共享：shouldLog 过滤、文本提取、对象路径脱敏。
  */
-function wrapPinoAsLogger(pinoInst) {
-    return {
-        info: pinoInst.info.bind(pinoInst),
-        warn: pinoInst.warn.bind(pinoInst),
-        error: pinoInst.error.bind(pinoInst),
-        debug: pinoInst.debug.bind(pinoInst),
-    };
-}
-/**
- * 尝试创建 Pino logger
- *
- * pino 为可选 peerDependency，通过动态 import 加载。
- * 加载失败（宿主未安装 pino）则回退到 console logger。
- *
- * @returns Pino logger 实例，或 null（pino 不可用）
- */
-async function tryCreatePinoLogger() {
-    try {
-        const pino = (await import('pino')).default;
-        const { resolve } = await import('node:path');
-        const { mkdirSync, createWriteStream, statSync, truncateSync } = await import('node:fs');
-        const { expandHome } = await import('../utils/path.js');
-        const dataDir = process.env['MEMORA_DATA_DIR'] ?? '~/.memora';
-        const resolvedDataDir = resolve(expandHome(dataDir));
-        // pino.StreamEntry 类型在 pino 未安装时不可用，用内联类型
-        const streams = [];
-        // stderr 流（开发环境友好显示）
-        if (!isProd) {
-            streams.push({ level: 'info', stream: process.stderr });
-        }
-        // 文件流（结构化 JSON，方便后续分析）
-        // 日志轮转保护——超过 10MB 时截断重写，防止长期运行生成巨大文件
-        if (fileEnabled) {
-            try {
-                const logsDir = resolve(resolvedDataDir, 'logs');
-                mkdirSync(logsDir, { recursive: true });
-                const logFilePath = resolve(logsDir, 'memora.log');
-                // 检查文件大小，超过 10MB 时截断
-                const LOG_MAX_BYTES = 10 * 1024 * 1024; // 10MB
-                try {
-                    const stat = statSync(logFilePath);
-                    if (stat.size > LOG_MAX_BYTES) {
-                        truncateSync(logFilePath, 0);
-                        process.stderr.write(`[memora] 日志文件超过 10MB，已截断：${logFilePath}\n`);
-                    }
-                }
-                catch (err) {
-                    // 文件不存在或无法 stat，正常——首次写入
-                    if (process.env['MEMORA_DEBUG'])
-                        process.stderr.write(`[memora] stat 日志文件失败：${errMsg(err)}\n`);
-                }
-                streams.push({
-                    level: 'info',
-                    stream: createWriteStream(logFilePath, { flags: 'a' }),
-                });
-            }
-            catch (err) {
-                process.stderr.write(`[memora] 日志文件创建失败：${errMsg(err)}\n`);
-            }
+function createConsoleLogFn(targetLevel) {
+    const prefix = `[${targetLevel.toUpperCase()}]`;
+    return (objOrMsg, msg) => {
+        if (!shouldLog(targetLevel))
+            return;
+        const text = typeof objOrMsg === 'string' ? objOrMsg : (msg ?? '');
+        if (typeof objOrMsg === 'object') {
+            // 对象路径：脱敏后 JSON 序列化，防敏感数据泄漏
+            console.error(`${prefix} ${text}`, JSON.stringify(redactSensitiveKeys(objOrMsg)));
         }
-        if (streams.length === 0) {
-            // 通过包装器适配 ILogger 接口，避免 as unknown as ILogger 双重断言
-            // SEC-AUDIT: 配置 redact 防止敏感信息写入日志文件
-            return wrapPinoAsLogger(pino({ level, redact: PINO_REDACT_PATHS }));
+        else {
+            console.error(`${prefix} ${text}`);
         }
-        // 通过包装器适配 ILogger 接口
-        // SEC-AUDIT: 配置 redact 防止敏感信息写入日志文件
-        return wrapPinoAsLogger(pino({ level, redact: PINO_REDACT_PATHS }, pino.multistream(streams)));
-    }
-    catch (err) {
-        // pino 未安装，回退到 console logger
-        if (process.env['MEMORA_DEBUG'])
-            process.stderr.write(`[memora] pino 加载失败：${errMsg(err)}\n`);
-        return null;
-    }
+    };
 }
 /**
- * 全局日志单例
- *
- * 初始化为 console fallback（同步可用，零 fs 副作用）。
- * 首次日志调用时懒触发 pino 升级（确保模块 import 零 fs 副作用）。
- * 宿主通过 setLogger() 注入后自动替换，并跳过 pino 升级。
+ * 全局日志单例：初始为 console fallback（同步可用，零 fs 副作用）。
+ * 宿主经 setLogger() 注入后替换；未注入时保持 console fallback。
  */
 let _logger = createConsoleLogger();
-/** 标记 _logger 是否已被宿主注入（用于 setLogger 覆盖检测 + pino 升级跳过） */
+/** 是否已被宿主注入（setLogger 覆盖告警判定） */
 let _loggerInjected = false;
-/** pino 升级是否已启动（确保只触发一次，避免重复 fs 操作） */
-let _pinoUpgradeStarted = false;
-// 同步初始化 utils 层 logger 桥接（确保 utils 在 pino 异步加载前就有 console fallback）
+// 同步初始化 utils 层 logger 桥接（确保 utils 始终持有日志实现，默认即 console fallback）
 setUtilsLogger(_logger);
 /**
- * 懒触发 pino 升级
- *
- * 在首次日志调用时触发，确保模块 import 零 fs 副作用。
- * - 宿主已注入 logger 时跳过升级（_loggerInjected 守卫）
- * - 升级启动后不再重复触发（_pinoUpgradeStarted 守卫）
- * - 竞态守卫：then 回调内再次检查 _loggerInjected，避免覆盖宿主在升级期间注入的 logger
- */
-function maybeUpgradeToPino() {
-    if (_pinoUpgradeStarted || _loggerInjected)
-        return;
-    _pinoUpgradeStarted = true;
-    void tryCreatePinoLogger().then((pinoLogger) => {
-        // 守卫：升级期间宿主可能已通过 setLogger 注入自定义 logger
-        if (_loggerInjected) {
-            setUtilsLogger(_logger);
-            return;
-        }
-        if (pinoLogger) {
-            _logger = pinoLogger;
-            _logger.info({ level, prod: isProd, fileEnabled }, 'logger 启动（pino）');
-        }
-        else {
-            _logger.info({ level, prod: isProd }, 'logger 启动（console fallback，pino 未安装）');
-        }
-        // 桥接注入到 utils 层（utils 运行时不依赖 logging/）
-        setUtilsLogger(_logger);
-    });
-}
-/**
- * 全局日志访问器
- *
- * 20+ 个内核模块统一通过此变量输出日志。
- * 首次访问任一方法时懒触发 pino 升级（确保 import 零 fs 副作用）。
- * 宿主注入自定义 logger 后，所有模块自动使用新实现。
+ * 全局日志访问器：20+ 内核模块统一经此输出；每个方法为对当前 `_logger` 的**普通委托闭包**，
+ * 宿主注入/复位后所有持有者自动切换到新实现（函数身份稳定，外部可将 `logger.info` 直接作回调传递）。
  */
 export const logger = {
-    get info() {
-        maybeUpgradeToPino();
-        return _logger.info.bind(_logger);
-    },
-    get warn() {
-        maybeUpgradeToPino();
-        return _logger.warn.bind(_logger);
-    },
-    get error() {
-        maybeUpgradeToPino();
-        return _logger.error.bind(_logger);
-    },
-    get debug() {
-        maybeUpgradeToPino();
-        return _logger.debug.bind(_logger);
-    },
+    info: (...args) => _logger.info(...args),
+    warn: (...args) => _logger.warn(...args),
+    error: (...args) => _logger.error(...args),
+    debug: (...args) => _logger.debug(...args),
 };
 /**
- * 替换全局日志实现
- *
- * 宿主项目在 Agent 初始化前调用此函数注入自定义 logger。
- * 传入 undefined 则恢复为默认（pino 或 console fallback）。
- *
- * 注意：此函数修改全局状态。在单 Agent 模型下（ADR-011），
- * 同一进程只有一个 Agent 实例，不会冲突。若同一进程创建多个
- * Agent 实例并分别注入 logger，后者会覆盖前者——此时会输出警告。
+ * 替换全局日志实现：宿主在 Agent 初始化前调用注入自定义 logger；传入 undefined 恢复默认。
+ * 注入即成为内核**唯一**日志出口：同时桥接 utils 层（`loggerHolder`），
+ * 使 scanner / eventEmitter / rolePackManager 等 utils 侧模块也走注入实现（而非停留在 console fallback）。
+ * 修改全局状态：单 Agent 模型下不会冲突；若多处注入，后者覆盖前者并输出警告。
  */
 export function setLogger(newLogger) {
     if (newLogger) {
-        // 检测覆盖：如果当前 logger 已被宿主注入，且新 logger 不是同一个，说明有多处注入
+        // 检测覆盖：当前已被宿主注入且新实例不同，说明有多处注入
         if (_loggerInjected && _logger !== newLogger) {
             _logger.warn('setLogger 覆盖了已有的自定义 logger（单 Agent 模型下不应出现此情况）');
         }
         _loggerInjected = true;
         _logger = newLogger;
+        // 注入即唯一出口：同步桥接 utils 层，否则 utils 侧仍持有旧 console fallback
+        setUtilsLogger(_logger);
     }
     else {
-        // 恢复默认：同步恢复到 console fallback
-        // pino 升级不主动触发——等下次日志调用时由 maybeUpgradeToPino() 懒触发
-        // 这样 setLogger(undefined) 零 fs 副作用，与模块加载时一致
+        // 恢复默认：回到内置 console fallback，并重新桥接 utils 层
         _loggerInjected = false;
-        _pinoUpgradeStarted = false; // 允许下次日志调用时重新触发升级
         _logger = createConsoleLogger();
         setUtilsLogger(_logger);
     }