# ChatGPT Web Bridge

**Python MCP stdio + Chrome Manifest V3 擴充功能。版本 1.2.0。**

1.2.0 Windows 新增本機自動啟動與配對，安裝固定 native host 後，Chrome 載入擴充功能即可啟動 Bridge 並交換配對資料，不必手動複製 Token。此機已安裝；重新載入擴充功能一次即可套用。[自動啟動與驗收](docs/AUTO-START.md)。

1.1.0 新增 Google Flow 可見 UI adapter，含 Omni 設定與費用核對、防重複提交、原生下載追蹤。需要重新載入擴充功能並由使用者授權 Flow 分頁；不處理或繞過網站驗證。[Flow 更新與用法](docs/FLOW.md)。下方原有 ChatGPT 端到端驗收限制仍適用；新增 adapter 的真實網站生成尚待驗證。

讓本機 Agents 透過使用者已登入、明確授權的 `chatgpt.com` 分頁送出對話與圖片要求、查詢完成狀態、下載圖片。不是 OpenAI API 包裝器，不需要 API Key，不讀取登入 Cookie，也不需要開啟 Chrome 遠端除錯連接埠。

> **交付狀態：完整可執行原始碼，尚未完成真實 ChatGPT 帳號端到端驗收。** Python/本機 transport/離線 DOM/模擬 Chrome API 測試結果見 [驗證報告](docs/VALIDATION.md)。交付環境的選擇性實際 extension 載入測試逾時；已確認 Chromium 環境政策封鎖所有 extension 與網址，不能宣稱已在真實 Chrome + ChatGPT 成功生圖。網站 DOM、下載按鈕、上傳方式可能需要依帳號當前介面調整。
>
> **服務條款：** OpenAI 個人服務條款禁止自動或程式化擷取資料／輸出，並禁止繞過限制及保護措施。這個整合不是官方授權介面；逐次人工確認也不構成條款豁免。使用前必須確認適用條款與必要授權，不應視為可長期無人值守爬取的服務。[官方來源與查閱範圍](docs/SOURCES.md)。

## 1. 已實作的功能與範圍

| 類別 | 本版實作 |
|---|---|
| 對話 | 新開授權分頁、授權現有分頁、送出文字、讀取目前已載入的訊息 |
| 圖片 | 透過一般對話輸入要求實際生圖；可附本機 PNG/JPEG/WebP 參考圖片 |
| 任務 | 立即取得任務 `id`；輪詢、取消、只續查不重送；SQLite 持久化 |
| 防重複 | 必填 `request_id`；同一請求相同參數回傳舊任務；不同參數拒絕 |
| 多 Agent | 多個 MCP stdio 子程序共用一個 bridge；生成工作全域逐一執行；同分頁鎖定 |
| 下載 | `original` 嘗試點網頁原生下載；`rendered` 儲存已顯示圖片資源的原始位元組 |
| 安全 | 預設關閉、自動送出預設關閉、人工逐次確認、擴充功能 ID + token 配對、僅監聽 loopback |
| 維護 | 狀態診斷、CSS selectors 覆寫、JSON/Markdown 匯出、跨平台安裝腳本、MCP 設定產生器 |

這裡的「圖片生成」是把要求送到正常的網頁聊天輸入框，不會呼叫未公開生圖 API。不自動選模型、不操控付費／訂閱頁面、不切換帳號繞過額度。請先在 Chrome 手動確認可用模型及生圖功能；只有文字回覆時會標示 `text_only`，不假裝已有圖片。

## 2. 架構

```text
Codex / OpenCode / AGY / 其他支援本機 stdio MCP 的 Agent
                     │ JSON-RPC，stdin/stdout
                     ▼
           Python MCP server（每個 Agent 各自啟動）
                     │ Bearer token，本機 HTTP /call
                     ▼
           Python bridge（每組設定只執行一個）
                     │ 驗證 Origin + token 的 WebSocket
                     ▼
       Chrome extension service worker（同一個 Chrome profile）
                     │ 限制動作、隔離 content script
                     ▼
            明確授權的 chatgpt.com 分頁
```

Bridge、MCP Python 子程序與 Chrome 預設必須位於**同一台電腦的同一本機網路環境**。遠端 Codex VM 的 `127.0.0.1` 不是 Windows 主機；不能直接套這份本機設定。這個專案不會把服務公開到 LAN／Internet，也沒有提供跨 VM 傳檔或遠端 gateway。Node、Rust、Docker、WSL 都不是執行期必要條件。

## 3. Windows 安裝

需要已安裝 **Python 3.11+**、**Chrome 120+**；首次安裝需要網路下載 Python 依賴。ZIP 不含 Python 或 Chrome 安裝程式。

### 步驟 A：解壓縮並安裝 Python 環境

建議解壓縮至固定路徑，例如 `C:\Tools\chatgpt-web-bridge`；之後不要任意搬移，Chrome unpacked extension ID 與 Agent 設定均可能受路徑影響。

在該資料夾執行 `install.cmd`，或 PowerShell：

```powershell
cd C:\Tools\chatgpt-web-bridge
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1
```

這會建立 `.venv`、`.local/config.json`、`.local/input/` 和 `.local/agent-configs/`。不需要系統管理員，不永久更改 PowerShell execution policy，不覆寫現有 Agent 設定；再次安裝保留既有 token。

### 步驟 B：載入擴充功能及配對

Chrome 開啟 `chrome://extensions`，開啟「開發人員模式」，按「載入未封裝項目」，選擇本專案的 **`extension` 資料夾**，不是專案根目錄。複製顯示的 32 字元擴充功能 ID。

```powershell
.\scripts\cwb.ps1 pair --extension-id 實際的32字元ID
.\scripts\cwb.ps1 show-token
```

打開擴充功能「選項」，填入：

```text
Bridge URL: ws://127.0.0.1:8765/extension
Token:      剛剛 show-token 的內容
啟用:       勾選
自動送出:   初次使用保持不勾選
```

按儲存。Token 是本機密鑰，不是 ChatGPT 的 token；不要貼給 Agent 對話、截圖分享或提交 Git。

### 步驟 C：啟動 Bridge

在獨立 PowerShell 視窗執行，使用期間保留該視窗：

```powershell
.\scripts\start-bridge.ps1
```

或雙擊 `start.cmd`。再開另一個視窗檢查：

```powershell
.\scripts\cwb.ps1 doctor
```

應看到 `paired: true` 與 `connected: true`。`doctor` 是連線檢查，不代表 ChatGPT 生圖已驗收。任何 `.ps1` 被本機政策阻擋時，可使用原生 Python 等效命令，不要放寬企業政策：

```powershell
.\.venv\Scripts\python.exe .\run.py --config .\.local\config.json doctor
```

### 步驟 D：登入並授權分頁

在同一個 Chrome profile 自行登入 ChatGPT。打開普通聊天頁，點擴充功能圖示，再點「授權目前分頁」。或由 Agent 用 `chatgpt_open` 新開受控分頁。擴充功能啟用後，Agent 可以建立受控新分頁；**已存在的其他分頁不會因此被全部授權**。

預設每次送出會在目標分頁顯示確認視窗，120 秒內按「允許這一次」才會送出。需要自主執行時，使用者可在擴充功能明確啟用自動送出；Agent 不能透過 tool 自行打開這個選項。自動送出可能消耗帳號額度。

### 步驟 E：接上 Agent

安裝程式已依實際解壓縮路徑產生設定片段：

```text
.local/agent-configs/codex.toml
.local/agent-configs/opencode.json
.local/agent-configs/agy.json
.local/agent-configs/generic.json
```

把對應片段**合併**進 Agent 的現有 MCP 設定，不要整份覆蓋。Codex 使用 `mcp_servers` TOML；OpenCode 使用 `mcp` local server；AGY／通用格式使用 `mcpServers`。主機須能啟動本機 Python stdio，且接受本版支援的 MCP 協定版本。各應用不同版本的設定位置及信任設定，以其官方介面為準；本次未在這三款實際 Agent 主機內驗收。

也能重新產生片段：

```powershell
.\scripts\cwb.ps1 client-config codex --python "$PWD\.venv\Scripts\python.exe" --launcher "$PWD\run.py"
```

**Agent 應啟動的是 `mcp` 子命令，不是 `bridge`。** MCP stdout 只放協定資料，bridge 請另外啟動。

## 4. macOS / Linux

```bash
bash scripts/install.sh
scripts/cwb.sh pair --extension-id 實際的32字元ID
scripts/cwb.sh show-token
scripts/start-bridge.sh
# 另一個 terminal：
scripts/cwb.sh doctor
```

在 Chrome 載入相同 `extension/`、選項中填寫 token/URL，再授權分頁。需要桌面 Chrome；不是 headless 部署方案。Windows、macOS 原生安裝腳本本次未實機驗收，CI 設定提供三平台測試矩陣但不是既有綠燈證明。

## 5. 給 Agent 的用法

可把 `skills/chatgpt-web-bridge/SKILL.md` 放進 Agent 支援的 skill 目錄；MCP 自身也提供 workflow prompt 及 `cwb://guide` resource。

範例指示：

> 使用 chatgpt_web_bridge，先檢查 bridge_status。新開一個 ChatGPT 分頁，要求生成一張 16:9、無人物的古代書齋圖片。只送出一次，保存回傳的 id，等待 chatgpt_job 完成。遇到 needs_attention 或文字回覆就停止，不重新生圖。完成後先用 original 下載並查詢下載狀態；不要把 rendered 預覽說成原始解析度。

### 文字對話

```json
{"name":"chatgpt_open","arguments":{"active":true}}
```

拿回實際 `tab_id` 後：

```json
{"name":"chatgpt_send_message","arguments":{"tab_id":123,"request_id":"my-chat-0001","prompt":"請用繁體中文回覆：連線測試成功。"}}
```

上面是工具呼叫結構示意，`123` 要換成真實 ID。回傳任務物件的 **`id`**，是下一步的 **`job_id`**：

```json
{"name":"chatgpt_job","arguments":{"job_id":"剛剛回傳的id","wait_seconds":20}}
```

持續查同一任務，不要再送相同提示詞。接續對話要等前一任務完成，使用同一 `tab_id`、新的 `request_id`。

### 圖片與參考圖

將你有權使用的參考圖放入 `.local/input/reference.png`：

```json
{"name":"chatgpt_generate_image","arguments":{"tab_id":123,"request_id":"scene-0001","prompt":"請根據參考圖生成一張16:9古代書齋圖片，保留建築風格，畫面無人。","attachment_paths":["reference.png"],"timeout_seconds":900}}
```

單次最多 4 張，本地傳輸總量最多 16 MiB；網站本身仍可拒絕附件。只支援 PNG、JPEG、WebP。檔案必須位於設定的 `input_dir` 中，不能任意讀取 Agent 電腦的檔案。要改白名單資料夾：

```powershell
.\scripts\cwb.ps1 set-input-dir E:\ChatGPT-Bridge-Input
# 改完設定要重啟 bridge。
```

### 下載圖片

從完成任務的 `result.messages` 取得含圖片的 `message_id`，再從其 `images` 取得 `image_index`。切勿自己猜 ID。

```json
{"name":"chatgpt_download_image","arguments":{"tab_id":123,"message_id":"實際訊息id","image_index":0,"mode":"original"}}
```

`original` 嘗試點對應圖片的網頁原生下載控制項，網站決定下載內容與檔名。沒有按鈕、下載事件無法明確歸屬或多圖歧義時報錯，不會盲目重按。

```json
{"name":"chatgpt_download_image","arguments":{"tab_id":123,"message_id":"實際訊息id","image_index":0,"mode":"rendered","filename":"study-scene"}}
```

`rendered` 取得當下 DOM 圖片 URL 的原始檔案位元組，不截圖、不以 canvas 重編碼。但該資源本身可能是預覽或縮圖，因此**不保證網站原圖解析度**。超過 16 MiB、CORS 限制或未知格式會拒絕。

下載開始不代表完成；使用回傳 `download_id` 查詢：

```json
{"name":"chatgpt_download_status","arguments":{"download_id":42}}
```

只有 `state: "complete"` 才能稱為下載完成。檔案在 **Chrome 電腦的下載資料夾**，不是 MCP Agent VM 的 `/mnt/data`；設定「下載前詢問儲存位置」或網站彈出對話框時，需要人在 Chrome 完成。網站來源檔也不一定是 PNG，依實際格式處理。

### 不接 MCP 也能測試

`examples/workflow.py` 提供實際可執行的 CLI：

```powershell
.\.venv\Scripts\python.exe .\examples\workflow.py --mode chat --prompt "請只回答：測試成功。" --state .\.local\first-test.json
```

```powershell
.\.venv\Scripts\python.exe .\examples\workflow.py --mode image --prompt "生成一張16:9古代書齋，無人物、無文字。" --state .\.local\scene-001.json --download original
```

首次寫入 request_id；重跑相同 state 檔案只查舊任務或以相同 request_id 確認登錄，不生成第二次。請先啟動 bridge、啟用擴充功能，並在網頁允許這次操作。未知結果會停止，**不自動 resume／acknowledge**。

CLI 呼叫也支援 `@UTF-8.json`，可避免 PowerShell 多行 JSON 的跳脫問題：

```powershell
.\scripts\cwb.ps1 call chatgpt_list_tabs
.\scripts\cwb.ps1 call chatgpt_generate_image '@examples/image-request.json'
```

最後一個範例先編輯 JSON 的 `tab_id` 及新的 `request_id`，不可照抄 123 當真實分頁。

## 6. 任務狀態及重試規則

```text
queued → preparing → sending → running → succeeded
                                  ├──→ text_only
                                  ├──→ needs_attention
                                  └──→ cancelled
送出前確定失敗 → failed
```

`needs_attention` 包含：網頁／分頁改變、Bridge 中斷、超時、Stop 結果無法確認。它會保留同分頁鎖，不會因重連或 Agent 逾時而自動重送。先讀取頁面、人工確認，再選擇 `chatgpt_resume_job` **只觀察原任務**，或人工承認未知結果後 `chatgpt_acknowledge_job` 釋放分頁。後者不是停止網站生圖，也不退還額度。

完成判斷需要：本輪使用者訊息、新的 assistant 訊息、沒有忙碌狀態、訊息的結束控制項與穩定期間。文字模式預設穩定 6 秒，圖片模式 12 秒；圖片模式只有文字會另等 45 秒後標示 `text_only`。不以固定 sleep 或看到一張既有圖片就說成功。這仍依賴 DOM，不等同官方完成事件。

## 7. 測試及維護

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Dev
.\.venv\Scripts\python.exe -m playwright install chromium
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe .\scripts\check_package.py
```

Node 只供 service-worker API mock 測試；沒有 Node 該項會跳過。Playwright 只供 DOM 測試，不是本專案操控日常 Chrome 的執行期依賴。選擇性完整 extension transport 測試：

```powershell
$env:CWB_REAL_EXTENSION_TEST='1'
.\.venv\Scripts\python.exe -m pytest tests/test_extension.py -q
Remove-Item Env:CWB_REAL_EXTENSION_TEST
```

不得更動瀏覽器企業政策來讓測試過關。測試沒有登入帳號，也不消耗生圖額度。真實帳號驗收見 [手動清單](docs/MANUAL-ACCEPTANCE.md)。

DOM 變更請先 `chatgpt_diagnose`，再在擴充功能「選項」覆寫已知 selector 群組；重設為 `{}` 會回到預設。只接受 CSS selector，不接受 JS 程式。修正前不要反覆送出以測試。

## 8. 已知不支援與非保證事項

只支援普通 `/`、`/c/<id>` 聊天頁；不支援 Projects、自訂 GPT `/g/`、圖片資料庫列表批次下載、Canvas、影片、帳號完整歷史、音訊串流、任意 JS、精準圖片 editor 選區、跨機遠端控制與自動解 CAPTCHA。自動化回覆內容不是可信系統指令。

本版沒有 ChatGPT API fallback、API 金鑰欄位、Rust 實作、Chrome 商店簽署版、打包 exe 或 Python 依賴離線 wheel。ZIP 含全部專案來源，不含使用者登入資料或 token。圖片辨識只證明回覆區域有符合條件的頁面圖片，不是來源或新生成的鑑定；請人工檢查成品。`original`/`rendered` 兩種下載都未經真實帳號驗收；不要把圖片數量、透明度、尺寸或生成時間當成硬保證。

## 文件索引

[工具完整定義](docs/TOOLS.md) · [架構及協定範圍](docs/ARCHITECTURE.md) · [安全](docs/SECURITY.md) · [排錯](docs/TROUBLESHOOTING.md) · [驗證](docs/VALIDATION.md) · [手動驗收](docs/MANUAL-ACCEPTANCE.md) · [官方來源](docs/SOURCES.md) · [MIT License](LICENSE)