399 lines
13 KiB
Markdown
399 lines
13 KiB
Markdown
# LineUp Agents v1 — 设计方案
|
||
|
||
**版本：** v1.1（第二版）
|
||
**最后更新：** 2026-07-27
|
||
|
||
---
|
||
|
||
## 一、产品定位
|
||
|
||
LineUp Agents 是一个**远程 Agent 操作交互端**。用户通过手机或 Web App，与运行在本地或服务器上的 AI Agent 进行顺畅的交互。不是任务管理系统，Agent 的任务拆解、执行、管理属于 Agent 自己的工作范畴。
|
||
|
||
### MVP 范围
|
||
|
||
| 做 | 不做 |
|
||
|----|------|
|
||
| App 直连 Agent（局域网 WebSocket）| 任务生命周期管理 |
|
||
| 通过 IM 中转连接 Agent（远程）| 自动化编排、调度 |
|
||
| App 收发消息、查看 Agent 状态 | 通知推送 |
|
||
| Agent 调 App 的工具（choice / 画板 / 计算器 等）| MCP 封装 |
|
||
| 工具发现与调用协议 | 多 Agent 工作流编排 |
|
||
| 用户 ↔ 用户基础通信（由 IM 平台提供）| 端到端加密（后续加） |
|
||
|
||
---
|
||
|
||
## 二、核心设计原则
|
||
|
||
**LineUp 协议只定义工具交互，不定义基础消息。**
|
||
|
||
这条原则是整个设计的关键。工具相关的内容（`tool.call`、`tool.result`、`tool.list`）由 LineUp 协议定义。文本、图片、语音、文件等基础消息，由下层传输平台（IM 服务或 WebSocket）原生处理，LineUp 不重复定义。
|
||
|
||
这让协议非常薄，换传输平台时工具协议不受影响。
|
||
|
||
---
|
||
|
||
## 三、架构总览
|
||
|
||
### 3.1 两种网络模式
|
||
|
||
LineUp 支持两种连接模式，插件根据配置自动切换。
|
||
|
||
**直连模式（局域网）**
|
||
|
||
```
|
||
Agent 插件 ── WebSocket 端口 :9527 ──→ App 端（Web）
|
||
```
|
||
|
||
Agent 插件在本地开 WebSocket Server，App 端手动输入 IP:端口连接。适合局域网内无公网 IP 的场景。
|
||
|
||
**中转模式（广域网）**
|
||
|
||
```
|
||
Agent 适配器 ──→ WuKongIM ←── 唐僧叨叨客户端 / LineUp App
|
||
▲
|
||
│ Webhook / HTTP API
|
||
唐僧叨叨业务服务
|
||
```
|
||
|
||
WuKongIM 负责客户端长连接、消息投递和消息存储；唐僧叨叨业务服务负责用户、好友、群组、文件等 IM 业务能力，并通过 Webhook 与 WuKongIM 协作。客户端以 WuKongIM 官方 SDK 建立长连接，以唐僧叨叨 API 处理业务操作。LineUp 的中转适配器需使用 WuKongIM 官方 SDK 或经验证的协议实现，不能复用其他 IM 平台的网关协议。
|
||
|
||
### 3.2 分层架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ 工具协议层（LineUp 定义） │
|
||
│ 内容：工具定义、tool.call / tool.result │
|
||
│ App 渲染 choice / canvas / calculator 等工具 │
|
||
├──────────────────────────────────────────────┤
|
||
│ 消息传输层（IM 平台或直连 WebSocket） │
|
||
│ 内容：文本 / 图片 / 文件 / 语音的收发 │
|
||
│ 直连模式：WebSocket 原生传输 │
|
||
│ 中转模式：WuKongIM 消息通道传输 │
|
||
├──────────────────────────────────────────────┤
|
||
│ 连接层（IM 平台或 WebSocket Server） │
|
||
│ 内容：连接建立、心跳保活、断线重连 │
|
||
│ 直连模式：Agent 插件 WS Server │
|
||
│ 中转模式：WuKongIM 连接管理 │
|
||
└──────────────────────────────────────────────┘
|
||
```
|
||
|
||
LineUp 协议只关心最上面一层。下面两层由传输平台处理。
|
||
|
||
### 3.3 设计决策
|
||
|
||
| 决策 | 当期结论 | 后续扩展思路 |
|
||
|------|---------|-------------|
|
||
| 网络模式 | 局域网直连 + WuKongIM 中转并存 | — |
|
||
| 中转服务 | 唐僧叨叨业务层 + WuKongIM 通讯层 | — |
|
||
| Agent 接入方式 | 直连模式用 LineUp 适配器；中转模式待基于 WuKongIM SDK 实现 | — |
|
||
| IM 平台选型 | WuKongIM；唐僧叨叨提供配套业务层和客户端 | — |
|
||
| App 端技术方向 | Vite + React（直连模式用 WebSocket；中转模式使用 WuKongIM JS SDK / 唐僧叨叨 API） | 原生移动端 App |
|
||
| 连接认证 | 直连：预共享 Token；中转：唐僧叨叨用户系统与 WuKongIM Token | 端到端加密 |
|
||
| 工具路由方式 | 字典路由 | 可引入框架级路由 |
|
||
|
||
---
|
||
|
||
## 四、工具协议定义（LineUp 协议的全部内容）
|
||
|
||
LineUp 协议只定义工具相关的三个消息类型。
|
||
|
||
### 4.1 工具定义结构
|
||
|
||
所有工具使用统一的结构模板，通过 `type` 区分行为差异。
|
||
|
||
| type | 含义 | 定义结构 |
|
||
|------|------|---------|
|
||
| `app` | 有状态应用，有生命周期 | `{ name, type, description, actions[] }` |
|
||
| `toolset` | 无状态工具集，多个动作 | `{ name, type, description, actions[] }` |
|
||
| `action` | 单指令工具，一个动作 | `{ name, type, description, inputSchema }` |
|
||
|
||
### 4.2 三类工具的完整定义
|
||
|
||
#### type: app — 有状态应用
|
||
|
||
```json
|
||
{
|
||
"name": "canvas",
|
||
"type": "app",
|
||
"description": "画板应用，支持绘制、撤销、清空等操作",
|
||
"actions": [
|
||
{
|
||
"name": "open",
|
||
"description": "创建画板实例，返回 instance_id",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"width": { "type": "integer", "description": "画板宽度" },
|
||
"height": { "type": "integer", "description": "画板高度" }
|
||
},
|
||
"required": ["width", "height"]
|
||
}
|
||
},
|
||
{
|
||
"name": "draw",
|
||
"description": "在画板上绘制路径",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"instance_id": { "type": "string", "description": "画板实例 ID" },
|
||
"path": { "type": "string", "description": "SVG 路径数据" },
|
||
"color": { "type": "string", "description": "线条颜色" },
|
||
"width": { "type": "integer", "description": "线条粗细" }
|
||
},
|
||
"required": ["instance_id", "path"]
|
||
}
|
||
},
|
||
{
|
||
"name": "undo",
|
||
"description": "撤销上一步操作",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"instance_id": { "type": "string", "description": "画板实例 ID" }
|
||
},
|
||
"required": ["instance_id"]
|
||
}
|
||
},
|
||
{
|
||
"name": "clear",
|
||
"description": "清空画板内容",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"instance_id": { "type": "string", "description": "画板实例 ID" }
|
||
},
|
||
"required": ["instance_id"]
|
||
}
|
||
},
|
||
{
|
||
"name": "close",
|
||
"description": "关闭画板释放资源",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"instance_id": { "type": "string", "description": "画板实例 ID" }
|
||
},
|
||
"required": ["instance_id"]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### type: toolset — 无状态工具集
|
||
|
||
```json
|
||
{
|
||
"name": "calculator",
|
||
"type": "toolset",
|
||
"description": "基础计算器，无状态，每次调用独立",
|
||
"actions": [
|
||
{
|
||
"name": "add",
|
||
"description": "两个数相加",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"a": { "type": "number" },
|
||
"b": { "type": "number" }
|
||
},
|
||
"required": ["a", "b"]
|
||
}
|
||
},
|
||
{
|
||
"name": "subtract",
|
||
"description": "两个数相减",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"a": { "type": "number" },
|
||
"b": { "type": "number" }
|
||
},
|
||
"required": ["a", "b"]
|
||
}
|
||
},
|
||
{
|
||
"name": "multiply",
|
||
"description": "两个数相乘",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"a": { "type": "number" },
|
||
"b": { "type": "number" }
|
||
},
|
||
"required": ["a", "b"]
|
||
}
|
||
},
|
||
{
|
||
"name": "divide",
|
||
"description": "两个数相除",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"a": { "type": "number" },
|
||
"b": { "type": "number" }
|
||
},
|
||
"required": ["a", "b"]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### type: action — 单指令工具
|
||
|
||
```json
|
||
{
|
||
"name": "choice",
|
||
"type": "action",
|
||
"description": "向用户提供一组选项让其选择",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"question": { "type": "string", "description": "问题描述" },
|
||
"options": { "type": "array", "items": { "type": "string" }, "description": "可选列表" }
|
||
},
|
||
"required": ["question", "options"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 三类工具对比
|
||
|
||
| | app | toolset | action |
|
||
|--|-----|---------|--------|
|
||
| 定义结构 | name + type + description + actions[] | name + type + description + actions[] | name + type + description + inputSchema |
|
||
| 适用场景 | 需要维护内部状态的应用 | 多个独立功能可归类 | 单个独立功能 |
|
||
| 生命周期 | open → use → close | 无 | 无 |
|
||
| instance_id | 需要 | 不需要 | 不需要 |
|
||
| 每次调用需 action | 是 | 是 | 仍需 action 字段 |
|
||
| 示例 | canvas（画板） | calculator（计算器） | choice / confirm / input |
|
||
|
||
### 4.4 tool.call 消息格式
|
||
|
||
```json
|
||
{
|
||
"call_id": "c1",
|
||
"name": "canvas",
|
||
"action": "open",
|
||
"arguments": { "width": 800, "height": 600 }
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `call_id` — 调用方生成，唯一标识一次调用，用于 tool.result 配对
|
||
- `name` — 工具名
|
||
- `action` — 动作名（app 和 toolset 类型必填，action 类型可省略）
|
||
- `arguments` — 动作的参数，按 inputSchema 结构传入
|
||
|
||
### 4.5 tool.result 消息格式
|
||
|
||
```json
|
||
{
|
||
"call_id": "c1",
|
||
"name": "canvas",
|
||
"action": "open",
|
||
"result": {
|
||
"message": "instance_id: inst_001"
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `call_id` — 与 tool.call 中的 call_id 一致，用于配对
|
||
- `name` — 工具名
|
||
- `action` — 动作名
|
||
- `result` — 返回数据，约定统一放在 result.message，后续按工具定义扩展
|
||
|
||
### 4.6 tool.list 消息
|
||
|
||
```json
|
||
{
|
||
"tools": [
|
||
{ "name": "choice", "type": "action", "description": "...", "inputSchema": {} },
|
||
{ "name": "calculator", "type": "toolset", "description": "...", "actions": [] },
|
||
{ "name": "canvas", "type": "app", "description": "...", "actions": [] }
|
||
]
|
||
}
|
||
```
|
||
|
||
设备注册和查询工具列表用统一的数据结构。直连模式下双向可查，中转模式下 App 端通过自定义消息类型注册工具。
|
||
|
||
---
|
||
|
||
## 五、完整交互流程
|
||
|
||
### 5.1 choice 工具调用
|
||
|
||
```
|
||
Agent 需要用户做选择
|
||
│
|
||
├── Agent 发 tool.call
|
||
│ { call_id: "c1", name: "choice", action: "select",
|
||
│ arguments: { question: "部署到哪个环境？", options: ["测试", "预发布", "生产"] } }
|
||
│
|
||
├── App 渲染选择界面，用户点击"预发布"
|
||
│
|
||
├── App 返回 tool.result
|
||
│ { call_id: "c1", name: "choice", action: "select",
|
||
│ result: { message: "预发布" } }
|
||
│
|
||
└── Agent 拿到结果，继续执行
|
||
```
|
||
|
||
### 5.2 canvas 完整生命周期
|
||
|
||
Agent 调 `canvas` 的 `open` 动作：
|
||
|
||
```json
|
||
{ "call_id": "c1", "name": "canvas", "action": "open", "arguments": { "width": 800, "height": 600 } }
|
||
```
|
||
|
||
App 返回 instance_id：
|
||
|
||
```json
|
||
{ "call_id": "c1", "name": "canvas", "action": "open", "result": { "message": "instance_id: inst_001" } }
|
||
```
|
||
|
||
Agent 绘制路径：
|
||
|
||
```json
|
||
{ "call_id": "c2", "name": "canvas", "action": "draw", "arguments": { "instance_id": "inst_001", "path": "M10 10 L50 50", "color": "red" } }
|
||
```
|
||
|
||
Agent 关闭画板：
|
||
|
||
```json
|
||
{ "call_id": "c3", "name": "canvas", "action": "close", "arguments": { "instance_id": "inst_001" } }
|
||
```
|
||
|
||
---
|
||
|
||
## 六、与 MCP 的关系
|
||
|
||
```
|
||
MCP LineUp
|
||
───────────────────────────────────────
|
||
MCP Server ──────────────── Tool（画板 / 计算器 / 选择框）
|
||
│ │
|
||
├─ MCP Tool A ├─ Action（open / draw / add / select）
|
||
├─ MCP Tool B ├─ Action
|
||
└─ MCP Tool C └─ Action
|
||
```
|
||
|
||
Tool = MCP Server 层，Action = MCP Tool 层。Action 才是实际可调用的最小能力单元。
|
||
|
||
工具定义格式复用 MCP 的 JSON Schema 标准。
|
||
|
||
---
|
||
|
||
## 七、后续可能的扩展
|
||
|
||
- 端到端加密，中转不可读消息内容
|
||
- 移动端原生 App（目前用响应式 Web）
|
||
- 直连模式切换到中转模式时的无缝过渡
|
||
- 更多 Agent 框架的插件支持（目前以 Hermes 为第一期）
|
||
- 框架级工具路由替代字典路由
|