init

wechat-bot/README.md

@@ -0,0 +1,137 @@
+# 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** - 容器化部署