opencode-groq-api

把 API 變成自己的工具（Groq）

官方文件查證日期：2026-07-27 依據：<https://console.groq.com/docs/speech-to-text>、<https://console.groq.com/docs/api-reference>、<https://console.groq.com/docs/rate-limits>、<https://console.groq.com/docs/models>、<https://console.groq.com/docs/your-data>、<https://console.groq.com/docs/billing-faqs>、<https://console.groq.com/docs/quickstart>

---

🔴 先看這裡：隱私紅線（這一段是本包最重要的內容）

這一包做的每一件事，都會把你的聲音檔送到別人的伺服器上。

不是「處理完就消失」那種送，是整個音檔上傳、在美國的機器上跑完、再把文字傳回來。你電腦上的麥克風錄到什麼，就送出去什麼。

這三類錄音，一律不要上傳

| ❌ 不要上傳 | 為什麼 | |------------|--------| | 含學生聲音的課堂錄音 | 學生是未成年人。要不要讓孩子的聲音上傳到境外雲端，這件事你不能代替家長同意。 | | 家長會談、親師溝通、電話錄音 | 對方通常不知道有錄音，更不知道會被上傳 | | 輔導紀錄、個案會議、學生私下談話 | 這類內容一旦外流，受傷的是孩子，而且你會有法律責任 |

順便三條也不要：唸到學生姓名的點名錄音、學生口說測驗的作答錄音、任何你不確定裡面有誰在講話的檔案。

這些可以上傳

• 你自己一個人講課、備課、口述的錄音（只有你的聲音）
• 你自己的公開演講、研習分享
• 你自己錄的旁白、口播稿
• 公開影片（新聞、公播教材、你自己頻道的影片）

一句話的判斷標準

## 🔴 「這個音檔如果明天出現在網路上，會不會有人受傷？會不會需要通報？」 只要答案是「會」或「不確定」——不上傳。沒有例外，不看時間趕不趕。

⚠️ 最容易出事的地方：檔案結尾

課堂錄音最常見的意外不是內容，是「忘記按停止」。

你以為錄的是自己講課的 40 分鐘，實際上錄音一直開到下課、開到學生跑上來問問題、開到你跟隔壁老師聊完。

🔴 規矩：上傳前先跳到檔案的最後 30 秒聽一遍。 這一步花 30 秒，可以擋掉這一包 90% 的真實風險。

Groq 官方的資料政策（查證 2026-07-27）

講完紅線再講政策，順序不能反——政策再好，也不會讓紅線消失。

| 項目 | 官方說法 | 出處 | |------|---------|------| | 推論請求的資料會保留嗎 | 預設不保留（"By default, Groq does not retain customer data for inference requests."） | Your Data in GroqCloud | | 會拿去訓練模型嗎 | 不會。服務協議明訂：未經客戶明示同意，不得將輸入／輸出用於訓練或微調模型 | Groq Services Agreement | | 有例外嗎 | 有。為了排除故障、調查濫用，可能暫時記錄輸入與輸出，最長保留 30 天（法律要求時可能更久） | Your Data in GroqCloud | | 可以完全關掉嗎 | 可以。所有客戶都能在 Console 的 Data Controls 開啟 Zero Data Retention（ZDR） | Your Data in GroqCloud | | 免費方案有比較差嗎 | 官方文件沒有為免費方案另訂較寬鬆的規定，寫的是同一套 | 同上 |

建議研習前先做一件事：登入 Console → Settings → Data Controls → 開啟 Zero Data Retention。花 10 秒，之後所有請求都適用。

🔴 但是——開了 ZDR，紅線一條都不會消失。 政策是廠商的承諾，不是「你的檔案沒有離開過你的電腦」的技術保證。 中間還有網路、還有你的電腦、還有你等一下會不會把 srt 檔傳到 LINE 群組。 真正安全的做法只有一個：那個檔案根本不要上傳。

真的非處理不可怎麼辦

有些內容就是不能上雲端，但你又真的需要逐字稿。三條路：

1. 請當事人自己來：讓學生／家長自己用手機的語音輸入打字，你只收文字
2. 本機跑：在自己電腦上跑離線的語音辨識模型（不連網、不上傳）。這條不在本研習範圍，也不在本包
3. 不做：這是完全合理的選項。省下的 20 分鐘，遠遠比不上一次個資事件

---

這一包在研習裡的位置：作品⑤「把 API 變成自己的工具」

第三天上午。這一包做的是「內部工具」——只有你自己在電腦上用，還不碰網頁。

前面幾包是「把別人做好的東西接進來」（NotebookLM、Obsidian、Supabase）。這一包不一樣：

你會拿一個原始的 API，做出一個以後可以一直用的東西。

這是整套研習裡第一次「呼叫外部服務、拿回結果、包成工具」。學會這個模式，之後接任何服務都是同一套邏輯。

🔑 這一包成不成功，判斷標準只有一個

| | 跑一次 | 變成工具 | |---|-------|-------------| | 你做的事 | 貼一串指令，看到 srt 跑出來 | 對 OpenCode 說一句人話，它自己做完 | | 換一份新素材 | 要回來翻講義、重貼指令 | 同一句話再說一次就好 | | 下個月還會用嗎 | 不會，因為忘了怎麼跑 | 會，因為只要記得那句話 | | 這一包的驗收 | ❌ 不算完成 | ✅ 這才算完成 |

所以步驟六（包成 Skill）不是加分題，是這一包的正題。 前面五個步驟都只是為了搞清楚「那句人話背後要做什麼」。

📌 下午的 10-netlify 會把這個工具再往外推一層：變成一個網頁，讓別人也能用。 今天上午先把「自己能用」做穩，下午才有東西可以搬上網。

---

這一包會幫你做什麼

兩條主線，都用同一把金鑰：

| 線 | 做什麼 | 輸入 → 輸出 | 用到的服務 | |----|--------|-------------|-----------| | A 轉字幕 | 把聲音變成有時間碼的字幕檔 | .mp4 / .mp3 / .m4a → .srt | Groq 的 Whisper | | B 文字清洗 | 把逐字稿整理成能發給學生看的講義 | .srt / .txt → .md | Groq 的文字模型 |

A 線的產物剛好是 B 線的原料。合起來就是：一段錄音 → 一份講義。

---

🚨 這一包的四個陷阱（先看完再動手）

| # | 陷阱 | 症狀 | 一句話解法 | |---|------|------|-----------| | ① | Groq 沒有 response_format=srt | 照 OpenAI 的教學打，回 400 | 拿 verbose_json，自己組 srt（步驟三附小程式） | | ② | 免費方案單檔上限 25 MB | 一支 40 分鐘影片直接被打回 | 先用 ffmpeg 壓成 16k 單聲道，超過 25 MB 就切段 | | ③ | Whisper 的中文不分繁簡 | 辛苦轉完，字幕是簡體 | language=zh 只能到「中文」；繁體要另外處理（步驟三 A5） | | ④ | 切段後時間碼要自己加偏移 | 第二段字幕全部從 00:00 開始，整份對不上畫面 | 用每一段的實際長度累加，不要用名目的「10 分鐘」 |

陷阱 ① 是最花時間的一個——網路上 95% 的 Whisper 教學都是寫給 OpenAI 的，那邊有 srt，Groq 沒有。 你會以為自己打錯字。

---

免費方案（不用綁信用卡）

⚠️ 以下為 2026-07-27 查到的數字。服務商隨時會調整，以官方頁面為準（本節最後教你怎麼自己查）。

要不要綁卡

| 問題 | 答案（查證 2026-07-27） | |------|------------------------| | 註冊要不要信用卡 | 不用。 用 Google／GitHub／Email 註冊，直接就能產金鑰 | | 免費用量要不要信用卡 | 不用。 免費方案是「限速」不是「限時」，沒有試用到期這回事 | | 什麼時候才需要卡 | 只有升級 Developer 方案時。官方文件寫得很清楚：升級需要「a valid payment method（credit card, US bank account, or SEPA debit account）」 |

🔴 研習現場的規矩：整個過程不會有任何畫面要你輸入卡號。 只要看到要求付款方式的畫面，代表你走進了升級流程——按上一頁退出來，不要輸入。 這一包主線完全不需要 Developer 方案。

免費額度（Whisper 語音）

| 項目 | 免費方案 | 換算成老師聽得懂的話 | |------|---------|---------------------| | 單檔大小上限 | 25 MB | 壓成 16k 單聲道 FLAC 後，約 25～30 分鐘的音訊 | | 每分鐘請求數 | 20 次 | 一次跑 20 個檔沒問題 | | 每日請求數 | 2,000 次 | 用不完 | | 每小時音訊秒數 | 7,200 秒 | 每小時可以轉 2 小時的音訊 | | 每日音訊秒數 | 28,800 秒 | 每天可以轉 8 小時的音訊 | | 最短音訊 | 0.01 秒 | — | | 最低計費長度 | 10 秒 | ⚠️ 見下方 |

⚠️ 「最低計費 10 秒」這條會咬人。 意思是：再短的檔，也至少吃掉 10 秒額度。 所以「把一堂課切成 200 個小片段各自送一次」是最浪費的做法——200 個 3 秒的檔會被算成 2,000 秒。 正確做法：切大段（10 分鐘一段），不要切小段。

（付費的 Developer 方案單檔上限是 100 MB。本包不走那條，寫在這裡只是讓你看到別人的教學寫 100 MB 時不會困惑。）

免費額度（文字模型，B 線用）

| 模型 | 每分鐘請求 | 每日請求 | 每分鐘 token | 每日 token | |------|-----------|---------|-----------------|-----------| | llama-3.3-70b-versatile | 30 | 1,000 | 12,000 | 100,000 | | openai/gpt-oss-120b | 30 | 1,000 | 8,000 | 200,000 | | llama-3.1-8b-instant | 30 | 14,400 | 6,000 | 500,000 |

🚨 這裡有一個沒人講、但一定會撞到的坑： 「每分鐘 token」小得驚人。 一小時的中文演講逐字稿大約 9,000～12,000 字，換算下來遠遠超過 12,000 token 的每分鐘上限。 也就是說：你不可能把一整份逐字稿一次丟給它清洗。 一定會拿到 429。 解法：分段送。 步驟五的小程式已經內建分段（預設一段 1,200 字）和自動重試，照著跑就好。

怎麼自己查最新的（模型會改名、額度會變）

| 想查什麼 | 去哪查 | |---------|--------| | 現在有哪些模型（最可靠） | 在終端機跑：curl.exe https://api.groq.com/openai/v1/models -H "Authorization: Bearer $env:GROQ_API_KEY" | | 模型說明頁 | <https://console.groq.com/docs/models> | | 我這個帳號的實際限額 | Console → Settings → Limits（這裡看到的才是你的，文件是通則） | | 語音的檔案大小上限 | <https://console.groq.com/docs/speech-to-text> | | 資料政策 | <https://console.groq.com/docs/your-data> |

📌 本包刻意不寫任何價格。 免費方案用不到，而寫死的價格只會在半年後變成錯誤資訊。 模型名稱也一樣：如果下面哪個模型名在你跑的時候不存在了，先跑上面那行 /v1/models 看它改叫什麼，不要硬套本文件。

---

選哪個 Whisper 模型：研習主線用 whisper-large-v3

Groq 上目前有兩個（查證 2026-07-27）：

| 模型 | 官方標示的準確度 | 速度 | 語言 | |------|-----------------|------|------| | whisper-large-v3 | 錯字率 10.3% | 189 倍即時 | 多語（含中文） | | whisper-large-v3-turbo | 錯字率 12% | 216 倍即時 | 多語（含中文） |

🔴 推薦：whisper-large-v3。理由是一個很多人沒注意到的事實——

在免費方案下，這兩個模型的額度完全一樣（都是 20 次/分、7,200 音訊秒/小時、28,800 音訊秒/日）。 turbo 的賣點是「比較便宜」。但免費方案本來就不用錢，所以那個賣點在這裡等於零。 而速度差多少？189 倍 vs 216 倍。一支 30 分鐘的錄音，一個要 9.5 秒、一個要 8.3 秒。你根本感覺不到。 結論：免費用戶沒有任何理由選 turbo。用準的那個。

什麼時候才換 turbo：你要一次跑幾十個檔、而且真的坐在旁邊等；或者以後升級成付費、開始在意費用。

📌 關於繁體中文的表現：Groq 官方沒有公布任何中文專屬的準確度數字，Whisper 官方也只有整體多語數字。 本包推薦 whisper-large-v3 的依據是「整體錯字率較低」＋「免費方案額度相同」，不是任何中文的實測比較。 實際上兩個模型對台灣國語的表現都算堪用，主要問題不是聽錯字，是專有名詞（人名、地名、課本術語）和繁簡——這兩件事都靠步驟五的清洗解決，換模型幫助不大。

---

選哪個文字模型：主線用 llama-3.3-70b-versatile

| 模型 | 為什麼選／不選 | |------|---------------| | llama-3.3-70b-versatile | ✅ 主線。中文品質在免費模型裡較穩，而且每分鐘 token 上限 12,000 是免費方案裡最大的——清洗逐字稿吃的就是這個 | | openai/gpt-oss-120b | 🟡 備援。主線那個掛掉或改名時用這個 | | llama-3.1-8b-instant | 🟡 量大時用。每日 500,000 token 最寬鬆，但中文品質明顯較弱，適合「整批粗清、之後自己再看過」 |

⚠️ 模型名稱會改。跑之前先用 /v1/models 確認一次（見上方「怎麼自己查最新的」）。

---

🤔 等一下——文字清洗為什麼不直接叫 OpenCode 做就好？

這是研習現場一定會有人問的問題，而且問得很對。

你已經在 01-connect-model 幫 OpenCode 接了模型。要清洗逐字稿，把檔案丟給它說「幫我整理成講義」，它就做完了。幹嘛還要多申請一把 Groq 金鑰、多寫一支程式？

答案是三件事：

| 理由 | 說明 | |------|------| | ① 這一包在教「模式」，不是在教「清洗」 | 呼叫 API 拿結果，這個模式之後接任何服務都通用。清洗只是拿來練手的題目 | | ② 語音那條沒有替代方案 | OpenCode 的模型聽不懂聲音檔。A 線非走 API 不可，而 B 線用同一把金鑰、同一套寫法，順著學最省力 | | ③ 下午要變成網頁 | 10-netlify 會把這個工具放到網路上給別人用。網頁不能呼叫你電腦裡的 OpenCode，只能呼叫 API。今天寫的這支程式，下午直接搬上去 |

💡 所以：日常自己用，直接叫 OpenCode 清洗完全 OK，不必每次都走 API。 但這一包要你走一次 API，是為了讓你手上有一個「離開 OpenCode 也能跑」的東西。

---

先備條件

• [ ] 已完成 00-env-setup 與 01-connect-model
• [ ] 已完成 02-file-toolkit 的 B 段（要用 ffmpeg 和 ffprobe 壓縮、切檔、量長度）
• [ ] 建議完成 07-github（金鑰不外洩這件事在那一包有完整說明）
• [ ] 有網路
• [ ] 手上有一份符合上面隱私紅線的音訊或影片檔

驗證：

ffmpeg -version; ffprobe -version

兩個都印出版本 = 過。

⚠️ ffprobe 常常缺席。 如果只裝了 yt-dlp 自帶的那套 FFmpeg，ffprobe 可能不在 PATH 上。 補裝系統版：winget install --id Gyan.FFmpeg -e（沒有管理員權限就加 --scope user）。 mac：brew install ffmpeg／Linux：sudo apt install -y ffmpeg。 真的裝不起來也還有救——步驟四的小程式有備援做法，看那一節。

📁 先建一個工作資料夾，名字用英數字

New-Item -ItemType Directory -Force "$HOME\Documents\groq-subtitle"

🚨 資料夾和檔名先不要用中文。 Windows 的命令列（PowerShell 5.1）傳中文檔名給 ffmpeg、curl 時偶爾會變亂碼，你會看到「找不到檔案」但檔案明明就在。 做法：轉檔前先把來源改成 lesson01.mp4 這種名字，全部跑完再改回中文。 這一條看起來很瑣碎，但研習現場每一梯都有人卡在這裡半小時。

---

步驟一：申請 Groq 金鑰

🖐️ 全程在瀏覽器手動做。AI agent 不要代為註冊、不要代填任何欄位。

1-1 註冊

1. 開 <https://console.groq.com>
2. 選 Continue with Google 或 Continue with GitHub（建議用 07-github 那個 GitHub 帳號，之後好管理），也可以用 Email
3. 沒有等待清單、不用審核、不會問你要信用卡

1-2 建立金鑰

左側選單 API Keys → Create API Key → 取一個看得懂的名字（例如 研習-字幕工具）→ 建立。

🔴 金鑰只會完整顯示這一次。 關掉視窗之後看不到第二次，只能刪掉重產一把。 現在就複製起來，貼到你的密碼管理器（不是貼到記事本、不是貼到 LINE 給自己）。

金鑰長得像 gsk_ 開頭的一長串。

1-3 順手開啟 Zero Data Retention

Settings → Data Controls → 開啟 Zero Data Retention。

10 秒的事，之後所有請求都適用。（再說一次：開了它，前面那些紅線一條都不會消失。）

1-4 驗證：金鑰是活的嗎

先做完步驟二設定好環境變數，再回來跑這一行（步驟二的驗證裡有）。

---

步驟二：金鑰要放哪裡（🚨 這一步做錯，金鑰會上 GitHub）

🔴 三條絕對規則

① 金鑰不寫進任何 .md 檔案裡 —— 包含你等一下要做的那個 Skill 檔。 ② 金鑰不寫進任何會被 git add 的檔案裡。 ③ 金鑰不貼進聊天視窗（包含貼給 AI agent 看）。

理由：研習的設定檔會投影在大螢幕上、會被拍照；而 GitHub 上有機器人專門在掃新推上去的金鑰，掃到的速度比你發現的速度快。

主線做法：設成環境變數（推薦，整台電腦設一次）

環境變數的好處是：金鑰不存在於任何一個檔案裡，所以永遠不可能被 commit。

Windows（PowerShell）

[System.Environment]::SetEnvironmentVariable("GROQ_API_KEY", "貼上你的金鑰", "User")

設完一定要重開終端機（連 OpenCode 也要完全關掉重開），新的環境變數才會生效。

macOS / Linux（寫進 ~/.zshrc 或 ~/.bashrc，然後 source 一次）

echo 'export GROQ_API_KEY="貼上你的金鑰"' >> ~/.zshrc
source ~/.zshrc

驗證（🔴 這行刻意不印出金鑰本身，可以安心投影）

Windows

if ($env:GROQ_API_KEY) { "KEY_SET len=" + $env:GROQ_API_KEY.Length } else { "KEY_MISSING" }

macOS / Linux

if [ -n "$GROQ_API_KEY" ]; then echo "KEY_SET len=${#GROQ_API_KEY}"; else echo "KEY_MISSING"; fi

看到 KEY_SET len=<某個數字> = 過。看到 KEY_MISSING → 沒重開終端機，或變數名打錯。

驗證金鑰是活的

curl.exe https://api.groq.com/openai/v1/models -H "Authorization: Bearer $env:GROQ_API_KEY"

• 回傳一大段 JSON（裡面看得到 whisper-large-v3）→ ✅ 金鑰可用，順便看到現在有哪些模型
• 回 invalid_api_key → 金鑰複製時少了一截，或前後有多餘的空白，重複製一次

Windows 一定要打 curl.exe（有 .exe），否則會叫到 PowerShell 內建的別名，行為完全不同。

專案做法：.env ＋ .gitignore（下午的 10-netlify 會用到）

如果你的工具要放進一個「會推上 GitHub 的專案資料夾」，用 .env：

先建 .gitignore（🔴 先建這個，再建 .env，順序不能反）

.env
*.key
credentials.*
desktop.ini
*.tmp

再建 .env

GROQ_API_KEY=貼上你的金鑰

驗證 .env 真的被擋掉了：

git status --short

🔴 輸出裡出現 .env 就是失敗——代表 git 還看得到它，下一次 git add . 就會把金鑰送上 GitHub。 回頭檢查 .gitignore 是不是拼錯、是不是放在 repo 根目錄。

更嚴格的檢查（agent 請跑這一行）：

git check-ignore -v .env

有輸出（會告訴你被 .gitignore 第幾行擋掉）= ✅ 過。沒有輸出 = ❌ 沒擋到。

📌 關於 Google 雲端硬碟：.env 放在雲端硬碟資料夾裡會被同步到你的雲端帳號——這通常可以接受（那是你自己的帳號）。 但它跟 .gitignore 是兩回事，雲端同步不會擋 git。兩件事都要做。

如果你要在 opencode.json 裡引用金鑰

本包用不到這件事（我們是自己呼叫 API，不是把 Groq 接成 OpenCode 的模型供應商）。但萬一你之後要：

"environment": { "GROQ_API_KEY": "{env:GROQ_API_KEY}" }

🔴 寫 {env:GROQ_API_KEY}，不要寫實際那串字。 這是 00-env-setup 附錄「MCP 通用守則」第 5 條的規矩，本包完全沿用。

🚨 萬一金鑰不小心外流了

刪掉檔案、刪掉訊息、清掉 git 歷史——全部沒有用。 金鑰已經在別人手上了。

## 唯一有效的處置：回 Console → API Keys → 把那把金鑰刪掉，重新產一把。 這件事做完之前，其他都不用做。做完之後，記得把環境變數也換成新的。

---

步驟三：A 線 — 把聲音變成字幕（.srt）

A1. 先把檔案壓小（🚨 這裡處理陷阱 ②）

免費方案單檔上限 25 MB。一支手機錄的 30 分鐘影片動輒好幾百 MB，直接送一定被打回。

官方建議的做法：降到 16kHz 單聲道、轉成 FLAC。 這樣做不會影響辨識準確度——Whisper 本來就只吃 16kHz，多出來的取樣率和第二個聲道，送上去也是被丟掉。

Groq 官方文件給的指令（原封不動）：

ffmpeg -i "lesson01.mp4" -ar 16000 -ac 1 -map 0:a -c:a flac "clean.flac"

| 參數 | 意思 | |------|------| | -ar 16000 | 取樣率降到 16kHz（Whisper 的原生規格） | | -ac 1 | 併成單聲道 | | -map 0:a | 只要聲音，把影像整個丟掉（影片檔的體積 95% 是影像） | | -c:a flac | 轉成 FLAC（無損壓縮） |

壓完看大小：

"{0:N1} MB" -f ((Get-Item "clean.flac").Length / 1MB)

# macOS / Linux
du -h clean.flac

經驗值：16k 單聲道 FLAC 大約每分鐘 0.8～1 MB。 所以 25 MB ≈ 25～30 分鐘。超過就要切段 → 跳到步驟四。

🟡 真的不想切檔的備案：改用 mp3 低位元率，一小時大約壓到 14 MB。 ``powershell ffmpeg -i "lesson01.mp4" -ar 16000 -ac 1 -map 0:a -c:a libmp3lame -b:a 32k "clean.mp3" `` 代價是有損壓縮，中文的準確度會略微下降。本包主線仍走 FLAC ＋ 切段，這個備案只在時間真的不夠時用。

A2. 呼叫 API

Windows（PowerShell，整段是一行，長是正常的）

curl.exe https://api.groq.com/openai/v1/audio/transcriptions -H "Authorization: Bearer $env:GROQ_API_KEY" -F "file=@clean.flac" -F "model=whisper-large-v3" -F "language=zh" -F "temperature=0" -F "response_format=verbose_json" -o "clean.json"

macOS / Linux

curl https://api.groq.com/openai/v1/audio/transcriptions \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -F "file=@clean.flac" \
  -F "model=whisper-large-v3" \
  -F "language=zh" \
  -F "temperature=0" \
  -F "response_format=verbose_json" \
  -o "clean.json"

| 參數 | 為什麼要 | |------|---------| | model=whisper-large-v3 | 見前面「選哪個模型」 | | language=zh | 一定要加。官方明講：指定語言會同時提升準確度和速度。不加的話它要先花時間猜語言，中英夾雜的課堂錄音很容易猜錯 | | temperature=0 | 要它照聽到的寫，不要自由發揮 | | response_format=verbose_json | 時間碼在這裡面。用 json 或 text 拿不到時間碼 | | -o clean.json | 存成檔案。不存的話一大堆 JSON 會直接噴在螢幕上 |

🚨 A3. 陷阱 ①：不要寫 response_format=srt

OpenAI 的 Whisper API 可以直接回 .srt。Groq 不行。

官方 API 文件寫得很明確——response_format 的 Allowed values 只有 json、text、verbose_json。

打 srt 或 vtt 會拿到 400 錯誤。而網路上 95% 的 Whisper 教學都是寫給 OpenAI 的，照抄過來就會撞這一關。

🔴 請直接記這句話： Groq 只給你「時間碼 ＋ 文字」，.srt 這個檔案要你自己組。 聽起來很麻煩，其實只是把 JSON 換個排版而已——下面那支小程式一次解決，而且以後長檔切段也是同一支。

A4. 把 verbose_json 組成 .srt

在工作資料夾建立 make_srt.py（這支程式不需要安裝任何套件，全部用 Python 內建的）：

# make_srt.py — 把 Groq 的 verbose_json 組成 .srt
# 用法：uv run python make_srt.py 輸出.srt 第1段.json 第2段.json ...
# 只有一段就只傳一個 json；多段會自動接上時間碼偏移（見步驟四）
import json, os, subprocess, sys

def fmt(t):
    """秒數 → SRT 的 00:00:00,000 格式"""
    ms = int(round(t * 1000))
    h, ms = divmod(ms, 3600000)
    m, ms = divmod(ms, 60000)
    s, ms = divmod(ms, 1000)
    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

def real_seconds(path):
    """用 ffprobe 量音訊檔的實際長度（秒）。量不到就回 None"""
    try:
        out = subprocess.run(
            ["ffprobe", "-v", "error", "-show_entries", "format=duration",
             "-of", "csv=p=0", path],
            capture_output=True, text=True, check=True).stdout.strip()
        return float(out)
    except Exception:
        return None

out_path, json_files = sys.argv[1], sys.argv[2:]
if not json_files:
    sys.exit("SRT_FAIL 沒有指定任何 json 檔")

offset, idx, blocks = 0.0, 1, []
for jf in json_files:
    with open(jf, encoding="utf-8") as f:
        data = json.load(f)
    for seg in data.get("segments", []):
        text = (seg.get("text") or "").strip()
        if not text:
            continue
        blocks.append(
            f"{idx}\n{fmt(seg['start'] + offset)} --> {fmt(seg['end'] + offset)}\n{text}\n")
        idx += 1
    # 🚨 陷阱 ④：偏移量用「這一段的實際長度」累加，不要用名目的 600 秒
    audio = os.path.splitext(jf)[0] + ".flac"
    dur = real_seconds(audio) if os.path.exists(audio) else None
    if dur is None:                       # ffprobe 不在？改用 API 回傳的長度
        dur = float(data.get("duration") or 0.0)
    offset += dur

with open(out_path, "w", encoding="utf-8") as f:
    f.write("\n".join(blocks))
print(f"SRT_OK segments={idx - 1} files={len(json_files)} out={out_path}")

跑它：

uv run python make_srt.py "lesson01.srt" "clean.json"

（uv 來自 00-env-setup。沒有 uv 就用 python make_srt.py ...，這支程式只用內建模組，任何 Python 3 都跑得動。）

成功的樣子：印出 SRT_OK segments=<某個數字> files=1 out=lesson01.srt，而且 segments 不是 0。

A5. 🚨 陷阱 ③：字幕變成簡體怎麼辦

Whisper 的語言代碼只有「中文（zh）」，沒有「繁體中文」。 它自己決定要吐繁體還是簡體，同一份檔案跑兩次結果還可能不一樣。

兩條路，建議兩條都做：

路線 A（一次搞定，但 Windows 有編碼坑）：用 prompt 參數暗示它

Whisper 的 prompt 參數是用來「示範風格」的（上限 224 token）。你用繁體字寫這個提示，它輸出繁體的機率會大幅提高。

先用記事本建立 prompt.txt（存檔時編碼選 UTF-8），內容一行：

以下是繁體中文的課堂錄音逐字稿。

然後在 A2 的指令尾巴加一個參數：

-F "prompt=<prompt.txt"

🚨 為什麼要用檔案，不直接把中文寫在指令裡？ Windows PowerShell 5.1 把中文參數傳給 curl.exe 時會用系統的 cp950 編碼，送出去常常變亂碼——而且不會報錯，你只會覺得「這個 prompt 好像沒效」。 -F "欄位名=<檔名" 是 curl 的語法，意思是「這個欄位的值從檔案讀」，直接讀原始位元組，繞過整個編碼問題。 macOS / Linux 沒有這個問題，直接寫中文也可以。

📌 這是社群通用做法，不是官方保證。 有效但不是 100%。所以還要有路線 B。

路線 B（零風險保底）：讓 OpenCode 只改字、不准動時間碼

把產出的 .srt 丟給 OpenCode，說：

幫我把這個 .srt 檔的字幕文字全部改成繁體中文（台灣用語），
順便修掉明顯的錯字。

🔴 硬規定：
- 時間碼那幾行（00:00:00,000 --> 00:00:03,120）一個字都不准改
- 字幕的行數與編號不准增減
- 不要合併或拆開任何一段

🔴 最後那三條一定要講，而且要講得像規定。 不講的話，AI 很常「順手」幫你合併太短的句子、重新分段——結果字幕跟畫面整份對不上，而且看起來完全正常，你要放完整支影片才會發現。

建議做法：路線 A 先做（省事），路線 B 當保底（順便修錯字）。

A6. ✅ A 線驗收：換一份新素材，同一句話能不能再跑一次

這才是這一包的驗收，不是「跑出一個 srt」。

| # | 做什麼 | 通過的樣子 | |---|--------|-----------| | 1 | 用播放器開啟原始影片，把 .srt 拖進去 | 字幕跟嘴巴對得上（不是「有字幕就好」） | | 2 | 跳到影片最後面看 | 最後一句字幕的時間接近影片總長（差很多 = 時間碼歪了，看步驟四） | | 3 | 換一支完全不同的錄音，從 A1 重跑一次 | 一樣跑得完 | | 4 | 🔴 步驟六做完之後：對 OpenCode 說「幫我把 <新檔名> 轉成字幕」 | 它自己做完全部，你沒有再貼任何指令 ← 這一項才是真的通過 |

第 4 項現在還做不到（Skill 還沒包）。先記著它，這是你等一下要達成的目標。

---

步驟四：長音檔怎麼切、時間碼怎麼接（🚨 這裡處理陷阱 ④）

只有超過 25 MB（約 25～30 分鐘）才需要這一步。 短檔請直接跳到步驟五。

官方建議 vs 本包做法

Groq 官方建議的是「切成有重疊的片段，各自轉，合併時處理重疊的部分」，並附了一份 Cookbook 範例。

本包不走重疊那條，理由很實際：重疊之後要判斷「這兩段重複的文字哪一份才對、接縫在哪」，這是整條流程裡最容易寫錯、也最難驗證的部分。對老師來說划不來。

本包做法：不重疊、切固定長度、用「每一段的實際長度」累加時間碼。 代價是接縫處可能斷在句子中間（少一兩個字或斷句怪怪的）。 但這件事步驟五的清洗會順手修掉，而且比起「整份時間碼歪掉」，這個代價便宜太多。

4-1 切檔（先壓再切，順序不能反）

# ① 先壓成 16k 單聲道 FLAC（跟 A1 一模一樣）
ffmpeg -i "lesson01.mp4" -ar 16000 -ac 1 -map 0:a -c:a flac "clean.flac"

# ② 再切成每段 10 分鐘（600 秒）
ffmpeg -i "clean.flac" -f segment -segment_time 600 -c:a flac "chunk_%03d.flac"

會產生 chunk_000.flac、chunk_001.flac、chunk_002.flac…

為什麼是 10 分鐘？ 10 分鐘的 16k 單聲道 FLAC 約 8～10 MB，離 25 MB 上限有很大的安全邊際。 切太小反而浪費（記得「最低計費 10 秒」那條），切太大會踩到上限。10 分鐘是甜蜜點。

為什麼要先壓再切？ 這樣每一段的規格完全一致，量長度、接時間碼都不會出意外。 先切再壓的話，每段會各自被 ffmpeg 處理一次，長度可能出現零點幾秒的差異。

4-2 逐段呼叫 API

Windows（PowerShell）

Get-ChildItem "chunk_*.flac" | Sort-Object Name | ForEach-Object {
  $out = $_.BaseName + ".json"
  Write-Host "轉換中：$($_.Name)"
  curl.exe https://api.groq.com/openai/v1/audio/transcriptions -H "Authorization: Bearer $env:GROQ_API_KEY" -F "file=@$($_.Name)" -F "model=whisper-large-v3" -F "language=zh" -F "temperature=0" -F "response_format=verbose_json" -o $out
  Start-Sleep -Seconds 3
}

macOS / Linux

for f in chunk_*.flac; do
  echo "轉換中：$f"
  curl https://api.groq.com/openai/v1/audio/transcriptions \
    -H "Authorization: Bearer $GROQ_API_KEY" \
    -F "file=@$f" -F "model=whisper-large-v3" -F "language=zh" \
    -F "temperature=0" -F "response_format=verbose_json" \
    -o "${f%.flac}.json"
  sleep 3
done

💡 中間的 Start-Sleep 3 / sleep 3 是刻意的：免費方案每分鐘 20 次，這樣跑絕對不會撞到上限。 一支 1 小時的錄音會切成 6 段，全部跑完大約 1 分鐘。

檢查每一段都有回來：

Get-ChildItem "chunk_*.json" | Select-Object Name, Length

🔴 有哪個 .json 大小只有幾百 bytes → 那一段失敗了，裡面裝的是錯誤訊息不是字幕。 用記事本打開看它寫什麼，對照本文件最後的「常見卡關」。不要就這樣往下做，那一段的字幕會整段消失。

4-3 合併（🚨 這裡就是陷阱 ④）

為什麼不能直接接起來

每一段轉回來的時間碼，都是從 00:00:00 開始的。

也就是說第二段的第一句話，API 說它在 0 分 3 秒——但它實際上在整支影片的 10 分 3 秒。 直接把 6 段接起來，你會得到一份「前 10 分鐘有 6 份字幕、後面 50 分鐘全空」的檔案。

正確做法：加偏移量。但不能用「10 分鐘」硬算

🔴 這是本包最細、也最多人做錯的一條： ffmpeg 的 -segment_time 600 是「大約 600 秒」，不是「剛好 600 秒」——實際切點會落在音訊的封包邊界上。 每段差個零點幾秒，六段累積起來就是好幾秒。 字幕一開始對得很好，越到後面越飄——而這種錯誤最難發現，因為前 10 分鐘完全正常。 正解：用 ffprobe 量每一段的實際長度，一段一段累加。 make_srt.py 已經內建這個做法（real_seconds() 那個函式），你不用自己算。

直接跑（把所有 json 按順序一次餵進去）：

Windows

$files = (Get-ChildItem "chunk_*.json" | Sort-Object Name).Name
uv run python make_srt.py "lesson01.srt" $files

macOS / Linux

uv run python make_srt.py "lesson01.srt" $(ls chunk_*.json | sort)

🔴 順序絕對不能錯。 chunk_010.json 一定要排在 chunk_002.json 後面。 上面用了 Sort-Object Name / sort，而檔名是三位數補零的（%03d），所以字母排序就是正確順序。 如果你自己手動列檔名，請務必檢查順序——順序一錯，整份字幕會亂到看不出規律。

📌 ffprobe 真的裝不起來的備援：make_srt.py 量不到長度時，會自動改用 API 回傳的 duration 欄位。 那個數字是 Groq 算的，通常也很準，只是不像 ffprobe 那樣是直接量檔案。能裝 ffprobe 還是裝。

4-4 驗證時間碼有沒有歪（🔴 這一步不要跳過）

這是唯一能抓到時間碼漂移的方法：

| # | 做什麼 | 通過的樣子 | |---|--------|-----------| | 1 | 看原始影片的總長度 | 記下來，例如 58:20 | | 2 | 用記事本打開 .srt，捲到最後一行 | 最後一個時間碼很接近 58:20（差 5 秒內算正常） | | 3 | 把 .srt 拖進播放器，跳到影片最後 2 分鐘 | 字幕還對得上嘴巴 | | 4 | 跳到每一個接縫處（10 分、20 分、30 分…） | 那附近的字幕沒有明顯偏移 |

🔴 只驗開頭是抓不到這個 bug 的。 時間碼漂移的特徵就是「前面完全正常」。 一定要看最後面。

歪掉了怎麼辦：

| 症狀 | 原因 | |------|------| | 最後一句只到 10:00 左右 | 只餵了一個 json 進去，或檔案順序被打亂 | | 越後面偏差越大 | ffprobe 沒裝，而且 API 的 duration 也不準 → 補裝系統版 FFmpeg 再跑一次 make_srt.py（不用重轉，json 都還在） | | 中間整段字幕消失 | 某一段的 .json 其實是錯誤訊息（回 4-2 檢查每個 json 的大小） |

---

步驟五：B 線 — 把逐字稿清洗成講義

5-1 先把 srt 變成純文字

字幕檔裡有編號和時間碼，那些不需要送去清洗（還會白白吃掉寶貴的 token 額度）。

uv run python -c "import re,sys;t=open('lesson01.srt',encoding='utf-8').read();lines=[l for l in t.splitlines() if l.strip() and not l.strip().isdigit() and '-->' not in l];open('lesson01.txt','w',encoding='utf-8').write('\n'.join(lines))"

或者更簡單——直接把 .srt 丟給 OpenCode 說「把時間碼和編號拿掉，只留文字，存成 lesson01.txt」。

5-2 建立清洗程式

在同一個資料夾建立 clean.py（一樣不需要安裝任何套件）：

# clean.py — 把逐字稿清洗成可讀講義（Groq Chat Completions）
# 用法：uv run python clean.py 逐字稿.txt 講義.md
import json, os, sys, time, urllib.error, urllib.request

API   = "https://api.groq.com/openai/v1/chat/completions"
MODEL = "llama-3.3-70b-versatile"   # 會改名！先跑 /v1/models 確認
LIMIT = 1200                        # 每段送幾個字。免費方案 TPM 很小，不要調大

KEY = os.environ.get("GROQ_API_KEY")
if not KEY:
    sys.exit("CLEAN_FAIL 環境變數 GROQ_API_KEY 沒設，回步驟二")

SYSTEM = (
    "你是台灣國中小老師的文字編輯助理。把語音辨識出來的逐字稿，"
    "整理成可以直接發給學生看的講義段落。規則："
    "① 一律輸出繁體中文，用台灣的慣用詞；"
    "② 刪掉贅詞、口頭禪、結巴、重複、以及講者自己更正掉的前半句；"
    "③ 補上標點符號，依語意分段；"
    "④ 不要新增原文沒有的內容，不要加自己的解釋；"
    "⑤ 聽不出來的地方原樣保留，並在後面加上 [?]；"
    "⑥ 不要寫開場白或結語，直接輸出整理後的內文。"
)

def split_text(raw, limit):
    """依行切段，盡量不切在句子中間"""
    parts, buf = [], ""
    def flush():
        nonlocal buf
        if buf.strip():
            parts.append(buf)
        buf = ""
    for line in raw.splitlines(keepends=True):
        while len(line) > limit:          # 整篇沒換行的長文，只好硬切
            flush()
            parts.append(line[:limit])
            line = line[limit:]
        if len(buf) + len(line) > limit:
            flush()
        buf += line
    flush()
    return parts

def call(text):
    body = json.dumps({
        "model": MODEL,
        "temperature": 0.2,
        "messages": [{"role": "system", "content": SYSTEM},
                     {"role": "user",   "content": text}],
    }).encode("utf-8")
    req = urllib.request.Request(API, data=body, headers={
        "Authorization": "Bearer " + KEY,
        "Content-Type": "application/json",
    })
    with urllib.request.urlopen(req, timeout=180) as r:
        return json.load(r)["choices"][0]["message"]["content"].strip()

raw   = open(sys.argv[1], encoding="utf-8").read()
parts = split_text(raw, LIMIT)
out   = []

for n, p in enumerate(parts, 1):
    print(f"清洗第 {n}/{len(parts)} 段…")
    for attempt in range(3):
        try:
            out.append(call(p))
            break
        except urllib.error.HTTPError as e:
            detail = e.read().decode("utf-8", "ignore")[:300]
            if e.code == 429 and attempt < 2:      # 額度滿了，等一下再試
                print("   額度滿了，等 35 秒再試")
                time.sleep(35)
                continue
            sys.exit(f"CLEAN_FAIL http={e.code} {detail}")
    time.sleep(2)                                   # 段與段之間刻意留間隔

open(sys.argv[2], "w", encoding="utf-8").write("\n\n".join(out))
print(f"CLEAN_OK pieces={len(parts)} out={sys.argv[2]}")

跑它：

uv run python clean.py "lesson01.txt" "lesson01-講義.md"

成功的樣子：一段一段印出進度，最後印 CLEAN_OK pieces=<數字> out=lesson01-講義.md。

5-3 為什麼要分段、為什麼中間要等

| 設計 | 理由 | |------|------| | LIMIT = 1200（一段 1,200 字） | 免費方案 llama-3.3-70b-versatile 每分鐘只有 12,000 token。一小時的逐字稿一次送必定 429 | | 段與段之間 sleep 2 | 讓每分鐘的 token 用量攤平，不會集中在前 10 秒燒完 | | 遇到 429 等 35 秒重試 | token 額度是每分鐘重置的，等一下就會恢復 |

🔴 不要把 LIMIT 調大想跑快一點。 調大只會讓你更快撞到 429，然後每次都要等 35 秒，整體反而更慢。

5-4 想要別的產出，改 SYSTEM 那段就好

clean.py 裡的 SYSTEM 字串就是「你要它做什麼」。改那一段，這支程式就變成另一個工具：

| 你想要 | SYSTEM 改成 | |--------|--------------| | 講義（預設） | 上面那段 | | 課堂重點摘要 | 「把逐字稿整理成 5～8 條重點，每條一行，用繁體中文…」 | | 學生自學版（口語轉書面） | 「把逐字稿改寫成適合國中生自己閱讀的說明文…」 | | 抽出考題素材 | 「從逐字稿裡找出可以出題的概念，列成清單…」 |

💡 這就是「把 API 變成工具」的意思——同一支程式、同一把金鑰，換一段話就換一個工具。

5-5 ✅ B 線驗收：換一份新素材，同一句話能不能再跑一次

| # | 做什麼 | 通過的樣子 | |---|--------|-----------| | 1 | 打開 lesson01-講義.md | 是通順的繁體中文段落，不是一長串沒標點的字 | | 2 | 跟原逐字稿對照 | 意思沒被改掉、沒有多出原文沒講過的內容 | | 3 | 找一段你記得自己講錯又更正的地方 | 更正前那半句被刪掉了 | | 4 | 換一份完全不同的逐字稿，重跑一次 | 一樣跑得完 | | 5 | 🔴 步驟六做完之後：對 OpenCode 說「幫我把 <新檔名> 整理成講義」 | 它自己做完，你沒有再貼指令 ← 這一項才是真的通過 |

⚠️ 第 2 項要真的看。語言模型偶爾會「幫你補充」——補出來的東西看起來很專業，但你根本沒講過。 發講義前自己讀一遍，這件事不能外包。

---

步驟六：把整條流程包成 Skill（🔴 這是作品⑤ 的正題）

前面五步都是「跑一次」。跑一次的東西下個月一定忘記。

現在把它變成一個技能：以後在任何資料夾、對 OpenCode 說一句人話，它就會自己做完。

6-1 建立技能資料夾

Windows

New-Item -ItemType Directory -Force "$HOME\.config\opencode\skills\audio-notes"

macOS / Linux

mkdir -p ~/.config/opencode/skills/audio-notes

⚠️ 資料夾名稱要和技能的 name 一模一樣，檔名要是全大寫的 SKILL.md，OpenCode 才掃得到。（規矩同 08-workflow-skills。）

6-2 把兩支小程式搬進去

Copy-Item "$HOME\Documents\groq-subtitle\make_srt.py" "$HOME\.config\opencode\skills\audio-notes\"
Copy-Item "$HOME\Documents\groq-subtitle\clean.py"    "$HOME\.config\opencode\skills\audio-notes\"

🔴 搬之前先確認這兩支檔案裡沒有金鑰。 它們讀的是 os.environ.get("GROQ_API_KEY")，本來就沒有——但如果你剛剛「為了測試方便」把金鑰貼死在裡面，現在就是把它拿掉的時候。

6-3 建立 SKILL.md

把下面整段內容原封不動寫入 ~/.config/opencode/skills/audio-notes/SKILL.md （不要把最外層的 ``` ` `` 圍籬符號寫進檔案，檔案第一行必須是 ---`）：

---
name: audio-notes
description: 把音訊或影片轉成字幕檔（.srt），以及把逐字稿清洗成可讀講義（.md）。當使用者說「轉字幕」、「上字幕」、「做逐字稿」、「這個錄音幫我轉文字」、「把逐字稿整理成講義」、「把這段錄音變成講義」時，請一定要使用此技能。走 Groq 的 Whisper 與文字模型，金鑰讀自環境變數 GROQ_API_KEY。
---

# 音訊 → 字幕 → 講義

## 🔴 執行前必問（不可跳過）

動手之前，先問使用者這一句，**等到回答再繼續**：

> 「這個音檔裡面**有沒有學生、家長的聲音**，或是輔導、個案相關的內容？
> 有的話這條流程不能用——語音會上傳到雲端。」

- 回答「有」或「不確定」 → **停止，不要呼叫任何 API**，把原因說清楚
- 回答「沒有，只有我自己的聲音」 → 繼續

順便提醒一次：**上傳前先聽檔案的最後 30 秒**，課堂錄音常常錄到下課後的對話。

## 金鑰

金鑰一律從環境變數 `GROQ_API_KEY` 讀取。

- **不准**把金鑰寫進本檔案、寫進任何 `.py`、寫進任何會被 commit 的檔案
- **不准**把金鑰印在終端機上、或複述給使用者看
- 環境變數不存在 → 停下來，請使用者依懶人包 `09-groq-api` 步驟二設定，**不要自己想辦法繞過**

## 模式 A：音訊 → 字幕（.srt）

1. **檢查工具**：`ffmpeg -version`、`ffprobe -version`。缺了就停下來告訴使用者（懶人包 `02-file-toolkit` B 段）
2. **檔名先換成英數字**（中文檔名在 Windows 命令列可能亂碼），全部跑完再改回來
3. **壓縮**：
   `ffmpeg -i <來源> -ar 16000 -ac 1 -map 0:a -c:a flac clean.flac`
4. **看大小**。25 MB 以內 → 跳到第 6 步；超過 → 第 5 步
5. **切段**（每段 600 秒）：
   `ffmpeg -i clean.flac -f segment -segment_time 600 -c:a flac chunk_%03d.flac`
6. **逐段呼叫 API**，每次之間停 3 秒：
   端點 `https://api.groq.com/openai/v1/audio/transcriptions`
   參數 `model=whisper-large-v3`、`language=zh`、`temperature=0`、`response_format=verbose_json`
   輸出存成與音訊同名的 `.json`
   - 🚨 **`response_format` 不可以填 `srt` 或 `vtt`**，Groq 不支援，會回 400
7. **檢查每個 `.json`**：檔案太小（幾百 bytes）代表那一段失敗了，是錯誤訊息不是字幕。**先處理再往下**
8. **組 srt**（json 一定要照檔名排序傳入）：
   `uv run python <本技能資料夾>/make_srt.py <輸出>.srt chunk_000.json chunk_001.json ...`
9. **繁體化**：把產出的 srt 逐句改成繁體中文並修錯字。
   🔴 **時間碼那幾行一個字都不准改，行數與編號不准增減，不准合併或拆開任何一段。**
10. **回報**：段數、輸出路徑，並提醒使用者「請拖進播放器確認**最後 2 分鐘**的字幕還對得上」

## 模式 B：逐字稿 → 講義（.md）

1. 來源是 `.srt` → 先去掉編號與時間碼，只留文字，存成 `.txt`
2. 執行：`uv run python <本技能資料夾>/clean.py <逐字稿>.txt <輸出>.md`
3. 拿到 `CLEAN_OK` 才算成功
4. 回報時**一定要加這句**：「語言模型偶爾會補充原文沒有的內容，**發給學生前請自己讀一遍**」

## 常見狀況

| 狀況 | 處理 |
|------|------|
| `400` 且訊息提到 `response_format` | 用了 `srt`／`vtt`，改成 `verbose_json` |
| `413` 或檔案太大 | 沒壓縮，或壓完仍超過 25 MB → 回去切段 |
| `429` | 額度滿了，等 35 秒再試，**不要換模型硬闖** |
| `401` / `invalid_api_key` | `GROQ_API_KEY` 沒設或設錯 → 停下來請使用者處理 |
| 模型名稱不存在 | 跑 `https://api.groq.com/openai/v1/models` 看現在有哪些，不要亂猜 |
| 字幕越後面越對不上 | `ffprobe` 沒裝，`make_srt.py` 量不到每段實際長度。補裝 FFmpeg 後**重跑 make_srt.py 就好，不用重轉** |

## 不該做的事

- ❌ 使用者沒回答隱私那一題就開始上傳
- ❌ 把金鑰寫進任何檔案或印出來
- ❌ 修改 srt 的時間碼
- ❌ 為了「快一點」把清洗的分段字數調大（只會更快撞 429）
- ❌ 一次送幾十個很短的小檔（最低計費 10 秒，額度會白白燒光）

## 注意事項

- 所有訊息使用**繁體中文**
- Windows 用 PowerShell，串指令用 `;` 不要用 `&&`
- Windows 呼叫 curl 要打 `curl.exe`（有 `.exe`）

6-4 允許這個技能

打開（或建立）~/.config/opencode/opencode.json，確認 permission.skill 裡有這一項：

{
  "permission": {
    "skill": {
      "audio-notes": "allow"
    }
  }
}

⚠️ 如果 opencode.json 已經有內容（前面幾包加的 MCP 設定、08-workflow-skills 加的三個技能），不要整份覆蓋，只要把 audio-notes 這一行併進既有的 permission.skill 區塊就好。

6-5 重啟 OpenCode

OpenCode 只有啟動時才會掃描技能目錄。 剛剛新增的資料夾，要完全關掉再重開才會被認得（關視窗不算，要真的結束程序）。

6-6 ✅ 最終驗收：這一包成不成功，看這裡

| # | 做什麼 | 通過的樣子 | |---|--------|-----------| | 1 | 對 OpenCode 說「列出你現在可用的技能」 | 清單裡有 audio-notes | | 2 | 拿一份全新的、沒跑過的錄音，說「幫我把 <檔名> 轉成字幕」 | 它自己壓縮、呼叫 API、組 srt、繁體化，你沒有貼任何指令 | | 3 | 檢查它有沒有先問隱私那一題 | 有問 ← 沒問的話回去看 SKILL.md 是不是貼漏了 | | 4 | 拿一份全新的逐字稿，說「幫我把 <檔名> 整理成講義」 | 它自己做完 | | 5 | 打開 SKILL.md、make_srt.py、clean.py 搜尋 gsk_ | 🔴 三個檔案裡都搜不到 ← 搜到就是失敗，回步驟二 |

## 🔴 第 2 項和第 4 項就是這一包的分水嶺。 做得到 = 你有了一個工具。做不到 = 你只是跑過一次。 差別在下個月：有工具的人會再用，跑過一次的人早就忘了。

---

常見卡關

金鑰與帳號

| 症狀 | 原因 / 解法 | |------|------------| | KEY_MISSING | 環境變數沒生效。重開終端機（連 OpenCode 也要完全關掉重開） | | 401 / invalid_api_key | 金鑰複製時少一截，或前後多了空白。回 Console 重新產一把 | | 金鑰畫面關掉了才發現沒複製 | 看不回來，只能刪掉重產。 這是設計，不是壞掉 | | 註冊時要求信用卡 | 你走進升級流程了。 按上一頁退出來，免費方案不需要卡 | | 金鑰不小心 push 上 GitHub | 刪檔案沒用。立刻回 Console 刪掉那把金鑰、重產一把。 然後更新環境變數 |

A 線（轉字幕）

| 症狀 | 原因 / 解法 | |------|------------| | 400 提到 response_format | 🚨 陷阱 ①。填了 srt／vtt，Groq 不支援。改 verbose_json，用 make_srt.py 組 | | 413 / 檔案太大 | 🚨 陷阱 ②。免費方案單檔 25 MB。回 A1 壓縮，還是太大就切段 | | 轉出來是簡體 | 🚨 陷阱 ③。看 A5 兩條路線 | | .srt 拖進播放器沒反應 | 檔名要和影片同名（lesson01.mp4 ↔ lesson01.srt），或播放器裡手動載入 | | 字幕全部集中在前 10 分鐘 | 🚨 陷阱 ④。只餵了一個 json，或檔案順序亂了。回 4-3 | | 越後面偏差越大 | ffprobe 沒裝。補裝 FFmpeg，重跑 make_srt.py 就好，不用重轉（json 都還在） | | 中間有一整段沒字幕 | 那一段的 .json 是錯誤訊息。回 4-2 檢查每個 json 的大小 | | SRT_OK segments=0 | API 回的 json 裡沒有 segments——多半是 response_format 沒填 verbose_json | | 字幕內容整段重複 | 音檔裡有長時間靜音，Whisper 的已知行為。剪掉靜音再轉 | | ffmpeg 說找不到檔案，但檔案就在 | 中文檔名 ／ 路徑有空白。先改成英數字檔名，或整個路徑用雙引號包起來 | | 一句一個檔跑，額度突然沒了 | 最低計費 10 秒。改成切 10 分鐘大段 |

B 線（文字清洗）

| 症狀 | 原因 / 解法 | |------|------------| | 429 | 每分鐘 token 額度滿了。程式會自己等 35 秒重試；一直發生就把 LIMIT 調小（例如 800） | | CLEAN_FAIL http=404 | 模型改名了。跑 /v1/models 看現在叫什麼，改 clean.py 的 MODEL | | 講義裡出現我沒講過的內容 | 語言模型「幫你補充」了。把 SYSTEM 的第 ④ 條講更重，或改用比較大的模型 | | 輸出還是簡體 | SYSTEM 第 ① 條被忽略了。在使用者訊息開頭再寫一次「請用繁體中文（台灣）輸出」 | | 跑很慢 | 正常。免費方案要分段＋等待。一小時的逐字稿約 10 段，大約 2～3 分鐘 | | 專有名詞一直錯 | 語音辨識階段就聽錯了。把正確寫法列在 SYSTEM 裡，例如「本文的專有名詞：正三角形、外心、內心」 |

Skill 與環境

| 症狀 | 原因 / 解法 | |------|------------| | 技能沒出現在清單 | ①檔名要全大寫 SKILL.md ②資料夾名要等於 name ③檔案第一行必須是 ---（圍籬符號不要寫進去）④沒重啟 OpenCode | | 技能叫得動但找不到 .py | SKILL.md 裡要用技能資料夾的完整路徑叫程式，不是相對路徑 | | uv 說找不到 | 回 00-env-setup。或直接用 python make_srt.py ...，這兩支程式只用內建模組 | | ffprobe 找不到 | 只裝了 yt-dlp 自帶的 FFmpeg。winget install --id Gyan.FFmpeg -e（沒管理員權限加 --scope user） | | PowerShell 串指令語法錯誤 | PowerShell 5.1 不支援 &&，改用 ; | | curl 行為很奇怪 | Windows 要打 curl.exe（有 .exe），否則叫到 PowerShell 的別名 | | 中文參數傳給 curl 變亂碼 | PowerShell 5.1 的編碼問題。改用 -F "欄位=<檔名" 從檔案讀（見 A5） | | opencode.json 存檔後 OpenCode 起不來 | JSON 格式：大括號要成對、引號要用英文半形 "、Windows 路徑反斜線寫兩條 \\ |

---

✅ 成功訊號（機器可判讀）

執行完請完整輸出下面這個區塊，讓後續的 agent 可以直接判讀。

=== OPENCODE_GROQ_API ===
result=PASS                  # PASS | PARTIAL | FAIL
os=windows                   # windows | macos | linux
privacy_confirmed=yes        # yes | no（使用者已確認素材不含學生/家長聲音）
key_set=yes                  # yes | no（環境變數 GROQ_API_KEY 存在）
key_in_files=no              # no | yes（SKILL.md 與 .py 內是否搜得到 gsk_）
api_ok=yes                   # yes | no（/v1/models 回傳正常）
ffmpeg=ok                    # ok | missing
ffprobe=ok                   # ok | missing（缺了會退用 API 的 duration）
model_stt=whisper-large-v3   # 實際使用的語音模型
model_llm=llama-3.3-70b-versatile   # 實際使用的文字模型
srt_single=OK                # OK | FAIL | SKIP（單檔轉字幕）
srt_chunked=OK               # OK | FAIL | SKIP（長檔切段合併）
srt_tail_aligned=yes         # yes | no（影片最後 2 分鐘字幕仍對得上）
clean_ok=OK                  # OK | FAIL | SKIP
skill_installed=yes          # yes | no（~/.config/opencode/skills/audio-notes/）
skill_listed=yes             # yes | no（重啟後 OpenCode 掃得到）
skill_rerun_srt=OK           # OK | FAIL（換新素材，一句話跑完 A 線）
skill_rerun_clean=OK         # OK | FAIL（換新素材，一句話跑完 B 線）
=== END ===

判定規則（agent 請照這個判斷，不要自行認定）：

| 結果 | 條件 | |------|------| | PASS | skill_rerun_srt=OK 且 skill_rerun_clean=OK 且 key_in_files=no | | PARTIAL | A、B 兩線手動跑得起來，但技能沒包成／換素材沒跑通 | | FAIL | api_ok=no，或 A、B 兩線都跑不起來 |

## 🔴 兩條會直接讓整體變成 FAIL 的： key_in_files=yes —— 金鑰出現在任何檔案裡，不管其他項目多漂亮，一律 FAIL。 privacy_confirmed=no —— 沒跟使用者確認過素材內容就上傳，一律 FAIL，而且要在回報裡明確寫出來。 這兩條不准「先繼續、之後再補」。

---

完成回報格式

## Groq API 工具化結果

### 隱私確認
- 已向使用者確認素材不含學生／家長／輔導內容：是 / 否
- 已提醒「上傳前聽最後 30 秒」：是 / 否
- Zero Data Retention 已開啟：是 / 否 / 未確認

### 金鑰
- 存放方式：環境變數 / 專案 .env
- `.gitignore` 已擋住 `.env`（`git check-ignore -v .env` 有輸出）：是 / 否 / 不適用
- SKILL.md 與 .py 內搜尋 `gsk_`：查無 / ⚠️ 有（立刻撤銷重產）
- 金鑰驗證（`/v1/models`）：PASS / FAIL

### A 線：轉字幕
- 使用模型：<實際用的>
- 來源檔長度：<分鐘> ／ 壓縮後大小：<MB>
- 是否切段：否 ／ 是（<N> 段，每段 600 秒）
- 產出：`<路徑>.srt`（<N> 句）
- 時間碼驗證（看**最後 2 分鐘**）：PASS / FAIL
- 繁體化方式：prompt 參數 / OpenCode 改字 / 兩者都做

### B 線：文字清洗
- 使用模型：<實際用的>
- 分段數：<N>
- 產出：`<路徑>.md`
- 已提醒使用者「發給學生前自己讀一遍」：是 / 否

### 工具化（本包正題）
- 技能位置：`~/.config/opencode/skills/audio-notes/`
- 隨附程式：`make_srt.py`、`clean.py`
- `opencode.json` 權限已加：是 / 否
- 已重啟 OpenCode：是 / 否
- 技能出現在清單：是 / 否
- 🔴 **換新素材、一句話跑完 A 線**：PASS / FAIL
- 🔴 **換新素材、一句話跑完 B 線**：PASS / FAIL

### 待處理
- <把 FAIL 的項目與原因列在這裡；全部 PASS 就寫「無」>

---

如果做壞了，怎麼重來

對 OpenCode 說：「Groq 這一包做壞了，幫我清乾淨重來。」

| 想重來的東西 | 做法 | |-------------|------| | 只是某一段轉壞了 | 刪掉那一段的 .json，重跑那一段就好。其他段不用重轉 | | 時間碼歪了 | 補裝 ffprobe，重跑 make_srt.py。API 不用重打，json 都還在 | | 字幕整份要重來 | 刪掉 chunk_*.json 和 .srt，從 4-2 重跑 | | 技能沒被掃到 | 檢查檔名是不是 SKILL.md（全大寫）、資料夾名是不是 audio-notes、第一行是不是 ---。改完完全關閉 OpenCode 再開 | | 技能整個不要了 | 刪掉 ~/.config/opencode/skills/audio-notes/ 資料夾，並從 opencode.json 的 permission.skill 移除那一行 | | 金鑰外洩 | 🔴 Console → API Keys → 刪掉那把、重產一把 → 更新環境變數。這件事優先於其他所有事 |

⚠️ 重跑 API 之前先想一下額度：免費方案每小時 7,200 音訊秒。 一支 1 小時的錄音重轉三次就用掉一半。先確認是哪一步壞了，不要整條重來。

---

下一步

## 🚀 下午：把這個工具變成網頁 → 10-netlify 現在你有一個「只有你的電腦能用」的工具。 下午那一包會把它放上網路——別的老師打開網址就能用，不用裝 OpenCode、不用申請金鑰。 今天早上寫的 clean.py、學到的「金鑰放環境變數不放檔案」，下午會原封不動用上。 （尤其是金鑰那條：網頁上線之後，金鑰放錯地方是全世界都看得到。這件事今天先練，下午就不會慌。）

其他方向：

• 素材從哪裡來（下載影片、抽音軌、抓現成字幕）→ 02-file-toolkit 的 B 段
• 產出的講義要收進第二大腦 → 04-obsidian
• 工具要備份、換電腦也帶著走 → 07-github
• 想讓「轉字幕」也能被開工／收工流程接住 → 08-workflow-skills

📌 提醒一件事：~/.config/opencode/skills/ 底下的技能不在任何專案的 repo 裡。 換一台電腦，這個技能不會跟著過去。要帶著走，就把 audio-notes 這個資料夾也放進你的 GitHub（見 07-github）——但記得，裡面永遠不要有金鑰。