| name | ask-bridge |
| description | 完整使用 ask-bridge CLI 的 Agent Skill。使用 ask-bridge 將低風險、探索性 AI 研究、摘要、文件分析、程式片段分析、錯誤訊息整理、方案比較、初稿產出或可委派的背景調查交給 ChatGPT、Gemini 或 Claude 網站。當 Codex 需要透過本機 ask-bridge 命令呼叫網站型 AI、利用 ChatGPT/Gemini/Claude 網頁額度、附加檔案或圖片、切換模型、設定逾時、取回或儲存回覆、下載生成圖片、管理瀏覽器 session、更新 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 優先序：
- CLI
--provider chatgpt|gemini|claude
~/.config/ask-bridge/config.json 的 provider- 內建預設
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 與帳號權限 |
只有 --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 支援 auto、instant、medium、high 與對應中文別名；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。
- 專案目前固定使用
chrome-devtools-mcp@1.7.0，並直接透過內建的 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，避免只依賴終端機渲染結果。
