初始化 agent_ops 文档治理体系

2026-08-07 16:56:51 +08:00
commit 10840909ab
75 changed files with 15750 additions and 0 deletions
@@ -0,0 +1,398 @@
+# 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 为第一期）
+- 框架级工具路由替代字典路由