# Phase 4: 多平台接入 — 开发报告

> **报告日期**：2026-05-23
> **分支**：`dev`
> **阶段**：Phase 4 — 多平台接入
> **总计修改文件数**：18 个 (新增 15 个, 修改 3 个)
> **总代码行数**：1852 行 (Go) + 配置文件
> **编译状态**：platform-bridge ✅ / ai-core ⚠️ 网络不可用 (预存在问题)

---

## 一、背景

Phase 3 完成了插件与工具系统。Phase 4 的目标是建立统一的多平台消息接入层，让昔涟能够通过 QQ、Telegram、Webhook 等多种渠道与用户交互。

### 核心目标

| 任务 | 说明 |
|------|------|
| 统一消息模型 | 所有平台消息转换为统一的 UnifiedMessage/UnifiedResponse |
| 身份映射 | 平台用户 UID → Cyrene 用户的身份映射与权限管理 |
| QQ OBv11 适配器 | 反向 WebSocket 连接，QQ 机器人协议适配 |
| Telegram 适配器 | Bot API Webhook 模式，消息收发 + 输入状态 |
| 通用 Webhook | 标准 HTTP POST 接收任意平台消息 |
| 权限检查器 | admin/full/basic/restricted 四级权限，工具/设备白名单 |
| WeChat/Feishu/Discord 桩 | 预留接口，待后续接入外部 SDK |

---

## 二、架构概览

```
┌──────────────────────────────────────────────────────┐
│               Platform Bridge (port 8095)             │
│                                                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐             │
│  │ QQ OBv11 │ │ Telegram │ │ Webhook  │  ... 6 适配器│
│  │ (WS 8096)│ │ (Bot API)│ │ (通用)    │             │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘             │
│       │              │              │                  │
│  ┌────▼──────────────▼──────────────▼────┐            │
│  │           Platform Router             │            │
│  │  ┌────────────┐  ┌─────────────────┐  │            │
│  │  │  Identity  │  │   Permission    │  │            │
│  │  │  Mapper    │  │   Checker       │  │            │
│  │  └────────────┘  └────────┬────────┘  │            │
│  └───────────────────────────┴────────────┘            │
│                    │                                   │
│            forwardToAICore()                           │
│                    │                                   │
│            ┌───────▼────────┐                          │
│            │   AI-Core      │                          │
│            │ (port 8081)    │                          │
│            └────────────────┘                          │
└──────────────────────────────────────────────────────┘
```

## 消息流程

```
外部平台消息 → Adapter.ToUnified() → 统一消息 → IdentityMapper.Resolve()
    → Permission Check → forwardToAICore() → 统一响应 → Adapter.FromUnified()
    → 平台消息发送
```

---

## 三、文件清单

### 3.1 核心类型 (internal/bridge/)

| 文件 | 行数 | 说明 |
|------|------|------|
| `unified.go` | 76 | UnifiedMessage, UnifiedResponse, ResponseMessage, PlatformCapabilities, PlatformMessage, Attachment, PlatformHints |
| `adapter.go` | 24 | PlatformAdapter 接口 (PlatformName, ToUnified, FromUnified, Capabilities, Connect, Disconnect, IsConnected, HealthCheck) + MessageHandler 类型 |
| `mapper.go` | 73 | IdentityMapper — platform:platformUID → CyreneUser 映射注册/查询/列表 |
| `router.go` | 168 | PlatformRouter — 适配器注册、消息路由、通道上下文管理、响应发送 |

### 3.2 权限系统 (internal/permissions/)

| 文件 | 行数 | 说明 |
|------|------|------|
| `permissions.go` | 115 | PlatformIdentity 结构体 + Checker 权限检查器 (四级权限: admin/full/basic/restricted)、工具白名单、IoT 设备白名单 |

### 3.3 平台适配器 (internal/adapter/)

| 文件 | 行数 | 说明 |
|------|------|------|
| `qq/protocol.go` | 75 | OBv11 协议类型 (OBv11Message, OBv11Sender, OBv11SendMsg 等) |
| `qq/adapter.go` | 394 | QQ 适配器 — 反向 WebSocket 服务器, ToUnified/FromUnified, SendMessage, ReadMessages 事件循环, markdown→QQ 格式转换 |
| `telegram/adapter.go` | 251 | Telegram 适配器 — Bot API Webhook, ToUnified 支持结构化/map 两种输入, SendMessage, SendChatAction (typing 指示器) |
| `webhook/adapter.go` | 121 | 通用 Webhook 适配器 — WebhookPayload/WebhookResponse 标准格式 |
| `wechat/stub.go` | 50 | 微信桩 (待 WeChatFerry / 企业微信 SDK) |
| `feishu/stub.go` | 50 | 飞书桩 (待 Lark Go SDK) |
| `discord/stub.go` | 50 | Discord 桩 (待 discordgo) |

### 3.4 REST API (internal/handler/)

| 文件 | 行数 | 说明 |
|------|------|------|
| `bridge_handler.go` | 149 | 路由注册, /health, /api/v1/platforms, /api/v1/identities, /api/v1/webhook/telegram, /api/v1/webhook/{platform} |

### 3.5 配置与入口

| 文件 | 行数 | 说明 |
|------|------|------|
| `config/config.go` | 52 | 环境变量加载 (PORT, AI_CORE_URL, QQ_BOT_PORT, TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_URL) |
| `cmd/main.go` | 204 | 服务入口 — 创建 mapper/checker/router, 注册 6 个适配器, 设置消息处理器, QQ 消息读取循环, 身份种子数据 |

### 3.6 DevTools 集成 (修改)

| 文件 | 变更 | 说明 |
|------|------|------|
| `devtools/src/config.js` | +33 行 | 添加 plugin-manager 和 platform-bridge 服务配置 |
| `devtools/src/process-manager.js` | +2/-2 | 添加新服务到启动顺序和 DB 检查列表 |
| `backend/go.work` | +1 | 添加 platform-bridge 模块 |

---

## 四、关键设计决策

### 4.1 导入循环解决

原始设计中 `adapter` 包定义了 `PlatformAdapter` 接口，`bridge` 包的 `router.go` 引用它，但 `adapter` 实现文件又引用 `bridge` 的类型。产生了循环依赖：

```
adapter ↔ bridge (import cycle)
```

**解决方案**：将 `PlatformAdapter` 接口和 `MessageHandler` 类型从 `internal/adapter/` 移到 `internal/bridge/adapter.go`，与它们引用的类型 (`UnifiedMessage`, `UnifiedResponse`) 放在同一包中。

同理，`permissions ↔ bridge` 循环通过将 `PlatformIdentity` 从 `bridge/mapper.go` 移到 `permissions/permissions.go` 解决。

### 4.2 QQ 适配器的反向 WebSocket

QQ 使用 OneBot v11 协议，采用反向 WebSocket 模式：
- **平台桥接启动 WebSocket 服务器** (端口 8096)
- **QQ 机器人框架主动连接到此端口**
- 消息通过 WebSocket 双向传递

```go
// Connect 非阻塞：在 goroutine 中启动 HTTP Server
mux.HandleFunc("/ws/qq", func(w, r) { upgrade(w, r) })
go srv.ListenAndServe()
```

### 4.3 Telegram Webhook 模式

Telegram 适配器使用 Bot API webhook：
- **启动时**调用 `setWebhook` 注册回调 URL
- **运行时**被动接收 Telegram 服务器推送的 Update
- **ToUnified** 同时支持结构化 `*TelegramUpdate` 和原始 `map[string]interface{}`，避免 HTTP handler 与适配器类型耦合

### 4.4 桩适配器策略

WeChat、Feishu、Discord 目前为桩实现。它们实现了完整的 `PlatformAdapter` 接口但返回错误信息，提示需要哪个 SDK。这样做的好处：
- 路由注册和平台列表正常工作
- 当获取到对应的 SDK 和凭据后，只需替换桩实现即可
- Auth 系统可通过 API 查看所有平台状态

### 4.5 权限模型

```
admin     → 所有权限 (聊天/IoT操控/查询/记忆管理/系统管理/全部工具/全部设备)
full      → 聊天 + IoT操控 + IoT查询 + 记忆访问
basic     → 聊天 + IoT查询
restricted → 仅聊天
```

权限检查器支持细粒度的工具白名单和设备白名单，admin 自动拥有所有权限。

---

## 五、API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查，返回平台列表 |
| GET | `/api/v1/platforms` | 列出所有平台及其能力 |
| GET | `/api/v1/platforms/{name}` | 单个平台详情 |
| GET | `/api/v1/identities` | 列出所有身份映射 |
| POST | `/api/v1/webhook/telegram` | 接收 Telegram Bot API Update |
| POST | `/api/v1/webhook/{platform}` | 接收通用 Webhook 消息 |

---

## 六、环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PORT` | 8095 | 桥接服务 HTTP 端口 |
| `AI_CORE_URL` | http://localhost:8081 | AI-Core 地址 |
| `QQ_BOT_PORT` | 8096 | QQ OBv11 WebSocket 监听端口 |
| `TELEGRAM_BOT_TOKEN` | (空) | Telegram Bot API Token |
| `TELEGRAM_WEBHOOK_URL` | (空) | Telegram Webhook 回调 URL |
| `QQ_ADMIN_UID` | (空) | QQ 管理员 UID (种子身份) |
| `TELEGRAM_ADMIN_UID` | (空) | Telegram 管理员 UID (种子身份) |

---

## 七、已知限制

1. **WeChat/Feishu/Discord 为桩** — 需要对应的 SDK 和凭据后才能启用
2. **QQ 适配器未实现心跳** — OBv11 协议中 bot 需要定期发送心跳包维持连接
3. **Telegram 未处理 callback_query** — 目前仅处理 message 类型的 Update
4. **平台桥接与 Gateway 之间无内部认证** — `forwardToAICore` 直接调用 AI-Core，绕过 Gateway。后续若需要 Gateway 统一管理会话，应通过 Gateway 的 HTTP API 而非 WebSocket

---

## 八、验证指南

```bash
# 1. 编译 platform-bridge
cd backend/platform-bridge
GOWORK=off go build ./cmd/main.go

# 2. 启动服务
./main

# 3. 健康检查
curl http://localhost:8095/health

# 4. 查看注册的平台
curl http://localhost:8095/api/v1/platforms

# 5. 测试通用 Webhook
curl -X POST http://localhost:8095/api/v1/webhook/webhook \
  -H "Content-Type: application/json" \
  -d '{"user_id":"test_user","user_name":"测试用户","content":"你好昔涟","channel_id":"test_channel"}'

# 6. 查看身份映射
curl http://localhost:8095/api/v1/identities
```