@yanhaidao/wecom 2.4.160 → 2.5.110

package/dist/src/transport/bot-ws/sdk-adapter.js

@@ -0,0 +1,257 @@
+import crypto from "node:crypto";
+import AiBot, { generateReqId, } from "@wecom/aibot-node-sdk";
+import { registerBotWsPushHandle, unregisterBotWsPushHandle } from "../../app/index.js";
+import { clearWecomMcpAccountCache } from "../../capability/mcp/index.js";
+import { mapBotWsFrameToInboundEvent } from "./inbound.js";
+import { uploadAndSendBotWsMedia } from "./media.js";
+import { createBotWsReplyHandle } from "./reply.js";
+import { createBotWsSessionSnapshot } from "./session.js";
+export class BotWsSdkAdapter {
+    runtime;
+    log;
+    client;
+    ownerId;
+    constructor(runtime, log) {
+        this.runtime = runtime;
+        this.log = log;
+        this.ownerId = `${this.runtime.account.accountId}:ws:${crypto.randomUUID().slice(0, 8)}`;
+    }
+    start() {
+        const bot = this.runtime.account.bot;
+        if (!bot?.wsConfigured || !bot.ws) {
+            throw new Error(`WeCom bot account "${this.runtime.account.accountId}" missing WS config.`);
+        }
+        this.log.info?.(`[wecom-ws] start account=${this.runtime.account.accountId} botId=${bot.ws.botId} wsUrl=default heartbeat=default reconnectInterval=default`);
+        const client = new AiBot.WSClient({
+            botId: bot.ws.botId,
+            secret: bot.ws.secret,
+            logger: {
+                debug: (message, ...args) => this.log.info?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
+                info: (message, ...args) => this.log.info?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
+                warn: (message, ...args) => this.log.warn?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
+                error: (message, ...args) => this.log.error?.(`[wecom-ws] ${message} ${args.join(" ")}`.trim()),
+            },
+        });
+        this.client = client;
+        registerBotWsPushHandle(this.runtime.account.accountId, {
+            isConnected: () => client.isConnected,
+            replyCommand: async ({ cmd, body, headers }) => {
+                const replyHeaders = {
+                    ...(headers ?? {}),
+                    req_id: headers?.req_id ?? generateReqId("wecom_ws"),
+                };
+                const result = await client.reply({ headers: replyHeaders }, body ?? {}, cmd);
+                this.runtime.touchTransportSession("bot-ws", {
+                    ownerId: this.ownerId,
+                    running: true,
+                    connected: client.isConnected,
+                    authenticated: client.isConnected,
+                    lastOutboundAt: Date.now(),
+                    lastError: undefined,
+                });
+                return result;
+            },
+            sendMarkdown: async (chatId, content) => {
+                await client.sendMessage(chatId, {
+                    msgtype: "markdown",
+                    markdown: { content },
+                });
+                this.runtime.touchTransportSession("bot-ws", {
+                    ownerId: this.ownerId,
+                    running: true,
+                    connected: client.isConnected,
+                    authenticated: client.isConnected,
+                    lastOutboundAt: Date.now(),
+                    lastError: undefined,
+                });
+            },
+            sendMedia: async ({ chatId, mediaUrl, text, mediaLocalRoots, maxBytes }) => {
+                const result = await uploadAndSendBotWsMedia({
+                    wsClient: client,
+                    chatId,
+                    mediaUrl,
+                    mediaLocalRoots,
+                    maxBytes,
+                });
+                if (result.ok && text?.trim()) {
+                    await client.sendMessage(chatId, {
+                        msgtype: "markdown",
+                        markdown: { content: text.trim() },
+                    });
+                }
+                this.runtime.touchTransportSession("bot-ws", {
+                    ownerId: this.ownerId,
+                    running: true,
+                    connected: client.isConnected,
+                    authenticated: client.isConnected,
+                    lastOutboundAt: Date.now(),
+                    lastError: result.ok ? undefined : result.error,
+                });
+                return result;
+            },
+        });
+        client.on("connected", () => {
+            this.log.info?.(`[wecom-ws] connected account=${this.runtime.account.accountId}`);
+            this.runtime.updateTransportSession(createBotWsSessionSnapshot({
+                accountId: this.runtime.account.accountId,
+                ownerId: this.ownerId,
+                connected: true,
+                authenticated: false,
+            }));
+        });
+        client.on("authenticated", () => {
+            this.log.info?.(`[wecom-ws] authenticated account=${this.runtime.account.accountId}`);
+            this.runtime.updateTransportSession(createBotWsSessionSnapshot({
+                accountId: this.runtime.account.accountId,
+                ownerId: this.ownerId,
+                connected: true,
+                authenticated: true,
+            }));
+        });
+        client.on("disconnected", (reason) => {
+            clearWecomMcpAccountCache(this.runtime.account.accountId);
+            const normalizedReason = String(reason ?? "").toLowerCase();
+            const kicked = normalizedReason.includes("kick") ||
+                normalizedReason.includes("owner") ||
+                normalizedReason.includes("replaced");
+            this.log.warn?.(`[wecom-ws] disconnected account=${this.runtime.account.accountId} kicked=${String(kicked)} reason=${reason ?? "unknown"}`);
+            if (kicked) {
+                this.runtime.recordOperationalIssue({
+                    transport: "bot-ws",
+                    category: "ws-kicked",
+                    summary: `ws owner lost: ${reason ?? "unknown"}`,
+                    error: reason ?? "unknown",
+                });
+            }
+            this.runtime.updateTransportSession(createBotWsSessionSnapshot({
+                accountId: this.runtime.account.accountId,
+                ownerId: this.ownerId,
+                running: false,
+                connected: false,
+                authenticated: false,
+                lastDisconnectedAt: Date.now(),
+                lastError: reason,
+            }));
+        });
+        client.on("reconnecting", (attempt) => {
+            this.log.warn?.(`[wecom-ws] reconnecting account=${this.runtime.account.accountId} attempt=${attempt}`);
+        });
+        client.on("error", (error) => {
+            this.log.error?.(`[wecom-ws] error account=${this.runtime.account.accountId} message=${error.message}`);
+            this.runtime.updateTransportSession(createBotWsSessionSnapshot({
+                accountId: this.runtime.account.accountId,
+                ownerId: this.ownerId,
+                running: false,
+                connected: client.isConnected,
+                authenticated: client.isConnected,
+                lastError: error.message,
+            }));
+        });
+        const handleFrame = async (frame) => {
+            const botAccount = this.runtime.account.bot;
+            if (!botAccount) {
+                return;
+            }
+            this.log.info?.(`[wecom-ws] frame account=${this.runtime.account.accountId} cmd=${frame.cmd} reqId=${frame.headers.req_id ?? "n/a"}`);
+            this.runtime.touchTransportSession("bot-ws", {
+                ownerId: this.ownerId,
+                running: true,
+                connected: client.isConnected,
+                authenticated: client.isConnected,
+                lastInboundAt: Date.now(),
+            });
+            const event = mapBotWsFrameToInboundEvent({
+                account: botAccount,
+                frame,
+            });
+            const replyHandle = createBotWsReplyHandle({
+                client,
+                frame,
+                accountId: this.runtime.account.accountId,
+                inboundKind: event.inboundKind,
+                placeholderContent: botAccount.config.streamPlaceholderContent,
+                autoSendPlaceholder: event.inboundKind === "text" ||
+                    event.inboundKind === "image" ||
+                    event.inboundKind === "file" ||
+                    event.inboundKind === "voice" ||
+                    event.inboundKind === "mixed",
+                onDeliver: () => {
+                    this.runtime.touchTransportSession("bot-ws", {
+                        ownerId: this.ownerId,
+                        running: true,
+                        connected: client.isConnected,
+                        authenticated: client.isConnected,
+                        lastOutboundAt: Date.now(),
+                    });
+                },
+                onFail: (error) => {
+                    this.runtime.touchTransportSession("bot-ws", {
+                        ownerId: this.ownerId,
+                        running: client.isConnected,
+                        connected: client.isConnected,
+                        authenticated: client.isConnected,
+                        lastError: error instanceof Error ? error.message : String(error),
+                    });
+                },
+            });
+            const staticWelcomeText = event.inboundKind === "welcome" ? botAccount.config.welcomeText?.trim() : undefined;
+            if (staticWelcomeText) {
+                this.log.info?.(`[wecom-ws] static welcome reply account=${this.runtime.account.accountId} messageId=${event.messageId} peer=${event.conversation.peerKind}:${event.conversation.peerId} len=${staticWelcomeText.length}`);
+                await replyHandle.deliver({
+                    text: staticWelcomeText,
+                }, { kind: "final" });
+                this.log.info?.(`[wecom-ws] static welcome delivered account=${this.runtime.account.accountId} messageId=${event.messageId}`);
+                return;
+            }
+            await this.runtime.handleEvent(event, replyHandle);
+        };
+        const runHandleFrame = (frame) => {
+            void handleFrame(frame).catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                this.log.error?.(`[wecom-ws] frame handler failed account=${this.runtime.account.accountId} reqId=${frame.headers?.req_id ?? "n/a"} message=${message}`);
+                this.runtime.recordOperationalIssue({
+                    transport: "bot-ws",
+                    category: "runtime-error",
+                    messageId: frame.body?.msgid,
+                    raw: {
+                        transport: "bot-ws",
+                        command: frame.cmd,
+                        headers: frame.headers,
+                        body: frame.body,
+                        envelopeType: "ws",
+                    },
+                    summary: `bot-ws frame handler crashed reqId=${frame.headers?.req_id ?? "n/a"}`,
+                    error: message,
+                });
+                this.runtime.touchTransportSession("bot-ws", {
+                    ownerId: this.ownerId,
+                    running: client.isConnected,
+                    connected: client.isConnected,
+                    authenticated: client.isConnected,
+                    lastError: message,
+                });
+            });
+        };
+        client.on("message", (frame) => {
+            runHandleFrame(frame);
+        });
+        client.on("event", (frame) => {
+            runHandleFrame(frame);
+        });
+        client.connect();
+    }
+    stop() {
+        this.log.info?.(`[wecom-ws] stop account=${this.runtime.account.accountId}`);
+        clearWecomMcpAccountCache(this.runtime.account.accountId);
+        unregisterBotWsPushHandle(this.runtime.account.accountId);
+        this.runtime.updateTransportSession(createBotWsSessionSnapshot({
+            accountId: this.runtime.account.accountId,
+            ownerId: this.ownerId,
+            running: false,
+            connected: false,
+            authenticated: false,
+            lastDisconnectedAt: Date.now(),
+        }));
+        this.client?.disconnect();
+    }
+}

package/dist/src/transport/bot-ws/session.js

@@ -0,0 +1,15 @@
+export function createBotWsSessionSnapshot(params) {
+    return {
+        accountId: params.accountId,
+        transport: "bot-ws",
+        running: params.running ?? true,
+        ownerId: params.ownerId,
+        connected: params.connected,
+        authenticated: params.authenticated,
+        lastConnectedAt: params.lastConnectedAt ?? (params.connected ? Date.now() : undefined),
+        lastDisconnectedAt: params.lastDisconnectedAt,
+        lastInboundAt: params.lastInboundAt,
+        lastOutboundAt: params.lastOutboundAt,
+        lastError: params.lastError,
+    };
+}

package/dist/src/transport/http/common.js

@@ -0,0 +1,78 @@
+import { WEBHOOK_PATHS } from "../../types/constants.js";
+export function normalizeWecomWebhookPath(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return "/";
+    const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    if (withSlash.length > 1 && withSlash.endsWith("/"))
+        return withSlash.slice(0, -1);
+    return withSlash;
+}
+export function resolveQueryParams(req) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    return url.searchParams;
+}
+export function resolvePath(req) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    return normalizeWecomWebhookPath(url.pathname || "/");
+}
+export function resolveSignatureParam(params) {
+    return params.get("msg_signature") ?? params.get("msgsignature") ?? params.get("signature") ?? "";
+}
+export function isAgentCallbackPathCandidate(path) {
+    return (path === WEBHOOK_PATHS.AGENT ||
+        path === WEBHOOK_PATHS.AGENT_PLUGIN ||
+        path.startsWith(`${WEBHOOK_PATHS.AGENT}/`) ||
+        path.startsWith(`${WEBHOOK_PATHS.AGENT_PLUGIN}/`));
+}
+export function isNonMatrixWecomBasePath(path) {
+    return (path === WEBHOOK_PATHS.BOT ||
+        path === WEBHOOK_PATHS.BOT_ALT ||
+        path === WEBHOOK_PATHS.AGENT ||
+        path === WEBHOOK_PATHS.BOT_PLUGIN ||
+        path === WEBHOOK_PATHS.AGENT_PLUGIN);
+}
+function maskAccountId(accountId) {
+    const normalized = accountId.trim();
+    if (!normalized)
+        return "***";
+    if (normalized.length <= 4)
+        return `${normalized[0] ?? "*"}***`;
+    return `${normalized.slice(0, 2)}***${normalized.slice(-2)}`;
+}
+export function logRouteFailure(params) {
+    const payload = {
+        reqId: params.reqId,
+        path: params.path,
+        method: params.method,
+        reason: params.reason,
+        candidateAccountIds: params.candidateAccountIds.map(maskAccountId),
+    };
+    console.error(`[wecom] route-error ${JSON.stringify(payload)}`);
+}
+export function writeRouteFailure(res, reason, message) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ error: reason, message }));
+}
+export async function readTextBody(req, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    return await new Promise((resolve) => {
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > maxBytes) {
+                resolve({ ok: false, error: "payload too large" });
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            resolve({ ok: true, value: Buffer.concat(chunks).toString("utf8") });
+        });
+        req.on("error", (err) => {
+            resolve({ ok: false, error: String(err) });
+        });
+    });
+}

package/dist/src/transport/http/registry.js

@@ -0,0 +1,71 @@
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/routing";
+import { monitorState } from "../../monitor/state.js";
+import { WEBHOOK_PATHS } from "../../types/constants.js";
+import { normalizeWecomWebhookPath } from "./common.js";
+const webhookTargets = new Map();
+const agentTargets = new Map();
+function ensurePruneTimer() {
+    monitorState.startPruning();
+}
+function checkPruneTimer() {
+    if (webhookTargets.size === 0 && agentTargets.size === 0) {
+        monitorState.stopPruning();
+    }
+}
+export function registerWecomWebhookTarget(target) {
+    const key = normalizeWecomWebhookPath(target.path);
+    const normalizedTarget = { ...target, path: key };
+    const existing = webhookTargets.get(key) ?? [];
+    webhookTargets.set(key, [...existing, normalizedTarget]);
+    ensurePruneTimer();
+    return () => {
+        const updated = (webhookTargets.get(key) ?? []).filter((entry) => entry !== normalizedTarget);
+        if (updated.length > 0)
+            webhookTargets.set(key, updated);
+        else
+            webhookTargets.delete(key);
+        checkPruneTimer();
+    };
+}
+export function registerAgentWebhookTarget(target) {
+    const key = normalizeWecomWebhookPath(target.path);
+    const normalizedTarget = { ...target, path: key };
+    const existing = agentTargets.get(key) ?? [];
+    agentTargets.set(key, [...existing, normalizedTarget]);
+    ensurePruneTimer();
+    return () => {
+        const updated = (agentTargets.get(key) ?? []).filter((entry) => entry !== normalizedTarget);
+        if (updated.length > 0)
+            agentTargets.set(key, updated);
+        else
+            agentTargets.delete(key);
+        checkPruneTimer();
+    };
+}
+export function getWecomWebhookTargets(path) {
+    return webhookTargets.get(normalizeWecomWebhookPath(path)) ?? [];
+}
+export function getAgentWebhookTargets(path) {
+    return agentTargets.get(normalizeWecomWebhookPath(path)) ?? [];
+}
+export function hasMatrixExplicitRoutesRegistered() {
+    for (const [key, targets] of webhookTargets.entries()) {
+        if (key.startsWith(`${WEBHOOK_PATHS.BOT_ALT}/`) && targets.some((target) => target.account.accountId !== DEFAULT_ACCOUNT_ID)) {
+            return true;
+        }
+        if (key.startsWith(`${WEBHOOK_PATHS.BOT_PLUGIN}/`) &&
+            targets.some((target) => target.account.accountId !== DEFAULT_ACCOUNT_ID)) {
+            return true;
+        }
+    }
+    for (const [key, targets] of agentTargets.entries()) {
+        if (key.startsWith(`${WEBHOOK_PATHS.AGENT}/`) && targets.some((target) => target.agent.accountId !== DEFAULT_ACCOUNT_ID)) {
+            return true;
+        }
+        if (key.startsWith(`${WEBHOOK_PATHS.AGENT_PLUGIN}/`) &&
+            targets.some((target) => target.agent.accountId !== DEFAULT_ACCOUNT_ID)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/src/transport/http/request-handler.js

@@ -0,0 +1,51 @@
+import crypto from "node:crypto";
+import { handleAgentCallbackRequest } from "../agent-callback/request-handler.js";
+import { getAgentWebhookTargets, getWecomWebhookTargets, hasMatrixExplicitRoutesRegistered } from "./registry.js";
+import { isAgentCallbackPathCandidate, isNonMatrixWecomBasePath, logRouteFailure, resolvePath, resolveQueryParams, writeRouteFailure, } from "./common.js";
+export async function handleWecomHttpRequest(params) {
+    const { req, res, handleBotWebhookRequest } = params;
+    const path = resolvePath(req);
+    const reqId = crypto.randomUUID().slice(0, 8);
+    const remote = req.socket?.remoteAddress ?? "unknown";
+    const ua = String(req.headers["user-agent"] ?? "");
+    const cl = String(req.headers["content-length"] ?? "");
+    const q = resolveQueryParams(req);
+    const hasTimestamp = Boolean(q.get("timestamp"));
+    const hasNonce = Boolean(q.get("nonce"));
+    const hasEchostr = Boolean(q.get("echostr"));
+    const hasMsgSig = Boolean(q.get("msg_signature"));
+    const hasSignature = Boolean(q.get("signature"));
+    console.log(`[wecom] inbound(http): reqId=${reqId} path=${path} method=${req.method ?? "UNKNOWN"} remote=${remote} ua=${ua ? `"${ua}"` : "N/A"} contentLength=${cl || "N/A"} query={timestamp:${hasTimestamp},nonce:${hasNonce},echostr:${hasEchostr},msg_signature:${hasMsgSig},signature:${hasSignature}}`);
+    if (hasMatrixExplicitRoutesRegistered() && isNonMatrixWecomBasePath(path)) {
+        logRouteFailure({
+            reqId,
+            path,
+            method: req.method ?? "UNKNOWN",
+            reason: "wecom_matrix_path_required",
+            candidateAccountIds: [],
+        });
+        writeRouteFailure(res, "wecom_matrix_path_required", "Matrix mode requires explicit account path. Use /plugins/wecom/bot/{accountId} or /plugins/wecom/agent/{accountId}.");
+        return true;
+    }
+    const agentTargets = getAgentWebhookTargets(path);
+    if (agentTargets.length > 0 || isAgentCallbackPathCandidate(path)) {
+        return handleAgentCallbackRequest({
+            req,
+            res,
+            path,
+            reqId,
+            targets: agentTargets,
+        });
+    }
+    const botTargets = getWecomWebhookTargets(path);
+    if (botTargets.length === 0) {
+        return false;
+    }
+    return handleBotWebhookRequest({
+        req,
+        res,
+        path,
+        reqId,
+        targets: botTargets,
+    });
+}

package/{src/transport/index.ts → dist/src/transport/index.js}

@@ -1,14 +1,6 @@
 export { BotWsSdkAdapter } from "./bot-ws/sdk-adapter.js";
 export { startBotWebhookTransport } from "./bot-webhook/http-handler.js";
 export { startAgentCallbackTransport } from "./agent-callback/http-handler.js";
-export {
-  deliverAgentApiMedia,
-  deliverAgentApiText,
-} from "./agent-api/delivery.js";
-export {
-  downloadAgentApiMedia,
-  getAgentApiAccessToken,
-  sendAgentApiMedia,
-  sendAgentApiText,
-} from "./agent-api/client.js";
+export { deliverAgentApiMedia, deliverAgentApiText, } from "./agent-api/delivery.js";
+export { downloadAgentApiMedia, getAgentApiAccessToken, sendAgentApiMedia, sendAgentApiText, } from "./agent-api/client.js";
 export { uploadAgentApiMedia } from "./agent-api/media-upload.js";

package/dist/src/types/account.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/config.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/constants.js

@@ -0,0 +1,28 @@
+export const WEBHOOK_PATHS = {
+    BOT: "/wecom/bot",
+    BOT_ALT: "/wecom",
+    AGENT: "/wecom/agent",
+    BOT_PLUGIN: "/plugins/wecom/bot",
+    AGENT_PLUGIN: "/plugins/wecom/agent",
+};
+export const API_ENDPOINTS = {
+    GET_TOKEN: "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
+    SEND_MESSAGE: "https://qyapi.weixin.qq.com/cgi-bin/message/send",
+    SEND_APPCHAT: "https://qyapi.weixin.qq.com/cgi-bin/appchat/send",
+    UPLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/upload",
+    DOWNLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/get",
+};
+export const LIMITS = {
+    TEXT_MAX_BYTES: 20_480,
+    TOKEN_REFRESH_BUFFER_MS: 60_000,
+    REQUEST_TIMEOUT_MS: 15_000,
+    MAX_REQUEST_BODY_SIZE: 1024 * 1024,
+    BOT_WEBHOOK_PASSIVE_WINDOW_MS: 5_000,
+    BOT_WEBHOOK_RESPONSE_URL_TTL_MS: 60 * 60 * 1000,
+    BOT_STREAM_WINDOW_MS: 6 * 60 * 1000,
+    BOT_WS_HEARTBEAT_MS: 30_000,
+};
+export const CRYPTO = {
+    PKCS7_BLOCK_SIZE: 32,
+    AES_KEY_LENGTH: 32,
+};

package/dist/src/types/events.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/index.js

@@ -0,0 +1 @@
+export * from "./constants.js";

package/dist/src/types/legacy-stream.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/message.js

@@ -0,0 +1,5 @@
+/**
+ * WeCom 消息类型定义
+ * Bot 和 Agent 模式共用
+ */
+export {};

package/dist/src/types/runtime-context.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/runtime.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/upstream/index.js

@@ -0,0 +1,111 @@
+/**
+ * 上下游企业支持模块
+ *
+ * 根据企业微信文档：https://developer.work.weixin.qq.com/document/path/97213
+ *
+ * 关键逻辑：
+ * 1. 上下游企业消息中的 ToUserName 是下游企业的 CorpID
+ * 2. 需要使用下游企业的 access_token 来发送消息
+ * 3. 获取下游企业 access_token 的接口：
+ *    POST https://qyapi.weixin.qq.com/cgi-bin/corpgroup/corp/gettoken?access_token=ACCESS_TOKEN
+ *    {
+ *      "corpid": "下游企业corpid",
+ *      "business_type": 1,  // 1 表示上下游企业
+ *      "agentid": 下游企业应用ID
+ *    }
+ * 4. 需要使用上游企业的 access_token 作为调用凭证
+ */
+/**
+ * 从消息中检测是否是上下游用户
+ * 通过比较消息中的 ToUserName（CorpID）与配置的 CorpID
+ */
+export function detectUpstreamUser(params) {
+    const { messageToUserName, primaryCorpId } = params;
+    if (!messageToUserName?.trim() || !primaryCorpId?.trim()) {
+        return false;
+    }
+    const normalizedMessageCorpId = messageToUserName.trim().toLowerCase();
+    const normalizedPrimaryCorpId = primaryCorpId.trim().toLowerCase();
+    // 如果消息中的 CorpID 与主 CorpID 不同，则是上下游用户
+    return normalizedMessageCorpId !== normalizedPrimaryCorpId;
+}
+/**
+ * 为上下游用户创建临时的 Agent 配置
+ * 使用下游企业的 CorpID 和 AgentID，但保持主企业的 corpSecret
+ *
+ * 注意：这个配置用于发送消息，但获取 access_token 时需要使用专门的
+ * corpgroup/corp/gettoken 接口
+ */
+export function createUpstreamAgentConfig(params) {
+    const { baseAgent, upstreamCorpId, upstreamAgentId } = params;
+    return {
+        ...baseAgent,
+        corpId: upstreamCorpId,
+        agentId: upstreamAgentId,
+        // corpSecret 保持主企业的，用于获取下游企业的 access_token
+        // token 和 encodingAESKey 保持主企业的，用于回调验证
+    };
+}
+/**
+ * 从配置中解析上下游企业映射
+ * 支持在 agent 配置中添加 upstreamCorps 字段
+ */
+export function resolveUpstreamCorpConfig(params) {
+    const { upstreamCorpId, upstreamCorps } = params;
+    if (!upstreamCorps) {
+        return undefined;
+    }
+    // Normalize to array format (support both Record<string, ...> and array)
+    const entries = Array.isArray(upstreamCorps)
+        ? upstreamCorps.map((item, i) => [String(i), item])
+        : Object.entries(upstreamCorps);
+    // Find matching upstream config
+    const normalizedTargetCorpId = upstreamCorpId.trim().toLowerCase();
+    for (const [key, config] of entries) {
+        const normalizedConfigCorpId = config.corpId.trim().toLowerCase();
+        if (normalizedConfigCorpId === normalizedTargetCorpId) {
+            return config;
+        }
+    }
+    return undefined;
+}
+/**
+ * 构建上下游用户的回复目标
+ * 格式: wecom-agent-upstream:{accountId}:{corpId}:{userId}
+ */
+export function buildUpstreamAgentSessionTarget(userId, accountId, upstreamCorpId) {
+    return `wecom-agent-upstream:${accountId}:${upstreamCorpId}:${userId}`;
+}
+/**
+ * 解析上下游用户的回复目标
+ */
+export function parseUpstreamAgentSessionTarget(target) {
+    const prefix = "wecom-agent-upstream:";
+    if (target.startsWith(prefix)) {
+        const parts = target.slice(prefix.length).split(":");
+        if (parts.length !== 3) {
+            return undefined;
+        }
+        return {
+            accountId: parts[0],
+            upstreamCorpId: parts[1],
+            userId: parts[2],
+        };
+    }
+    // 兼容当前工作区里尚未持久化的新格式，避免旧会话目标失效。
+    const queryIndex = target.indexOf("?upstream_corp=");
+    if (queryIndex < 0 || !target.startsWith("wecom-agent:")) {
+        return undefined;
+    }
+    const pathPart = target.slice(0, queryIndex);
+    const upstreamCorpId = target.slice(queryIndex + "?upstream_corp=".length).trim();
+    const match = pathPart.match(/^wecom-agent:([^:]+):user:(.+)$/i);
+    if (!match || !upstreamCorpId) {
+        return undefined;
+    }
+    return {
+        accountId: match[1].trim(),
+        upstreamCorpId,
+        userId: match[2].trim(),
+    };
+}