# 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** - 容器化部署