ask-bridge 0.1.1 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.en.md CHANGED
@@ -1,9 +1,26 @@
1
1
  # Ask Bridge 🦀
2
2
 
3
- `ask` is a powerful, lightweight command-line tool written in **Rust** that automates ChatGPT or Gemini directly in your real Chrome browser. It uses the **Model Context Protocol (MCP)** and **Chrome DevTools Protocol (CDP)** via the embedded `doggy8088/mcp-cli` Rust library dependency and `chrome-devtools-mcp` to control Chrome, input prompts, click submit, and print the response back to your terminal. ChatGPT is the default provider; use `--provider gemini` to switch to Gemini.
3
+ `ask-bridge` is a powerful, lightweight command-line tool written in **Rust** that automates ChatGPT or Gemini directly in your real Chrome browser. It uses the **Model Context Protocol (MCP)** and **Chrome DevTools Protocol (CDP)** via the embedded `doggy8088/mcp-cli` Rust library dependency and `chrome-devtools-mcp` to control Chrome, input prompts, click submit, and print the response back to your terminal. ChatGPT is the default when no global provider is configured; use `--provider gemini` or the global config file to switch to Gemini.
4
4
 
5
- Unlike typical API clients, `ask` operates inside a real Chrome browser with a **persistent user profile**. This means:
6
- - You log in manually **once** (`ask login`).
5
+ ## Design Intent
6
+
7
+ The core purpose of `ask-bridge` is not to replace ChatGPT, Gemini, or any Coding Agent. It is to bridge them together. During software development, many AI-assisted tasks are exploratory: researching background information, summarizing documents, comparing options, digesting error messages, analyzing code snippets, drafting text, or clarifying uncertain technical questions. These tasks do not always need to be handled directly by the primary Coding Agent, and they do not always justify using the same agent budget that should be reserved for code editing, testing, refactoring, and integration work.
8
+
9
+ With `ask-bridge`, a Coding Agent can delegate low-risk, exploratory, and research-oriented tasks to the ChatGPT or Gemini websites, then bring the website response back into the terminal or the next step of the local workflow. Because ChatGPT and Gemini website usage quotas are typically separate from Coding Agent execution quotas, `ask-bridge` gives developers a more flexible way to allocate AI resources: the primary agent can focus on understanding the repository, modifying code, running tests, and integrating results, while website-based AI handles background research, text processing, and candidate solution generation.
10
+
11
+ In other words, `ask-bridge` is an external research bridge for AI Agents. It turns the manual workflow of switching to a browser, pasting a prompt, waiting for a response, and copying the result back into a command-line-driven automation capability. This lets an agent request help from ChatGPT or Gemini without leaving the local development workflow, then use the response as supporting context for its own judgment.
12
+
13
+ This tool is especially useful for:
14
+
15
+ - Sending large documents, error messages, or code snippets to a website-based AI for summarization, comparison, or first-pass analysis.
16
+ - Letting a Coding Agent outsource background research, alternative analysis, or checklist generation before implementation.
17
+ - Moving AI tasks that do not directly modify project files out of the primary agent workflow.
18
+ - Reusing existing ChatGPT or Gemini web accounts for interactive website features outside an API workflow.
19
+
20
+ `ask-bridge` does not guarantee that provider output is correct, and it should not replace local tests, official documentation checks, or human review. Its role is to reduce the operational cost of exploratory AI work and let the primary Coding Agent obtain external AI assistance with less friction.
21
+
22
+ Unlike typical API clients, `ask-bridge` operates inside a real Chrome browser with a **persistent user profile**. This means:
23
+ - You log in manually **once** (`ask-bridge login`).
7
24
  - You can solve CAPTCHAs, pass provider-side browser checks, and access the selected provider's web features like a normal user.
8
25
  - Your session cookies, login state, and chat history are saved persistently.
9
26
 
@@ -13,12 +30,13 @@ Unlike typical API clients, `ask` operates inside a real Chrome browser with a *
13
30
 
14
31
  - **🦀 100% Rust Core**: Extremely fast, lightweight, and compile-once, run-anywhere binary.
15
32
  - **Multi-provider support**: Choose ChatGPT or Gemini with `--provider chatgpt|gemini`.
33
+ - **Global provider config**: Set the default provider in `~/.config/ask-bridge/config.json`; CLI `--provider` overrides the config file.
16
34
  - **🌐 Real Browser Automation**: Directly interacts with Chrome on port `9223` (isolated debug profile).
17
35
  - **🔒 Persistent Login**: Uses a dedicated local profile directory (`~/.config/ask-bridge/chrome-profile`) so you never lose your login state.
18
36
  - **Response Output**: Prints the selected provider's response back to your terminal.
19
37
  - **🌀 TUI Thinking Animation**: Displays a rotating spinner while waiting for the provider to reply, then clears it once output starts.
20
38
  - **🧠 Intelligent Tab Management**: Reuses existing provider tabs if open, focuses them, or opens new ones, avoiding tab clutter.
21
- - **🖥️ Pipe & Stdin Support**: Supports piping prompts via `stdin` (e.g. `cat report.txt | ask "summarize this"`).
39
+ - **🖥️ Pipe & Stdin Support**: Supports piping prompts via `stdin` (e.g. `cat report.txt | ask-bridge "summarize this"`).
22
40
  - **📎 Image & File Attachments**: Attach local images to ChatGPT with `--image`, or documents (PDF, Word, Excel, plain text, Markdown, JSON, etc.) with `--file`; Gemini currently supports `--file` and rejects `--image`.
23
41
  - **🔀 Model Switching**: Use `--model` to switch the provider model before the prompt is sent, such as ChatGPT `GPT-5.4` or Gemini `3.5 Flash`.
24
42
  - **🔍 Quiet by Default & Verbose Mode**: Quiet and clean output by default (displaying only the generated response), with an optional `--verbose` flag to display full browser state logs if needed.
@@ -30,9 +48,22 @@ Unlike typical API clients, `ask` operates inside a real Chrome browser with a *
30
48
 
31
49
  To run this tool, you need:
32
50
 
33
- 1. **`node`/`npx`** installed to automatically launch the `chrome-devtools-mcp` server.
51
+ 1. **Node.js 20.19.0 LTS or newer LTS**, with both `node` and `npx` available in the current shell's `PATH`. `ask-bridge` starts `chrome-devtools-mcp@latest` through `npx`; older Node.js versions, such as `v20.11.0`, can cause the MCP server to exit during `initialize`.
34
52
  2. **Google Chrome** installed (normally located at `/Applications/Google Chrome.app` on macOS). `make install` installs it with Homebrew when it is missing and Homebrew is available.
35
53
 
54
+ Check the Node.js version visible to your current shell:
55
+
56
+ ```bash
57
+ node -v
58
+ npx -v
59
+ ```
60
+
61
+ | Platform | Notes |
62
+ | --- | --- |
63
+ | macOS | Install a Node.js LTS release with Homebrew or nvm. If you use nvm, make sure the same shell that runs `ask-bridge` has loaded nvm and that `node -v` reports `v20.19.0` or newer. Chrome is detected at `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` by default. |
64
+ | Windows | Install a Node.js LTS release with the official installer, winget, or nvm-windows. Reopen PowerShell after installation, then verify that `node -v` and `npx -v` work. Chrome is detected from the standard `Program Files`, `Program Files (x86)`, and `%LOCALAPPDATA%` install paths. |
65
+ | Linux | Distribution package repositories may provide an older Node.js version. Prefer NodeSource, nvm, or an official Node.js LTS source. Install Google Chrome Stable and make sure `google-chrome` or `google-chrome-stable` is available in `PATH`; Snap, Flatpak, or Chromium installs may not match the default detection logic. |
66
+
36
67
  You do **not** need a global `mcp-cli` executable. The Rust binary uses `mcp-cli` as a Cargo dependency from `https://github.com/doggy8088/mcp-cli`.
37
68
 
38
69
  ---
@@ -57,6 +88,7 @@ irm https://raw.githubusercontent.com/doggy8088/ask-bridge/main/install.ps1 | ie
57
88
 
58
89
  > [!NOTE]
59
90
  > Make sure the installation path (`~/.local/bin` for macOS/Linux, and `$HOME\.local\bin` for Windows) is added to your system's `PATH` environment variable.
91
+ > The formal CLI command is `ask-bridge`; the installer also provides `ask` as a backward-compatible alias. The examples below use `ask-bridge`.
60
92
 
61
93
  ### 2. Build & Install from Source (For Developers)
62
94
 
@@ -66,7 +98,7 @@ Clone or navigate to the project directory and build/install with Make:
66
98
  make install
67
99
  ```
68
100
 
69
- This verifies the Node.js environment, installs the required Chrome browser if needed, builds the optimized binary, and links it to `~/.local/bin/ask`.
101
+ This verifies the Node.js environment, installs the required Chrome browser if needed, builds the optimized binary, links the formal command to `~/.local/bin/ask-bridge`, and also creates the `ask` alias.
70
102
 
71
103
  ### 3. Build Only
72
104
 
@@ -78,22 +110,38 @@ cargo build --release
78
110
 
79
111
  The compiled binary will be located at `target/release/ask-bridge`.
80
112
 
113
+ ### 4. Install the Agent Skill
114
+
115
+ This repository provides an `ask-bridge` Agent Skill so Skills-compatible Coding Agents can use `ask-bridge` to delegate exploratory research, summarization, document analysis, or option comparison tasks to the ChatGPT or Gemini websites.
116
+
117
+ Install it with `npx skills`; you do not need to copy the `skills/` directory manually:
118
+
119
+ ```bash
120
+ npx skills add doggy8088/ask-bridge --skill ask-bridge
121
+ ```
122
+
123
+ To install it globally for Codex, specify the agent and global scope:
124
+
125
+ ```bash
126
+ npx skills add doggy8088/ask-bridge --skill ask-bridge --agent codex --global
127
+ ```
128
+
81
129
  ---
82
130
 
83
131
  ## 📖 Usage Guide
84
132
 
85
133
  ### 1. First Time Setup: Login to a provider
86
134
 
87
- Before sending prompts, you need to log in to the selected provider. ChatGPT is the default:
135
+ Before sending prompts, you need to log in to the selected provider. ChatGPT is the default when no global provider is configured:
88
136
 
89
137
  ```bash
90
- ask login
138
+ ask-bridge login
91
139
  ```
92
140
 
93
141
  For Gemini:
94
142
 
95
143
  ```bash
96
- ask --provider gemini login
144
+ ask-bridge --provider gemini login
97
145
  ```
98
146
 
99
147
  - This will automatically launch Google Chrome with a dedicated, persistent debug profile.
@@ -101,13 +149,39 @@ ask --provider gemini login
101
149
  - Once logged in, return to your terminal and press **`[Enter]`**.
102
150
  - The tool will verify your login status and save your profile. You only need to do this **once**!
103
151
 
152
+ #### Global Provider Config
153
+
154
+ To use Gemini by default when `--provider` is not specified:
155
+
156
+ ```bash
157
+ ask-bridge config --provider gemini
158
+ ```
159
+
160
+ To switch the default back to ChatGPT:
161
+
162
+ ```bash
163
+ ask-bridge config --provider chatgpt
164
+ ```
165
+
166
+ You can check the current setting with:
167
+
168
+ ```bash
169
+ ask-bridge config
170
+ ```
171
+
172
+ `--provider` has higher priority than the global config file, so this command temporarily uses ChatGPT:
173
+
174
+ ```bash
175
+ ask-bridge --provider chatgpt "Summarize this text."
176
+ ```
177
+
104
178
  ### 2. Send Prompts Directly
105
179
 
106
180
  Simply pass your prompt as an argument:
107
181
 
108
182
  ```bash
109
- ask "What is the difference between a struct and a tuple in Rust?"
110
- ask --provider gemini "What is the difference between a struct and a tuple in Rust?"
183
+ ask-bridge "What is the difference between a struct and a tuple in Rust?"
184
+ ask-bridge --provider gemini "What is the difference between a struct and a tuple in Rust?"
111
185
  ```
112
186
 
113
187
  - Chrome will open or focus on your selected provider tab.
@@ -116,12 +190,12 @@ ask --provider gemini "What is the difference between a struct and a tuple in Ru
116
190
 
117
191
  ### 3. Open a Brand New Session (`--new`)
118
192
 
119
- By default, `ask` will reuse any existing open tab for the selected provider to avoid cluttering your browser with too many tabs.
193
+ By default, `ask-bridge` will reuse any existing open tab for the selected provider to avoid cluttering your browser with too many tabs.
120
194
 
121
195
  If you want to start a **completely fresh conversation session** (equivalent to clicking "New Chat" in the sidebar), use the `--new` flag:
122
196
 
123
197
  ```bash
124
- ask "誰是保哥?" --new
198
+ ask-bridge "誰是保哥?" --new
125
199
  ```
126
200
 
127
201
  - This will open a **brand new selected-provider tab**.
@@ -134,19 +208,19 @@ By default, standard queries run Chrome in **headless mode** (`--headless=true`)
134
208
  If you want to watch Chrome work in real-time or need to manually check what's happening on the page, you can run in **headful mode** by setting `--headless=false`:
135
209
 
136
210
  ```bash
137
- ask "誰是保哥?" --headless=false
211
+ ask-bridge "誰是保哥?" --headless=false
138
212
  ```
139
213
 
140
- *Note: `ask login` always overrides the default and runs in **headful mode** so you can interact with the UI. For other subcommands, pass `--headless=false` when you want a visible browser.*
214
+ *Note: `ask-bridge login` always overrides the default and runs in **headful mode** so you can interact with the UI. For other subcommands, pass `--headless=false` when you want a visible browser.*
141
215
 
142
216
  ### 5. Verbose Mode (`--verbose`)
143
217
 
144
- By default, `ask` runs in a **quiet, clean mode** that hides all background browser-control logs (such as "Checking open Chrome tabs...", "Typing prompt...", etc.) and only displays the final markdown answer. However, it still plays an animated rotating spinner in your terminal while waiting for the provider to generate a response.
218
+ By default, `ask-bridge` runs in a **quiet, clean mode** that hides all background browser-control logs (such as "Checking open Chrome tabs...", "Typing prompt...", etc.) and only displays the final markdown answer. However, it still plays an animated rotating spinner in your terminal while waiting for the provider to generate a response.
145
219
 
146
- If you want to see detailed step-by-step status logs of what `ask` is doing behind the scenes, add the `--verbose` flag:
220
+ If you want to see detailed step-by-step status logs of what `ask-bridge` is doing behind the scenes, add the `--verbose` flag:
147
221
 
148
222
  ```bash
149
- ask "誰是保哥?" --verbose
223
+ ask-bridge "誰是保哥?" --verbose
150
224
  ```
151
225
 
152
226
  This will print every stage of the browser automation:
@@ -161,27 +235,27 @@ This will print every stage of the browser automation:
161
235
  Use `-v` or `--version` to print the current version number:
162
236
 
163
237
  ```bash
164
- ask -v
238
+ ask-bridge -v
165
239
  ```
166
240
 
167
241
  ### 7. Piping & Stdin Support
168
242
 
169
- You can pipe text or files directly into `ask`:
243
+ You can pipe text or files directly into `ask-bridge`:
170
244
 
171
245
  ```bash
172
- echo "Explain quantum computing in one sentence" | ask
246
+ echo "Explain quantum computing in one sentence" | ask-bridge
173
247
  ```
174
248
 
175
- When you also pass a prompt argument, `ask` uses the prompt first and then appends stdin content after two newlines:
249
+ When you also pass a prompt argument, `ask-bridge` uses the prompt first and then appends stdin content after two newlines:
176
250
 
177
251
  ```bash
178
- cat /Users/will/.copilot/session-state/46cc0f1c-79fd-4622-9548-a0b7fa3794be/research/does-cursor-support-byok.md | ask 'What is this?'
252
+ cat /Users/will/.copilot/session-state/46cc0f1c-79fd-4622-9548-a0b7fa3794be/research/does-cursor-support-byok.md | ask-bridge 'What is this?'
179
253
  ```
180
254
 
181
255
  Or read files:
182
256
 
183
257
  ```bash
184
- cat src/main.rs | ask "Are there any memory leaks in this Rust code?"
258
+ cat src/main.rs | ask-bridge "Are there any memory leaks in this Rust code?"
185
259
  ```
186
260
 
187
261
  ### 8. Attaching Images or Files
@@ -193,8 +267,8 @@ Instead of piping file contents into the prompt, you can upload local files as a
193
267
  Use `--image` (repeatable) to attach one or more local images. This currently supports ChatGPT; Gemini image input is not enabled and exits with an explicit error when used with `--provider gemini`.
194
268
 
195
269
  ```bash
196
- ask "Describe this image." --image screenshot.png
197
- ask "Compare these two images." --image v1.png --image v2.png
270
+ ask-bridge "Describe this image." --image screenshot.png
271
+ ask-bridge "Compare these two images." --image v1.png --image v2.png
198
272
  ```
199
273
 
200
274
  Supported formats include PNG, JPEG, GIF, WebP, SVG, BMP, and more.
@@ -204,15 +278,15 @@ Supported formats include PNG, JPEG, GIF, WebP, SVG, BMP, and more.
204
278
  Use `--file` (repeatable) to attach documents such as PDF, Word, Excel, PowerPoint, plain text, Markdown, CSV, JSON, or source code. This flow supports both ChatGPT and Gemini.
205
279
 
206
280
  ```bash
207
- ask "Summarize this PDF." --file report.pdf
208
- ask "How many rows are in this CSV?" --file data.csv
209
- ask "Check this code for issues." --file src/main.rs
281
+ ask-bridge "Summarize this PDF." --file report.pdf
282
+ ask-bridge "How many rows are in this CSV?" --file data.csv
283
+ ask-bridge "Check this code for issues." --file src/main.rs
210
284
  ```
211
285
 
212
286
  You can attach images and documents at the same time:
213
287
 
214
288
  ```bash
215
- ask "Compare this design image against the spec document and list inconsistencies." --image design.png --file spec.docx
289
+ ask-bridge "Compare this design image against the spec document and list inconsistencies." --image design.png --file spec.docx
216
290
  ```
217
291
 
218
292
  ### 9. Switch Model
@@ -220,11 +294,11 @@ ask "Compare this design image against the spec document and list inconsistencie
220
294
  Use `--model` to automatically switch the provider model before the prompt is sent. Matching is case- and punctuation-insensitive (`-`, `.`, spaces, etc. are ignored).
221
295
 
222
296
  ```bash
223
- ask "Introduce Rust in a few sentences." --model GPT-5.4
224
- ask "Prove this math problem." --model o3
225
- ask "Quickly translate this." --model 即時
226
- ask --provider gemini "Introduce Rust in a few sentences." --model "3.5 Flash"
227
- ask --provider gemini "Introduce Rust in a few sentences." --model "3.1 Pro"
297
+ ask-bridge "Introduce Rust in a few sentences." --model GPT-5.4
298
+ ask-bridge "Prove this math problem." --model o3
299
+ ask-bridge "Quickly translate this." --model 即時
300
+ ask-bridge --provider gemini "Introduce Rust in a few sentences." --model "3.5 Flash"
301
+ ask-bridge --provider gemini "Introduce Rust in a few sentences." --model "3.1 Pro"
228
302
  ```
229
303
 
230
304
  Available model names (depending on your account entitlements and provider UI):
@@ -233,34 +307,34 @@ Available model names (depending on your account entitlements and provider UI):
233
307
  - **ChatGPT thinking levels**: `智慧`, `即時`, `中等`, `高`, `超高`, `專業`
234
308
  - **Gemini modes**: `3.5 Flash`, `3.1 Flash-Lite`, `3.1 Pro`
235
309
 
236
- > If the requested name is not found in the menu, `ask` reports `Model switch failed: error: model not found in menu` and aborts without submitting the prompt.
310
+ > If the requested name is not found in the menu, `ask-bridge` reports `Model switch failed: error: model not found in menu` and aborts without submitting the prompt.
237
311
 
238
312
  ### 10. Just Open a Provider
239
313
 
240
314
  To quickly launch the browser and open the selected provider without sending any query:
241
315
 
242
316
  ```bash
243
- ask open
244
- ask --provider gemini open
317
+ ask-bridge open
318
+ ask-bridge --provider gemini open
245
319
  ```
246
320
 
247
321
  ### 11. Close the Browser Instance
248
322
 
249
- To close the Chrome debug profile instance managed by `ask`:
323
+ To close the Chrome debug profile instance managed by `ask-bridge`:
250
324
 
251
325
  ```bash
252
- ask close
326
+ ask-bridge close
253
327
  ```
254
328
 
255
- `close` only shuts down the `ask` Chrome instance that uses `~/.config/ask-bridge/chrome-profile` and listens on debug port `9223`. If that port is occupied by a non-`ask` Chrome process, it reports an error instead of closing it.
329
+ `close` only shuts down the `ask-bridge` Chrome instance that uses `~/.config/ask-bridge/chrome-profile` and listens on debug port `9223`. If that port is occupied by a non-`ask-bridge` Chrome process, it reports an error instead of closing it.
256
330
 
257
331
  ---
258
332
 
259
333
  ## ⚙️ How It Works (Under the Hood)
260
334
 
261
- 1. **Browser Initialization**: `ask` checks if Chrome is listening on debugging port `9223`. If not, it spawns Google Chrome as a background process with a custom profile directory (`~/.config/ask-bridge/chrome-profile`).
335
+ 1. **Browser Initialization**: `ask-bridge` checks if Chrome is listening on debugging port `9223`. If not, it spawns Google Chrome as a background process with a custom profile directory (`~/.config/ask-bridge/chrome-profile`).
262
336
  2. **MCP Bridge Config**: On startup, it automatically writes a custom `mcp_servers.json` to `~/.config/ask-bridge/mcp_servers.json`, configuring the Chrome DevTools MCP server by default with `chrome-devtools-mcp@latest` and `--browser-url=http://127.0.0.1:9223`.
263
- 3. **Client Call**: `ask` calls the embedded `doggy8088/mcp-cli` Rust library dependency, invoking `list_pages`, `select_page`, `type_text`, and `evaluate_script` tools to automate the DOM without relying on an external `mcp-cli` executable.
337
+ 3. **Client Call**: `ask-bridge` calls the embedded `doggy8088/mcp-cli` Rust library dependency, invoking `list_pages`, `select_page`, `type_text`, and `evaluate_script` tools to automate the DOM without relying on an external `mcp-cli` executable.
264
338
  4. **State Polling**: During generation, a lightweight JavaScript engine checks the provider's send/stop button states and extracts response element inner-text for terminal output.
265
339
 
266
340
  ---
package/README.md CHANGED
@@ -1,10 +1,27 @@
1
1
  # Ask Bridge 🦀
2
2
 
3
- `ask` 是以 Rust 撰寫的輕量命令列工具,可透過真實 Chrome 瀏覽器自動操作 ChatGPT 與 Gemini。它使用 Model Context Protocol MCP 與 Chrome DevTools Protocol CDP,並透過內建的 `doggy8088/mcp-cli` Rust library dependency 搭配 `chrome-devtools-mcp` 控制 Chrome、輸入 prompt、送出訊息,並將回覆輸出到終端機。預設 provider 為 ChatGPT,可用 `--provider gemini` 切換到 Gemini。
3
+ `ask-bridge` 是以 Rust 撰寫的輕量命令列工具,可透過真實 Chrome 瀏覽器自動操作 ChatGPT 與 Gemini。它使用 Model Context Protocol MCP 與 Chrome DevTools Protocol CDP,並透過內建的 `doggy8088/mcp-cli` Rust library dependency 搭配 `chrome-devtools-mcp` 控制 Chrome、輸入 prompt、送出訊息,並將回覆輸出到終端機。未設定全域 provider 時預設使用 ChatGPT,可用 `--provider gemini` 或全域設定檔切換到 Gemini。
4
4
 
5
- 不同於一般 API client,`ask` 會在真實 Chrome 瀏覽器中執行,並使用持久化的專屬使用者 profile。這表示:
5
+ ## 設計意圖
6
6
 
7
- - 只需要手動登入一次,透過 `ask login` 完成。
7
+ `ask-bridge` 的核心目的不是取代 ChatGPT、Gemini 或任何 Coding Agent,而是把它們橋接在一起。開發過程中常會出現大量探索性的 AI 需求,例如查資料、整理文件、比較方案、摘要錯誤訊息、分析程式片段、產生初稿或協助釐清不確定的技術問題。這類任務通常不一定需要由主要 Coding Agent 親自完成,也不一定值得消耗與程式碼編輯、測試、重構等高價值工作相同的 agent 額度。
8
+
9
+ 透過 `ask-bridge`,Coding Agent 可以把這些低風險、探索性、可委派的研究工作轉交給 ChatGPT 或 Gemini 網站處理,再把網站回覆取回終端機或後續工作流程中。由於 ChatGPT、Gemini 網站的使用額度與 Coding Agent 的執行額度通常分開計算,`ask-bridge` 可以讓開發者更有彈性地分配 AI 資源:主要 agent 專注在理解專案、修改程式、執行測試與整合結果;網站型 AI 則負責背景研究、文字處理與候選方案產出。
10
+
11
+ 換句話說,`ask-bridge` 是一個給 AI Agent 使用的外部研究橋接器:它把原本需要人類切換瀏覽器、貼上 prompt、等待回覆、再複製結果的流程,包裝成可由命令列驅動的自動化能力。這讓 agent 可以在不離開本機工作流程的情況下,自主向 ChatGPT 或 Gemini 發出請求,取得輔助資訊,並將其納入後續判斷。
12
+
13
+ 此工具特別適合:
14
+
15
+ - 將大型文件、錯誤訊息或程式片段交給網站型 AI 做摘要、比對或初步分析。
16
+ - 讓 Coding Agent 在實作前先委外蒐集背景資料、整理替代方案或產生檢查清單。
17
+ - 把不需要直接修改專案檔案的 AI 任務移出主要 agent 執行流程。
18
+ - 利用既有 ChatGPT 或 Gemini 網頁帳號的能力,處理 API 以外的互動式網站功能。
19
+
20
+ `ask-bridge` 不保證網站 provider 的輸出一定正確,也不應取代本機測試、官方文件查證或人工審查。它的定位是降低探索性 AI 工作的操作成本,讓主要 Coding Agent 能以更低摩擦取得外部 AI 協助。
21
+
22
+ 不同於一般 API client,`ask-bridge` 會在真實 Chrome 瀏覽器中執行,並使用持久化的專屬使用者 profile。這表示:
23
+
24
+ - 只需要手動登入一次,透過 `ask-bridge login` 完成。
8
25
  - 可處理 CAPTCHA、Cloudflare,並像一般使用者一樣存取所選 provider 的網頁功能。
9
26
  - Session cookies、登入狀態與對話紀錄會持久保存。
10
27
 
@@ -12,12 +29,13 @@
12
29
 
13
30
  - **100% Rust 核心**:快速、輕量,編譯後即可執行。
14
31
  - **多 provider 支援**:使用 `--provider chatgpt|gemini` 選擇 ChatGPT 或 Gemini。
32
+ - **全域 provider 設定**:可在 `~/.config/ask-bridge/config.json` 指定預設 provider,CLI 的 `--provider` 會覆蓋設定檔。
15
33
  - **真實瀏覽器自動化**:直接控制監聽 `9223` port 的 Chrome debug profile。
16
34
  - **持久登入狀態**:使用專屬本機 profile 目錄 `~/.config/ask-bridge/chrome-profile`,避免重複登入。
17
35
  - **回覆輸出**:所選 provider 產生回覆時,將內容輸出到終端機。
18
36
  - **思考動畫**:等待 provider 回覆時,在終端機顯示旋轉 spinner,開始輸出內容後自動清除。
19
37
  - **智慧分頁管理**:可重用既有 provider 分頁、聚焦分頁,或開啟新分頁,避免分頁過度增加。
20
- - **Pipe 與 stdin 支援**:支援透過 standard input 傳入 prompt,例如 `cat report.txt | ask "summarize this"`。
38
+ - **Pipe 與 stdin 支援**:支援透過 standard input 傳入 prompt,例如 `cat report.txt | ask-bridge "summarize this"`。
21
39
  - **圖片與文件上傳**:可透過 `--image` 附上 ChatGPT 圖片,或透過 `--file` 附上文件(PDF、Word、Excel、純文字、Markdown、JSON 等皆可),一次可指定多個檔案;Gemini 目前支援 `--file`,不支援 `--image` 圖片輸入。
22
40
  - **模型切換**:使用 `--model` 在送出 prompt 前自動切換 provider 模型(如 ChatGPT 的 `GPT-5.4`、`o3`,或 Gemini 的 `3.5 Flash`、`3.1 Pro`)。
23
41
  - **預設安靜模式與 verbose 模式**:預設只輸出最終回覆;加上 `--verbose` 可顯示背景瀏覽器控制流程。
@@ -27,9 +45,22 @@
27
45
 
28
46
  執行此工具需要:
29
47
 
30
- 1. 已安裝 `node` 與 `npx`,用於自動啟動 `chrome-devtools-mcp` server。
48
+ 1. 已安裝 **Node.js 20.19.0 LTS 以上,或更新的 LTS 版本**,並確保 `node` 與 `npx` 可在目前 shell 的 `PATH` 中執行。`ask-bridge` 會透過 `npx` 啟動 `chrome-devtools-mcp@latest`;若 Node.js 版本過舊,例如 `v20.11.0`,MCP server 會在 `initialize` 階段直接退出。
31
49
  2. 已安裝 Google Chrome。macOS 預設路徑通常是 `/Applications/Google Chrome.app`。若缺少 Chrome,且系統有 Homebrew,`make install` 會自動安裝。
32
50
 
51
+ 可用以下命令確認目前 shell 看到的 Node.js 版本:
52
+
53
+ ```bash
54
+ node -v
55
+ npx -v
56
+ ```
57
+
58
+ | 平台 | 注意事項 |
59
+ | --- | --- |
60
+ | macOS | 可使用 Homebrew 或 nvm 安裝 Node.js LTS。若使用 nvm,請確認執行 `ask-bridge` 的同一個 shell 已載入 nvm,且 `node -v` 顯示 `v20.19.0` 以上。Chrome 預設偵測 `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`。 |
61
+ | Windows | 可使用 Node.js 官方安裝程式、winget 或 nvm-windows 安裝 Node.js LTS。安裝後請重新開啟 PowerShell,並確認 `node -v` 與 `npx -v` 可執行。Chrome 會優先偵測 `Program Files`、`Program Files (x86)` 與 `%LOCALAPPDATA%` 底下的標準安裝路徑。 |
62
+ | Linux | 許多發行版內建套件庫可能提供較舊的 Node.js;建議使用 NodeSource、nvm 或官方 Node.js LTS 來源安裝。請安裝 Google Chrome Stable,並確認 `google-chrome` 或 `google-chrome-stable` 位於 `PATH` 中;Snap、Flatpak 或 Chromium 安裝方式可能不符合預設偵測邏輯。 |
63
+
33
64
  不需要安裝全域 `mcp-cli` 執行檔。Rust binary 會透過 Cargo 從 `https://github.com/doggy8088/mcp-cli` 使用 `mcp-cli` 作為 dependency。
34
65
 
35
66
  ## 安裝與建置
@@ -52,6 +83,7 @@ irm https://raw.githubusercontent.com/doggy8088/ask-bridge/main/install.ps1 | ie
52
83
 
53
84
  > [!NOTE]
54
85
  > 請確保安裝路徑(macOS/Linux 為 `~/.local/bin`;Windows 為 `$HOME\.local\bin`)已加入您的系統 `PATH` 環境變數中。
86
+ > 正式 CLI 命令為 `ask-bridge`;安裝流程也會提供 `ask` 作為向後相容 alias。以下範例皆以 `ask-bridge` 為準。
55
87
 
56
88
  ### 2. 從原始碼建置與安裝 (適用於開發者)
57
89
 
@@ -61,7 +93,7 @@ irm https://raw.githubusercontent.com/doggy8088/ask-bridge/main/install.ps1 | ie
61
93
  make install
62
94
  ```
63
95
 
64
- 此命令會自動檢查 Node.js 環境、檢查與安裝 Chrome 瀏覽器、建置最佳化的 binary,並在 `~/.local/bin/ask` 建立符號連結 (symlink)。
96
+ 此命令會自動檢查 Node.js 環境、檢查與安裝 Chrome 瀏覽器、建置最佳化的 binary,並在 `~/.local/bin/ask-bridge` 建立正式命令符號連結 (symlink),同時建立 `ask` alias。
65
97
 
66
98
  ### 3. 只建置不安裝
67
99
 
@@ -73,20 +105,36 @@ cargo build --release
73
105
 
74
106
  編譯後的 binary 會位於 `target/release/ask-bridge`。
75
107
 
108
+ ### 4. 安裝 Agent Skill
109
+
110
+ 本專案提供 `ask-bridge` Agent Skill,讓支援 Skills 的 Coding Agent 可以在適合的情境下,自主使用 `ask-bridge` 將探索性研究、摘要、文件分析或方案比較等工作委派給 ChatGPT 或 Gemini 網站。
111
+
112
+ 請使用 `npx skills` 安裝,不需要手動複製 `skills/` 目錄:
113
+
114
+ ```bash
115
+ npx skills add doggy8088/ask-bridge --skill ask-bridge
116
+ ```
117
+
118
+ 若要安裝到 Codex 的全域 Skills 目錄,可指定 agent 與 global scope:
119
+
120
+ ```bash
121
+ npx skills add doggy8088/ask-bridge --skill ask-bridge --agent codex --global
122
+ ```
123
+
76
124
  ## 使用方式
77
125
 
78
126
  ### 1. 首次設定:登入 provider
79
127
 
80
- 送出 prompt 前,需要先登入所選 provider。ChatGPT 為預設:
128
+ 送出 prompt 前,需要先登入所選 provider。未設定全域 provider 時,ChatGPT 為預設:
81
129
 
82
130
  ```bash
83
- ask login
131
+ ask-bridge login
84
132
  ```
85
133
 
86
134
  若要登入 Gemini:
87
135
 
88
136
  ```bash
89
- ask --provider gemini login
137
+ ask-bridge --provider gemini login
90
138
  ```
91
139
 
92
140
  此命令會:
@@ -98,13 +146,39 @@ ask --provider gemini login
98
146
 
99
147
  此流程通常只需要執行一次。
100
148
 
149
+ #### 全域 provider 設定
150
+
151
+ 若希望未指定 `--provider` 時預設使用 Gemini,可用 `ask-bridge config` 指定:
152
+
153
+ ```bash
154
+ ask-bridge config --provider gemini
155
+ ```
156
+
157
+ 若要改回 ChatGPT:
158
+
159
+ ```bash
160
+ ask-bridge config --provider chatgpt
161
+ ```
162
+
163
+ 可檢視目前設定:
164
+
165
+ ```bash
166
+ ask-bridge config
167
+ ```
168
+
169
+ `--provider` 的優先權高於全域設定檔,因此以下命令會暫時使用 ChatGPT:
170
+
171
+ ```bash
172
+ ask-bridge --provider chatgpt "請摘要這段內容。"
173
+ ```
174
+
101
175
  ### 2. 直接提問
102
176
 
103
177
  將 prompt 作為 argument 傳入:
104
178
 
105
179
  ```bash
106
- ask "Rust struct 和 tuple 有什麼差異?"
107
- ask --provider gemini "Rust struct 和 tuple 有什麼差異?"
180
+ ask-bridge "Rust struct 和 tuple 有什麼差異?"
181
+ ask-bridge --provider gemini "Rust struct 和 tuple 有什麼差異?"
108
182
  ```
109
183
 
110
184
  執行後:
@@ -115,12 +189,12 @@ ask --provider gemini "Rust struct 和 tuple 有什麼差異?"
115
189
 
116
190
  ### 3. 開啟全新對話
117
191
 
118
- 預設情況下,`ask` 會重用既有所選 provider 分頁,以避免建立過多分頁。
192
+ 預設情況下,`ask-bridge` 會重用既有所選 provider 分頁,以避免建立過多分頁。
119
193
 
120
194
  若要開啟全新的 provider 對話,使用 `--new`:
121
195
 
122
196
  ```bash
123
- ask "誰是保哥?" --new
197
+ ask-bridge "誰是保哥?" --new
124
198
  ```
125
199
 
126
200
  此模式會開啟新的所選 provider 分頁,並清理先前同一 provider 的分頁。
@@ -132,19 +206,19 @@ ask "誰是保哥?" --new
132
206
  若想觀察 Chrome 的操作過程,或需要手動檢查頁面狀態,可改用 headful 模式:
133
207
 
134
208
  ```bash
135
- ask "誰是保哥?" --headless=false
209
+ ask-bridge "誰是保哥?" --headless=false
136
210
  ```
137
211
 
138
- `ask login` 會強制使用 headful 模式,方便你和瀏覽器 UI 互動;其他 subcommand 若要可見瀏覽器,請明確加上 `--headless=false`。
212
+ `ask-bridge login` 會強制使用 headful 模式,方便你和瀏覽器 UI 互動;其他 subcommand 若要可見瀏覽器,請明確加上 `--headless=false`。
139
213
 
140
214
  ### 5. Verbose 模式
141
215
 
142
- 預設情況下,`ask` 只輸出所選 provider 的最終回覆,隱藏背景控制訊息。
216
+ 預設情況下,`ask-bridge` 只輸出所選 provider 的最終回覆,隱藏背景控制訊息。
143
217
 
144
218
  若要查看完整瀏覽器自動化流程,加入 `--verbose`:
145
219
 
146
220
  ```bash
147
- ask "誰是保哥?" --verbose
221
+ ask-bridge "誰是保哥?" --verbose
148
222
  ```
149
223
 
150
224
  Verbose 模式會顯示類似以下流程:
@@ -160,27 +234,27 @@ Verbose 模式會顯示類似以下流程:
160
234
  使用 `-v` 或 `--version` 顯示目前版本號:
161
235
 
162
236
  ```bash
163
- ask -v
237
+ ask-bridge -v
164
238
  ```
165
239
 
166
240
  ### 7. Pipe 與 stdin
167
241
 
168
- 可透過 pipe 將文字或檔案內容傳入 `ask`:
242
+ 可透過 pipe 將文字或檔案內容傳入 `ask-bridge`:
169
243
 
170
244
  ```bash
171
- echo "用一句話解釋 quantum computing" | ask
245
+ echo "用一句話解釋 quantum computing" | ask-bridge
172
246
  ```
173
247
 
174
- 若同時提供 prompt argument,`ask` 會先送出該 prompt,接著加上兩個換行後再附加管道內容:
248
+ 若同時提供 prompt argument,`ask-bridge` 會先送出該 prompt,接著加上兩個換行後再附加管道內容:
175
249
 
176
250
  ```bash
177
- cat /Users/will/.copilot/session-state/46cc0f1c-79fd-4622-9548-a0b7fa3794be/research/does-cursor-support-byok.md | ask 'What is this?'
251
+ cat /Users/will/.copilot/session-state/46cc0f1c-79fd-4622-9548-a0b7fa3794be/research/does-cursor-support-byok.md | ask-bridge 'What is this?'
178
252
  ```
179
253
 
180
254
  也可以讀取檔案內容:
181
255
 
182
256
  ```bash
183
- cat src/main.rs | ask "這段 Rust code 有記憶體洩漏風險嗎?"
257
+ cat src/main.rs | ask-bridge "這段 Rust code 有記憶體洩漏風險嗎?"
184
258
  ```
185
259
 
186
260
  ### 8. 附上圖片或文件
@@ -192,8 +266,8 @@ cat src/main.rs | ask "這段 Rust code 有記憶體洩漏風險嗎?"
192
266
  使用 `--image` 附上一或多張本機圖片(可重複指定)。此功能目前支援 ChatGPT;Gemini 圖片輸入尚未支援,搭配 `--provider gemini` 使用會立即回報錯誤。
193
267
 
194
268
  ```bash
195
- ask "請描述這張圖片的內容。" --image screenshot.png
196
- ask "比較這兩張圖的差異。" --image v1.png --image v2.png
269
+ ask-bridge "請描述這張圖片的內容。" --image screenshot.png
270
+ ask-bridge "比較這兩張圖的差異。" --image v1.png --image v2.png
197
271
  ```
198
272
 
199
273
  支援的格式包含 PNG、JPEG、GIF、WebP、SVG、BMP 等。
@@ -203,15 +277,15 @@ ask "比較這兩張圖的差異。" --image v1.png --image v2.png
203
277
  使用 `--file` 附上一或多份本機文件(可重複指定),例如 PDF、Word、Excel、PowerPoint、純文字、Markdown、CSV、JSON、程式碼等。ChatGPT 與 Gemini 都支援此流程。
204
278
 
205
279
  ```bash
206
- ask "請摘要這份 PDF 的重點。" --file report.pdf
207
- ask "這份 CSV 總共有幾筆資料?" --file data.csv
208
- ask "幫我檢查這段程式碼有沒有問題。" --file src/main.rs
280
+ ask-bridge "請摘要這份 PDF 的重點。" --file report.pdf
281
+ ask-bridge "這份 CSV 總共有幾筆資料?" --file data.csv
282
+ ask-bridge "幫我檢查這段程式碼有沒有問題。" --file src/main.rs
209
283
  ```
210
284
 
211
285
  也可以同時附上圖片與文件:
212
286
 
213
287
  ```bash
214
- ask "請對照這張設計圖與規格文件,指出不一致的地方。" --image design.png --file spec.docx
288
+ ask-bridge "請對照這張設計圖與規格文件,指出不一致的地方。" --image design.png --file spec.docx
215
289
  ```
216
290
 
217
291
  #### 顯示上傳結果
@@ -223,11 +297,11 @@ provider 回覆後,可使用 `-i` / `--image-output` 指定生成圖片的下
223
297
  使用 `--model` 在送出 prompt 前自動切換 provider 的模型。比對時不分大小寫與標點符號(`-`、`.`、空格 等)。
224
298
 
225
299
  ```bash
226
- ask "用幾句話介紹 Rust。" --model GPT-5.4
227
- ask "證明這個數學問題。" --model o3
228
- ask "快速翻譯這段話。" --model 即時
229
- ask --provider gemini "用幾句話介紹 Rust。" --model "3.5 Flash"
230
- ask --provider gemini "用幾句話介紹 Rust。" --model "3.1 Pro"
300
+ ask-bridge "用幾句話介紹 Rust。" --model GPT-5.4
301
+ ask-bridge "證明這個數學問題。" --model o3
302
+ ask-bridge "快速翻譯這段話。" --model 即時
303
+ ask-bridge --provider gemini "用幾句話介紹 Rust。" --model "3.5 Flash"
304
+ ask-bridge --provider gemini "用幾句話介紹 Rust。" --model "3.1 Pro"
231
305
  ```
232
306
 
233
307
  可用的模型名稱(視帳號權限與 provider UI 而定):
@@ -236,32 +310,32 @@ ask --provider gemini "用幾句話介紹 Rust。" --model "3.1 Pro"
236
310
  - **ChatGPT 思考強度**:`智慧`、`即時`、`中等`、`高`、`超高`、`專業`
237
311
  - **Gemini 模式**:`3.5 Flash`、`3.1 Flash-Lite`、`3.1 Pro`
238
312
 
239
- > 若指定的名稱在選單中找不到,`ask` 會回報 `Model switch failed: error: model not found in menu` 並中止,不會送出 prompt。
313
+ > 若指定的名稱在選單中找不到,`ask-bridge` 會回報 `Model switch failed: error: model not found in menu` 並中止,不會送出 prompt。
240
314
 
241
315
  ### 10. 只開啟 provider
242
316
 
243
317
  若只想快速開啟瀏覽器並進入所選 provider:
244
318
 
245
319
  ```bash
246
- ask open
247
- ask --provider gemini open
320
+ ask-bridge open
321
+ ask-bridge --provider gemini open
248
322
  ```
249
323
 
250
324
  ### 11. 關閉瀏覽器 instance
251
325
 
252
- 若要關閉 `ask` 管理的 Chrome debug profile instance:
326
+ 若要關閉 `ask-bridge` 管理的 Chrome debug profile instance:
253
327
 
254
328
  ```bash
255
- ask close
329
+ ask-bridge close
256
330
  ```
257
331
 
258
- `close` 只會關閉使用 `~/.config/ask-bridge/chrome-profile` 且監聽 debug port `9223` 的 `ask` Chrome instance;若該 port 被非 `ask` Chrome 程序占用,會回報錯誤而不會關閉它。
332
+ `close` 只會關閉使用 `~/.config/ask-bridge/chrome-profile` 且監聽 debug port `9223` 的 `ask-bridge` Chrome instance;若該 port 被非 `ask-bridge` Chrome 程序占用,會回報錯誤而不會關閉它。
259
333
 
260
334
  ## 運作原理
261
335
 
262
- 1. **瀏覽器初始化**:`ask` 會檢查 Chrome 是否正在監聽 debug port `9223`。若沒有,會以專屬 profile 目錄 `~/.config/ask-bridge/chrome-profile` 啟動 Google Chrome。
336
+ 1. **瀏覽器初始化**:`ask-bridge` 會檢查 Chrome 是否正在監聽 debug port `9223`。若沒有,會以專屬 profile 目錄 `~/.config/ask-bridge/chrome-profile` 啟動 Google Chrome。
263
337
  2. **MCP Bridge 設定**:啟動時會自動寫入 `~/.config/ask-bridge/mcp_servers.json`,預設設定 Chrome DevTools MCP server,使用 `chrome-devtools-mcp@latest` 與 `--browser-url=http://127.0.0.1:9223`。
264
- 3. **Client 呼叫**:`ask` 透過內建的 `doggy8088/mcp-cli` Rust library dependency 呼叫 MCP tools,例如 `list_pages`、`select_page`、`type_text` 與 `evaluate_script`,不依賴系統上的外部 `mcp-cli` 命令。
338
+ 3. **Client 呼叫**:`ask-bridge` 透過內建的 `doggy8088/mcp-cli` Rust library dependency 呼叫 MCP tools,例如 `list_pages`、`select_page`、`type_text` 與 `evaluate_script`,不依賴系統上的外部 `mcp-cli` 命令。
265
339
  4. **狀態輪詢**:provider 產生回覆期間,工具會以 JavaScript 檢查送出與停止按鈕狀態,擷取回覆元素的文字內容,並輸出到 `stdout`。
266
340
 
267
341
  ## 相關文件
@@ -157,9 +157,26 @@ async function installFromRelease() {
157
157
  rmSync(tmpDir, { recursive: true, force: true });
158
158
  }
159
159
 
160
+ function checkChrome() {
161
+ const chromePaths = {
162
+ darwin: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
163
+ linux: '/usr/bin/google-chrome',
164
+ win32: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
165
+ };
166
+ const chromePath = chromePaths[process.platform];
167
+ if (chromePath && !existsSync(chromePath)) {
168
+ console.warn('');
169
+ console.warn('⚠️ Google Chrome was not found on your system.');
170
+ console.warn(' ask-bridge requires Chrome to automate ChatGPT / Gemini.');
171
+ console.warn(' Please install it from: https://www.google.com/chrome/');
172
+ console.warn('');
173
+ }
174
+ }
175
+
160
176
  async function main() {
161
177
  if (installFromLocalBuild()) return;
162
178
  await installFromRelease();
179
+ checkChrome();
163
180
  }
164
181
 
165
182
  if (require.main === module) {
@@ -173,6 +190,7 @@ module.exports = {
173
190
  TARGETS,
174
191
  artifactName,
175
192
  cargoTarget,
193
+ checkChrome,
176
194
  findExtractedBinary,
177
195
  platformKey,
178
196
  releaseBaseUrl,
package/package.json CHANGED
@@ -1,8 +1,9 @@
1
1
  {
2
2
  "name": "ask-bridge",
3
- "version": "0.1.1",
3
+ "version": "0.1.5",
4
4
  "description": "Automate ChatGPT or Gemini from the command line through Chrome.",
5
5
  "bin": {
6
+ "ask-bridge": "npm/cli.cjs",
6
7
  "ask": "npm/cli.cjs"
7
8
  },
8
9
  "scripts": {