# LineUp Agents — MVP 产品与技术规格

**状态：** v0.1 / 讨论稿  
**日期：** 2026-07-24  
**目标：** 用最小可行的服务端、Web 客户端和 Agent Adapter，验证“统一的人机协作交互层”是否成立。

---

## 1. 一句话定义

**LineUp Agents 是一个面向个人与小团队的 Agent 协作入口：人通过统一的对话、任务、状态与确认组件，连接并管理自己已经拥有的 AI Agent。**

它类似于一个为 Agent 设计的 Channel：不是替换 OpenClaw、Codex、Hermes 或自定义运行时，而是把它们接入一个更适合持续协作的交互层。

## 2. 讨论结论与产品判断

| 已达成的判断 | 对首版的含义 |
|---|---|
| 先做好交互，不急着做万能 Agent 平台 | 任务、状态、确认和展示是核心，不把能力重心放在模型或编排 |
| Agent 的长期运行需要服务端 | 服务端持久化事件、会话和任务；客户端可随时离开和回来 |
| 主流 Agent 应能接入 | 定义轻量、事件驱动的 Adapter 协议，而非绑定单一框架 |
| 配置必须简单通用 | 用户只需绑定 Agent、选择会话、开始协作；复杂部署隐藏在 Adapter 后 |
| 自动拆分/分配可探索，但自动可靠完成仍很难 | v0.1 允许 Agent 报告子任务；不做自动抢占、调度或自治执行承诺 |

## 3. 问题与目标用户

### 3.1 要解决的问题

今天的人机协作通常被困在终端、网页聊天页或某个框架专属界面中。用户很难跨端了解：

- 我的 Agent 现在是否正在执行、卡在哪里、是否失联？
- 它何时需要我确认、补充信息或授权？
- 多个持续任务之间，哪个最重要、哪个已经完成？
- 换一个 Agent 框架后，为什么交互与历史记录都断裂？

LineUp 的工作不是替 Agent 思考，而是把这些协作状态变得可见、可控、连续。

### 3.2 首批用户

1. **重度个人 Agent 用户**：在本机或 VPS 上长时间运行一个或多个 Agent，希望在手机和 Web 上随时查看和介入。
2. **小型 AI 原生团队**：成员共享少量部署好的 Agent，需要看清谁在处理什么、何时要人类决策。
3. **Agent/Runtimes 开发者**：希望用少量接入工作获得成熟交互界面，而不是重造消息、任务与通知系统。

### 3.3 北极星任务

> 我在外出时收到一条通知：我的代码 Agent 需要决定是否执行数据库迁移。我打开 LineUp，看见完整任务上下文、影响说明和两个清晰选项；批准后 Agent 继续执行，我随后能看到结果与相关产物。

## 4. 产品原则

1. **状态先于文本。** 聊天记录很重要，但“正在运行”“等待我”“已失败”必须一眼可见。
2. **人保留关键控制权。** 有风险、费用、外部副作用的行动必须能由 Agent 发起清晰的确认请求。
3. **Agent 无关，但不抹平差异。** 统一最小能力；框架特有能力可通过扩展卡片展示。
4. **渐进披露。** 默认只展示当前决策所需的信息；详细日志、原始事件和调试字段按需展开。
5. **每一件事都可追溯。** 任务、消息、审批和状态转换写入不可变事件流，便于同步与审计。
6. **先轻后重。** 先交付一个连接可靠、体验细腻的 Channel，再逐步增加任务协作能力。

## 5. MVP 范围

### 5.1 必须交付

| 能力 | 用户价值 | v0.1 交付 |
|---|---|---|
| Agent 绑定 | 连接用户已有 Agent | 配对码/Token 绑定、Agent 在线状态、撤销绑定 |
| 会话 | 保持对话连续 | 会话列表、消息流、流式文本、附件链接 |
| 任务 | 看清长期工作 | 创建任务、状态、进度、父子任务展示、取消请求 |
| 人类介入 | 不让 Agent 默默卡住 | 单选、多选、文本补充、批准/拒绝四类交互卡片 |
| 实时同步 | 跨端了解当前状态 | WebSocket、断线重连、顺序事件、离线补偿 |
| 通知 | 用户离开时仍可介入 | 浏览器通知/邮件二选一，优先通知“等待用户”和“失败” |
| Adapter SDK | 接入至少一个实际 Agent | TypeScript SDK + 示例 Adapter + 事件协议文档 |

### 5.2 明确不做

- 自动从自然语言可靠拆解、排程并完成任意复杂任务。
- Agent 之间的自动抢单、竞价、自治协调与长期记忆治理。
- 模型 API 代理、模型计费、Sandbox 执行器或完整远程桌面。
- 企业 SSO、复杂 RBAC、多租户计费与组织级合规功能。
- 原生 iOS/Android App；首版先用响应式 Web 验证交互模型。

## 6. 信息架构

```text
工作区
├── 收件箱
│   ├── 等待我处理
│   ├── 失败 / 需要关注
│   └── 最近完成
├── 会话
│   └── 一个会话对应人与一个或多个 Agent 的协作上下文
├── 任务
│   ├── 全部
│   ├── 进行中
│   ├── 等待我
│   └── 已完成 / 已取消
├── Agent
│   ├── 在线状态与能力
│   ├── 绑定 / 配置
│   └── Adapter 诊断日志
└── 设置
    └── 用户、通知、开发者 Token
```

### 6.1 核心对象

| 对象 | 含义 | 关键字段 |
|---|---|---|
| Workspace | 数据与访问边界 | `id`, `name` |
| User | 使用者 | `id`, `displayName` |
| Agent | 一个可连接的 Agent 实例 | `id`, `name`, `runtime`, `status`, `capabilities` |
| Conversation | 一个协作上下文 | `id`, `workspaceId`, `title`, `agentIds` |
| Message | 用户、Agent 或系统产生的内容 | `id`, `conversationId`, `author`, `content`, `createdAt` |
| Task | 可追踪的工作单元 | `id`, `conversationId`, `parentTaskId`, `title`, `status`, `progress` |
| Interaction | 必须由用户处理的结构化请求 | `id`, `taskId`, `type`, `status`, `payload`, `expiresAt` |
| Event | 所有状态变化的事实记录 | `id`, `sequence`, `type`, `subject`, `payload`, `occurredAt` |

### 6.2 任务状态机

```mermaid
stateDiagram-v2
  [*] --> queued
  queued --> running: Agent 接受 / 用户开始
  running --> waiting_for_human: 发起 Interaction
  waiting_for_human --> running: 用户响应
  running --> succeeded: 完成
  running --> failed: 失败
  queued --> cancelled: 取消
  running --> cancelled: 取消确认 / Agent 停止
  waiting_for_human --> cancelled: 用户取消
  succeeded --> [*]
  failed --> [*]
  cancelled --> [*]
```

状态定义：

- `queued`：任务已创建、尚未由 Agent 接受。
- `running`：Agent 正在执行，允许不断上报进度与日志摘要。
- `waiting_for_human`：工作被一个未处理的 Interaction 阻塞，应进入收件箱并通知用户。
- `succeeded` / `failed` / `cancelled`：终态；任务和完整事件历史可查。

## 7. 关键交互

### 7.1 首次连接 Agent

1. 用户在「Agent」页点击“连接我的 Agent”。
2. 选择 Adapter 类型（首版：Generic SDK；后续可有 OpenClaw 预设）。
3. 服务端生成一次性配对码和安装命令；配对码有效期 10 分钟。
4. 用户在 Agent 所在机器运行 Adapter，Adapter 用配对码建立出站 WebSocket。
5. 服务端显示 Agent 名称、版本、可用能力与在线状态；用户确认命名后完成绑定。

**体验要求：** 不要求用户开放入站端口；Agent 主动连接中转服务。连接失败时必须显示可复制的诊断码及下一步建议。

### 7.2 发起与跟进一个任务

1. 用户在会话底部输入自然语言需求，可勾选“作为任务跟踪”。
2. 系统先创建 `task.created`，再把文本作为 `message.created` 发送给目标 Agent。
3. Agent 接受后上报 `task.status_changed: running`，可持续上报 0–100 的进度和一句简短状态。
4. 用户可在会话内看简要进度，也可打开任务详情查看子任务、产物和事件时间线。
5. Agent 完成、失败或需要人类处理时，状态即时同步到任务列表和收件箱。

### 7.3 Agent 请求人类决策

交互卡片的结构为：**为什么需要你 → 影响是什么 → 你能做什么 → 详细信息（折叠）**。

| 卡片类型 | 示例 | 必填交互 |
|---|---|---|
| `approval` | “将执行生产数据库迁移” | 批准 / 拒绝；可选备注 |
| `choice` | “部署区域选择” | 2–5 个选项；可标注推荐项 |
| `input` | “请提供测试环境 URL” | 文本输入、格式校验 |
| `review` | “请检查生成的变更计划” | 展示内容或附件；批准 / 要求修改 |

响应后，卡片变为只读并保留“谁在何时作出什么决定”；对应事件发送回 Agent，任务恢复 `running`。

### 7.4 Agent 失联与恢复

- WebSocket 心跳间隔 25 秒；连续 2 次未收到心跳标记为 `offline`。
- 运行中任务不立刻标为失败，而显示“Agent 连接中断”，并保留最后心跳时间。
- Adapter 重连后携带最后确认的 `sequence`；服务端补发缺失下行事件。
- 若 Agent 在配置的宽限期（默认 15 分钟）后仍未恢复，任务改为 `failed`，原因是 `agent_unreachable`。

## 8. 页面与组件规格

### 8.1 桌面端主界面

```text
┌──────────────┬───────────────────────────────────────┬──────────────────────┐
│ 工作区       │ 会话：网站重构                         │ 任务详情             │
│              │                                       │                      │
│ 收件箱  (2)  │ [用户] 分析现有页面并提交改进建议       │ ● 正在执行  60%      │
│ 会话         │                                       │ “整理组件依赖”        │
│ 任务         │ [Agent] 已建立任务计划，正在扫描仓库… │                      │
│ Agent        │                                       │ 子任务               │
│              │ ┌───────────────────────────────────┐ │ ✓ 扫描仓库           │
│              │ │ 需要你的确认                       │ │ ● 整理组件依赖        │
│              │ │ 允许安装 3 个开发依赖？            │ │ ○ 输出迁移方案        │
│              │ │ [查看变更] [拒绝] [允许]           │ │                      │
│              │ └───────────────────────────────────┘ │ 事件时间线            │
│              │                                       │                      │
│              │  输入消息…                    [发送] │                      │
└──────────────┴───────────────────────────────────────┴──────────────────────┘
```

**响应式规则：** 宽度小于 900px 时隐藏右侧详情为抽屉；小于 640px 时侧栏收起，顶部保留收件箱未读数和 Agent 在线指示。

### 8.2 首版设计令牌

```css
:root {
  --surface-canvas: #f7f8fa;
  --surface-default: #ffffff;
  --surface-subtle: #f1f3f5;
  --text-primary: #1b1f24;
  --text-secondary: #59636e;
  --border-subtle: #d8dee4;
  --brand: #356ae6;
  --status-running: #356ae6;
  --status-waiting: #b7791f;
  --status-success: #168a5b;
  --status-danger: #c93c37;
  --radius-card: 12px;
  --radius-control: 8px;
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-6: 24px;
}
```

可访问性底线：正文与背景对比度至少 4.5:1；不只依靠颜色表达状态；所有卡片操作支持键盘焦点、Enter/Space 触发及明确的加载/提交结果。

## 9. 系统架构

```mermaid
flowchart LR
  subgraph Clients[用户客户端]
    WEB[响应式 Web]
    MOBILE[未来移动端]
  end

  subgraph Cloud[LineUp 中转服务]
    API[HTTPS API]
    RT[Realtime Gateway\nWebSocket]
    AUTH[身份与设备绑定]
    APP[协作应用服务]
    DB[(PostgreSQL)]
    BUS[(Event / Job Queue)]
    PUSH[通知服务]
  end

  subgraph UserEnv[用户的本机或服务器]
    ADAPTER[LineUp Adapter]
    RUNTIME[OpenClaw / Codex /\nHermes / 自定义 Agent]
  end

  WEB <-- HTTPS + WS --> API
  WEB <-- HTTPS + WS --> RT
  MOBILE <-- HTTPS + WS --> API
  MOBILE <-- HTTPS + WS --> RT
  API --> AUTH
  API --> APP
  RT --> APP
  APP --> DB
  APP --> BUS
  BUS --> PUSH
  ADAPTER <-- 出站 WSS --> RT
  ADAPTER <--> RUNTIME
```

### 9.1 推荐实现取舍

| 层 | 首版选择 | 原因 |
|---|---|---|
| Web | Next.js + TypeScript | 同时覆盖 Web、响应式移动体验与后续 BFF 需求 |
| 服务端 | TypeScript（Fastify/NestJS 任选其一） | 与 SDK 共享类型和校验器，迭代快 |
| 实时连接 | 标准 WebSocket | 对 Agent 和客户端都简单；协议可公开 |
| 数据 | PostgreSQL | 可靠存储、查询任务，JSONB 容纳扩展事件 |
| 临时事件/队列 | Redis Streams 或 BullMQ | 处理通知、投递重试和长连接广播 |
| Adapter SDK | TypeScript 首发 | 覆盖主要 Node Agent；协议保持语言无关 |
| 鉴权 | 短期 Access Token + Agent 配对 Token | 安全模型足够简单，后续可演进 OAuth/设备授权 |

**关键边界：** 业务服务不执行 Agent 的工具调用，也不存放模型密钥。它仅路由已认证事件、持久化协作状态，并向用户端可靠同步。

## 10. 最小事件协议（LAP/0.1）

所有 WebSocket 帧使用统一 envelope。`payload` 按 `type` 做 schema 校验；未知字段容忍但记录，未知事件类型忽略并保留兼容性告警。

```ts
type Envelope<T = unknown> = {
  id: string;                 // UUID，幂等键
  type: string;               // 如 task.status_changed
  version: '0.1';
  occurredAt: string;         // ISO 8601 UTC
  workspaceId: string;
  conversationId?: string;
  taskId?: string;
  sequence?: number;          // 服务端下行事件全局递增序号
  correlationId?: string;     // 串联一次用户请求和后续事件
  payload: T;
};
```

### 10.1 用户端 → 服务端

| 事件 | 说明 | 关键 payload |
|---|---|---|
| `message.create` | 发消息 | `content`, `targetAgentId` |
| `task.create` | 创建受跟踪任务 | `title`, `description`, `targetAgentId` |
| `interaction.respond` | 回应卡片 | `interactionId`, `response` |
| `task.cancel_requested` | 请求取消 | `reason?` |

### 10.2 Agent → 服务端

| 事件 | 说明 | 关键 payload |
|---|---|---|
| `agent.hello` | Adapter 握手与能力声明 | `agentVersion`, `runtime`, `capabilities`, `lastSequence?` |
| `message.create` | Agent 文本或富内容 | `content`, `blocks?` |
| `task.accepted` | 接受任务 | `taskId` |
| `task.status_changed` | 上报状态或进度 | `status`, `progress?`, `summary?`, `error?` |
| `task.child_created` | 仅用于展示的子任务 | `parentTaskId`, `title`, `status` |
| `interaction.requested` | 请求用户输入或确认 | `interaction` |
| `artifact.created` | 上报链接/文件/结果 | `name`, `url`, `mimeType?`, `summary?` |

### 10.3 服务端 → Agent

| 事件 | 说明 |
|---|---|
| `task.assigned` | 新任务及所属会话上下文 |
| `message.delivered` | 用户追加消息 |
| `interaction.resolved` | 用户的结构化回答 |
| `task.cancel_requested` | 用户请求停止 |
| `system.resync_required` | Adapter 无法从断点恢复，需拉取或重建状态 |

### 10.4 Interaction 示例

```json
{
  "type": "interaction.requested",
  "version": "0.1",
  "id": "evt_01J...",
  "occurredAt": "2026-07-24T12:00:00Z",
  "workspaceId": "ws_01J...",
  "conversationId": "conv_01J...",
  "taskId": "task_01J...",
  "payload": {
    "interaction": {
      "id": "int_01J...",
      "type": "approval",
      "title": "允许执行数据库迁移吗？",
      "description": "此操作会在 production 执行 3 个已审阅的迁移文件。",
      "risk": "high",
      "options": [
        { "id": "approve", "label": "允许执行", "style": "primary" },
        { "id": "reject", "label": "拒绝", "style": "danger" }
      ],
      "details": { "migrationCount": 3, "environment": "production" },
      "expiresAt": "2026-07-25T12:00:00Z"
    }
  }
}
```

## 11. 安全与可靠性基线

- Agent 仅建立**出站** TLS WebSocket；用户无需暴露本机端口。
- 配对码为一次性、短有效期且仅用于兑换 Agent 凭据；凭据可单独撤销。
- 每一个 Agent 凭据限定到单 Workspace 和 Agent 身份，禁止跨工作区投递。
- 写入事件必须使用 envelope `id` 去重；客户端与 Adapter 应能安全重发。
- 明确区分“取消请求”与“已取消”：只有 Agent 确认停止或超时策略生效后任务才进入终态。
- 记录审批摘要、响应人、时间和关联任务；不要默认把原始敏感输入发到通知正文。
- 默认保留最小化运行日志；敏感字段可在 Adapter 侧脱敏后再上报。

## 12. 验证指标与首轮测试

### 12.1 产品假设

如果用户能在离开 Agent 所在机器后，仍清楚掌握任务状态并在 30 秒内完成关键介入，那么他们会愿意把更多长期任务交给已连接的 Agent。

### 12.2 成功指标

| 指标 | 首轮目标 |
|---|---|
| 成功绑定一个 Agent 的比例 | ≥ 80% |
| 从收到“等待用户”通知到完成处理的中位时间 | < 60 秒 |
| 用户判断任务当前状态的正确率 | ≥ 90% |
| 消息/状态在在线情况下端到端可见延迟 P95 | < 1 秒 |
| Agent 重连后未丢失的待处理事件比例 | 100% |
| 试用用户愿意在下一周继续连接 Agent 的比例 | ≥ 60% |

### 12.3 5 人可用性测试

找 3 位已有 Agent 使用经验的用户与 2 位刚接触长任务 Agent 的用户；每人完成以下任务：

1. 连接一个模拟 Agent，说明它是否在线。
2. 创建“整理项目依赖并产出计划”的任务，定位它的当前进度。
3. 在不打开日志的前提下处理一个高风险批准请求。
4. 让 Agent 断线并恢复，判断任务是否需要重新开始。

记录完成率、完成时间、误操作、口头疑问和 SUS 问卷。任何导致用户错误批准高风险行为的问题均视为 P0，必须在公开测试前解决。

## 13. 实施顺序与分工建议

### 13.1 三个迭代

| 迭代 | 目标 | 可演示结果 |
|---|---|---|
| I1：连通性 | 账户/工作区、配对、WebSocket、事件存储 | 一个模拟 Agent 在线，能发收消息 |
| I2：协作闭环 | 会话、任务状态、Interaction 卡片、收件箱 | 用户能创建任务、远程批准、看到 Agent 继续与完成 |
| I3：可靠性 | 重连补偿、通知、审计、示例 Adapter | Agent 断线恢复后协作连续，能供首批用户试用 |

### 13.2 初始分工（两人）

| 负责人 | 主责 | I1–I3 输出 |
|---|---|---|
| Stephen | 中转服务与协议 | 数据模型、事件路由、WebSocket、鉴权、Adapter SDK、模拟 Agent |
| 爱德姆 | 产品交互与客户端 | 信息架构、Web 交互、任务/确认卡片、连接引导、可用性测试与反馈整理 |

共同决策：协议版本、风险确认策略、首个真实 Agent Adapter 的接入优先级。每周用一段真实的 Agent 长任务进行端到端验收，而不是只测 API。

## 14. 待决策清单

这些决策会改变实现范围，应在开始 I1 前由两位创始人确认：

1. **首个真实接入对象：** OpenClaw 优先，还是先做 Generic SDK + 模拟 Agent？建议先后者，避免因特定框架阻塞核心验证。
2. **首批部署模式：** 托管中转服务，还是可自托管？建议先托管开发环境，协议与部署保持可自托管。
3. **账号范围：** 仅个人 Workspace，还是首版就允许邀请第二位成员？建议数据模型支持成员，界面先围绕个人。
4. **通知通道：** 浏览器推送、邮件、Telegram/飞书任选一条。建议浏览器通知优先，集成型 Channel 放在 I3 后评估。
5. **产品命名：** “LineUp Agents”暂作工作名；上线前需检查域名、商标及中文名称可用性。

## 15. Definition of Done：MVP 演示

一次合格的演示应从零完成以下闭环：

1. 用户注册并创建一个 Workspace。
2. 用户通过一次性配对码连接运行在另一台机器上的模拟或真实 Agent。
3. 用户创建一个任务，关闭浏览器后再打开，任务与会话仍完整存在。
4. Agent 上报至少两个进度变化，并创建一个子任务。
5. Agent 发起一个 `approval` 请求，用户在收件箱处理后，Agent 收到响应并继续执行。
6. 断开 Adapter，界面在合理时间内显示失联；重连后不重复执行或丢失审批响应。
7. Agent 产出一条结果消息和一个 Artifact，任务成为 `succeeded`，全部过程在事件时间线中可追溯。

完成这套闭环后，再根据试用反馈决定是优先扩充移动端、增加框架 Adapter，还是深化任务协作能力。