From 802d8e2adf9a7c2607c6a9fbce3d1039ec574a32 Mon Sep 17 00:00:00 2001 From: Xin Wang Date: Wed, 28 Oct 2026 16:33:02 +0800 Subject: [PATCH] docs: plan computer use and A2A task backends --- README.md | 1 + docs-developer/computer-a2a-plan.mdx | 95 ++++++++++++++++++++++++++++ docs-developer/development-plan.mdx | 6 ++ docs-developer/docs.json | 2 +- 4 files changed, 103 insertions(+), 1 deletion(-) create mode 100644 docs-developer/computer-a2a-plan.mdx diff --git a/README.md b/README.md index a63eac3..42df13f 100644 --- a/README.md +++ b/README.md @@ -55,3 +55,4 @@ docker compose up -d - [能力状态与收敛建议](docs-user/status.mdx)：已实现、未实现及建议移除的占位内容。 - [开发者快速开始](docs-developer/index.mdx)、[Realtime 协议](docs-developer/realtime-protocol.mdx)、[Responses 接口](docs-developer/responses-api.mdx)：接口细节与契约。 - [后端说明](backend/README.md)：实现和本地开发；[开发计划](docs-developer/development-plan.mdx)：生产化待办。 +- [Computer Use 与 A2A 规划](docs-developer/computer-a2a-plan.mdx)：电脑环境、远程 Agent 后端、网页接管与分阶段验收（尚未实现）。 diff --git a/docs-developer/computer-a2a-plan.mdx b/docs-developer/computer-a2a-plan.mdx new file mode 100644 index 0000000..4d4ea9b --- /dev/null +++ b/docs-developer/computer-a2a-plan.mdx @@ -0,0 +1,95 @@ +--- +title: Computer Use 与 A2A 任务后端规划 +description: 以独立电脑环境验证任务闭环，再通过 A2A 接入远程 Agent。 +--- + +# Computer Use 与 A2A 任务后端规划 + +记录日期：2026-10-28。状态：已确认建设方向，尚未实现、部署或完成真实服务验收。本文不改变现有接口承诺，也不表示已新增任务后端类型。 + +## 目标与选型 + +在现有语音助手中提供一台可观看、可接管的 AI 电脑：用户通过语音提出任务，后台 Agent 操作浏览器、文件或画板，网页展示同一桌面的执行过程，最终返回成果并由 Speaker 播报。 + +电脑运行环境首选 [AIO Sandbox](https://github.com/agent-infra/sandbox)。它提供浏览器、Shell、文件与桌面操作接口及 VNC 入口。模型和任务推理循环由独立 Computer Agent 提供，AIO 本身不负责理解和完成用户目标。采用前固定镜像、SDK 和 API 版本，并验证所选版本的桌面能力；不混用最新文档与旧镜像。 + +增加 A2A 作为可选远程 Agent 后端。首版仅实现客户端适配，使用[官方 Python SDK](https://github.com/a2aproject/a2a-python)，明确支持的协议版本。A2A 用于委派任务、交换进度、补充输入与成果；桌面显示和接管使用独立接口。 + +## 架构与现有能力复用 + +```text +Speaker / Pipecat 语音链路 + → TaskService：记录、配置快照、进度、取消、结果 + → A2AExecutor：远程任务协议适配 + → Computer Agent：多模态观察与行动循环 + → AIO Sandbox：桌面、浏览器、文件、Shell + → 网页电脑面板：noVNC 观看与接管 +``` + +- 保留现有 reasoner、opencode，新增 a2a 资源类型；首版仍仅提示词 Pipeline，一个助手最多绑定一个任务后端。 +- 复用 `prepare/run/cancel/snapshot/send_input` 执行器边界、任务卡片和 Speaker 通知，尽量不修改 Pipecat 框架。 +- ComputerUseExecutor 可用于早期直连验证；它是过渡实现，暂不承诺增加长期公开的 computer 资源类型。最终远程 Computer Agent 优先通过 a2a 接入。 +- Pipecat Jobs 负责平台侧任务生命周期，远端 Agent 负责内部模型循环和恢复；平台断线重连只观察已存在任务，不重新执行远端目标。 +- 暂不引入 Deep Agents 或 LangGraph。只有真实任务暴露长上下文、技能加载或恢复需求后，再通过对照试验决定。 + +当前 MCP 客户端会省略图片返回，不能直接把截图工具接入 Reasoner 就声称支持 Computer Use。首版由 Computer Agent 直接处理截图与模型消息；以后统一多模态工具返回时，另行设计图片大小、历史裁剪和模型兼容性。 + +## 阶段一：真实电脑操作闭环 + +- [ ] 在独立环境部署一台固定 Linux 电脑，验证截图、点击、输入、拖拽、文件保存及桌面显示。 +- [ ] 实现最小 Computer Agent，设置动作次数、执行时限及截图历史上限，记录动作与失败原因。 +- [ ] 增加网页电脑面板、暂停、接管和交还操作，界面遵循 `frontend/DESIGN.md`。 +- [ ] 接管时停止下发 AI 动作并等待在途动作结束；交还后重新截图，禁止根据旧画面继续操作。 +- [ ] 为电脑会话分配独立标识和工作目录，明确销毁环境与成果保留规则。 +- [ ] 桌面和操作 API 通过服务端鉴权代理访问，远端密钥不下发浏览器；首版保持单租户、单电脑，不挂载宿主敏感目录。 + +验收任务：语音要求“打开画板，画一个红色三角形并保存 PNG”，网页看到全过程；中途能接管再交还；最终能下载实际保存的文件并听到结果播报。连续曲线需要时增加整条笔画路径工具，不让每个像素移动都触发一次模型调用。 + +该阶段使用真实模型和真实桌面；模拟测试单独标记，不代替端到端验收。 + +## 阶段二：A2A 通用远程后端 + +- [ ] 新增 a2a 资源配置：服务/Agent Card 地址、服务端凭据、时限和能力检查；接入现有启用、绑定与配置快照规则。 +- [ ] 读取 Agent Card，校验协议版本、传输与流式能力；首版只支持一种明确的 HTTP 绑定，不同时实现所有传输。 +- [ ] 实现提交、流式状态/成果更新、查询、取消、补充回答；无流式能力时使用有界轮询。 +- [ ] 持久化本地任务与远端 taskId/contextId 的映射，支持进程重启后查询远端已有任务。 +- [ ] 支持文本和文件成果；定义文件大小、访问鉴权、保留时间及下载失败行为。 +- [ ] 将阶段一的 Computer Agent 包装为 A2A 服务，并用独立测试服务验证适配器不依赖电脑专有字段。 + +必须保留的语义： + +| 远端行为 | 平台处理 | +| --- | --- | +| 直接返回 Message | 按直接响应处理，不伪造远端异步任务句柄或仅据文字判断执行成功 | +| 返回 Task | 保存远端标识并跟踪状态，提交回执不代表完成 | +| input-required | 映射待输入；简单问题可由 Speaker 追问，复杂输入由网页处理 | +| auth-required | 独立标识认证需求，进入网页流程，不当作普通问答或播报凭据；不支持的认证方式明确提示 | +| completed | 映射“远端报告完成”，不宣称平台独立验证成功 | +| rejected / failed | 映射失败并保留远端原始状态与原因 | +| 取消请求已发送 | 保留取消中，收到远端确认后才标记已取消；不代表回滚副作用 | +| 断线或提交结果不确定 | 查询已知句柄；没有可靠句柄时标记未知，不盲目重新提交 | + +验收覆盖：直接消息、异步完成、拒绝、失败、输入续跑、认证需求、取消被拒、流式断开、进程重启、文件成果和重复提交。模拟服务覆盖协议边界，真实 Computer Agent 验证完整语音到成果链路。 + +## 阶段三：电脑体验与可靠性增强 + +- [ ] 定义版本化的电脑会话扩展，包含 computerSessionId、受控查看入口和成果引用；明确这不是 A2A 标准字段。 +- [ ] 定义接管/交还控制权状态机及桌面断线行为；A2A 任务继续运行与桌面查看连接分别管理。 +- [ ] 根据实际需求增加环境创建/回收、资源限额、空闲超时、录屏和成果预览。 +- [ ] 用真实任务比较成功率、模型调用数、费用、耗时、取消延迟和恢复行为，再决定扩展并发或更换 harness。 + +## 范围与优先级 + +默认顺序为阶段一 → 阶段二 → 阶段三。若出现明确的第三方 A2A 接入需求，可先做阶段二的通用客户端，再接电脑服务。 + +首版不做 Agent 市场、自动发现、动态多 Agent 路由、完整 A2A Server 对外开放、多租户桌面编排、任意操作系统支持；不扩大 Workflow/Realtime 的任务委派范围。 + +本方向与生产化计划并列推进，不改变标准契约、可观测性、运行可靠性和质量门禁的既有顺序。现有 ARQ 迁移计划面向知识库、分析、Webhook 等后台作业，不意味着自动重放远端 A2A 任务或迁移实时媒体链路。 + +## 参考资料 + +- [AIO 桌面操作接口](https://sandbox.agent-infra.com/daemon/basic/display)：能力探测、截图、动作、录屏与桌面查看。 +- [A2A 官方规范](https://github.com/a2aproject/A2A/blob/main/docs/specification.md)：消息、任务生命周期、流式成果与取消语义。 +- [现有任务后端说明](/prompt-task-backends)：已实现能力与当前边界。 + +以上外部资料是选型依据，实施时须按锁定版本再次核对；本规划不构成真实服务兼容性验证。 diff --git a/docs-developer/development-plan.mdx b/docs-developer/development-plan.mdx index 27cb252..92664ad 100644 --- a/docs-developer/development-plan.mdx +++ b/docs-developer/development-plan.mdx @@ -319,6 +319,12 @@ Realtime Pipeline 与媒体连接绑定，继续保留在 API 进程内，不迁 ## 推荐交付批次 +### 配套产品方向：Computer Use 与 A2A + +新增[Computer Use 与 A2A 任务后端规划](/computer-a2a-plan)。该方向尚未实现，复用现有 Speaker、TaskService 和任务资源体系，以 AIO Sandbox 为电脑环境首选，并增加可选的 A2A 远程 Agent 后端。 + +交付顺序：先验证真实电脑操作、网页观看与接管，再完成 A2A 通用客户端和 Computer Agent 接入，最后按真实需求扩展会话管理与可靠性。具体范围、状态语义和验收标准以专项规划为准；不改变本页生产化里程碑顺序。 + ### 批次 A：契约与工程入口 - 修复统一测试命令； diff --git a/docs-developer/docs.json b/docs-developer/docs.json index 423c9f4..cee8f4f 100644 --- a/docs-developer/docs.json +++ b/docs-developer/docs.json @@ -50,7 +50,7 @@ }, { "group": "开发与质量", - "pages": ["development-plan"] + "pages": ["development-plan", "computer-a2a-plan"] } ] }