138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
# 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. 配置环境变量
|
||
|
||
```bash
|
||
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）：**
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
docker compose logs -f
|
||
```
|
||
|
||
**本地运行：**
|
||
|
||
```bash
|
||
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 | 同步对话（降级方案） |
|
||
|
||
### 请求格式
|
||
|
||
```json
|
||
{
|
||
"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** - 容器化部署
|