@xpert-ai/plugin-wecom

通用企业微信（WeCom）集成插件，提供 API 模式回调 URL、对话调度（handoff）和企业微信 OpenAPI 通知中间件。

能力

• Integration 配置（Token / EncodingAESKey / CorpId / CorpSecret / AgentId）
• 回调 URL 暴露：/api/wecom/webhook/:integrationId
• GET URL 校验：校验签名并解密 echostr
• 支持空 Query 的连通性探测（返回 success）
• POST 回调接收：校验签名并解密 encrypt，解析入站消息并触发 Xpert 对话调度
• 回调配置查询：/api/wecom/callback-config?integration=<id>
• 工作流触发器：WeCom Trigger（可将 Integration 绑定到指定 Xpert）
• 智能体中间件：WeComNotifyMiddleware（6 个工具）
• Chat Channel：wecom（用于 webhook 入站消息的统一处理）

使用步骤

1. 在 Xpert 创建企业微信 Integration（provider=wecom）并保存。
2. 在企业微信后台（API 模式）填写 URL：
   • https://<your-api-domain>/api/wecom/webhook/<integrationId>
3. Token 与 EncodingAESKey 填写为 Integration 中对应配置。
4. 你可以任选一种路由方式：
   • 在 Integration 上配置 xpertId（旧模式，直接路由）
   • 在工作流中使用 WeCom Trigger 绑定 integrationId -> xpertId（推荐，和飞书/钉钉一致）
5. 如果要使用通知中间件调用企业微信 OpenAPI，请补全 corpId、corpSecret、agentId。
6. 企业微信发起 URL 校验时，插件会自动验签并返回解密后的明文。

中间件配置（WeComNotifyMiddleware）

• integrationId：必填，读取企业微信集成配置
• recipient_type：可选，默认收件人类型（chat_id / user_id / party_id / tag_id / to_all）
• recipient_id：可选，默认收件人 ID（支持模板变量，如 {{chatId}}）
• template.enabled / template.strict：可选，模板渲染开关与严格模式
• defaults.timeoutMs：可选，请求超时

工具列表：

• wecom_send_text_notification
  • 优先走 AIBot response_url 回复（当前会话）
  • 无 response_url 时回退 message/send（OpenAPI）
• wecom_send_rich_notification
  • 优先走 AIBot response_url（markdown / template_card）
  • 其余情况回退 message/send（OpenAPI）
• wecom_update_message
  • 优先走 AIBot response_url 更新模板卡片
  • 无法走 AIBot 时回退 message/update_template_card（OpenAPI，需 response_code）
• wecom_recall_message
  • 调用 message/recall（OpenAPI）
• wecom_list_users
  • 调用 user/get 或 user/simplelist / user/list（OpenAPI）
• wecom_list_chats
  • 调用 wedoc/smartsheet/groupchat/list（OpenAPI），可选再调用 appchat/get 拉详情

说明：

• 前 3 个工具属于混合路由（AIBot 优先 + OpenAPI 回退）；后 3 个工具是 OpenAPI-only
• wecom_list_chats 为 docid 作用域查询，需要传 docId 或在 integration 配置 smartsheetDocId
• wecom_update_message 依赖 response_code，遵循企业微信时效与调用次数限制

本地构建

cd xpertai/integrations/wecom
node ../../node_modules/typescript/bin/tsc -p tsconfig.lib.json

生命周期验证（plugin-dev-harness）

cd xpertai/integrations/wecom
node ../../node_modules/typescript/bin/tsc -p tsconfig.lib.json
cd ../../..
node plugin-dev-harness/dist/index.js --workspace ./xpertai --plugin @hxr222223323232323/plugin-wecom-xr --verbose