| name | audio-transcribe |
| description | 用 Gemini 原生多模態音訊理解，把音檔完整轉錄為逐字稿（含講者與 [MM:SS] 時間戳），不摘要不省略。逐字稿寫入檔案，只回傳檔案路徑。若當前代理本身沒有原生音訊理解（如 Claude Code、Codex、Copilot），會自動委派給 `agy -p` 非互動指令；若已在 agy／gemini 上執行則直接原生轉錄。另附逐字稿轉 SRT 字幕腳本。觸發詞：轉錄、逐字稿、轉逐字、聽打、音檔轉文字、transcribe、audio transcript、把錄音轉成文字、轉字幕、SRT、字幕檔。 |
| version | 1.3.0 |
| author | LazyJerry |
音檔逐字轉錄（audio-transcribe）
把音檔完整轉錄為逐字稿。核心手法是直接用模型的原生多模態音訊理解讀音檔聽寫，而非呼叫 whisper／ffmpeg 等外部 STT 工具。
<SKILL_DIR> 為此 skill 安裝目錄（~/.claude/skills/audio-transcribe）。
設計原則
固定流程由 scripts/transcribe.sh 自動完成，代理只負責取得音檔絕對路徑、呼叫腳本、轉述結果。腳本會自動偵測執行環境並二選一：
| 執行環境 | 偵測依據 | 行為 |
|---|
| 不在 agy／gemini（Claude Code、Codex、Copilot…） | ANTIGRAVITY_CONVERSATION_ID 不存在 | 腳本呼叫 agy -p 非互動指令，由 Gemini 原生音訊理解轉錄，並由 agy 自行把逐字稿寫入輸出檔、回覆只給路徑一行；腳本驗證檔案後 stdout 只印該檔絕對路徑（exit 0） |
| 已在 agy／gemini（原生具備音訊理解） | ANTIGRAVITY_CONVERSATION_ID 存在（實測 agy run_command 子行程會帶此變數） | 腳本不遞迴呼叫 agy，改印出 canonical prompt、目標輸出檔路徑與指示（exit 3），交由當前代理原生轉錄後寫檔、只回傳路徑 |
執行流程
1. 取得音檔絕對路徑
向使用者確認要轉錄的音檔絕對路徑（腳本會拒絕相對路徑）。
2. 執行單一進入點
sh <SKILL_DIR>/scripts/transcribe.sh <音檔絕對路徑> [模型] [輸出檔路徑]
- 第二參數為選填模型，預設
gemini-3.6-flash-high（亦可用環境變數 AGY_MODEL 覆寫）。
- 第三參數為選填輸出檔路徑，預設
<音檔同目錄>/<音檔主檔名>.transcript.md（亦可用環境變數 TRANSCRIPT_OUT 覆寫）；相對路徑相對音檔目錄解析。
--add-dir 由腳本自音檔路徑推得，--dangerously-skip-permissions 已內建。
3. 依結束碼處理
- exit 0：delegate 已完成，stdout 只有輸出檔絕對路徑（逐字稿已由 agy 寫入該檔）。把路徑回報給使用者即可，不要讀取或轉貼逐字稿內容（除非使用者另外要求）。
- exit 3：你正在 agy／gemini 上執行。改用你自己的原生音訊理解能力，依 stderr 印出的 canonical prompt 直接把該音檔讀進來聽並完整逐字轉錄，於每段開頭標註講者與
[MM:SS]；把逐字稿寫入 stderr 指示的目標輸出檔，只回傳該路徑，不要回傳全部內容。不要呼叫 whisper／ffmpeg 或任何外部 STT。
- exit 2：參數或檔案錯誤（路徑非絕對、檔案不存在／不可讀）。修正後重試。
- exit 4：找不到
agy。告知使用者需安裝 Antigravity CLI，或改在支援原生音訊的代理上執行。
- exit 5：agy 結束但沒寫出逐字稿（或內容為空）。stderr 會給
<輸出檔>.agy.<pid>.log，先看日誌再重試；舊逐字稿已自動還原。
- exit 124：agy 逾時。舊輸出檔保留不動。
輸出格式
逐字稿每段開頭標註講者與時間戳，例如：
[00:00] Speaker 1: ……
[00:07] Speaker 1: ……
完整逐字，不摘要、不省略。
轉字幕（選用）
使用者要 SRT 字幕時，把上一步的逐字稿丟給：
sh <SKILL_DIR>/scripts/transcript-to-srt.sh <逐字稿絕對路徑> [輸出 srt 路徑] [媒體總長秒數]
- 輸出預設
<逐字稿同目錄>/<主檔名去掉 .transcript>.srt；stdout 只印該檔絕對路徑。
- 每句結束時間 = min(下一句起始, 起始 +
MAX_CUE)，MAX_CUE 預設 15 秒，避免長靜音產生超長字幕。
- 給第三參數（媒體總長秒數）可讓最後一句結束在實際片尾。
- 逐字稿只有單一講者時自動移除講者前綴；多講者則保留。
- 結束碼：0 成功；2 參數／檔案錯誤；3 逐字稿中找不到任何可解析的時間戳行。
