ChatGPT 浏览器引擎

repo-harness chatgpt browser-* 使用本地已登录的 ChatGPT Web 会话来做规划和审查。它不使用 OpenAI API，也不需要 OPENAI_API_KEY。Prompt 由显式指定的仓库文件构建，每次运行都保存为一份 repo-local 的会话记录。

浏览器引擎跑在 Oracle 上——repo-harness 把 oracle --engine browser 作为默认、推荐的 provider 来封装。更早的自研 Chrome 引擎只作为已弃用的诊断手段保留。

它做什么

从显式指定的文件构建经策略检查的 prompt 包，通过 Oracle 驱动 ChatGPT Web，并把会话记录保存在 .ai/harness/chatgpt/sessions/<sessionId>/ 下。

它不做什么

绝不索要用户名、密码、SSO 密钥、2FA 验证码、cookie 或浏览器 token。不会上传任意仓库文件，不会默认启用远程 CDP，也绝不把模型回复当作事实来源——repo-local 的会话存储才是审计记录。

Provider 取向

Oracle 是主路径

• oracle——默认、推荐。 Oracle 拥有浏览器引擎；repo-harness 总是传入 --engine browser 并关闭自动归档。这就是你想要的 provider。
• native——已弃用。 自研的 Chrome DevTools Protocol 引擎不再维护， 只作为短期诊断手段保留（browser-doctor --provider native），后续会被移除。

1. 首次设置

1. 创建会话根目录并打印推荐的忽略规则（浏览器状态保留在本地）：

   repo-harness chatgpt browser-setup --repo .

2. 让一个固定版本的 Oracle 二进制可被解析——放在你的 PATH 上，或仓库的 node_modules/.bin 里。 Oracle 是一个可选的外部 CLI，有自己的运行时要求（Node ≥ 24），与 repo-harness 的 Bun 运行时相互独立。

3. 验证引擎已就绪（这是 Oracle 运行时边界的权威判断）：

   repo-harness chatgpt browser-doctor --repo . --provider oracle --json

   反复运行直到它报告 status: "ready"。如果它报告 nodeCompatible: false，先修复或重装 Oracle 的 Node 运行时。

把浏览器状态挡在版本控制之外

browser-setup 会为本地浏览器 profile 和会话 token 打印忽略规则。绝不要提交它们， 也绝不要把会话数据粘贴到 issue、PR 或共享日志里。

2. Dry run

在不打开 ChatGPT 的情况下校验 prompt、文件策略、内联大小和会话写入路径。它会保存一个 dry_run 会话。

repo-harness chatgpt browser-consult \
  --repo . \
  --dry-run \
  --prompt "Review this sprint." \
  --file plans/sprints/example.sprint.md \
  --model "GPT-5 Pro" \
  --thinking heavy

3. 运行一次 consult

Oracle 是默认 provider，所以 --provider oracle 是可选的，这里写出来只是为了清楚。

repo-harness chatgpt browser-consult \
  --repo . \
  --provider oracle \
  --prompt "Review this PRD and return risks." \
  --file plans/prds/example.prd.md \
  --follow-up "Challenge your previous recommendation." \
  --write-output .ai/harness/handoff/gptpro/chatgpt-review.md

注意

• --model 选择 ChatGPT 模型；--thinking <light|standard|extended|heavy> 映射到 Oracle 的 浏览器思考时长。省略 --model 则保留已登录 UI 中当前选中的模型。
• 写出的答案文件是权威的——stdout/stderr 只当作日志。
• 一次干净退出但没有产生答案文件，会被报告为可恢复（ORACLE_CAPTURE_INCOMPLETE）： prompt 可能已经提交了，所以用 browser-followup 重新接上，而不是重新发送。
• --write-output 必须是仓库相对路径，除非传入 --overwrite-output，否则不会覆盖已有文件； 绝对路径需要仅供人工使用的 --allow-absolute-output。把 GPT Pro 的输出放在 .ai/harness/handoff/gptpro/ 下。

4. 会话

repo-harness chatgpt browser-list --repo .
repo-harness chatgpt browser-session --repo . chgpt_20260617_120530_review-sprint
repo-harness chatgpt browser-session --repo . chgpt_20260617_120530_review-sprint --metadata-only
repo-harness chatgpt browser-open --repo . chgpt_20260617_120530_review-sprint

每个会话都是一份自包含的记录：

• 文件夹.ai/harness/chatgpt/sessions/

  • 文件夹<sessionId>/

    • meta.json 元数据、时间戳、provider 信息
    • prompt.md 输入 prompt
    • transcript.md 完整对话
    • output.md 捕获的 assistant 响应
    • events.jsonl 结构化事件流
    • 文件夹artifacts/ 可选的生成产物

      • …

5. 跟进与清理

把一个 follow-up 链接到一个已保存的会话——它会通过 Oracle 恢复那段对话：

repo-harness chatgpt browser-followup \
  --repo . \
  --session chgpt_20260617_120530_review-sprint \
  --prompt "Turn that review into a Codex-ready goal."

清理默认是 dry-run，只有传入 --force 时才会移除候选项：

repo-harness chatgpt browser-cleanup --repo . --status dry_run --limit 20
repo-harness chatgpt browser-cleanup --repo . --status dry_run --limit 20 --force

6. Native provider（已弃用）

仅供诊断——正在移除

原生的 Chrome DevTools Protocol provider 已弃用，优先用 Oracle。Chrome 136+ 还会对你的默认 Chrome 数据目录屏蔽 remote-debugging 开关，所以任何原生用法都需要一个非默认的 --profile-dir。

repo-harness chatgpt browser-doctor --repo . --provider native
repo-harness chatgpt browser-consult --repo . --provider native --prompt "Reply exactly OK"

原生运行使用 ChatGPT Web UI 中已经选好的模型/思考模式；传入 --model 或 --thinking 会 fail closed。 当你需要由 provider 端选择模型时，请用 Oracle。

7. 通过 MCP 暴露（可选）

浏览器工具在 MCP 中默认禁用。显式启用它们：

repo-harness mcp serve \
  --repo . \
  --transport stdio \
  --profile planner \
  --enable-chatgpt-browser

这会暴露 run_chatgpt_browser_consult、read_chatgpt_browser_session、 list_chatgpt_browser_sessions、open_chatgpt_browser_session 和 continue_chatgpt_browser_session。MCP consult 把 writeOutput 限制在工作流产物上，比如 .ai/harness/handoff/*.md、tasks/reviews/**、.ai/harness/checks/**、plans/prds/** 和 plans/sprints/**。

文件策略与安全

引擎在任何浏览器或 provider 运行之前就拒绝被拒文件，并拒绝那些解析到仓库之外的允许路径符号链接。

• 默认允许： AGENTS.md、CLAUDE.md、README.md、docs/**、plans/**、tasks/**、 .ai/context/**、.ai/harness/**、package.json
• 默认拒绝： .env / .env.*、私钥和证书文件、.ssh/**、.git/**、node_modules/**、dist/**、 build/**、coverage/**、secrets/**、credentials/**、private/**、 _ops/**、.repo-harness/**/*.json

安全提示

保持浏览器 profile 和本地配置不提交。没有明确的安全方案之前，不要把 Chrome 远程调试暴露到 localhost 之外。在发送大量或敏感上下文之前先 dry-run，优先用窄范围的文件而不是整仓 dump， 并把生成的 ChatGPT 输出当作审查输入——而不是权威的代码事实。

下一步

MCP 连接器 通过 MCP 向 ChatGPT 和 Codex 暴露工作流产物。

ChatGPT Pro 规划器 完整的 plan-and-review 工作流。