@imweapp/openclaw-imwe 2026.4.12-alpha.4 → 2026.4.12-alpha.5

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * index.ts — 插件主入口（full 模式）
+ *
+ * 使用 defineChannelPluginEntry 定义入口。
+ * AppKey/AppSecret 签名认证无需 runtime 注入，故省略 setRuntime。
+ */
+import { defineChannelPluginEntry } from 'openclaw/plugin-sdk/channel-core';
+import { imwePlugin } from './src/channel.js';
+export default defineChannelPluginEntry({
+    id: 'imwe',
+    name: 'imwe',
+    description: 'imwe 即时通讯渠道插件，AppKey/AppSecret 签名认证，支持多账号',
+    plugin: imwePlugin,
+});

package/dist/setup-entry.js

@@ -0,0 +1,15 @@
+/**
+ * setup-entry.ts — 轻量入口（setup-only 模式）
+ *
+ * 当渠道未配置或被禁用时，core 加载这个文件而不是 index.ts。
+ * defineSetupPluginEntry 只暴露 ChannelPlugin 对象（用于 setup wizard），
+ * 不注入 runtime，不注册 CLI，不加载任何运行时代码。
+ *
+ * 这样做的好处：
+ *   - 节省内存：不加载 monitor.ts、api-client.ts 等重量级模块
+ *   - 加快启动：setup 流程不需要建立网络连接
+ *   - 安全隔离：未配置的渠道不会尝试连接平台
+ */
+import { defineSetupPluginEntry } from 'openclaw/plugin-sdk/channel-core';
+import { imwePlugin } from './src/channel.js';
+export default defineSetupPluginEntry(imwePlugin);

package/dist/src/accounts.js

@@ -0,0 +1,95 @@
+/**
+ * accounts.ts — 账号解析逻辑
+ *
+ * 职责：
+ *   - 从 OpenClawConfig 中读取 imwe 渠道配置
+ *   - 合并顶层默认值与账号级配置（多账号继承）
+ *   - 解析 appKey / appSecret（优先级：账号级 config > 顶层 config > 环境变量）
+ *   - 导出 listImweAccountIds / resolveImweAccount 供 ChannelConfigAdapter 使用
+ */
+import { createAccountListHelpers, resolveMergedAccountConfig, } from 'openclaw/plugin-sdk/account-helpers';
+import { normalizeAccountId } from 'openclaw/plugin-sdk/account-id';
+import { coerceSecretRef } from 'openclaw/plugin-sdk/provider-auth';
+// ─────────────────────────────────────────────────────────────────────────────
+// 账号 id 列表工具
+// ─────────────────────────────────────────────────────────────────────────────
+const { listAccountIds: listImweAccountIds, resolveDefaultAccountId: resolveDefaultImweAccountId } = createAccountListHelpers('imwe');
+export { listImweAccountIds, resolveDefaultImweAccountId };
+// ─────────────────────────────────────────────────────────────────────────────
+// 配置合并
+// ─────────────────────────────────────────────────────────────────────────────
+function mergeImweAccountConfig(cfg, accountId) {
+    return resolveMergedAccountConfig({
+        channelConfig: cfg.channels?.imwe,
+        accounts: cfg.channels?.imwe?.accounts,
+        accountId,
+        omitKeys: ['defaultAccount'],
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// SecretRef 解析 helper
+// ─────────────────────────────────────────────────────────────────────────────
+/** 将纯字符串或 SecretRef 对象解析为字符串值。env 类型 ref 从 process.env 读取。 */
+function resolveSecretLike(value) {
+    if (value != null && typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    const ref = coerceSecretRef(value);
+    if (!ref)
+        return undefined;
+    // env 类型 SecretRef 从 process.env 读取
+    if (ref.source === 'env') {
+        return process.env[ref.id]?.trim() || undefined;
+    }
+    return undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 凭证解析：优先级 账号级 config > 顶层 config > 环境变量
+// ─────────────────────────────────────────────────────────────────────────────
+function resolveImweCredentials(merged, accountId) {
+    // 1. config 里的 appKey + appSecret（支持 SecretRef）
+    const configKey = resolveSecretLike(merged.appKey);
+    const configSecret = resolveSecretLike(merged.appSecret);
+    if (configKey && configSecret) {
+        return { appKey: configKey, appSecret: configSecret, source: 'config' };
+    }
+    // 2. 环境变量（仅 default 账号，避免多账号混用同一组 env）
+    if (normalizeAccountId(accountId) === 'default') {
+        const envKey = process.env.IMWE_APP_KEY?.trim();
+        const envSecret = process.env.IMWE_APP_SECRET?.trim();
+        if (envKey && envSecret) {
+            return { appKey: envKey, appSecret: envSecret, source: 'env' };
+        }
+    }
+    return { appKey: '', appSecret: '', source: 'none' };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 主解析函数
+// ─────────────────────────────────────────────────────────────────────────────
+export function resolveImweAccount(params) {
+    const accountId = normalizeAccountId(params.accountId) ??
+        normalizeAccountId(params.cfg.channels?.imwe?.defaultAccount) ??
+        'default';
+    const baseEnabled = params.cfg.channels?.imwe?.enabled !== false;
+    const merged = mergeImweAccountConfig(params.cfg, accountId);
+    const accountEnabled = merged.enabled !== false;
+    const { appKey, appSecret, source } = resolveImweCredentials(merged, accountId);
+    const apiBaseUrl = merged.apiBaseUrl?.trim() || process.env.IMWE_API_BASE_URL?.trim() || '';
+    return {
+        accountId,
+        name: merged.name,
+        enabled: baseEnabled && accountEnabled,
+        apiBaseUrl,
+        appKey,
+        appSecret,
+        credentialSource: source,
+        config: merged,
+    };
+}
+export function listEnabledImweAccounts(cfg) {
+    return listImweAccountIds(cfg)
+        .map((accountId) => resolveImweAccount({ cfg, accountId }))
+        .filter((account) => account.enabled);
+}

package/dist/src/api-client.js

@@ -0,0 +1,498 @@
+/**
+ * api-client.ts — imwe Open API HTTP 客户端
+ *
+ * 对应接口文档：docs/02-OpenAPI接口设计.md
+ * Base URL：/api/im/open/bot
+ *
+ * ── 传输格式 ──────────────────────────────────────────────────────────────────
+ *   sendMessage / pullMessages：application/x-protobuf
+ *   getMe 等 JSON 接口：        application/json
+ *
+ * ── 鉴权机制（文档 §1） ───────────────────────────────────────────────────────
+ *   每个请求携带三个 Header：
+ *     X-Api-Key:   API Key（ak_ 前缀）
+ *     X-Timestamp: 毫秒级时间戳字符串
+ *     X-Signature: Base64(HMAC-SHA256(apiSecret, signString))
+ *
+ *   签名原文（signString）：
+ *     {METHOD}&{PATH}&{TIMESTAMP}&{BODY_HASH}
+ *     BODY_HASH = hex(SHA-256(body))，body 为空时对空字符串 "" 哈希
+ *
+ * ── 设计原则 ──────────────────────────────────────────────────────────────────
+ *   - 纯函数，不持有状态
+ *   - Protobuf encode/decode 集中在 src/proto/codec.ts，此文件只负责 HTTP 传输
+ *   - 请求失败时抛出带 HTTP 状态码的 Error，由上层决定是否重试
+ */
+import { createHmac, createHash, randomUUID } from 'node:crypto';
+import { decodeSendResponse, encodeSendRequest, encodeMediaSendRequest, encodeMarkdownSendRequest, encodeTypingSignalRequest, decodeInboundPacket, genClientMsgId, } from './proto/codec.js';
+import { decodeInboundPacketWithE2ee } from './proto/inbound.codec.js';
+import { getRegistry } from './proto/registry.js';
+import { uploadMediaToStorage } from './media-upload.js';
+import { inferMediaType, inferMediaTypeFromMime } from './media-utils.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// 签名工具（文档 §1.2）
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 计算请求签名。
+ *
+ * 签名原文：{METHOD}&{PATH}&{TIMESTAMP}&{BODY_HASH}
+ *   - METHOD：HTTP 方法大写，固定为 "POST"
+ *   - PATH：请求路径，如 "/api/im/open/bot/sendMessage"
+ *   - TIMESTAMP：与 X-Timestamp Header 相同的毫秒时间戳字符串
+ *   - BODY_HASH：hex(SHA-256(body))，body 为空时对空字符串 "" 哈希
+ *
+ * 签名算法：Base64(HMAC-SHA256(apiSecret, signString))
+ *
+ * @param params.apiSecret  API Secret（创建机器人时返回，明文仅展示一次）
+ * @param params.method     HTTP 方法（大写），通常为 "POST"
+ * @param params.path       请求路径，如 "/api/im/open/bot/sendMessage"
+ * @param params.timestamp  毫秒时间戳字符串，与 X-Timestamp Header 一致
+ * @param params.body       请求体字节（Protobuf 二进制或 JSON 字符串的 UTF-8 编码）
+ * @returns Base64 编码的 HMAC-SHA256 签名字符串
+ */
+export function buildSignature(params) {
+    // 1. 计算请求体的 SHA-256 哈希（小写 hex）
+    //    body 为空时对空字符串 "" 哈希（SHA-256("") 是固定值）
+    const bodyHash = createHash('sha256').update(params.body).digest('hex');
+    // 2. 拼接签名原文
+    const signString = [params.method, params.path, params.timestamp, bodyHash].join('&');
+    // 3. HMAC-SHA256 签名，输出 Base64
+    return createHmac('sha256', params.apiSecret).update(signString, 'utf8').digest('base64');
+}
+/**
+ * 构造鉴权 Header 集合。
+ *
+ * @param apiKey    API Key（ak_ 前缀）
+ * @param apiSecret API Secret
+ * @param method    HTTP 方法（大写）
+ * @param path      请求路径（含前导 /）
+ * @param body      请求体字节
+ * @returns 包含 X-Api-Key / X-Timestamp / X-Signature 的 Header 对象
+ */
+function buildAuthHeaders(apiKey, apiSecret, method, path, body) {
+    // 毫秒级时间戳（文档要求毫秒，服务端校验 5 分钟窗口）
+    const timestamp = String(Date.now());
+    const signature = buildSignature({ apiSecret, method, path, timestamp, body });
+    return {
+        'X-Api-Key': apiKey,
+        'X-Timestamp': timestamp,
+        'X-Signature': signature,
+        reqid: randomUUID().replaceAll('-', ''),
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 内部工具：统一 HTTP 请求
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 发送 Protobuf 二进制请求，返回响应体字节。
+ *
+ * Content-Type: application/x-protobuf
+ * Accept:       application/x-protobuf
+ *
+ * @param apiBaseUrl  API 基础地址，如 https://api.imwe.example.com
+ * @param path        请求路径，如 /api/im/open/bot/sendMessage
+ * @param body        Protobuf 编码的请求体
+ * @param auth        鉴权凭证（apiKey + apiSecret）
+ * @param opts.timeoutMs  请求超时（毫秒），默认不超时
+ * @throws 非 2xx 响应时抛出包含状态码的 Error
+ */
+export async function postProto(apiBaseUrl, path, body, auth, opts) {
+    const url = `${apiBaseUrl.replace(/\/$/, '')}${path}`;
+    const controller = new AbortController();
+    const timer = opts?.timeoutMs ? setTimeout(() => controller.abort(), opts.timeoutMs) : null;
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-protobuf',
+                Accept: 'application/x-protobuf',
+                ...buildAuthHeaders(auth.apiKey, auth.apiSecret, 'POST', path, body),
+            },
+            body: body,
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const errText = await res.text().catch(() => '');
+            throw new Error(`imwe API ${path} 返回 ${res.status}: ${errText}`);
+        }
+        const buf = await res.arrayBuffer();
+        return new Uint8Array(buf);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * 发送 JSON 请求，返回解析后的 JSON 对象。
+ *
+ * Content-Type: application/json
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param path        请求路径
+ * @param body        请求体对象（会被 JSON.stringify）
+ * @param auth        鉴权凭证
+ * @param opts.timeoutMs  请求超时（毫秒）
+ * @throws 非 2xx 响应时抛出包含状态码的 Error
+ */
+export async function postJson(apiBaseUrl, path, body, auth, opts) {
+    const url = `${apiBaseUrl.replace(/\/$/, '')}${path}`;
+    const bodyStr = JSON.stringify(body);
+    const bodyBytes = new TextEncoder().encode(bodyStr);
+    const controller = new AbortController();
+    const timer = opts?.timeoutMs ? setTimeout(() => controller.abort(), opts.timeoutMs) : null;
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                ...buildAuthHeaders(auth.apiKey, auth.apiSecret, 'POST', path, bodyBytes),
+            },
+            body: bodyStr,
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const errText = await res.text().catch(() => '');
+            throw new Error(`imwe API ${path} 返回 ${res.status}: ${errText}`);
+        }
+        return res.json();
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// getJson — 签名 GET 请求（JSON 响应）
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 发送带签名的 GET 请求，返回 JSON 响应。
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param path        请求路径
+ * @param auth        鉴权凭证
+ * @param opts.timeoutMs  请求超时（毫秒）
+ * @throws 非 2xx 响应时抛出包含状态码的 Error
+ */
+export async function getJson(apiBaseUrl, path, auth, opts) {
+    const url = `${apiBaseUrl.replace(/\/$/, '')}${path}`;
+    const emptyBody = new Uint8Array(0);
+    const controller = new AbortController();
+    const timer = opts?.timeoutMs ? setTimeout(() => controller.abort(), opts.timeoutMs) : null;
+    try {
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: {
+                Accept: 'application/json',
+                ...buildAuthHeaders(auth.apiKey, auth.apiSecret, 'GET', path, emptyBody),
+            },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const errText = await res.text().catch(() => '');
+            throw new Error(`imwe API ${path} 返回 ${res.status}: ${errText}`);
+        }
+        return res.json();
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * 获取当前机器人信息。
+ *
+ * 对应接口：POST /api/im/open/bot/getMe
+ * 返回的 botAcctId 是机器人的 mainAcctId，pullMessages 时作为 boxId 使用。
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @returns 机器人信息
+ * @throws 鉴权失败或网络错误时抛出 Error
+ */
+export async function getMe(apiBaseUrl, auth) {
+    return postJson(apiBaseUrl, '/api/im/open/bot/getMe', {}, auth);
+}
+/**
+ * 通过事件箱模式拉取机器人待处理消息。
+ *
+ * 对应接口：POST /api/im/open/bot/pullMessages
+ * 请求体：PbBoxPullReq（直接序列化，不包装在 PbPacket 中）
+ * 响应体：PbBoxPullRsp
+ *
+ * 增量拉取流程：
+ *   1. 首次调用：state.nextStartSeq=0，拉取全部历史消息
+ *   2. 响应 milestone=true：将 endSeq 落库，下次从 endSeq+1 开始
+ *   3. 响应 hasMore=true：立即继续拉取（调用方负责循环）
+ *   4. 响应 endSeq=0：无新消息
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param boxId       事件箱 ID（机器人的 botAcctId/mainAcctId，来自 getMe 响应）
+ * @param state       拉取状态（含 nextStartSeq，调用方负责持久化）
+ * @returns 解包后的消息列表、更新后的状态、是否还有更多数据
+ */
+export async function pullMessages(apiBaseUrl, auth, boxId, state, opts) {
+    const reg = await getRegistry();
+    // 构造 PbBoxPullReq
+    const reqMsg = reg.PbBoxPullReq.create({
+        boxId,
+        startSeq: state.nextStartSeq,
+    });
+    const requestBody = reg.PbBoxPullReq.encode(reqMsg).finish();
+    const responseBytes = await postProto(apiBaseUrl, '/api/im/open/bot/pullMessages', requestBody, auth);
+    // 解码 PbBoxPullRsp
+    // protobufjs 将 uint64 字段解码为 Long 对象（来自 long 包），用 Number() 转换为 number
+    const rsp = reg.PbBoxPullRsp.decode(responseBytes);
+    // Long 对象用 toNumber()，普通 number 直接用，统一转为 number
+    const toNum = (v) => v == null ? 0 : typeof v === 'number' ? v : v.toNumber();
+    const endSeq = toNum(rsp.endSeq);
+    const hasMore = rsp.hasMore ?? false;
+    // milestone=true 且 endSeq>0 时更新游标，下次从 endSeq+1 开始
+    const nextStartSeq = rsp.milestone && endSeq > 0 ? endSeq + 1 : state.nextStartSeq;
+    // 解包每条消息：item.body → PbChatMsgDeliverBody → PbChatMsgEnvelope → text
+    const messages = [];
+    for (const item of rsp.items ?? []) {
+        if (!item.body || item.body.length === 0) {
+            continue;
+        }
+        // item.body 是 PbChatMsgDeliverBody 的字节，需要包装成 PbPacket(SERVER_REQ) 再走四层解包
+        // 按文档：items[].request.body 为 PbChatMsgDeliverBody
+        // 构造一个虚拟的 PbPacket(SERVER_REQ) 供 decodeInboundPacket 使用
+        const requestMsg = reg.PbRequest.create({
+            path: '/chat/deliver',
+            reqId: item.reqId ?? '',
+            reqStamp: toNum(item.reqStamp),
+            body: item.body,
+        });
+        const requestBytes = reg.PbRequest.encode(requestMsg).finish();
+        const packetMsg = reg.PbPacket.create({
+            type: 2, // SERVER_REQ
+            request: reg.PbRequest.decode(requestBytes),
+        });
+        const packetBytes = reg.PbPacket.encode(packetMsg).finish();
+        const result = opts?.e2eeDecrypt
+            ? await decodeInboundPacketWithE2ee(packetBytes, { e2eeDecrypt: opts.e2eeDecrypt })
+            : await decodeInboundPacket(packetBytes);
+        if (result.ok) {
+            messages.push(result.message);
+        }
+        // result.ok=false 时静默跳过（操作消息、非文本消息、decrypt-failed、operation-consumed 等）
+    }
+    return {
+        messages,
+        state: { nextStartSeq },
+        hasMore,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// sendMessage — 发送单聊消息（文档 §一）
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 向用户发送单聊文字消息。
+ *
+ * 对应接口：POST /api/im/open/bot/sendMessage
+ * 请求体：PbPacket(CLIENT_REQ) 四层包装（由 encodeSendRequest 生成）
+ * 响应体：PbResponse 的 protobuf 二进制（statusCode + body），body 为 PbMsgRspBody
+ *
+ * 四层包装链路（由 send.codec.ts 负责）：
+ *   PbChatTextContent(text)
+ *     → PbChatMsgEnvelope(textContent)
+ *       → PbSingleChatMsgReqBody(fromId, toId, envelopeType=1, e2eeFlag=false, envelope)
+ *         → PbRequest(path="/api/im/chat/bot", body)
+ *           → PbPacket(type=CLIENT_REQ=0, request)
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param fromId      发送方 ID（机器人的 botAcctId，来自 getMe 响应）
+ * @param to          接收方用户 ID
+ * @param text        消息文本内容
+ * @returns 发送结果
+ */
+export async function sendTextMessage(apiBaseUrl, auth, fromId, to, text, options) {
+    const clientMsgId = options?.clientMsgId ?? genClientMsgId();
+    // encodeSendRequest 负责四层包装，fromId 传入供 PbSingleChatMsgReqBody 使用
+    const requestBody = await encodeSendRequest(to, text, fromId, {
+        referenceClientMsgId: options?.replyToId,
+        clientMsgId,
+    });
+    const responseBytes = await postProto(apiBaseUrl, '/api/im/open/bot/sendMessage', requestBody, auth);
+    return {
+        ...(await decodeSendResponse(responseBytes)),
+        clientMsgId,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// sendMediaMessage — 发送多媒体消息（文档 §一）
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 向用户发送多媒体消息（图片/视频/音频/文件）。
+ *
+ * 使用与 sendTextMessage 相同的 HTTP 接口和鉴权机制，
+ * 区别在于 PbChatMsgEnvelope 的 oneof 字段为 richMediaContent/fileContent/audioContent。
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param media       多媒体消息参数（含 to、url、mediaType 等）
+ * @returns 发送结果
+ */
+export async function sendMediaMessage(apiBaseUrl, auth, media) {
+    const clientMsgId = media.clientMsgId ?? genClientMsgId();
+    const requestBody = await encodeMediaSendRequest({
+        ...media,
+        clientMsgId,
+    });
+    const responseBytes = await postProto(apiBaseUrl, '/api/im/open/bot/sendMessage', requestBody, auth);
+    return {
+        ...(await decodeSendResponse(responseBytes)),
+        clientMsgId,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// sendMarkdownMessage — 发送 markdown 消息（文档 §一）
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 向用户发送 markdown 格式消息。
+ *
+ * 使用与 sendTextMessage / sendMediaMessage 相同的 HTTP 接口和鉴权机制，
+ * 区别在于 PbChatMsgEnvelope 的 oneof 字段为 markdownContent（字段 16）。
+ *
+ * 四层包装链路（由 send.codec.ts::encodeMarkdownSendRequest 负责）：
+ *   PbMarkdownContent(digest, markdown)
+ *     → PbChatMsgEnvelope(markdownContent=...)
+ *       → PbSingleChatMsgReqBody(envelopeType=1, e2eeFlag=false)
+ *         → PbRequest(path="/api/im/chat/bot")
+ *           → PbPacket(type=CLIENT_REQ=0)
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param params      markdown 消息参数：fromId / to / markdown / digest? / clientMsgId?
+ * @returns 发送结果
+ */
+export async function sendMarkdownMessage(apiBaseUrl, auth, params) {
+    const clientMsgId = params.clientMsgId ?? genClientMsgId();
+    const requestBody = await encodeMarkdownSendRequest({
+        to: params.to,
+        fromId: params.fromId,
+        markdown: params.markdown,
+        digest: params.digest,
+        clientMsgId,
+    });
+    const responseBytes = await postProto(apiBaseUrl, '/api/im/open/bot/sendMessage', requestBody, auth);
+    return {
+        ...(await decodeSendResponse(responseBytes)),
+        clientMsgId,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// sendMediaMessageWithUpload — 上传并发送多媒体消息（deliver 回调专用）
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 上传并发送多媒体消息。
+ *
+ * 与 sendMediaMessage 的区别：包含 uploadMediaToStorage 上传步骤。
+ * 与 sendImweMedia（send.ts）的区别：不走账号解析，直接接收已解析的连接参数。
+ * 适用于 monitor.ts 的 deliver 回调，此时账号信息已在上下文中。
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param fromId      发送方 ID（机器人的 botAcctId）
+ * @param to          接收方用户 ID
+ * @param mediaUrl    媒体文件 URL（本地路径或远程 URL）
+ * @param options     可选参数（caption 等）
+ * @returns 发送结果
+ */
+export async function sendMediaMessageWithUpload(apiBaseUrl, auth, fromId, to, mediaUrl, options) {
+    const log = options?.log;
+    // 上传到平台存储
+    log?.info?.(`[sendMediaMessageWithUpload] 开始上传: mediaUrl=${mediaUrl.slice(0, 80)}, to=${to}`);
+    const uploadResult = await uploadMediaToStorage(mediaUrl, auth, apiBaseUrl, {
+        imMainAccId: to,
+        log,
+    });
+    log?.info?.(`[sendMediaMessageWithUpload] 上传完成: url=${uploadResult.url.slice(0, 80)}, contentType=${uploadResult.contentType}, fileSize=${uploadResult.fileSize}`);
+    // 优先从上传结果的 contentType 推断媒体类型，回退到原始 URL 后缀推断
+    // 注意：不能用 uploadResult.url（CDN URL 可能无扩展名，会永远回退为 'file'）
+    const mediaType = uploadResult.contentType
+        ? inferMediaTypeFromMime(uploadResult.contentType)
+        : inferMediaType(mediaUrl);
+    log?.info?.(`[sendMediaMessageWithUpload] 推断 mediaType=${mediaType}, 准备发送`);
+    return sendMediaMessage(apiBaseUrl, auth, {
+        to,
+        fromId,
+        url: uploadResult.url,
+        mediaType,
+        mimeType: uploadResult.contentType,
+        fileSize: uploadResult.fileSize,
+        caption: options?.caption,
+        blurHash: uploadResult.blurHash,
+        width: uploadResult.width,
+        height: uploadResult.height,
+    });
+}
+/**
+ * 获取文件上传的预签名 URL。
+ * 第三方使用该 URL 直传文件到对象存储（无需经过服务端中转）。
+ *
+ * @param apiBaseUrl    API 基础地址
+ * @param auth          鉴权凭证
+ * @param params        上传参数
+ */
+export async function uploadPreSignedUrl(apiBaseUrl, auth, params) {
+    return postJson(apiBaseUrl, '/api/im/open/bot/uploadPreSignedUrl', {
+        imMainAccId: params.imMainAccId,
+        fileName: params.fileName,
+        fileSize: params.fileSize,
+        mimeType: params.mimeType,
+        scene: params.scene ?? 'AI_GC',
+    }, auth);
+}
+/**
+ * 文件上传到对象存储后，确认上传完成，获取文件访问地址。
+ *
+ * @param apiBaseUrl    API 基础地址
+ * @param auth          鉴权凭证
+ * @param params        确认参数
+ */
+export async function uploadConfirm(apiBaseUrl, auth, params) {
+    return postJson(apiBaseUrl, '/api/im/open/bot/uploadConfirm', {
+        imMainAccId: params.imMainAccId,
+        fileId: params.fileId,
+        needDownloadUrl: false,
+        scene: params.scene ?? 'AI_GC',
+    }, auth);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// sendTypingSignal — 发送 typing indicator 信号（文档 §一，envelopeType=2）
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 向用户发送 typing signal（正在输入指示器）。
+ *
+ * 使用与 sendTextMessage 相同的 HTTP 接口和鉴权机制，
+ * 区别在于 envelopeType=2 和 PbChatOperationEnvelope 信封。
+ *
+ * 四层包装链路（由 send.codec.ts 负责）：
+ *   PbBotThinkingSignal(status, botImAcctId)
+ *     → PbChatOperationEnvelope(botThinking=...)
+ *       → PbSingleChatMsgReqBody(fromId, toId, envelopeType=2, envelope=...)
+ *         → PbRequest(path="/api/im/chat/bot", body=...)
+ *           → PbPacket(type=CLIENT_REQ=0, request=...)
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param fromId      发送方 ID（机器人的 botAcctId，来自 getMe 响应）
+ * @param to          接收方用户 ID
+ * @param status      1=begin（开始输入），2=end（结束输入）
+ * @param botImAcctId Bot 的 imAcctId（通常等于 fromId / botAcctId）
+ * @returns 发送结果
+ */
+export async function sendTypingSignal(apiBaseUrl, auth, fromId, to, status, botImAcctId) {
+    // encodeTypingSignalRequest 负责四层包装，fromId 传入供 PbSingleChatMsgReqBody 使用
+    const requestBody = await encodeTypingSignalRequest(to, status, botImAcctId, fromId);
+    const responseBytes = await postProto(apiBaseUrl, '/api/im/open/bot/sendMessage', requestBody, auth);
+    return decodeSendResponse(responseBytes);
+}

package/dist/src/bot-info-cache.js

@@ -0,0 +1,43 @@
+/**
+ * bot-info-cache.ts — 机器人信息的进程级缓存
+ *
+ * 生命周期：
+ *   - monitor.ts 的 monitorImweAccount 在 getMe 成功后调用 setBotInfo 写入
+ *   - send.ts 的 sendImweText 在发送消息时调用 getBotInfo 读取 botAcctId 作为 fromId
+ *   - monitor.ts 的轮询循环退出时调用 clearBotInfo 清理
+ *
+ * 多账号安全：以 accountId 为 key，每个账号独立缓存，互不干扰。
+ *
+ * 为什么不用 channelRuntime.runtimeContexts：
+ *   outbound 的 sendText 回调签名是 (ctx: ChannelOutboundContext) => ...，
+ *   ChannelOutboundContext 只有 cfg/to/text/accountId，没有 channelRuntime，
+ *   无法调用 runtimeContexts.get()。模块级 Map 是最简单可靠的方案。
+ */
+/** accountId → BotInfo，进程级缓存 */
+const cache = new Map();
+/**
+ * 缓存机器人信息（monitor 启动时写入）。
+ *
+ * @param accountId 账号 ID（多账号时区分不同机器人）
+ * @param info      getMe 返回的机器人信息
+ */
+export function setBotInfo(accountId, info) {
+    cache.set(accountId, info);
+}
+/**
+ * 读取缓存的机器人信息（send / outbound / pairing 读取）。
+ *
+ * @param accountId 账号 ID
+ * @returns 缓存的 BotInfo，未缓存时返回 undefined
+ */
+export function getBotInfo(accountId) {
+    return cache.get(accountId);
+}
+/**
+ * 清除缓存的机器人信息（monitor 停止时调用）。
+ *
+ * @param accountId 账号 ID
+ */
+export function clearBotInfo(accountId) {
+    cache.delete(accountId);
+}