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

package/dist/config/config-protection.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Config protection utilities — ~/.roy-agent 配置事故系统性防护（Task #5194）
+ *
+ * 背景：2026-11-07/11-08 连续三起 ~/.roy-agent 配置被覆盖/重置事故
+ * （测试覆盖 ×2、daily-summary 副本手动覆盖 ×1）。路径级守卫
+ * （Task #5181 测试隔离）已封死测试写路径，但内容级覆盖
+ * （合法写入者写坏内容）无法靠路径守卫防住。
+ *
+ * 三道护栏：
+ *   1. snapshotConfigDir  — 写前快照，保留最近 N=10 份，可回滚
+ *   2. appendAuditLog     — 写入审计（谁/何时/什么），排查不再考古
+ *   3. checkSourceCountDrop — 源数骤降 >30% 检测（fail-safe 拒绝覆盖）
+ */
+/** 需要快照保护的关键配置文件 */
+export declare const PROTECTED_CONFIG_FILES: readonly ["config.jsonc", "auth.json", "event-sources.json", "wecom-credentials.json"];
+/** 快照保留数量 */
+export declare const SNAPSHOT_KEEP = 10;
+/** 文件名安全的时间戳（如 2026-11-08T21-37-13-512Z） */
+export declare function snapshotTimestamp(d?: Date): string;
+/**
+ * 对 configDir 下的关键配置文件做一次快照。
+ *
+ * - 只快照存在的文件（缺失跳过，不报错）
+ * - configDir 不存在时返回 null（不抛错）
+ * - 快照后清理最旧快照，保留最近 SNAPSHOT_KEEP 份
+ *
+ * @returns 快照目录路径；configDir 不存在时返回 null
+ */
+export declare function snapshotConfigDir(configDir: string, now?: Date): string | null;
+/** 列出现有快照目录（按时间戳名排序，旧→新） */
+export declare function listSnapshots(configDir: string): string[];
+/** 单条审计记录 */
+export interface AuditEntry {
+    /** ISO 时间戳 */
+    ts: string;
+    /** 写入进程 pid */
+    pid: number;
+    /** 被写文件名 */
+    file: string;
+    /** 动作（如 save / pre-save-snapshot / drop-blocked） */
+    action: string;
+    /** 补充信息 */
+    detail?: string;
+}
+/**
+ * 追加一条审计记录到 <configDir>/audit.log（每行一个 JSON）。
+ * 失败静默（审计绝不能反过来弄坏配置写入主流程）。
+ */
+export declare function appendAuditLog(configDir: string, entry: Omit<AuditEntry, "ts" | "pid">): void;
+/** 读取审计日志（解析失败的行跳过） */
+export declare function readAuditLog(configDir: string): AuditEntry[];
+/** 源数骤降检查结果 */
+export interface SourceDropCheck {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * 源数骤降检测（Task #5188 P1 建议）。
+ *
+ * 规则：previousCount 合法（>0）且 newCount 下降超过 30% ⇒ 拒绝。
+ * previousCount <= 0（无盘上配置/读取失败）时放行。
+ *
+ * @param previousCount 磁盘上现有源数
+ * @param newCount 本次要写入的源数
+ */
+export declare function checkSourceCountDrop(previousCount: number, newCount: number): SourceDropCheck;
+/**
+ * 读取磁盘上 event-sources.json 的源数；文件缺失/损坏返回 -1。
+ */
+export declare function readSourceCountFromDisk(configPath: string): number;
+/** utimes helper for tests (exported so tests need no require hack) */
+export declare function setTimestamps(p: string, d: Date): void;
+/**
+ * 通用护栏写入包装（Task #5194 opencodego review MAJOR-1）。
+ *
+ * 背景：护栏原先只接 event-sources.json 一个写入口，
+ * config.jsonc / auth.json 的写入路径（fallback-model-command、
+ * cli app-config-io）零接线 ⇒ 事故 1/2 的主要目标文件裸奔。
+ *
+ * 语义：写前快照（可回滚）→ 执行 writeFn → 写后审计。
+ * - writeFn 抛错 ⇒ 返回 false 并记 write-failed 审计（错误原样上抛由调用方决定）
+ * - 快照/审计失败不阻断写入主流程（护栏绝不能弄坏配置写入）
+ *
+ * @param configDir 配置目录（如 ~/.roy-agent）
+ * @param file 被写文件名（如 config.jsonc）
+ * @param writeFn 实际写入动作（同步）
+ * @returns true=写入成功；false=写入抛错
+ */
+export declare function guardConfigWrite(configDir: string, file: string, writeFn: () => void): boolean;

package/dist/config/index.d.ts

@@ -2,3 +2,4 @@ export { type ConfigSource, type ConfigSourceType, type ConfigChangeEvent, type
 export { FileSource, type FileSourceOptions } from "./file-source";
 export { EnvSource, type EnvSourceOptions } from "./env-source";
 export { parseJSONC, parseJSONCWithEnv, parseJSONCWithProtocols, substituteEnvVars, substituteProtocolRefs, } from "./config-parser";
+export { guardConfigWrite, snapshotConfigDir, appendAuditLog, readAuditLog, checkSourceCountDrop, readSourceCountFromDisk, PROTECTED_CONFIG_FILES, type AuditEntry, type SourceDropCheck, } from "./config-protection";

package/dist/config/index.js

@@ -13,6 +13,15 @@ import {
   substituteEnvVars,
   substituteProtocolRefs
 } from "../shared/@ai-setting/roy-agent-core-adg9ghbt.js";
+import {
+  PROTECTED_CONFIG_FILES,
+  appendAuditLog,
+  checkSourceCountDrop,
+  guardConfigWrite,
+  readAuditLog,
+  readSourceCountFromDisk,
+  snapshotConfigDir
+} from "../shared/@ai-setting/roy-agent-core-2stt4rp5.js";
 import"../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../shared/@ai-setting/roy-agent-core-7hh0brvs.js";
 import"../shared/@ai-setting/roy-agent-core-pgvcf91v.js";
@@ -27,9 +36,16 @@ import"../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 export {
   substituteProtocolRefs,
   substituteEnvVars,
+  snapshotConfigDir,
+  readSourceCountFromDisk,
+  readAuditLog,
   parseJSONCWithProtocols,
   parseJSONCWithEnv,
   parseJSONC,
+  guardConfigWrite,
+  checkSourceCountDrop,
+  appendAuditLog,
+  PROTECTED_CONFIG_FILES,
   MemorySource,
   FileSource,
   EnvSource,

package/dist/env/agent/agent-component.d.ts

@@ -240,6 +240,34 @@ export declare class AgentComponent extends BaseComponent {
     private abortControllers;
     private defaultTools;
     private doomLoopCaches;
+    /**
+     * ★ Task #5224 — session-scope cache snapshot（**内存级**，key = sessionId）。
+     *
+     * ## 为什么改成内存级
+     *
+     * 旧实现把快照持久化到 `session.metadata.cacheSnapshot`，带来三个问题：
+     *
+     * 1. **体积爆炸**：快照 = 整份 systemPrompt（含展开后的 memory），
+     *    实测单 session metadata ≈ 102 KB —— `packages/cli/src/commands/shared/chat-session.ts:48`
+     *    自述这是本地 `sessions.db` 膨胀到 3.3 GB 的直接原因。
+     * 2. **跨进程时间差**：进程重启后复用的旧快照创建于渠道 prompt 引入之前，
+     *    且失效检测只看 memory.md mtime → 旧快照被判「新鲜」永久复用
+     *    → 渠道 prompt 永远进不了 LLM system message（Task #5210/#5217 根因）。
+     * 3. **需要一堆补丁兜底**：fix③ 追加 + includes 判重（Task #5223）
+     *    都是为了在「持久化 + 复用」模型下把渠道 prompt 塞回去。
+     *
+     * ## 新语义（用户确认）
+     *
+     * - 快照是**进程内**的一次性构建产物：session 生命周期内构建一次，之后一直用。
+     * - **不持久化** sessions.db ⇒ 进程重启后全部重建（自然拿到最新 memory）。
+     * - **渠道 prompt 在构建时注入**（唯一注入点）⇒ 无需任何复用轮补丁。
+     * - **不做失效检测**（`_isMemorySnapshotStale` 已删除）⇒ session 内 memory
+     *   变更不生效（冻结语义），新 session 自然用最新 memory。
+     *
+     * 生命周期 = AgentComponent 实例 = 生产环境进程生命周期
+     * （`environment.service.ts` 只 `new AgentComponent()` 一次）。
+     */
+    private _cacheSnapshots;
     /**
      * Task #4623 — per-run fallback state.
      *
@@ -491,36 +519,28 @@ export declare class AgentComponent extends BaseComponent {
      * 这里只需要构建当前请求的消息，不重复添加
      */
     /**
-     * 【Task #2744】session-scope cache snapshot 加载/创建/持久化
+     * 【Task #2744 / #5224】session-scope cache snapshot —— **内存级**构建/复用
      *
-     * 设计目标：把 systemPrompt（{{memory}} 已替换）和 additionInfo 绑定到 session 生命周期，
-     * first-run 计算一次并持久化到 session.metadata.cacheSnapshot，后续 _run 直接复用
+     * 设计目标：把 systemPrompt（{{memory}} 已替换 + **构建时注入的渠道 prompt**）
+     * 和 additionInfo 绑定到 session 生命周期，构建一次后一直用
      * → 字节级一致 → LLM prompt cache 命中。
      *
+     * ★ Task #5224 变更（用户确认的最终设计）：
+     * - 存储：**内存 Map**（`_cacheSnapshots`，key = sessionId），**不持久化** sessions.db
+     *   ⇒ 不再把整份 systemPrompt（~102KB）写进 session 行（本地库膨胀主因）
+     * - 复用：同 sessionId 直接命中 Map；**不做失效检测**
+     *   （`_isMemorySnapshotStale` 已删除）⇒ session 内 memory 变更不生效（冻结）
+     * - 注入：渠道 prompt 在**构建时**并入快照（唯一注入点）
+     *   ⇒ 不再需要 fix③ 复用轮追加 + includes 判重补丁
+     *
      * @returns
      * - snapshot: 冻结的 { systemPrompt, additionInfo, snapshotAt } 快照
      * - systemPromptOverride: 如果 snapshot 命中，覆盖调用方的 resolvedSystemPrompt
      *   （值是 snapshot.systemPrompt，命中时与 snapshot.systemPrompt 相同）
      *
-     * 错误处理：所有 I/O 失败均降级为"返回 null"（调用方走 fallback 路径），
-     * 不阻塞 run。
+     * 错误处理：所有异常均降级为"返回 null"（调用方走 fallback 路径），不阻塞 run。
      */
     private _loadOrCreateCacheSnapshot;
-    /**
-     * 【Task #4813】B1 mtime 失效检测：快照是否因 memory 文件变化而过期
-     *
-     * 返回 null = 快照仍有效（可复用）；返回字符串 = 过期原因（用于日志）。
-     *
-     * 兼容迁移：旧快照（Task #4813 之前持久化）无 memoryStat 字段 → 视为过期。
-     */
-    private _isMemorySnapshotStale;
-    /**
-     * 【Task #4813】采集各 memory 文件的 mtime（按 MemoryComponent 配置的
-     * memoryPaths × memoryFile），供快照失效检测使用。
-     *
-     * 文件不存在 → 记为 0（删除后重拍语义）；memory component 缺失 → 全 0。
-     */
-    private _collectMemoryStat;
     /**
      * 【Task #2744】无 sessionId 时的 {{memory}} fallback 替换
      *
@@ -535,7 +555,8 @@ export declare class AgentComponent extends BaseComponent {
      * currentTaskId 是否成功注入到 LLM 上下文
      *
      * Task #2744 (session-scope cache optimization):
-     * 如果 ctx._cacheSnapshot 存在（由 AgentComponent._run 在 first-run 时持久化到
+     * 如果 ctx._cacheSnapshot 存在（由 AgentComponent._run 在 first-run 时构建到
+     * 内存快照 `_cacheSnapshots`，★ Task #5224 起不再持久化到
      * session.metadata.cacheSnapshot），则返回 snapshot 的 additionInfo，**跨多轮
      * 保持字节级一致** —— 这是 LLM prompt cache 命中的前提。
      *

package/dist/env/agent/agent-component.js

@@ -7,8 +7,8 @@ import {
   filterToolsByAgent,
   parseToolList,
   toLLMMessage
-} from "../../shared/@ai-setting/roy-agent-core-9vhq7fvv.js";
-import"../../shared/@ai-setting/roy-agent-core-v85n42ve.js";
+} from "../../shared/@ai-setting/roy-agent-core-dkrvmjsh.js";
+import"../../shared/@ai-setting/roy-agent-core-ze5cqpf2.js";
 import"../../shared/@ai-setting/roy-agent-core-jvv2h3d6.js";
 import"../../shared/@ai-setting/roy-agent-core-ed233k5z.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";

package/dist/env/agent/index.js

@@ -4,8 +4,8 @@ import {
 import {
   AgentComponent,
   AgentComponentConfigSchema
-} from "../../shared/@ai-setting/roy-agent-core-9vhq7fvv.js";
-import"../../shared/@ai-setting/roy-agent-core-v85n42ve.js";
+} from "../../shared/@ai-setting/roy-agent-core-dkrvmjsh.js";
+import"../../shared/@ai-setting/roy-agent-core-ze5cqpf2.js";
 import"../../shared/@ai-setting/roy-agent-core-jvv2h3d6.js";
 import"../../shared/@ai-setting/roy-agent-core-ed233k5z.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";

package/dist/env/agent/types.d.ts

@@ -227,24 +227,28 @@ export interface HookContext {
     /**
      * Task #2744: session-scope cache snapshot (internal use)
      *
-     * 持久化在 session.metadata.cacheSnapshot，由 AgentComponent._run 在 first-run
-     * 创建并透传给 buildMessages。buildMessages 使用 snapshot 的 additionInfo（而非
-     * 每轮重读 ctx.context.additionInfo）以保证 system prompt 字节级一致 → LLM
-     * prompt cache 命中。
+     * ★ Task #5224 — 快照改为**内存级**（`AgentComponent._cacheSnapshots`，
+     *   key=sessionId），**不再持久化**到 session.metadata.cacheSnapshot。
+     *   由 AgentComponent._run 在 first-run 创建并透传给 buildMessages。
+     *   buildMessages 使用 snapshot 的 additionInfo（而非每轮重读
+     *   ctx.context.additionInfo）以保证 system prompt 字节级一致 → LLM
+     *   prompt cache 命中。
      *
-     * - systemPrompt: 含 {{memory}} 替换后的最终字符串
+     * - systemPrompt: 含 {{memory}} 替换后的最终字符串（**含构建时注入的渠道 prompt**）
      * - additionInfo: first-run 时的 additionInfo（冻结）
-     * - snapshotAt: 持久化时间戳
+     * - snapshotAt: 构建时间戳
      *
-     * 第三方代码不应直接修改此字段。如需强制重建 snapshot，可通过
-     * sessionComponent.update(sessionId, { metadata: { cacheSnapshot: null } }) 清除。
+     * ⚠️ 本字段**仅是运行时透传载体**：它的值只来自
+     *   `_loadOrCreateCacheSnapshot` 的内存 Map，**既不从 session.metadata 读取，
+     *   也不写入 session.metadata** —— 不要把它当成「可持久化到 session 行」的句柄。
+     *
+     * 第三方代码不应直接修改此字段。快照重建条件：进程重启（内存态全失）
+     * 或换用新的 sessionId。
      */
     _cacheSnapshot?: {
         systemPrompt: string;
         additionInfo: string;
         snapshotAt: number;
-        /** 【Task #4813】B1 mtime 失效检测：首拍时各 memory 文件的 mtime（ms） */
-        memoryStat?: MemorySnapshotStat;
     };
     /** 执行上下文（可直接修改属性） */
     context: AgentContext;
@@ -320,13 +324,29 @@ export type AgentType = "primary" | "sub" | "summary";
  * - globalMtime: global memory.md 的 mtime（ms）；文件不存在记 0
  * - projectMtime: project memory.md 的 mtime（ms）；文件不存在记 0
  *
- * 复用快照前比对当前 mtime，不一致 → 快照过期 → 重拍。
- * 旧快照无此字段 → 视为过期（一次性迁移重拍）。
+ * ⚠️ 【Task #5224】**已停用**（保留类型仅为向后兼容，不破坏公开导出面）：
+ * 快照改内存级后，失效检测（`_isMemorySnapshotStale`）被移除 —— session
+ * 生命周期内快照冻结，新 session / 进程重启自然重建并拿到最新 memory。
  */
 export interface MemorySnapshotStat {
     globalMtime: number;
     projectMtime: number;
 }
+/**
+ * ★ Task #5224 — session-scope cache snapshot（内存级）。
+ *
+ * 构建一次、session 生命周期内冻结使用；不持久化到 sessions.db。
+ *
+ * - systemPrompt: 含 {{memory}} 替换后的最终字符串，
+ *   **且含构建时注入的渠道 prompt**（唯一注入点）
+ * - additionInfo: 构建时的 additionInfo（冻结 → 字节级一致 → prompt cache 命中）
+ * - snapshotAt: 构建时间戳
+ */
+export interface CacheSnapshot {
+    systemPrompt: string;
+    additionInfo: string;
+    snapshotAt: number;
+}
 /**
  * Agent 状态
  */

package/dist/env/error-reply.d.ts

@@ -111,6 +111,12 @@ export interface FailureReplyChannelLike {
     profile?: string;
     appId?: string;
     userId?: string;
+    /**
+     * Task #5311：渠道自定义参数（event-source ReplyChannel.params 的透传）。
+     * 企微通道用 `params.sourceId`（WS fallback 实例定位）与
+     * `params.reqId`（WS 被动回帧）。lark 通道不读它。
+     */
+    params?: Record<string, unknown>;
 }
 export interface NotifyReactFailureOptions {
     /** 触发 React 中断的错误（任意类型，内部会做类型安全处理） */

package/dist/env/error-reply.js

@@ -8,7 +8,7 @@ import {
   getFailureRuleIds,
   humanizeRetryAfter,
   notifyReactFailure
-} from "../shared/@ai-setting/roy-agent-core-6cy43nss.js";
+} from "../shared/@ai-setting/roy-agent-core-rykf7c04.js";
 import"../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../shared/@ai-setting/roy-agent-core-m880qz3y.js";
 import"../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";

package/dist/env/event-source/bounty-im-handler.d.ts

@@ -208,7 +208,15 @@ export declare class BountyIMInstance implements EventSourceInstance {
      * 优先用 config.systemPrompt，否则用默认 prompt。
      * 该 prompt 会透传到 EventSourceEvent.metadata.systemPrompt，
      * 由 run.ts 在 dispatch env event 时注入到 agent system prompt。
+     *
+     * ★ ES-M1（Task #5144 / 方案 M2）：结果缓存为实例字段 ——
+     * 构造一次，每条消息事件不再重新 resolve。同一渠道输出
+     * 逐字节稳定（resolveBountyIMSystemPrompt 只读 config，
+     * 本就确定；缓存进一步杜绝未来混入事件级变量导致的字节漂移，
+     * 保护 LLM prompt cache 前缀一致性）。
      */
+    private cachedSystemPrompt?;
+    private systemPromptResolved;
     private getCurrentSystemPrompt;
     getStatus(): EventSourceStatus;
     start(): Promise<void>;

package/dist/env/event-source/es-command.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Task #5302 — `es` command（eventsource 管理斜杆命令）
+ *
+ * 用户需求（飞书明令 2026-11-11 10:11）：
+ *   1. 斜杆命令 `/es add|list|del|mod` 管理 eventsource
+ *   2. 飞书 `##command##: es <sub>` 触发（复用 Task #4722 command 子系统）
+ *   3. interactive TUI 也要支持（见 packages/cli/src/tui-solid/interactive-slash-commands.ts）
+ *
+ * ## 数据面
+ *
+ * 直接读写 `~/.roy-agent/event-sources.json`（EventSourceComponent
+ * 的持久化文件，格式 `{version, sources: EventSourceConfig[]}`）。
+ *
+ * 为什么不走组件实例：command 子系统是**无状态纯函数**（es 前端 /
+ * CLI / interactive 三个前端共享），拿不到运行中的 EventSourceComponent；
+ * 且 component.register() 会触发 saveConfig() 竞态。直接文件读写 +
+ * 写后重读校验，与 reset-command.ts 同级简单度。
+ *
+ * ⚠️ 与运行中 daemon 的关系：本命令改的是**磁盘配置**。运行中的
+ * EventSourceComponent 不会自动 reload（它只在启动时 loadConfig），
+ * 改完需 `##command##: reset` 重启进程生效 —— 在输出里明确提示。
+ *
+ * ## 安全
+ *
+ * - add 重名拒绝（与 component.register 一致）
+ * - mod 只允许白名单字段（enabled/name/interval/cron/profile）；
+ *   command/url 属于命令注入面，mod 明确不允许（需 del + add）
+ * - 写失败（磁盘/权限）→ ok:false，不静默
+ *
+ * ## 已知限制
+ *
+ * 参数按空白切分（飞书 `##command##:` 与 interactive `/es` 同规则），
+ * 因此含空格的值（如 cron 表达式）无法经这两个前端写入；
+ * CLI 侧可用引号传入。需要时用 CLI 或手工编辑 event-sources.json。
+ */
+import type { CommandDefinition } from "./command-registry";
+/** 从 configPath（config.jsonc）推导同目录的 event-sources.json */
+export declare function resolveEsFilePath(configPath?: string): string;
+export declare const esCommand: CommandDefinition;

package/dist/env/event-source/es-plugins.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Task #5193 — EventSource 插件加载共享模块
+ *
+ * ## 为什么抽出来
+ *
+ * 插件机制（BUILT_IN_PLUGIN_FACTORIES / getPluginHookPoints /
+ * registerPluginHooks）原来**只存在于 LarkCliInstance**（私有方法）。
+ * WecomCliInstance 要加载 WecomTaskNotifyPlugin 就得复用同一套逻辑，
+ * 但两者是独立的 class —— 直接复制会 drift（Task #4946「声明 ≠ 实现」
+ * 的教训：handleRule.plugins 配在 wecom 源上是 dead config）。
+ *
+ * 本模块把「按名字实例化 + 注册 hook 点」抽成**纯函数**，
+ * LarkCliInstance 与 WecomCliInstance 都可以调（lark 侧后续可迁移，
+ * 本次不动 lark 行为）。
+ *
+ * ## Hook 注册语义（与 LarkCliInstance.registerPluginHooks 一致）
+ *
+ * - Hook 模式（有 execute 无 hookPoint）→ 按 getPluginHookPoints
+ *   白名单（5 个 task hook 点）逐点注册
+ * - 显式 hookPoint → 单点注册
+ * - BasePlugin 模式（有 init）→ 调 init（registerHook 回调注册）
+ * - pluginEnabled 检查 key = `${sourceId}:${pluginName}`
+ */
+/** 插件工厂配置（工厂收到的最小面） */
+export interface PluginFactoryConfig {
+    sourceId: string;
+    pluginName: string;
+    [key: string]: unknown;
+}
+/**
+ * 内置插件工厂注册表。
+ *
+ * ⚠️ 与 event-source-handlers.ts 的 BUILT_IN_PLUGIN_FACTORIES **同源**：
+ * 该表在 handlers 里定义（静态 import 让 bundler 内联），本模块
+ * 通过注入函数引用避免循环依赖 —— 调用方（handlers / wecom handler）
+ * 传入自己的工厂表。
+ */
+export type PluginFactory = (cfg: PluginFactoryConfig) => any;
+/**
+ * 内置插件工厂注册表（单一真相源，Task #5193 迁入）。
+ *
+ * ⚠️ 原 BUILT_IN_PLUGIN_FACTORIES 在 event-source-handlers.ts，
+ * 迁到本模块让 wecom-cli-handler 也能复用（避免循环依赖）。
+ * handlers 侧改为引用本表，行为零变化。
+ */
+export declare const BUILT_IN_PLUGIN_FACTORIES: Record<string, PluginFactory>;
+/** wecom 侧工厂表（当前与全局同源；将来可裁剪 lark 专属插件） */
+export declare function getWecomPluginFactories(): Record<string, PluginFactory>;
+/**
+ * 获取插件的 hook 点列表（与 LarkCliInstance.getPluginHookPoints 同语义）
+ */
+export declare function getPluginHookPointsShared(plugin: any): string[];
+/**
+ * 把插件实例的 hooks 注册到 globalHookManager。
+ *
+ * @returns 注册的 hook 点列表（诊断用）
+ */
+export declare function registerPluginHooksShared(plugin: any, pluginName: string, sourceId: string): string[];
+/**
+ * 按名字实例化内置插件（工厂表由调用方注入）。
+ *
+ * @returns 插件实例；未知名字 / 实例化失败 → null
+ */
+export declare function importPluginShared(name: string, factories: Record<string, PluginFactory>, pluginConfig?: Record<string, unknown>): any | null;
+/**
+ * 注销插件注册的所有 hooks（stop 时调用）
+ */
+export declare function unregisterPluginHooksShared(pluginName: string, hookPoints: string[]): void;

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

@@ -64,6 +64,21 @@ export declare class EventSourceComponent extends BaseComponent implements Event
     private buffers;
     private configPath;
     private persistenceEnabled;
+    constructor();
+    /**
+     * 测试环境守卫（Task #5181，2026-11-07/11-08 事故防再发）
+     *
+     * 事故：测试中实例化 EventSourceComponent 并触发 saveConfig()，
+     * 覆盖了生产 ~/.roy-agent/event-sources.json（10 个真实事件源配置差点丢失）。
+     *
+     * 规则：
+     *   - 测试环境（NODE_ENV=test 或存在 BUN_TEST_WORKER_ID）⇒ persistence=false
+     *     （只内存不落盘，绝不触碰真实 $HOME/.roy-agent/）
+     *   - 显式 opt-out：ROY_AGENT_ES_PERSISTENCE=1 可在测试中强制开启持久化
+     *     （用于守卫自身可测 / 隔离 HOME 的持久化测试）
+     */
+    static isTestEnvironment(): boolean;
+    private applyTestEnvironmentGuard;
     /** ConfigComponent 用于配置管理 */
     private configComponent?;
     /** 配置热更新 watcher 清理函数 */

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

@@ -56,6 +56,49 @@ export declare function buildLarkRecommendedAction(opts: {
     chatId?: string;
     messageId?: string;
 }): RecommendedAction;
+/**
+ * 渠道静态规则章节标题（system prompt 与 lean 卡片互相指认的锚点）
+ */
+export declare const LARK_CHANNEL_PROMPT_SECTION_TITLE = "\u2B50 \u98DE\u4E66\u56DE\u590D\u89C4\u8303\uFF08system prompt \u6CE8\u5165\u7248\uFF09";
+/**
+ * ★ Task #5212（DS review MINOR-3）：飞书 prompt 长度**防御性上限**（单一来源）。
+ *
+ * 两个出口共用同一预算：
+ *   - lean 渠道 system prompt（buildLarkChannelSystemPrompt）
+ *   - legacy recommendedAction.action（buildLarkRecommendedAction）
+ *
+ * ⚠️ 这是**防御性上限**，不是编辑预算：正常小幅扩写仍有余量，
+ * 但「各加一节」式回归会立刻超。改动相关章节前先量长度，
+ * 改完必须跑 lark-channel-system-prompt.test.ts (G) 组守护测试。
+ * （历史：旧 action 模板 ~4486 → profile=tongzhuli 时 4745 → #5164 追加
+ *  文档交付规范段后 4991 → #5212 追加引用上下文段后 5287。）
+ */
+export declare const LARK_PROMPT_LENGTH_BUDGET = 5300;
+/**
+ * 构建飞书渠道级 system prompt（ES-M1 lean 模式核心）。
+ *
+ * 内容 = 渠道静态规则（关键 0/1/2/3 + 禁止 + 成功判定，与旧
+ * recommendedAction 长模板字节级同源）+ profile 渠道约定（开头 2-3 行）。
+ *
+ * **禁止读事件**：入参只有 profile（渠道配置）；同一渠道多次调用
+ * 逐字节一致，这是 LLM prompt cache 前缀稳定的根基。
+ *
+ * 静态规则中的定位占位（replyTo.messageId / replyTo.chatId）语义不变：
+ * system prompt 里写明「具体值取自 recommendedAction.replyTo」。
+ */
+export declare function buildLarkChannelSystemPrompt(opts: {
+    profile?: string;
+}): string;
+/**
+ * 解析 lark-cli 渠道的 systemPrompt（单点构造，只读 config）。
+ *
+ * - lean（默认）：config.systemPrompt（用户配置，若有）+ 渠道静态 prompt；
+ * - legacy（per-source 可回退）：返回 config.systemPrompt 原值
+ *   （未设置则 undefined，与旧版行为一致）。
+ *
+ * 同一 config 多次调用逐字节一致（测试守护）。
+ */
+export declare function resolveLarkChannelSystemPrompt(config: EventSourceConfig): string | undefined;
 /**
  * 提取事件元信息
  *
@@ -156,6 +199,30 @@ export declare class LarkCliInstance implements EventSourceInstance {
     private recentEventIds;
     private readonly DEDUP_WINDOW_MS;
     private readonly DEDUP_MAX_SIZE;
+    /**
+     * ★ ES-M1（Task #5144）：渠道 system prompt 的**实例级缓存**。
+     *
+     * resolveLarkChannelSystemPrompt(config) 只读 config（渠道配置），
+     * 输出对同一渠道是恒定的 —— 缓存到实例字段后：
+     *   1. 每条事件不再重复构造（字符串拼接成本省掉）；
+     *   2. 更重要的是**杜绝字节漂移**：构造函数禁止读 event/rawEvent，
+     *      缓存值天然跨事件逐字节一致 → LLM prompt cache 前缀稳定
+     *      （方案 §4.1 的"单点构造"规则）。
+     * legacy 模式下该字段是 config.systemPrompt（可能 undefined），
+     * 同样缓存一次。
+     */
+    private cachedChannelSystemPrompt?;
+    private channelSystemPromptResolved;
+    /**
+     * 获取本渠道的 systemPrompt（ES-M1，Task #5144）。
+     *
+     * lean 模式（默认）：config.systemPrompt（用户配置，若有）+ 渠道静态 prompt；
+     * legacy 模式：config.systemPrompt 原值（未设置则 undefined）。
+     *
+     * 结果缓存在实例字段（构造一次），供 handleEvent 注入
+     * metadata.systemPrompt → query-executor → AgentComponent 追加。
+     */
+    getChannelSystemPrompt(): string | undefined;
     /**
      * Environment 引用（由 EventSourceComponent.startSource 调用 setEnvironment 注入）
      *
@@ -571,6 +638,7 @@ export { timerHandler };
 export { bountyIMHandler };
 export { bountyCliHandler };
 export { cliCommandHandler } from "./cli-command-handler";
+export { wecomCliHandler } from "./wecom-cli-handler";
 /**
  * 根据类型获取内置 Handler
  */

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

@@ -1,7 +1,10 @@
 import {
+  LARK_CHANNEL_PROMPT_SECTION_TITLE,
+  LARK_PROMPT_LENGTH_BUDGET,
   LarkCliInstance,
   bountyCliHandler,
   bountyIMHandler,
+  buildLarkChannelSystemPrompt,
   buildLarkRecommendedAction,
   builtInHandlers,
   extractCommandText,
@@ -10,14 +13,18 @@ import {
   larkCliHandler,
   patchCardByLarkCli,
   renderRuleNoticeSection,
-  timerHandler
-} from "../../shared/@ai-setting/roy-agent-core-3gpygqcx.js";
-import"../../shared/@ai-setting/roy-agent-core-bxkjk7zx.js";
+  resolveLarkChannelSystemPrompt,
+  timerHandler,
+  wecomCliHandler
+} from "../../shared/@ai-setting/roy-agent-core-xf6z96qy.js";
+import"../../shared/@ai-setting/roy-agent-core-vx8zc847.js";
 import {
   cliCommandHandler
 } from "../../shared/@ai-setting/roy-agent-core-v0hf14bj.js";
 import"../../shared/@ai-setting/roy-agent-core-tm1mxttk.js";
-import"../../shared/@ai-setting/roy-agent-core-rsn44n9y.js";
+import"../../shared/@ai-setting/roy-agent-core-2stt4rp5.js";
+import"../../shared/@ai-setting/roy-agent-core-b31v3qpv.js";
+import"../../shared/@ai-setting/roy-agent-core-m3vjepzz.js";
 import"../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
 import"../../shared/@ai-setting/roy-agent-core-9vxh6f8h.js";
 import"../../shared/@ai-setting/roy-agent-core-ezvpreqz.js";
@@ -25,9 +32,9 @@ import"../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
 import"../../shared/@ai-setting/roy-agent-core-m46fe3x4.js";
 import"../../shared/@ai-setting/roy-agent-core-4rtg69cn.js";
-import"../../shared/@ai-setting/roy-agent-core-hd3n57zs.js";
-import"../../shared/@ai-setting/roy-agent-core-w0qjeq2v.js";
-import"../../shared/@ai-setting/roy-agent-core-6cy43nss.js";
+import"../../shared/@ai-setting/roy-agent-core-d1n4jbza.js";
+import"../../shared/@ai-setting/roy-agent-core-7dd0s3xb.js";
+import"../../shared/@ai-setting/roy-agent-core-rykf7c04.js";
 import"../../shared/@ai-setting/roy-agent-core-c2gbt68e.js";
 import"../../shared/@ai-setting/roy-agent-core-1v4g0d4x.js";
 import"../../shared/@ai-setting/roy-agent-core-cgtq6427.js";
@@ -48,7 +55,9 @@ import"../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
 import"../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
 import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 export {
+  wecomCliHandler,
   timerHandler,
+  resolveLarkChannelSystemPrompt,
   renderRuleNoticeSection,
   patchCardByLarkCli,
   larkCliHandler,
@@ -58,7 +67,10 @@ export {
   cliCommandHandler,
   builtInHandlers,
   buildLarkRecommendedAction,
+  buildLarkChannelSystemPrompt,
   bountyIMHandler,
   bountyCliHandler,
-  LarkCliInstance
+  LarkCliInstance,
+  LARK_PROMPT_LENGTH_BUDGET,
+  LARK_CHANNEL_PROMPT_SECTION_TITLE
 };