初始化 agent_ops 文档治理体系

2026-08-07 16:56:51 +08:00
commit 10840909ab
75 changed files with 15750 additions and 0 deletions
@@ -0,0 +1,441 @@
+# 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，还是深化任务协作能力。