@wecom/wecom-openclaw-plugin 2026.4.2-beta.0 → 2026.4.3-beta.0

package/dist/src/types/message.d.ts

@@ -0,0 +1,238 @@
+/**
+ * WeCom 消息类型定义
+ * Bot 和 Agent 模式共用
+ */
+/**
+ * Bot 模式入站消息基础结构 (JSON)
+ */
+/**
+ * **WecomBotInboundBase (Bot 入站消息基类)**
+ *
+ * Bot 模式下 JSON 格式回调的基础字段。
+ * @property msgid 消息 ID
+ * @property aibotid 机器人 ID
+ * @property chattype 会话类型: "single" | "group"
+ * @property chatid 群聊 ID (仅群组时存在)
+ * @property response_url 下行回复 URL (用于被动响应转主动推送)
+ * @property from 发送者信息
+ */
+export type WecomBotInboundBase = {
+    msgid?: string;
+    aibotid?: string;
+    chattype?: "single" | "group";
+    chatid?: string;
+    response_url?: string;
+    from?: {
+        userid?: string;
+        corpid?: string;
+    };
+    msgtype?: string;
+    /** 附件数量 (部分消息存在) */
+    attachment_count?: number;
+};
+export type WecomBotInboundText = WecomBotInboundBase & {
+    msgtype: "text";
+    text?: {
+        content?: string;
+    };
+    quote?: WecomInboundQuote;
+};
+export type WecomBotInboundVoice = WecomBotInboundBase & {
+    msgtype: "voice";
+    voice?: {
+        content?: string;
+    };
+    quote?: WecomInboundQuote;
+};
+export type WecomBotInboundVideo = WecomBotInboundBase & {
+    msgtype: "video";
+    video?: {
+        url?: string;
+        aeskey?: string;
+    };
+    quote?: WecomInboundQuote;
+};
+export type WecomBotInboundStreamRefresh = WecomBotInboundBase & {
+    msgtype: "stream";
+    stream?: {
+        id?: string;
+    };
+};
+export type WecomBotInboundEvent = WecomBotInboundBase & {
+    msgtype: "event";
+    create_time?: number;
+    event?: {
+        eventtype?: string;
+        [key: string]: unknown;
+    };
+};
+/**
+ * **WecomInboundQuote (引用消息)**
+ *
+ * 消息中引用的原始内容（如回复某条消息）。
+ * 支持引用文本、图片、混合类型、语音、文件等。
+ */
+export type WecomInboundQuote = {
+    msgtype?: "text" | "image" | "mixed" | "voice" | "file" | "video";
+    /** 引用文本内容 */
+    text?: {
+        content?: string;
+    };
+    /** 引用图片 URL */
+    image?: {
+        url?: string;
+    };
+    /** 引用混合消息 (图文) */
+    mixed?: {
+        msg_item?: Array<{
+            msgtype: "text" | "image";
+            text?: {
+                content?: string;
+            };
+            image?: {
+                url?: string;
+            };
+        }>;
+    };
+    /** 引用语音 */
+    voice?: {
+        content?: string;
+    };
+    /** 引用文件 */
+    file?: {
+        url?: string;
+    };
+    /** 引用视频 */
+    video?: {
+        url?: string;
+    };
+};
+export type WecomBotInboundMessage = WecomBotInboundText | WecomBotInboundVoice | WecomBotInboundVideo | WecomBotInboundStreamRefresh | WecomBotInboundEvent | (WecomBotInboundBase & {
+    quote?: WecomInboundQuote;
+} & Record<string, unknown>);
+/**
+ * Agent 模式入站消息结构 (解析自 XML)
+ */
+/**
+ * **WecomAgentInboundMessage (Agent 入站消息)**
+ *
+ * Agent 模式下解析自 XML 的扁平化消息结构。
+ * 键名保持 PascalCase (如 `ToUserName`)。
+ */
+export type WecomAgentInboundMessage = {
+    ToUserName?: string;
+    FromUserName?: string;
+    CreateTime?: number;
+    MsgType?: string;
+    MsgId?: string;
+    AgentID?: number;
+    Content?: string;
+    PicUrl?: string;
+    MediaId?: string;
+    FileName?: string;
+    Format?: string;
+    Recognition?: string;
+    ThumbMediaId?: string;
+    Location_X?: number;
+    Location_Y?: number;
+    Scale?: number;
+    Label?: string;
+    Title?: string;
+    Description?: string;
+    Url?: string;
+    Event?: string;
+    EventKey?: string;
+    ChatId?: string;
+};
+/**
+ * 模板卡片类型
+ */
+/**
+ * **WecomTemplateCard (模板卡片)**
+ *
+ * 复杂的交互式卡片结构。
+ * @property card_type 卡片类型: "text_notice" | "news_notice" | "button_interaction" ...
+ * @property source 来源信息
+ * @property main_title 主标题
+ * @property sub_title_text 副标题
+ * @property horizontal_content_list 水平排列的键值列表
+ * @property button_list 按钮列表
+ */
+export type WecomTemplateCard = {
+    card_type: "text_notice" | "news_notice" | "button_interaction" | "vote_interaction" | "multiple_interaction";
+    source?: {
+        icon_url?: string;
+        desc?: string;
+        desc_color?: number;
+    };
+    main_title?: {
+        title?: string;
+        desc?: string;
+    };
+    task_id?: string;
+    button_list?: Array<{
+        text: string;
+        style?: number;
+        key: string;
+    }>;
+    sub_title_text?: string;
+    horizontal_content_list?: Array<{
+        keyname: string;
+        value?: string;
+        type?: number;
+        url?: string;
+        userid?: string;
+    }>;
+    card_action?: {
+        type: number;
+        url?: string;
+        appid?: string;
+        pagepath?: string;
+    };
+    action_menu?: {
+        desc: string;
+        action_list: Array<{
+            text: string;
+            key: string;
+        }>;
+    };
+    select_list?: Array<{
+        question_key: string;
+        title?: string;
+        selected_id?: string;
+        option_list: Array<{
+            id: string;
+            text: string;
+        }>;
+    }>;
+    submit_button?: {
+        text: string;
+        key: string;
+    };
+    checkbox?: {
+        question_key: string;
+        option_list: Array<{
+            id: string;
+            text: string;
+            is_checked?: boolean;
+        }>;
+        mode?: number;
+    };
+};
+/**
+ * 出站消息类型
+ */
+export type WecomOutboundMessage = {
+    msgtype: "text";
+    text: {
+        content: string;
+    };
+} | {
+    msgtype: "markdown";
+    markdown: {
+        content: string;
+    };
+} | {
+    msgtype: "template_card";
+    template_card: WecomTemplateCard;
+};

package/dist/src/types/message.js

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

package/dist/{esm/types/src → src}/utils.d.ts

@@ -2,6 +2,8 @@
  * 企业微信公共工具函数
  */
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import type { ResolvedAgentAccount } from "./types/account.js";
+import type { WecomAgentConfig, WecomNetworkConfig, WecomMediaConfig, WecomDynamicAgentsConfig } from "./types/config.js";
 /**
  * 企业微信群组配置
  */
@@ -30,7 +32,32 @@ export interface WeComConfig {
     sendThinkingMessage?: boolean;
     /** 额外允许访问的本地媒体路径白名单（支持 ~ 表示 home 目录），如 ["~/Downloads", "~/Documents"] */
     mediaLocalRoots?: string[];
+    /** Agent 模式配置（自建应用） */
+    agent?: WecomAgentConfig;
+    /** 网络配置 */
+    network?: WecomNetworkConfig;
+    /** 媒体处理配置 */
+    media?: WecomMediaConfig;
+    /** 动态 Agent 配置 */
+    dynamicAgents?: WecomDynamicAgentsConfig;
+    /** 连接模式：webhook | websocket（默认 websocket） */
+    connectionMode?: "webhook" | "websocket";
+    /** Webhook 验证 token */
+    token?: string;
+    /** AES 加密密钥（43 字符 Base64） */
+    encodingAESKey?: string;
+    /** 接收方 ID */
+    receiveId?: string;
+    /** enter_chat 欢迎消息 */
+    welcomeText?: string;
+    /** 流式占位符提示内容 */
+    streamPlaceholderContent?: string;
 }
+/**
+ * 单个企业微信账号的配置类型（用于 accounts 字段下的每个账号）。
+ * 与 WeComConfig 字段完全一致，账号级字段会覆盖顶层同名字段。
+ */
+export type WeComAccountConfig = Partial<WeComConfig>;
 export declare const DefaultWsUrl = "wss://openws.work.weixin.qq.com";
 export interface ResolvedWeComAccount {
     accountId: string;
@@ -42,6 +69,12 @@ export interface ResolvedWeComAccount {
     /** 是否发送"思考中"消息，默认为 true */
     sendThinkingMessage: boolean;
     config: WeComConfig;
+    /** Agent 模式能力（自建应用） */
+    agent?: ResolvedAgentAccount;
+    /** Webhook 模式配置 */
+    token?: string;
+    encodingAESKey?: string;
+    receiveId?: string;
 }
 /**
  * 解析企业微信账户配置
@@ -51,3 +84,11 @@ export declare function resolveWeComAccount(cfg: OpenClawConfig): ResolvedWeComA
  * 设置企业微信账户配置
  */
 export declare function setWeComAccount(cfg: OpenClawConfig, account: Partial<WeComConfig>): OpenClawConfig;
+/**
+ * 解析出口代理 URL（对齐原版 resolveWecomEgressProxyUrl）
+ *
+ * 优先级：
+ * 1. config.channels.wecom.network.egressProxyUrl
+ * 2. 环境变量：OPENCLAW_WECOM_EGRESS_PROXY_URL → WECOM_EGRESS_PROXY_URL → HTTPS_PROXY → ALL_PROXY → HTTP_PROXY
+ */
+export declare function resolveWecomEgressProxyUrl(cfg: OpenClawConfig): string | undefined;

package/dist/{esm/src → src}/utils.js

@@ -1,19 +1,18 @@
-import { DEFAULT_ACCOUNT_ID } from './openclaw-compat.js';
-import { CHANNEL_ID } from './const.js';
-
 /**
  * 企业微信公共工具函数
  */
-const DefaultWsUrl = "wss://openws.work.weixin.qq.com";
+import { DEFAULT_ACCOUNT_ID } from "./openclaw-compat.js";
+import { CHANNEL_ID } from "./const.js";
+export const DefaultWsUrl = "wss://openws.work.weixin.qq.com";
 /**
  * 解析企业微信账户配置
  */
-function resolveWeComAccount(cfg) {
+export function resolveWeComAccount(cfg) {
     const wecomConfig = (cfg.channels?.[CHANNEL_ID] ?? {});
     return {
         accountId: DEFAULT_ACCOUNT_ID,
         name: wecomConfig.name ?? "企业微信",
-        enabled: wecomConfig.enabled ?? false,
+        enabled: wecomConfig.enabled !== false,
         websocketUrl: wecomConfig.websocketUrl || DefaultWsUrl,
         botId: wecomConfig.botId ?? "",
         secret: wecomConfig.secret ?? "",
@@ -24,7 +23,7 @@ function resolveWeComAccount(cfg) {
 /**
  * 设置企业微信账户配置
  */
-function setWeComAccount(cfg, account) {
+export function setWeComAccount(cfg, account) {
     const existing = (cfg.channels?.[CHANNEL_ID] ?? {});
     const merged = {
         enabled: account.enabled ?? existing?.enabled ?? true,
@@ -51,6 +50,21 @@ function setWeComAccount(cfg, account) {
         },
     };
 }
-
-export { DefaultWsUrl, resolveWeComAccount, setWeComAccount };
-//# sourceMappingURL=utils.js.map
+/**
+ * 解析出口代理 URL（对齐原版 resolveWecomEgressProxyUrl）
+ *
+ * 优先级：
+ * 1. config.channels.wecom.network.egressProxyUrl
+ * 2. 环境变量：OPENCLAW_WECOM_EGRESS_PROXY_URL → WECOM_EGRESS_PROXY_URL → HTTPS_PROXY → ALL_PROXY → HTTP_PROXY
+ */
+export function resolveWecomEgressProxyUrl(cfg) {
+    const wecom = (cfg.channels?.[CHANNEL_ID] ?? {});
+    const proxyUrl = wecom.network?.egressProxyUrl ??
+        process.env.OPENCLAW_WECOM_EGRESS_PROXY_URL ??
+        process.env.WECOM_EGRESS_PROXY_URL ??
+        process.env.HTTPS_PROXY ??
+        process.env.ALL_PROXY ??
+        process.env.HTTP_PROXY ??
+        "";
+    return proxyUrl.trim() || undefined;
+}

package/dist/src/version.d.ts

@@ -0,0 +1,2 @@
+/** 插件版本号，运行时从 package.json 读取 */
+export declare const PLUGIN_VERSION: string;

package/dist/src/version.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * 从当前文件位置向上逐级查找 package.json
+ * - ts 源码直接运行时（tsx/ts-node）：src/version.ts → 向上 1 级
+ * - tsc 编译后运行时：dist/src/version.js → 向上 2 级
+ */
+const findPackageJson = () => {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = resolve(dir, "package.json");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // 已到文件系统根目录
+        dir = parent;
+    }
+    throw new Error("找不到 package.json");
+};
+const pkg = JSON.parse(readFileSync(findPackageJson(), "utf-8"));
+/** 插件版本号，运行时从 package.json 读取 */
+export const PLUGIN_VERSION = pkg.version ?? "";

package/dist/src/webhook/command-auth.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 命令授权（Command Authorization）
+ *
+ * 从 lh 版 shared/command-auth.ts 迁移。
+ * 适配新版 WeComConfig（dmPolicy / allowFrom 扁平化在顶层）。
+ */
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import type { WeComConfig } from "../utils.js";
+/** 命令授权结果 */
+export interface WecomCommandAuthResult {
+    /** 当前消息是否是需要鉴权的命令 */
+    shouldComputeAuth: boolean;
+    /** 账号配置的私信策略 */
+    dmPolicy: "pairing" | "allowlist" | "open" | "disabled";
+    /** 当前发送者是否在白名单中 */
+    senderAllowed: boolean;
+    /** 是否配置了授权器 */
+    authorizerConfigured: boolean;
+    /** 最终授权结果：true=放行，false=拒绝，undefined=不需要鉴权 */
+    commandAuthorized: boolean | undefined;
+    /** 生效的白名单列表 */
+    effectiveAllowFrom: string[];
+}
+/**
+ * 解析命令授权状态
+ *
+ * 适配新版 WeComConfig 的扁平化字段：
+ * - dmPolicy → accountConfig.dmPolicy
+ * - allowFrom → accountConfig.allowFrom
+ */
+export declare function resolveWecomCommandAuthorization(params: {
+    core: PluginRuntime;
+    cfg: OpenClawConfig;
+    accountConfig: WeComConfig;
+    rawBody: string;
+    senderUserId: string;
+}): Promise<WecomCommandAuthResult>;
+/**
+ * 构建未授权命令的中文提示文案
+ *
+ * @param scope - "bot"（智能机器人）或 "agent"（自建应用）
+ */
+export declare function buildWecomUnauthorizedCommandPrompt(params: {
+    senderUserId: string;
+    dmPolicy: "pairing" | "allowlist" | "open" | "disabled";
+    scope: "bot" | "agent";
+}): string;

package/dist/src/webhook/command-auth.js

@@ -0,0 +1,96 @@
+/**
+ * 命令授权（Command Authorization）
+ *
+ * 从 lh 版 shared/command-auth.ts 迁移。
+ * 适配新版 WeComConfig（dmPolicy / allowFrom 扁平化在顶层）。
+ */
+// ============================================================================
+// 内部工具函数
+// ============================================================================
+/** 归一化白名单条目：去除空格、统一小写、去掉 wecom:/user:/userid: 前缀 */
+function normalizeWecomAllowFromEntry(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/^wecom:/, "")
+        .replace(/^user:/, "")
+        .replace(/^userid:/, "");
+}
+/** 判断发送者是否在白名单中 */
+function isWecomSenderAllowed(senderUserId, allowFrom) {
+    const list = allowFrom.map((entry) => normalizeWecomAllowFromEntry(entry)).filter(Boolean);
+    if (list.includes("*"))
+        return true;
+    const normalizedSender = normalizeWecomAllowFromEntry(senderUserId);
+    if (!normalizedSender)
+        return false;
+    return list.includes(normalizedSender);
+}
+/**
+ * 解析命令授权状态
+ *
+ * 适配新版 WeComConfig 的扁平化字段：
+ * - dmPolicy → accountConfig.dmPolicy
+ * - allowFrom → accountConfig.allowFrom
+ */
+export async function resolveWecomCommandAuthorization(params) {
+    const { core, cfg, accountConfig, rawBody, senderUserId } = params;
+    const dmPolicy = (accountConfig.dmPolicy ?? "pairing");
+    const configAllowFrom = (accountConfig.allowFrom ?? []).map((v) => String(v));
+    const shouldComputeAuth = core.channel.commands.shouldComputeCommandAuthorized(rawBody, cfg);
+    // WeCom channel 不支持 pairing CLI（"Channel wecom does not support pairing"），
+    // 因此 pairing 策略等同于 allowlist。
+    // Policy 语义：
+    // - open: 命令对所有人放行（除非更高层级的 access-groups 拒绝）
+    // - allowlist: 命令需要 allowFrom 白名单
+    // - pairing: 等同 allowlist（因 WeCom 不支持 pairing CLI）
+    const effectiveAllowFrom = dmPolicy === "open" ? ["*"] : configAllowFrom;
+    const senderAllowed = isWecomSenderAllowed(senderUserId, effectiveAllowFrom);
+    const allowAllConfigured = effectiveAllowFrom.some((entry) => normalizeWecomAllowFromEntry(entry) === "*");
+    const authorizerConfigured = allowAllConfigured || effectiveAllowFrom.length > 0;
+    const useAccessGroups = cfg.commands?.useAccessGroups !== false;
+    const commandAuthorized = shouldComputeAuth
+        ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+            useAccessGroups,
+            authorizers: [{ configured: authorizerConfigured, allowed: senderAllowed }],
+        })
+        : undefined;
+    return {
+        shouldComputeAuth,
+        dmPolicy,
+        senderAllowed,
+        authorizerConfigured,
+        commandAuthorized,
+        effectiveAllowFrom,
+    };
+}
+// ============================================================================
+// 未授权提示文案构建
+// ============================================================================
+/**
+ * 构建未授权命令的中文提示文案
+ *
+ * @param scope - "bot"（智能机器人）或 "agent"（自建应用）
+ */
+export function buildWecomUnauthorizedCommandPrompt(params) {
+    const user = params.senderUserId || "unknown";
+    const policy = params.dmPolicy;
+    const scopeLabel = params.scope === "bot" ? "Bot（智能机器人）" : "Agent（自建应用）";
+    const dmPrefix = params.scope === "bot" ? "channels.wecom.bot" : "channels.wecom.agent";
+    const allowCmd = (value) => `openclaw config set ${dmPrefix}.allowFrom '${value}'`;
+    const policyCmd = (value) => `openclaw config set ${dmPrefix}.dmPolicy "${value}"`;
+    if (policy === "disabled") {
+        return [
+            `无权限执行命令（${scopeLabel} 已禁用：dmPolicy=disabled）`,
+            `触发者：${user}`,
+            `管理员：${policyCmd("open")}（全放开）或 ${policyCmd("allowlist")}（白名单）`,
+        ].join("\n");
+    }
+    return [
+        `无权限执行命令（入口：${scopeLabel}，userid：${user}）`,
+        `管理员全放开：${policyCmd("open")}`,
+        `管理员放行该用户：${policyCmd("allowlist")}`,
+        `然后设置白名单：${allowCmd(JSON.stringify([user]))}`,
+        `如果仍被拦截：检查 commands.useAccessGroups/访问组`,
+    ].join("\n");
+}

package/dist/src/webhook/gateway.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Webhook Gateway 生命周期管理
+ *
+ * 从 @mocrane/wecom gateway-monitor.ts 部分迁移（仅 Webhook 部分）。
+ * 负责：初始化状态、注册 Target、启停管理。
+ *
+ * 关键设计：
+ * - MonitorState 是全局单例（monitorState），所有账号共享同一个 StreamStore 和 ActiveReplyStore
+ * - Target 注册/注销不影响 monitorState 生命周期，只控制 pruneTimer 的启停
+ * - 每个账号注册多条路径（兼容历史路径 + 推荐路径 + 多账号路径）
+ * - 按 accountId 管理各自的 unregister，stop 时只注销该账号的 Target
+ */
+import type { WebhookGatewayContext } from "./types.js";
+import { WebhookMonitorState } from "./state.js";
+/**
+ * 获取当前的 MonitorState 实例（全局单例）
+ *
+ * 供 monitor.ts 等内部模块调用以访问 StreamStore 和 ActiveReplyStore。
+ */
+export declare function getMonitorState(): WebhookMonitorState;
+/**
+ * 启动 Webhook Gateway
+ *
+ * 1. 验证 Webhook 配置
+ * 2. 确保 pruneTimer 启动
+ * 3. 设置 FlushHandler（仅首次）
+ * 4. 解析并注册多条 Webhook 路径
+ */
+export declare function startWebhookGateway(ctx: WebhookGatewayContext): void;
+/**
+ * 停止 Webhook Gateway
+ *
+ * 1. 注销该账号的 Target（不影响其他账号）
+ * 2. 如果没有任何活跃 Target，停止清理定时器
+ */
+export declare function stopWebhookGateway(ctx: WebhookGatewayContext): void;