使用文件 / 疑難排解

工具沒有被呼叫

講了「搜尋 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」)

還是沒解決時要提供什麼資訊

  1. 你用的提示詞檔名,以及它的 front matter 原始內容。
  2. 你實際說的那句話(原文)。
  3. 當時選的模型與 provider。
  4. 該次錄音的 prompt_correction_tool_trace.json,或確認它不存在。
  5. 平台與版本。
  6. zerotype.log 中該次請求的片段。

提供前請先確認檔案裡沒有金鑰、個人資料或公司內部內容——工具參數可能包含路徑、網址或命令。

這一頁有錯、或有沒寫到的地方?寫信到 training [at] miniasp.com,我們會依實際行為更新文件。