# 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 实现。*