@ai-setting/roy-agent-core 1.7.77 → 1.7.88

package/dist/env/event-source/timer-handler.d.ts

@@ -25,6 +25,29 @@ export declare const DEFAULT_TIMER_INTERVAL_MS: number;
  * 2. 便于测试时注入 mock
  */
 export type GetRunningTasksFn = () => BackgroundTask[];
+/**
+ * ★ Task #5409：tick 的两种触发模式（写进 `timer.tick.fire` span 的 mode 属性）
+ */
+export type TimerFireMode = "interval" | "schedule";
+/**
+ * ★ Task #5409：tick 统计（跳过 / 触发计数）
+ *
+ * 为什么需要：修复后**空转 tick 不再留 trace**（原来每 30 秒一条 `timer.tick`，
+ * 每天约 2880 条无价值 span，全部 0ms）。代价是「被跳过的 tick」在 trace 里
+ * 不可见，无法再靠 `debug trace --list` 判断 timer 是否活着。
+ *
+ * 因此把可观测性改到**进程内计数器**：`getTickStats()` 可随时读取，
+ * 另外每次真正 fire 的 span 上会带 `skippedSinceLastFire` —— 一眼看出
+ * 「这个 timer 一直在跑，只是长期被 running 任务挡住」。
+ */
+export interface TimerTickStats {
+    /** 累计真正 fire（构建并投递 SelfReminder 事件）的次数 */
+    firedTicks: number;
+    /** 累计被跳过的 tick 次数（有 running 任务 / 抛错 / 时刻不命中 / 当日去重） */
+    skippedTicks: number;
+    /** 距离上次 fire 之间被跳过的 tick 次数（fire 后归零） */
+    skippedSinceLastFire: number;
+}
 /**
  * 用于注入 BackgroundTaskManager 的 options key
  */
@@ -51,6 +74,29 @@ export interface TimerScheduleEntry {
     label?: string;
     sessionId?: string;
 }
+/**
+ * ★ Task #5409：`fireTick()` 的入参（object 形式，便于 paramFilter 取出全部字段）
+ */
+export interface TimerFireContext {
+    /** 触发模式 */
+    mode: TimerFireMode;
+    /** timer 事件源 id（`this.config.id`）—— paramFilter 拿不到 this，故显式传入 */
+    sourceId: string;
+    /** 距上次 fire 被跳过的 tick 次数 */
+    skippedSinceLastFire: number;
+    /** schedule 模式的命中项 */
+    entry?: TimerScheduleEntry;
+}
+/**
+ * ★ Task #5409：构造 `timer.tick.fire` span 的属性（供 paramFilter 摊平到顶层）
+ *
+ * 出参键名就是 `debug trace` / `debug span` 里能直接看到的字段：
+ * - `mode`：interval / schedule
+ * - `sourceId`：timer 事件源 id（哪个 timer 触发的）
+ * - `skippedSinceLastFire`：距上次 fire 被跳过的 tick 次数
+ * - `scheduleTime` / `scheduleLabel`：schedule 模式的命中项
+ */
+export declare function buildFireSpanAttributes(ctx: TimerFireContext): Record<string, unknown>;
 /**
  * 校验 `HH:MM` 格式
  *
@@ -100,6 +146,10 @@ export declare class TimerInstance implements EventSourceInstance {
     private readonly skipWhenRunning;
     /** 已触发标记：`YYYY-MM-DD#HH:MM` → true（当日去重） */
     private readonly firedKeys;
+    /** ★ Task #5409：tick 统计（跳过/触发计数），替代原「每次都留 trace」的可观测性 */
+    private firedTicks;
+    private skippedTicks;
+    private skippedSinceLastFire;
     /** 可注入时钟（测试用） */
     private readonly now;
     private status;
@@ -117,14 +167,54 @@ export declare class TimerInstance implements EventSourceInstance {
     start(): Promise<void>;
     stop(): Promise<void>;
     getStatus(): EventSourceStatus;
+    /**
+     * ★ Task #5409：读取 tick 统计（跳过 / 触发计数）
+     *
+     * 修复后空转 tick 不再落 trace，用这个计数器保留「timer 还活着」的可观测性：
+     * - `firedTicks` 一直为 0 且 `skippedTicks` 持续增长 → 一直被 running 任务挡住
+     * - 两者都不再增长 → tick 本身可能没在跑（`getStatus()` 应为 running）
+     */
+    getTickStats(): TimerTickStats;
     onEvent(handler: EventSourceEventHandler): void;
     offEvent(): void;
     /**
      * 定时器 tick 回调
      *
      * Rule-based 检查：有 status === "running" 的后台任务时跳过本次触发
+     *
+     * ★ Task #5409：**入口不再挂 `@TracedAs`**。
+     *
+     * 原来 `@TracedAs("timer.tick")` 在入口就建 span，于是「有 running 任务 →
+     * return」这种什么都没做的空转 tick 也会落一条 trace。生产实测每 30 秒一条、
+     * 全部 0ms/ok，每天约 2880 条，是 traces.db 膨胀的增量来源之一。
+     *
+     * 现在只有**真正 fire 了 SelfReminder 事件**才记一条 `timer.tick.fire`
+     * （见 `fireTick()`），跳过路径零 trace；跳过次数改由 `getTickStats()` 暴露。
      */
     private tick;
+    /**
+     * ★ Task #5409：记录一次「被跳过」的 tick（零 trace）
+     *
+     * 可观测性走两条路：
+     * 1. 进程内计数器（`getTickStats()`）—— 供 `/status` 类排查直接读
+     * 2. 每累计 `SKIPPED_TICK_LOG_EVERY` 次打一条 debug 汇总日志 —— 供 app.log
+     *    确认 timer 仍在跑（`log_trace.logging.level=debug` 时可见）
+     */
+    private recordSkip;
+    /**
+     * ★ Task #5409：真正 fire 一次的**唯一入口** —— 事件构建 + 投递 + 1 条 trace
+     *
+     * 命名 `timer.tick.fire`（而不是保留 `timer.tick`）：trace 列表里一眼能看出
+     * 「这条 span 代表 timer 真的触发了」，不再是「tick 发生了但可能什么都没做」。
+     *
+     * span 属性（经 paramFilter 摊平到顶层）：
+     * - `mode`：interval / schedule
+     * - `sourceId`：timer 事件源 id
+     * - `skippedSinceLastFire`：距上次 fire 被跳过的次数 —— 长期被 running 任务
+     *   挡住时这个数字会很大，是「空转但不留 trace」的可观测证据
+     * - `scheduleTime` / `scheduleLabel`：schedule 模式下的命中项
+     */
+    private fireTick;
     /**
      * ★ Task #4815：schedule 模式 tick
      *
@@ -135,6 +225,10 @@ export declare class TimerInstance implements EventSourceInstance {
      * 4. schedule 模式默认**不**做 rule-based 跳过；
      *    仅当 options.skipWhenRunning=true 时才检查后台任务
      * 5. 命中 → 标记已触发 + 构建事件（prompt 取当次命中项）
+     *
+     * ★ Task #5409：入口不再挂 `@TracedAs`。只有真正命中并 fire 时才由
+     * `fireTick()` 落一条 `timer.tick.fire`（mode=schedule）；未命中 / 当日已触发 /
+     * 被 running 任务挡住 / schedule 全项非法 → 零 trace，只累加 `skippedTicks`。
      */
     private tickSchedule;
     /**
@@ -157,6 +251,10 @@ export declare class TimerInstance implements EventSourceInstance {
      *   - metadata 注入 `scheduleLabel`（可选，便于下游识别是哪个时刻）
      *
      * @param entry 命中的 schedule 项；interval 模式不传
+     *
+     * ★ Task #5409：不再挂 `@TracedAs` —— 它只在 `fireTick()` 内部被调用一次，
+     * 且 fireTick 已经有 `timer.tick.fire` span。原来这里再加一个装饰器，
+     * 会让「一次 fire」落 2 条 span（实测 span 数交替 2/3 正是这个原因）。
      */
     private buildSelfReminderEvent;
 }

package/dist/env/event-source/types.d.ts

@@ -40,11 +40,22 @@ export declare const BUILT_IN_EVENT_SOURCE_TYPES: {
      * 「CLI 没有 IM 通道，输出到 stdout」的 prompt（而不是套用飞书模板）。
      */
     readonly CLI_COMMAND: "cli-command";
+    /**
+     * ★ Task #5142：企业微信（WeCom）也是一个事件源。
+     *
+     * 走企微官方 CLI `wecom-cli`（npm: `@wecom/cli`）。
+     *
+     * ⚠️ **必须是新类型名 `wecom-cli`，不能抄 `lark-cli`**：
+     * `getHandlerForEsType(esType)` 是 v2 notify prompt 的唯一分派 key，
+     * 抄成 lark-cli 会让 agent 拿到「用 lark-cli 发到 oc_xxx」的 prompt，
+     * 而企微根本没有 oc_xxx。
+     */
+    readonly WECOM_CLI: "wecom-cli";
 };
 /**
  * 内置事件源类型列表
  */
-export declare const BUILT_IN_EVENT_SOURCE_TYPE_LIST: ("lark-cli" | "timer" | "bounty-im" | "cli-command")[];
+export declare const BUILT_IN_EVENT_SOURCE_TYPE_LIST: ("lark-cli" | "timer" | "bounty-im" | "cli-command" | "wecom-cli")[];
 /**
  * HandleRuleConfig
  *
@@ -123,6 +134,33 @@ export interface EventSourceConfig {
      *    里手动开启，否则 consumer 能 ready 但永远收不到事件。
      */
     eventKeys?: string[];
+    /**
+     * ★ Task #5360（补充需求 2026-11-11 20:54）：是否推送「状态通知文本消息」。
+     *
+     * ## 背景
+     *
+     * 卡片化改造后，rule-based 直发的状态文本（`⏱️ 后台任务运行中 20m` /
+     * `✅ 已完成 36m`）默认下线，改由任务卡片承载。本开关是**逃生舱**：
+     * 保留旧的文本推送能力，用户想恢复时一行配置即可，不必 revert 代码。
+     *
+     * ## 取值
+     *
+     * - `false` / **缺省**（默认）：不发状态通知文本 —— 全部走卡片
+     * - `true`：逐字恢复改造前的文本推送行为
+     *
+     * ## 边界（很重要，别扩大语义）
+     *
+     * - 只影响「状态通知文本」，**不影响卡片**（卡片是渠道独立插件，与本开关正交）
+     * - 不影响 `sink === "stdout"` 的 CLI 本地输出（本地没有卡片可发，
+     *   文本是唯一可见输出 —— 见 `shouldDeliverNoticeText` 的 stdout 例外）
+     * - 不影响卡片失败兜底 markdown 与失败回执（那是**降级/异常告知**，不是状态通知）
+     *
+     * ## 类型严格性
+     *
+     * 判定处一律用 `=== true`，所以手改 JSON 写出 `"true"`（字符串）/ `1` /
+     * `null` 都会被当成 `false` —— 防 YAML/手改造成的类型漂移。
+     */
+    statusNotifications?: boolean;
     /** 轮询间隔（毫秒，定时器用） */
     interval?: number;
     /** cron 表达式（定时器用） */
@@ -161,8 +199,52 @@ export interface EventSourceConfig {
      *
      * 内置 bounty-im handler 在 config.systemPrompt 未设置时使用默认 prompt；
      * 用户可显式覆盖。
+     *
+     * ★ ES-M1（Task #5144）：lark-cli 渠道在 lean 模式下，未配置本字段时
+     * 也会注入渠道静态 prompt（buildLarkChannelSystemPrompt），规则文本
+     * 前置到 system prompt；配置了则用户值在前 + 渠道 prompt 在后。
      */
     systemPrompt?: string;
+    /**
+     * 渠道 prompt 模式（ES-M1，Task #5144；默认 "lean"）
+     *
+     * - "lean"（默认）：渠道静态回复规则（关键 0/1/2/3、30KB 上限、禁分段、
+     *   --as bot、mktemp+jq 模板，~1566 tok）前置注入 system prompt；
+     *   per-event recommendedAction 压缩为动态小卡片（action 一句话 +
+     *   replyTo 四元组）。
+     * - "legacy"：per-source 回退开关 —— 行为与旧版完全一致
+     *   （recommendedAction 4.4KB 长模板、无渠道 systemPrompt 注入）。
+     *
+     * 用途：灰度期如果 sub-agent / 第三方 consumer 依赖
+     * `payload.message` 里 JSON 的长模板规则文本，可将该 source
+     * 回退为 legacy。
+     */
+    channelPromptMode?: "legacy" | "lean";
+    /**
+     * ★ Task #5333 — 该事件源驱动的 agent 会话**额外注入**的工具名列表。
+     *
+     * 背景（用户 2026-11-11 16:54）：「ES config 支持 extend tools ——
+     * 不同 ES 驱动的 agent 注入 tools 可不同。企微 ES 有特有工具
+     * （wecom_respond），不该配到 default agent。」
+     *
+     * 语义：
+     * - 只有 `tool.metadata.channelOnly === true` 的工具受本字段控制
+     *   （未标记 channelOnly 的工具对所有 agent 本来就可见，无需声明）
+     * - 未配置本字段 → 不放行任何 channelOnly 工具
+     * - 配置后 → handler 把它写进 `evt.metadata.extendTools`，
+     *   经 run.ts / run-headless-dispatch.ts 透传到
+     *   `AgentContext.extendTools`，最终由 ToolRegistry / AgentComponent
+     *   的可见性过滤放行
+     *
+     * 内置默认：`wecom-cli` handler 恒注入 `["wecom_respond"]`
+     * （企微唯一出站工具，不配也必须可见），用户的 config.extendTools
+     * 追加在后并去重。
+     *
+     * ```json
+     * { "type": "wecom-cli", "extendTools": ["my_extra_tool"] }
+     * ```
+     */
+    extendTools?: string[];
     /**
      * Agent IM 地址（bounty-im 类型用，格式：agent-id@host）
      *
@@ -244,6 +326,30 @@ export interface EventMetadata {
     senderEmail?: string;
     /** 租户 key */
     tenantKey?: string;
+    /**
+     * ★ Task #5212：lark 引用消息上下文
+     *
+     * lark-cli `im.message.receive_v1` 事件的引用字段归一化：
+     * - rootId:   根消息 id（root_id）
+     * - parentId: 直接回复的父消息 id（reply_to / parent_id）
+     * - threadId: thread id（thread_id），仅 thread 场景存在
+     *
+     * 无任何引用字段（普通消息）时为 undefined。
+     * agent 据此知道当前消息是对哪条消息的回复。
+     */
+    replyContext?: {
+        rootId?: string;
+        parentId?: string;
+        threadId?: string;
+        /**
+         * ★ Task #5251：企微引用内容（quote 内嵌原文归一文本）
+         *
+         * 企微长连接协议直接内嵌被引用内容（SDK BaseMessage.quote），
+         * 无被引用消息 id —— 因此企微侧只有 quotedText，
+         * 无 rootId/parentId/threadId（那些是 lark 侧字段）。
+         */
+        quotedText?: string;
+    };
     /**
      * 事件源注入到 agent systemPrompt 的专属 prompt
      *
@@ -262,6 +368,45 @@ export interface EventMetadata {
 export interface RecommendedAction {
     /** 动作描述 */
     action: string;
+    /**
+     * ★ ES-M1（Task #5144）：静态规则是否已前置到渠道 system prompt。
+     *
+     * lean 模式（默认）下 extractMetadata 会置 `true`：
+     * 规则文本（关键 0/1/2/3、30KB 上限、禁分段、--as bot、mktemp+jq
+     * 模板）不再出现在 `action` 里，而是注入了渠道 system prompt
+     * （EventMetadata.systemPrompt）。旧 consumer / 灰度观察者可据此
+     * 识别"卡片已瘦身"这一新形态。
+     *
+     * legacy 模式不设置该字段（保持旧版形态识别）。
+     */
+    staticRulesInSystemPrompt?: true;
+    /**
+     * ★ Task #5212（DS review MAJOR-2）：lark 引用消息上下文
+     *
+     * 当前消息「是对哪条消息的回复」的定位信息（rootId / parentId / threadId）。
+     *
+     * ⚠️ 为什么挂在 recommendedAction 而不是只挂 metadata：
+     *   agent 实际收到的 user message = `payload.message` =
+     *   `JSON.stringify({ rawData, recommendedAction, triggerEventId? })`
+     *   —— **不含 metadata 键**。只写进 evt.metadata / evt.payload.metadata
+     *   的话，agent 读不到任何 parentId 值，需求（「让 agent LLM 看到是对某
+     *   消息 id 的回复」）无法闭环。
+     *
+     * 无引用字段（普通消息）时为 undefined（不产生空对象）。
+     */
+    replyContext?: {
+        rootId?: string;
+        parentId?: string;
+        threadId?: string;
+        /**
+         * ★ Task #5251：企微引用内容（quote 内嵌原文归一文本）
+         *
+         * 企微长连接协议直接内嵌被引用内容（SDK BaseMessage.quote），
+         * 无被引用消息 id —— 因此企微侧只有 quotedText，
+         * 无 rootId/parentId/threadId（那些是 lark 侧字段）。
+         */
+        quotedText?: string;
+    };
     /** 回复目标（如果有） */
     replyTo?: {
         appId?: string;
@@ -346,6 +491,13 @@ export interface EventSourceEventPayload {
      * 反查原始 chatId。
      */
     triggerEventId?: string;
+    /**
+     * Task #5199：已落盘媒体文件的本地路径（image/file/video/voice）。
+     *
+     * WecomCliInstance.handleWsFrame 异步下载解密后写入；
+     * agent 用 understand_image(image_source=<path>) 读图。
+     */
+    mediaFiles?: string[];
 }
 /**
  * EventSource 事件
@@ -653,7 +805,7 @@ export interface BuildNotifyHandlePromptInput {
         error?: string;
         /**
          * 子 session ID —— 超时 / 失败后如需**续跑**，主 agent 可直接
-         * `delegate_task(existingSubSessionId=<此值>, ...)` 让子代理继承历史继续推进，
+         * `delegate_task(sub_session_id="<此值>", ...)` 让子代理继承历史继续推进，
          * 不必从零重来。
          */
         subSessionId?: string;