173 lines
5.9 KiB
Markdown
173 lines
5.9 KiB
Markdown
---
|
||
name: 艾叶 IM Bridge
|
||
description: 多平台 IM 消息网关。将个人微信、企业微信、飞书、WhatsApp、网页聊天等平台的消息桥接到卡若AI，实现跨平台 AI 对话。使用本技能当需要：(1) 配置/启动 IM 桥接 (2) 新增聊天通道 (3) 排查 IM 通道问题 (4) 对接新的消息平台
|
||
triggers: 艾叶、IM、聊天对接、消息网关、微信对接、企业微信对接、飞书对接、WhatsApp对接、网页聊天、IM桥接、通道配置、艾叶IM
|
||
owner: 火炬
|
||
group: 火
|
||
version: "1.0"
|
||
updated: "2026-03-13"
|
||
---
|
||
|
||
# 艾叶 IM Bridge
|
||
|
||
## 概述
|
||
|
||
艾叶是卡若AI的多平台 IM 消息网关，参考 OpenClaw 三层架构设计（Gateway → Channel → LLM），让任何聊天平台的消息都能路由到卡若AI进行对话，然后把 AI 回复推回对应平台。
|
||
|
||
**核心理念**：一个网关，任何平台，同一个 AI。
|
||
|
||
## 架构
|
||
|
||
```
|
||
个人微信 / 企业微信 / 飞书 / WhatsApp / 网页
|
||
│
|
||
┌─────────▼─────────┐
|
||
│ 艾叶 IM Bridge │ ← Channel Layer（通道适配）
|
||
│ (FastAPI:18900) │
|
||
└─────────┬─────────┘
|
||
│ HTTP POST /v1/chat
|
||
┌─────────▼─────────┐
|
||
│ 卡若AI 网关 │ ← LLM Layer（AI 推理）
|
||
│ (FastAPI:18080) │
|
||
└───────────────────┘
|
||
```
|
||
|
||
## 源代码位置
|
||
|
||
```
|
||
/Users/karuo/Documents/个人/卡若AI/运营中枢/scripts/aiye_im_bridge/
|
||
```
|
||
|
||
## 支持的通道
|
||
|
||
| 通道 | 对接方式 | Webhook 路径 | 状态 |
|
||
|:---|:---|:---|:---|
|
||
| 个人微信 | 中间件 Webhook（兼容存客宝/WeChatFerry/ComWeChatBot） | `/webhook/wechat_personal` | ✅ 就绪 |
|
||
| 企业微信 | 官方 API 回调 | `/webhook/wechat_work` | ✅ 就绪 |
|
||
| 飞书 | 事件订阅回调 | `/webhook/feishu` | ✅ 就绪 |
|
||
| WhatsApp | Cloud API Webhook | `/webhook/whatsapp` | ✅ 就绪 |
|
||
| 网页聊天 | REST + WebSocket | `/api/web/chat` `/ws/web/chat` `/chat` | ✅ 就绪 |
|
||
|
||
## 快速开始
|
||
|
||
### 1. 启动
|
||
|
||
```bash
|
||
cd 运营中枢/scripts/aiye_im_bridge
|
||
bash start.sh # 默认端口 18900
|
||
bash start.sh 19000 # 指定端口
|
||
```
|
||
|
||
### 2. 配置通道
|
||
|
||
编辑 `config/channels.yaml`，按需启用通道并填入对应平台的凭证。首次运行会自动从 `channels.example.yaml` 复制一份。
|
||
|
||
### 3. 验证
|
||
|
||
- 访问 `http://localhost:18900` 查看欢迎页
|
||
- 访问 `http://localhost:18900/chat` 打开网页聊天
|
||
- 访问 `http://localhost:18900/status` 查看通道状态
|
||
|
||
## 各通道配置说明
|
||
|
||
### 个人微信
|
||
|
||
需要一个微信协议中间件（存客宝、WeChatFerry、ComWeChatBot 等），中间件负责微信登录和消息抓取，艾叶只做 HTTP 桥接：
|
||
1. 中间件将消息 POST 到 `http://艾叶地址/webhook/wechat_personal`
|
||
2. 艾叶处理后通过 `callback_url` 回调中间件发送回复
|
||
|
||
### 企业微信
|
||
|
||
1. 在企业微信管理后台创建自建应用
|
||
2. 设置回调 URL 为 `http(s)://你的域名/webhook/wechat_work`
|
||
3. 在 `channels.yaml` 填入 `corp_id`、`agent_id`、`secret`、`token`、`encoding_aes_key`
|
||
|
||
### 飞书
|
||
|
||
1. 在飞书开放平台创建应用
|
||
2. 开启「机器人」能力
|
||
3. 事件订阅地址设为 `http(s)://你的域名/webhook/feishu`
|
||
4. 订阅事件 `im.message.receive_v1`
|
||
5. 在 `channels.yaml` 填入 `app_id`、`app_secret`、`verification_token`
|
||
|
||
### WhatsApp
|
||
|
||
1. 在 Meta 开发者后台配置 WhatsApp Business API
|
||
2. Webhook URL 设为 `http(s)://你的域名/webhook/whatsapp`
|
||
3. 在 `channels.yaml` 填入 `phone_number_id`、`access_token`、`verify_token`
|
||
|
||
### 网页聊天
|
||
|
||
默认启用。访问 `/chat` 即可使用内置聊天界面，也可通过 REST API 或 WebSocket 集成到自己的系统。
|
||
|
||
## 扩展新通道
|
||
|
||
继承 `core/channel_base.py` 的 `ChannelBase`，实现以下方法：
|
||
|
||
```python
|
||
class MyChannel(ChannelBase):
|
||
@property
|
||
def platform(self) -> str:
|
||
return "my_platform"
|
||
|
||
async def start(self) -> None: ...
|
||
async def stop(self) -> None: ...
|
||
async def send(self, msg: OutboundMessage) -> bool: ...
|
||
def register_routes(self, app) -> None: ...
|
||
```
|
||
|
||
然后在 `main.py` 的 `_register_channels()` 中注册即可。
|
||
|
||
## 聊天命令
|
||
|
||
在任何通道中发送：
|
||
- `/reset` — 重置对话上下文
|
||
- `/status` — 查看当前会话状态
|
||
- `/help` — 查看可用命令
|
||
|
||
## 管理接口
|
||
|
||
| 路径 | 方法 | 说明 |
|
||
|:---|:---|:---|
|
||
| `/` | GET | 欢迎页 |
|
||
| `/status` | GET | 通道状态 |
|
||
| `/health` | GET | 健康检查 |
|
||
| `/chat` | GET | 网页聊天界面 |
|
||
| `/docs` | GET | API 文档（Swagger） |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
aiye_im_bridge/
|
||
├── main.py # 主入口
|
||
├── start.sh # 启动脚本
|
||
├── requirements.txt # 依赖
|
||
├── config/
|
||
│ ├── channels.yaml # 通道配置（不入库）
|
||
│ └── channels.example.yaml # 配置示例
|
||
├── core/
|
||
│ ├── channel_base.py # Channel 基类
|
||
│ ├── router.py # 消息路由
|
||
│ ├── session.py # 会话管理
|
||
│ └── bridge.py # 网关桥接
|
||
└── channels/
|
||
├── wechat_personal.py # 个人微信
|
||
├── wechat_work.py # 企业微信
|
||
├── feishu.py # 飞书
|
||
├── whatsapp.py # WhatsApp
|
||
└── web.py # 网页聊天
|
||
```
|
||
|
||
## 依赖
|
||
|
||
- Python 3.10+
|
||
- fastapi、uvicorn、httpx、pyyaml、websockets
|
||
- 卡若AI 网关运行中（默认 `http://127.0.0.1:18080`）
|
||
|
||
## 与消息中枢的关系
|
||
|
||
- **消息中枢**（Clawdbot/Moltbot）：TypeScript，OpenClaw 框架，重型多通道 AI 助手
|
||
- **艾叶**：Python，轻量 Webhook 桥接，专注于把消息接到卡若AI网关
|
||
|
||
两者可共存，艾叶更适合快速对接新平台、轻量部署。
|