lineup/agent_ops

Fork 0

Files

T

kyugao 10840909ab 初始化 agent_ops 文档治理体系

2026-08-07 16:56:51 +08:00

21 KiB

Raw Permalink Blame History

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 首批用户

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

3.3 北极星任务

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

4. 产品原则

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

工作区
├── 收件箱
│   ├── 等待我处理
│   ├── 失败 / 需要关注
│   └── 最近完成
├── 会话
│   └── 一个会话对应人与一个或多个 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 任务状态机

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

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

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

7.2 发起与跟进一个任务

用户在会话底部输入自然语言需求，可勾选“作为任务跟踪”。
系统先创建 task.created，再把文本作为 message.created 发送给目标 Agent。
Agent 接受后上报 task.status_changed: running，可持续上报 0–100 的进度和一句简短状态。
用户可在会话内看简要进度，也可打开任务详情查看子任务、产物和事件时间线。
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 桌面端主界面

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

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

8.2 首版设计令牌

: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. 系统架构

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 校验；未知字段容忍但记录，未知事件类型忽略并保留兼容性告警。

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 示例

{
  "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 的用户；每人完成以下任务：

连接一个模拟 Agent，说明它是否在线。
创建“整理项目依赖并产出计划”的任务，定位它的当前进度。
在不打开日志的前提下处理一个高风险批准请求。
让 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 前由两位创始人确认：

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

15. Definition of Done：MVP 演示

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

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

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

21 KiB Raw Permalink Blame History Unescape Escape