feat(plugins): unify realtime device viewers for Codex and WorkBuddy

docs/plans/2026-09-13-viewer-candidate-acceptance.md

@@ -0,0 +1,106 @@
+# Codex / WorkBuddy 实时设备墙候选验收记录
+
+日期：2026-09-13。基于提交 `60c1a47` 的本地改动。候选版本为 Codex 0.2.0 / 协议 3、WorkBuddy 0.3.0 / 协议 8。未公开发布。本记录区分代码检查、模拟视频、安装与真实宿主，不将能力检测算作真机验收。
+
+## 交付范围
+
+- 两端各自内置独立 Viewer、scrcpy 4.1 视频传输、WebSocket 与 WebCodecs 页面；无需 DSH，也未修改 DSH。
+- 新增同名 open_viewer / viewer_status / close_viewer 接口；控制会话关联 Viewer。实际可见视频帧的本地回执建立首次门槛；准备依赖后最多等 30 秒。
+- Viewer 与控制生命周期分离。完成或取消控制不关闭视频；已建立门槛后关页不撤销控制。隐藏页保留轻量 presence 连接并暂停视频，最后一个视频订阅者退出后清理编码器和专属转发。
+- 每宿主最多四路共享源、960 / 30 fps / 2 Mbps、无音频、无视频控制通道；解码队列及发送队列有界，丢帧后等待配置和关键帧。
+- Skill 使用 Codex 原生右侧浏览器入口、WorkBuddy 内置 present_files；安装器提前准备视频资源，保留旧包与恢复记录。
+- 修复实测发现的 WorkBuddy 5.5.3 Hooks 字段兼容问题：宿主实际消费 updatedInput，旧实现仅返回 modifiedInput。现在同时返回两者，不改变宿主权限决定。
+
+## 自动化与浏览器
+
+| 检查 | 结果 | 边界 |
+|---|---|---|
+| Codex 完整测试、构建、打包校验 | 80 项 / 14 文件通过 | 含真实 Viewer HTTP/WS 回执与控制服务集成测试 |
+| WorkBuddy 完整测试、构建、打包校验 | 138 项 / 25 文件通过 | 包含已有 Hooks、停止、镜像兼容与执行证据回归 |
+| 首次门槛 | 通过 | 未回执、隐藏、伪造、过期、错设备、重放、超时、新任务不继承；门槛前 host observe/act 调用为零 |
+| 隐藏页生命周期回归 | 修复前失败、修复后通过 | 去掉 presence 保活与回收保护后测试失败；恢复实现后通过 |
+| WorkBuddy Hook 字段回归 | 修复前 2 项失败、修复后通过 | 对象与字符串形式的 deferred 参数均覆盖；额外有实际宿主复测 |
+| 原生 H.264 浏览器解码 | 两端通过 | ffmpeg 合成红/蓝帧，经真实 WS 和 VideoDecoder 绘制，验证颜色改变、任务结束后播放、关页释放 |
+| 四路模拟流 30 分钟 | 两端均通过，60 次采样，关页后全部订阅释放 | 合成流不是四台手机，也不是手机端到端性能测量 |
+
+最后一次短浏览器测试首帧：Codex 908 ms、WorkBuddy 741 ms（包含测试浏览器启动）。早期运行分别为 1045 / 1146 ms。此数值是合成流环境数据，不用于宣称手机性能达标。
+
+四路长测结果（每 30 秒采样一次）：
+
+| 指标 | Codex | WorkBuddy |
+|---|---:|---:|
+| 持续时间 | 1800 秒 | 1800 秒 |
+| 每路平均绘制帧率 | 29.44 fps | 29.44 fps |
+| 服务进程 RSS 起始 / 结束 | 56.48 / 54.19 MiB | 56.92 / 54.56 MiB |
+| RSS 观测最小 / 最大 | 53.03 / 61.34 MiB | 53.73 / 61.58 MiB |
+| 重连 / 解码队列积压 | 0 / 0 | 0 / 0 |
+| 关页释放四路订阅 | 通过 | 通过 |
+
+采样的合成流“服务端发送 → 解码回调”P95 为 3 ms，仅用于识别测试环境积压，不包含手机采集、编码或物理屏幕呈现。长测启动后又增加了隐藏页 presence 保活和配置包显式重置，二者已经过最终集成/浏览器短测，但未重跑最终包的完整 30 分钟长测。该表只证明长测候选的模拟传输/解码稳定性，不代表最终候选或真机长稳门槛全部通过。
+
+## 实际宿主和手机
+
+本机为 macOS arm64，仅一台已授权 Android 手机（PKV110），不在公开记录中保存序列号或 Viewer 访问凭据。
+
+| 环境 | 已观察到的结果 | 尚未覆盖 |
+|---|---|---|
+| Codex 当前任务原生右侧浏览器 | 候选 CLI 创建 Viewer，原生 open_in_codex 打开；后端 ready；读取实际截图，桌面左滑一次、右滑恢复；关闭控制会话后视频继续 | 当前 Codex 已装 personal 来源，未覆盖原插件来冒充独立安装器验收；独立候选 CLI + 实际宿主入口已验证，安装后 Skill 自动发现仍待验收 |
+| WorkBuddy 5.5.3 国内版 | 实际预构建安装器升级成功；首次 MCP 未信任导致工具不可见，宿主信任后恢复；任务内 present_files 自动打开右侧真实视频 | 完整取消、重启和双任务并发的真机回归仍待补齐 |
+| WorkBuddy 5.5.3 国内版 Hooks 修复后 | automation.available=true；首帧 11377 ms；任务结束后页面变成“任务已结束 · 继续投屏” | 自动继续复杂任务与用户停止的最终真机验收另列，不由只读测试代替 |
+| WorkBuddy 海外版 | 模拟海外 bundle / .workbuddy-ai 配置定位、安装及幂等检查通过 | 环境未安装真实海外客户端，右侧页面与 Hooks 未实测 |
+
+WorkBuddy 只读测试实际积分：首次未信任的失败任务 1.29；信任后首次视频通过 1.34（首帧 6771 ms，但当时 Hooks 未绑定，不能作为完整任务通过证据）；修复 Hooks 后只读任务 1.29。纯投屏结束后无持续模型调用。Codex 当前任务没有可归因的积分计量，未估算。
+
+后续 WorkBuddy 真机控制验收在首帧阶段返回 `display_timeout`，没有建立控制会话，也没有调用 observe/act，剩余预算仍为 100。复核时 Mac 已锁定，原生界面工具明确报告不能操作；因此记录为“显示门槛正确阻断、控制闭环未验收”，没有自动创建新任务绕过超时。不能据此断言 USB 断连是根因。
+
+## 安装和恢复
+
+| 项目 | 实测 | 范围 |
+|---|---|---|
+| Codex 冷视频依赖准备 | 312533 ms | 独立缓存，真实资源下载；不是完整宿主安装耗时 |
+| WorkBuddy 冷视频依赖准备 | 首次 240 秒超时；改为 600 秒上限后重试 282910 ms 完成 | 网络时间单独记录，失败不改配置 |
+| Codex 缓存视频资源后的安装 / 重复安装 | 1248 / 653 ms | 隔离 HOME；Codex CLI 和私有 Node 启动器为 fixture，候选包与视频缓存是真实的 |
+| WorkBuddy 缓存视频资源后的安装 / 重复安装 | 13258 / 1457 ms | 隔离海外配置 fixture，真实 npm 预构建包、私有 Node 和依赖导入 |
+| WorkBuddy 国内实际候选安装 | 12 秒；Hooks 修复后的再次升级 11 秒 | 复用既有 Node 和视频缓存，退出宿主后修改配置 |
+| WorkBuddy 配置回退 | 0.2.1 → 0.3.0 → 0.2.1 → 0.3.0，通过 | 隔离配置，使用本机保留旧包；外来 MCP、设置和 Hooks 保留，没有重复 Hook。旧版真实宿主运行未重新验收 |
+| 下载失败恢复 | 两端实际遇到 fetch failed，保留旧配置并给出恢复步骤 | 随后用已验证完整缓存通过安装回归；没有将缓存测试标成冷下载成功 |
+| Codex 旧版恢复 | 安装失败时 marketplace 来源恢复分支经过 fixture 回归 | 真实旧版安装器降级尚未验收 |
+
+安装配置成功与宿主信任、工具加载是不同阶段。WorkBuddy 升级导致 MCP 路径改变时，宿主可能要求再次信任；应该在连接器管理中完成一次信任，而不是让模型循环安装。
+
+## 未通过的发布门槛
+
+以下项目明确保持未验收，不以本轮候选包交付替代：
+
+1. WorkBuddy 海外版真实任务自动打开、首帧与 Hooks。
+2. 两台真机的设备选择、并发隔离、断连不得切换；目前仅一台手机。
+3. 真机横竖屏切换、持续动态画面的单机 ≥24 fps，以及手机到屏幕端到端延迟 P95 ≤500 ms。合成流发送到解码耗时不是端到端延迟。
+4. 真机连续播放 30 分钟的进程、ADB 转发、缓冲资源完整记录。中间中断的长时间运行不算通过。
+5. 实际宿主取消、关闭页面后继续控制、MCP 断连重连、宿主重启的完整组合回归；已有单元/集成覆盖不替代这些实测。
+6. Codex 独立来源安装后的 Skill 自动发现和真实旧版降级恢复。
+
+## 复现与候选文件
+
+```sh
+cd plugins/opengui
+pnpm check
+pnpm test:viewer
+VIEWER_TEST_DEVICES=4 VIEWER_SOAK_MS=1800000 pnpm test:viewer
+pnpm package
+
+cd ../../workbuddy-plugin
+npm run check
+npm run test:viewer
+VIEWER_TEST_DEVICES=4 VIEWER_SOAK_MS=1800000 npm run test:viewer
+npm run pack:release
+```
+
+宿主实测后最后补充了“收到配置包即重置解码器”，最终浏览器测试通过 160×320 → 320×160 的配置/关键帧恢复。Mac 锁定后未再安装最终包进行宿主复测；此前实测包与最终包的差异包括这一页面修复，不能标成最终包全链路已通过。
+
+浏览器测试需要开发机的 agent-browser、ffmpeg；最终用户安装不需要。
+
+- Codex：`plugins/opengui/.artifacts/opengui-codex-0.2.0-install.command`、同目录 tar.gz / zip 与 SHA-256。
+- WorkBuddy：`workbuddy-plugin/dist/opengui-workbuddy-0.3.0-install.command`、同目录 `opengui-mcp-0.3.0.tgz` / connector zip 与 SHA-256。
+- 安装时把对应 archive 和 `.sha256` 放在一起，向安装器传入 `--archive /绝对路径/文件名`。未发布候选不应依赖公开下载 URL。
+
+原始本机调试日志不入仓库；公开记录只保留去标识化的结果与边界。候选包尚未发布。

plugins/opengui/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "opengui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Control authorized local Android devices from Codex on macOS, with screenshot-guided actions and a read-only device wall.",
   "author": { "name": "Core-Mate", "url": "https://github.com/Core-Mate" },
   "homepage": "https://github.com/Core-Mate/OpenGUI/tree/main/plugins/opengui",