使用文件 / 疑難排解
診斷資料與 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:
- 版本更新後第一次啟動(方便對照「哪一版出的問題」)。
- 檔案累積到約 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 資料夾處理。
刪掉之後無法復原,要保留證據請先備份。
還是沒解決時要提供什麼資訊
- 平台與版本號(
zerotype.log開頭那行就有版本)。 - 發生時間,請註明時區。log 的時間戳可能是 UTC。
- 該次的錄音資料夾名稱(例如
20260521-181100-001)。 - 你看到的現象與預期行為,一句話即可。
- 依照上面的「什麼情況看哪個檔案」,挑 1 到 3 個檔案提供。
- 若是授權或金鑰問題,附上錯誤訊息與支援代碼,不要附完整授權碼或金鑰。
最後提醒:任何要給別人看的檔案,請先自己打開確認一次內容。這些檔案是為了讓你看得懂自己的問題而存在,不是設計成可以直接公開的格式。
這一頁有錯、或有沒寫到的地方?寫信到 training [at] miniasp.com,我們會依實際行為更新文件。