Initialize LineUp app server
This commit is contained in:
@@ -0,0 +1,333 @@
|
||||
# LineUp App Server — 项目设计文档
|
||||
|
||||
> 版本：0.1（提案）
|
||||
> 日期：2026-07-30
|
||||
> 状态：待确认
|
||||
> 目标：精简的蓝牙应用服务端，帮助用户与远端 Agent 服务建立连接，实现互相通信
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目定位
|
||||
|
||||
### 1.1 与唐僧叨叨的关系
|
||||
|
||||
唐僧叨叨是一个完整的 IM 业务系统（用户/群组/文件/朋友圈/工作台/推送...），模块众多、功能庞大。LineUp App Server 不是唐僧叨叨的副本，而是：
|
||||
|
||||
```
|
||||
唐僧叨叨：消费级 IM 全栈（群聊、朋友圈、文件、搜索...）
|
||||
LineUp App Server：只做两件事 ——
|
||||
① 用户认证身份 → 接入通讯网络
|
||||
② 消息路由 → 连接用户与 Agent
|
||||
```
|
||||
|
||||
**所以我们不是在唐僧叨叨上改，而是从它那里取经：**
|
||||
- 复用它的 WuKongIM 集成模式（怎么调用 API、怎么写 Webhook）
|
||||
- 复用它的 HTTP 路由注册方式（gin 框架 + module 自注册）
|
||||
- 复用它的 Webhook 消息处理逻辑（msg.notify、msg.offline 等事件）
|
||||
- 丢弃所有跟业务无关的模块（群聊、文件、推送、朋友圈...）
|
||||
|
||||
### 1.2 LineUp App Server 的定义
|
||||
|
||||
> LineUp App Server 是一个轻量级的**通讯网关**。
|
||||
> 它的唯一职责是：让一个通过蓝牙/WiFi 连接的移动客户端，能够接入 WuKongIM 3.0 通讯网络，并与远端的 Agent 服务进行消息交换。
|
||||
|
||||
**它不是什么：**
|
||||
- 不是社交平台（不处理好友、朋友圈、群聊）
|
||||
- 不是文件存储（不处理文件上传/下载）
|
||||
- 不是推送网关（不处理 APNS/HMS/Mi Push）
|
||||
- 不是管理后台（不处理统计、审核、工作台）
|
||||
- 不是机器人平台（不处理自定义机器人接入）
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心概念
|
||||
|
||||
### 2.1 三种参与者
|
||||
|
||||
```
|
||||
┌──────────┐ ┌─────────────────┐ ┌──────────┐
|
||||
│ 用户 Client │ ◄─► │ LineUp App Server │ ◄─► │ Agent 服务 │
|
||||
│ (手机 App) │ │ (通讯网关) │ │ (远端 LLM) │
|
||||
└──────────┘ └────────┬────────┘ └──────────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ WuKongIM 3.0 │
|
||||
│ (消息管道) │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
- **用户 Client**：运行在手机上的 App，通过蓝牙/WiFi 与 App Server 通信
|
||||
- **Agent 服务**：远端的 AI Agent（如 Hermes），有自己的 WuKongIM 客户端连接
|
||||
- **WuKongIM 3.0**：消息传输管道，负责可靠投递
|
||||
- **LineUp App Server**：通讯网关，负责身份认证 + 消息路由
|
||||
|
||||
### 2.2 消息流转模型
|
||||
|
||||
```
|
||||
用户发送消息 "帮我查天气"
|
||||
|
||||
① Client → App Server
|
||||
用户 App 通过 HTTP/WS 发送消息到 App Server
|
||||
|
||||
② App Server → WuKongIM
|
||||
App Server 调用 WuKongIM API 将消息投递到 Agent 所在的频道
|
||||
|
||||
③ WuKongIM → Agent Service
|
||||
WuKongIM 将消息推送到 Agent 的 WebSocket 连接
|
||||
|
||||
④ Agent Service 处理
|
||||
Agent 处理请求（可能调用外部工具）
|
||||
|
||||
⑤ Agent Service → WuKongIM
|
||||
Agent 回复消息，发送到 WuKongIM
|
||||
|
||||
⑥ WuKongIM → App Server (Webhook)
|
||||
WuKongIM 通过 Webhook 通知 App Server 有新消息
|
||||
|
||||
⑦ App Server → Client
|
||||
App Server 将消息推送给用户 Client
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 通信协议分层
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ LineUp 自定义消息协议 │ ← 业务层
|
||||
│ (text, choice, progress, canvas...) │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 唐僧叨叨消息模型 │ ← 适配层
|
||||
│ (Message, Channel, Conversation) │
|
||||
├──────────────────┬──────────────────────┤
|
||||
│ WKProto WebSocket│ HTTP API + Webhook │ ← WuKongIM 3.0
|
||||
│ (双向实时, 15200) │ (管理面, 15001) │
|
||||
│ │ (通知面, callback) │
|
||||
└──────────────────┴──────────────────────┘
|
||||
```
|
||||
|
||||
**WuKongIM 3.0 的三层能力:**
|
||||
|
||||
| 层 | 协议 | 端口 | 方向 | 用途 |
|
||||
|---|---|---|---|---|
|
||||
| **数据面** | WKProto WebSocket / TCP | 15200 / 15100 | **双向全双工** | 客户端收发消息 |
|
||||
| **管理面** | HTTP REST API | 15001 | App Server → WK | 用户/频道/消息管理 |
|
||||
| **通知面** | HTTP Webhook | Callback | WK → App Server | 事件通知(新消息/离线/在线) |
|
||||
|
||||
> 客户端直连 WuKongIM 的 WebSocket (15200),所有实时消息都在这个管道里跑。
|
||||
> App Server 只做两件事: ① 通过 HTTP API 做管理; ② 通过 Webhook 接收事件推送给 Client。
|
||||
|
||||
---
|
||||
|
||||
## 4. 架构设计
|
||||
|
||||
### 4.1 服务端口
|
||||
|
||||
```
|
||||
LineUp App Server:
|
||||
- HTTP API: :8090 (客户端 REST API)
|
||||
- WebSocket: :8090/ws (客户端实时推送)
|
||||
- Webhook: :8090/v1/webhook (接收 WuKongIM 回调)
|
||||
|
||||
WuKongIM 3.0: (已部署)
|
||||
- API: :15001 (管理 API: /route, /channel, /message/send...)
|
||||
- TCP: :15100 (WKProto TCP)
|
||||
- WebSocket: :15200 (WKProto WebSocket)
|
||||
- Manager: :15301 (管理后台)
|
||||
```
|
||||
|
||||
### 4.2 模块划分
|
||||
|
||||
```
|
||||
lineup-app-server/
|
||||
├── main.go # 入口：加载配置 → 注册模块 → 启动 HTTP
|
||||
├── go.mod / go.sum
|
||||
├── configs/
|
||||
│ └── lineup.yaml # 配置：WuKongIM 地址、Token、端口
|
||||
├── internal/
|
||||
│ ├── app.go # App 生命周期：Init → Start → Stop
|
||||
│ ├── config.go # 配置结构体
|
||||
│ └── db.go # 数据库（轻量，仅存储用户/Token）
|
||||
└── modules/
|
||||
├── user/ # 用户模块：登录/注册/Token管理
|
||||
│ ├── module.go # → 模块自注册
|
||||
│ ├── api.go # → REST: POST /login, POST /register
|
||||
│ ├── db.go # → 用户数据存储
|
||||
│ └── service.go # → 业务逻辑
|
||||
├── channel/ # 频道模块：创建Agent对话频道
|
||||
│ ├── module.go
|
||||
│ ├── api.go # → REST: POST /channels, GET /channels
|
||||
│ └── service.go # → 调用 WuKongIM Channel API
|
||||
├── message/ # 消息模块：收发消息
|
||||
│ ├── module.go
|
||||
│ ├── api.go # → REST: POST /messages, GET /messages/sync
|
||||
│ └── service.go # → 调用 WuKongIM Message API
|
||||
├── webhook/ # Webhook模块：接收WuKongIM回调
|
||||
│ ├── module.go
|
||||
│ ├── handler.go # → HTTP: POST /v1/webhook
|
||||
│ └── event.go # → 事件分发：msg.notify → 推送Client
|
||||
└── client/ # 客户端连接模块（蓝牙/WS网关）
|
||||
├── module.go
|
||||
├── ws.go # → WebSocket: /ws (向Client实时推送)
|
||||
└── push.go # → 消息推送：把WuKongIM消息推给客户端
|
||||
```
|
||||
|
||||
**只有 6 个模块（vs 唐僧叨叨的 15 个），代码量预计减少 70%+。**
|
||||
|
||||
### 4.3 数据库设计（最简方案）
|
||||
|
||||
选项 A（推荐起步）: **不使用关系数据库，用文件/内存存储**
|
||||
```go
|
||||
// 用户注册本质上就是向WuKongIM申请一个token
|
||||
// agent的对话频道和消息都存储在WuKongIM内部
|
||||
// App Server 本身不需要持久化存储
|
||||
```
|
||||
|
||||
选项 B（如果需要持久化）: **SQLite / PebbleDB**
|
||||
```sql
|
||||
-- 极简表设计
|
||||
CREATE TABLE users (
|
||||
uid TEXT PRIMARY KEY, -- 用户ID（与WuKongIM一致）
|
||||
token TEXT, -- WuKongIM Token
|
||||
name TEXT, -- 显示名称
|
||||
created INTEGER -- 创建时间
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 核心通讯流程
|
||||
|
||||
### 5.1 用户上线流程
|
||||
|
||||
```
|
||||
Step 1: Client 通过 HTTP POST /login
|
||||
→ App Server 验证用户凭证
|
||||
→ App Server 调用 WuKongIM API 获取 Route 信息
|
||||
→ 返回 {token, route} 给 Client
|
||||
|
||||
Step 2: Client 使用 token 和 route 直连 WuKongIM WebSocket
|
||||
→ WuKongIM WebSocket: ws://host:15200?token=xxx
|
||||
→ 这一步完全绕开 App Server，Client 自己跟 WuKongIM 通信
|
||||
|
||||
Step 3: Client 同时连接 App Server WebSocket
|
||||
→ ws://app-server:8090/ws?token=xxx
|
||||
→ 用于接收实时推送（Webhook 转发过来的消息）
|
||||
```
|
||||
|
||||
**关键设计决策：客户端直连 WuKongIM，App Server 只作为 Webhook 中转。**
|
||||
|
||||
### 5.2 发送消息流程
|
||||
|
||||
```
|
||||
Client → WuKongIM WebSocket (直连)
|
||||
→ 消息直接写入 WuKongIM，不经过 App Server
|
||||
→ App Server 通过 Webhook 收到通知后，可以通过 WebSocket 推送给对端
|
||||
```
|
||||
|
||||
### 5.3 Agent 连接方式
|
||||
|
||||
```
|
||||
Agent Service 有两种接入方式：
|
||||
|
||||
方式 A（推荐）：直接作为 WuKongIM 客户端
|
||||
- Agent 用 Go/Python SDK 连接 WuKongIM
|
||||
- 收发消息走 WuKongIM 原生协议
|
||||
- App Server 完全透明，只做 Webhook 中转
|
||||
|
||||
方式 B：通过 App Server API
|
||||
- Agent 注册为 App Server 的"特殊用户"
|
||||
- 消息通过 App Server 的 HTTP API 中转
|
||||
- 适合 Agent 无法直连 WuKongIM 的场景
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. WuKongIM 3.0 集成清单
|
||||
|
||||
### 6.1 调用的 WuKongIM API
|
||||
|
||||
| API | 用途 | 代码位置 |
|
||||
|---|---|---|
|
||||
| `POST /user/token` | 生成用户 Token | `modules/user/service.go` |
|
||||
| `GET /route?uid=` | 获取连接地址 | `modules/user/service.go` |
|
||||
| `POST /channel` | 创建 Agent 对话频道 | `modules/channel/service.go` |
|
||||
| `POST /channel/messagesync` | 同步频道消息 | `modules/message/service.go` |
|
||||
| `POST /message/send` | 发送消息（App Server 代发） | `modules/message/service.go` |
|
||||
|
||||
### 6.2 接收的 Webhook 事件
|
||||
|
||||
| 事件 | 含义 | 处理方式 |
|
||||
|---|---|---|
|
||||
| `msg.notify` | 新消息通知 | 推送给对应的 Client WebSocket |
|
||||
| `msg.offline` | 离线消息 | 推送给刚上线的 Client |
|
||||
| `user.onlinestatus` | 用户在线状态变化 | 更新 Agent 在线状态 |
|
||||
|
||||
### 6.3 v3 兼容性对照（已有验证结论）
|
||||
|
||||
| 功能 | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| Token 生成 | ✅ | API 兼容 |
|
||||
| Route 查询 | ✅ | 格式兼容（uid参数在v3被忽略但不影响） |
|
||||
| Channel 管理 | ✅ | API 兼容 |
|
||||
| Message Send | ✅ | API 兼容 |
|
||||
| Message Sync | ✅ | v3 使用 `channel/messagesync` |
|
||||
| Webhook 事件名 | ✅ | msg.notify/msg.offline/user.onlinestatus 完全一致 |
|
||||
| Webhook HTTP | ✅ | v3 原生 HTTP Webhook（不需要改 gRPC 适配） |
|
||||
| Message Search | ❌ 不需要 | 精简版不做消息搜索 |
|
||||
| 文件上传 | ❌ 不需要 | 精简版不做文件服务 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 实施计划
|
||||
|
||||
### Phase 1: 最小骨架（1-2 天）
|
||||
```
|
||||
目标：Go 项目编译通过，HTTP 服务启动，能连接 WuKongIM 3.0
|
||||
|
||||
□ 创建 go.mod，引入唐僧叨叨的 server/config 和 wkhttp
|
||||
□ 实现 main.go：加载配置 + 启动 gin HTTP 服务
|
||||
□ 实现 user 模块：POST /login（调 WuKongIM /user/token）
|
||||
□ 实现 webhook 模块：POST /v1/webhook（接收并打印事件日志）
|
||||
□ 手工测试：curl /login → 拿到 token → 用 token 连 WuKongIM
|
||||
```
|
||||
|
||||
### Phase 2: 消息通路（2-3 天）
|
||||
```
|
||||
目标：用户和 Agent 能通过 App Server + WuKongIM 互相发消息
|
||||
|
||||
□ 实现 channel 模块：创建/查询频道
|
||||
□ 实现 message 模块：发送消息、同步消息
|
||||
□ 实现 client WebSocket：向 Client 实时推送消息
|
||||
□ 端到端测试：用户发消息 → Agent 收到 → Agent 回复 → 用户收到
|
||||
```
|
||||
|
||||
### Phase 3: 蓝牙/本地通信适配（2-3 天）
|
||||
```
|
||||
目标：手机 App 通过本地网络连接 App Server
|
||||
|
||||
□ 实现蓝牙发现 / 局域网发现协议
|
||||
□ App Server 暴露本地 HTTP 服务（mDNS 广播）
|
||||
□ 安全认证：设备配对 Token
|
||||
```
|
||||
|
||||
### Phase 4: 稳定与优化（1-2 天）
|
||||
```
|
||||
□ 连接断开重连
|
||||
□ 消息确认与去重
|
||||
□ 监控与日志
|
||||
□ 性能调优
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 参考资料
|
||||
|
||||
- WuKongIM 3.0 源码：`wukongim/`
|
||||
- WuKongIM 3.0 本地环境：`infra/wukongim-v3/`
|
||||
- 兼容性验证：`项目状态记录.md` §六-§八
|
||||
- LineUp App 层架构方案：`设计/02.正式方案/lineup-app-layer-architecture.md`
|
||||
|
||||
---
|
||||
|
||||
*本文档为项目设计提案，待确认后进入 Phase 1 实现。*
|
||||
Reference in New Issue
Block a user