yaoyao/docs/agent-platform-implementation.md

多 Agent、电脑环境与 macOS App 落地记录

目标：完成本线程确认的整体方案。macOS App、Web、执行节点和电脑服务源码共同维护在 hermes-yaoyao；移动客户端继续使用各自仓库。当前工作分支为 feat/bot-agent-teams。

本文用于保留完整范围和验收证据，不以某个局部功能完成代替整体完成。未经证据核对的项目保持待完成。

完整交付范围

桌面与服务

• macOS App 复用 Vue 界面，打包所需服务运行时，打开 App 自动启动或连接正确的服务。
• 单实例、数据目录独占、身份/版本验证；兼容已有服务，不误停外部实例。
• 关闭窗口保留任务、菜单栏恢复窗口、明确退出时安全停止自己管理的进程。
• Hermes 检测与托管、服务启动进度、可恢复错误、日志、崩溃恢复与睡眠唤醒核对。
• 可选后台常驻与开机启动；正常安装不强制开启。
• 本机凭据保护、受限桌面通信、受信任页面与外部页面隔离。
• arm64 App/安装包、签名完整性、更新与回退流程；公证和发布状态独立核实。

团队执行

• 基础自主创建 Agent、团队、启动和查询任务，以及按轮次授权（ac62d07）。
• 持久 Agent、临时助手、团队角色分离；记录创建来源与可恢复生命周期。
• 子任务负责人、依赖、验收条件、产物归属、结构化分派和计划调整。
• 成功/失败结果自动回到原会话，忙碌时排队；归档、停止、撤权后不复活旧任务。
• 区分执行结束与目标完成；复核、返工、等待用户、受阻状态可追踪。
• 持久投递与去重、重启修复、自动唤醒/递归/配额限制。
• Agent、桌面和共享写入资源的并发限制；取消只影响所属任务。

执行节点与电脑

• Hermes 侧 Runner、版本/能力协商、受控工具传输，覆盖默认 Docker 部署与远程节点。
• 权限取账号、Agent、任务、节点、电脑能力的交集；模型不能指定真实调用身份或凭据。
• 电脑 Provider 统一接口与离线一致性测试；Docker、Podman和远程节点支持。
• 独立电脑环境与受控 Hermes Worker；终端、文件、浏览器和子进程不会退回宿主执行。
• 按需启动、资源上限、持久工作区、浏览器资料、产物导出和空闲清理。
• 画面查看/控制分离、人工接管/交还、递增租约版本、旧请求拒绝。
• 环境重建、数据恢复、更新维护、在途操作不确定性处理。
• 可选可信团队共享环境、多桌面、独立浏览器资料及一致保存。
• 扩展提供商适配边界，能力不足时明确降级，不伪装为同等隔离。

跨端与验收

• Web、macOS、iOS、Android 共享权限/状态/事件协议，按平台提供入口和安全降级。
• 原始聊天展示回传结果、团队展示分派与产物、电脑面板支持查看与接管。
• 隔离环境下完成启动、重启、撤权、重复请求、并发、停止竞态和数据恢复测试。
• 真实打包 App 及真实电脑环境验收；脚本模型与真实模型证据分别记录。
• 所有实现以中文 Git 提交；正式服务部署、安装、公证和发布的状态明确区分。

实施顺序

1. 桌面托管与服务身份/生命周期基础。
2. 持久团队分派、结果回传与资源调度。
3. 执行节点及隔离电脑 Provider、Hermes Worker。
4. 共享桌面、跨端、后台服务、更新恢复及最终交付验收。

当前证据

• 起点：Web ac62d07，iOS 5908a2b；此前自主组队分支的验收见 docs/bot-agent-teams.md。
• 桌面基础：开发启动与打包后 App 均通过 desktop/lifecycle.test.mjs，实际测试服务启动、窗口关闭后存活、强制结束服务后的恢复、外部连接不误停服务、退出清理。
• 2026-09-08 首个桌面快照：arm64 App，开发证书签名；严格签名验证和 DMG 校验通过。DMG SHA-256：611995fea080455da3a87a561cb5a7465a70e7437a91b948d45ce346822b0095。这是阶段产物，尚未公证、发布或替换正式服务。
• 桌面基础对应服务全量测试 652 项通过；任务协调器正在继续实现，不能据此宣称后续任务或 VM 已完成。
• 任务协调阶段：类型检查、666 项全量测试及真实 Hermes 隔离协议验收通过。真实协议验证包含持久成员、组队、具体成员分派、成员不继承组队工具、管理员验收、目标完成、原会话结果及双管理员并发工具隔离。
• Web 验证任务状态、结果跳转和独立文字/附件草稿；iOS 验证任务进度、停止和结构化任务跳转；Android API 31 模拟器验证对应工作流。测试日志在本轮工具记录中，后续完整交付仍需重新核对最终代码。
• 下一阶段必须继续执行节点、受控 Worker、VM、临时助手、资源租约、文件/产物搬运、后台常驻、更新回退等未完成项。当前 App 安装包是桌面基础快照，不是最终完整平台交付。
• Runner 阶段：新增独立执行节点、管理员注册/配置下载/停用入口，以及打包 CLI。最终类型检查和 680 项全量测试通过（1 项真实协议测试按需跳过）；独立打包 Runner 的 13 项协议/CLI 测试通过；浏览器注册流程通过并核对桌面/窄屏截图。
• 单独启用 HERMES_TEAM_RUNNER=1 后，真实 Hermes 隔离协议验收通过，包含原生工具创建成员、组队、结构化分派、验收、完成、结果回传和双管理员工具隔离。执行细节和当前限制见 docs/runner.md。这是传输层验收，尚非 VM 或真实模型自主决策验收。
• 桌面 Runner 阶段：App 新增原生配置导入、系统加密存储、私有进程传参、自动启动与有界重连。开发 App 的 4 项生命周期/凭据测试通过；打包 arm64 App 的真实生命周期测试再次通过，覆盖配置导入、服务崩溃后的重新连接、窗口关闭保留连接、退出清理与再次打开自动连接。
• 此次打包验收使用 /tmp/yaoyao-runner-package-130917f/mac-arm64/夭夭.app，为临时 ad-hoc 签名测试包，严格签名检查通过。未替换 desktop-release 中较早的开发证书快照，也未安装、部署、公证或发布。服务全量 680 项通过；配置与 Runner 定向 23 项通过。
• 电脑 Provider 基础：实现私有容器、归属与约束校验、持久工作目录、guest 执行和取消时的停止确认。15 项 Docker/Podman 离线测试通过；真实 Docker 无网络环境的创建、画面读取、持久文件重建和取消写入验收通过，截图已核对，测试容器已清理。详见 docs/computer-provider.md。尚未接入任务资源租约和受控 Worker，VM 功能仍未完成。
• 电脑租约基础：SQLite 保存持有者、递增代次、期限与停止状态；配额在启动前预占，未确认停止的资源保持占用，取消后退休旧容器 ID。资源池 6 项测试及接入资源池后的真实 Docker 生命周期测试通过。仍未将该资源池接入 Bot 任务和受控 Worker。

• 当前源码验证：类型检查、711 项全量测试通过；2 项真实环境测试默认按需跳过，已分别执行过真实 Hermes Runner 协议和真实 Docker 电脑/租约验收。所有电脑验收容器均已清理。整体目标仍在进行，下一步是受控 Worker、联网代理及任务/权限接入，随后完成跨端电脑界面与其余交付项。

• 受控 Worker 阶段：Bot 执行方式可选择隔离电脑，已接入真实 Hermes 模型循环、任务授权与持久电脑租约。模型循环在 Runner 侧，工具和工具子进程在 guest 内；凭据不传入电脑环境。详见 docs/computer-worker.md。

• 完整 Runner 二进制验收经过控制面 → Runner → Hermes Worker → 真实 Docker；验证 UID 1000 执行、配置中的 cwd、同一 Agent 更新 cwd 后继续执行、宿主原生工具拒绝、团队创建、原会话结果、文件附件下载及多块二进制导出。模型服务使用确定的测试响应，没有调用付费模型。

• 增加执行节点能力协商，旧 Runner 不支持隔离时明确拒绝；未提交的资源不足任务保留排队，恢复后只提交一次。历史消息记录原执行环境，后续改变 Agent 设置也不会把原隔离消息的路径交给宿主读取。

• 产物校验后保留原作者/消息归属，支持原有下载接口、转交与任务复核附件。类型检查和 718 项测试通过；4 项真实环境测试默认跳过，Worker 的真实环境与打包 Runner 版本已单独执行。

• 全目标仍未完成：优先继续受控联网、镜像准备/升级、临时助手、屏幕查看与人工接管、共享环境、移动端入口及后台/更新交付项。不能将 Worker 链路完成视作完整平台交付。

• 本阶段最终检查：类型检查与 719 项全量测试通过，4 项真实环境测试默认按需跳过；打包 Runner 的真实 Worker 测试 2 项通过，包含原生宿主工具拒绝、分块二进制产物、下载、cwd 变更和取消延迟写入。Web 4 项入口测试及桌面 4 项生命周期测试通过；窄屏弹窗截图已核对。测试电脑容器全部清理。

• 停止与撤权分开处理：撤销执行授权不阻断已绑定任务的清理，只允许清理原会话；清理通道不能提交新工作。电脑恢复首先核对并停止原持有者，旧容器身份不会被新任务复用。

• 公网代理阶段：保持电脑无外部网卡，通过专属进程管道建立公网 80/443 连接，拒绝保留地址、内网、宿主网卡地址及混合 DNS 结果。支持命令环境变量与浏览器代理策略。真实 Docker 的 curl/Firefox HTTPS、截图、宿主拒绝和关停测试通过；完整打包 Runner 的 Worker 公网访问测试通过。详见 docs/computer-network.md。

• 联网阶段最终验证：类型检查和 756 项全量测试通过，5 项真实环境测试默认跳过；地址/代理与 BFF 定向 50 项通过，Web 4 项流程测试通过。真实 Firefox 公网页面截图已核对；公网 Worker 的打包 Runner 验收通过。电脑验收容器全部清理，完整目标仍未完成。

• 临时助手阶段：新增创建并分派任务的工具，助手没有单聊、不是永久团队成员，只能执行所属目标的当前阶段；固化隔离模式，禁止提权和跨任务使用。目标结束后退役，按原 Runner 进行持久清理重试；清理只删除助手执行数据，保留控制面产物。详见 docs/task-helpers.md。

• Web、iOS、Android 已加入临时助手标识和持久成员选择过滤。iOS 27 项 Workspace 测试通过；Android 模型测试和 Debug Kotlin 编译通过。真实 Hermes Worker / Docker 的临时助手执行和退役清理验收已通过。

• 临时助手最终验收：服务端类型检查与 759 项全量测试通过，5 项真实环境测试默认跳过；打包 Runner 的真实临时助手完成/清理验收通过；Web 4 项流程测试和临时助手标识截图通过。iOS 27 项 Workspace 测试、Android 31 项模型测试和 Debug Kotlin 编译通过。测试容器全部清理。其余镜像管理、电脑接管、共享环境和桌面交付项继续推进。

• 电脑控制阶段：Web、macOS、iOS、Android 入口已接入只读画面与独立人工控制凭据；暂停模型、等待在途工具、同一电脑递增代次转交、交还后继续原任务。真实 Docker 终端点击/输入/文件证明和原任务续跑通过。详见 docs/computer-control.md。跨端原生视觉、镜像管理、共享环境和最终桌面交付仍待完成。

• 电脑控制源码检查：类型检查和 Web 构建通过，762 项全量测试通过，5 项浏览器流程通过，iOS 28 项 Workspace 测试通过，Android 模型测试和 Kotlin 编译通过。窄屏电脑面板截图已核对。本轮验收容器全部清理，正式 Web 服务 PID 28292 未改变。

• 镜像与维护阶段：本仓库提供固定来源的镜像配方、健康/截图验证、校验归档导入导出、停止后的工作区备份/恢复/重建及内容恢复中断后的回退。新镜像不会自动替换运行环境；保留旧镜像与恢复前数据。真实 arm64 Docker 构建、归档往返通过。详见 docs/computer-maintenance.md。

• 维护阶段最终验证：类型检查和 767 项全量测试通过；真实新镜像的工作区恢复后重启读写通过；打包 Runner / 新镜像的完整 Worker 验收 2 项通过，包含公网、临时助手和人工接管。恢复保留挂载根目录以兼容 macOS 文件共享，并测试中断回退。

• 桌面补齐阶段：内置服务版本与 App 对齐校验，已有外部服务显示实际版本；登录启动为原生显式开关，支持登录时仅驻留菜单栏。App 内置服务禁用源码部署更新器，提供 App 手动更新/数据回退说明。6 项桌面生命周期及凭据/偏好/版本测试、14 项更新器定向测试通过。真实开机与最后完整包验收仍需区分，见 docs/macos-app.md。