Wechat-Bot/wechat-bot/README.md

Wechat-Bot

企业微信消息分发中转站 —— 企业微信智能机器人与远程 Agent 的桥梁。

企业微信文档：https://developer.work.weixin.qq.com/document/path/101463

架构说明

企业微信用户
    │
    ▼
企业微信服务器 (wss://openws.work.weixin.qq.com)
    │  WebSocket 长连接
    ▼
wecom-aibot-python-sdk (接收/发送消息)
    │  SSE 流式 + HTTP 调用
    ▼
远程 Agent 服务 (AGENT_BASE_URL)

• 企业微信侧：通过 wecom-aibot-python-sdk 建立 WebSocket 长连接，接收用户消息
• Agent 侧：通过 HTTP 调用远程 Agent 的 REST API（兼容 ADK api_server 格式）
• 流式回复：优先使用 /run_sse（SSE 流式）实现打字机效果，失败时降级为 /run（同步）
• 会话管理：自动为每个用户创建 Agent 会话，企业微信 userid 与 Agent user_id 一一对应
• 思考过滤：自动去除模型思考过程（<think...> 标签），只推送正式回复给用户

支持的消息类型

类型	msgtype	说明
文本	text	直接转发给 Agent 处理
图片	image	下载并描述，转发给 Agent
语音	voice	提取文本内容后处理
文件	file	下载并描述，转发给 Agent
视频	video	下载并描述，转发给 Agent
图文混排	mixed	提取文本内容后处理

项目结构

wechat-bot/
├── main.py              # 主入口，启动 WebSocket 客户端
├── config.py            # 全局配置（从 .env 加载）
├── requirements.txt     # Python 依赖
├── Dockerfile           # Docker 镜像构建
├── docker-compose.yml   # Docker Compose 编排
├── .env.example         # 环境变量模板
└── bot/
    ├── __init__.py
    ├── wecom_bot.py     # 组装层：创建 WSClient + 注册事件
    ├── agent_client.py  # Agent 通信：HTTP 客户端、会话管理、SSE/同步调用
    ├── handlers.py      # 消息处理：统一的 handle_message()
    ├── message_parser.py # 消息解析：提取文本内容和元数据
    └── reply_parser.py  # 回复解析：去除思考标签、去重

快速开始

1. 配置环境变量

cp .env.example .env

编辑 .env 文件，填写以下必要配置：

配置项	必填	说明	默认值
WECHAT_BOT_ID	✅	企业微信机器人 ID	-
WECHAT_BOT_SECRET	✅	长连接密钥	-
AGENT_BASE_URL	✅	Agent 服务地址	http://127.0.0.1:8000
AGENT_APP_NAME	❌	Agent 应用名称	root_agent
AGENT_TIMEOUT	❌	Agent 调用超时（秒）	120
LOG_LEVEL	❌	日志级别	INFO

WECHAT_BOT_ID 和 WECHAT_BOT_SECRET 获取方式：企业微信管理后台 → 智能机器人 → API 模式

2. 启动 Agent 服务

确保你的 Agent 服务已启动并监听对应端口。

3. 启动 Bot

Docker 部署（推荐，适用于 NAS）：

docker compose up -d --build
docker compose logs -f

本地运行：

pip install -r requirements.txt
python main.py

Agent API 集成

本项目通过 HTTP 调用远程 Agent，兼容 ADK api_server 接口格式：

接口	方法	用途
/apps/{app_name}/users/{user_id}/sessions	POST	为用户创建会话
/run_sse	POST	SSE 流式对话（主要方式）
/run	POST	同步对话（降级方案）

请求格式

{
  "app_name": "root_agent",
  "user_id": "企业微信用户ID",
  "session_id": "会话ID",
  "new_message": {
    "role": "user",
    "parts": [{"text": "用户消息"}]
  }
}

响应处理

• SSE 流式：逐行解析 data: 事件，收集 content.parts[].text
• 自动过滤 thought: true 的思考内容
• 自动去除 <think...</think 标签（兼容 MiniMax 等模型的思考格式）
• 自动去重（ADK 最后一个 event 会重复发送完整内容）
• finishReason: "STOP" 时提取正式回复并发送给用户

技术栈

• Python >= 3.10
• wecom-aibot-python-sdk - 企业微信智能机器人 SDK
• httpx - 异步 HTTP 客户端（支持 SSE 流式）
• python-dotenv - 环境变量管理
• Docker + Docker Compose - 容器化部署