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

package/dist/env/event-source/wecom-card-builder.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @fileoverview Task #5203 — 企微真卡片（template_card）构造器
+ *
+ * ## 为什么存在
+ *
+ * #5193 用 markdown 模拟进展卡片（wecom-cli msg_type 无 template_card）。
+ * Task #5202 官方文档实锤：aibot WS 长连接协议**原生支持** template_card
+ * （aibot_send_msg 直发 + aibot_respond_update_msg 更新）——
+ * wecom-cli 只是没封装，走 WecomWsBridge 直发即可。
+ *
+ * ## 协议依据（官方文档取证，Task #5202/#5203）
+ *
+ * - 主动推送（101463）：`{cmd:"aibot_send_msg", headers:{req_id},
+ *   body:{chatid, chat_type, msgtype:"template_card", template_card:{...}}}`
+ *   chat_type：1 单聊（userid）/ 2 群聊 / 0 兼容
+ * - 模板卡片类型（101032）：
+ *   - text_notice：main_title / emphasis_content 必填，card_action 必填
+ *   - button_interaction：main_title / button_list / task_id 必填，
+ *     button_list ≤6，按钮 key 最长 1024 字节不可重复
+ *   - task_id：同一个机器人不能重复，只能由数字字母和 "_-@" 组成，≤128 字节
+ * - 卡片更新（101463）：`{cmd:"aibot_respond_update_msg",
+ *   headers:{req_id:事件回调透传}, body:{response_type:"update_template_card",
+ *   template_card:{...}}}` — 仅适用于 template_card_event，5 秒内回复；
+ *   template_card.task_id 须与回调收到的 task_id 一致
+ * - 按钮点击回调：template_card_event，event.event_key = 按钮 key
+ *
+ * ## task_id 策略
+ *
+ * 企微的 task_id 是「同一张卡的标识」（更新时用），而我们的任务
+ * 生命周期会**多次发卡**（每次进展一张新卡，企微无主动 patch）。
+ * ⇒ 发卡时用 `newWecomCardTaskId(taskId)`（带序号/时间戳，保证不重复）；
+ *   更新时必须用**回调里带回的 task_id**（buildWecomCardUpdateFrame 的
+ *   taskId 参数 = 回调解析出的原始 task_id）。
+ *
+ * @see wecom-ws-bridge.ts（帧发送）
+ * @see wecom-task-notify-plugin.ts（hook 接线）
+ */
+/** 标准按钮动作 key（回调 event_key 据此分发） */
+export declare const WecomCardActionKey: {
+    /** 查看详情 */
+    readonly VIEW: "task_view";
+    /** 标记完成 */
+    readonly MARK_DONE: "task_mark_done";
+    /** 重新打开 */
+    readonly REOPEN: "task_reopen";
+};
+export type WecomCardActionKey = (typeof WecomCardActionKey)[keyof typeof WecomCardActionKey];
+/** 企微按钮 style：1 默认蓝 / 2 次要灰 / 3 / 4 强调（官方 1~4） */
+export type WecomButtonStyle = 1 | 2 | 3 | 4;
+export interface WecomCardButton {
+    text: string;
+    style?: WecomButtonStyle;
+    key: string;
+}
+export interface WecomHorizontalContent {
+    keyname: string;
+    value: string;
+    type?: 0 | 1;
+    url?: string;
+}
+export interface WecomMilestoneLite {
+    title: string;
+    timestamp: string;
+    description?: string;
+}
+/** text_notice 卡片结构（只声明我们用到的字段） */
+export interface WecomTextNoticeCard {
+    card_type: "text_notice";
+    main_title: {
+        title: string;
+        desc?: string;
+    };
+    emphasis_content: {
+        title: string;
+        desc: string;
+    };
+    sub_title_text?: string;
+    horizontal_content_list: WecomHorizontalContent[];
+    quote_area: {
+        type?: number;
+        title: string;
+        quote_text: string;
+    };
+    card_action: {
+        type: number;
+        url?: string;
+    };
+}
+/** button_interaction 卡片结构（只声明我们用到的字段） */
+export interface WecomButtonInteractionCard {
+    card_type: "button_interaction";
+    main_title: {
+        title: string;
+        desc?: string;
+    };
+    sub_title_text?: string;
+    horizontal_content_list?: WecomHorizontalContent[];
+    quote_area?: {
+        type?: number;
+        title: string;
+        quote_text: string;
+    };
+    button_list: WecomCardButton[];
+    card_action?: {
+        type: number;
+        url?: string;
+    };
+    /** ★ 必填：同一机器人不能重复；更新时须与回调一致 */
+    task_id: string;
+}
+/**
+ * 任务的稳定 task_id 前缀：`roy-task-<taskId>`。
+ *
+ * 用途：
+ * - 发卡时作为 `newWecomCardTaskId` 的前缀（可从回调 task_id 反解任务号）
+ * - 更新时**不能**用它（发卡用的是带序号的全量 id）——
+ *   更新帧的 task_id 必须原样用回调带回的值
+ */
+export declare function wecomCardTaskIdForTask(taskId: number): string;
+/**
+ * 生成一张新卡的 task_id：`roy-task-<taskId>-<seq>-<rand>`。
+ *
+ * 协议硬约束：同一机器人不能重复 → 加序号 + 随机后缀。
+ * 字符集：数字字母和 "_-@"（官方 101032）。
+ */
+export declare function newWecomCardTaskId(taskId: number): string;
+/**
+ * 构造 text_notice 进展卡（任务状态一览）。
+ *
+ * 信息密度对齐 #5193 markdown 卡：标题+进度+状态+时间线+最新操作。
+ */
+export declare function buildWecomTextNoticeCard(input: {
+    taskId: number;
+    title: string;
+    statusLabel: string;
+    progress: number;
+    description?: string;
+    changeSummary?: string;
+    milestones: WecomMilestoneLite[];
+    /** 终态（completed/cancelled/…）→ sub_title_text 收尾文案 */
+    terminal?: boolean;
+}): WecomTextNoticeCard;
+/**
+ * 构造 button_interaction 交互卡（可点击按钮更新状态）。
+ *
+ * @param input.taskId 用于生成 task_id（回调据此反解任务）
+ * @param input.buttons 超过 6 个时只取前 6 个（协议上限）
+ */
+export declare function buildWecomButtonInteractionCard(input: {
+    taskId: number;
+    title: string;
+    statusLabel: string;
+    progress: number;
+    description?: string;
+    changeSummary?: string;
+    milestones?: WecomMilestoneLite[];
+    buttons: WecomCardButton[];
+    /** 已有的 task_id（更新场景复用；发新卡时不传自动生成） */
+    cardTaskId?: string;
+}): WecomButtonInteractionCard;
+/**
+ * 构造 aibot_send_msg 直发 template_card 帧。
+ *
+ * @param input.chatType "single"（chat_type=1，chatid=userid）|
+ *                      "group"（chat_type=2，chatid=群 chatid）
+ */
+export declare function buildWecomSendCardFrame(input: {
+    chatId: string;
+    chatType: "single" | "group";
+    card: WecomTextNoticeCard | WecomButtonInteractionCard;
+    /** 显式 req_id（缺省自动生成 aibot_send_msg_ 前缀） */
+    reqId?: string;
+}): {
+    cmd: string;
+    headers: {
+        req_id: string;
+    };
+    body: Record<string, unknown>;
+};
+/**
+ * 构造 aibot_respond_update_msg 更新帧（按钮点击后 5 秒窗口内）。
+ *
+ * ★ 协议硬约束：
+ * - req_id 必须**原样透传** template_card_event 回调帧的 req_id
+ * - template_card.task_id 必须与回调收到的 task_id 一致
+ *   （回调的 task_id 是发卡时的全量 id，不是 roy-task-<n> 前缀）
+ *
+ * @param input.taskId 回调解析出的**原始** task_id（原样回填）
+ */
+export declare function buildWecomCardUpdateFrame(input: {
+    reqId: string;
+    /** 回调带回的原始 task_id（原样回填，不做转换） */
+    taskId: string;
+    statusLabel: string;
+    note?: string;
+    /** 更新后的按钮列表（如把「标记完成」换成「已确认」） */
+    buttonOverrides?: WecomCardButton[];
+    /**
+     * ★ Task #5203 时间线详情：操作记录（milestones + processSteps）
+     * 渲染成 quote_area 引用文本（每行一条，最新在上）。
+     */
+    timeline?: WecomMilestoneLite[];
+    /**
+     * ★ Task #5273：任务标题（可选）。
+     *
+     * 用户反馈更新卡缺任务号/标题 → main_title 从
+     * `📋 ${statusLabel}` 升级为
+     * `📋 Task #<n> · <title> · ${statusLabel}`（缺省字段自动省略，
+     * 向后兼容旧调用方）。
+     */
+    taskTitle?: string;
+    /** ★ Task #5273：roy 任务号（可选，与 taskTitle 配对渲染） */
+    taskNumber?: number;
+}): {
+    cmd: string;
+    headers: {
+        req_id: string;
+    };
+    body: Record<string, unknown>;
+};

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

@@ -0,0 +1,266 @@
+/**
+ * @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;
+}
+/**
+ * 构造企微的 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;
+/** 企微渠道 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;
+}>;