使用文件 / 疑難排解
工具沒有被呼叫
講了「搜尋 Google」卻只換成一段文字?照這六步檢查 front matter、提示詞選擇、模型與說法。
最後更新
症狀
- 你說「搜尋 Google 某某主題」,結果「搜尋 Google 某某主題」被當成文字貼進輸入框。
- 放開錄音鍵後什麼都沒發生,也沒有貼上任何文字。
- 同一個工具昨天可以用,今天突然不動作。
依序檢查
1. 那份提示詞有啟用工具嗎
工具預設全部關閉,而且只認目前選取那份提示詞的 front matter。只寫這句是不會啟用工具的:
請幫我搜尋資料。
要這樣寫:
---
ENABLE_GOOGLE_SEARCH: true
---
如果我明確要求搜尋,請使用 google_search。
ENABLE_* 或 ZEROTYPE_ENABLE_* 都可以,值用 true 或 1。
2. 你選到的是那份提示詞嗎
錄音中可以用錄音鍵加數字鍵切換提示詞(Windows 是 Right Alt,macOS 是 Right Option),HUD 會顯示目前切到的名稱。如果你剛才切到另一份沒有啟用工具的提示詞,工具自然不會出現。
事後也可以驗證:歷史記錄每一筆都會記錄當時使用的提示詞名稱。
3. 這個模型支援工具呼叫嗎
工具呼叫要靠模型配合。有些模型或某些相容端點不支援工具呼叫,或支援度有限。最快的驗證方式是換一個你確定支援工具呼叫的模型,同樣的話再講一次。
如果換模型就好了,問題在模型選擇,不在 ZeroType。
4. 你的說法夠明確嗎
| 說法 | 結果 |
|---|---|
| 「幫我查一下那個東西」 | 太模糊,模型可能只當一般文字 |
| 「搜尋 Google ZeroType 語音輸入工具」 | 明確,會觸發 google_search |
| 「打開那個網站」 | 沒有網址,open_url 不會用 |
| 「打開 https://example.com/pricing」 | 明確,會觸發 open_url |
| 「按 Ctrl A 然後 Ctrl C」 | 明確,會觸發 send_keys |
| 「幫我輸入這段話」 | 太模糊,也可能被當成一般聽寫 |
提示詞裡也要寫清楚路由規則,例如「只有我明確說『執行』才可以用 run_shell;如果我只是問指令怎麼寫,只輸出文字說明」。模型會照你寫的界線判斷。
5. 這個平台支援這個工具嗎
十個工具在 Windows 與 macOS 都支援,但 run_shell 有平台限制:
- Windows:只支援
pwsh。機器上沒有pwsh就無法使用,ZeroType 不會改用 Windows PowerShell 或cmd。 - macOS:使用
/bin/zsh。
send_keys 也有平台差異:macOS 請用 Command/Cmd 類的說法,Windows 用 Ctrl、Alt、Win 類的說法。
6. 工具其實跑了,只是沒有文字
這是很多人的誤會。工具是副作用,成功執行後 ZeroType 不會再輸入「已完成」之類的確認文字。網頁開了、App 開了、快捷鍵送出去了,畫面上可能什麼字都沒有。
反過來也可能相反:如果那份提示詞明確寫了 ENABLE_TOOL_FINAL_OUTPUT: false,即使模型產生了文字,也只會留在診斷檔,不會輸入前景 App。
怎麼確認工具真的跑了
打開該次錄音的資料夾,看 prompt_correction_tool_trace.json。裡面會列出這次呼叫了哪個工具、模型給的原始參數,以及成功或失敗的結果。
- 有紀錄、結果成功:工具確實執行了,問題在別的地方(例如你以為它沒開網頁)。
- 有紀錄、結果失敗:錯誤訊息會寫在裡面,例如找不到 App、
pwsh不存在、網址格式不對。 - 完全沒有紀錄:模型根本沒要求工具,回到第 1 到第 4 點。
資料位置見 診斷資料與 log。
常見誤解
| 你以為 | 實際 |
|---|---|
| 測試連線成功就代表工具可用 | 測試連線用的是停用工具的環境,不會執行任何工具 |
| 開啟 ZeroType 就會啟用工具 | 工具是逐份提示詞設定的,預設全關 |
| 「重新轉錄」會重跑一次工具 | 不會。重新轉錄不執行工具、不輸入文字、不送 Enter |
| 工具成功後會貼一段「已完成」 | 不會,這是刻意設計 |
| 同一份提示詞改了 front matter 立刻生效 | 手動編輯檔案後要重新載入(選單有「重新啟動 ZeroType」) |
還是沒解決時要提供什麼資訊
- 你用的提示詞檔名,以及它的 front matter 原始內容。
- 你實際說的那句話(原文)。
- 當時選的模型與 provider。
- 該次錄音的
prompt_correction_tool_trace.json,或確認它不存在。 - 平台與版本。
zerotype.log中該次請求的片段。
提供前請先確認檔案裡沒有金鑰、個人資料或公司內部內容——工具參數可能包含路徑、網址或命令。
這一頁有錯、或有沒寫到的地方?寫信到 training [at] miniasp.com,我們會依實際行為更新文件。