JellyfishBot
开发者指南 · 07

WeChat 集成

完整 iLink 协议细节、CDN 加解密、踩坑记录见 docs/dev/wechat-channels.md 和 docs/wechat-integration-guide.md。

7.1 双栈架构

text
┌──────────────────────────────────────────────────────────┐
│  Service 渠道                  │  Admin 自接入            │
├────────────────────────────────┼─────────────────────────┤
│  /api/wc/*                     │  /api/admin/wechat/*    │
│  router.py                     │  admin_router.py         │
│  bridge.py                     │  admin_bridge.py         │
│  Consumer Agent (channel=wechat│  Admin Agent             │
│  对话存于 service conversations│  对话存于 admin convos   │
│  会话存 wechat_sessions.json   │  存 admin_wechat_session.│
│  权限按 service capabilities   │  完整 docs/scripts 权限  │
└────────────────────────────────┴─────────────────────────┘
共享：client.py / media.py / delivery.py / rate_limiter.py

7.2 关键模块

模块职责
client.pyiLink 协议：getconfig / getupdates / sendmessage / getuploadurl / cdn 上传下载
bridge.pyService Bridge：消息路由 + 多模态构建 + send_message 拦截 + 自动审批 HITL
admin_bridge.pyAdmin Bridge：完整权限 + 内联 send_message 处理
session_manager.py会话生命周期 + 持久化 + 重连（指数退避）
media.pyAES-128-ECB 加解密 + CDN 上传下载
delivery.py统一投递（含 <<FILE:>> 标签解析）
rate_limiter.py单用户 10 条/60s + QR 5 次/60s + 全局 session 上限
router.py / admin_router.pyHTTP API 端点

7.3 多媒体投递

方向流程
接收图片CDN GET → AES 解密 → base64 multimodal → Agent Vision
发送图片getuploadurl → AES 加密 → CDN POST → sendmessage(image_item.media)
接收语音CDN GET → AES 解密 → SILK→WAV（pysilk） → Whisper 转文字
发送 TTS/generated/audio/ 下的 MP3 通过 send_file 作为文件附件发送

语音条（voice_item）方案暂停：pysilk 编码的 SILK 在 WeChat 客户端始终静音，24kHz/16kHz 均无效，待进一步调研。

7.4 <<FILE:>> 标签解析

delivery.py::extract_media_tags(text) -> (cleaned_text, [paths])：

python
_MEDIA_TAG_RE = re.compile(r"<<FILE:([^>]+?)>>")
  • 主动从 send_message 的 text 抽取 <<FILE:path>> 标签，转为额外 media 投递
  • 剩余 cleaned_text 作为文本发出
  • 同时支持 media_path 参数和 <<FILE:>> 标签两种用法
  • Bridge 和 Scheduler 共享此模块，避免重复代码

7.5 Session 管理要点

  • 指数退避重连（max 20 次后自动移除）
  • 有 from_user_id 的会话不参与 24h 无活动清理（长期保留）
  • 无 from_user_id 的空会话才按 inactive 清理
  • 空轮询仅对「未建立用户」会话在 50 次后丢弃
  • 多 Admin 隔离：list_sessions / remove_session 按 admin_id 过滤

7.6 Admin 自接入

  • 端点：POST /api/admin/wechat/qrcode / GET qrcode/status / GET/DELETE session / GET messages
  • 会话持久化：users/{user_id}/admin_wechat_session.json，Docker/重启后自动恢复
  • _save_admin_session() 在会话创建、from_user_id 首次捕获、context_token 更新时写入
  • restore_admin_sessions() 在 main.py startup 时调用
  • shutdown_admin_sessions() 仅停止轮询和关闭连接，不删除持久化文件
上一篇←Service & Consumer 双层下一篇定时任务（Scheduler）→