使用文件 / 疑難排解

診斷資料與 log

log 與每次錄音的留底放在哪裡、裡面有什麼、什麼時候該提供,以及怎麼安全清除。

最後更新

什麼時候會用到

需要看 log 或錄音留底的情況通常是這幾種:

  • 文字沒貼上、貼錯位置,或只貼了一部分。
  • 工具該動作卻沒動作,或做了不該做的事。
  • 錄音被忽略,但你不確定是太短、太小聲,還是被規則刪掉。
  • 授權或金鑰錯誤,訊息看不出原因。

ZeroType 會把每次處理的 request、response 與結果留在你自己的電腦上,這些就是排查的依據。

檔案放在哪裡

平台 log 每次錄音的留底
Windows %LOCALAPPDATA%\ZeroType\logs\zerotype.log %LOCALAPPDATA%\ZeroType\recordings\
macOS ~/Library/Application Support/ZeroType/logs/zerotype.log ~/Library/Application Support/ZeroType/recordings/

recordings 底下每次錄音會有一個以時間命名的資料夾,格式類似 20260521-181100-001。

log 會在兩種情況自動換檔,舊檔改名為 zerotype-YYYYMMDD-HHMMSS.log:

  1. 版本更新後第一次啟動(方便對照「哪一版出的問題」)。
  2. 檔案累積到約 10 MB。

所以回報問題時,請注意你打開的是目前版本的 zerotype.log,不是舊的封存檔。

每次錄音會留下什麼

不是每個資料夾都會有全部檔案,實際內容取決於流程跑到哪一步。

檔案 內容
audio.wav 實際送去轉錄的音訊(16 kHz、16-bit、單聲道)
recording_summary.json 音訊摘要:長度、裁切量、增益前後的 peak/RMS、是否被忽略與忽略原因
transcription_text.txt provider 回傳的原始轉寫
transcription_processed_text.txt 套用你的 Transcription 規則後、實際送進 AI 的文字
prompt_correction_text.txt 模型產生的原始校正文字
output_text.txt 最後要輸出的文字(已套用字形轉換與 FinalOutput 規則)
foreground_injection_diagnostics.json 輸入階段診斷:輸入模式、注入前後的目標 App 與視窗、剪貼簿備份與還原結果
history_entry.json 歷史記錄用的資料:時間、提示詞、輸入狀態、警告
history_feedback.json 你評分或寫註記後才會出現
prompt_correction_tool_trace.json 有呼叫工具時才有:工具名稱、模型原始參數、成功或失敗

沒有檔案的常見原因也很有參考價值:

情況 會看到的狀態
錄音太短或太小聲被忽略 通常不會建立資料夾,因為在建立留底前就結束了
轉錄失敗 有 audio.wav 與 history_entry.json,狀態為轉錄失敗,可用「重新轉錄」取回
轉錄回傳空文字 有 transcription_text.txt,但沒有後續的校正與輸出檔
你的規則把文字刪成空 transcription_text.txt 有內容、transcription_processed_text.txt 是空的
AI 校正失敗 用處理後轉錄當備援輸出,warning 會標示校正失敗
只執行了工具、沒有輸出文字 有工具紀錄,沒有 output_text.txt
處理中被取消 保留 audio.wav 與已寫出的檔案,狀態為已取消

log 裡有什麼、沒有什麼

log 記錄的是技術過程:每次轉錄與校正請求的 provider、API base、模型或部署名稱、實際請求網址、授權模式、音訊格式與大小、是否帶入工具定義等。

log 不會記錄:API 金鑰、提示詞內容、你的語音文字、base64 音訊或模型回應本文。網址若含有 api_key、token、signature 這類看起來敏感的參數,寫入前會先遮蔽。

相對地,recordings 裡會有你的語音與文字。兩者的隱私等級不同,處理方式也不該一樣。

什麼情況看哪個檔案

你的問題 先看
完全沒文字、不知道卡在哪 歷史記錄狀態 → 該筆 recording_summary.json
音量或長度被忽略 recording_summary.json 的 inputPeak、inputRms、trimmedSampleCount、忽略原因
轉寫文字不對 transcription_text.txt 與 transcription_processed_text.txt 的差異
AI 校正結果不對 prompt_correction_text.txt 與 output_text.txt 的差異
文字被規則改掉 比對上面兩者,再看 user_prompt_overrides.json
貼錯位置、沒貼上 foreground_injection_diagnostics.json 的目標視窗與注入階段
工具有沒有跑 prompt_correction_tool_trace.json
授權或金鑰 zerotype.log 中對應時間的片段

macOS log 常見訊息

macOS 的 log 有一串好用的階段訊息,可以快速定位:

訊息 意義
Audio engine start failed 錄音根本沒啟動,通常是音訊裝置或路由問題
First audio buffer received 有收到音訊,但不代表內容不是靜音
Recording ignored before transcription 被短音訊/低音量策略擋下,沒有送到 provider
Transcription request starting 音訊已送出,本機階段通過
Prompt correction request starting 轉錄成功,進入 AI 校正
Foreground injection completed 文字已輸入或貼上

看到「有 buffer 進來」但 recording_summary.json 的峰值極低,代表確實收到靜音,問題在麥克風或裝置選擇,不在轉錄服務。

隱私提醒

recordings 內的檔案可能包含:你的語音、轉寫與校正文字、提示詞內容、剪貼簿摘要、前景視窗資訊、工具參數(可能含本機路徑、網址、shell 命令與命令輸出)以及模型原始回應。

因此:

  • 不要把整個錄音資料夾提交到 repo、貼進 issue 或公開聊天。
  • 提供前先只挑必要檔案,必要時把個人資料、公司內容、剪貼簿內容與敏感路徑刪除或遮蔽。
  • 描述現象與檔名比整包上傳更有用。

怎麼清除

打開歷史記錄:

  • 刪除此筆:刪掉那一筆的整個資料夾(含音訊)。
  • 清空全部:刪掉歷史記錄看得到的所有資料夾。

這兩個動作只刪本機檔案,不會同步,也不會上傳。沒列在歷史記錄裡的診斷資料夾(例如只執行了工具、沒有輸出文字的)不會被「清空全部」刪掉,需要時請自行到 recordings 資料夾處理。

刪掉之後無法復原,要保留證據請先備份。

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

  1. 平台與版本號(zerotype.log 開頭那行就有版本)。
  2. 發生時間,請註明時區。log 的時間戳可能是 UTC。
  3. 該次的錄音資料夾名稱(例如 20260521-181100-001)。
  4. 你看到的現象與預期行為,一句話即可。
  5. 依照上面的「什麼情況看哪個檔案」,挑 1 到 3 個檔案提供。
  6. 若是授權或金鑰問題,附上錯誤訊息與支援代碼,不要附完整授權碼或金鑰。

最後提醒:任何要給別人看的檔案,請先自己打開確認一次內容。這些檔案是為了讓你看得懂自己的問題而存在,不是設計成可以直接公開的格式。

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