Browser Agent 实施与验证记录

本页只记录 Computer Use 目标设计的实施任务、验证命令和 review 结论，不修改概念设计。第一项任务交付内置浏览器 Browser Agent 的低成本 baseline。

TASK 1 · COMPLETE

任务 1：DOM-first Browser Agent baseline

批准的设计：docs/reference/design/integrations/computer-use.html。

基线：717d4e17。实现从隔离 worktree 和分支 codex/browser-agent-20260814 开始。

生产文件：openprogram/programs/agentic_functions/browser_agent/__init__.py、openprogram/programs/_registry.py、openprogram/programs/__init__.py、openprogram/agent/authority.py。

测试文件：tests/unit/test_browser_agent.py。

行为契约

公开入口名为 browser_agent，只控制 OpenProgram 桌面端当前可见的内置 web tab；底层固定使用现有 engine=app。
内部工具默认 observe，返回 URL、title、viewport、页面文本、ARIA snapshot 和当前 observation 有效的 element refs，不发送截图。
只有显式 screenshot 才返回一张当前 viewport PNG，并通过当前模型原生 vision 处理；不调用 image_analyze。
不导入或调用 OCR、YOLO、object detector、candidate boxes、zoom、component memory、vision memory、workflow replay 或自动学习。
每个会改变页面状态的动作必须携带最新 frame_id 和 element ref；动作后立即使旧 observation 失效。下一次写动作前必须重新 observe。
公开结果中的 status=succeeded 只在内部工具实际通过一次 DOM/URL assertion，且该 assertion 晚于最后一次写动作时产生。模型输出只提供 summary，不能决定 status。
不开放 JavaScript eval、cookie/storage、upload/download、sidecar、headless fallback 或用户 Chrome profile。
调用结束、取消、超时和异常均关闭本次 Playwright session；现有 playwright_browser API 保持不变。

Public-entry RED

python -m pytest -q tests/unit/test_browser_agent.py 必须先证明以下缺口：

browser_agent 尚未注册。
没有 DOM/ARIA/ref observation 与 viewport screenshot 的受限工具。
没有 stale frame 拒绝和动作后重新 observe 约束。
没有 Runtime 权威 completion，模型可以在无 verification 时声称成功。

安全、取消、错误与并发边界

读取与 screenshot 不请求额外授权；外部 origin 的 navigate/click/type/press/select 每次经过现有 approval 机制。本地项目页面仍受 frame freshness 和 cancel 检查。
首版每个 browser_agent 调用只拥有一个 browser session。已有 playwright_browser session 不复用，避免跨任务 refs 和 verification 交叉。
首版不声称解决多窗口 responder 绑定；当桌面控制面无法唯一确认 tab 时返回 target_lost 或底层错误，不选择其他页面。
step limit、timeout、invalid structured reply、tool error 和 verification missing 都返回 failed/cancelled，不转换为 succeeded。

明确排除

桌面级 Computer Use、GUI Harness 视觉 pipeline、权限卡片新 UI、永久 origin grant、tab lease、多窗口路由重构、Windows、OS keychain/keyring、浏览器 profile 迁移均不属于任务 1。

Full gate manifest

python -m pytest -q tests/unit/test_browser_agent.py tests/unit/test_browser_tool.py tests/unit/test_webtab_control.py
python -m pytest -q tests/unit/test_session_config_tools_intent.py tests/unit/test_tool_expansion_deterministic.py tests/agentic_programming/test_self_recursion_guard.py
python -m tools.docs_site.checklinks
git diff --check

安装版 E2E 验证

测试对象：/Applications/OpenProgram.app 0.6.1。测试没有用 Electron 源码启动；桌面进程和 18101 worker 均来自应用包，worker Python 为 Contents/Resources/runtime/python/cpython-3.12.10-macos-aarch64-none/bin/python3.12。

隔离方式：使用 profile browser-agent-installed-20260814 和端口 18101，避免影响同时运行的其他 OpenProgram worker。模型配置来自该 profile 的本地副本。

场景	运行证据	结论
DOM-first 表单	Session `local_38e090f085`；输入 `browser-agent-installed-final`，点击 pushState，`url_contains ?p=1` 通过；2 次页面写动作，0 次 screenshot，0 个 tool error。	PASS
单图视觉输入	Session `local_7a8021f999`；tool trace 为 `observe → screenshot → verify`；恰好 1 次 screenshot，返回 `ImageContent` 与 `mime_type='image/png'`，无 validation error。	PASS
模型原生 vision 判断	模型基于该 screenshot 判断当前 viewport 含浅色紫色渐变区域。该项是模型语义判断，不是 DOM assertion。	已获得视觉结果
确定性完成判定	同一视觉 session 的 `title_contains Desktop Transfer Acceptance` 返回 `passed=true`，Runtime 因此输出 `status=succeeded`、`reason_code=verified`。该 assertion 只验证标题，不单独证明渐变判断正确。	PASS，证据范围受限

安装版缺陷闭环

缺陷	修复	验证
`ToolReturn` 用 `media_type` 构造 provider 图片，截图调用触发缺少 `mime_type` 的 Pydantic validation error。	`3c850a91` 改为 provider 类型要求的 `mime_type`；screenshot 未传 frame ID 时复用最新 observation，并继续限制同一 frame 只截图一次。	Browser/tool runtime 相关测试 74 passed；安装版视觉 trace 中 PNG image block 成功到达模型。
自动检测到 provider.json 提供的 `minimax-cn-coding-plan` 后，`create_runtime()` 仍直接索引六项内置表，抛出 `KeyError`。	`2acf630b` 将动态 provider 路由到通用 API Runtime，并规范化带 provider 前缀的 model。	Provider routing 6 passed；安装版 session 成功创建 `minimax-cn-coding-plan:MiniMax-M3` Runtime。
桌面内嵌 runtime 只安装基础 wheel，没有 Playwright Python 包，CDP session 无法创建。	`334d0abc` 让桌面 runtime 安装 wheel 的 `[browser]` extra，并在构建时导入检查 `playwright.sync_api`；不下载 Playwright Chromium。	发布回归测试、Bash 语法和 Ruff 通过；安装包内嵌 Python 导入通过；DOM 与视觉 E2E 均通过。

本地 macOS 构建未签名。依赖安装同时报告 Web 依赖 8 个 high severity、Desktop 依赖 2 个 moderate 与 5 个 high severity；本任务未执行会改写依赖树的 npm audit fix。

任务账本

项目	证据	状态
Base commit	`717d4e17`	记录完成
RED	`python -m pytest -q tests/unit/test_browser_agent.py`：9 failed，缺失公开模块与全部约束。	记录完成
GREEN / affected	Focused browser/browser-control group：51 passed；registry/tool-selection group：25 passed。	通过
Specification review	独立只读 review 对实现提交 `37b2c37c` 逐项核对 8 条行为契约与安全边界；zero remaining findings。	PASS
Quality review	首轮 `CHANGES_REQUIRED` 的取消、URL scheme、cleanup 三项已由 `af33c608` 修复。Fresh review 对候选 `d0996f7b` 复核全部 changed boundary，确认此前 `KeyboardInterrupt` 结论为误判；zero remaining findings。	PASS
Full gate	Reviewed candidate：browser/browser-control 58 passed；registry/tool-selection 25 passed；Ruff passed；docs 0 broken links；diff check passed。	通过