微信渠道实现¶

📎 引用文件

本文引用的文件 - weixin.py - wecom.py - base.py - config.py - schema.py - env_schema.py - utils.py

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能与限制
故障排查指南
结论
附录：配置与环境变量

简介¶

本章节面向 Vibe-Trading 的“微信渠道”集成，覆盖两类微信生态接入方式： - 个人微信（WeChat）：通过 HTTP 长轮询接口与 ilinkai.weixin.qq.com 通信，使用二维码登录获取 bot token，支持文本、图片、语音、视频、文件等消息收发。 - 企业微信（WeCom）：基于 WebSocket 长连接（wecom_aibot_sdk），无需公网 Webhook，支持文本、图片、语音、文件、混合内容等消息收发。

文档将说明应用配置、消息回调/事件处理、认证机制、平台限制与安全验证、身份识别与会话管理、消息路由、错误处理策略、媒体加密解密、部署步骤以及常见问题解决方案。

项目结构¶

微信相关代码集中在 channels 子模块中，遵循统一的通道抽象基类，便于扩展与维护。

graph TB subgraph "通道层" WX["个人微信 WeixinChannel"] WC["企业微信 WecomChannel"] BASE["BaseChannel 抽象基类"] end subgraph "配置与工具" CFG["channels.config.load_channels_config"] SCHEMA["AgentConfig / ChannelsConfig"] ENV["EnvConfig 环境变量模型"] UTILS["utils.get_media_dir / split_message"] end WX --> BASE WC --> BASE WX --> UTILS WC --> UTILS CFG --> SCHEMA ENV --> CFG

图表来源 - weixin.py:121-169 - wecom.py:54-100 - base.py:22-82 - config.py:11-21 - schema.py:429-456 - env_schema.py:545-577 - utils.py:16-32

章节来源 - weixin.py:121-169 - wecom.py:54-100 - base.py:22-82 - config.py:11-21 - schema.py:429-456 - env_schema.py:545-577 - utils.py:16-32

核心组件¶

个人微信通道 WeixinChannel
使用 HTTP 长轮询从 ilinkai.weixin.qq.com 拉取消息，二维码登录获取并持久化 bot token。
支持多类型消息解析与下载（文本、图片、语音、视频、文件），内置 AES 解密与分片发送。
维护 context_token、typing_ticket、会话暂停与退避重试等状态。
企业微信通道 WecomChannel
使用 wecom_aibot_sdk 建立 WebSocket 长连接，接收事件并转发到消息总线。
支持图片/语音/文件下载与上传（分块 base64 上传协议），流式回复与欢迎消息。
通道基类 BaseChannel
统一抽象 start/stop/send、权限校验 allow_from、配对码流程、消息入队发布。
配置加载与结构化
load_channels_config 读取 agent.json 中的 channels 配置；ChannelsConfig 定义全局通道开关与重试策略。
EnvConfig 集中管理环境变量，提供默认值与类型校验。

章节来源 - weixin.py:121-169 - wecom.py:54-100 - base.py:22-82 - config.py:11-21 - schema.py:429-456 - env_schema.py:545-577

架构总览¶

下图展示微信渠道在 Vibe-Trading 中的整体交互：客户端消息经通道适配器进入消息总线，再由上层 Agent 处理并回写至对应微信渠道。

sequenceDiagram participant User as "微信用户" participant WX as "个人微信通道<br/>WeixinChannel" participant WC as "企业微信通道<br/>WecomChannel" participant Bus as "消息总线 MessageBus" participant Agent as "Agent 处理层" Note over User,WX : 个人微信：HTTP 长轮询拉取 User->>WX : 发送消息 WX->>Bus : publish_inbound(InboundMessage) Bus-->>Agent : 分发到会话/工具链 Agent-->>Bus : OutboundMessage Bus-->>WX : send(OutboundMessage) WX-->>User : 文本/媒体回复 Note over User,WC : 企业微信：WebSocket 事件驱动 User->>WC : 发送消息 WC->>Bus : publish_inbound(InboundMessage) Bus-->>Agent : 分发到会话/工具链 Agent-->>Bus : OutboundMessage Bus-->>WC : send(OutboundMessage) WC-->>User : 文本/媒体回复

图表来源 - weixin.py:538-593 - wecom.py:102-148 - base.py:179-227

详细组件分析¶

个人微信（WeixinChannel）¶

认证与登录
二维码登录流程：获取二维码、轮询扫码状态、成功后保存 bot token、base_url 等状态。
状态持久化：account.json 保存 token、get_updates_buf、context_tokens、typing_tickets、base_url。
消息接收
长轮询 getupdates，按服务器建议调整超时；去重处理 message_id；上下文 token 缓存与刷新。
解析 item_list，支持文本、图片、语音、视频、文件；引用消息合并；语音优先使用转写文本，否则尝试本地转录。
媒体下载与解密
根据 media 字段选择 full_url 或 encrypt_query_param 下载；AES-128-ECB 解密；失败时回退策略。
消息发送
文本分片发送（最大长度限制）；媒体先上传 CDN（AES 加密 + 分块），再发送媒体消息；打字指示器保活。
工具提示缓冲合并，避免触发 iLink 频率限制。
会话与限流
会话过期自动暂停一段时间；context_token 过期前主动刷新；typing_ticket 定期续期。

flowchart TD Start(["收到 getupdates"]) --> CheckErr{"ret/errcode 是否错误?"} CheckErr --> |是| HandleErr["会话过期则暂停; 其他错误抛出异常"] CheckErr --> |否| UpdateBuf["更新 get_updates_buf"] UpdateBuf --> ForEachMsg["遍历 msgs"] ForEachMsg --> ParseItem["解析 item_list<br/>文本/图片/语音/视频/文件"] ParseItem --> MediaCheck{"是否有可下载媒体?"} MediaCheck --> |是| DownloadMedia["下载并解密媒体"] MediaCheck --> |否| BuildContent["组装文本内容"] DownloadMedia --> BuildContent BuildContent --> Publish["调用 _handle_message 入队"] Publish --> End(["结束"])

图表来源 - weixin.py:538-593 - weixin.py:598-831 - weixin.py:837-928

章节来源 - weixin.py:327-415 - weixin.py:443-515 - weixin.py:538-593 - weixin.py:598-831 - weixin.py:837-928 - weixin.py:1088-1222 - weixin.py:1287-1474 - weixin.py:1477-1587

企业微信（WecomChannel）¶

认证与连接
使用 WSClient 建立 WebSocket 长连接，自动重连与心跳；需要 bot_id 与 secret。
事件处理
注册多种消息事件处理器（text/image/voice/file/mixed），统一进入 _process_message。
进入聊天事件 enter_chat 支持欢迎消息。
媒体处理
下载：通过 SDK 提供的 download_file 获取并保存；大小限制与文件名安全处理。
上传：三步协议（init → chunk × N → finish），分块 base64 传输，返回 media_id。
消息发送
有 frame 时使用 reply_stream 进行流式回复；无 frame 时主动发送 markdown。
媒体文件先上传，再发送对应 msgtype。

sequenceDiagram participant WeCom as "企业微信平台" participant WC as "WecomChannel" participant Bus as "消息总线" participant Agent as "Agent 处理层" WeCom->>WC : WebSocket 事件(文本/图片/语音/文件/混合) WC->>WC : _process_message(去重/权限/组装内容) WC->>Bus : publish_inbound(InboundMessage) Bus-->>Agent : 分发 Agent-->>Bus : OutboundMessage Bus-->>WC : send(OutboundMessage) alt 有媒体 WC->>WeCom : 上传媒体(init/chunk/finish) WeCom-->>WC : media_id WC->>WeCom : 发送媒体(msgtype + media_id) else 纯文本 WC->>WeCom : reply_stream/markdown end

图表来源 - wecom.py:102-148 - wecom.py:173-191 - wecom.py:217-355 - wecom.py:356-490 - wecom.py:492-555

章节来源 - wecom.py:54-100 - wecom.py:102-148 - wecom.py:173-191 - wecom.py:217-355 - wecom.py:356-490 - wecom.py:492-555

通道基类与通用能力¶

权限控制：allow_from 白名单、配对码流程、跨通道 operator 授权。
消息入队：统一封装 InboundMessage，支持媒体路径与元数据。
流式能力：send_delta、send_reasoning_delta/end、send_file_edit_events 等钩子。

章节来源 - base.py:22-82 - base.py:152-227

依赖关系分析¶

通道对基础库的依赖
个人微信：httpx、pydantic、可选 qrcode、可选 pycryptodome/cryptography（用于 AES）。
企业微信：wecom_aibot_sdk（WSClient、generate_req_id、download_file）。
配置依赖
channels.config.load_channels_config 读取 agent.json 的 channels 部分。
schema.ChannelsConfig 定义全局通道开关、重试次数、回复超时、operators。
env_schema.EnvConfig 提供环境变量默认值与类型校验。
工具依赖
utils.get_media_dir 为各通道媒体文件提供统一存储根目录。
utils.split_message 用于文本分片发送。

graph LR WX["WeixinChannel"] --> httpx["httpx"] WX --> pydantic["pydantic"] WX --> crypto["pycryptodome/cryptography (可选)"] WC["WecomChannel"] --> sdk["wecom_aibot_sdk"] WX --> utils["utils.get_media_dir/split_message"] WC --> utils CFG["channels.config"] --> schema["schema.ChannelsConfig"] ENV["env_schema.EnvConfig"] --> CFG

图表来源 - weixin.py:27-37 - wecom.py:1-21 - config.py:11-21 - schema.py:429-456 - env_schema.py:545-577 - utils.py:16-32

章节来源 - weixin.py:27-37 - wecom.py:1-21 - config.py:11-21 - schema.py:429-456 - env_schema.py:545-577 - utils.py:16-32

性能与限制¶

个人微信
消息长度限制：单条文本最大约 4000 字符，超出会分片发送。
iLink 频率限制：工具提示消息会被缓冲合并，避免频繁触发限流（约每 5 分钟 7 条）。
会话过期：errcode 为特定值时会暂停会话一段时间，避免无效请求。
context_token 有效期较短，发送前会主动刷新以防丢失。
企业微信
媒体上传大小限制：入站媒体限制 200MB；出站上传分块（每块 512KB raw，base64 编码）。
流式回复：使用 reply_stream 提升用户体验；无 frame 时仅支持 markdown 主动推送。
通用
URL 安全校验：媒体下载目标需通过 validate_url_target，禁止私有/组播地址。
文件路径安全：文件名清理与路径检查，防止越权访问。

章节来源 - weixin.py:55-57 - weixin.py:1031-1064 - weixin.py:538-593 - weixin.py:972-1029 - wecom.py:23-27 - wecom.py:356-490 - utils.py:97-180

故障排查指南¶

个人微信
二维码登录失败：检查网络、二维码是否过期；日志会提示刷新次数上限。
会话过期：出现 errcode 特定值时会自动暂停会话；等待恢复后继续轮询。
媒体下载失败：优先尝试 full_url，失败回退 encrypt_query_param；若仍失败记录日志。
发送失败：media 上传失败会降级为文本提示；网络/服务端错误会抛出以便重试。
企业微信
SDK 未安装：启动时打印安装提示；缺少 bot_id/secret 会直接报错。
媒体下载失败：检查 aeskey 与 url；记录警告并跳过该媒体。
上传失败：init/chunk/finish 任一阶段失败都会记录错误并返回 None。
流式回复错误：确保使用 reply_stream；普通 reply 不支持 text msgtype。
通用
权限拒绝：allow_from 未包含 sender_id 且非 DM；DM 会下发配对码。
路径/URL 不安全：validate_url_target 拒绝私有/组播地址；文件名清理避免越权。

章节来源 - weixin.py:327-415 - weixin.py:538-593 - weixin.py:837-928 - weixin.py:1155-1222 - wecom.py:102-148 - wecom.py:217-355 - wecom.py:356-490 - wecom.py:492-555 - base.py:165-227 - utils.py:97-180

结论¶

Vibe-Trading 的微信渠道提供了两套成熟方案：个人微信通过 HTTP 长轮询与企业微信通过 WebSocket 长连接，均具备完善的认证、消息解析、媒体处理、会话管理与错误恢复能力。结合统一的通道基类与结构化配置，可在不同场景下灵活启用与扩展。生产环境建议关注频率限制、会话过期、媒体大小与安全性校验，并结合日志与告警快速定位问题。

附录：配置与环境变量¶

个人微信（WeixinChannel）
enabled：是否启用
allow_from：允许的用户/群列表
base_url：iLink 服务地址
cdn_base_url：CDN 地址
route_tag：路由标签
token：手动设置的 bot token（或通过二维码登录获取）
state_dir：状态持久化目录（默认运行时子目录）
poll_timeout：长轮询超时秒数
企业微信（WecomChannel）
enabled：是否启用
bot_id：机器人 ID
secret：机器人密钥
allow_from：允许的用户/群列表
welcome_message：进入聊天时的欢迎消息
全局通道配置（ChannelsConfig）
send_progress：是否发送进度消息
send_tool_hints：是否发送工具提示
send_max_retries：发送最大重试次数
reply_timeout_s：回复超时时间
operators：跨通道操作员白名单
环境变量（EnvConfig）
提供 LLM、数据源、API、Swarm、Agent 调优、路径、OCR、Memory 等分组的环境变量默认值与类型校验。
可通过环境变量覆盖默认值，保证部署一致性。

章节来源 - weixin.py:121-132 - wecom.py:54-62 - schema.py:429-456 - env_schema.py:545-577

← 内置渠道实现钉钉渠道实现 →