12 KiB
12 KiB
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（推荐起步）: 不使用关系数据库，用文件/内存存储
// 用户注册本质上就是向WuKongIM申请一个token
// agent的对话频道和消息都存储在WuKongIM内部
// App Server 本身不需要持久化存储
选项 B（如果需要持久化）: SQLite / PebbleDB
-- 极简表设计
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 实现。