ask-bridge

Ask Bridge

核心原則

使用 ask-bridge 把低風險、探索性、可委派的 AI 任務交給 ChatGPT、Gemini 或 Claude 網站處理，再將回覆作為本機工作流程的參考輸入。不要把 provider 回覆視為事實來源、測試結果或已完成的程式碼變更。

優先把主要 Coding Agent 保留給下列工作：讀取專案脈絡、修改檔案、執行測試、驗證行為、整合結論。把 ask-bridge 用於背景研究、摘要、候選方案、初稿與輔助分析。

執行命令名稱

安裝後優先使用 ask-bridge：

ask-bridge --help

本專案產出的 Rust binary 叫 ask-bridge，release 產物通常位於 target/release/ask-bridge。在專案內測試尚未安裝的版本時，可使用：

cargo run --bin ask-bridge -- --help
target/release/ask-bridge --help

本 Skill 下方範例一律以安裝後的 ask-bridge 命令表示。

ask 只是向後相容 alias。除非使用者明確要求 alias，文件、範例與自動化命令都優先使用 ask-bridge。

使用前檢查

先確認 ask-bridge、Node.js 與 npx 可用：

ask-bridge -v
node --version
npx --version

Node.js 必須符合 ^20.19.0、^22.12.0 或 >=23.0.0。執行瀏覽器操作還需要 Google Chrome；macOS、Windows 與 Linux 的偵測位置依專案 README 為準。

若找不到 ask-bridge，在 ask-bridge 專案中可先使用既有安裝流程、cargo run --bin ask-bridge --，或建置後的 target/release/ask-bridge；不要臆測使用者環境已完成設定。

在 Windows 安裝或更新後，額外確認實際命令來源：

where.exe ask-bridge
ask-bridge --version

第一筆展開後的完整路徑結尾應為 \.local\bin\ask-bridge.exe。若其他舊命令排在前面， 重新執行官方 install.ps1；安裝程式會驗證 Windows PE 格式與版本輸出， 並將正式安裝目錄移到 User PATH 最前面。

全域設定檔

ask-bridge 會讀取全域設定檔：

~/.config/ask-bridge/config.json

可用格式：

{
  "provider": "gemini"
}

或：

{
  "provider": "chatgpt"
}

或：

{
  "provider": "claude"
}

provider 優先序：

1. CLI --provider chatgpt|gemini|claude
2. ~/.config/ask-bridge/config.json 的 provider
3. 內建預設 chatgpt

若需要替使用者設定預設 provider，可建立設定檔：

ask-bridge config --provider gemini
ask-bridge config --provider claude

若要改回 ChatGPT：

ask-bridge config --provider chatgpt

使用 ask-bridge config 可查看目前設定：

ask-bridge config

若任務需要單次覆蓋全域設定，直接使用 --provider，不要修改設定檔：

ask-bridge --provider chatgpt '請摘要這段內容。'

首次使用或登入失效時，ask-bridge 可能需要瀏覽器互動登入。只有在任務允許互動式登入時才執行：

ask-bridge login
ask-bridge --provider gemini login
ask-bridge --provider claude login
ask-bridge login --provider gemini

若目前任務不適合中斷等待登入，回報需要使用者完成登入，不要反覆重試。

委派決策

適合使用 ask-bridge：

• 摘要長文件、錯誤訊息、測試輸出、issue 討論或研究筆記。
• 請外部 AI 對程式片段、設計方案或規格草稿做初步分析。
• 產生候選實作策略、檢查清單、測試案例構想或文件初稿。
• 比較多個方案的優缺點，但由本機 agent 保留最終判斷。
• 將不需要直接修改專案檔案的工作移出主要 agent 流程。

避免使用 ask-bridge：

• 需要讀取或傳送密鑰、憑證、token、個資、內部機密或使用者未授權的內容。
• 需要可驗證最新資訊、法規、價格、版本、新聞或官方規格時，把 ask-bridge 當成唯一資料來源。
• 需要直接修改檔案、執行測試、操作 git、發佈或部署。
• 任務要求嚴格可重現、可稽核或不可容忍 provider 幻覺。

快速語法

基本語法：

ask-bridge [OPTIONS] [PROMPT] [COMMAND]

常用範例：

ask-bridge '請摘要下列錯誤訊息，列出可能原因與下一步檢查。'
ask-bridge --provider gemini '請比較這三個實作方向的風險與取捨。'
cat report.md | ask-bridge '請摘要這份文件，列出待辦。'
ask-bridge '請摘要這份規格文件。' --file docs/spec.md -o /tmp/spec-summary.md
ask-bridge '請描述這張截圖中的 UI 問題。' --image screenshot.png
ask-bridge '請分析這份長報告。' --file report.pdf --timeout 600
ask-bridge '請根據這份 prompt 產生圖片。' -i /tmp/generated-images/

若同時提供 prompt argument 與 stdin，ask-bridge 會組合為：

prompt + "\n\n" + stdin

參數速查

參數	用途	用法重點
[PROMPT]	要送給 provider 的文字 prompt	可省略；若 stdin 有內容則使用 stdin；若兩者都有，會以兩個換行串接
-p, --provider <PROVIDER>	選擇 provider	可用 chatgpt、gemini 或 claude；此為 global option，可放在子命令前後；優先權高於全域設定檔
--headless[=<HEADLESS>]	控制 Chrome 是否 headless	預設 true；要顯示瀏覽器請用 --headless=false；不要寫成 --headless false
--new	開啟全新 provider 對話	會開啟並綁定新的唯一分頁，同時保留所有既有頁籤；用於隔離上下文
--session <URL_OR_ID>	接續既有 provider 對話	可傳完整對話 URL 或對話 ID；--session-id、--session-url 為別名；不能與 --new 同時使用
-v, -V, --version	顯示版本	-V 是原始碼中定義的短別名；文件與一般操作優先用 -v 或 --version
--verbose	顯示瀏覽器自動化流程	用於診斷 provider UI、登入、上傳、模型切換或等待回覆問題
-o, --output <FILE>	將最終 Markdown 回覆寫入檔案	同時仍會在終端機輸出渲染結果；適合保留研究紀錄
-i, --image-output <IMAGE_PATH>	下載 provider 回覆中的生成圖片	可指定資料夾或檔案路徑；可搭配一般 prompt、get 或 open <url>
--image <IMAGE_FILE>	附加圖片檔，可重複指定	支援 ChatGPT 與 Claude；搭配 Gemini 會失敗
--file <FILE>	附加文件檔，可重複指定	支援 PDF、Word、Excel、PowerPoint、純文字、Markdown、CSV、JSON、程式碼等；ChatGPT、Gemini 與 Claude 都可用
--timeout <SECONDS>	設定等待上限	必須是大於 0 的整數，預設 300 秒；同時套用於一般回覆與 login 登入偵測
--model <MODEL>	送出 prompt 前切換模型	比對不分大小寫與標點；模型名稱取決於 provider UI 與帳號權限
--reasoning <REASONING>	切換 provider 推理模式	ChatGPT 支援 instant、medium、high、xhigh（新版已無 auto）；Gemini 支援 extended；Claude 不支援
-h, --help	顯示 help	可用 ask-bridge --help 或 ask-bridge help <COMMAND>

只有 --provider 是 global option，可放在子命令前後。其他頂層選項搭配子命令時必須放在子命令之前，例如 ask-bridge --timeout 600 login、ask-bridge --output /tmp/reply.md get <url>；不要寫成 ask-bridge login --timeout 600 或 ask-bridge get <url> --output ...。

Provider 選擇

預設使用 ChatGPT：

ask-bridge '請摘要下列錯誤訊息，列出可能原因與下一步檢查。'
ask-bridge --provider chatgpt '請分析這段程式碼的風險。'
ask-bridge -p chatgpt '請整理這份文件的待辦。'

使用 Gemini 或 Claude 時明確指定 provider：

ask-bridge --provider gemini '請比較這三個實作方向的風險與取捨。'
ask-bridge -p gemini '請摘要這份文件。' --file notes.md
ask-bridge --provider claude '請初步分析這段程式碼的風險。'
ask-bridge -p claude '請摘要這份文件。' --file notes.md

選擇原則：

• 未指定 --provider 時，先依全域設定檔選擇 provider；設定檔不存在時使用 ChatGPT。
• 使用 ChatGPT 作為未設定時的預設 provider。
• 使用 Gemini 做替代觀點、快速摘要或使用者明確要求 Gemini 時。
• 使用 Claude 做程式碼分析、長文摘要、替代觀點或使用者明確要求 Claude 時；Claude 也支援 --image 圖片輸入。
• 若 provider 失敗，可在不增加風險的情況下改用另一個 provider 一次。
• 不要硬編不存在的模型名稱；只有使用者指定或專案文件明確列出時才使用 --model。

Prompt 組裝

讓委派 prompt 包含明確輸出契約：

你是協助主要 Coding Agent 的研究助手。
目標：<要完成的分析或摘要>
背景：<必要上下文>
輸入資料：<貼上內容或說明附件>
請輸出：
1. 直接結論
2. 依據與不確定處
3. 可執行的下一步
限制：不要聲稱已修改本機檔案；不確定時請明確標示。

保持 prompt 聚焦。大型任務先請 provider 產生摘要或候選清單，再由本機 agent 判斷是否需要第二輪委派。

傳入資料

對短文字使用 argument：

ask-bridge '請用 5 點摘要這段錯誤訊息，並標示最可能的根因。'

對程式片段或命令輸出使用 stdin：

cargo test 2>&1 | ask-bridge '請摘要測試失敗重點，列出可能要看的檔案與函式。'
cat src/main.rs | ask-bridge '請初步檢查這段 Rust 程式碼的錯誤處理與風險。'

同時使用 prompt 與 stdin：

cat docs/spec.md | ask-bridge '請根據下列規格產生實作檢查清單。'

在非互動式 agent 環境中，若已提供 prompt argument，但 stdin 管道保持開啟且沒有送入資料，工具最多等待 2 秒後會只使用 prompt argument 繼續執行。若沒有 prompt argument，stdin 就是必要輸入；超過 2 秒仍無資料時，工具會印出等待診斷並持續等到收到資料或 EOF。

對完整文件、二進位文件或多檔案使用 --file：

ask-bridge '請摘要這份規格文件，列出實作需求與待釐清問題。' --file docs/spec.md
ask-bridge '請比較這兩份文件的差異。' --file old.md --file new.md
ask-bridge --provider gemini '請摘要這份 PDF。' --file report.pdf

對圖片使用 --image，目前支援 ChatGPT 與 Claude：

ask-bridge '請描述這張截圖中的 UI 問題，並列出可能的 CSS 原因。' --image screenshot.png
ask-bridge '請比較這兩張圖的差異。' --image before.png --image after.png
ask-bridge --provider claude '請描述這張截圖中的 UI 問題。' --image screenshot.png

同時附加圖片與文件時，使用 ChatGPT 或 Claude：

ask-bridge '請對照設計圖與規格文件，列出不一致處。' --image design.png --file spec.md

輸出與下載

將 Markdown 回覆寫入檔案：

ask-bridge '請整理這份輸入的重點與待辦。' --file notes.md --output /tmp/ask-notes.md
ask-bridge '請整理這份輸入的重點與待辦。' --file notes.md -o /tmp/ask-notes.md

下載 provider 回覆中的生成圖片：

ask-bridge '請產生一張產品概念圖。' --image-output /tmp/ask-images/
ask-bridge '請產生一張產品概念圖。' -i /tmp/product-concept.png

若可接受輸出同時包含 thread URL，也可使用 shell redirect：

ask-bridge '請整理這份輸入的重點與待辦。' --file notes.md > /tmp/ask-bridge-notes.md

一般提問完成後，終端機還會輸出目前 provider 對話的 thread URL。--output 寫入的是純 Markdown 回覆，不包含該 URL；需要後續接續或稽核對話時，另外保留終端機輸出的連結。

逾時控制

一般回覆與手動登入偵測預設最多等待 300 秒。預期長回覆時提高上限：

ask-bridge '請完整分析這份報告。' --file report.pdf --timeout 600
ask-bridge --timeout 600 login

--timeout 必須是大於 0 的整數。一般回覆逾時時，工具會停止等待並輸出警告；不要把空白或未完成的輸出當成有效回覆。登入逾時只代表仍未偵測到完成狀態，需檢查瀏覽器後再決定是否重試。

模型與推理模式切換

模型與推理模式是兩個獨立參數：

ask-bridge '證明這個數學問題。' --model 'GPT-5.6 Sol' --reasoning high
ask-bridge '快速翻譯這段話。' --reasoning instant
ask-bridge --provider gemini '用幾句話介紹 Rust。' --model '3.6 Flash'
ask-bridge --provider gemini '證明這個數學問題。' --model '3.1 Pro' --reasoning extended
ask-bridge --provider claude '用幾句話介紹 Rust。' --model Sonnet

ChatGPT 的 --reasoning 支援 instant、medium、high、xhigh 與對應中文別名（新版推理滑桿已無「自動」）；ask-bridge 一律使用 ChatGPT「對話（Chat）」模式，不使用「工作（Work）」模式；Gemini 只支援 extended，且不能搭配非 Pro 模型；Claude 不支援 --reasoning。

模型只比對 provider 選單的主標籤，忽略副標題與 badge，且不會把不存在的舊版本自動對應到其他版本。若切換失敗，應依錯誤列出的目前選項修正參數，不要猜測替代模型名稱。舊用法 --model 高 與 --model 延伸思考 暫時可用，但應改成 --reasoning。

ChatGPT Agent 提及語法

使用 ChatGPT 時，prompt 可以採用 @Agent名稱 prompt正文 格式。符合格式時，ask-bridge 會先輸入 Agent mention、等待候選選單出現，再按 Tab 接受 UI 當下的預設選取項，最後輸入正文。此流程不會驗證候選是否與輸入的 Agent 名稱完全相符。

語法與限制

• 格式：@Agent名稱 prompt正文
• 名稱限制：Agent 名稱必須由 1 至 10 個非空白字元組成。
• 正文限制：Agent 名稱後必須至少有一個空白，且去除前導空白後的正文不可為空。
• Provider 限制：特殊處理只適用於 ChatGPT；Gemini 與 Claude 會將相同內容視為一般文字 prompt。
• Fallback：格式不符合時，不會觸發 Agent mention 流程，而會按照一般 prompt 處理。

使用範例

ask-bridge --provider chatgpt \
  '@研究助手 請摘要這份規格並列出風險。' \
  --file docs/spec.md

ask-bridge --provider chatgpt \
  '@程式審查 請檢查這份程式碼的風險。' \
  --file src/main.rs

對話與瀏覽器控制

需要隔離上下文時使用 --new：

ask-bridge '請只根據本次輸入分析，不要沿用既有對話脈絡。' --new

需要沿用網頁端既有對話脈絡時，傳入對話 ID 或完整 URL：

ask-bridge --provider chatgpt --session-id 'conversation-uuid' '請接續先前的規劃。'
ask-bridge --session-url 'https://chatgpt.com/c/conversation-uuid' '請產出下一步計畫。'

完整 URL 會辨識 provider；若同時明確指定不同的 --provider，命令會停止。 不要使用對話標題猜測 session，也不要將 --session 與 --new 同時使用。

一般提問預設 --headless=true。需要觀察 Chrome 操作時使用：

ask-bridge '請回覆 ok' --headless=false
ask-bridge '請回覆 ok' --verbose --headless=false

關閉 ask-bridge 管理的 Chrome instance：

ask-bridge close

close 只應關閉 ask-bridge 使用的 debug profile 與 debug port instance。若 port 被非 ask-bridge Chrome 程序占用，工具應回報錯誤而不是關閉它。

子命令速查

公開子命令：

子命令	用途	範例
login	開啟 provider 並等待使用者手動登入	ask-bridge login、ask-bridge --provider gemini login、ask-bridge --provider claude login
close	關閉 ask-bridge 管理的 Chrome instance	ask-bridge close
config	顯示或設定全域預設 provider	ask-bridge config、ask-bridge config --provider claude
update	依作業系統執行官方安裝流程並重新安裝	ask-bridge update
help	顯示 help	ask-bridge help、ask-bridge help login

隱藏或維護用子命令：

子命令	用途	範例
open [url]	不帶 URL 時開啟 provider；帶 URL 時開啟該對話並複製最新回覆	ask-bridge open、ask-bridge open 'https://chatgpt.com/c/...'
get [url]	從目前 provider 或指定 URL 取得最新回覆；目前固定使用可見瀏覽器	ask-bridge get、ask-bridge -o /tmp/reply.md get 'https://gemini.google.com/app/...'
dump	將目前分頁 HTML 寫到 target/dump.html，供除錯使用	ask-bridge --verbose dump
screenshot	將目前分頁截圖寫到 target/screenshot.png，供除錯使用	ask-bridge --headless=false screenshot

open、get、dump、screenshot 可能不出現在一般 --help 中。除錯或維護 ask-bridge 自動化流程時才使用隱藏子命令；一般委派任務優先使用 prompt、--file、--image、--output 與 --image-output。

update 會修改目前安裝內容並使用網路：macOS/Linux 執行 README 的官方安裝流程，Windows 則啟動更新輔助程式或回退到 PowerShell 安裝流程。不要把版本查詢誤當成更新需求；只查版本時使用 ask-bridge -v。

執行與診斷特性

• 每次 CLI 執行會重用同一個長連線 chrome-devtools-mcp 子程序，不會為每個瀏覽器操作重啟 MCP server。
• 專案目前固定使用 [email protected]，並直接透過內建的 mcp-cli Rust library 建立 stdio 連線；不需要另外安裝 mcp-cli 執行檔。
• MCP 連線建立上限為 120 秒，單次 MCP tool 呼叫上限為 90 秒。這兩個內部上限與使用者設定的 --timeout 不同；--timeout 只控制 provider 回覆與登入偵測等待時間。
• MCP 設定、日誌與 Chrome profile 分別位於 ~/.config/ask-bridge/mcp_servers.json、~/.config/ask-bridge/chrome-devtools-mcp.log 與 ~/.config/ask-bridge/chrome-profile。Chrome 使用遠端除錯 port 9223。

使用回覆

將回覆視為外部建議：

• 先閱讀並萃取可驗證的部分，再套用到本機工作。
• 對程式建議，仍需讀原始碼、修改檔案並執行測試。
• 對最新資訊或官方規格，必須再用可靠來源查證。
• 對不確定或互相矛盾的結果，保留疑點，不要包裝成確定結論。

失敗處理

登入、CAPTCHA、Cloudflare 或 session 失效時，要求使用者完成 ask-bridge login，或在允許互動式瀏覽器時執行登入流程。

provider UI 變更或自動化失敗時，使用 --verbose 取得診斷資訊；必要時用 --headless=false 觀察瀏覽器狀態：

ask-bridge '請回覆 ok' --verbose
ask-bridge '請回覆 ok' --headless=false
ask-bridge --verbose dump
ask-bridge --headless=false screenshot

Gemini 圖片輸入不支援時，改用 ChatGPT 或 Claude，或改以文字描述圖片內容。不要把同一個失敗命令無限制重試。

模型切換失敗時，移除 --model 或改用 provider 預設模型，不要猜測替代模型名稱。

若看到 MCP tool 逾時、傳輸程序結束或 MCP session was reset; re-run the command，工具已重設該次執行的持久 MCP session。先保留原始錯誤，再安全地重跑命令一次；涉及送出 prompt 的失敗不要連續盲目重試，以免 provider 已收到前一次請求。

沒有 prompt 且沒有子命令時，ask-bridge 會顯示 help。若任務需要非互動輸出，優先搭配 --output 或 shell redirect，避免只依賴終端機渲染結果。