企业微信 AI Bot 通道扩展实战加密回调校验、流式轮询与统一消息管线接入【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi导读ext-wecom-bot是 AionUI 仓库中一个完整的企业微信 AI Bot 通道扩展示例它演示了如何把企业微信WeCom的 Bot 模式回调接入 AionUI 的统一通道消息管线覆盖GET回调验签、加密POST载荷解密、msgtypestream流式轮询响应、response_url一次性兜底回推以及dist-first 扩展入口 源码包装器的扩展开发形态。读完本文你将掌握企业微信 Bot 回调的完整接入流程含 SHA1 签名与 AES-256-CBC 加解密的实现细节、AionUI 通道扩展的清单声明方式以及如何用just dev-ext一键启动示例扩展进行本地联调。一、示例定位一个用于通道能力验证的生态扩展ext-wecom-bot位于仓库的 examples/ext-wecom-bot 目录其README.md开宗明义它是面向 AionUI 的企业微信 AI Bot 通道扩展示例核心目标是验证扩展通道能力。与之同级的 examples/ext-feishu 是飞书通道适配器示例二者共同构成仓库对IM 通道扩展这一能力的参考实现集合。该示例刻意保持轻框架入口代码使用CommonJS编写不依赖任何第三方运行时框架以便与当前扩展加载器保持兼容。这意味着示例本身可以直接作为你自研企业微信通道扩展的骨架——把channels/ext-wecom-bot-channel.js、channels/state.js、webui/webhook.js三个文件拷贝后替换业务逻辑即可。示例的通道注册声明位于 aion-extension.json其中contributes.channelPlugins声明了一个名为企业微信 AI Bot (Example)的通道插件其type为ext-wecom-bot入口指向channels/ext-wecom-bot-channel.js。值得注意的是描述字段中明确提醒仅开启 WebUI 远程访问LAN通常不足以通过企微回调校验生产环境需要公网 HTTPS 地址。二、快速运行从启动应用到启用通道原文档给出的运行步骤基于 Windows PowerShell 的just命令如下以扩展模式启动应用just dev-ext该命令定义在仓库根目录的 justfile 中实际执行node scripts/dev-bootstrap.mjs launch start --extensions。从 scripts/dev-bootstrap.mjs 可以看到--extensions标志会把examples目录解析为AIONUI_EXTENSIONS_PATH注入启动环境从而在开发模式下自动加载全部示例扩展。同文件还提供webui-ext仅启动 WebUI与cli-ext启动 CLI两种形态以及dev-ext-doctor用于跨平台诊断扩展启动问题。打开设置 - 通道Channels找到企业微信 AI Bot (Example)。填写两项凭证token企业微信 AI Bot 回调 TokenencodingAesKey43 位 EncodingAESKey。启用该通道。可选填写Public Base URL即你的公网 HTTPS 来源例如https://bot.example.com。关于第 3 步的凭证约束channels/ext-wecom-bot-channel.js 中的validateConfig()做了强制校验token必填encodingAesKey必须是字符串且长度严格等于 43 字符否则启动时直接抛出ext-wecom-bot: encodingAesKey must be 43 characters。这也是企业微信官方约定43 字符 Base64 编码的 AESKey示例在启动阶段就拦截了错误配置避免运行期才暴露问题。三、Webhook 地址与部署前提启用通道后企业微信回调需要指向示例注册的 Webhook 端点。原文档给出的地址为http://your-host:webui-port/ext-wecom-bot/webhook桌面端本地默认值http://127.0.0.1:25808/ext-wecom-bot/webhook该路径来自 aion-extension.json 中contributes.webui.apiRoutes的声明路径/ext-wecom-bot/webhook映射到webui/webhook.js且auth设为false——即该端点不要求登录鉴权因为它需要被企业微信服务器直接回调。网络可达性约束务必注意原文档 Notes 部分强调了两点部署事实LAN 远程访问适合本地测试但企业微信回调通常要求公网可达的 HTTPS URL本示例是生态扩展示例用于通道能力验证。这与 aion-extension.json 中通道描述的警告一致仅开启 WebUI 远程访问LAN不足以通过企微回调校验。因此本地联调可以先通过内网穿透等手段暴露 HTTPS 地址生产则必须部署到公网。四、回调处理核心GET 验签与 POST 解密webui/webhook.js是请求的入口处理器它先做统一的前置校验再按 HTTP 方法分流从 query 中提取msg_signature、timestamp、nonce三者缺失则返回400 missing query signature params通过getActivePlugin()拿到当前激活的通道插件若未激活返回503对应企业微信回调重试场景请求进入前先执行cleanupExpiredRecords()清理过期状态详见下文状态管理。GETURL 验证echostr 回显企业微信 Bot 模式创建回调时会用带echostr的 GET 请求校验服务器校验msg_signature不匹配返回403 signature mismatch通过后调用plugin.decrypt(echostr)解密并把解密出的明文以text/plain原样返回对应代码res.type(text/plain).send(verified)。POST加密消息载荷POST 请求体为{encrypt: ...}形式的加密 JSON缺少encrypt字段返回400 invalid body: missing encrypt校验msg_signature失败返回403解密后JSON.parse得到明文消息解析失败返回400 decrypt body failed。签名与加解密算法实现签名与加解密都实现在 channels/ext-wecom-bot-channel.jsSHA1 签名L10-L13把token、timestamp、nonce、encrypted四个字符串排序后拼接再做 SHA1 摘要与msg_signature比对。AES-256-CBC 解密L30-L40encodingAesKey追加补齐为 44 字符 Base64 得到 32 字节密钥IV 取密钥前 16 字节解密后手动去掉 PKCS7 填充decodePkcs7校验 padding 范围为 1~32明文结构为16 字节随机串 4 字节网络序内容长度 明文 填充因此取subarray(16)跳过随机串再按前 4 字节长度切出真正的消息体。AES-256-CBC 加密L42-L53用于构造加密响应采用crypto.randomBytes(16)生成随机前缀写入4 字节大端长度补齐 32 字节块encodePkcs7后加密。这些细节完全对齐企业微信官方签名 AES 加密规范是回调校验能通过的核心保证。五、流式轮询msgtypestream的响应模型这是示例最有特色的部分。企业微信 AI Bot 的stream消息类型允许服务器立即返回一个 stream id随后客户端反复轮询获取增量内容从而模拟 AI 输出的打字机效果。响应构造buildEncryptedStreamResponse(streamState, timestamp, nonce)构造加密的msgtypestream响应{ msgtype: stream, stream: { id: stream id, finish: false, content: 可见内容, thinking_content: 思考内容 } }其中thinking_content仅在存在思考内容时附带整个 payload 会走encryptPayload加密并按同样的 SHA1 规则生成msgsignature。轮询刷新webhook.js L86-L101当 POST 载荷本身是msgtypestream且携带stream.id时webhook 视为客户端轮询刷新请求命中getStream(streamId)则返回当前流状态增量内容由服务端拼接未命中则视为会话过期创建一个expired状态的流并返回会话已过期的提示。状态机与 TTLstate.jschannels/state.js 用内存 Map 管理流状态并定义了四条生命周期常量常量值含义STREAM_IDLE_MS30 秒已结束的流在空闲 30 秒后被清理STREAM_TTL_MS5 分钟未结束的流最长存活 5 分钟EVENT_TTL_MS5 分钟事件去重窗口RESPONSE_URL_TTL_MS55 分钟response_url有效期企业微信限制每条流记录包含streamId、chatId、visibleContent、thinkingContent、finished、finalizedAt等字段getLatestStreamByChatId按updatedAt取某会话最新的流供sendMessage定位。六、消息桥接统一通道管线与内容归一化入站消息归一化toUnifiedIncomingMessage(payload)把企业微信消息转换成 AionUI 通道的统一结构chatId取chatid单聊回退为dm:useridplatform固定为ext-wecom-bot用户信息从from.userid/from_name推导。extractInboundText则按msgtype分别提取文本、语音、混合消息mixed、图片、文件、位置等类型并映射为[图片]、[文件]、[位置]这类可读文本。入站处理与软收尾handleInboundMessage把归一化消息交给messageHandler由 AionUI 运行时注入并给该会话注册一个 1.2 秒的兜底定时器若 ActionExecutor 没有显式结束消息则软关闭该流finishStream避免客户端永远轮询不到finishtrue。出站流优先、response_url 兜底sendMessage的出站策略非常典型优先通过getLatestStreamByChatId找到当前流把 AI 增量写入visibleContent/thinkingContent根据是否包含 Thinking/思考 关键字区分思考流与可见流客户端轮询即可拿到若流上下文不可用例如消息是异步推回的则回退到consumeResponseUrl(chatId)消费该会话缓存的response_url用postResponseUrlMessage以markdown消息一次性推回response_url是一次性的state.js 中consumeResponseUrl置usedtrue后即失效有效期 55 分钟。事件去重企业微信回调可能重试。webhook 用shouldDropDuplicate(eventId)基于msgid做 5 分钟窗口去重重复事件直接返回success且不触发二次处理避免 AI 被重复触发。七、扩展清单解析dist-first 形态与配置字段虽然示例当前把入口直接指向channels/*.jsCommonJS 源码README 特别强调这是dist-first 扩展入口dist/*配源码包装器用于开发的示范生产扩展通常发布编译产物到dist/同时保留源码入口以便just dev-ext开发期直接热载。aion-extension.json 的字段值得作为模板参考credentialFieldstokenpassword必填、encodingAesKeypassword必填对应设置页的凭证输入configFieldspublicBaseUrltext可选对应可选的公网地址webui.apiRoutes声明/ext-wecom-bot/webhook路由及auth:falsewebui.staticAssets把assets目录挂到/ext-wecom-bot/assets前缀。关于通道扩展的生态位可对照 examples/ext-feishu/aion-extension.json飞书示例展示了i18n.localesDir、多路由/collect与/stats且auth:true和configFields布尔开关enableMetrics默认true说明同一套清单机制可表达不同的通道能力面。八、源码级验证与扩展点小结端到端测试tests/e2e/specs/ext-lifecycle.e2e.ts、tests/e2e/specs/ext-ipc-queries.e2e.ts覆盖了扩展生命周期与 IPC 查询可作为通道扩展联调的参考入口如果你要自研同类通道改造extractInboundText适配你的消息类型替换postResponseUrlMessage的msgtype并按需要调整 state.js 中的 TTL 常量例如更长的思考时间可放宽STREAM_TTL_MS需要公网 HTTPS 才能让企业微信回调真正生效本地联调建议配合内网穿透工具暴露127.0.0.1:25808/ext-wecom-bot/webhook。整体来看ext-wecom-bot用约 400 行代码完整呈现了企业微信 Bot 回调验证 → 加密载荷处理 → 流式轮询响应 → 统一通道管线桥接的全链路是理解 AionUI 扩展通道机制与企微 Bot 接入的极佳最小实现。【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
