@zooique/memora 2.0.3 → 3.0.1

package/dist/agent/tracer.d.ts

@@ -1,27 +1,12 @@
 /**
- * Agent 可观测性接口 — 零依赖的轻量 Span/Trace 抽象
- *
- * 定义 ITracer 和 ISpan 接口，让宿主项目注入 OpenTelemetry 等实现。
- * 默认 NoopTracer 静默丢弃所有 span，不引入任何运行时开销。
- *
- * 设计约束（详见 ADR-001 · 运行时栈，零依赖原则）：
- *   - 禁止直接 import OpenTelemetry SDK（违反零依赖原则）
- *   - Span 收集为 fire-and-forget，不阻塞 AgentLoop 主流程
- *   - Tracer 未注入时自动降级，不抛异常
- *
- * 使用方式：
- *   // 宿主侧（泊文等）
- *   const otelTracer = new OpenTelemetryTracer(tracerProvider); // 宿主实现 ITracer
- *   const agent = new Agent({ ..., tracer: otelTracer });
- *
- *   // memora 内部
- *   const span = this.opts.tracer.startSpan('llm.call', { model: 'gpt-4o' });
- *   // ... LLM 调用 ...
- *   span.end();
+ * Agent 可观测性接口 — 零依赖轻量 Span/Trace 抽象。
+ * 宿主注入 ITracer 实现（如 OpenTelemetry）；默认 NoopTracer 静默丢弃所有 span，零运行时开销。
+ * 约束：只留 span 名契约（宿主按名过滤建监控面板）；Span 收集 fire-and-forget 不阻塞主流程；未注入时自动降级不抛异常。
  */
+import type { ContextBudget, ContextOccupancy } from '../agent/budget.js';
 /** Span 属性值类型 */
 type SpanAttributeValue = string | number | boolean;
-/** Span 接口 — 一次可观测操作的基本单元 */
+/** 一次可观测操作的基本单元 */
 export interface ISpan {
     /** 设置 Span 属性（键值对元数据） */
     setAttribute(key: string, value: SpanAttributeValue): void;
@@ -32,129 +17,136 @@ export interface ISpan {
 }
 /** Tracer 接口 — 宿主注入的可观测性实现 */
 export interface ITracer {
-    /**
-     * 开始一个新的 Span
-     *
-     * @param name - Span 名称（如 'llm.call'、'tool.execute'）
-     * @param attributes - 初始属性（可选）
-     * @returns ISpan 实例
-     */
+    /** 开始新 Span（name 如 'llm.call'、'tool.execute'；attributes 可选） */
     startSpan(name: string, attributes?: Record<string, SpanAttributeValue>): ISpan;
 }
-/** NoopTracer 单例（在未注入 tracer 时使用） */
+/** NoopTracer 单例（未注入 tracer 时使用） */
 export declare const NOOP_TRACER: ITracer;
 /**
- * AgentLoop 关键节点的 Span 名称常量
+ * AgentLoop 关键节点 Span 名称常量——供宿主按名过滤建监控面板。
+ * 各 span 名称/用途契约（span 名是宿主监控依赖，勿改）：
  *
- * 供宿主项目按名称过滤 span 做监控面板。
+ * 记忆检索耗时看 TOOL_EXEC span（search_memories 工具）；内核无召回类 span 发射点，
+ * 勿凭旧契约重新加名。
+ *
+ * DIFFICULTY / REPORT 是**预留名**（规划能力尚未落地），内核同样零 emit 点——
+ * 不得把注释写成正在进行的行为，否则宿主按名建监控面板会永远收不到数据。
  */
 export declare const TRACE_SPANS: {
-    /** 记忆召回阶段 */
-    readonly RECALL: "recall.recall";
     /** LLM API 调用 */
     readonly LLM_CALL: "llm.call";
     /** 工具执行 */
     readonly TOOL_EXEC: "tool.execute";
     /** 最终响应生成 */
     readonly RESPONSE: "response.generate";
-    /** 记忆衰减执行（补全衰减可观测性缺口） */
-    readonly DECAY: "memory.decay";
-    /**
-     * 上下文摘要生成（补全 generateContextSummary 可观测性缺口）
-     *
-     * 触发条件：消息超 maxContextTokens 触发截断时，调用 LLM 生成"遗忘补偿"摘要。
-     * 监控此 span 可观察截断频率、摘要生成耗时与失败率。
-     */
+    /** 上下文摘要生成——消息超 maxContextTokens 触发截断时调 LLM 生成"遗忘补偿"摘要；观察截断频率/耗时/失败率 */
     readonly CONTEXT_SUMMARY: "context.summary";
-    /**
-     * 对话后归档处理
-     *
-     * 触发条件：每轮 chat() 完成后调用 postProcess，含角色匹配、技能匹配、
-     * profile 归档、insight 提取、AutoConfigRefiner 五个子步骤。
-     * 监控此 span 可观察归档耗时、失败率、各子步骤执行情况。
-     */
+    /** 对话后归档处理——每轮 chat() 后 postProcess（round-summary 生成、角色/技能匹配）；观察归档耗时/失败率 */
     readonly POST_PROCESS: "archive.postProcess";
-    /**
-     * 实际记忆召回函数
-     *
-     * 触发条件：每轮 processUserInput 调用 recall() 执行双通道召回
-     * （语义搜索 + 关键词搜索 + hybridMerge 融合排序）。
-     * 现有 RECALL span 仅 wrapping 注入动作并立即 end，不覆盖实际召回耗时。
-     * 此 span 在 recall() 函数内部埋点，可观察真实召回耗时与双通道命中分布。
-     */
-    readonly RECALL_ACTUAL: "recall.actual";
-    /**
-     * 输入护栏检查
-     *
-     * 触发条件：用户输入注入上下文前调用 runGuardrails 检查。
-     * 监控此 span 可观察护栏触发频率、阻断率、耗时。
-     */
-    readonly GUARDRAIL_INPUT: "guardrail.input";
-    /**
-     * 输出护栏检查
-     *
-     * 触发条件：LLM 响应返回给用户前调用 runGuardrails 检查。
-     * 监控此 span 可观察输出护栏触发频率、阻断率、耗时。
-     */
-    readonly GUARDRAIL_OUTPUT: "guardrail.output";
+    /** 难度分级——**预留名**：规划能力（回答前判定简单/复杂），内核当前**零 emit 点** */
+    readonly DIFFICULTY: "round.difficulty";
+    /** 汇报闭环——**预留名**：规划能力（复杂任务收敛后独立汇报），内核当前**零 emit 点** */
+    readonly REPORT: "round.report";
 };
 /**
- * Agent 运行时指标快照
- *
- * 由 Agent.getMetrics() 聚合 AgentLoop + Agent 两层指标产出，
- * 供宿主项目构建监控面板或健康度诊断面板。
- *
- * 设计原则：
- *   - 纯只读快照——调用时不修改任何状态
- *   - 同步返回——不触发 LLM 或 IO
- *   - 累计值——指标从 Agent 初始化起累加，close() 后清零
- *
- * 分 5 个维度：LLM 调用、记忆召回、工具调用、上下文管理、记忆衰减。
+ * Agent 运行时指标快照——Agent.getMetrics() 聚合 AgentLoop+Agent 两层指标产出，供宿主做监控/健康度面板。
+ * 只读快照（不修改状态）、同步返回（不触发 LLM/IO）、累计值（init 起累加，close() 后清零）。
+ * 分 4 维度：LLM 调用、工具调用、上下文管理、任务级 SLO（无衰减/记忆召回维度：对应指标零写点）。
  */
 export interface AgentMetrics {
-    /** LLM 调用相关指标 */
+    /** LLM 调用指标 */
     llm: {
-        /** LLM 调用总次数（含重试，每次 provider.chat 调用算一次） */
+        /** 调用总次数（含重试，每次 provider.chat 算一次） */
         callCount: number;
-        /** 累计输入 token 数（基于 estimateTokens 粗略估算） */
+        /** 累计输入 token（estimateTokens 估算） */
         totalInputTokens: number;
-        /** 累计输出 token 数（基于 estimateTokens 粗略估算） */
+        /** 累计输出 token（estimateTokens 估算） */
         totalOutputTokens: number;
+        /** 实际 API 返回的输入 token 累计值（仅在 Provider 支持 usage 时填充，否则为 0） */
+        actualInputTokens: number;
+        /** 实际 API 返回的输出 token 累计值（仅在 Provider 支持 usage 时填充，否则为 0） */
+        actualOutputTokens: number;
+        /**
+         * LLM 空响应兜底次数：200 但 0 token 时用户看到兜底文案、
+         * 任务零产出却被 success 盖章。宿主据此识别「瞬态抽风」（可期望重试救回）vs「模型拒绝」（重试也空）。
+         */
+        emptyResponseCount: number;
+        /**
+         * 截断救回次数：截断型空响应（finishReason='length'）换策略重试后成功产出的次数。
+         * 与 `emptyResponseCount` 互补（最终仍空 = 救回失败归彼计）：救回成功的轮正文是真实
+         * 模型产出（不影响成功收尾），但「曾发生截断」只在本计数留痕——真机验证换策略重试
+         * 效力的唯一观测面。
+         */
+        truncationRecoveryCount: number;
+        /**
+         * tool_call 批次成形守卫（`auditToolCallPairing` 发送边界）实际拒发次数。
+         * N>0 代表内核真拦下了坏批次（孤立 tool 消息 / 空函数名 / 重复 id / 名称超长）。
+         * 与 `unparsedToolIntentCount` 互补：后者是「模型想干却没干成」（模型侧），
+         * 本值是「内核拦下了会发出去的坏批次」（内核侧守门）。
+         */
+        pairingGuardFires: number;
     };
-    /** 记忆召回相关指标 */
-    recall: {
-        /** 召回总次数（每轮对话 processUserInput 算一次） */
-        totalCount: number;
-        /** 命中次数（召回结果非空算命中） */
-        hitCount: number;
-        /** 命中率（0-1，hitCount / totalCount，totalCount 为 0 时返回 0） */
-        hitRate: number;
-    };
-    /** 工具调用相关指标 */
+    /** 工具调用指标 */
     tools: {
         /** 工具调用总次数 */
         callCount: number;
-        /** 工具调用失败次数（结果以 [ERR 开头） */
+        /** 失败次数（结果以 [ERR 开头） */
         failureCount: number;
+        /**
+         * 未解析工具意图数（文本骨架 <tool_call>/<function=> 但无常原生 toolCalls）。
+         * 让「想干活却一步没干成」不被静默盖「完成」；宿主可据 N>0 不显示该轮成功收尾。
+         */
+        unparsedToolIntentCount: number;
+        /**
+         * read_file 覆盖度台账回显（分支② `formatLedgerStub` 拦截）命中次数。
+         * 用于观测防重补缝是否过度拦截：0 代表防重没在替身层拦截
+         * （可能是护住也可能是拦不住），N 增大代表替身频繁顶替「拿回整份视角」的合法重读（规避行为红旗）。
+         * 健康判定需连同真机规避信号交叉看，本计数仅提供可观测的量化基线。
+         */
+        ledgerStubEchoCount: number;
+        /** read_dedup 护栏硬拦命中（同主体重复获取且结果仍在上下文）次数。
+         *  与 ledgerStubEchoCount 互补：本计数 = L2 精确判重（模型乒乓信号，撞墙升级文案的量化基线）。 */
+        readDedupBlockCount: number;
     };
     /** 上下文管理指标 */
     context: {
-        /** 上下文截断次数（messages 超过 maxContextTokens 触发截断的次数） */
+        /** 上下文截断次数（messages 超 maxContextTokens 触发截断） */
         truncationCount: number;
         /** 当前工作记忆消息数 */
         messageCount: number;
-        /** 当前估算 token 数（基于 estimateTokens） */
+        /** 当前估算 token 数（estimateTokens） */
         estimatedTokens: number;
+        /** 最近一次输入装配的上下文预算构成（可选：prepare 计算并透出，供宿主展示预算分配） */
+        budget?: ContextBudget;
+        /** 上下文占用快照（可选：prepare 期真实用量，供输入区指示器展示） */
+        occupancy?: ContextOccupancy;
+        /**
+         * 当前激活角色包底盘占用（system prompt 总体 token，persona+rules+技能 L1+工具 schema+全局技能+时间戳）。
+         * 与 occupancy.rolePackBaseTokens 同源但产生时机更早：装配 / 切换角色包时即确定（不依赖跑过 prepare），
+         * 冷启动 / 重启后首屏即可显示真实占比。prepare 期仍会以其实际注入值覆盖刷新（口径一致，同一估算器）。
+         */
+        rolePackBaseTokens?: number;
+    };
+    /** 任务级 SLO 度量（AgentLoop 层填充） */
+    tasks: {
+        /** 任务总执行次数（每次 processUserInput 算一次） */
+        totalCount: number;
+        /** 任务成功次数（正常完成，未被 abort/暂停） */
+        successCount: number;
+        /** 任务失败次数（被中止、超时、或迭代耗尽） */
+        failureCount: number;
+        /** 任务成功率（0-1，totalCount 为 0 时为 0） */
+        successRate: number;
+        /** 平均任务耗时（毫秒，0 表示尚无数据） */
+        avgDurationMs: number;
+    };
+    /** 任务表触发观测量（实证任务表是否被 LLM 触发，驱动 plan_item_boundary/折叠） */
+    plan: {
+        /** 累计调用 task_table_write 次数（= 建表/重建次数，0 = 从未触发） */
+        taskTableWriteCount: number;
+        /** 累计产出 plan_item_boundary 次数（= 思考折叠分块边界数，同 0 即布局骨血空转） */
+        planItemBoundaryCount: number;
     };
-    /** 记忆衰减指标（由 Agent 层填充，AgentLoop 层此字段为 null） */
-    decay: {
-        /** 衰减执行次数 */
-        runCount: number;
-        /** 累计衰减记忆数（score 被调低的记忆条数） */
-        totalDecayedCount: number;
-        /** 上次衰减时间（ISO 8601，null 表示从未执行过） */
-        lastRunAt: string | null;
-    } | null;
 }
 export {};
 //# sourceMappingURL=tracer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/agent/tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,iBAAiB;AACjB,KAAK,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAIpD,6BAA6B;AAC7B,MAAM,WAAW,KAAK;IACpB,yBAAyB;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC3D,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,4BAA4B;IAC5B,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrC;AAID,8BAA8B;AAC9B,MAAM,WAAW,OAAO;IACtB;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,KAAK,CAAC;CACjF;AA4BD,qCAAqC;AACrC,eAAO,MAAM,WAAW,EAAE,OAA0B,CAAC;AAIrD;;;;GAIG;AACH,eAAO,MAAM,WAAW;IACtB,aAAa;;IAEb,iBAAiB;;IAEjB,WAAW;;IAEX,aAAa;;IAEb,yBAAyB;;IAEzB;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;OAOG;;IAEH;;;;;OAKG;;IAEH;;;;;OAKG;;CAEK,CAAC;AAIX;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,GAAG,EAAE;QACH,4CAA4C;QAC5C,SAAS,EAAE,MAAM,CAAC;QAClB,2CAA2C;QAC3C,gBAAgB,EAAE,MAAM,CAAC;QACzB,2CAA2C;QAC3C,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,eAAe;IACf,MAAM,EAAE;QACN,uCAAuC;QACvC,UAAU,EAAE,MAAM,CAAC;QACnB,sBAAsB;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,0DAA0D;QAC1D,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,eAAe;IACf,KAAK,EAAE;QACL,cAAc;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,4BAA4B;QAC5B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,cAAc;IACd,OAAO,EAAE;QACP,oDAAoD;QACpD,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,sCAAsC;QACtC,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,+CAA+C;IAC/C,KAAK,EAAE;QACL,aAAa;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,8BAA8B;QAC9B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,oCAAoC;QACpC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,GAAG,IAAI,CAAC;CACV"}
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/agent/tracer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAIzE,iBAAiB;AACjB,KAAK,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAIpD,mBAAmB;AACnB,MAAM,WAAW,KAAK;IACpB,yBAAyB;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC3D,iBAAiB;IACjB,GAAG,IAAI,IAAI,CAAC;IACZ,4BAA4B;IAC5B,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrC;AAID,8BAA8B;AAC9B,MAAM,WAAW,OAAO;IACtB,+DAA+D;IAC/D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,KAAK,CAAC;CACjF;AA4BD,oCAAoC;AACpC,eAAO,MAAM,WAAW,EAAE,OAA0B,CAAC;AAIrD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW;IACtB,iBAAiB;;IAEjB,WAAW;;IAEX,aAAa;;IAEb,wEAAwE;;IAExE,4EAA4E;;IAE5E,sDAAsD;;IAEtD,uDAAuD;;CAE/C,CAAC;AAIX;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe;IACf,GAAG,EAAE;QACH,sCAAsC;QACtC,SAAS,EAAE,MAAM,CAAC;QAClB,oCAAoC;QACpC,gBAAgB,EAAE,MAAM,CAAC;QACzB,oCAAoC;QACpC,iBAAiB,EAAE,MAAM,CAAC;QAC1B,6DAA6D;QAC7D,iBAAiB,EAAE,MAAM,CAAC;QAC1B,6DAA6D;QAC7D,kBAAkB,EAAE,MAAM,CAAC;QAC3B;;;WAGG;QACH,kBAAkB,EAAE,MAAM,CAAC;QAC3B;;;;;WAKG;QACH,uBAAuB,EAAE,MAAM,CAAC;QAChC;;;;;WAKG;QACH,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,aAAa;IACb,KAAK,EAAE;QACL,cAAc;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,wBAAwB;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB;;;WAGG;QACH,uBAAuB,EAAE,MAAM,CAAC;QAChC;;;;;WAKG;QACH,mBAAmB,EAAE,MAAM,CAAC;QAC5B;0EACkE;QAClE,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,cAAc;IACd,OAAO,EAAE;QACP,gDAAgD;QAChD,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,mCAAmC;QACnC,eAAe,EAAE,MAAM,CAAC;QACxB,mDAAmD;QACnD,MAAM,CAAC,EAAE,aAAa,CAAC;QACvB,0CAA0C;QAC1C,SAAS,CAAC,EAAE,gBAAgB,CAAC;QAC7B;;;;WAIG;QACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,gCAAgC;IAChC,KAAK,EAAE;QACL,uCAAuC;QACvC,UAAU,EAAE,MAAM,CAAC;QACnB,+BAA+B;QAC/B,YAAY,EAAE,MAAM,CAAC;QACrB,2BAA2B;QAC3B,YAAY,EAAE,MAAM,CAAC;QACrB,qCAAqC;QACrC,WAAW,EAAE,MAAM,CAAC;QACpB,0BAA0B;QAC1B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,yDAAyD;IACzD,IAAI,EAAE;QACJ,mDAAmD;QACnD,mBAAmB,EAAE,MAAM,CAAC;QAC5B,0DAA0D;QAC1D,qBAAqB,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH"}

package/dist/agent/tracer.js

@@ -1,102 +1,57 @@
 /**
- * Agent 可观测性接口 — 零依赖的轻量 Span/Trace 抽象
- *
- * 定义 ITracer 和 ISpan 接口，让宿主项目注入 OpenTelemetry 等实现。
- * 默认 NoopTracer 静默丢弃所有 span，不引入任何运行时开销。
- *
- * 设计约束（详见 ADR-001 · 运行时栈，零依赖原则）：
- *   - 禁止直接 import OpenTelemetry SDK（违反零依赖原则）
- *   - Span 收集为 fire-and-forget，不阻塞 AgentLoop 主流程
- *   - Tracer 未注入时自动降级，不抛异常
- *
- * 使用方式：
- *   // 宿主侧（泊文等）
- *   const otelTracer = new OpenTelemetryTracer(tracerProvider); // 宿主实现 ITracer
- *   const agent = new Agent({ ..., tracer: otelTracer });
- *
- *   // memora 内部
- *   const span = this.opts.tracer.startSpan('llm.call', { model: 'gpt-4o' });
- *   // ... LLM 调用 ...
- *   span.end();
+ * Agent 可观测性接口 — 零依赖轻量 Span/Trace 抽象。
+ * 宿主注入 ITracer 实现（如 OpenTelemetry）；默认 NoopTracer 静默丢弃所有 span，零运行时开销。
+ * 约束：只留 span 名契约（宿主按名过滤建监控面板）；Span 收集 fire-and-forget 不阻塞主流程；未注入时自动降级不抛异常。
  */
 // ─── Noop 实现（默认，零开销）───────────────────────
-/** 空 Span 实现（静默丢弃所有操作） */
+/** 空 Span 实现（静默丢弃所有操作，无实际作用） */
 class NoopSpan {
     setAttribute(_key, _value) {
-        // noop
+        /* noop */
     }
     end() {
-        // noop
+        /* noop */
     }
     recordException(_error) {
-        // noop
+        /* noop */
     }
 }
-/** 空 Tracer 实现（始终返回 NoopSpan） */
+/** 空 Tracer 实现（始终返回共享的 NoopSpan） */
 class NoopTracer {
     startSpan(_name, _attributes) {
-        // 共享同一个 NoopSpan 实例，避免分配开销
+        // 共享同一 NoopSpan 实例，避免分配开销
         return NOOP_SPAN;
     }
 }
-/** 共享的 NoopSpan 单例（避免每次 startSpan 分配新对象） */
+/** 共享 NoopSpan 单例（避免每次 startSpan 分配新对象） */
 const NOOP_SPAN = new NoopSpan();
-/** NoopTracer 单例（在未注入 tracer 时使用） */
+/** NoopTracer 单例（未注入 tracer 时使用） */
 export const NOOP_TRACER = new NoopTracer();
 // ─── AgentLoop 预定义 Span 名称 ─────────────────────
 /**
- * AgentLoop 关键节点的 Span 名称常量
+ * AgentLoop 关键节点 Span 名称常量——供宿主按名过滤建监控面板。
+ * 各 span 名称/用途契约（span 名是宿主监控依赖，勿改）：
+ *
+ * 记忆检索耗时看 TOOL_EXEC span（search_memories 工具）；内核无召回类 span 发射点，
+ * 勿凭旧契约重新加名。
  *
- * 供宿主项目按名称过滤 span 做监控面板。
+ * DIFFICULTY / REPORT 是**预留名**（规划能力尚未落地），内核同样零 emit 点——
+ * 不得把注释写成正在进行的行为，否则宿主按名建监控面板会永远收不到数据。
  */
 export const TRACE_SPANS = {
-    /** 记忆召回阶段 */
-    RECALL: 'recall.recall',
     /** LLM API 调用 */
     LLM_CALL: 'llm.call',
     /** 工具执行 */
     TOOL_EXEC: 'tool.execute',
     /** 最终响应生成 */
     RESPONSE: 'response.generate',
-    /** 记忆衰减执行（补全衰减可观测性缺口） */
-    DECAY: 'memory.decay',
-    /**
-     * 上下文摘要生成（补全 generateContextSummary 可观测性缺口）
-     *
-     * 触发条件：消息超 maxContextTokens 触发截断时，调用 LLM 生成"遗忘补偿"摘要。
-     * 监控此 span 可观察截断频率、摘要生成耗时与失败率。
-     */
+    /** 上下文摘要生成——消息超 maxContextTokens 触发截断时调 LLM 生成"遗忘补偿"摘要；观察截断频率/耗时/失败率 */
     CONTEXT_SUMMARY: 'context.summary',
-    /**
-     * 对话后归档处理
-     *
-     * 触发条件：每轮 chat() 完成后调用 postProcess，含角色匹配、技能匹配、
-     * profile 归档、insight 提取、AutoConfigRefiner 五个子步骤。
-     * 监控此 span 可观察归档耗时、失败率、各子步骤执行情况。
-     */
+    /** 对话后归档处理——每轮 chat() 后 postProcess（round-summary 生成、角色/技能匹配）；观察归档耗时/失败率 */
     POST_PROCESS: 'archive.postProcess',
-    /**
-     * 实际记忆召回函数
-     *
-     * 触发条件：每轮 processUserInput 调用 recall() 执行双通道召回
-     * （语义搜索 + 关键词搜索 + hybridMerge 融合排序）。
-     * 现有 RECALL span 仅 wrapping 注入动作并立即 end，不覆盖实际召回耗时。
-     * 此 span 在 recall() 函数内部埋点，可观察真实召回耗时与双通道命中分布。
-     */
-    RECALL_ACTUAL: 'recall.actual',
-    /**
-     * 输入护栏检查
-     *
-     * 触发条件：用户输入注入上下文前调用 runGuardrails 检查。
-     * 监控此 span 可观察护栏触发频率、阻断率、耗时。
-     */
-    GUARDRAIL_INPUT: 'guardrail.input',
-    /**
-     * 输出护栏检查
-     *
-     * 触发条件：LLM 响应返回给用户前调用 runGuardrails 检查。
-     * 监控此 span 可观察输出护栏触发频率、阻断率、耗时。
-     */
-    GUARDRAIL_OUTPUT: 'guardrail.output',
+    /** 难度分级——**预留名**：规划能力（回答前判定简单/复杂），内核当前**零 emit 点** */
+    DIFFICULTY: 'round.difficulty',
+    /** 汇报闭环——**预留名**：规划能力（复杂任务收敛后独立汇报），内核当前**零 emit 点** */
+    REPORT: 'round.report',
 };
 //# sourceMappingURL=tracer.js.map

package/dist/agent/tracer.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../src/agent/tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAiCH,6CAA6C;AAE7C,0BAA0B;AAC1B,MAAM,QAAQ;IACZ,YAAY,CAAC,IAAY,EAAE,MAA0B;QACnD,OAAO;IACT,CAAC;IACD,GAAG;QACD,OAAO;IACT,CAAC;IACD,eAAe,CAAC,MAAa;QAC3B,OAAO;IACT,CAAC;CACF;AAED,iCAAiC;AACjC,MAAM,UAAU;IACd,SAAS,CAAC,KAAa,EAAE,WAAgD;QACvE,2BAA2B;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AAED,4CAA4C;AAC5C,MAAM,SAAS,GAAG,IAAI,QAAQ,EAAE,CAAC;AAEjC,qCAAqC;AACrC,MAAM,CAAC,MAAM,WAAW,GAAY,IAAI,UAAU,EAAE,CAAC;AAErD,kDAAkD;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,aAAa;IACb,MAAM,EAAE,eAAe;IACvB,iBAAiB;IACjB,QAAQ,EAAE,UAAU;IACpB,WAAW;IACX,SAAS,EAAE,cAAc;IACzB,aAAa;IACb,QAAQ,EAAE,mBAAmB;IAC7B,yBAAyB;IACzB,KAAK,EAAE,cAAc;IACrB;;;;;OAKG;IACH,eAAe,EAAE,iBAAiB;IAClC;;;;;;OAMG;IACH,YAAY,EAAE,qBAAqB;IACnC;;;;;;;OAOG;IACH,aAAa,EAAE,eAAe;IAC9B;;;;;OAKG;IACH,eAAe,EAAE,iBAAiB;IAClC;;;;;OAKG;IACH,gBAAgB,EAAE,kBAAkB;CAC5B,CAAC"}
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../src/agent/tracer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA6BH,6CAA6C;AAE7C,gCAAgC;AAChC,MAAM,QAAQ;IACZ,YAAY,CAAC,IAAY,EAAE,MAA0B;QACnD,UAAU;IACZ,CAAC;IACD,GAAG;QACD,UAAU;IACZ,CAAC;IACD,eAAe,CAAC,MAAa;QAC3B,UAAU;IACZ,CAAC;CACF;AAED,oCAAoC;AACpC,MAAM,UAAU;IACd,SAAS,CAAC,KAAa,EAAE,WAAgD;QACvE,0BAA0B;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AAED,2CAA2C;AAC3C,MAAM,SAAS,GAAG,IAAI,QAAQ,EAAE,CAAC;AAEjC,oCAAoC;AACpC,MAAM,CAAC,MAAM,WAAW,GAAY,IAAI,UAAU,EAAE,CAAC;AAErD,kDAAkD;AAElD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,iBAAiB;IACjB,QAAQ,EAAE,UAAU;IACpB,WAAW;IACX,SAAS,EAAE,cAAc;IACzB,aAAa;IACb,QAAQ,EAAE,mBAAmB;IAC7B,wEAAwE;IACxE,eAAe,EAAE,iBAAiB;IAClC,4EAA4E;IAC5E,YAAY,EAAE,qBAAqB;IACnC,sDAAsD;IACtD,UAAU,EAAE,kBAAkB;IAC9B,uDAAuD;IACvD,MAAM,EAAE,cAAc;CACd,CAAC"}