318 lines
12 KiB
Markdown
318 lines
12 KiB
Markdown
# LineUp App — 移动端设计文档
|
||
|
||
> 版本：0.1（提案）
|
||
> 日期：2026-07-30
|
||
> 依赖：LineUp App Server + WuKongIM 3.0
|
||
> 基础：唐僧叨叨 Android 客户端（wkbase / wklogin / SDK 封装）
|
||
|
||
---
|
||
|
||
## 1. 定位
|
||
|
||
LineUp App 是一个**单通道 Agent 对话客户端**。用户打开 App 后只有一个对话——和他的 AI Agent。
|
||
|
||
不是社交 IM（没有好友列表、没有群聊、没有朋友圈）。
|
||
当前版本只做一件事：**连上 WuKongIM，进入唯一频道，与 Agent 收发消息。**
|
||
|
||
```
|
||
┌──────────────────────────────────────────┐
|
||
│ LineUp App │
|
||
│ │
|
||
│ ┌───────────────────────────────┐ │
|
||
│ │ Agent 对话频道 │ │
|
||
│ │ │ │
|
||
│ │ [用户] 帮我查一下今天天气 │ │
|
||
│ │ [Agent] 北京今天晴, 22°C │ │
|
||
│ │ [Agent] ┌─ choice ─┐ │ │
|
||
│ │ │ 需要更多？ │ │ │
|
||
│ │ │ [是] [否] │ │ │
|
||
│ │ └───────────┘ │ │
|
||
│ └───────────────────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────────────────┐ │
|
||
│ │ 输入框 │ │
|
||
│ └───────────────────────────────┘ │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 架构分层
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ LineUp App (Android) │
|
||
│ │
|
||
│ UI 层: 聊天界面 + Agent 消息渲染 │
|
||
│ ├─ ChatView (文本/图片/语音) │
|
||
│ └─ AgentWidgets (choice/form/canvas) │
|
||
│ │
|
||
│ 业务层: 频道管理 + 消息路由 │
|
||
│ ├─ ChannelManager (只有一个频道) │
|
||
│ └─ MessageRouter (分发到UI) │
|
||
│ │
|
||
│ 通讯层: WuKongIM SDK 封装 │
|
||
│ ├─ WKClient (长连接/心跳/重连) │
|
||
│ ├─ WKSend / WKRecv │
|
||
│ └─ TokenManager (认证) │
|
||
│ │
|
||
│ 本地存储: SQLite / SharedPreferences │
|
||
│ ├─ Token 缓存 │
|
||
│ └─ 消息历史 (最近N条) │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.1 复用唐僧叨叨的模块
|
||
|
||
| 唐僧叨叨模块 | 用途 | LineUp 是否复用 |
|
||
|---|---|---|
|
||
| `wklogin` | 登录 / 注册 / Token 获取 | ✅ 复用 |
|
||
| `wkbase` | 基础 UI / WebSocket 连接 / 消息模型 | ✅ 复用核心 |
|
||
| `wkpush` | 厂商推送 | ❌ 暂不需要 |
|
||
| `wkscan` | 扫码 | ❌ 不需要 |
|
||
| 群聊/通讯录/朋友圈 | — | ❌ 隐藏/移除 |
|
||
|
||
**核心思路：保留通信管道，砍掉社交外壳。**
|
||
|
||
---
|
||
|
||
## 3. 连接流程
|
||
|
||
### 3.1 首次启动
|
||
|
||
```
|
||
Step 1: 用户打开 App
|
||
→ 输入手机号 → 点"获取验证码" → 输入 123456
|
||
→ App 调 LineUp App Server: POST /login
|
||
→ Server 调 WuKongIM /user/token 生成 Token
|
||
→ 返回 {uid, token, im_host, im_port}
|
||
|
||
Step 2: App 用 Token 连接 WuKongIM WebSocket
|
||
→ ws://100.121.118.116:15200?token=xxx
|
||
→ WuKongIM 返回 Connack → 连接建立
|
||
|
||
Step 3: App 进入唯一频道
|
||
→ 频道 ID: "agent_default" (硬编码)
|
||
→ App 调 WuKongIM Sub 帧订阅该频道
|
||
→ 收到 Suback → 可以收发消息
|
||
|
||
Step 4: 显示对话界面
|
||
→ 同步最近 N 条消息 (channel/messagesync)
|
||
→ 等待用户输入
|
||
```
|
||
|
||
### 3.2 后续启动（Token 未过期）
|
||
|
||
```
|
||
Step 1: 读取本地缓存的 Token
|
||
Step 2: 直接连 WuKongIM WebSocket
|
||
Step 3: 跳过登录页，直接进入对话
|
||
```
|
||
|
||
### 3.3 Agent 也在同一个频道
|
||
|
||
```
|
||
用户的 WuKongIM 用户: uid="user_<phone>"
|
||
Agent 的 WuKongIM 用户: uid="agent_default"
|
||
|
||
频道 ID: "agent_default_channel"
|
||
频道类型: 个人频道 (channel_type=1)
|
||
|
||
用户 → Send(频道) → WuKongIM → Recv → Agent
|
||
Agent → Send(频道) → WuKongIM → Recv → App
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 消息类型
|
||
|
||
### 4.1 普通文本消息
|
||
|
||
用户发什么就送什么，Agent 回文本也直接显示。
|
||
|
||
### 4.2 LineUp 结构化消息（信封格式）
|
||
|
||
沿用设计文档定义的信封协议：
|
||
|
||
```json
|
||
{
|
||
"v": 1,
|
||
"id": "msg_xxx",
|
||
"type": "lineup.v1.tool.call",
|
||
"sender": {"kind": "agent", "id": "agent_default"},
|
||
"target": {"kind": "device", "id": "device_phone_01"},
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
### 4.3 第一批支持的 Agent 工具消息
|
||
|
||
| 类型 | 触发条件 | UI 渲染 |
|
||
|---|---|---|
|
||
| `lineup.v1.tool.choice` | Agent 需要用户做选择 | 渲染为可点击的选项按钮 |
|
||
| `lineup.v1.tool.confirm` | Agent 需要用户确认操作 | 渲染确认/取消按钮 |
|
||
| `lineup.v1.tool.input` | Agent 需要用户输入值 | 渲染输入框 |
|
||
| `lineup.v1.tool.progress` | Agent 报告进度 | 渲染进度条 |
|
||
| `lineup.v1.event.error` | Agent 报错 | 渲染错误提示 |
|
||
|
||
**这些 payload 通过 WuKongIM 的 SendPacket.Payload 字段传递，App 收到后解析 type 字段决定渲染方式。**
|
||
|
||
### 4.4 通用 UI Surface 与上层 App 能力
|
||
|
||
除内置文本、Markdown、choice、confirm、progress 等稳定组件外，LineUp Client 还支持受控的 UI Surface：Agent 可发送 `lineup.v1.ui.open`，以 HTML/CSS/JS 描述一个交互界面；后续以 `ui.patch` 推送状态，以 `ui.event` 接收用户动作，以 `ui.close` 关闭实例。
|
||
|
||
这不是把 Agent 脚本放进 App 主进程执行。Android 端必须在隔离 WebView 中承载 Surface，禁用任意网络访问、文件访问、同源权限和未注册的 JavaScript interface。Surface 只能通过受限 bridge 上报用户事件。
|
||
|
||
Agent 若要调用 App 的上层能力（例如打开链接、选文件、写剪贴板、相机、定位或业务模块），必须走独立的 `lineup.v1.app.list` → `app.call` → `app.result` 协议：Client 先声明 capability，再按风险等级弹出用户确认或系统授权，绝不允许 Surface 直接越权调用。本协议详见 [LineUp UI Surface 与 App Capability 协议](../设计/02.正式方案/lineup-ui-surface-protocol.md)。
|
||
|
||
---
|
||
|
||
## 5. UI 设计
|
||
|
||
### 5.1 消息渲染规则
|
||
|
||
```
|
||
if payload 为空:
|
||
→ 普通文本消息，照常显示
|
||
|
||
if payload.type == "lineup.v1.tool.choice":
|
||
→ 渲染为选项卡片
|
||
→ 用户点击某个选项后:
|
||
→ App 组装 tool.result Payload
|
||
→ Send 回 Agent
|
||
|
||
if payload.type == "lineup.v1.tool.progress":
|
||
→ 渲染为进度条卡片
|
||
→ 被动显示，无需用户操作
|
||
```
|
||
|
||
### 5.2 登录页
|
||
|
||
```
|
||
┌──────────────────────┐
|
||
│ │
|
||
│ LineUp │
|
||
│ 你的 AI 搭档 │
|
||
│ │
|
||
│ ┌──────────────────┐│
|
||
│ │ +86 手机号 ││
|
||
│ └──────────────────┘│
|
||
│ ┌────────┐ ┌──────┐ │
|
||
│ │ 验证码 │ │ 获取 │ │
|
||
│ └────────┘ └──────┘ │
|
||
│ │
|
||
│ [ 登 录 ] │
|
||
│ │
|
||
└──────────────────────┘
|
||
```
|
||
|
||
### 5.3 主界面
|
||
|
||
```
|
||
┌──────────────────────────────┐
|
||
│ Agent (在线) ··· │ ← 顶部栏：Agent名称+在线状态
|
||
├──────────────────────────────┤
|
||
│ │
|
||
│ [Agent] 你好，我是你的 AI │
|
||
│ 助手，有什么可以帮 │
|
||
│ 助你的？ │
|
||
│ │
|
||
│ [用户] 帮我查天气 │
|
||
│ │
|
||
│ [Agent] ┌─ 选择城市 ────┐ │
|
||
│ │ ○ 北京 │ │
|
||
│ │ ○ 上海 │ │
|
||
│ │ ● 深圳 │ │
|
||
│ │ [确认] │ │
|
||
│ └────────────────┘ │
|
||
│ │
|
||
├──────────────────────────────┤
|
||
│ ┌────────────────────┐ 📎 │ ← 输入栏
|
||
│ │ 输入消息... │ 📷 │
|
||
│ └────────────────────┘ 🎤 │
|
||
└──────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 服务端交互协议
|
||
|
||
### 6.1 App → LineUp App Server
|
||
|
||
| API | 方法 | 用途 |
|
||
|---|---|---|
|
||
| `/login` | POST | 手机号+验证码 → {uid, token, im_addr} |
|
||
| `/ws` | WebSocket | App 维持与 Server 的长连接（接收 Server 推送） |
|
||
|
||
### 6.2 App → WuKongIM (直连)
|
||
|
||
| 操作 | 方向 | 协议 |
|
||
|---|---|---|
|
||
| 连接 | App → WK | WKProto Connect (带 Token) |
|
||
| 发消息 | App → WK | WKProto Send (频道+Payload) |
|
||
| 收消息 | WK → App | WKProto Recv |
|
||
| 同步消息 | App → WK | channel/messagesync |
|
||
| 心跳 | 双向 | WKProto Ping/Pong |
|
||
|
||
---
|
||
|
||
## 7. 与唐僧叨叨 App 的差异
|
||
|
||
| 功能 | 唐僧叨叨 | LineUp App |
|
||
|---|---|---|
|
||
| 登录 | 手机号+验证码 / 第三方 | 手机号+验证码（简化版） |
|
||
| 主界面 | 会话列表（多聊天） | **直接进入唯一 Agent 对话** |
|
||
| 通讯录 | 好友+群组+工作台 | 无 |
|
||
| 发现页 | 朋友圈+附近 | 无 |
|
||
| 消息类型 | 文本/图片/语音/文件/位置 | 文本 + Agent 工具卡片 |
|
||
| 设置 | 隐私/通知/通用 | 极简（仅退出/重置） |
|
||
| WuKongIM 连接 | `wkbase` SDK 封装 | 复用 `wkbase` 核心 |
|
||
| 服务端 | 唐僧叨叨业务层 | LineUp App Server |
|
||
|
||
---
|
||
|
||
## 8. 实施计划
|
||
|
||
### Phase 1: 最小通信通路（1-2天）
|
||
```
|
||
目标: 能登录、连 WuKongIM、收发文本消息
|
||
|
||
□ 基于唐僧叨叨 wklogin + wkbase 创建简化版 App 壳
|
||
□ 移除所有非必要模块（群聊/通讯录/朋友圈）
|
||
□ 登录后直连 WuKongIM WebSocket
|
||
□ 硬编码频道 ID，进入固定对话
|
||
□ 能发送和接收文本消息
|
||
```
|
||
|
||
### Phase 2: Agent 工具消息渲染（2-3天）
|
||
```
|
||
目标: 能解析 LineUp 信封，渲染 choice/confirm/progress
|
||
|
||
□ 实现 Payload 解析器
|
||
□ choice 卡片 → 选项按钮列表
|
||
□ confirm 卡片 → 确认/取消按钮
|
||
□ progress 卡片 → 进度条
|
||
□ 用户操作后组装 tool.result 回传给 Agent
|
||
```
|
||
|
||
### Phase 3: UI 美化 + 体验优化（2-3天）
|
||
```
|
||
目标: 不再是粗制原型，而是可用产品
|
||
|
||
□ 对话气泡 UI 优化
|
||
□ Agent 在线状态指示
|
||
□ 消息发送状态（发送中/已送达）
|
||
□ 启动动画 / 过渡效果
|
||
□ 错误处理（断网/超时）
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 参考资料
|
||
|
||
- 唐僧叨叨 Android 源码: `upstream/tangsengdaodao-android/`
|
||
- LineUp App Server 设计: `lineup-app-server/DESIGN.md`
|
||
- WuKongIM JS SDK: `@wukongim/sdk-js` (Agent 端用)
|
||
- LineUp App 层架构: `设计/02.正式方案/lineup-app-layer-architecture.md`
|
||
- 消息信封与 UI Surface 定义: `设计/02.正式方案/lineup-ui-surface-protocol.md`
|