Skip to content

feat(browser): 接管模式 — 可见 headed 窗口承载会话级登录与人工处理(#491 P2) - #524

Merged
Qiyuanqiii merged 6 commits into
mainfrom
Qiyuanqiii/browser-takeover-mode
Nov 2, 2026
Merged

Qiyuanqiii merged 6 commits into
mainfrom
Qiyuanqiii/browser-takeover-mode

Conversation

@Qiyuanqiii

@Qiyuanqiii Qiyuanqiii commented Oct 29, 2026 •

Copy link
Copy Markdown
Member

动机 / Motivation

#491 P2 的 headed 交接 + 会话级登录 v1:默认 headless 下,登录态(staging 预览、OAuth、2FA)与 waiting_user 人工处理都不可达。Codex 用 Chrome 扩展解决身份;Universal-Code 是本地桌面产品,最自然的路径是把同一个隔离浏览器以可见窗口启动——人工在窗口内登录,登录态存续于会话一次性 profile,cleanup 时擦除(profile 生命周期既有语义,零新增清理面)。

变更 / Changes

  • CYBERAGENT_BROWSER_HEADED=1|true(或 CLI cyberagent api serve --browser-headed)在组合根选择接管模式;三个组合根全部接线(api serve、前台 CLI run 的 DangerFullAccess 路径、桌面控制面)。
  • 只改变进程可见性:同一一次性 profile、origin scope、请求级拦截、下载隔离与审批规则不变;ProfileToken/Generation 指纹与可见性无关(评审确认无跨代漂移)。
  • waiting_user 状态文案指向接管模式;usage.md 新增双语 "Browser takeover and session login" 小节(含会话 30 分钟 RuntimeDeadline 边界的如实说明——到期 profile 擦除、下次导航开新 profile)。
  • 评审记录(3 条 P3 文档/接线精度问题,全部修复)见 docs/reviews/browser-takeover-mode/。

验证 / Verification

  • gofmt/go vet/go build ./... 全部干净;TestBrowserHeadedFromEnvironment 覆盖取值矩阵(1/true/大小写/空白与 0/false/yes/on 的 fail-closed)。
  • 评审子代理独立实跑 internal/desktop 全量 ok;Headless 汇点、spec 参数两种变体校验、指纹链、文案一致性逐项核验。
  • 已知边界(如实记录):env 在进程启动时求值,运行中更改需重启;桌面设置 UI 化(替代环境变量)留作后续;web vitest 由 CI 执行。

关联 #491、#520、#523。

评审跟进 / Review follow-up

外部评审对本 PR 的结论是"实现可以保留,但建议补一次真实 headed 浏览器验收,并在上游合并后重新检查差异"。本轮完成两件事:

1. 已吸收上游修复(merge commit 9e667a06)

本 PR 的 base 是 #523(Qiyuanqiii/browser-download-release),而 #523 的 base 是 #520。评审指出这三者必须按 #520 → #523 → #524 的顺序处理,不能因为各自 CI 成功就按普通独立 PR 合并。因此本轮先把 #520 的 P1 会话累计下载预算修复(2cd5cbb9)与 #523 的 P2 释放审批审计修复(fb1e3ae4)一并以 merge commit 并入本分支,保证本 PR 建立在已修复的上游之上。

并入后本 PR 相对其 base 的有效差异仍只有接管模式本身的 12 个文件(+278/−8),没有把上游功能重复计入本 PR。

2. 合并前置条件

真实 headed 浏览器验收清单 / Real headed browser acceptance checklist

外部评审指出:本 PR 的测试主要覆盖环境变量解析与三个组合根的接线,没有证明真实 headed 场景。人工 2FA 与真实站点的跨 origin OAuth 登录无法在无人值守环境完成,因此下面每一步都必须由具备可见桌面环境的维护者实跑确认;未跑之前,本 PR 不应视为已完成真实场景验收。

前置条件:以 CYBERAGENT_BROWSER_HEADED=1(或 cyberagent api serve --browser-headed)启动,并用 CYBERAGENT_BROWSER_SESSION_LIFETIME_MINUTES 把会话时长设到足够覆盖整轮人工操作(上限 30 分钟 RuntimeDeadline,到期后 profile 擦除)。

  1. 可见窗口中的真实登录:在 headed 窗口内访问一个需要登录的站点并完成登录。确认窗口确实可见、输入焦点落在窗口内、登录态存续于该会话的一次性 profile。
  2. 跨站 OAuth 跳转:完成一次授权页位于另一 origin 的 OAuth 授权。这是评审明确点出的未验证风险点:现有请求级拦截策略若按 origin 白名单工作,跨站跳转可能被拦截而无法完成授权。必须记录拦截是否放行,以及放行条件是什么。
  3. 人工 2FA:在 waiting_user 状态下由人工在可见窗口内输入验证码,确认整个过程不会被 30 分钟 RuntimeDeadline 提前打断(必要时先提高会话时长上限再测)。
  4. 登录后的会话恢复:同一会话内再次导航,确认登录态仍在;会话结束后确认 profile 被擦除、登录态不跨会话残留。
  5. 证据留存:为上述每一步保存截图与对应日志,连同 commit 号记录到本 PR 或 docs/reviews/browser-takeover-mode/。

说明:第 2 项(跨 origin OAuth 是否被现有拦截策略放行)与第 3 项(人工 2FA)无法在无人值守 CI 中自动化,必须人工实跑。本 PR 的 CI 全绿不等价于上述场景已验收;本清单是合并前的待办验收项,不是已完成项。


层叠栈同步:已携带 #520 / #523 的第二轮修复

第二轮外部复审在 #520 查出超限下载的 Browser.cancelDownload 未携带 browserContextId
(取消打在默认 BrowserContext 上 → 取消失败 → 按既有策略关闭整个会话),在 #523 查出重复释放
响应回显请求方而非落盘审批、以及工件写失败留下半截文件导致该 GUID 永久无法重试。两处修复已
按层叠顺序并入本分支:merge: carry the browser context cancel fix into the release branch
→ fix(application): report the recorded release approval and roll back failed artifact writes
→ 本分支的 merge commit(0e21640f 携带 2dcf89ba),沿用本栈既有的 merge commit 传播方式,
未做任何 force-push。

同步后的复测(Go 1.26.10 / windows-amd64,HEAD 0e21640f):

…in and manual handling

Issue #491 P2 (headed handoff) + the session-login story: the agent
browser can now run as a visible window on the operator's desktop so a
human can log in, complete 2FA/OAuth, or resolve waiting_user states
manually. Login state persists in the session's disposable profile and
dies with it at cleanup; the agent gains no extra authority and origin
scope, interception, quarantine, and approvals are unchanged.

- CYBERAGENT_BROWSER_HEADED=1|true at either composition root, or
  cyberagent api serve --browser-headed.
- waiting_user status copy now points at the takeover mode.
- Bilingual usage docs for the takeover and session-login semantics.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
@Qiyuanqiii
Qiyuanqiii force-pushed the Qiyuanqiii/browser-takeover-mode branch from 9764541 to bd34eba Compare October 29, 2026 22:56
claude and others added 3 commits October 30, 2026 07:10
… logins

Completes the takeover-mode follow-up flagged in review: the browser
session runtime deadline (30 minutes by default) wipes the disposable
profile — including manual login state — right when a takeover session
needs it most. Operators can now raise it with
CYBERAGENT_BROWSER_SESSION_LIFETIME_MINUTES (5..1440, accepted at the
same three composition roots; malformed or out-of-range values keep the
default). Quarantine, approvals, and cleanup receipts are unchanged.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Caution

Review failed

The pull request is closed.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants