@ai-setting/roy-agent-core 1.7.52 → 1.7.53

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

@@ -0,0 +1,486 @@
+/**
+ * 内置 EventSourceHandler 实现
+ *
+ * 提供 lark-cli 事件源类型的 Handler 实现
+ * 支持通过 handleRule.plugins 加载外部 Plugin
+ */
+import { ChildProcess } from "child_process";
+import type { EventSourceConfig, EventSourceHandler, EventSourceInstance, EventSourceStatus, EventSourceEventHandler, EventMetadata, ReplyChannel, RecommendedAction } from "./types";
+import { timerHandler } from "./timer-handler";
+import { bountyIMHandler } from "./bounty-im-handler";
+import { bountyCliHandler } from "./bounty-cli-handler";
+/**
+ * 构建 Lark `im.message.receive_v1` 事件推荐动作 prompt (Task #2185 / #4137 / #4242)
+ *
+ * 现状：飞书回复统一走 **单条结构化 post content**（`--msg-type post --content`）。
+ *   - @mention 用结构化 at 节点 `{"tag":"at","user_id":"ou_xxx"}`，飞书会回填 mentions
+ *     （真实 @）；正文用 `{"tag":"md","text":"..."}` 节点，仍支持标题/表格/加粗。
+ *   - 历史上的 `--markdown` + 正文内联 `<at>` 已废弃：LLM 常写坏标签
+ *     （自闭合 `<at/>` 会让整条 Markdown 解析失败、@ 退化成纯文本）。
+ *   - 用 mktemp + trap + `jq --rawfile` 安全构造 content（jq 自动转义换行）。
+ *
+ * 设计要点：
+ *   1. 推荐路径：先写临时 .md 文件（正文），再用 jq 组装结构化 content，
+ *      最后 `lark-cli ... --msg-type post --content "$content"` 调用。
+ *   2. 显式禁止：--text / --msg-type text / --markdown / 正文内联 <at> 标签 /
+ *      字面反斜杠+n / ANSI-C 引号 —— 这些都会导致坏 Markdown 或 @ 失效。
+ *   3. 必须使用下方 recommendedAction.replyTo 给定的 profile / chatId / messageId
+ *      / --as bot，禁止 LLM 凭印象自己填。
+ *   4. replyTo 既有结构（appId / profile / chatId / messageId）保持不变，老 consumer
+ *      仍能解析。
+ *   5. prompt 自身 JSON/日志转义干净：警示用 words 描述字面反斜杠+n，避免把 0x0A
+ *      控制字符混进示例字符串里。
+ *   6. **#4242 + #4243 合并修复**：禁止 sub-agent 把回复拆成多条循环 send
+ *      （综合 #4137 webhook 重复通知 + #4171 msg 进 thread 折叠丢失 +
+ *      #4241 review 暴露 sub-agent 自行拼 flag）。整次回复**只发一条**结构化 post
+ *      （「发送类」命令只调一次），全部内容写进单个 md 节点；超长压缩正文或用附件区。
+ *      长度上限用**官方 30 KB 请求体**（飞书错误码 230025），不是早期误写的
+ *      "4096 字符"——那个数字没有出处，还会被 agent 当成分段阈值。
+ *   7. **单一来源（去重）**：#4242 的「关键 0」与 #4243 的「关键 4」讲的是同一条规则，
+ *      两个并行 task 各自 merge 后重复了三遍、占 prompt 38% 字符，且给出的"照抄模板"
+ *      互相矛盾（send --chat-id vs reply --message-id）。现合并为「关键 0」单一章节，
+ *      `--reply-in-thread` 全文只出现一次；由
+ *      `single-message-reply-prompt.test.ts` 的 (A)/(D)/(G) 组守护，防止再次重复。
+ *   8. **指令优先级**：lark-im skill 建议 `--markdown` / ANSI-C 引号，与本 prompt 冲突；
+ *      故在「关键 0」顶部显式声明"以本 prompt 为准"，避免 sub-agent 自行揉合两套指令
+ *      （#4241 的偏移指令语义根因）。
+ *
+ * 注意：本 prompt 字符串会在 console.log / JSON 序列化链路里往返多次，
+ * 不要在示例里出现字面换行（0x0A 控制字符）与 bash ANSI-C 引号（dollar 符号紧跟单引号），
+ * 否则就是新的字面陷阱。
+ */
+export declare function buildLarkRecommendedAction(opts: {
+    profile?: string;
+    chatType?: string;
+    appId?: string;
+    chatId?: string;
+    messageId?: string;
+}): RecommendedAction;
+/**
+ * 提取事件元信息
+ *
+ * 支持两种事件格式：
+ * 1. 简化格式（lark-cli 推送）：顶层有 message_id, chat_id, content 等
+ * 2. 嵌套格式：event.message, header.event_type 等
+ */
+/**
+ * 从 rawEvent 中提取 EventMetadata + ReplyChannel + RecommendedAction
+ *
+ * 【导出】原文件 default 为 internal,Task #2326 lark-messageid-context 集成测试需要直接调用。
+ * 处理两种事件格式：
+ * - 嵌套格式: { event: { message: { message_id, chat_id }, sender: {...} } }
+ * - 简化格式: { message_id, chat_id, sender_id }
+ */
+export declare function extractMetadata(rawEvent: unknown, eventType?: string): {
+    metadata: EventMetadata;
+    replyChannel?: ReplyChannel;
+    recommendedAction?: RecommendedAction;
+};
+/**
+ * LarkCli EventSourceInstance 实现
+ * 支持通过 handleRule.plugins 加载外部 Plugin
+ *
+ * 进程启动逻辑参考 bash-effect.ts：
+ * - 使用 shell: true + stdio: ["pipe", "pipe", "pipe"]
+ * - stdin 保持打开直到进程结束
+ */
+export declare class LarkCliInstance implements EventSourceInstance {
+    private config;
+    private status;
+    /**
+     * ★ Task #4339：所有 consume 子进程（**一个 EventKey 一个进程**）。
+     *
+     * lark-cli 硬约束（1.0.98 实测）：`event consume` 只接受**恰好一个** EventKey；
+     * 逗号多 key（`k1,k2`）和通配符（`im.*`）都会 `unknown EventKey` 直接 exit 2。
+     * 所以"同时监听 im.message.receive_v1 + card.action.trigger"必须拆成两个
+     * 子进程 —— 它们共享同一个 bus daemon（UDS），互不干扰。
+     *
+     * 详见 reports/2026-10-19-lark-cli-multi-event-consume-research.md
+     */
+    private children;
+    /** 默认 stream 行缓冲（processStream 兼容入口用；每个子进程用自己的 buffer） */
+    private buffer;
+    /** ★ Task #4339：start() 并发保护 */
+    private starting;
+    private eventHandler?;
+    /**
+     * ★ Task #4230 follow-up：卡片路由端口（lookup/getTask 侧）
+     *
+     * 构建一次、多处复用（含 loadPlugins 收尾时补 ensureTaskGroupChat）。
+     */
+    private cardRoutingPorts?;
+    /** ★ Task #4230 follow-up：群名缓存（判定"触发群是不是别 task 的专属群"） */
+    private chatNameCache;
+    /** ★ Task #4230 follow-up：已加载插件实例（收尾 cross-wire 用） */
+    private pluginInstances;
+    /**
+     * ★ Task #4331：卡片按钮 callback 端口（注入 getTask/updateTaskContext/createGroupChat/deleteGroupChat/notifier）。
+     * 由外部（一般是 loadPlugins 末尾的 cross-wire 或 CLI 启动器）注入。
+     * 未注入时 handleCardActionEvent 会 warn 并 skip（不影响其他事件处理）。
+     */
+    private cardActionPorts?;
+    /**
+     * ★ Task #4331：注入卡片按钮 callback 端口（由 caller/loadPlugins 调用）
+     */
+    setCardActionPorts(ports: import("../task/plugins/lark-card-action-handler").CardActionPorts): void;
+    /** 诊断：端口是否注入 */
+    hasCardActionPorts(): boolean;
+    /**
+     * ★ Task #3977/3978 修复：去重最近处理的 event_id
+     *
+     * 根因：lark-cli event consume 偶尔会把同一条 JSON 事件写到 stdout 和 stderr
+     * 两路（race condition），导致 processStream 被调用两次 → 同一个飞书事件被
+     * dispatch 两次 → 主 agent 和 sub-agent 都创建同名 task（bug 表现：一次
+     * 用户委托产生 2 个 task）。
+     *
+     * 防御性做法：在 handleEvent 内根据 event_id 做 LRU 去重，避免重复 dispatch。
+     * - 用 Map 记录最近 100 个 event_id + 处理时间
+     * - 同一 instance 内 60s 内相同 event_id 视为重复，跳过
+     *
+     * ★ Task #4137 升级为跨实例共享 SHARED_SEEN（module-level Map）：
+     * - 多 LarkCliInstance 共享去重表，避免"实例 A 处理过、实例 B 又处理一次"
+     * - key = event_id（共享窗口）
+     *
+     * 注意：这里**不做** self-echo（自回灌）检测。回灌的根因是出站身份，
+     * 已在源头解决——所有出站一律 `--as bot`（见 buildLarkRecommendedAction），
+     * bot 自己发出的消息不会被本 app 的事件订阅回投。
+     * 不要再引入"记录已发送 message_id 再在入口拦截"的兜底：它依赖 parse lark-cli
+     * stdout（正文含裸引号会 PARSE FAIL，拿不到 id 就形同虚设），收益/复杂度不成正比。
+     */
+    private static SHARED_SEEN;
+    private static SHARED_MSG_TTL_MS;
+    private static SHARED_MSG_MAX;
+    /**
+     * 测试钩子：重置 SHARED_SEEN 静态状态。
+     * 仅供单测在 beforeEach 里调用，生产路径禁止调用。
+     */
+    static __resetDedupForTest(): void;
+    private recentEventIds;
+    private readonly DEDUP_WINDOW_MS;
+    private readonly DEDUP_MAX_SIZE;
+    /**
+     * Environment 引用（由 EventSourceComponent.startSource 调用 setEnvironment 注入）
+     *
+     * 用于在 registerPluginHooks 时通过 env.getComponent('task') 拿到 taskComponent，
+     * 给支持 setTaskUpdater 的 plugin（如 PerTaskGroupChatPlugin）注入 DB 持久化回调。
+     * 未注入时（如第三方 handler）所有 plugin 都不会拿到 taskUpdater，行为与之前一致。
+     */
+    private environment?;
+    /** 已加载的 plugins */
+    private loadedPlugins;
+    constructor(config: EventSourceConfig);
+    /**
+     * 注入 Environment 引用（实现 EventSourceInstance.setEnvironment）
+     *
+     * 调用时机：EventSourceComponent.startSource 在 instance.start() 之前调用。
+     * 必须先于 loadPlugins()，否则 plugin 拿不到 taskComponent。
+     */
+    setEnvironment(env: unknown): void;
+    start(): Promise<void>;
+    /**
+     * ★ Task #4339：配置自检 —— 两个"静默失效"陷阱，必须在启动时喊出来。
+     *
+     * ① `eventKeys` 里包含 card.action.trigger，但 `eventTypes` 过滤器不含它：
+     *    `handleEvent` 会先过 eventTypes 再分流，卡片点击会被**静默丢弃**。
+     * ② `eventKeys` 里包含 card.action.trigger，但飞书后台没开"回调配置"：
+     *    consumer 能 ready，事件永远不来（lark-cli 无 preflight 检查，我们查不到，
+     *    只能提示）。
+     */
+    private warnOnCardActionConfigTraps;
+    /**
+     * ★ Task #4339：spawn 一个 consume 子进程。
+     *
+     * 抽成 protected 方法是为了让单测注入"假子进程"（否则测试会真的去连
+     * lark-cli bus，污染真实事件订阅）。
+     */
+    protected spawnConsumeChild(command: string): ChildProcess;
+    /**
+     * ★ Task #4339：解析要消费的 EventKey 列表。
+     *
+     * lark-cli 的硬约束（1.0.98 实测）：
+     *   - `event consume` 只接受**恰好一个** EventKey；
+     *   - 逗号多 key / 通配符都会 `unknown EventKey` 直接 exit 2；
+     *   - 所以"同时监听 receive + card action"必须是**多个子进程**，
+     *     它们共享同一个 bus daemon（UDS），互不干扰。
+     *
+     * 配置来源优先级：
+     *   1. `config.eventKeys`（推荐：显式多 key，例：["im.message.receive_v1","card.action.trigger"]）
+     *   2. `config.command`（用户自定义单命令，原样保留 / 注入 --profile）
+     *   3. 默认 `["im.message.receive_v1"]`
+     */
+    resolveConsumeEventKeys(): string[];
+    /**
+     * ★ Task #4339：构造本实例要 spawn 的完整命令列表（已注入 --profile）。
+     */
+    buildConsumeCommands(): string[];
+    /**
+     * ★ Task #4339：启动前 best-effort 冲突检查。
+     *
+     * lark-cli 一个 EventKey 只允许一个 consumer；若已有 orphan consumer 占着，
+     * 我们新起的进程会立刻 `failed_precondition` exit 2，整个 event-source 变 error。
+     * 这里提前查一次 `lark-cli event status --json` 并打 warn，让排障有据可依。
+     *
+     * 完全 best-effort：lark-cli 不存在 / 输出不是 JSON / 超时 → 静默跳过。
+     */
+    private warnOnConsumeConflict;
+    /**
+     * ★ Task #4339：查询当前 bus 上已被占用的 EventKey 集合。
+     *
+     * 完全 best-effort：lark-cli 不存在 / 输出不是 JSON / 超时 → 返回空集合。
+     * protected 是为了让单测覆盖成 no-op（避免真的 spawn lark-cli）。
+     */
+    protected probeBusyEventKeys(): Promise<Set<string>>;
+    /**
+     * ★ Task #4339：挂接单个 consume 子进程的 stdio。
+     *
+     * 每个子进程持有**自己的行缓冲**（避免两个进程的 NDJSON 切片互相错拼）。
+     *
+     * @returns 收到 `[event] ready event_key=` 时 resolve；5s 内没收到 ready
+     *          （或进程直接退出，例如配置错误 exit 2）也会 resolve —— 避免
+     *          start() 永久卡住，但此时 status 已被置为 error。
+     */
+    private wireChildStreams;
+    stop(): Promise<void>;
+    getStatus(): EventSourceStatus;
+    onEvent(handler: EventSourceEventHandler): void;
+    offEvent(): void;
+    /**
+     * 加载 handleRule.plugins 中指定的 plugins
+     *
+     * ★ 必须先调用 setEnvironment()，否则 plugin.setTaskUpdater 不会注入。
+     */
+    private loadPlugins;
+    /**
+     * ★ Task #4339：把 `card.action.trigger` 的真实端口接到本实例上。
+     *
+     * 为什么必须有这一步：`card.action.trigger` 走的是「直接回调」而不是 Agent ——
+     * `handleEvent` 分流后调 `handleCardActionEvent`，而它**依赖
+     * `this.cardActionPorts` 已注入**；未注入时只打一条 warn 然后 return。
+     * Task #4331 实现了这套机制但**一直没接线**（生产链路是死代码，只有单测 +
+     * 手工 bridge 脚本在跑）。
+     *
+     * 依赖：
+     *   - getTask / updateTaskContext   ← env.getComponent("task")
+     *   - createGroupChat / deleteGroupChat ← lark-card-action-handler 的 lark-cli 实现
+     *   - notifier ← pluginInstances 里插件共享的 LarkCardPatchNotifier
+     *     （共享实例才知道这张卡片已累积的里程碑/过程历史；找不到就新建一个，
+     *      `updateMetaAndBuildCard` 会返回 undefined，handler 自动走 fallback）
+     *
+     * 任意一环缺失（如没配 task component）→ 不注入，行为与之前一致（warn + skip）。
+     */
+    private wireCardActionPorts;
+    /**
+     * Task #4230 follow-up：把「按需建专属群」能力接到卡片路由端口上
+     *
+     * 顺序问题：两个插件是分别 import + registerPluginHooks 的，NotifyHook 在
+     * PerTaskGroupChatPlugin 之前加载，所以只能在 loadPlugins 收尾时补一次。
+     */
+    private wireCardRoutingGroupProvider;
+    /**
+     * 获取插件的 hook 点列表
+     */
+    private getPluginHookPoints;
+    /**
+     * 实例化内置 Plugin
+     *
+     * 早期版本是按字符串名走动态 import，会因为 bundler 把 workspace 内的 core
+     * 同时识别为「内联源码」+「外部包」而产生两份 module（导致 tracer 单例分裂、
+     * traceId 跨 plugin 边界丢失）。现在改成顶层静态 import + factory 注册表，
+     * 让 bundler 直接看到依赖关系并完成内联。
+     */
+    private importPlugin;
+    /**
+     * 注册 Plugin hooks 到 globalHookManager
+     *
+     * 支持三种模式：
+     * 1. BasePlugin 模式：继承 BasePlugin，需要调用 init(env)
+     * 2. TaskPlugin 模式：plugin.hooks 是 [{ point, priority }]
+     * 3. Hook 模式：plugin.execute 是函数
+     *
+     * ★ Task #XXXX P0 修复：检测 plugin.setTaskUpdater 存在性，自动绑定 taskComponent.updateTask 包装。
+     *   - PerTaskGroupChatPlugin 依赖 setTaskUpdater 把 larkPerTaskChatId 持久化到 DB
+     *   - 未注入时：plugin 在 attachChatIdToTask 阶段只更新 in-memory，DB 没持久化 → 后续
+     *     AFTER_UPDATE 从 DB 加载 task 时 getTaskChatId() 返回 undefined，所有通知 silently skip。
+     *   - 修复链路：EventSourceComponent.startSource → instance.setEnvironment(env) →
+     *     registerPluginHooks → env.getComponent('task').updateTask → plugin.setTaskUpdater
+     */
+    private registerPluginHooks;
+    /**
+     * ★ P0 修复：如果 plugin 支持 setTaskUpdater，自动注入 taskComponent.updateTask 包装
+     *
+     * 链路：
+     * EventSourceComponent.startSource → instance.setEnvironment(env) →
+     * loadPlugins → registerPluginHooks → injectTaskUpdater(plugin) →
+     * env.getComponent('task') → taskComponent.updateTask → plugin.setTaskUpdater
+     *
+     * 行为：
+     * - plugin.setTaskUpdater 存在 && env 已注入 && taskComponent 存在 → 注入成功
+     * - 任意一环缺失 → 跳过注入，plugin 走 fallback（in-memory only）
+     * - 已注入（plugin.hasTaskUpdater() === true）→ 跳过，避免重复
+     *
+     * 日志：注入成功/失败都有 debug 日志，方便排查为什么 plugin 拿不到 DB 写权限
+     */
+    private injectTaskUpdater;
+    /**
+     * ★ Task #4039 C 项：如果 plugin 支持 setTaskGetter，自动注入 taskComponent.getTask。
+     *
+     * 用途：PerTaskGroupChatPlugin 的更新/完成/操作通知在"任务自身无群"时沿
+     * `parent_task_id` 上溯祖先群，与 CLI notify 路径（resolveNotifyChatIds）统一。
+     * 未注入时退化为只读自身 context（向后兼容）。
+     */
+    private injectTaskGetter;
+    /**
+     * ★ Task #4230 follow-up：给支持 setCardRoutingPorts 的 plugin 注入「卡片路由端口」
+     *
+     * 端口负责三件"需要 IO"的事（让 plugin 保持纯逻辑 + 可单测）：
+     * 1. lookupChatOwnership(chatId)：这个群是不是某个 task 的专属群（多重信号）
+     * 2. getTask(id)：lineage 上溯
+     * 3. ensureTaskGroupChat(task)：按需建专属群（由 PerTaskGroupChatPlugin 提供，
+     *    在 loadPlugins 收尾时 cross-wire）
+     */
+    private injectCardRoutingPorts;
+    /**
+     * 取群名（带进程内缓存）
+     *
+     * 只在需要判定"触发群是不是别 task 的群"时调用（DB 信号为空才会走到）。
+     * lark-cli 失败 / 未安装 → 返回 undefined（判定退化为"不是专属群"）。
+     */
+    private lookupChatName;
+    /**
+     * ★ Task #4023：如果 plugin 支持 setSessionComponent，自动注入 SessionComponent 引用
+     *
+     * 链路：
+     * EventSourceComponent.startSource → instance.setEnvironment(env) →
+     * registerPluginHooks → env.getComponent('session') → plugin.setSessionComponent
+     *
+     * 未注入时：PerTaskGroupChatPlugin 不会写 chat↔task 绑定，群消息 handler 拿不到
+     *           parentTaskId 注入。task.context.larkPerTaskChatId 仍正常工作。
+     */
+    private injectSessionComponent;
+    /**
+     * ★ Task #4023 + #4025 OC track #3 改进：查询 chat_id → task_id 绑定
+     *
+     * 缓存策略：依赖 SessionComponent.getChatTaskBinding 内置 LRU+TTL 缓存，
+     * 这里不再重复缓存（避免失效传播问题）。
+     *
+     * 设计选择（采纳 OC track B 的设计哲学）：
+     * - duck-typing 检查 sessionComponent.getChatTaskBinding（不依赖具体类）
+     * - 仅当 binding.status === "ready" 且 taskId 是正数时才返回
+     *   （保留 A 的 0/负数 fail-fast 哲学；不让 caller 处理无效 taskId）
+     * - 错误 / 缺失一律 graceful 返回 null（event dispatch 不被阻塞）
+     *
+     * @returns taskId（如有 ready 绑定）；null 表示无绑定、缺 sessionComponent 或抛错
+     */
+    private resolveChatTaskBinding;
+    /**
+     * 卸载所有已加载的 plugins
+     */
+    private unloadPlugins;
+    /**
+     * 把一段流文本按行切分并 dispatch（默认共享 buffer 版本，兼容旧调用/测试）
+     */
+    private processStream;
+    /**
+     * ★ Task #4339：带**独立行缓冲**的流处理。
+     *
+     * 每个 consume 子进程持有自己的 buffer holder —— 两个进程的 NDJSON 切片
+     * 若共用一个 buffer，会在 chunk 边界上互相错拼出坏行。
+     *
+     * @param opts.jsonLinesOnly true 时只 dispatch `{` 开头的完整行（stderr 用，
+     *        该流里混着 `[event] ...` 状态信息）。注意判断是在**拼完整行之后**做的，
+     *        所以跨 chunk 的 JSON 也能正确还原。
+     */
+    private processStreamWith;
+    /**
+     * 逐行 dispatch。handleEvent 是 async（Task #4023 注入 parentTaskId 需要
+     * await binding 查询），但这里不能阻塞 stream 读取 —— fire-and-forget，
+     * 错误由 handleEvent 自己的 try/catch + span.end() 兜底。
+     */
+    private dispatchLines;
+    private handleEvent;
+    /**
+     * 处理 card.action.trigger 事件（Task #4331）
+     *
+     * 流程：
+     *   1. 解析 event.action_value（JSON 字符串）拿到 { action, taskId }
+     *   2. 调 handleCardAction（建群/解散群 + 写 task.context + 渲染新卡片）
+     *   3. 用 event.token 调 lark-cli api POST /open-apis/interactive/v1/card/update patch 原卡片
+     *      （飞书要求用 token 即时 patch，30min 有效）
+     *
+     * ★★ 如何真正收到 card.action.trigger（Task #4339 修正）★★
+     *
+     * 旧注释写的是「把 command 改成
+     * `lark-cli event consume 'im.message.receive_v1,card.action.trigger' --as bot`」
+     * —— 这是**错的**：lark-cli `event consume` 只接受恰好一个 EventKey，
+     * 逗号形式会 `unknown EventKey` 并 **exit 2**，整个 event-source 变 error。
+     *
+     * 正确做法：在 EventSource config 里配置 `eventKeys` 数组
+     * （一个 key 一个子进程，共享同一个 bus daemon）：
+     *
+     *   {
+     *     "type": "lark-cli",
+     *     "profile": "tongzhuli",
+     *     "eventKeys": ["im.message.receive_v1", "card.action.trigger"]
+     *   }
+     *
+     * 且必须先在飞书开发者后台「事件与回调 → 回调配置」里开启 card.action.trigger，
+     * 否则 consumer 能 ready 但永远收不到事件。
+     * 详见 reports/2026-10-19-lark-cli-multi-event-consume-research.md
+     */
+    private handleCardActionEvent;
+    /**
+     * 用飞书 token 直接 patch 卡片（30min 有效，最多 2 次）
+     *
+     * 飞书 API: POST /open-apis/interactive/v1/card/update
+     *
+     * ★ Task #4337 Bug B fix + refactor：
+     *   - 抽出为 module-level exported function `patchCardByLarkCli`（可独立测试 cmd 字符串）
+     *   - 删掉 `--yes`（lark-cli 1.0.96 `api` 子命令不支持 `unknown flag "--yes"`）
+     */
+    private patchCardByToken;
+    /**
+     * 从 rawEvent 中提取 userId
+     *
+     * ★ Task #3987 后续修复：兼容 lark-cli `event consume` 的简化格式
+     *   - 嵌套格式: event.event.sender.sender_id.open_id
+     *   - 简化格式: event.sender_id（顶层字符串）
+     */
+    private extractUserId;
+    /**
+     * 构建 EnvReplyChannel
+     */
+    private buildReplyChannel;
+    /**
+     * 使用 lark-cli 发送消息
+     */
+    private sendLarkMessage;
+}
+/**
+ * LarkCli Handler
+ */
+export declare const larkCliHandler: EventSourceHandler;
+/**
+ * 用飞书 token 直接 patch 卡片（30min 有效，最多 2 次）
+ *
+ * 飞书 API: POST /open-apis/interactive/v1/card/update
+ *
+ * ★ Task #4337 Bug B fix：
+ *   - 删掉 `--yes`（lark-cli 1.0.96 `api` 子命令不支持，会报 `unknown flag "--yes"`）
+ *   - 抽出为 module-level exported function 便于独立测试 cmd 字符串
+ *
+ * @param token 飞书提供的 30min 有效 token（事件里带的 ctoken_xxx）
+ * @param card 新的卡片 payload（来自 buildTaskCard 的输出）
+ * @param profile lark-cli profile（可选）
+ */
+export declare function patchCardByLarkCli(token: string, card: any, profile?: string): Promise<void>;
+/**
+ * 所有内置 Handler
+ */
+export declare const builtInHandlers: EventSourceHandler[];
+export { timerHandler };
+export { bountyIMHandler };
+export { bountyCliHandler };
+/**
+ * 根据类型获取内置 Handler
+ */
+export declare function getBuiltInHandler(type: string): EventSourceHandler | undefined;

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

@@ -0,0 +1,110 @@
+/**
+ * EventStore — ESPlugin v2 Phase 1（Task #4042）
+ *
+ * 持久化 trigger event，让 ES plugin 能：
+ *   1. emitTriggerEvent(payload) → 返回 triggerEventId 并落库
+ *   2. getEventById(id) → 主 agent 处理 notify event 时反查 ES info（chatId / messageId / senderId）
+ *   3. getRecentEvents(esType, senderId, limit) → 多轮对话上下文
+ *
+ * 设计目标：
+ *   - 同步 API（better-sqlite3 / bun:sqlite 都是同步的，wrap 成 async 给上层调用方便）
+ *   - 单库 / 单表 / 1 索引（开销最小）
+ *   - 跑 bun:test < 10ms p95（warm）
+ *
+ * 向后兼容：
+ *   - 不引入运行时依赖（沿用 core 现有的 sqlite 兼容层，与 span-storage 同源）
+ *   - 不修改现有任何 schema
+ */
+/**
+ * Trigger event 元数据（来自 ES 原始 event）。
+ *
+ * 故意写得比 EventMetadata 更宽：因为不同 ES（lark / bounty-im / timer / cron）
+ * 元数据形状不同，store 不做形状校验，仅做 round-trip。
+ */
+export interface TriggerEventMetadata {
+    /** 事件类型（im.message.receive_v1 / cron.tick / ...）*/
+    eventType?: string;
+    /** 发送方 app ID（lark 用）*/
+    appId?: string;
+    /** 渠道 chat ID（lark / bounty-im 用）*/
+    chatId?: string;
+    /** 渠道类型（p2p / group / channel）*/
+    chatType?: string;
+    /** 原始消息 ID（lark 用，im +messages-reply 关联回原 user query）*/
+    messageId?: string;
+    /** 消息类型（text / image / ...）*/
+    messageType?: string;
+    /** 发送方 user ID（lark open_id / bounty user_id）*/
+    senderId?: string;
+    /** 租户 key（多租户场景）*/
+    tenantKey?: string;
+    /** 其他 ES-specific 元数据 */
+    [key: string]: unknown;
+}
+/**
+ * Trigger event 输入（emitTriggerEvent 调用方传）
+ */
+export interface TriggerEventInput {
+    /** 发送方 ID（必填，用于 getRecentEvents 查询）*/
+    senderId: string;
+    /** 提取出的文本内容（用于上层 LLM prompt）*/
+    text?: string;
+    /** 元数据（chatId / messageId / ...）*/
+    metadata: TriggerEventMetadata;
+    /** ES 原始 event 对象（可选，留档用）*/
+    rawEvent?: unknown;
+}
+/**
+ * 持久化后的 event（getEventById / getRecentEvents 返回）
+ */
+export interface PersistedEvent {
+    eventId: string;
+    esType: string;
+    senderId: string;
+    text: string | null;
+    /** JSON 反序列化后的元数据 */
+    metadata: TriggerEventMetadata;
+    /** 原始 event 对象（JSON 反序列化）*/
+    rawEvent: unknown;
+    createdAt: number;
+}
+/**
+ * EventStore 接口
+ */
+export interface EventStore {
+    insertTriggerEvent(input: TriggerEventInput, esType: string): Promise<string>;
+    getEventById(eventId: string): Promise<PersistedEvent | null>;
+    getRecentEvents(esType: string, senderId: string, limit: number): Promise<PersistedEvent[]>;
+}
+/**
+ * EventStore 配置
+ */
+export interface EventStoreOptions {
+    /** SQLite 数据库路径（必填）*/
+    dbPath: string;
+}
+declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS event_store (\n  event_id   TEXT PRIMARY KEY,\n  es_type    TEXT NOT NULL,\n  sender_id  TEXT NOT NULL,\n  text       TEXT,\n  metadata   TEXT NOT NULL,\n  raw_event  TEXT,\n  created_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_es_sender_time\n  ON event_store (es_type, sender_id, created_at DESC);\n";
+/**
+ * 默认 EventStore 实现（SQLite）
+ */
+export declare class EventStoreImpl implements EventStore {
+    private readonly db;
+    private readonly insertStmt;
+    private readonly getByIdStmt;
+    private readonly recentStmt;
+    constructor(options: EventStoreOptions);
+    insertTriggerEvent(input: TriggerEventInput, esType: string): Promise<string>;
+    getEventById(eventId: string): Promise<PersistedEvent | null>;
+    getRecentEvents(esType: string, senderId: string, limit: number): Promise<PersistedEvent[]>;
+    /**
+     * 关闭数据库（测试 / graceful shutdown 用）
+     */
+    close(): void;
+}
+export { SCHEMA_SQL as EVENT_STORE_SCHEMA_SQL };
+/** 注册进程内共享 EventStore（cli wiring / 测试用） */
+export declare function setSharedEventStore(store: EventStore | null): void;
+/** 获取进程内共享 EventStore（未注册返回 null） */
+export declare function getSharedEventStore(): EventStore | null;
+/** 清空共享单例（仅测试用） */
+export declare function resetSharedEventStore(): void;

package/dist/env/event-source/idempotency-key.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview 共享 idempotency-key 派生器（Task #4137 P1）
+ *
+ * 用途：把"出站消息 idempotency-key 派生"逻辑抽出来，让：
+ *     - PerTaskGroupChatPlugin.buildSendToChatArgs
+ *     - LarkCliTaskNotifyHook.buildReplyArgs
+ *   共用同一份派生规则（hash 来源 / 截断 / 兜底）。
+ *
+ * 设计：飞书 lark-cli `im +messages-send --idempotency-key <key>` 限制 ≤ 50 字符，
+ * 因此派生后必须截断。Bun.hash 默认无依赖，hash 命中率高。
+ */
+/**
+ * 派生 ≤50 字符的 idempotency-key
+ *
+ * @param parts - 拼接来源（如 chatId / taskId / type / content 截断 / messageId）
+ *               任意 string | number | undefined 都会被 stringify 拼到 source 串
+ * @returns ≤ 50 字符的 idempotency-key（"roy-" 前缀）
+ */
+export declare function deriveIdempotencyKey(parts: Array<string | number | undefined | null>): string;

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

@@ -0,0 +1,15 @@
+/**
+ * EventSource 模块入口
+ *
+ * 导出所有 EventSource 相关的类型、类和函数
+ */
+export type { EventSourceStatus, EventSourceType, EventSourceConfig, EventMetadata, RecommendedAction, ReplyChannel, EventSourceEventPayload, EventSourceEvent, EventSourceEventHandler, EventSourceStatusChangeEvent, EventSourcePersistenceConfig, EventSourceInstance, EventSourceHandler, EventSourceInitHook, EventSourceComponentInterface, EventSourceAgentHandlerConfig, } from "./types";
+export { EventSourceInitHooks } from "./types";
+export { BUILT_IN_EVENT_SOURCE_TYPES, BUILT_IN_EVENT_SOURCE_TYPE_LIST } from "./types";
+export { isBuiltInEventSourceType, isValidEventSourceType, getDefaultConfigForType, validateEventSourceConfig, } from "./types";
+export { EventSourceComponent } from "./event-source-component";
+export { EventStoreImpl, setSharedEventStore, getSharedEventStore, resetSharedEventStore, } from "./event-store";
+export type { EventStore, TriggerEventInput, TriggerEventMetadata, PersistedEvent, EventStoreOptions, } from "./event-store";
+export { larkCliHandler, timerHandler, bountyIMHandler, builtInHandlers, getBuiltInHandler, extractMetadata, } from "./event-source-handlers";
+export { TimerInstance } from "./timer-handler";
+export { BountyIMInstance, buildDefaultBountyIMSystemPrompt, resolveBountyIMSystemPrompt } from "./bounty-im-handler";

package/dist/env/event-source/index.js

@@ -11,7 +11,7 @@ import {
   larkCliHandler,
   resolveBountyIMSystemPrompt,
   timerHandler
-} from "../../shared/@ai-setting/roy-agent-core-ezgsem94.js";
+} from "../../shared/@ai-setting/roy-agent-core-ph5qbqcx.js";
 import {
   BUILT_IN_EVENT_SOURCE_TYPES,
   BUILT_IN_EVENT_SOURCE_TYPE_LIST,
@@ -22,7 +22,7 @@ import {
   validateEventSourceConfig
 } from "../../shared/@ai-setting/roy-agent-core-ck60j1q9.js";
 import"../../shared/@ai-setting/roy-agent-core-rnwr39b0.js";
-import"../../shared/@ai-setting/roy-agent-core-pkpkctvf.js";
+import"../../shared/@ai-setting/roy-agent-core-hch2geta.js";
 import {
   EventStoreImpl,
   getSharedEventStore,