@mocrane/wecom 2026.2.5

package/src/onboarding.ts

@@ -0,0 +1,472 @@
+/**
+ * WeCom 配置向导 (Onboarding)
+ * 支持 Bot、Agent 和双模式同时启动的交互式配置流程
+ */
+
+import type {
+    ChannelOnboardingAdapter,
+    ChannelOnboardingDmPolicy,
+    OpenClawConfig,
+    WizardPrompter,
+} from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type { WecomConfig, WecomBotConfig, WecomAgentConfig, WecomDmConfig } from "./types/index.js";
+
+const channel = "wecom" as const;
+
+type WecomMode = "bot" | "agent" | "both";
+
+// ============================================================
+// 辅助函数
+// ============================================================
+
+function getWecomConfig(cfg: OpenClawConfig): WecomConfig | undefined {
+    return cfg.channels?.wecom as WecomConfig | undefined;
+}
+
+function setWecomEnabled(cfg: OpenClawConfig, enabled: boolean): OpenClawConfig {
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            wecom: {
+                ...(cfg.channels?.wecom ?? {}),
+                enabled,
+            },
+        },
+    } as OpenClawConfig;
+}
+
+function setWecomBotConfig(cfg: OpenClawConfig, bot: WecomBotConfig): OpenClawConfig {
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            wecom: {
+                ...(cfg.channels?.wecom ?? {}),
+                enabled: true,
+                bot,
+            },
+        },
+    } as OpenClawConfig;
+}
+
+function setWecomAgentConfig(cfg: OpenClawConfig, agent: WecomAgentConfig): OpenClawConfig {
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            wecom: {
+                ...(cfg.channels?.wecom ?? {}),
+                enabled: true,
+                agent,
+            },
+        },
+    } as OpenClawConfig;
+}
+
+function setGatewayBindLan(cfg: OpenClawConfig): OpenClawConfig {
+    return {
+        ...cfg,
+        gateway: {
+            ...(cfg.gateway ?? {}),
+            bind: "lan",
+        },
+    } as OpenClawConfig;
+}
+
+function setWecomDmPolicy(
+    cfg: OpenClawConfig,
+    mode: "bot" | "agent",
+    dm: WecomDmConfig,
+): OpenClawConfig {
+    const wecom = getWecomConfig(cfg) ?? {};
+    if (mode === "bot") {
+        return {
+            ...cfg,
+            channels: {
+                ...cfg.channels,
+                wecom: {
+                    ...wecom,
+                    bot: {
+                        ...wecom.bot,
+                        dm,
+                    },
+                },
+            },
+        } as OpenClawConfig;
+    }
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            wecom: {
+                ...wecom,
+                agent: {
+                    ...wecom.agent,
+                    dm,
+                },
+            },
+        },
+    } as OpenClawConfig;
+}
+
+// ============================================================
+// 欢迎与引导
+// ============================================================
+
+async function showWelcome(prompter: WizardPrompter): Promise<void> {
+    await prompter.note(
+        [
+            "🚀 欢迎使用企业微信（WeCom）接入向导",
+            "本插件支持「智能体 Bot」与「自建应用 Agent」双模式并行。",
+        ].join("\n"),
+        "WeCom 配置向导",
+    );
+}
+
+// ============================================================
+// 模式选择
+// ============================================================
+
+async function promptMode(prompter: WizardPrompter): Promise<WecomMode> {
+    const choice = await prompter.select({
+        message: "请选择您要配置的接入模式:",
+        options: [
+            {
+                value: "bot",
+                label: "Bot 模式 (智能机器人)",
+                hint: "回调速度快，支持流式占位符，适合日常对话",
+            },
+            {
+                value: "agent",
+                label: "Agent 模式 (自建应用)",
+                hint: "功能最全，支持 API 主动推送、发送文件/视频、交互卡片",
+            },
+            {
+                value: "both",
+                label: "双模式 (Bot + Agent 同时启用)",
+                hint: "推荐：Bot 用于快速对话，Agent 用于主动推送和媒体发送",
+            },
+        ],
+        initialValue: "both",
+    });
+    return choice as WecomMode;
+}
+
+// ============================================================
+// Bot 模式配置
+// ============================================================
+
+async function configureBotMode(
+    cfg: OpenClawConfig,
+    prompter: WizardPrompter,
+): Promise<OpenClawConfig> {
+    await prompter.note(
+        [
+            "正在配置 Bot 模式...",
+            "",
+            "💡 操作指南: 请在企微后台【管理工具 -> 智能机器人】开启 API 模式。",
+            "🔗 回调 URL: https://您的域名/wecom/bot",
+            "",
+            "请先在后台填入回调 URL，然后获取以下信息。",
+        ].join("\n"),
+        "Bot 模式配置",
+    );
+
+    const token = String(
+        await prompter.text({
+            message: "请输入 Token:",
+            validate: (value: string | undefined) => (value?.trim() ? undefined : "Token 不能为空"),
+        }),
+    ).trim();
+
+    const encodingAESKey = String(
+        await prompter.text({
+            message: "请输入 EncodingAESKey:",
+            validate: (value: string | undefined) => {
+                const v = value?.trim() ?? "";
+                if (!v) return "EncodingAESKey 不能为空";
+                if (v.length !== 43) return "EncodingAESKey 应为 43 个字符";
+                return undefined;
+            },
+        }),
+    ).trim();
+
+    const streamPlaceholder = await prompter.text({
+        message: "流式占位符 (可选):",
+        placeholder: "正在思考...",
+        initialValue: "正在思考...",
+    });
+
+    const welcomeText = await prompter.text({
+        message: "欢迎语 (可选):",
+        placeholder: "你好！我是 AI 助手",
+        initialValue: "你好！我是 AI 助手",
+    });
+
+    const botConfig: WecomBotConfig = {
+        token,
+        encodingAESKey,
+        streamPlaceholderContent: streamPlaceholder?.trim() || undefined,
+        welcomeText: welcomeText?.trim() || undefined,
+    };
+
+    return setWecomBotConfig(cfg, botConfig);
+}
+
+// ============================================================
+// Agent 模式配置
+// ============================================================
+
+async function configureAgentMode(
+    cfg: OpenClawConfig,
+    prompter: WizardPrompter,
+): Promise<OpenClawConfig> {
+    await prompter.note(
+        [
+            "正在配置 Agent 模式...",
+            "",
+            "💡 操作指南: 请在企微后台【应用管理 -> 自建应用】创建应用。",
+        ].join("\n"),
+        "Agent 模式配置",
+    );
+
+    const corpId = String(
+        await prompter.text({
+            message: "请输入 CorpID (企业ID):",
+            validate: (value: string | undefined) => (value?.trim() ? undefined : "CorpID 不能为空"),
+        }),
+    ).trim();
+
+    const agentIdStr = String(
+        await prompter.text({
+            message: "请输入 AgentID (应用ID):",
+            validate: (value: string | undefined) => {
+                const v = value?.trim() ?? "";
+                if (!v) return "AgentID 不能为空";
+                if (!/^\d+$/.test(v)) return "AgentID 应为数字";
+                return undefined;
+            },
+        }),
+    ).trim();
+    const agentId = Number(agentIdStr);
+
+    const corpSecret = String(
+        await prompter.text({
+            message: "请输入 Secret (应用密钥):",
+            validate: (value: string | undefined) => (value?.trim() ? undefined : "Secret 不能为空"),
+        }),
+    ).trim();
+
+    await prompter.note(
+        [
+            "💡 操作指南: 请在自建应用详情页进入【接收消息 -> 设置API接收】。",
+            "🔗 回调 URL: https://您的域名/wecom/agent",
+            "",
+            "请先在后台填入回调 URL，然后获取以下信息。",
+        ].join("\n"),
+        "回调配置",
+    );
+
+    const token = String(
+        await prompter.text({
+            message: "请输入 Token (回调令牌):",
+            validate: (value: string | undefined) => (value?.trim() ? undefined : "Token 不能为空"),
+        }),
+    ).trim();
+
+    const encodingAESKey = String(
+        await prompter.text({
+            message: "请输入 EncodingAESKey (回调加密密钥):",
+            validate: (value: string | undefined) => {
+                const v = value?.trim() ?? "";
+                if (!v) return "EncodingAESKey 不能为空";
+                if (v.length !== 43) return "EncodingAESKey 应为 43 个字符";
+                return undefined;
+            },
+        }),
+    ).trim();
+
+    const welcomeText = await prompter.text({
+        message: "欢迎语 (可选):",
+        placeholder: "欢迎使用智能助手",
+        initialValue: "欢迎使用智能助手",
+    });
+
+    const agentConfig: WecomAgentConfig = {
+        corpId,
+        corpSecret,
+        agentId,
+        token,
+        encodingAESKey,
+        welcomeText: welcomeText?.trim() || undefined,
+    };
+
+    return setWecomAgentConfig(cfg, agentConfig);
+}
+
+// ============================================================
+// DM 策略配置
+// ============================================================
+
+async function promptDmPolicy(
+    cfg: OpenClawConfig,
+    prompter: WizardPrompter,
+    modes: ("bot" | "agent")[],
+): Promise<OpenClawConfig> {
+    const policyChoice = await prompter.select({
+        message: "请选择私聊 (DM) 访问策略:",
+        options: [
+            { value: "pairing", label: "配对模式", hint: "推荐：安全，未知用户需授权" },
+            { value: "allowlist", label: "白名单模式", hint: "仅允许特定 UserID" },
+            { value: "open", label: "开放模式", hint: "任何人可发起" },
+            { value: "disabled", label: "禁用私聊", hint: "不接受私聊消息" },
+        ],
+        initialValue: "pairing",
+    });
+
+    const policy = policyChoice as "pairing" | "allowlist" | "open" | "disabled";
+    let allowFrom: string[] | undefined;
+
+    if (policy === "allowlist") {
+        const allowFromStr = String(
+            await prompter.text({
+                message: "请输入白名单 UserID (多个用逗号分隔):",
+                placeholder: "user1,user2",
+                validate: (value: string | undefined) => (value?.trim() ? undefined : "请输入至少一个 UserID"),
+            }),
+        ).trim();
+        allowFrom = allowFromStr.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+
+    const dm: WecomDmConfig = { policy, allowFrom };
+
+    let result = cfg;
+    for (const mode of modes) {
+        result = setWecomDmPolicy(result, mode, dm);
+    }
+    return result;
+}
+
+// ============================================================
+// 配置汇总
+// ============================================================
+
+async function showSummary(cfg: OpenClawConfig, prompter: WizardPrompter): Promise<void> {
+    const wecom = getWecomConfig(cfg);
+    const lines: string[] = ["✅ 配置已保存！", ""];
+
+    if (wecom?.bot?.token) {
+        lines.push("📱 Bot 模式: 已配置");
+        lines.push(`   回调 URL: https://您的域名/wecom/bot`);
+    }
+
+    if (wecom?.agent?.corpId) {
+        lines.push("🏢 Agent 模式: 已配置");
+        lines.push(`   回调 URL: https://您的域名/wecom/agent`);
+    }
+
+    lines.push("");
+    lines.push("⚠️ 请确保您已在企微后台填写了正确的回调 URL，");
+    lines.push("   并点击了后台的『保存』按钮完成验证。");
+
+    await prompter.note(lines.join("\n"), "配置完成");
+}
+
+// ============================================================
+// DM Policy Adapter
+// ============================================================
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+    label: "WeCom",
+    channel,
+    policyKey: "channels.wecom.bot.dm.policy",
+    allowFromKey: "channels.wecom.bot.dm.allowFrom",
+    getCurrent: (cfg: OpenClawConfig) => {
+        const wecom = getWecomConfig(cfg);
+        return (wecom?.bot?.dm?.policy ?? "pairing") as "pairing";
+    },
+    setPolicy: (cfg: OpenClawConfig, policy: "pairing" | "allowlist" | "open" | "disabled") => {
+        return setWecomDmPolicy(cfg, "bot", { policy });
+    },
+    promptAllowFrom: async ({ cfg, prompter }: { cfg: OpenClawConfig; prompter: WizardPrompter }) => {
+        const allowFromStr = String(
+            await prompter.text({
+                message: "请输入白名单 UserID:",
+                validate: (value: string | undefined) => (value?.trim() ? undefined : "请输入 UserID"),
+            }),
+        ).trim();
+        const allowFrom = allowFromStr.split(",").map((s) => s.trim()).filter(Boolean);
+        return setWecomDmPolicy(cfg, "bot", { policy: "allowlist", allowFrom });
+    },
+};
+
+// ============================================================
+// Onboarding Adapter
+// ============================================================
+
+export const wecomOnboardingAdapter: ChannelOnboardingAdapter = {
+    channel,
+    dmPolicy,
+    getStatus: async ({ cfg }: { cfg: OpenClawConfig }) => {
+        const wecom = getWecomConfig(cfg);
+        const botConfigured = Boolean(wecom?.bot?.token && wecom?.bot?.encodingAESKey);
+        const agentConfigured = Boolean(
+            wecom?.agent?.corpId && wecom?.agent?.corpSecret && wecom?.agent?.agentId,
+        );
+        const configured = botConfigured || agentConfigured;
+
+        const statusParts: string[] = [];
+        if (botConfigured) statusParts.push("Bot ✓");
+        if (agentConfigured) statusParts.push("Agent ✓");
+
+        return {
+            channel,
+            configured,
+            statusLines: [
+                `WeCom: ${configured ? statusParts.join(" + ") : "需要配置"}`,
+            ],
+            selectionHint: configured
+                ? `configured · ${statusParts.join(" + ")}`
+                : "enterprise-ready · dual-mode",
+            quickstartScore: configured ? 1 : 8,
+        };
+    },
+    configure: async ({ cfg, prompter }: { cfg: OpenClawConfig; prompter: WizardPrompter }) => {
+        // 1. 欢迎
+        await showWelcome(prompter);
+
+        // 2. 模式选择
+        const mode = await promptMode(prompter);
+
+        let next = cfg;
+        const configuredModes: ("bot" | "agent")[] = [];
+
+        // 3. 配置 Bot
+        if (mode === "bot" || mode === "both") {
+            next = await configureBotMode(next, prompter);
+            configuredModes.push("bot");
+        }
+
+        // 4. 配置 Agent
+        if (mode === "agent" || mode === "both") {
+            next = await configureAgentMode(next, prompter);
+            configuredModes.push("agent");
+        }
+
+        // 5. DM 策略
+        next = await promptDmPolicy(next, prompter, configuredModes);
+
+        // 6. 启用通道
+        next = setWecomEnabled(next, true);
+
+        // 7. 设置 gateway.bind 为 lan（允许外部访问回调）
+        next = setGatewayBindLan(next);
+
+        // 8. 汇总
+        await showSummary(next, prompter);
+
+        return { cfg: next, accountId: DEFAULT_ACCOUNT_ID };
+    },
+};

package/src/outbound.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("./agent/api-client.js", () => ({
+  sendText: vi.fn(),
+  sendMedia: vi.fn(),
+  uploadMedia: vi.fn(),
+}));
+
+describe("wecomOutbound", () => {
+  it("does not crash when called with core outbound params", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    await expect(
+      wecomOutbound.sendMedia({
+        cfg: {},
+        to: "wr-test-chat",
+        text: "caption",
+        mediaUrl: "https://example.com/media.png",
+      } as any),
+    ).rejects.toThrow(/Agent mode/i);
+  });
+
+  it("routes sendText to agent chatId/userid", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const api = await import("./agent/api-client.js");
+    const now = vi.spyOn(Date, "now").mockReturnValue(123);
+    (api.sendText as any).mockResolvedValue(undefined);
+
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          agent: {
+            corpId: "corp",
+            corpSecret: "secret",
+            agentId: 1000002,
+            token: "token",
+            encodingAESKey: "aes",
+          },
+        },
+      },
+    };
+
+    // Chat ID (wr/wc) is intentionally NOT supported for Agent outbound.
+    await expect(wecomOutbound.sendText({ cfg, to: "wr123", text: "hello" } as any)).rejects.toThrow(
+      /不支持向群 chatId 发送/,
+    );
+    expect(api.sendText).not.toHaveBeenCalled();
+
+    // Test: User ID (Default)
+    const userResult = await wecomOutbound.sendText({
+      cfg,
+      to: "userid123",
+      text: "hi",
+    } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({
+        chatId: undefined,
+        toUser: "userid123",
+        toParty: undefined,
+        toTag: undefined,
+        text: "hi",
+      }),
+    );
+    expect(userResult.messageId).toBe("agent-123");
+
+    (api.sendText as any).mockClear();
+
+    // Test: User ID explicit
+    await wecomOutbound.sendText({ cfg, to: "user:zhangsan", text: "hi" } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({ toUser: "zhangsan", toParty: undefined }),
+    );
+
+    (api.sendText as any).mockClear();
+
+    // Test: Party ID (Numeric)
+    await wecomOutbound.sendText({ cfg, to: "1001", text: "hi party" } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({ toUser: undefined, toParty: "1001" }),
+    );
+
+    (api.sendText as any).mockClear();
+
+    // Test: Party ID Explicit
+    await wecomOutbound.sendText({ cfg, to: "party:2002", text: "hi party 2" } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({ toUser: undefined, toParty: "2002" }),
+    );
+
+    (api.sendText as any).mockClear();
+
+    // Test: Tag ID Explicit
+    await wecomOutbound.sendText({ cfg, to: "tag:1", text: "hi tag" } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({ toUser: undefined, toTag: "1" }),
+    );
+
+    now.mockRestore();
+  });
+
+  it("suppresses /new ack for bot sessions but not agent sessions", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const api = await import("./agent/api-client.js");
+    const now = vi.spyOn(Date, "now").mockReturnValue(456);
+    (api.sendText as any).mockResolvedValue(undefined);
+    (api.sendText as any).mockClear();
+
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          agent: {
+            corpId: "corp",
+            corpSecret: "secret",
+            agentId: 1000002,
+            token: "token",
+            encodingAESKey: "aes",
+          },
+        },
+      },
+    };
+
+    const ack = "✅ New session started · model: openai-codex/gpt-5.2";
+
+    // Bot 会话（wecom:...）应抑制，避免私信回执
+    const r1 = await wecomOutbound.sendText({ cfg, to: "wecom:userid123", text: ack } as any);
+    expect(api.sendText).not.toHaveBeenCalled();
+    expect(r1.messageId).toBe("suppressed-456");
+
+    (api.sendText as any).mockClear();
+
+    // Agent 会话（wecom-agent:...）允许发送回执
+    await wecomOutbound.sendText({ cfg, to: "wecom-agent:userid123", text: ack } as any);
+    expect(api.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({
+        toUser: "userid123",
+        text: "✅ 已开启新会话（模型：openai-codex/gpt-5.2）",
+      }),
+    );
+
+    now.mockRestore();
+  });
+});