@yanhaidao/wecom 2.2.7 → 2.3.2

package/src/types/account.ts

@@ -2,7 +2,13 @@
  * WeCom 账号类型定义
  */
 
-import type { WecomBotConfig, WecomAgentConfig, WecomDmConfig, WecomNetworkConfig } from "./config.js";
+import type {
+    WecomBotConfig,
+    WecomAgentConfig,
+    WecomDmConfig,
+    WecomNetworkConfig,
+    WecomAccountConfig,
+} from "./config.js";
 
 /**
  * 解析后的 Bot 账号
@@ -40,8 +46,8 @@ export type ResolvedAgentAccount = {
     corpId: string;
     /** 应用 Secret */
     corpSecret: string;
-    /** 应用 ID (数字) */
-    agentId: number;
+    /** 应用 ID (数字，可选) */
+    agentId?: number;
     /** 回调 Token */
     token: string;
     /** 回调加密密钥 */
@@ -52,23 +58,46 @@ export type ResolvedAgentAccount = {
     network?: WecomNetworkConfig;
 };
 
-/**
- * 已解析的模式状态
- */
-export type ResolvedMode = {
-    /** Bot 模式是否已配置 */
-    bot: boolean;
-    /** Agent 模式是否已配置 */
-    agent: boolean;
+/** Matrix/Legacy 的统一账号解析结果 */
+export type ResolvedWecomAccount = {
+    /** 账号 ID（用于 bindings.match.accountId） */
+    accountId: string;
+    /** 展示名称 */
+    name?: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 是否具备至少一种可用能力（bot/agent） */
+    configured: boolean;
+    /** 原始账号配置（Matrix 条目或 Legacy 聚合） */
+    config: WecomAccountConfig;
+    /** Bot 能力 */
+    bot?: ResolvedBotAccount;
+    /** Agent 能力 */
+    agent?: ResolvedAgentAccount;
 };
 
+/** 解析模式 */
+export type ResolvedMode = "disabled" | "legacy" | "matrix";
+
 /**
- * 解析后的 WeCom 账号集合
+ * 已解析的模式状态
  */
 export type ResolvedWecomAccounts = {
-    /** Bot 模式账号 */
+    /** 当前模式 */
+    mode: ResolvedMode;
+    /** 默认账号 ID */
+    defaultAccountId: string;
+    /** 账号集合（Legacy 下仅 default） */
+    accounts: Record<string, ResolvedWecomAccount>;
+    /**
+     * 向后兼容：默认账号的 bot（历史调用点仍可读取）。
+     * Matrix 下等价于 defaultAccountId 对应账号的 bot。
+     */
     bot?: ResolvedBotAccount;
-    /** Agent 模式账号 */
+    /**
+     * 向后兼容：默认账号的 agent（历史调用点仍可读取）。
+     * Matrix 下等价于 defaultAccountId 对应账号的 agent。
+     */
     agent?: ResolvedAgentAccount;
 };
 

package/src/types/config.ts

@@ -30,15 +30,33 @@ export type WecomNetworkConfig = {
     egressProxyUrl?: string;
 };
 
+/** 路由行为配置 */
+export type WecomRoutingConfig = {
+    /**
+     * 当路由未命中 bindings（matchedBy=default）时是否拒绝继续处理。
+     * - true: fail-closed（推荐于多账号）
+     * - false: 允许回退默认 agent（历史兼容）
+     */
+    failClosedOnDefaultRoute?: boolean;
+};
+
 /**
  * Bot 模式配置 (智能体)
  * 用于接收 JSON 格式回调 + 流式回复
  */
 export type WecomBotConfig = {
+    /** 智能机器人 ID（用于 Matrix 模式二次身份确认） */
+    aibotid?: string;
     /** 回调 Token (企微后台生成) */
     token: string;
     /** 回调加密密钥 (企微后台生成) */
     encodingAESKey: string;
+    /**
+     * BotId 列表（可选，用于审计与告警）。
+     * - 回调路由优先由 URL + 签名决定；botIds 不参与强制拦截。
+     * - 当解密后的 aibotid 不在 botIds 中时，仅记录告警日志。
+     */
+    botIds?: string[];
     /** 接收者 ID (可选，用于解密校验) */
     receiveId?: string;
     /** 流式消息占位符 */
@@ -58,8 +76,8 @@ export type WecomAgentConfig = {
     corpId: string;
     /** 应用 Secret */
     corpSecret: string;
-    /** 应用 ID */
-    agentId: number | string;
+    /** 应用 ID（可选；不填时可接收回调，但主动发送需具备该字段） */
+    agentId?: number | string;
     /** 回调 Token (企微后台「设置API接收」) */
     token: string;
     /** 回调加密密钥 (企微后台「设置API接收」) */
@@ -93,10 +111,27 @@ export type WecomConfig = {
     bot?: WecomBotConfig;
     /** Agent 模式配置 (自建应用) */
     agent?: WecomAgentConfig;
+    /**
+     * 多账号配置（每个账号可包含 bot + agent，作为一组）。
+     * accountId 用于与 OpenClaw `bindings[].match.accountId` 对齐，从而把不同 WeCom 账号路由到不同 OpenClaw agent。
+     */
+    accounts?: Record<string, WecomAccountConfig>;
+    /** 默认账号（可选） */
+    defaultAccount?: string;
     /** 媒体处理配置 */
     media?: WecomMediaConfig;
     /** 网络配置 */
     network?: WecomNetworkConfig;
+    /** 路由配置 */
+    routing?: WecomRoutingConfig;
     /** 动态 Agent 配置 */
     dynamicAgents?: WecomDynamicAgentsConfig;
 };
+
+/** Matrix 账号条目 */
+export type WecomAccountConfig = {
+    enabled?: boolean;
+    name?: string;
+    bot?: WecomBotConfig;
+    agent?: WecomAgentConfig;
+};

package/src/types/index.ts

@@ -7,9 +7,11 @@ export * from "./constants.js";
 
 // 配置类型
 export type {
+    WecomAccountConfig,
     WecomDmConfig,
     WecomMediaConfig,
     WecomNetworkConfig,
+    WecomRoutingConfig,
     WecomBotConfig,
     WecomAgentConfig,
     WecomConfig,
@@ -17,6 +19,7 @@ export type {
 
 // 账号类型
 export type {
+    ResolvedWecomAccount,
     ResolvedBotAccount,
     ResolvedAgentAccount,
     ResolvedMode,

package/src/types.ts

@@ -1,143 +1,34 @@
-export type WecomDmConfig = {
-  policy?: "pairing" | "allowlist" | "open" | "disabled";
-  allowFrom?: Array<string | number>;
-};
-
-export type WecomAccountConfig = {
-  name?: string;
-  enabled?: boolean;
-
-  webhookPath?: string;
-  token?: string;
-  encodingAESKey?: string;
-  receiveId?: string;
-
-  streamPlaceholderContent?: string;
-
-  dm?: WecomDmConfig;
-  welcomeText?: string;
-};
-
-export type WecomConfig = WecomAccountConfig & {
-  accounts?: Record<string, WecomAccountConfig>;
-  defaultAccount?: string;
-};
-
-export type ResolvedWecomAccount = {
-  accountId: string;
-  name?: string;
-  enabled: boolean;
-  configured: boolean;
-  token?: string;
-  encodingAESKey?: string;
-  receiveId: string;
-  config: WecomAccountConfig;
-};
-
-export type WecomInboundBase = {
-  msgid?: string;
-  aibotid?: string;
-  chattype?: "single" | "group";
-  chatid?: string;
-  response_url?: string;
-  from?: { userid?: string; corpid?: string };
-  msgtype?: string;
-};
-
-export type WecomInboundText = WecomInboundBase & {
-  msgtype: "text";
-  text?: { content?: string };
-  quote?: unknown;
-};
-
-export type WecomInboundVoice = WecomInboundBase & {
-  msgtype: "voice";
-  voice?: { content?: string };
-  quote?: unknown;
-};
-
-export type WecomInboundStreamRefresh = WecomInboundBase & {
-  msgtype: "stream";
-  stream?: { id?: string };
-};
-
-export type WecomInboundEvent = WecomInboundBase & {
-  msgtype: "event";
-  create_time?: number;
-  event?: {
-    eventtype?: string;
-    [key: string]: unknown;
-  };
-};
-
-export type WecomInboundQuote = {
-  msgtype?: "text" | "image" | "mixed" | "voice" | "file";
-  text?: { content?: string };
-  image?: { url?: string };
-  mixed?: {
-    msg_item?: Array<{
-      msgtype: "text" | "image";
-      text?: { content?: string };
-      image?: { url?: string };
-    }>;
-  };
-  voice?: { content?: string };
-  file?: { url?: string };
-};
-
-export type WecomInboundMessage =
-  | (WecomInboundText & { quote?: WecomInboundQuote })
-  | WecomInboundVoice
-  | WecomInboundStreamRefresh
-  | WecomInboundEvent
-  | (WecomInboundBase & { quote?: WecomInboundQuote } & Record<string, unknown>);
-
-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 WecomInboundTemplateCardEvent = WecomInboundBase & {
-  msgtype: "event";
-  event: {
-    eventtype: "template_card_event";
-    template_card_event: {
-      card_type: string;
-      event_key: string;
-      task_id: string;
-      selected_items?: {
-        selected_item: Array<{
-          question_key: string;
-          option_ids: { option_id: string[] };
-        }>;
-      };
-    };
-  };
-};
-
-
 /**
- * Template card event payload (button click, checkbox, select)
+ * Backward-compatible type bridge.
+ * Canonical definitions live in `src/types/*`.
  */
+export type {
+  WecomDmConfig,
+  WecomAccountConfig,
+  WecomConfig,
+  ResolvedWecomAccount,
+  WecomInboundQuote,
+  WecomTemplateCard,
+  WecomOutboundMessage,
+} from "./types/index.js";
+
+import type {
+  WecomBotInboundBase,
+  WecomBotInboundText,
+  WecomBotInboundVoice,
+  WecomBotInboundStreamRefresh,
+  WecomBotInboundEvent,
+  WecomBotInboundMessage,
+} from "./types/index.js";
+
+export type WecomInboundBase = WecomBotInboundBase;
+export type WecomInboundText = WecomBotInboundText;
+export type WecomInboundVoice = WecomBotInboundVoice;
+export type WecomInboundStreamRefresh = WecomBotInboundStreamRefresh;
+export type WecomInboundEvent = WecomBotInboundEvent;
+export type WecomInboundMessage = WecomBotInboundMessage;
+
+export type WecomInboundTemplateCardEvent = WecomBotInboundEvent;
 export type WecomTemplateCardEventPayload = {
   card_type: string;
   event_key: string;
@@ -148,12 +39,3 @@ export type WecomTemplateCardEventPayload = {
     option_ids?: string[];
   };
 };
-
-/**
- * Outbound message types that can be sent via response_url
- */
-export type WecomOutboundMessage =
-  | { msgtype: "text"; text: { content: string } }
-  | { msgtype: "markdown"; markdown: { content: string } }
-  | { msgtype: "template_card"; template_card: WecomTemplateCard };
-

package/GEMINI.md

@@ -1,76 +0,0 @@
-# 企业微信 (WeCom) 插件上下文
-
-## 平台架构：机器人 (Bot) vs 自建应用 (Agent)
-
-本插件采用 **双模 (Dual-Mode)** 架构，结合了企业微信“智能机器人”和“自建应用”的优势。
-
-### 1. 定义与边界
-
-| 特性 | **Bot (智能机器人)** | **Agent (自建应用)** |
-| :--- | :--- | :--- |
-| **身份** | 虚拟用户/助手。 | 工作台中的服务应用。 |
-| **位置** | 存在于 **会话** 中 (单聊或群聊)。 | 存在于 **工作台** 或应用列表。 |
-| **协议** | **JSON** (加密)。 | **XML** (加密)。 |
-| **交互** | 对话式 (回复用户)。 | 事务式 (通知用户/系统)。 |
-| **流式 (Stream)** | ✅ **支持** (打字机效果)。 | ❌ 不支持。 |
-| **文件能力** | ❌ **受限** (被动回复无法发文件)。 | ✅ **完整支持** (API 发送视频、文件、图片)。 |
-| **群聊支持** | ✅ 原生支持 (可被 @)。 | ⚠️ 受限 (仅能在自建群或通过 API 推送)。 |
-
-### 2. 通信协议
-
-#### A. Bot (智能机器人)
-*   **接收 (回调)**:
-    *   **格式**: JSON。
-    *   **单聊**: `chattype: "single"`. 无 `chatid`。`cid` = `from.userid`。
-    *   **群聊**: `chattype: "group"`. 有 `chatid`。`cid` = `chatid`。
-*   **发送 (回复)**:
-    *   **交互回复**: 使用回调中的 `response_url`。支持 `markdown`, `template_card`。**不支持文件/视频**。
-    *   **主动推送**: 使用 Webhook Key。
-
-#### B. Agent (自建应用)
-*   **接收 (回调)**:
-    *   **格式**: XML。
-    *   **结构**: `<ToUserName>`, `<FromUserName>`, `<MsgType>`, `<Content>`。
-*   **发送 (推送)**:
-    *   **API**: `message/send`。
-    *   **能力**: 支持所有媒体类型 (文件, 视频, 语音, 文本, 卡片)。
-    *   **对象**: 用户 (`touser`), 部门 (`toparty`), 标签 (`totag`)。
-
----
-
-## 核心策略：机器人优先，智能体兜底 (接近 6 分钟切换)
-
-### 目标
-*   **默认**: 用户在 Bot 会话触发，结果在 Bot 会话内完成回复（含流式）。
-*   **兜底**: 当 Bot 因超时（接近 6 分钟限制）、异常或流式窗口结束无法完成交付时，若配置了 Agent，则由 Agent 私信触发用户发送最终结果。
-
-### 关键约束
-*   **6 分钟窗口**: 企业微信智能机器人流式链路最多维持 6 分钟。超过后连接断开。
-
-### 流程详解
-
-#### 1. 启动阶段 (Bot)
-1.  **接收消息**: 解析 JSON 回调。
-2.  **生成 StreamID**: 确定性生成 `streamId = hash(accountId + aibotid + msgid)`，防止并发重试导致重复创建流。
-3.  **快速响应**: 立即返回“已接收，处理中”或流式首包，建立连接。
-
-#### 2. 执行阶段 (Worker)
-4.  **异步处理**: 任务入队执行。
-5.  **流式刷新**: 当收到企微的“流式消息刷新”回调时，根据 `streamId` 返回最新生成的内容。
-
-#### 3. 正常交付 (Bot)
-6.  **完成**: 任务在 6 分钟内完成，发送 `finish=true` 信号结束流式消息。
-
-#### 4. 异常切换 (Agent 兜底)
-7.  **触发条件**:
-    *   **超时临界**: `now >= createdAt + 6min - 安全阈值(30s)`。
-    *   **链路中断**: Bot 刷新回调长时间未到达 (如 > 60s)。
-    *   **发送异常**: Bot 接口报错。
-8.  **切换动作**:
-    *   **状态标记**: 将任务标记为 `agent_fallback`。
-    *   **用户提示**: (可选) Bot 在群内尝试发送“结果将私信送达”。
-    *   **私信推送**: Agent 调用 `message/send` 接口，将最终结果（文本/文件）推送给触发者 `userId`。
-    *   **注意**: 即使原会话是群聊，兜底结果通常通过 Agent **私信** 发送给触发者，因为 Agent 难以直接向普通群推送消息。
-
-### 总结
-该策略确保了用户体验（首选流式）和交付可靠性（超时/发文件走 Agent）的平衡。