IntentKit WeChat 集成全解析基于 iLink Bot API 的 Go 渠道适配器实战指南【免费下载链接】intentkitIntentKit is an open-source, self-hosted cloud agent cluster that manages a collaborative team of AI agents for you.项目地址: https://gitcode.com/GitHub_Trending/int/intentkitIntentKit 是一个开源、可自托管的云端 Agent 集群负责管理一组协同工作的 AI Agent。在它的渠道适配层中WeChat微信通道是一个完全独立的 Go 服务它通过微信官方的 iLink Bot APIilinkai.weixin.qq.com把企业微信机器人与 IntentKit 的团队频道team channel连接起来专门服务于线索 Agentlead agent场景。本文以仓库中的 integrations/wechat/AGENTS.md 为骨架结合integrations/wechat目录下的 Go 源码完整讲解该通道的定位、配置项、长轮询消息流、媒体加解密链路与会话窗口管理机制。读完本文你将掌握如何在 IntentKit 中理解并运维微信机器人通道以及 iLink 私有协议的关键实现细节。一、WeChat 集成在 IntentKit 中的定位WeChat 集成是 IntentKit 三个渠道适配器之一Telegram、WeChat 之外还有 SSH 等本地通道。与 Telegram 同时支持单 Agent 团队频道不同WeChat 通道只支持团队频道team channels不支持单 Agent这是 integrations/wechat/AGENTS.md 中明确划定的 Scope只服务Lead agentteam channels即团队级线索 Agent轮询数据库中channel_typewechat AND enabledtrue的team_channels记录收到的入站消息被路由到 Core API 的/core/lead/execute源码中实际实现为/core/lead/stream的 SSE 流式接口见下文。整个 Integrations 层的共同约定记录在 integrations/AGENTS.mdGo 1.26、resty v3 作为唯一 HTTP 客户端、GORM PostgreSQL与 Python 端共享同一数据库且按约定不加外键约束、log/slog结构化日志、环境变量 .env配置。二、通道目录结构与依赖每个渠道目录都遵循统一的布局api/Core API 客户端、bot/manager handler sender、config/环境变量、store/GORM 模型外加渠道专属子包。WeChat 通道完整结构如下integrations/wechat/ ├── api/client.go # Core API 客户端健康检查、StreamTeamLead、SetPushChannel ├── bot/ │ ├── manager.go # 机器人生命周期管理 长轮询循环 入站消息处理 │ ├── sender.go # 实现 shared.MessageSender负责各类出站消息 │ └── session_timer.go# 微信客服会话窗口的到期提醒定时器 ├── config/config.go # 环境变量加载与校验 ├── ilink/ │ ├── client.go # iLink Bot API 客户端resty 实现 │ ├── media.go # 入站媒体的下载、AES 解密与校验 │ └── types.go # iLink 协议 DTO 与常量 └── store/models.go # team_channels / team_channel_data 的 GORM 模型入口文件位于 integrations/cmd/wechat/main.go它按固定顺序完成设置 slogJSON handlerDEBUGtrue时降为 Debug 级→ 加载.env→ 解析配置 → 初始化 Redis → 包装告警 handler → 连接 PostgreSQL → 创建 Core API 客户端 → 初始化 S3 存储 → 启动 Manager最后安装 SIGINT/SIGTERM 信号处理实现优雅退出。第三方依赖上iLink Bot API 是微信官方的私有长轮询 HTTP 接口其客户端在 integrations/wechat/ilink/client.go 中用 resty 实现没有任何官方 SDK 可依赖。三、配置与环境变量3.1 通道专属变量WeChat 通道专属的环境变量在 integrations/wechat/config/config.go 中定义# 秒两次新/变更 wechat 频道数据库同步之间的间隔 WX_NEW_CHANNEL_POLL_INTERVAL10这是 integrations/wechat/AGENTS.md 中唯一列出的通道专属变量默认值10秒Manager 用它驱动time.Ticker定期扫描数据库。3.2 会话窗口变量integrations/wechat/config/config.go 中还定义了两个与微信客服窗口相关的变量AGENTS.md 未展开但源码实现清晰# iLink 只允许在用户最后一次入站消息的客服窗口内主动推送机器人消息 WX_SESSION_WINDOW24h WX_SESSION_WARN_BEFORE30m它们在Load()中被time.ParseDuration解析为time.Duration并有严格校验WX_SESSION_WARN_BEFORE必须 0且 WX_SESSION_WINDOW否则启动直接报错退出。这背后的业务原因见第七节iLink 只接受在客服窗口内的主动推送。3.3 通用环境变量来自 integrations/AGENTS.mdWeChat 通道同样需要# 数据库与 IntentKit Python 端共享 DB_HOST... DB_PORT5432 DB_NAME... DB_USERNAME... DB_PASSWORD... # IntentKit Core API INTERNAL_BASE_URLhttp://intent-api # 可观测性 / 运行时 ENVlocal RELEASEv0.17.x DEBUGfalse # Redis告警处理共享限流用可选 REDIS_HOST... REDIS_PORT6379 REDIS_PASSWORD... REDIS_DB0DSN 由DatabaseDSN()方法组装sslmodedisable TimeZoneUTC用户名/密码为空时自动省略。Core API 客户端超时设为 10 分钟api/client.go以容纳 SSE 长流。四、整体架构模式Manager 长轮询 Sender每个渠道都使用相同的骨架WeChat 通道的具体实现在 integrations/wechat/bot/manager.goManager在WX_NEW_CHANNEL_POLL_INTERVAL间隔的time.Ticker上查询数据库里所有enabledtrue的 wechat 频道对每个新增/变更的条目启动一个长轮询 goroutine对每个被移除的条目取消其 context。轮询/处理循环pollLoop从平台收取入站消息转发给 Core API 的/core/lead/stream并把回复以 SSE 流式方式回传。Sender实现shared.MessageSender接口var _ shared.MessageSender (*WechatSender)(nil)编译期断言共享的 dispatcher 把 Core API 输出的 text/image/video/file/card/choice 归一化为各渠道的发送调用。4.1 机器人生命周期管理syncBotssyncBots()每次 tick 执行查询team_channels中channel_typewechat AND enabledtrue的记录对每条记录调用ensureTeamBotRunning()从team_channels.configJSONB读取bot_token、baseurl、ilink_bot_id三个凭据字段缺一不可缺少则 Warn 并跳过以team:teamID为 map key 维护bots/cancelFuncs/tokenHashes。若 token 发生变化会先取消旧 bot 再重建——实现热重启对不再 active 的团队调用cancel()并清理 session timer。值得注意的是二维码登录由 Python APIapp/local/wechat.py负责本 Go 服务不参与登录。Go 服务只读取team_channels.config中已存储的凭据Credentials{BotToken, BaseURL, ILinkBotID, UserID}见 integrations/wechat/ilink/types.go。4.2 长轮询循环pollLooppollLoop是每个团队独立的 goroutine核心逻辑msgs, err : entry.client.GetUpdates(ctx)出错时记录 Warn 级别日志故意不用 Error 级别避免单团队故障刷屏告警并进入指数退避从 2 秒起步翻倍增长上限 4 分钟退避期间用select { case -ctx.Done(): return; case -time.After(backoff): }等待保证 context 取消时能立即退出连续失败计数与outage.Tracker联动只有聚合的GetUpdates 大面积故障才以 Error 级别上报告警通道emitOutageAlertIfDue()恢复时也会记录outage recovered成功即重置退避然后逐条调用handleTeamMessage()。4.3 入站消息处理handleTeamMessagehandleTeamMessage处理一个WeixinMessage的完整流程遍历msg.ItemList按item.Type分派文本、图片、语音、视频、文件五种类型ItemTypeText1/Image2/Voice3/File4/Video5见 ilink/types.go对纯媒体消息无文字用summarizeAttachments生成占位文本如 User sent an image, a voice message.持久化context_token每次入站消息都携带新的context_token存入team_channel_data.data-context_token供后续主动推送使用。botEntry内部用sync.RWMutex保护可变字段并用updateContextTokenIfChanged缓存去重避免无意义的 DB 写拦截/default命令把当前会话设为团队的默认推送频道调用 Core API 的/core/lead/set-push-channel并回复 This chat is now the default push channel.懒加载typing_ticket首次收到消息时才调用getconfig获取因为该接口需要真实的user_idcontext_token然后以 10 秒为周期发送 typing 指示器直到 Agent 回复完成组装 payload 调用apiClient.StreamTeamLead()通过 SSE 把 Core 流式输出的每个ChatMessage交给shared.DispatchMessage与WechatSender发送给用户。五、iLink 协议关键细节5.1 context_token 必须原样回传这是 AGENTS.md 中反复强调的硬性规则入站消息中的context_token必须在发送给同一用户的任何回复中原样回传。在 client.go 的SendMessage中ContextToken直接透传WechatSender则在构造时保存该 token所有发送方法复用。若回传错误iLink 会以非零ret拒绝发送窗口已过期时常见ret-2。5.2 X-WECHAT-UIN 头X-WECHAT-UIN是一个随机的uint32编码为 base64 后的值每次请求重新生成。源码generateWechatUIN()func generateWechatUIN() string { n : rand.Uint32() return base64.StdEncoding.EncodeToString([]byte(strconv.FormatUint(uint64(n), 10))) }每个doPost都会设置该头用于会话隔离/防重放。5.3 长轮询游标GetUpdates携带GetUpdatesBuf游标来自上次响应与LongpollingTimeout: 30秒响应后把新的GetUpdatesBuf缓存到Client.updatesBuf实现增量拉取。getupdates的响应默认不打 Info 日志过于嘈杂仅在ret ! 0时记录 Warn。5.4 鉴权NewClient(baseURL, botToken, botID)创建两个独立的 resty 客户端apiClient40 秒超时固定头Content-Type: application/json、AuthorizationType: ilink_bot_token、Authorization: Bearer botTokencdnClient用于 CDN 上传见第六节。六、媒体链路加密、解密与 CDN 上传这是 WeChat 通道最复杂的部分涉及两条方向相反的链路。6.1 入站媒体下载 → AES-128-ECB 解密 → S3微信 iLink 的媒体经 CDN 下发时是AES-128-ECB PKCS7 加密的密文密钥随消息附带。入站处理在 integrations/wechat/ilink/media.goMediaDownloadURL()把encrypted_query_param包装进 CDN 下载 URLiLink 返回的原始值需要用该 key 名包裹与上传约定一致resolveMediaKey()处理密钥优先级顶层 item 的aeskeyhex 字符串优先于media.aes_key且必须是 32 位 hex16 字节downloadAndDecryptMedia()先下载原始字节http.DetectContentType嗅探 MIME对图片走imagePolicyaccept: image/*allowRawFastPath: true——若原始字节 MIME 已满足条件可直接跳过解密快速路径对语音/视频/文件走permissive策略——SILK/AMR/任意二进制无法可靠嗅探必须靠 AES PKCS7 解密成功本身作为完整性信号禁止快速路径防止协议缺陷把密文当明文转发aesECBDecrypt逐块解密并剥离 PKCS7 paddingdecodeAESKey兼容三种密钥编码base64(hex 字符串)、base64(原始 16 字节)、裸 hex 字符串解密成功后由finalizeInboundMedia解析扩展名文件名扩展名优先于嗅探 MIME见extensionFromFilename按wechat/teamID/kind/unixms_xid.ext的 key 上传到 S3uploadMedia产出types.ChatMessageAttach转发给 LLM。四种入站媒体的差异化处理类型附件类型特殊处理图片AttachImage严格image/*校验拒绝无扩展名映射的怪异子类型如 HEIC为下游 Gemini vision 兜底语音AttachAudio成功转码/AttachFile兜底微信发送 SILK-v3任何 LLM 都不接受用transcodeSilkToMP3转码为 MP3转码失败则原样上传 SILK 供诊断视频AttachVideo默认mp4文件AttachFile优先用户文件名扩展名6.2 出站媒体下载 → 加密 → CDN 上传 → sendmessage出站方向Agent 回复图片/视频/文件在 client.go 的UploadMedia中完成四步生成随机的 16 字节 AES key 与filekeycrypto/rand并计算原文 MD5调用/ilink/bot/getuploadurl申请上传参数携带FileKey / MediaType / RawSize / RawFileMD5 / FileSize / AESKey密文大小按 PKCS7 规则计算(rawSize/16 1) * 16用 AES-128-ECB PKCS7 加密原始数据把密文 POST 到 CDNnovac2c.cdn.weixin.qq.com/c2c/upload从响应头X-Encrypted-Param或响应体encrypt_query_param取回下载参数组装CDNMedia{EncryptQueryParam, AESKey: base64(hex), EncryptType: 1}最后通过sendmessage发送。CDN 上传使用独立的 resty 客户端并开启SetAllowNonIdempotentRetry(true)——这是 AGENTS.md 特意记录的设计决策POST 本身不具备幂等性但每次调用的filekey都是随机生成的所以即使重放也安全。该客户端配置了SetRetryCount(2)共 3 次尝试、SetRetryWaitTime(500ms)、SetRetryMaxWaitTime(3s)指数退避并通过AddRetryHooks记录重试日志。图片/视频/文件的上传媒体类型分别使用UploadMediaImage1/Video2/Voice3/File4与ItemType是两套常量见 ilink/types.go。WechatSendersender.go实现统一兜底策略任何媒体上传或发送失败都会回退为纯文本发送 URL保证用户至少能看到内容链接卡片SendCard与选项SendChoice则拼装为格式化文本发送。这正是shared/dispatcher.go把 Core API 输出归一化的体现。七、客服会话窗口与到期提醒微信 iLink 只允许在用户最后一次入站消息后的客服窗口内主动推送机器人消息因此 integrations/wechat/bot/session_timer.go 实现了完整的窗口管理状态记录每个团队保存last_user_message_atunix 毫秒与warned_for已发送提醒的窗口标识。优先存 Rediswechat:session:last:team带TTL window 1hRedis 不可用时回退到team_channel_data.data-wechat_sessionJSONB 字段MergeTeamChannelDataField用INSERT ... ON CONFLICT DO UPDATE原子合并见 store/models.go计时只有默认推送频道的用户发消息才刷新窗口OnQualifyingUserMessage在window - warnBefore后触发预到期提醒其他用户聊天不刷新定时器启动恢复Restore()在启动时读取持久化状态若窗口仍开启且未提醒过则恢复定时器已过触发点但窗口未关闭则立即触发窗口已关闭则跳过去重与竞态触发时通过 RedisSETNXDB 回退为带条件的UPDATE原子操作获取已提醒锁并用last_user_message_at匹配校验防止陈旧定时器在新窗口误发或重复发送提醒内容sendExpiringNotice实时解析当前默认聊天 ID 与持久化的context_token重启后无需内存预热即可发送然后以system_trigger: wechat_session_expiring调用/core/lead/stream让线索 Agent 生成窗口即将关闭 状态摘要的提醒在窗口内送达用户。八、运行与部署8.1 直接运行go run ./integrations/cmd/wechat启动时依次完成 DB 连接、S3 初始化、Redis 连接然后打印WeChat Integration Started并进入 ticker 循环。进程收到 SIGINT/SIGTERM 后调用manager.Stop()关闭stopCh、停止所有 session timer、取消每个团队的 context实现优雅退出。8.2 Docker 构建docker build -f integrations/Dockerfile.wechat -t intent-wechat integrations/integrations/Dockerfile.wechat与integrations/Dockerfile.telegram独立构建两者共享同一个 integrations/go.mod 模块。九、关键设计经验总结综合 AGENTS.md 与源码可以提炼出该通道最有价值的几条工程经验凭据与运行分离登录二维码与运行解耦Go 服务只消费team_channels.config中的静态凭据简化了权限面私有协议客户端化面对无官方 SDK 的私有长轮询 API用 resty 收敛所有 HTTP 细节鉴权头、UIN 头、游标、超时并统一 JSON 错误处理ret/errmsg非零即报错非幂等重放的安全化通过每次随机 filekey这一业务事实让 CDN 上传的重试变得安全这是 restySetAllowNonIdempotentRetry的正当使用场景日志分级即告警策略单团队失败只记 Warn只有聚合的 GetUpdates 故障才走 Error 告警避免故障放大效应窗口状态双写容灾Redis 与 DB JSONB 互为回退SETNX/条件 UPDATE 保证提醒幂等重启后Restore无缝续跑统一消息归一化WechatSender实现shared.MessageSender让 Core API 的产出与渠道无关媒体失败自动降级为文本链接。如需进一步深入可继续阅读 integrations/wechat/ilink/client.go协议客户端、integrations/wechat/bot/manager.go生命周期与消息处理、integrations/wechat/bot/session_timer.go窗口管理以及共享层 integrations/shared/dispatcher.go 与 integrations/AGENTS.md。【免费下载链接】intentkitIntentKit is an open-source, self-hosted cloud agent cluster that manages a collaborative team of AI agents for you.项目地址: https://gitcode.com/GitHub_Trending/int/intentkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考