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 ...。

プロバイダーの選択

デフォルトでは ChatGPT を使用します：

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

Gemini または Claude を使用する場合は、プロバイダーを明示的に指定します：

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

選択の原則：

• --provider が指定されていない場合は、まずグローバル設定ファイルに基づいてプロバイダーを選択し、設定ファイルが存在しない場合は ChatGPT を使用します。
• 未設定時のデフォルトプロバイダーとして ChatGPT を使用します。
• 代替の視点や迅速な要約が必要な場合、またはユーザーから明示的に Gemini を求められた場合は Gemini を使用します。
• コード分析、長文の要約、代替の視点が必要な場合、またはユーザーから明示的に Claude を求められた場合は Claude を使用します。Claude は --image による画像入力にも対応しています。
• プロバイダーが失敗した場合は、リスクを増やさずに済む場合に限り、別のプロバイダーに一度切り替えることができます。
• 存在しないモデル名を決めつけて指定しないでください。--model を使用するのは、ユーザーが指定した場合、またはプロジェクトのドキュメントに明記されている場合に限ります。

プロンプトの組み立て

委任するプロンプトには、明確な出力要件を含めます：

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

プロンプトは要点を絞ってください。大規模なタスクでは、まずプロバイダーに要約または候補リストを生成させてから、ローカルエージェントが2回目の委任が必要かどうかを判断します。

入力データ

短いテキストには引数を使用します：

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

コードスニペットやコマンド出力には stdin を使用します：

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

プロンプトと stdin の両方を使用します：

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

非対話型のエージェント環境で、プロンプト引数が指定されている一方、stdin パイプが開いたままでデータが送られていない場合、ツールは最大 2 秒待機した後、プロンプト引数のみを使用して処理を続行します。プロンプト引数が指定されていない場合、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

プロバイダーの応答に含まれる生成画像をダウンロードします：

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

出力にスレッド URL が含まれても問題ない場合は、シェルのリダイレクトも使用できます：

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

通常の質問が完了すると、現在のプロバイダーとの会話のスレッド URL もターミナルに出力されます。--output に書き込まれるのは純粋な Markdown の応答であり、その URL は含まれません。後で会話を続けたり監査したりする必要がある場合は、ターミナルに出力されたリンクを別途保存してください。

タイムアウトの制御

通常の応答と手動ログインの検出では、デフォルトで最大 300 秒待機します。長い応答が予想される場合は、上限を引き上げます：

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

--timeout は 0 より大きい整数でなければなりません。通常の応答がタイムアウトした場合、ツールは待機を停止して警告を出力します。空の出力や未完了の出力を有効な応答として扱わないでください。ログインのタイムアウトは、完了状態がまだ検出されていないことだけを示します。ブラウザーを確認してから、再試行するかどうかを判断してください。

モデルと推論モードの切り替え

モデルと推論モードは、独立した2つのパラメーターです：

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 をサポートしていません。

モデル名はプロバイダーのメニューに表示されるメインラベルのみで照合され、副題やバッジは無視されます。また、存在しない旧バージョンが別のバージョンに自動的に割り当てられることはありません。切り替えに失敗した場合は、エラーに表示された現在の選択肢に従ってパラメーターを修正し、代替モデル名を推測しないでください。旧形式の --model 高 と --model 延伸思考 は当面使用できますが、--reasoning に変更してください。

ChatGPT Agent のメンション構文

ChatGPT を使用する場合、プロンプトは @Agent名称 prompt正文 の形式にできます。この形式に一致すると、ask-bridge はまず Agent メンションを入力し、候補メニューが表示されるまで待機してから、Tab を押して UI 上で現在デフォルト選択されている項目を確定し、最後に本文を入力します。この手順では、候補が入力された Agent 名と完全に一致するかどうかは検証されません。

構文と制限

• 形式：@Agent名称 prompt正文
• 名前の制限：Agent 名は、空白以外の文字を1～10文字で構成する必要があります。
• 本文の制限：Agent 名の後に少なくとも1つの空白が必要です。また、先頭の空白を除去した後の本文は空であってはなりません。
• プロバイダーの制限：特殊な処理は ChatGPT のみに適用されます。Gemini と Claude では、同じ内容を通常のテキストプロンプトとして扱います。
• フォールバック：形式に一致しない場合、Agent メンションの処理は実行されず、通常のプロンプトとして処理されます。

使用例

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 も明示的に指定されている場合、コマンドは停止します。 会話タイトルからセッションを推測しないでください。また、--session と --new を同時に使用しないでください。

通常の質問では、デフォルトで --headless=true が指定されます。Chrome の操作を確認する必要がある場合は、次のようにします：

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

ask-bridge が管理する Chrome インスタンスを終了します：

ask-bridge close

close は、ask-bridge が使用するデバッグプロファイルとデバッグポートのインスタンスのみを終了します。ポートが ask-bridge 以外の Chrome プロセスに使用されている場合、ツールはそのプロセスを終了せず、エラーを報告する必要があります。

サブコマンド一覧

公開サブコマンド：

サブコマンド	用途	例
login	プロバイダーを開き、ユーザーが手動でログインするまで待機します	ask-bridge login、ask-bridge --provider gemini login、ask-bridge --provider claude login
close	ask-bridge が管理する Chrome インスタンスを終了します	ask-bridge close
config	グローバルなデフォルトプロバイダーを表示または設定します	ask-bridge config、ask-bridge config --provider claude
update	OS に応じて公式のインストール手順を実行し、再インストールします	ask-bridge update
help	ヘルプを表示します	ask-bridge help、ask-bridge help login

非表示または保守用のサブコマンド：

サブコマンド	用途	例
open [url]	URL を指定しない場合はプロバイダーを開き、URL を指定した場合はその会話を開いて最新の応答をコピーします	ask-bridge open、ask-bridge open 'https://chatgpt.com/c/...'
get [url]	現在のプロバイダーまたは指定 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 の自動化ワークフローのデバッグや保守を行う場合にのみ使用してください。通常の委任タスクでは、プロンプト、--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，避免只依賴終端機渲染結果。