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

package/dist/env/event-source/wecom-cli-handler.d.ts

@@ -0,0 +1,291 @@
+/**
+ * @fileoverview Task #5142 — `wecom-cli` EventSource handler
+ *
+ * ## 定位
+ *
+ * 企业微信（WeCom）官方 CLI 是 `@wecom/cli`（Rust 编译，npm 名 `@wecom/cli`，
+ * 二进制名 `wecom-cli`，仓库 https://github.com/WeComTeam/wecom-cli）。
+ * 本 handler 把企微接入 roy-agent 的 EventSource 体系，esType = **`wecom-cli`**。
+ *
+ * ## 为什么 esType 必须是新类型名（不能抄 `lark-cli`）
+ *
+ * `getHandlerForEsType(esType)` 是 v2 notify prompt 的**唯一分派 key**。
+ * 若落库写成 `lark-cli`，主 agent 会拿到「用 lark-cli 发到 oc_xxx」的 prompt ——
+ * 而企微根本没有 `oc_xxx`，agent 必然发不出去。
+ *
+ * ## 入站 transport 三方案（调研结论）
+ *
+ * | 方案 | 机制 | 结论 |
+ * |---|---|---|
+ * | A | 企微 webhook 回调 URL | 需**公网可达 URL** + 消息加解密（EncodingAESKey）。本机是内网 → 不可直接用 |
+ * | B | 轮询 `wecom-cli chat messages list` | 只支持**最近 7 天**，且需先知道 `chat_id` → 只能作补充，不能作主路径 |
+ * | C | 第三方桥接（CLI-WeChat-Bridge / golembot） | 依赖非官方项目（AGPL-3.0 传染风险）→ 只作参考实现 |
+ * | **D（采用）** | **企微长连接 WebSocket** `wss://openws.work.weixin.qq.com` | ✅ **无需公网 IP**、无需加解密；官方 SDK `@wecom/aibot-node-sdk` 已封装认证/心跳/重连/reply 串行队列 |
+ *
+ * 企微官方文档：
+ * - 长连接：https://developer.work.weixin.qq.com/document/path/101463
+ * - 接收消息（webhook 模式）：https://developer.work.weixin.qq.com/document/path/100719
+ * - 官方 Node SDK：https://www.npmjs.com/package/@wecom/aibot-node-sdk
+ *
+ * ## 长连接协议要点（来自官方文档 101463）
+ *
+ * - 握手：`wss://openws.work.weixin.qq.com` → 发送 `aibot_subscribe`（body: bot_id + secret）
+ * - 入站：`aibot_msg_callback`（消息）/ `aibot_event_callback`（事件）
+ * - 出站：`aibot_respond_msg`（被动回复，**必须透传回调的 req_id**）/
+ *   `aibot_send_msg`（主动推送）/ `aibot_respond_welcome_msg` / `aibot_respond_update_msg`
+ * - 心跳：`ping`，建议 30s
+ * - **每个机器人同一时刻只允许 1 条长连接**（新连接会踢掉旧连接）⇒ 必须做单实例互斥
+ * - 收到回调后 **24h 内**可回复该会话；限频 **30 条/分钟、1000 条/小时**
+ * - 流式消息需 10 分钟内 `finish=true`
+ *
+ * ## 本 handler 的边界（Phase 1 骨架）
+ *
+ * Phase 1 只做「spawn 子进程 + 解析行 JSON + 产出 EventSourceEvent」：
+ * 入站通过 `wecom-cli` 的**行 JSON 输出**（未来由长连接桥接进程产出 NDJSON），
+ * 出站由 notify prompt 指导 agent 直接调 `wecom-cli message aibot send --json ...`。
+ *
+ * @see packages/core/src/env/event-source/wecom-cli-handler.test.ts
+ */
+import type { EventSourceHandler, EventSourceConfig, EventMetadata, ReplyChannel } from "./types";
+/** 企微事件源类型名（必须是**新**类型名，不能抄 lark-cli） */
+export declare const WECOM_CLI_ES_TYPE = "wecom-cli";
+/**
+ * 企微 chatId 前缀。
+ *
+ * 企微的 `chatid` 与飞书的 `oc_xxx` 语义不同（企微群聊 id 是业务方自己的
+ * chatid，单聊则是 userid），下游按前缀即可反解「这是企微会话」，
+ * 避免与 lark / cli 的 chatId 撞车。
+ */
+export declare const WECOM_CHAT_ID_PREFIX = "wecom:";
+/** 企微长连接默认地址（官方文档 101463） */
+export declare const WECOM_WS_DEFAULT_URL = "wss://openws.work.weixin.qq.com";
+interface WecomCliConfig {
+    botId?: string;
+    secret?: string;
+    /** 覆盖默认命令（高级用法） */
+    command?: string;
+    /** 群机器人 webhook（可选） */
+    webhook?: string;
+    /**
+     * 独立凭据文件路径（Task #5228）。
+     *
+     * 多 bot 场景（如 wecom-bot-2）用独立凭据文件隔离凭据；
+     * 曾是 dead config（声明≠实现），现已接入 resolveWecomCredentials。
+     */
+    credentialsPath?: string;
+}
+/**
+ * 从 EventSourceConfig 读取企微相关字段。
+ *
+ * 优先级：顶级字段 → `options.*`（CLI 透传路径）。
+ */
+export declare function readWecomCliConfig(config: EventSourceConfig): WecomCliConfig;
+/** 默认凭据文件路径（~/.roy-agent/wecom-credentials.json，权限 600） */
+export declare const WECOM_CREDENTIALS_DEFAULT_PATH: string;
+/** 凭据文件解析结果 */
+export interface WecomCredentials {
+    botId: string;
+    secret: string;
+}
+/**
+ * 读取企微凭据文件（不抛）。
+ *
+ * 文件形态：`{"agent_id":"1000003","secret":"..."}`
+ * （agent_id 即智能机器人 BotID）。
+ *
+ * 缺失 / 坏 JSON / 字段不全 → null（调用方据此降级）。
+ */
+export declare function readWecomCredentialsFile(path: string): WecomCredentials | null;
+/**
+ * 解析企微凭据（优先级：config 显式配置 > options.credentialsPath
+ * 独立凭据文件 > 默认凭据文件）。
+ *
+ * ★ Task #5228：`options.credentialsPath` 曾是 dead config——
+ *   wecom-bot-2 配置了独立凭据文件却仍用生产默认凭据连接 → 无回复。
+ *   声明 ≠ 实现（与 #4946 provider temperature 同类坑）。
+ *
+ * 全缺 → undefined：调用方（start）据此**优雅降级**为骨架模式，
+ * 不 crash、不假装在收消息。
+ */
+export declare function resolveWecomCredentials(config: EventSourceConfig, credentialsPath?: string): WecomCredentials | undefined;
+/** `buildWecomReplyChannel` 的入参 */
+export interface WecomReplyChannelInput {
+    /** 企微会话 id（群聊有，单聊通常无） */
+    chatId?: string;
+    /** 消息 id（msgid） */
+    messageId?: string;
+    /** 会话类型：single / group */
+    chatType?: string;
+    /** 发送者 userid */
+    userId?: string;
+    /**
+     * ★ Task #5311（CV M1）：事件源 ID —— 失败回执的 WS fallback 需要它
+     * 反查注册实例（`getWecomRespondTarget(sourceId)`）。缺了只剩 CLI 一条路。
+     */
+    sourceId?: string;
+    /** ★ Task #5311：原始 req_id —— WS 被动回帧（带引用语义）需要 */
+    reqId?: string;
+    /**
+     * ★ Task #5360（补充需求）：状态通知文本开关（来自 ES 配置）。
+     *
+     * 写进 `params` 让 delegate 快照带下去 —— 与 lark 侧同字段同语义。
+     * 严格 `=== true`；显式写 false（不省略，保留"源上显式关"的信息）。
+     */
+    statusNotifications?: boolean;
+}
+/**
+ * 构造企微的 replyChannel。
+ *
+ * ★ 硬约束：`_captureReplyChannelSnapshot()`（delegate-tool.ts:2864）要求
+ * `chatId || messageId` **至少一个非空**，否则整份快照被丢弃 →
+ * notify event 无回复目标 → 规则通知静默丢失。
+ *
+ * 因此本函数**恒不返回 chatId/messageId 双空**：
+ * - 群聊 → chatId = 原始 `chatid`
+ * - 单聊 → chatId = 原始 `userid`（企微单聊的回复目标就是 userid）
+ * - 全空 → chatId = `"wecom:unknown"`（占位，保证下游不丢快照）
+ *
+ * ⚠️ **`chatId` 必须是「可直接用于回复命令」的原始值**，不能加前缀：
+ * `extractReplyContext()` 返回的 chatId 会一路流到 notify prompt，
+ * agent 会把它原样塞进 `wecom-cli message aibot send --json '{"chat_id":"..."}'`。
+ * 加了前缀就等于给 agent 塞了个错误的 chat_id。
+ *
+ * 渠道区分靠 `type: "wecom-cli"` + `params.chatType`，
+ * 原始值同时冗余存进 `params.wecomChatId` / `params.wecomUserId`。
+ */
+export declare function buildWecomReplyChannel(input: WecomReplyChannelInput): ReplyChannel;
+/** 解析结果 */
+export interface ParsedWecomFrame {
+    metadata: EventMetadata;
+    text: string;
+    /** 原始 req_id（长连接回复必须透传） */
+    reqId?: string;
+}
+/**
+ * ★ Task #5271：构建企微 user message（payload.message）。
+ *
+ * 企微的 user message 是**纯文本**（lark 是
+ * JSON.stringify({rawData, recommendedAction})，recommendedAction
+ * 能进 user message；企微不能）。#5251 把 quotedText 挂到
+ * recommendedAction.replyContext，但 LLM 永远看不到
+ * （#5212 MAJOR-2 同型问题在企微重演）。
+ *
+ * replyContext 存在时把引用内容拼进正文，格式：
+ *
+ *   [用户正文]
+ *
+ *   [引用消息] 被引用的原文内容
+ *
+ * 无 replyContext 时返回原正文（字节不变，向后兼容）。
+ */
+export declare function buildWecomUserMessage(text: string, replyContext?: {
+    quotedText?: string;
+}): string;
+/**
+ * 解析企微长连接帧 → EventSourceEvent 元数据。
+ *
+ * 无效帧返回 `null`（不抛）—— 非法输入不能拖垮整个事件源。
+ *
+ * @param frame 原始帧（`aibot_msg_callback` / `aibot_event_callback`）
+ */
+export declare function parseWecomFrame(raw: unknown): ParsedWecomFrame | null;
+/**
+ * 企微渠道**恒需**放行的 channel-only 工具。
+ *
+ * `wecom_respond` 是企微唯一出站通道（wecom-cli 主路径 + WS 回帧 fallback）。
+ * 它带有 `metadata.channelOnly = true`（Task #5333），默认对所有 agent 隐藏
+ * ——如果不在这里显式放行，企微事件的 agent 将**无法回复**用户。
+ */
+export declare const WECOM_DEFAULT_EXTEND_TOOLS: readonly string[];
+/**
+ * 解析企微渠道的 extendTools（默认 + 配置，去重保序）。
+ *
+ * 顺序：WECOM_DEFAULT_EXTEND_TOOLS 在前（确定性前缀），config.extendTools 在后。
+ * 去重保持首次出现位置 —— 保证同一 config 多次调用结果**逐字节一致**
+ * （对齐 buildWecomChannelSystemPrompt 的稳定性纪律，避免无意义的 diff）。
+ *
+ * @param config 事件源配置（可选字段 extendTools）
+ */
+export declare function resolveWecomExtendTools(config: EventSourceConfig | undefined): string[];
+/** 企微渠道 system prompt 的章节标题（lean 卡片指回这里） */
+export declare const WECOM_CHANNEL_PROMPT_SECTION_TITLE = "\u2B50 \u4F01\u4E1A\u5FAE\u4FE1\u56DE\u590D\u89C4\u8303\uFF08system prompt \u6CE8\u5165\u7248\uFF09";
+/** `buildWecomChannelSystemPrompt` 入参（只允许渠道级配置，禁 event） */
+export interface WecomChannelSystemPromptInput {
+    /** 智能机器人 BotID（渠道身份，可选） */
+    botId?: string;
+}
+/**
+ * 构造企微渠道的 system prompt（单点构造，只读渠道配置）。
+ *
+ * ★ 与 buildLarkChannelSystemPrompt 同款纪律：
+ *   - 构造入参**只来自渠道配置**，禁止读 event/rawEvent
+ *     （否则字节漂移破坏 LLM prompt cache 前缀一致性）；
+ *   - 同一入参多次调用**逐字节一致**；
+ *   - per-event 动态部分（chatId/messageId/正文）只进
+ *     recommendedAction 动态卡片，不进这里。
+ *
+ * 内容：回复命令模板 + chatId 语义（单聊=userid / 群聊=chatid）+
+ * 出站纪律 + 文档交付规范（文档类生成不落本地路径，给企微可读内容）。
+ */
+export declare function buildWecomChannelSystemPrompt(opts: WecomChannelSystemPromptInput): string;
+/** `buildWecomNotifyPrompt` 入参 */
+export interface WecomNotifyPromptInput {
+    chatId?: string;
+    messageId?: string;
+    chatType?: string;
+    userId?: string;
+}
+/**
+ * 构造 notify prompt —— 四段式（与 lark-cli 版结构对齐，内容换成企微）。
+ *
+ * ① 用哪个 CLI 回消息
+ * ② 什么 flag（--json / chat_id / msg_type / markdown.content）
+ * ③ 禁什么（禁 curl、禁直连 qyapi、禁 lark-cli flag）
+ * ④ 怎么判成功（exit code + 解析 error.type / error.code）
+ */
+export declare function buildWecomNotifyPrompt(input: WecomNotifyPromptInput): string;
+/**
+ * 探测 `wecom-cli` 二进制是否存在。
+ *
+ * 为什么需要预探测：`spawn("exec <cmd>", {shell:true})` 在二进制缺失时
+ * **不会同步抛错**，而是让 shell 以 exit 127 退出 —— 事件源会短暂进入
+ * "running" 再变 error，状态闪烁且 CLI status 展示不及时。
+ *
+ * 预探测让「二进制不存在」在 start() 里**同步**变成可见的 error 状态。
+ *
+ * ⚠️ **Windows 兼容**（DS review MINOR M3）：Windows 上可执行文件可能是
+ * `wecom-cli.exe` / `wecom-cli.cmd`，纯命令名探测必须带这些扩展名兜底，
+ * 否则在 Windows 上永远判定「找不到」。
+ *
+ * @param binName 二进制名（默认 `wecom-cli`）
+ */
+export declare function resolveWecomBinary(binName?: string): {
+    found: boolean;
+    path?: string;
+};
+/**
+ * 从自定义命令串里解析出「可执行文件」并探测是否存在。
+ *
+ * 自定义 command 的形态是 shell 命令串（`exec <cmd> <args...>`），
+ * 可能带 `exec ` 前缀与引号。这里只做**保守**判定：
+ * - 取第一个「像路径」的 token（含 `/`）
+ * - 若是绝对路径且不存在 → 判定不可用
+ * - 其它情况一律返回 found=true（不误伤，避免把正常命令判死）
+ *
+ * @returns found=false 表示该命令的绝对路径可执行文件不存在
+ */
+export declare function probeCommandBinary(command: string): {
+    found: boolean;
+    path?: string;
+};
+/** WsBridge 需要的最小 WebSocket 面（测试 mock 友好） */
+export interface WebSocketLike {
+    on(ev: string, cb: (...args: unknown[]) => void): void;
+    send(data: string): void;
+    close(): void;
+    terminate(): void;
+}
+/** 生产默认工厂：动态 import('ws')（bun/Node 双 runtime 兼容） */
+export declare function defaultWecomWsFactory(): Promise<(url: string) => WebSocketLike>;
+export declare const wecomCliHandler: EventSourceHandler;
+export {};

package/dist/env/event-source/wecom-cli-sender.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview Task #5174（用户明令 2026-11-08 11:29）— 企微出站发送器（CLI 主路径）
+ *
+ * ## 为什么改 CLI
+ *
+ * 用户明令：「彻底改造下回复出站用 cli 吧，已经验证可以收到消息了，不用 ws 回」。
+ * `wecom-cli auth init` 扫码授权已完成（auth show = authorized），CLI 出站实测
+ * `success: true`；WS 回帧（`aibot_respond_msg`）保留为 **fallback**。
+ *
+ * ## CLI 出站的三个硬约束（实测）
+ *
+ * 1. **msg_type 没有 text** —— 只支持 markdown / image / file / voice / video；
+ *    传 `text` 报「存在未知字段'text'」⇒ 统一用 `markdown`。
+ * 2. **chat_id 必须是真实 userid**（形如 `wotnB7Wg...`），WS 回调里的
+ *    `from.userid`（如 `DongZhaoKun`）会被拒（40073 非法的 chat_id）。
+ *    因此需要 `contact users search` 解析 + 内存缓存。
+ * 3. 响应是 JSON，成功形如 `{"success": true}`，失败形如
+ *    `{"error": {"code": ..., "message": ...}}`。
+ *
+ * @see Task #5173 操作记录 #40148（实测取证）
+ */
+/** 默认发送硬超时（CLI 正常 < 2s，15s 是充裕余量） */
+export declare const WECOM_CLI_SEND_TIMEOUT_MS = 15000;
+/** contact 解析硬超时 */
+export declare const WECOM_CLI_RESOLVE_TIMEOUT_MS = 15000;
+/**
+ * 解析 wecom-cli 可执行文件路径。
+ *
+ * 优先级：`WECOM_CLI_BIN` 环境变量 → `wecom-cli`（PATH）。
+ * 本机 CLI 是 npm 装的平台子包，未在 PATH 里时必须用 env 指定。
+ *
+ * ## ⚠️ 隔离 HOME 部署必读（Task #5174 实测）
+ *
+ * CLI 授权凭据在 `$HOME/.config/wecom/credentials.enc`。若 roy-agent 跑在
+ * 隔离 HOME（测试 / 多租户）下，**只拷 credentials.enc 无效** ——
+ * `auth show` 仍会报 unauthorized。
+ *
+ * CLI 支持 `WECOM_CLI_CONFIG_DIR` 覆盖配置目录，部署时设置它指向
+ * **已授权**的配置目录即可（本机示例：`/home/dzk/.config/wecom`）。
+ * 该变量由子进程从 `process.env` 继承，本模块无需显式处理。
+ */
+export declare function resolveWecomCliBinary(): string;
+/** 构造 `message aibot send` 的 argv（不含二进制名） */
+export declare function buildWecomCliSendArgs(input: {
+    chatId: string;
+    content: string;
+}): string[];
+/** 构造 `contact users search` 的 argv（用于把 WS userid 解析成 CLI chat_id） */
+export declare function buildWecomCliResolveArgs(keywords: string): string[];
+/**
+ * 解析 CLI 输出（stdout 是 JSON）。
+ *
+ * - `{"error": {...}}` → 失败（读 error.code / error.message）
+ * - `{"success": true}` → 成功
+ * - 无法 parse → 失败（把原文片段带出来便于排查）
+ */
+export declare function parseWecomCliResult(stdout: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** 从 contact search 输出解析真实 userid */
+export declare function parseWecomCliUserSearch(stdout: string, fallback: string): string;
+/** 测试用：清空解析缓存 */
+export declare function __resetWecomCliChatIdCacheForTest(): void;
+/**
+ * 把 WS 回调里的 userid 解析成 CLI 可用的 chat_id。
+ *
+ * 已有缓存 → 直接返回；否则 `contact users search --set keywords=<userid>`
+ * 取 `users[0].userid`；解析失败返回原值（让 CLI 自己报 40073，便于排障）。
+ */
+export declare function resolveWecomCliChatId(userId: string): Promise<string>;
+/**
+ * 用 CLI 发 markdown 消息（**永不抛**）。
+ *
+ * @returns `{ok:true}` / `{ok:false, error}`；调用方据此决定是否走 WS fallback
+ */
+export declare function sendWecomCliMarkdown(input: {
+    chatId: string;
+    content: string;
+    timeoutMs?: number;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/env/event-source/wecom-media.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Task #5199 — 企微媒体（图片/文件）下载解密落盘
+ *
+ * ## 背景（用户实测问题）
+ *
+ * 企微长连接模式下 `image`/`file`/`video` 消息只带：
+ * - `image_url`（或 `image.voice_url` 等）：加密媒体下载地址，
+ *   **5 分钟内有效**；
+ * - `aeskey`：Base64 编码的 AES 密钥。
+ *
+ * 此前 WecomWsBridge 只透传消息文本（图片 → `[image]` 占位符），
+ * agent 看不到图片内容（用户反馈：「收到图片但没获取到图片内容」）。
+ *
+ * ## 解密协议（官方文档 101463 + SDK 源码取证，Task #5142）
+ *
+ * - **AES-256-CBC**，PKCS#7 填充到 **32 字节倍数**（不是 Node 默认 16），
+ *   必须 `setAutoPadding(false)` + 手动去填充（对齐官方 SDK decryptFile）；
+ * - **IV = aeskey 解码后的前 16 字节**（aeskey 是 Base64 的 32 字节密钥）；
+ * - 下载 URL 5 分钟内有效 → 下载失败如实报错。
+ *
+ * @see wecom-cli-handler.ts（extractText 图片分支注入落盘路径）
+ * @see wecom-media.test.ts
+ */
+/** 默认媒体落盘目录 */
+export declare const WECOM_MEDIA_DIR = "/tmp/wecom-media";
+/** 测试注入媒体目录（生产勿用） */
+export declare function setWecomMediaDir(dir: string): string;
+/** 测试重置（恢复默认目录） */
+export declare function __resetWecomMediaDirForTest(): void;
+/** 当前生效的媒体目录 */
+export declare function getWecomMediaDir(): string;
+/**
+ * 解密企微媒体（AES-256-CBC，PKCS#7 32 字节块）。
+ *
+ * 对齐官方 SDK `decryptFile`（@wecom/aibot-node-sdk dist/index.cjs.js）：
+ * 1. aesKey 是 Base64 编码的 32 字节密钥；
+ * 2. IV = key 前 16 字节；
+ * 3. `setAutoPadding(false)`（Node 默认按 16 字节块去填充会 bad decrypt）；
+ * 4. 手动校验并去除 PKCS#7 填充（padLen ∈ [1,32]，全部字节一致）。
+ *
+ * @param encrypted 加密的媒体数据
+ * @param aesKeyBase64 Base64 编码的 aeskey（来自消息体 image.aeskey 等）
+ * @returns 解密后的明文 Buffer
+ * @throws 参数非法 / 密钥错误 / padding 损坏时抛错（不静默返回垃圾数据）
+ */
+export declare function decryptWecomMedia(encrypted: Buffer, aesKeyBase64: string): Buffer;
+/** 从消息体提取出的媒体引用 */
+export interface WecomMediaRef {
+    /** 媒体类型（image / file / video / voice） */
+    kind: "image" | "file" | "video" | "voice";
+    /** 加密媒体下载地址（5 分钟内有效） */
+    url: string;
+    /** Base64 编码的 AES 密钥 */
+    aeskey: string;
+    /** 原始文件名（file 类型才有） */
+    filename?: string;
+}
+/**
+ * 从企微消息体提取媒体引用（image / file / video / voice）。
+ *
+ * - 单媒体消息：body.image / body.file / body.video / body.voice；
+ * - mixed 消息：遍历 body.mixed.msg_item[]，收集所有媒体 item；
+ * - 缺 url 或缺 aeskey 的 item 跳过（不产生坏引用）。
+ */
+export declare function extractWecomMediaRefs(body: Record<string, unknown>): WecomMediaRef[];
+/** 下载器返回值（测试注入用） */
+export interface WecomMediaFetchResult {
+    ok: boolean;
+    status: number;
+    buffer: Buffer;
+    /** 从 Content-Disposition 解析的文件名（可选） */
+    filename?: string;
+}
+/** 下载器签名（生产用全局 fetch；测试注入 mock） */
+export type WecomMediaFetcher = (url: string) => Promise<WecomMediaFetchResult>;
+/** fetchAndSaveWecomMedia 入参 */
+export interface FetchWecomMediaInput {
+    msgid: string;
+    url: string;
+    aeskey: string;
+    kind: WecomMediaRef["kind"];
+    /** 下载器（测试注入；缺省用全局 fetch） */
+    fetcher?: WecomMediaFetcher;
+    /** 原始文件名（可选） */
+    filename?: string;
+    /**
+     * ★ Task #5313：会话 id —— 落盘子目录，实现跨群媒体隔离。
+     * 缺省时保持旧行为（直接落媒体根目录）。
+     */
+    chatId?: string;
+}
+/**
+ * 下载企微加密媒体 → 解密 → 落盘，返回本地路径。
+ *
+ * - 下载失败（HTTP 非 200）→ 抛错（URL 5 分钟有效，失败必须可见）；
+ * - 解密失败（aeskey 错误/数据损坏）→ 抛错（不落垃圾文件）；
+ * - 成功 → saveWecomMediaFile 落盘（msgid_filename）。
+ */
+export declare function fetchAndSaveWecomMedia(input: FetchWecomMediaInput): Promise<string>;
+/** saveWecomMediaFile 入参 */
+export interface SaveWecomMediaInput {
+    /** 消息 ID（文件名前缀，防同名覆盖） */
+    msgid: string;
+    /** 原始文件名（可缺省，用 msgid 兜底） */
+    filename?: string;
+    /** 解密后的媒体数据 */
+    buffer: Buffer;
+    /**
+     * ★ Task #5313：会话 id —— 落盘到 `<mediaDir>/<safeChatId>/` 子目录。
+     *
+     * 背景：此前所有会话共用一个扁平目录，mediaFiles 只按 msgid 区分，
+     * agent 扫目录时会把别的群的历史图片当成本条消息的附件。
+     * 按 chatId 分层后跨群天然隔离（整目录清理也更容易）。
+     *
+     * 缺省（undefined）→ 保持旧行为，直接落媒体根目录。
+     */
+    chatId?: string;
+}
+/**
+ * 把解密后的媒体数据落盘到媒体目录。
+ *
+ * - 目录：默认 `/tmp/wecom-media`（测试可注入）；传 chatId 时落到
+ *   `<mediaDir>/<chatId>/` 子目录（Task #5313 跨群隔离）；
+ * - 文件名：`<msgid>_<basename(filename)>`（路径穿越防护：
+ *   只取 basename，`../../etc/passwd` → `passwd`）；
+ * - 目录不存在时自动创建。
+ *
+ * @returns 落盘的绝对路径
+ */
+export declare function saveWecomMediaFile(input: SaveWecomMediaInput): Promise<string>;

package/dist/env/event-source/wecom-respond-registry.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Task #5174（用户明令 2026-11-08 11:29）— 企微回复注册表 + `wecom_respond` 工具
+ *
+ * ## 出站主路径 = wecom-cli（CLI 已授权）
+ *
+ * 用户明令：「彻底改造下回复出站用 cli 吧，已经验证可以收到消息了，不用 ws 回」。
+ *
+ * 发送顺序：
+ *   1. **CLI**（`wecom-cli message aibot send --msg-type markdown`）—— 主路径
+ *   2. **WS 回帧**（`aibot_respond_msg`，req_id 透传）—— CLI 失败时 fallback
+ *      （两者都不可用时如实报错，绝不假装已发送）
+ *
+ * ## chat_id 语义（实测硬约束）
+ *
+ * - WS 回调里的 `from.userid`（如 `DongZhaoKun`）**不是** CLI 可用的 chat_id
+ *   → CLI 报 40073「非法的 chat_id」
+ * - CLI 需要真实 userid（`wotnB7Wg...` 形态）→ 由 `contact users search` 解析
+ *   （`wecom-cli-sender.resolveWecomCliChatId`，带内存缓存）
+ *
+ * ## 注册表
+ *
+ * `WecomCliInstance.startWithBridge()` 把实例登记进来（`sourceId → target`），
+ * `stop()` 注销；工具通过 `EnvContext.sourceId` 反查，从而拿到：
+ * - `respond(reqId, body)` —— WS fallback
+ * - `sourceId` 对应的配置（CLI 出站不需要实例，但保留用于 fallback）
+ *
+ * @see wecom-cli-sender.ts（CLI 出站实现）
+ * @see wecom-ws-bridge.ts（WS 回帧 fallback）
+ */
+import type { Tool } from "../types";
+/** 注册表条目：WS fallback 所需的最小面 */
+export interface WecomRespondTarget {
+    /** 发送 WS 回帧（透传原消息 req_id）；返回错误而不抛（best-effort） */
+    respond(reqId: string, body: Record<string, unknown>): Error | undefined;
+    /**
+     * 主动推送帧（Task #5203：aibot_send_msg 直发 template_card）。
+     * 返回错误而不抛（best-effort）。
+     */
+    sendCmd?(cmd: string, body: Record<string, unknown>): Error | undefined;
+}
+/** 登记一个可回复的企微实例（sourceId → target） */
+export declare function registerWecomRespondTarget(sourceId: string, target: WecomRespondTarget): void;
+/** 注销（实例 stop 时调用） */
+export declare function unregisterWecomRespondTarget(sourceId: string): void;
+/** 查询（工具执行时用） */
+export declare function getWecomRespondTarget(sourceId: string): WecomRespondTarget | undefined;
+/** 测试用：清空注册表 */
+export declare function __resetWecomRespondRegistryForTest(): void;
+/** 出站发送入参 */
+export interface WecomSendInput {
+    /** 事件源 ID（用于查 WS fallback 实例） */
+    sourceId: string;
+    /** 原始 WS 回调的 userid / chatid（CLI 侧会自动解析成真实 userid） */
+    rawChatId: string;
+    /** 原消息帧 req_id（WS fallback 用） */
+    reqId?: string;
+    /** 回复正文 */
+    content: string;
+}
+/** 出站发送结果 */
+export interface WecomSendResult {
+    ok: boolean;
+    /** 实际走通的通道 */
+    channel?: "cli" | "ws";
+    /** 失败原因（两个通道都失败时给出合并说明） */
+    error?: string;
+}
+/**
+ * 发送企微回复：**被动回帧优先（有 reqId 时），CLI 兜底**（永不抛）。
+ *
+ * ## 为什么被动回帧优先（Task #5287 回复引用）
+ *
+ * 取证结论（官方文档 101463 + CLI schema 实查）：
+ * - 主动推送（CLI `message.aibot.send` / WS `aibot_send_msg`）schema
+ *   **无 quote/引用字段** —— 协议不支持发消息时主动引用某条消息；
+ * - 被动回复（WS `aibot_respond_msg`，headers.req_id 原样透传）时，
+ *   企微服务端**自动**把回复引用到触发回调的用户消息（群聊场景）。
+ *
+ * ⇒ 要让用户看到「回复引用了哪条消息」，必须走被动回帧。
+ *   因此有 reqId 且 WS 实例在线时**优先** WS 被动回帧；
+ *   CLI 降为 fallback（无 reqId / WS 失败 / 无实例时仍可用，
+ *   #5174「CLI 主路径」行为在无 reqId 场景不回归）。
+ *
+ * 发送顺序：
+ *   1. **WS 被动回帧**（reqId 存在 + 注册实例在线）—— 带引用语义
+ *   2. **CLI**（`wecom-cli message aibot send --msg-type markdown`）—— fallback
+ *   3. 都失败 → `{ok:false, error}`（两个原因都带上，便于排障）
+ */
+export declare function sendWecomReply(input: WecomSendInput): Promise<WecomSendResult>;
+/** 卡片直发入参 */
+export interface WecomTemplateCardSendInput {
+    /** 事件源 ID（查注册的 WS 实例） */
+    sourceId: string;
+    /** 会话 ID（单聊=userid，群聊=群 chatid） */
+    chatId: string;
+    /** 会话类型（决定 chat_type：1 单聊 / 2 群聊） */
+    chatType: "single" | "group";
+    /** 卡片结构体（wecom-card-builder 构造） */
+    card: Record<string, unknown>;
+}
+/**
+ * 经 WS 长连接直发 template_card（aibot_send_msg 主动推送）。
+ *
+ * ## 为什么不走 wecom-cli
+ *
+ * wecom-cli v1.3.4 的 msg_type 枚举只有 markdown/image/file/voice/video，
+ * 没封装 template_card（官方仓源码 grep 零命中，Task #5202 取证）。
+ * WS 协议原生支持 → 直发。
+ *
+ * best-effort：永不抛；失败返回 `{ok:false, error}`。
+ *
+ * ⚠️ 主动推送前提（官方 101463）：需用户先在会话中给机器人发过消息；
+ * 限频 30 条/分钟、1000 条/小时（调用方节流）。
+ */
+export declare function sendWecomTemplateCard(input: WecomTemplateCardSendInput): Promise<WecomSendResult>;
+/**
+ * `wecom_respond` —— 回复企微用户（CLI 主路径，WS fallback）。
+ *
+ * 参数：
+ * - `content`：回复正文（markdown）
+ * - `chat_id`：**可选**，回复目标；缺省时从 EnvContext 事件 metadata 取
+ *   （单聊=senderId；群聊=chatid）。CLI 侧会自动解析成真实 userid。
+ * - `req_id`：**可选**，原消息帧 req_id（WS fallback 用）；缺省从 metadata.reqId 取
+ */
+export declare const wecomRespondTool: Tool;
+/** 标记本轮已发送（wecom_respond 工具成功时调用） */
+export declare function markWecomReplySent(explicitBag?: Record<string, unknown>): void;
+/** 本轮是否已发送过 */
+export declare function wasWecomReplySent(explicitBag?: Record<string, unknown>): boolean;
+/** 测试用：清空标记 */
+export declare function __resetWecomReplySentForTest(explicitBag?: Record<string, unknown>): void;
+/**
+ * 框架级兜底：turn 结束后，若本轮没发过回复且事件来自企微 → 直接把
+ * assistant 的最终文本发出去（CLI 主路径 → WS fallback）。
+ *
+ * 触发条件（全部满足）：
+ * 1. `envEvent.type === "event-source.event.wecom-cli"`
+ * 2. 最终文本非空
+ * 3. 本轮**尚未**通过 `wecom_respond` 工具发送（避免双发）
+ *
+ * @returns 发送结果；不满足触发条件时返回 `{skipped: true}`
+ */
+export declare function autoReplyWecomTurn(envEvent: unknown, finalText: string): Promise<{
+    skipped: true;
+    reason: string;
+} | {
+    skipped: false;
+    ok: boolean;
+    channel?: "cli" | "ws";
+    error?: string;
+}>;