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

package/dist/env/task/plugins/wecom-session-card-store.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview WecomSessionCardStore — 企微 **session 卡**的持久化记录（Task #5364）
+ *
+ * ## 为什么需要（B 方案的核心前提）
+ *
+ * 用户 2026-11-12 08:34 拍板 **B**：
+ *
+ * > 「企微改成**只维护一张卡 + 靠按钮触发更新**」
+ *
+ * 企微协议硬约束（#5203 已取证）：`aibot_respond_update_msg` **必须**在
+ * `template_card_event` 回调的 5 秒窗口内、用回调带回的 `req_id` 才能更新卡片。
+ * 生命周期事件不是回调、没有 req_id ⇒ **无法主动 patch**。
+ *
+ * 于是 #5360 的实现退化成「每个生命周期发一张新卡」—— 用户明确否掉（重复卡
+ * + 刷屏）。B 方案换一条路：
+ *
+ * ```
+ * 首次 lifecycle 事件 → 发**一张**卡（记住 cardTaskId）
+ * 后续 lifecycle 事件 → 只写本 store（不发送）
+ * 用户点「刷新」按钮   → 有 req_id 了 → 从本 store 读快照 + 实时活性 → patch 同一张卡
+ * ```
+ *
+ * ⇒ **本 store 是「刷新时能重建整张卡」的唯一数据来源**。缺了它，刷新只能
+ * 显示活性，生命周期/标题/操作记录全丢 —— 直接违反用户「原有信息一个不少」。
+ *
+ * ## 为什么不复用 wecom-card-state-store（task 维度）
+ *
+ * `wecom_card.task_id INTEGER PRIMARY KEY` 结构上装不下 `session_xxx` 字符串。
+ * 硬塞要么改主键类型（旧库迁移风险），要么把 sessionId hash 成数字（不可逆，
+ * 刷新时反解不回来）。所以**独立库文件 + 独立表 + 字符串主键**，零迁移风险。
+ *
+ * 库文件：`~/.local/share/roy-agent/wecom-session-cards.db`
+ */
+/** session 卡生命周期（与 wecom-card-builder 的 WecomSessionLifecycle 同义） */
+export type WecomSessionCardLifecycle = "running" | "completed" | "timeout" | "failed" | "stopped";
+/** 卡片上的一条执行动态（与 WecomMilestoneLite 结构兼容） */
+export interface WecomSessionMilestone {
+    title: string;
+    timestamp: string;
+    description?: string;
+}
+/** 一条 session 卡持久化记录 */
+export interface WecomSessionCardState {
+    /** ★ 主键：sub-session id（字符串，非 task 号） */
+    sessionId: string;
+    /** 企微 chat_id（单聊=userid，群聊=chatid） */
+    chatId: string;
+    /** 会话类型（更新发送/诊断用） */
+    chatType: "single" | "group";
+    /** 事件源 ID（WS 实例反查用；刷新端口不依赖它，但诊断需要） */
+    sourceId?: string;
+    /**
+     * ★ 首次发卡时卡片上的 `template_card.task_id`。
+     *
+     * 刷新帧的 `task_id` **必须**与回调带回的值一致（协议硬约束），
+     * 所以这个值必须持久化 —— 否则重启后刷新会因为 task_id 不匹配而失败。
+     */
+    cardTaskId: string;
+    /** 当前生命周期 */
+    lifecycle: WecomSessionCardLifecycle;
+    /** 会话标题（description / agent 名） */
+    title?: string;
+    /** 所属 agent（subagentType） */
+    agentType?: string;
+    /** 开始时间（ISO） */
+    startedAt?: string;
+    /** 该 session 关联的 roy 任务号（可选增强） */
+    associatedTaskId?: number;
+    /** 累积执行动态（JSON 字符串：WecomSessionMilestone[]） */
+    milestones?: string;
+    /** 首次发卡时间（ms epoch） */
+    createdAt: number;
+    /** 最后更新时间（ms epoch） */
+    updatedAt: number;
+    /** 终结时间（ms epoch）；仅终态有值 */
+    closedAt?: number;
+}
+/** 持久化端口（sender / 刷新 handler 只依赖这个接口，便于测试注入） */
+export interface WecomSessionCardStore {
+    /** 写入或覆盖一条记录 */
+    upsert(state: WecomSessionCardState): void;
+    /** 按 sessionId 读取 */
+    get(sessionId: string): WecomSessionCardState | undefined;
+    /** 列出全部记录（诊断用） */
+    list(): WecomSessionCardState[];
+    /** 标记终结（保留 cardTaskId 便于事后追溯） */
+    markClosed(sessionId: string): void;
+    /** 真删除（仅测试/手工清理用） */
+    delete(sessionId: string): void;
+    /** 释放资源 */
+    close(): void;
+}
+/** 内存实现（测试直接用，不经过 createWecomSessionCardStore 的环境守卫） */
+export declare class MemoryWecomSessionCardStore implements WecomSessionCardStore {
+    private readonly records;
+    upsert(state: WecomSessionCardState): void;
+    get(sessionId: string): WecomSessionCardState | undefined;
+    list(): WecomSessionCardState[];
+    markClosed(sessionId: string): void;
+    delete(sessionId: string): void;
+    close(): void;
+}
+/** 测试工厂：内存 store */
+export declare function createMemoryWecomSessionCardStore(): WecomSessionCardStore;
+export declare class SqliteWecomSessionCardStore implements WecomSessionCardStore {
+    private readonly db;
+    constructor(dbPath: string);
+    upsert(state: WecomSessionCardState): void;
+    get(sessionId: string): WecomSessionCardState | undefined;
+    list(): WecomSessionCardState[];
+    markClosed(sessionId: string): void;
+    delete(sessionId: string): void;
+    close(): void;
+}
+/** 默认库文件路径：`$HOME/.local/share/roy-agent/wecom-session-cards.db` */
+export declare function getDefaultWecomSessionCardDbPath(): string;
+/**
+ * 创建持久化 store。
+ *
+ * ★ 失败降级：SQLite 打不开时**不抛错**，回落内存实现并 warn ——
+ *   卡片刷新不能因为持久化层故障整体崩掉（降级后「只发一张卡」语义在
+ *   单进程内仍成立，只是重启后可能重发一张）。
+ *
+ * ★ 测试环境保护（与 createWecomCardStateStore 同配方）：
+ *   bun test 环境 + 未显式指定路径 → 一律返回内存实现（零副作用），
+ *   防止测试污染真实用户库。
+ */
+export declare function createWecomSessionCardStore(dbPath?: string): WecomSessionCardStore;
+/** 取（并在首次调用时创建）进程级共享 session 卡 store。 */
+export declare function getSharedWecomSessionCardStore(): WecomSessionCardStore;
+/**
+ * 测试钩子：重置共享单例（关闭旧连接，避免 fd 泄漏 / 跨用例串状态）。
+ */
+export declare function __resetSharedWecomSessionCardStoreForTest(): void;

package/dist/env/task/plugins/wecom-session-card-store.js

@@ -0,0 +1,23 @@
+import {
+  MemoryWecomSessionCardStore,
+  SqliteWecomSessionCardStore,
+  __resetSharedWecomSessionCardStoreForTest,
+  createMemoryWecomSessionCardStore,
+  createWecomSessionCardStore,
+  getDefaultWecomSessionCardDbPath,
+  getSharedWecomSessionCardStore
+} from "../../../shared/@ai-setting/roy-agent-core-7kvpc0w5.js";
+import"../../../shared/@ai-setting/roy-agent-core-6k8mb7zx.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
+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 {
+  getSharedWecomSessionCardStore,
+  getDefaultWecomSessionCardDbPath,
+  createWecomSessionCardStore,
+  createMemoryWecomSessionCardStore,
+  __resetSharedWecomSessionCardStoreForTest,
+  SqliteWecomSessionCardStore,
+  MemoryWecomSessionCardStore
+};

package/dist/env/task/plugins/wecom-task-notify-plugin.d.ts

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview WecomTaskNotifyHook — 企微任务进展通知 Hook（Task #5193）
+ *
+ * 在任务生命周期事件上，把「任务进展」渲染成 **markdown 消息**
+ * 发到企微（对齐 LarkCliTaskNotifyHook 的 hook 结构）：
+ *
+ * - `task:after.create`          → 发初始卡片
+ * - `task:after.update`          → 发更新卡片（进度/状态/变更摘要）
+ * - `task:after.complete`        → 发终态卡片（仅真验收完成）
+ * - `task:after.delete`          → 发取消收尾
+ * - `task:operation:after.create` → 时间线追加（节流）
+ *
+ * ## 与 lark-cli 插件的关键差异
+ *
+ * | 维度 | lark-cli | wecom-cli |
+ * |------|----------|-----------|
+ * | 卡片形态 | interactive card（可 patch 同一张） | **markdown 消息（每次新发）** |
+ * | 更新方式 | PATCH 原卡片 | 每次更新发一条新 markdown |
+ * | pin/unpin | 支持 | **无**（恒 false） |
+ * | messageId 跟踪 | 必须（patch 键） | 不需要 |
+ *
+ * ⇒ 企微侧防刷屏靠**节流**（operationThrottleMs 默认 5s）；
+ *   时间线**必须持久化**（wecom-cards.db）—— 每条新消息都要
+ *   渲染完整历史，重启后也不能丢。
+ *
+ * ## chat_id 语义（实测硬约束，Task #5174）
+ *
+ * - replyChannel.chatId：单聊 = 对方 userid，群聊 = chatid
+ * - CLI 需要真实 userid（`wotnB7Wg...` 形态）→ 出站统一走
+ *   `sendWecomReply`（内部 `resolveWecomCliChatId` 解析 + 缓存）
+ *
+ * @example
+ * ```typescript
+ * import { createWecomTaskNotifyHook } from "./wecom-task-notify-plugin";
+ * globalHookManager.register("task:after.create", createWecomTaskNotifyHook({...}));
+ * ```
+ */
+import type { Hook, HookContext } from "../../hook/types";
+import type { Task } from "../types";
+import { type WecomSendResult } from "../../event-source/wecom-respond-registry";
+import { MemoryWecomCardStateStore, getDefaultWecomCardDbPath, type WecomCardStateStore } from "./wecom-card-state-store";
+/** 通知类型（对齐 NotifyType） */
+export declare const WecomNotifyType: {
+    readonly TASK_CREATED: "task_created";
+    readonly TASK_UPDATED: "task_updated";
+    readonly TASK_COMPLETED: "task_completed";
+    readonly OPERATION_CREATED: "operation_created";
+};
+export type WecomNotifyType = (typeof WecomNotifyType)[keyof typeof WecomNotifyType];
+/** 时间线里程碑（渲染用，与 LarkCardPatchNotifier.Milestone 形态对齐） */
+export interface WecomMilestone {
+    title: string;
+    timestamp: string;
+    description?: string;
+}
+/** 插件配置 */
+export interface WecomTaskNotifyConfig {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 优先级 */
+    priority?: number;
+    /** 插件名称（用于 pluginEnabled 检查） */
+    pluginName?: string;
+    /** 事件源 ID（用于 pluginEnabled 检查） */
+    sourceId?: string;
+    /**
+     * 操作记录通知节流间隔（毫秒）
+     *
+     * 企微每次更新都是**新消息**，不加节流会刷屏。默认 5000ms；
+     * 设为 0 表示不节流。
+     */
+    operationThrottleMs?: number;
+    /**
+     * 时间线最多保留的里程碑条数（防消息无限膨胀）
+     *
+     * 企微 markdown 消息有长度上限，时间线太长会被截断。
+     * 默认 20 条，超出时丢最旧的（最新进展最重要）。
+     */
+    maxTimelineEntries?: number;
+    /** 通知类型过滤（空数组 = 全开） */
+    notifyTypes?: WecomNotifyType[];
+    /**
+     * ★ Task #5360（补充需求）：ES 配置的 `statusNotifications` 透传。
+     *
+     * - `false` / 缺省（默认）：只发卡片（#5255 单卡语义）
+     * - `true`：发卡成功后**额外**再发一条 markdown 状态文本
+     *
+     * 为什么由工厂注入而不是插件自己读 `event-sources.json`：
+     * 插件不持有 ES 配置句柄，且同一进程可能有多个 wecom 源 ——
+     * 由 `es-plugins` 工厂把**该源自己的**配置值传进来，语义最准确。
+     */
+    statusNotifications?: boolean;
+    /**
+     * 出站 sender（测试注入；不传用 sendWecomReply）
+     */
+    sender?: {
+        send(input: {
+            chatId: string;
+            content: string;
+        }): Promise<WecomSendResult>;
+    };
+    /**
+     * 卡片记录持久化 store
+     *
+     * 不传 → 自动创建（`~/.local/share/roy-agent/wecom-cards.db`）；
+     * 测试可注入 MemoryWecomCardStateStore。
+     */
+    cardStateStore?: WecomCardStateStore;
+}
+/**
+ * 从 EnvContext 判定是否企微事件，并提取 chatId。
+ *
+ * 判定优先级：
+ * 1. `envEvent.type === "event-source.event.wecom-cli"`（生产主路径）
+ * 2. `replyChannel.type === "wecom-cli"`（兜底：事件类型缺失但通道明确）
+ *
+ * 两者都不满足（lark / cli-command / timer…）→ isWecom=false，插件跳过。
+ */
+export declare function extractWecomFields(env: {
+    envEvent?: unknown;
+    replyChannel?: {
+        type?: string;
+        chatId?: string;
+    };
+}, fallbackSourceId?: string): {
+    isWecom: boolean;
+    chatId?: string;
+    sourceId?: string;
+};
+/**
+ * 渲染企微进展卡片（markdown）
+ *
+ * 结构（对齐 lark 卡片的信息密度，压缩成 markdown）：
+ * ```
+ * ### 📋 Task #42 · 时空增强任务
+ * **状态**：🔄 进行中（80%）
+ * > 任务描述第一行…
+ *
+ * **时间线**
+ * - 🕐 2026-06-01 00:00 — Task 创建
+ * - 🕐 2026-06-01 02:00 — 完成需求分析：已完成核心功能的需求拆解
+ * ```
+ */
+export declare function buildWecomTaskCard(input: {
+    task: Task;
+    statusLabel: string;
+    milestones: WecomMilestone[];
+    /** 变更摘要（update 时） */
+    changeSummary?: string;
+    /** 是否终态（终态加收尾分隔线） */
+    terminal?: boolean;
+}): string;
+export declare class WecomTaskNotifyHook implements Hook {
+    readonly name: string;
+    readonly priority: number;
+    readonly description?: string;
+    readonly pluginName?: string;
+    readonly sourceId?: string;
+    private readonly config;
+    /** 出站 sender（默认 sendWecomReply，测试可注入） */
+    private readonly sender;
+    /** 持久化 store（taskId → chatId/status/timeline） */
+    private readonly cardStateStore;
+    /**
+     * ★ Task #5360（补充需求）：状态通知文本开关（严格 `=== true`）。
+     *
+     * 构造时快照一次（配置热更新靠重建插件实例，与 `enabled` / `priority` 一致），
+     * 避免每次 deliver 都读 config 对象。
+     */
+    private readonly esStatusNotifications;
+    /** 操作记录节流状态：key `op:${taskId}` → 上次发送时间戳 */
+    private lastNotifyTimestamps;
+    constructor(config?: WecomTaskNotifyConfig);
+    /**
+     * 默认出站：sendWecomReply（CLI 主路径 → WS fallback）
+     *
+     * sourceId 从事件 metadata 取（sendWecomReply 只在 WS fallback 时用）。
+     */
+    private defaultSend;
+    execute(ctx: HookContext<unknown>): Promise<void>;
+    /** 任务创建：发初始卡片 */
+    private onAfterCreate;
+    /** 任务更新：发更新卡片 */
+    private onAfterUpdate;
+    /** 任务终态（task_complete）：仅真验收完成（to_validate 是自查关） */
+    private onAfterComplete;
+    /** 任务删除（硬删除）：收尾 */
+    private onAfterDelete;
+    /** 操作记录创建：时间线追加（节流） */
+    private onAfterOperationCreate;
+    /** 发初始卡片 */
+    private sendCardStart;
+    /** 发更新卡片 */
+    private sendCardUpdate;
+    /** 发终态卡片 */
+    private sendCardFinish;
+    /**
+     * 投递（永不抛）
+     *
+     * ★ Task #5203：主路径 = WS 直发 template_card（text_notice 进展卡）；
+     * 构造失败 / WS 不可用 → 回落 markdown（CLI 路径，#5193 行为）。
+     *
+     * @returns 是否成功（失败时调用方决定是否落库）
+     */
+    private deliver;
+    /**
+     * ★ Task #5360（补充需求）：读 ES 配置的 `statusNotifications`。
+     *
+     * ## 为什么读实时配置而不是快照
+     *
+     * lark 侧走 `EventHandler`（事件驱动，用 delegate 时刻的快照）；
+     * 企微插件是**直接挂在 hook 上**（`task:after.create/update/complete`），
+     * 拿不到"任务诞生时的快照"，所以只能读事件源当前配置。
+     *
+     * 语义差异可接受：企微侧开关变化对**下一次**任务状态变化生效（毫秒级），
+     * 而 lark 侧对已派生任务保持口径一致。两边各自的取舍都有文档说明。
+     *
+     * 严格 `=== true`（手改 JSON 的 "true"/1/null 一律当 false）。
+     */
+    private statusNotificationsEnabled;
+    /**
+     * ★ Task #5360（补充需求）：`statusNotifications: true` 时额外发的 markdown 状态文本。
+     *
+     * 内容 = 现有 `buildWecomTaskCard` 的 markdown 形态（#5193 的文本可读性），
+     * 与卡片正文同源，避免两套文案漂移。
+     */
+    private sendStatusMarkdown;
+    /**
+     * ★ Task #5203：经 WS 直发 template_card。
+     *
+     * - chatType：单聊 → chat_type=1；群聊 → 2
+     *   （★ Task #5270：读 replyChannel.params.chatType——
+     *   buildWecomReplyChannel 塞入，顶层无 chatType 字段；
+     *   另当 chatId 与当前 env 的 chatId 不一致时（终态/删除
+     *   链路用持久化记录的 rec.chatId，可能来自群会话）按群聊
+     *   处理，避免群 chatid + chat_type=1 错配被企微丢弃）
+     * - 失败返回 false（调用方回落 markdown），绝不抛
+     */
+    private deliverTemplateCard;
+    /** 读记录（store 异常降级为 undefined，绝不抛） */
+    private getRecord;
+    /** 解析持久化的时间线 JSON（损坏时返回空数组） */
+    private parseTimeline;
+    /** 时间线截断（保留最新 N 条） */
+    private trimTimeline;
+    /** 持久化时间线（失败只 warn） */
+    private persistTimeline;
+    /** 从记录重建最小 Task（delete 后 Task 已不存在） */
+    private hydrateTask;
+    /**
+     * 操作记录发送节流
+     *
+     * 同一 Task 在 operationThrottleMs（默认 5s）窗口内只发一次，
+     * 避免 agent 每次 tool call 都刷屏（企微每次都是新消息，比 lark 更敏感）。
+     *
+     * ★ 返回 true **不代表丢弃**：被节流的 operation 仍会先并进
+     *   时间线并落库，只是不立刻发送。
+     */
+    private shouldThrottleOperation;
+    /** 检查是否应该发送通知 */
+    private shouldNotify;
+}
+export declare function createWecomTaskNotifyHook(config?: WecomTaskNotifyConfig): WecomTaskNotifyHook;
+export { MemoryWecomCardStateStore, getDefaultWecomCardDbPath };

package/dist/env/task/storage/index.js

@@ -1,10 +1,10 @@
-import"../../../shared/@ai-setting/roy-agent-core-q813vafd.js";
+import"../../../shared/@ai-setting/roy-agent-core-vpcxv1ty.js";
 import {
   SQLiteTaskStore,
   getDefaultDataDir,
   getDefaultTaskDbPath
-} from "../../../shared/@ai-setting/roy-agent-core-ezvpreqz.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+} from "../../../shared/@ai-setting/roy-agent-core-6k8mb7zx.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 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";

package/dist/env/task/tools/index.js

@@ -11,12 +11,12 @@ import {
   searchTasksTool,
   treeTasksTool,
   updateTaskTool
-} from "../../../shared/@ai-setting/roy-agent-core-vffccgf6.js";
-import"../../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
+} from "../../../shared/@ai-setting/roy-agent-core-qwd2dq5q.js";
+import"../../../shared/@ai-setting/roy-agent-core-d6zdbgtc.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-7cbpmk4q.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 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";

package/dist/env/tool/built-in/index.d.ts

@@ -7,6 +7,7 @@ import { writeFileTool } from "./write-file";
 import { editFileTool } from "./edit-file";
 import { grepTool } from "./grep";
 import { understandImageTool } from "./understand-image";
+import { wecomRespondTool } from "../../event-source/wecom-respond-registry";
 import { createQueryBackgroundProcessTool } from "./query-background-process-tool";
 import { createCompactSessionTool, compactSessionTool } from "./compact-session-tool";
 export { bashTool };
@@ -17,6 +18,7 @@ export { writeFileTool };
 export { editFileTool };
 export { grepTool };
 export { understandImageTool };
+export { wecomRespondTool };
 import { queryBackgroundProcessTool } from "./query-background-process-tool";
 export { queryBackgroundProcessTool, createQueryBackgroundProcessTool };
 export { compactSessionTool, createCompactSessionTool };

package/dist/env/tool/built-in/index.js

@@ -8,7 +8,7 @@ import {
   grepTool,
   readFileTool,
   writeFileTool
-} from "../../../shared/@ai-setting/roy-agent-core-8ez6mccb.js";
+} from "../../../shared/@ai-setting/roy-agent-core-k3gcvybs.js";
 import {
   getUnderstandImageLLMProvider,
   resetUnderstandImageLLMProvider,
@@ -22,13 +22,20 @@ import {
   queryBackgroundProcessTool
 } from "../../../shared/@ai-setting/roy-agent-core-2akfd64z.js";
 import"../../../shared/@ai-setting/roy-agent-core-fttgm52a.js";
+import {
+  wecomRespondTool
+} from "../../../shared/@ai-setting/roy-agent-core-h1e1fm9b.js";
+import"../../../shared/@ai-setting/roy-agent-core-c4ec7k0p.js";
+import"../../../shared/@ai-setting/roy-agent-core-418zc9ha.js";
 import"../../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 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 {
   writeFileTool,
+  wecomRespondTool,
   understandImageTool,
   setUnderstandImageLLMProvider,
   resetUnderstandImageLLMProvider,

package/dist/env/tool/index.js

@@ -10,7 +10,7 @@ import {
   grepTool,
   readFileTool,
   writeFileTool
-} from "../../shared/@ai-setting/roy-agent-core-8ez6mccb.js";
+} from "../../shared/@ai-setting/roy-agent-core-k3gcvybs.js";
 import {
   getUnderstandImageLLMProvider,
   resetUnderstandImageLLMProvider,
@@ -19,23 +19,28 @@ import {
 } from "../../shared/@ai-setting/roy-agent-core-xwm8zavb.js";
 import"../../shared/@ai-setting/roy-agent-core-2akfd64z.js";
 import"../../shared/@ai-setting/roy-agent-core-fttgm52a.js";
+import"../../shared/@ai-setting/roy-agent-core-h1e1fm9b.js";
+import"../../shared/@ai-setting/roy-agent-core-c4ec7k0p.js";
+import"../../shared/@ai-setting/roy-agent-core-418zc9ha.js";
 import {
   ToolComponent,
   ToolRegistry,
-  ToolValidator,
   getMaxOutputSize,
   setToolConfigComponent
-} from "../../shared/@ai-setting/roy-agent-core-v85n42ve.js";
+} from "../../shared/@ai-setting/roy-agent-core-mx855td4.js";
 import"../../shared/@ai-setting/roy-agent-core-jvv2h3d6.js";
+import {
+  ToolValidator
+} from "../../shared/@ai-setting/roy-agent-core-wxrkcb17.js";
 import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import"../../shared/@ai-setting/roy-agent-core-mkc3zshb.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";
-import"../../shared/@ai-setting/roy-agent-core-pgvcf91v.js";
-import"../../shared/@ai-setting/roy-agent-core-ax9e9szb.js";
-import"../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";
-import"../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
-import"../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
-import"../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../shared/@ai-setting/roy-agent-core-m39v7qpx.js";
+import"../../shared/@ai-setting/roy-agent-core-smf94h73.js";
+import"../../shared/@ai-setting/roy-agent-core-yet36q5k.js";
+import"../../shared/@ai-setting/roy-agent-core-tkpp1ba0.js";
+import"../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 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";

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

@@ -163,6 +163,31 @@ export interface ToolMetadata {
      *   3. ToolComponent.listTools({ allowedAgent }) 一次过滤；agent-component 再做 allowedTools/deniedTools 二次过滤
      */
     allowedAgentTypes?: string[];
+    /**
+     * ★ Task #5333 — 渠道专用工具标记（channel-only tool）。
+     *
+     * `true` = 该工具**只对特定事件源渠道**有意义，默认对所有 agent 不可见；
+     * 只有当前会话的 `AgentContext.extendTools` 显式列出该工具名时才可见。
+     *
+     * 典型用例：`wecom_respond`（企微出站唯一通道）——
+     * 在飞书会话 / 交互式 CLI 里调用必然失败（无企微 chatId，无 wecom 注册表实例），
+     * 但它原先在 `getAllBuiltInTools()` 全局注册且无可见性声明 →
+     * 所有 agent（含 default 接待员）都被注入了它，LLM 会误调。
+     *
+     * 与 `allowedAgentTypes` 的区别：
+     * - `allowedAgentTypes` 按 **agent 身份** 过滤（谁可见）
+     * - `channelOnly` 按 **会话渠道上下文** 过滤（哪个事件源驱动的这一轮可见）
+     *
+     * 两者正交，都满足才可见。实际判定顺序见 `filterToolsByAgent`：
+     * **先 channelOnly**（渠道上下文），**再 allowedAgentTypes**（agent 身份）。
+     *
+     * ⚠️ 可见性只在 `AgentComponent.getAvailableTools` 一处收敛
+     * （`filterToolsByAgent`）。`ToolRegistry.listTools()` 是**存储目录**
+     * （`roy-agent tools list` / 调试用），不做 channelOnly 过滤 ——
+     * 否则"无 filter 全量返回、有 filter 却隐藏"会造成同一工具在不同
+     * 查询路径下存在性不一致。
+     */
+    channelOnly?: boolean;
     /**
      * Whether this tool explicitly opts out of string output truncation.
      *

package/dist/env/tool/validator.d.ts

@@ -1,4 +1,12 @@
 import type { Tool, ValidationResult } from "./types";
+/** 接线 ConfigComponent（由 ToolComponent.init 调用，支持热更新） */
+export declare function setToolReasonConfigComponent(component: {
+    get(key: string): unknown;
+} | null): void;
+/** 测试 / 无 ConfigComponent 场景的模块级开关 */
+export declare function setToolReasonRequired(required: boolean): void;
+/** 当前是否要求 reason（逃生开关读取，实时） */
+export declare function isToolReasonRequired(): boolean;
 /**
  * 工具参数验证器
  */

package/dist/env/workflow/engine/index.js

@@ -5,25 +5,25 @@ import {
   Scheduler,
   WorkflowEngine,
   init_engine
-} from "../../../shared/@ai-setting/roy-agent-core-6rh8k6ba.js";
+} from "../../../shared/@ai-setting/roy-agent-core-6gj1hc5z.js";
 import"../../../shared/@ai-setting/roy-agent-core-6atd905e.js";
-import"../../../shared/@ai-setting/roy-agent-core-dqxec05w.js";
-import"../../../shared/@ai-setting/roy-agent-core-efkjyh69.js";
+import"../../../shared/@ai-setting/roy-agent-core-bjtc9d35.js";
+import"../../../shared/@ai-setting/roy-agent-core-9710zwwz.js";
 import"../../../shared/@ai-setting/roy-agent-core-1db4vpc6.js";
-import"../../../shared/@ai-setting/roy-agent-core-dvtg4sn0.js";
-import"../../../shared/@ai-setting/roy-agent-core-c2gbt68e.js";
-import"../../../shared/@ai-setting/roy-agent-core-acj8ag08.js";
+import"../../../shared/@ai-setting/roy-agent-core-g8yr733d.js";
+import"../../../shared/@ai-setting/roy-agent-core-h83zdsrq.js";
+import"../../../shared/@ai-setting/roy-agent-core-tjnabyvq.js";
 import"../../../shared/@ai-setting/roy-agent-core-ddwa0n6h.js";
 import {
   DAGManager
-} from "../../../shared/@ai-setting/roy-agent-core-cgtq6427.js";
+} from "../../../shared/@ai-setting/roy-agent-core-e08bvpaq.js";
 import"../../../shared/@ai-setting/roy-agent-core-er070zjq.js";
 import"../../../shared/@ai-setting/roy-agent-core-mkc3zshb.js";
-import"../../../shared/@ai-setting/roy-agent-core-ax9e9szb.js";
-import"../../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";
-import"../../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
-import"../../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../../shared/@ai-setting/roy-agent-core-smf94h73.js";
+import"../../../shared/@ai-setting/roy-agent-core-yet36q5k.js";
+import"../../../shared/@ai-setting/roy-agent-core-tkpp1ba0.js";
+import"../../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 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";

package/dist/env/workflow/hooks/index.js

@@ -1,17 +1,17 @@
 import {
   init_hooks
-} from "../../../shared/@ai-setting/roy-agent-core-dvtg4sn0.js";
+} from "../../../shared/@ai-setting/roy-agent-core-g8yr733d.js";
 import {
   WorkflowHookPoints,
   emitWorkflowNodeHook,
   emitWorkflowRunHook,
   getRegisteredWorkflowHookPoints
-} from "../../../shared/@ai-setting/roy-agent-core-c2gbt68e.js";
-import"../../../shared/@ai-setting/roy-agent-core-ax9e9szb.js";
-import"../../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";
-import"../../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
-import"../../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+} from "../../../shared/@ai-setting/roy-agent-core-h83zdsrq.js";
+import"../../../shared/@ai-setting/roy-agent-core-smf94h73.js";
+import"../../../shared/@ai-setting/roy-agent-core-yet36q5k.js";
+import"../../../shared/@ai-setting/roy-agent-core-tkpp1ba0.js";
+import"../../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 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";