| name | opencode-file-toolkit |
| description | 安裝 agent 的內部工具包三合一——A 文件處理（Word/Excel/PPT/PDF/圖片/QR/轉 Markdown 的 Python 標配 10 套件）、B 影音工具（yt-dlp／FFmpeg／deno）、C 語音（Edge-TTS 讓 agent 開口說話）。說「裝內部工具包」「裝教學檔案處理工具包」「裝 Python 檔案工具」「裝 yt-dlp」「裝影音下載工具」「讓 agent 會說話」「裝 Edge-TTS」「裝語音」時載入。 |
內部工具包 三合一（文件／影音／語音）
研習六「作品階梯」的內部工具級：不是給學生用的網頁作品，而是讓 agent 長出手腳的一組工具。裝好之後，你對 OpenCode 說一句人話，它就能真的幫你產出獎狀、成績表、簡報、PDF、QR Code，也能下載影片抽字幕，還能開口把結論唸給你聽。
這一包裝三類工具，各自解決什麼
| 段 | 裝什麼 | 解決什麼問題 | 今天用得到嗎 |
|---|
| 標配 A：文件處理 | Python 10 套件（uv 裝進專案 .venv） | 讀 PDF 生教案、套印獎狀、算成績、做簡報、生 QR Code | ✅ 今天下午就用 |
| 標配 B：影音工具 | yt-dlp／FFmpeg／deno（系統工具，winget／brew） | 下載影片、抽字幕、轉 mp3 餵 AI | ⏭️ 今天不會用到，第二、三天的影片剪輯會 |
| 標配 C：語音 | edge-tts（Python 模組，微軟雲端語音、免金鑰） | 讓 agent 用台灣中文把結論唸出來 | ✅ 今天就用，裝完 30 秒內聽得到 |
🔀 三段彼此獨立，任一段失敗不影響其他兩段。
每段都有自己的驗證步驟與成功訊號。研習現場如果進度落後，先裝 A 和 C（今天要用），B 留課後自己補——B 沒裝完全不影響 A、C 能不能用。
這一份是懶人包入口。A 段實際的安裝腳本與驗證程式放在另一個 repo：
**https://github.com/mathruffian-dot/ai-agent-ep03**（預設分支是 master，不是 main）
本文件只負責：這是什麼、怎麼裝、怎麼驗、卡住怎麼辦。細部腳本以那個 repo 為準。
這包能幹嘛（裝完就能對 agent 說的話）
A 段（文件）
| 你想做的事 | 裝完後直接說 |
|---|
| 套印獎狀／通知單 | 「讀這份名單 Excel，套進這個獎狀 Word 模板，每人產一份」 |
| 成績計算＋標紅 | 「算總分與排名，不及格標紅，各班平均放最後一列」 |
| 大綱變簡報 | 「把這份教材大綱，每個重點做成一頁投影片」 |
| PDF 合併／抽頁／浮水印 | 「把這些 PDF 合併，第 5～8 頁另存，每頁加淡灰浮水印」 |
| 連結變 QR Code | 「把這 5 個連結各生一張 QR Code」 |
| 課本轉乾淨文字餵 AI | 「把這份 PDF 轉成 Markdown」 |
B 段（影音）
| 你想做的事 | 裝完後直接說 |
|---|
| 抓公開影片的字幕當逐字稿 | 「幫我抓這支影片的中文字幕，轉成 SRT」 |
| 只要聲音餵給 AI 摘要 | 「把這支影片下載成 mp3」 |
| 下載素材影片來剪 | 「用最高畫質下載這支影片」 |
C 段（語音）
| 你想做的事 | 裝完後直接說 |
|---|
| 讓 agent 唸結論 | 「把剛剛的結論用語音唸給我聽」 |
| 生一段旁白音檔 | 「把這段課程說明存成 mp3，我要放進影片」 |
先備條件
共同
A 段／C 段
B 段
⛔ 給 Agent 的七條規則（安裝前先讀，這幾條是防呆用的）
使用者說「裝內部工具包」「裝教學檔案處理工具包」時，逐條遵守：
- 只在專案資料夾內工作 — A 段以
ai-agent-ep03 資料夾為根，不要去掃其他磁碟或其他 agent 的目錄。
- 只裝三段標配（A 的 10 個套件、B 的三個系統工具、C 的 edge-tts） — 下方 A 段「選配」與「其他系統工具」一律不裝，除非使用者明確點名用途。
📌 v2 起 edge-tts 與 yt-dlp 已從「選配」升級為標配 B／C，這是本次擴充的刻意變更，不是誤裝。舊版文件把這兩個列在「預設不要裝」，以本文件為準。
- 禁止全域
pip install — A 段一律裝進該資料夾的 .venv，C 段用 uv tool install（獨立隔離環境），都不要污染使用者原有的 Python。
- 禁止逐項上網研究 — 版本解析交給
uv，不要為每個套件開網頁、寫長篇計畫或重複說明。
- 最多重試一次 — 失敗就回報原始錯誤訊息與建議，不要反覆改指令、重裝、或自行提權。
- 不自動切換執行環境 — Windows、WSL、Docker、沙盒是不同環境，不要為了裝成功就自己跳去 WSL 或換 agent。
- 三段各自獨立、各自回報 — A／B／C 任一段失敗，繼續把其他兩段做完，最後在成功訊號裡分段標示，不要整份中斷、也不要用「裝別段」來補救失敗那段。
🟢 標配 A：文件處理（Python 10 套件）
✅ 今天下午就會用到。 裝好之後 agent 才有辦法讀 PDF 生教案、套印獎狀、做簡報。
這一段完全不需要 B、C 段的任何東西。
A 段步驟
A1. 取得工具包
git clone https://github.com/mathruffian-dot/ai-agent-ep03.git
cd ai-agent-ep03
⚠️ 預設分支是 master。不要硬指定 -b main，會失敗。
A2. 確認版本釘選是最新的
打開 requirements-core.txt，確認內容如下（matplotlib 要是 3.11.1，舊版檔案可能還寫 3.11.0，請改掉）：
python-docx==1.2.0
openpyxl==3.1.5
python-pptx==1.0.2
pypdf==6.14.2
PyMuPDF==1.28.0
reportlab==5.0.0
Pillow==12.3.0
matplotlib==3.11.1
qrcode[pil]==8.2
markitdown[pdf,docx,pptx,xlsx]==0.1.6
A3. 安裝
Windows（有現成腳本，走這條）
在 ai-agent-ep03 資料夾內執行：
powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\install_windows.ps1"
腳本會依序：找 uv（沒有就用 WinGet 裝官方 astral-sh.uv）→ 建 .venv → 依 requirements-core.txt 安裝 → 執行 verify_core.py。
🔒 沒有管理員權限時（學校電腦常見）：腳本內建的 winget install --id astral-sh.uv 可能被擋。先自己跑一次使用者範圍安裝，再重跑腳本：
winget install --id astral-sh.uv --exact --scope user --accept-source-agreements --accept-package-agreements
還是不行就用官方腳本備案：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
macOS / Linux / WSL（原 repo 沒有腳本，用這組等價手動步驟）
curl -LsSf https://astral.sh/uv/install.sh | sh
cd ai-agent-ep03
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements-core.txt
.venv/bin/python verify_core.py
install_windows.ps1 寫死 Python 3.12 且只認 3.12 的既有 .venv。手動這條同樣建議用 3.12（最穩），但 3.11～3.14 都可行。
A4. 驗證 A 段（不需要 B、C 段）
.\.venv\Scripts\python.exe verify_core.py
.venv/bin/python verify_core.py
verify_core.py 不只 import，還會真的產一份 docx／xlsx／pptx／pdf／png／QR／圖表，再用 MarkItDown 轉回文字比對。判讀方式：
| 結果 | 標準輸出 | Exit code |
|---|
| ✅ 成功 | CORE_OK: 10/10 imports and file smoke tests (Python 3.x.y) | 0 |
| ❌ 套件缺漏 | CORE_FAIL: n/10 ＋ 逐項錯誤 | 1 |
| ❌ 匯入過了但實際操作失敗 | CORE_SMOKE_FAIL: <錯誤類型>: <訊息> | 1 |
只有看到 CORE_OK: 10/10 且 exit code 為 0，才算安裝成功。
A5. 告訴 agent 用哪個 Python
裝完之後，所有 Python 程式都要用這個直譯器跑，不要用系統的 python：
- Windows：
.\.venv\Scripts\python.exe
- macOS / Linux / WSL：
.venv/bin/python
A 段標配 10 個（預設就裝這些）
已在 Windows + Python 3.14 實測全數安裝成功，verify_core.py 輸出 CORE_OK: 10/10。
| 套件 | 用途 |
|---|
python-docx | 生成／讀寫 Word |
openpyxl | 讀寫與格式化 Excel |
python-pptx | 生成／改寫 PowerPoint |
pypdf | PDF 合併、拆分、浮水印 |
PyMuPDF | PDF 抽文字、抽頁、轉圖片 |
reportlab | 生成 PDF 與浮水印圖層 |
Pillow | 圖片裁切、去白邊、合成 |
matplotlib | 產生統計圖表 |
qrcode[pil] | 產生 QR Code |
markitdown[pdf,docx,pptx,xlsx] | PDF／Word／PPT／Excel 轉 Markdown |
markitdown 一定要帶 extras。 只裝裸的 markitdown 不會啟用各文件格式，pdf,docx,pptx,xlsx 四組才符合示範用途。
PyMuPDF 的 import 名稱： 1.28.0 起官方新名稱是 import pymupdf，但舊寫法 import fitz 仍然可用，兩者皆可，不必改既有程式碼。
版本下限：Python 3.11（不是只有 3.12 能跑）
原文件只提 3.12，但依相依關係實際推算：標配裡卡最緊的是 matplotlib 3.11.1（requires_python >=3.11），其次 PyMuPDF／Pillow／markitdown 要 ≥3.10。所以：
| Python | 結果 |
|---|
| 3.10 以下 | ❌ 解析失敗（uv 會直接報 matplotlib 不支援） |
| 3.11 | ✅ 可裝（實質下限） |
| 3.12 | ✅ 安裝腳本預設值，最穩 |
| 3.13 / 3.14 | ✅ 可裝，3.14 已實測 CORE_OK: 10/10 |
🟡 A 段選配（預設不要裝）
| 套件 | 為什麼不是標配 |
|---|
pandas | 已由 markitdown[xlsx] extras 自動帶入，不需另裝。 要做大量資料分析時本來就已經在了。 |
pdfplumber | 已由 markitdown[pdf] extras 自動帶入，不需另裝。 精準擷取 PDF 表格時直接用即可。 |
xlsxwriter | 已由 python-pptx 相依自動帶入，不需另裝。 |
docxcompose | 只有「合併多份 Word」才需要。 |
pdf2image | 需另裝 Poppler；PDF 轉圖用 PyMuPDF 就夠。 |
fpdf2 | 與標配的 reportlab 功能重疊。 |
ocrmypdf | 需 Tesseract（＋Windows 可能還要 Ghostscript），不適合研習現場全自動安裝。 |
docx2pdf | 只支援 Windows／macOS，且本機必須有 Microsoft Word。 |
pywin32 | 只有 Windows Office COM 自動化才需要。 |
edge-tts | 已升級為標配 C，見下方「標配 C：語音」。不要在這裡裝。 |
yt-dlp | 已升級為標配 B，見下方「標配 B：影音工具」。B 段用 winget／brew 裝系統版，不要用 pip 裝進 .venv。 |
youtube-transcript-api | 只有抓 YouTube 既有字幕時需要；無字幕影片無法處理。標配 B 的 yt-dlp 已能抓字幕，通常不必再裝這個。 |
前三項（pandas、pdfplumber、xlsxwriter）裝完標配後就已經在 .venv 裡了，這是相依關係自動帶進來的，不是誰裝錯。不要為了「清乾淨」去 uninstall，會把 markitdown 或 python-pptx 弄壞。
其餘項目使用者日後明確點名任務時，再由 agent 裝進同一個 .venv。不要一次把整張表裝完。
⚙️ A 段用不到的其他系統工具（不是 pip 套件，預設不要裝）
| 系統工具 | 何時才需要 | 限制 |
|---|
| Tesseract OCR | 掃描 PDF／圖片 OCR | 繁體中文還要 chi_tra 語言資料 |
| Ghostscript | OCRmyPDF 部分 PDF/A 流程 | Windows 安裝可能需管理員 |
| Poppler | 使用 pdf2image | 標配已用 PyMuPDF 轉圖，可不裝 |
ffmpeg | 影音下載、轉檔、合併 | 已升級為標配 B，見下方「標配 B：影音工具」 |
| Microsoft Office | docx2pdf、pywin32 COM | 沒有 Word／PowerPoint 就不能用 |
不要因為讀到這張表就去跑 winget install（唯一例外是已升級為標配 B 的 ffmpeg，照 B 段步驟裝）。
🎬 標配 B：影音工具（yt-dlp／FFmpeg／deno）
⏭️ 今天不會用到，第二、三天的影片剪輯與逐字稿會用到。
現場時間不夠可以整段跳過，回家再補；跳過完全不影響 A 段與 C 段。
這一段裝的是系統工具（不是 Python 套件），不進 .venv，跟 A 段的環境無關。
B 段裝什麼、為什麼
| 工具 | 用途 | 為什麼要 |
|---|
| yt-dlp | 下載影音平台的影片、音訊、字幕 | 抓公開影片當教材、抓字幕當逐字稿 |
| FFmpeg | 影音格式轉換、把音訊和影片合併 | yt-dlp 下載高畫質時，影音是分開的兩軌，要靠 FFmpeg 合起來 |
| deno | JavaScript 執行環境 | yt-dlp 解析 YouTube 新格式時需要，隨 yt-dlp 自動安裝，不必自己裝 |
⚠️ FFmpeg 有兩套，不要重複裝
這是最容易多花 20 分鐘的地方：
| 版本 | 從哪來 | 要不要自己裝 |
|---|
yt-dlp 專用版（yt-dlp.FFmpeg） | 裝 yt-dlp 時自動帶入 | ❌ 不用，裝 yt-dlp 就有了 |
系統版（Gyan.FFmpeg） | winget install Gyan.FFmpeg | 🟡 只有你想在別的地方直接用 ffmpeg 指令（剪片、轉檔）才裝 |
兩者可以並存，不會互相打架。 但如果你只是要下載影片和字幕，裝完 yt-dlp 就夠了，不需要再裝系統版。
B 段步驟
B1. 安裝 yt-dlp（會自動帶 FFmpeg 與 deno）
Windows
winget install --id yt-dlp.yt-dlp -e --accept-source-agreements --accept-package-agreements
🔒 沒有管理員權限時（學校電腦常見）：
winget install --id yt-dlp.yt-dlp -e --scope user --accept-source-agreements --accept-package-agreements
兩個都失敗就用 Python 版備案（不需要管理員）：uv tool install yt-dlp
macOS
brew install yt-dlp
Linux（Debian / Ubuntu）
sudo apt update && sudo apt install -y ffmpeg
uv tool install yt-dlp
🍎🐧 macOS / Linux 的 deno 不會自動裝。 「裝 yt-dlp 順便帶 deno」是 Windows winget 的行為。mac／Linux 要等實際下載遇到「需要 JS 執行環境」的錯誤時再補：
brew install deno（macOS）／curl -fsSL https://deno.land/install.sh | sh（Linux）
B2. （選用）安裝系統版 FFmpeg
只有你要直接用 ffmpeg 指令剪片、轉檔才需要。單純下載影片／字幕請跳過這步。
Windows
winget install --id Gyan.FFmpeg -e --accept-source-agreements --accept-package-agreements
🔒 沒有管理員權限：winget install --id Gyan.FFmpeg -e --scope user --accept-source-agreements --accept-package-agreements
macOS：brew install ffmpeg
Linux：sudo apt install -y ffmpeg
B3. 🚨 重開終端機（這一步跳過就會誤以為裝失敗）
裝完之後，已經開著的終端機讀不到新的 PATH，打 yt-dlp 一定說「找不到」——不是沒裝好，是視窗太舊。
做法：關掉目前的 PowerShell／終端機，開一個新的。
不想關視窗的話，Windows 可以就地刷新 PATH：
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
macOS / Linux：source ~/.zshrc（或 source ~/.bashrc）。
B4. 驗證 B 段（不需要 A、C 段）
Windows（PowerShell 用 ; 不要用 &&）
yt-dlp --version; ffmpeg -version; deno --version
macOS / Linux
yt-dlp --version; ffmpeg -version; deno --version
這裡刻意用 ; 不用 &&：&& 會在第一個缺的工具就中斷，你會看不到後面兩個到底有沒有裝好。
| 結果 | 長相 |
|---|
| ✅ 成功 | yt-dlp 印出日期型版本（如 2026.xx.xx）、ffmpeg 印出 ffmpeg version … |
| ❌ 失敗 | 出現「無法辨識」／command not found → 九成是沒重開終端機，回 B3 |
deno 沒有也不算失敗——它是 yt-dlp 遇到 YouTube 新格式時才用到的相依工具。只要 yt-dlp --version 有輸出，B 段就算通過；deno 缺了等實際下載失敗再補。
yt-dlp 常用指令備忘（第二、三天會回來查這張表）
| 想做的事 | 指令 |
|---|
| 先看這支影片有沒有字幕 | yt-dlp --list-subs <網址> |
| 下載中文字幕轉成 SRT | yt-dlp --skip-download --write-subs --sub-langs "zh-Hant,zh-TW,zh" --convert-subs srt <網址> |
| 人工字幕＋自動字幕一起抓 | yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs "zh-Hant,zh-TW,zh,en" --convert-subs srt <網址> |
| 只下載音訊成 mp3（餵 NotebookLM 用） | yt-dlp -x --audio-format mp3 <網址> |
| 下載整段影片（最高畫質） | yt-dlp -f "bv*+ba/b" <網址> |
| 自我更新（YouTube 一改格式就跑這個） | yt-dlp -U |
📌 不是每支影片都有字幕。 很多官方宣導頻道既沒上字幕、也沒開自動字幕，下載前先用 --list-subs 確認。真的沒有字幕，就要走「下載 mp3 → 語音轉文字」那條路（09-groq-api）。
⚠️ B 段兩個一定要知道的坑
坑 1：--print 會偷偷變成「只模擬、不下載」
--print 這個參數會隱含 simulate 模式。也就是說，你以為自己下的是「印出標題並且下載字幕」：
yt-dlp --print "%(title)s" --write-subs --sub-langs "zh-Hant" <網址>
實際上 yt-dlp 只會印字幕、一個檔案都不會存。要邊印邊下載，必須同時加 --no-simulate：
yt-dlp --print "%(title)s" --no-simulate --write-subs --sub-langs "zh-Hant" <網址>
🩹 這個坑實測踩過：一次批次處理 76 部影片，因為少了 --no-simulate，76 部全部誤報「沒有字幕」——其實字幕都在，只是根本沒下載。看到「整批都沒字幕」這種太整齊的結果，先回頭檢查有沒有 --print。
坑 2：重開終端機 PATH 才生效
見 B3。這是新裝完當下最常見的假失敗，指令沒錯、東西也裝好了，只是視窗太舊。
🔊 標配 C：語音（Edge-TTS）
✅ 今天就會用到，而且裝完 30 秒內就聽得到聲音。
這一段跟 A、B 段完全無關，A 段沒裝完也可以先裝這段。
Edge-TTS 是走 Edge 瀏覽器「大聲朗讀」背後的微軟雲端語音：不用申請金鑰、不用付費、聲音很自然。裝好之後 agent 就能把結論唸給你聽。
C 段步驟
C1. 安裝 edge-tts
所有平台通用（用 00-env-setup 裝好的 uv，不需要先做完 A 段）
uv tool install edge-tts
uv tool install 會把 edge-tts 裝進一個獨立的隔離環境並加到 PATH，不會污染系統 Python，也不會動到 A 段的 .venv。
💡 不想安裝、只想試一次：把下面所有指令的 edge-tts 換成 uvx edge-tts，uv 會臨時抓下來跑完就算，不留在電腦上。
🔒 沒有 uv（例如跳過了 00-env-setup）：pip install --user edge-tts 也可以，但仍不要用系統管理員權限做全域 pip install。
⚠️ 裝好了但打 edge-tts 說找不到指令？ 先重開終端機（跟 B3 同一個原因）。重開還是不行，代表模組裝好了、但那支 Python 的 Scripts 資料夾不在 PATH 上——把所有指令的 edge-tts 換成 python -m edge_tts，參數完全一樣（注意模組名是底線 edge_tts，指令名是連字號 edge-tts）。實測這條備案可正常出聲。
C2. 🎉 一行聽到聲音（研習現場的 wow 時刻）
Windows（PowerShell，整段複製貼上，一行就好）
edge-tts --voice zh-TW-YunJheNeural --text "老師好，我是你的 AI 助理，從現在開始我會說話了。" --write-media "$env:TEMP\hello.mp3"; Add-Type -AssemblyName PresentationCore; $p = New-Object System.Windows.Media.MediaPlayer; $p.Open([Uri]"$env:TEMP\hello.mp3"); Start-Sleep -Seconds 1; $p.Play(); Start-Sleep -Seconds 8; $p.Close()
macOS
edge-tts --voice zh-TW-YunJheNeural --text "老師好，我是你的 AI 助理，從現在開始我會說話了。" --write-media /tmp/hello.mp3 && afplay /tmp/hello.mp3
Linux
edge-tts --voice zh-TW-YunJheNeural --text "老師好，我是你的 AI 助理，從現在開始我會說話了。" --write-media /tmp/hello.mp3 && (mpv --no-video /tmp/hello.mp3 || ffplay -nodisp -autoexit -loglevel quiet /tmp/hello.mp3)
聽到聲音就成功了。 這就是 C 段的驗證——耳朵就是驗證工具。
C3. 驗證 C 段（機器判讀用）
耳朵聽到聲音是給人的驗證；agent 要判讀請看音檔有沒有真的生出來：
Windows
Test-Path "$env:TEMP\hello.mp3"; (Get-Item "$env:TEMP\hello.mp3").Length
macOS / Linux
test -f /tmp/hello.mp3 && wc -c < /tmp/hello.mp3
| 結果 | 判讀 |
|---|
| ✅ 成功 | 檔案存在且大小 > 10000 bytes（約 1 秒以上的語音） |
| ❌ 失敗 | 檔案不存在，或大小為 0（多半是沒網路，或 --text 是空的） |
檔案有生出來但聽不到聲音 → 不是 edge-tts 的問題，是播放的問題（音量、輸出裝置、耳機沒插）。先把音量開起來，再用檔案總管點兩下那個 mp3 確認。
🧹 重跑驗證前先把舊的 hello.mp3 刪掉，否則這次明明失敗，卻讀到上次留下的檔案而誤判成功。
Windows：Remove-Item "$env:TEMP\hello.mp3" -Force -ErrorAction SilentlyContinue／mac、Linux：rm -f /tmp/hello.mp3
建議聲音（台灣中文）
| 聲音代號 | 性別 | 感覺 |
|---|
zh-TW-YunJheNeural | 男 | 沉穩，適合唸結論、旁白（預設建議） |
zh-TW-HsiaoChenNeural | 女 | 親切，適合教學提示、學生端說明 |
zh-TW-HsiaoYuNeural | 女 | 另一個台灣女聲，想換換口味時用 |
以上三個是實測 edge-tts --list-voices 確認存在的全部台灣中文聲音。其他 zh-CN-* 開頭的是大陸口音，唸給台灣學生聽會怪，不建議用。
換聲音只要改 --voice 後面那串。想看全部可用聲音：
edge-tts --list-voices
🪟 播放不要開外部播放器視窗
研習現場（和日常使用）最惱人的就是每唸一句就彈出一個播放器視窗。做法上要避開 Start-Process／start／open 這類「交給系統預設程式開檔」的指令，改用行內播放：
| 平台 | 行內播放做法 | 會不會跳視窗 |
|---|
| Windows | PowerShell System.Windows.Media.MediaPlayer（就是 C2 那行用的） | ❌ 不會 |
| Windows（進階） | ffplay -nodisp -autoexit（需要 B 段的 FFmpeg） | ❌ 不會 |
| macOS | afplay | ❌ 不會 |
| Linux | mpv --no-video 或 ffplay -nodisp -autoexit | ❌ 不會 |
| 任何平台 | Start-Process ／ start ／ open | ✅ 會，不要用 |
想要完整的「用語音回答」技能？
本包只負責裝起來、確認出得了聲。真正好用的語音回覆技能（串流播放、首聲約 1–2 秒、離線備援、-Voice／-Out 參數）已經是一套獨立技能，不要在這裡重寫，直接裝那份：
https://github.com/mathruffian-dot/agent-speak-skill
把該 repo 的 speak/ 資料夾複製到 OpenCode 的技能目錄 ~/.config/opencode/skills/speak/，之後對 agent 說「用語音回答我」「唸給我聽」就會觸發。
那份技能同時支援 Claude Code／Codex／OpenCode／AntiGravity，技能目錄各自不同，詳見該 repo 的 README。
怎麼讓 agent「記得」這些規則
⚠️ 這一節的「做法一／二／三」是三種讓 agent 記住規則的方式，跟上面的標配 A／B／C 三段沒有關係，不要看混了。
ai-agent-ep03 裡那份 AGENT_SETUP_教學檔案處理工具包.md 的檔名，不是任何 agent 會自動載入的慣例檔名。它不會自己生效，你得主動遞交。三種做法擇一：
做法一：一次性遞交（最簡單）
把該檔案拖進對話，或說：
「讀 ai-agent-ep03/AGENT_SETUP_教學檔案處理工具包.md，只安裝核心工具，選用工具先不要裝。」
做法二：讓它在該專案常駐（推薦）
在 ai-agent-ep03/ 根目錄建立 AGENTS.md（OpenCode 的專案指令檔，會自動載入），寫進去：
# 本專案 Python 環境
- 一律使用本資料夾的 `.venv`，禁止全域 pip install。
- Windows 直譯器：`.\.venv\Scripts\python.exe`
- macOS/Linux：`.venv/bin/python`
- 只裝 requirements-core.txt 的標配 10 項；A 段選配套件要使用者明確點名才裝。
- 安裝或修環境後，一律跑 `verify_core.py`，看到 `CORE_OK: 10/10` 才算完成。
# 影音與語音工具（不在 .venv 裡）
- yt-dlp / ffmpeg / deno 是系統工具，用 winget / brew 裝，不要用 pip 裝進 .venv。
- yt-dlp 加 `--print` 時必須同時加 `--no-simulate`，否則不會真的下載。
- edge-tts 用 `uv tool install edge-tts` 裝在獨立環境；播放一律行內播放，禁止 Start-Process 開播放器視窗。
做法三：讓它全域常駐
把本份 SKILL.md 裝成全域技能，之後在任何專案說「裝內部工具包」都會載入：
npx skills add mathruffian-dot/opencode-lazy-packs --skill 02-file-toolkit -g -y
常見卡關
A 段（文件處理）
| 症狀 | 原因 | 解法 |
|---|
腳本說找不到 uv 的新 PATH | 終端機還是舊的環境變數 | 重開 OpenCode 再跑一次（不要自己改 PATH） |
腳本說既有 .venv 不是 3.12 | 資料夾裡有別的舊環境 | 把舊 .venv 改名，再重跑；不要讓 agent 自動刪掉 |
import fitz 找不到 | 沒裝 PyMuPDF，或用錯直譯器 | 確認是用 .venv 那支 python，不是系統 python |
| 裝在 WSL 但 Windows 用不到 | 兩邊 Python 環境彼此獨立 | WSL 另建一份 .venv，不能共用 |
CORE_SMOKE_FAIL | 套件裝到了但實際操作壞掉 | 貼出完整錯誤訊息，不要用「把選配全裝一遍」來硬補 |
B 段（影音工具）
| 症狀 | 原因 | 解法 |
|---|
裝完打 yt-dlp 說「無法辨識」 | 終端機太舊，讀不到新 PATH | 九成是這個：重開終端機（B3），或跑 B3 那段刷新 PATH |
| winget 說需要系統管理員權限 | 學校電腦沒有管理員 | 加 --scope user 重跑；再不行用 uv tool install yt-dlp |
| 整批影片都「沒有字幕」 | 指令裡有 --print，被隱含 simulate | 加上 --no-simulate（見 B 段坑 1） |
| 下載到的影片沒有聲音／畫質很低 | 高畫質影音分軌，缺 FFmpeg 合不起來 | 確認 ffmpeg -version 有輸出；沒有就回 B1／B2 |
| 昨天還能下載，今天突然壞了 | YouTube 改格式了 | 跑 yt-dlp -U 自我更新，再試一次 |
| 我已經裝過 FFmpeg 了，還要再裝嗎 | 兩套 FFmpeg 的混淆 | 不用。yt-dlp 自帶一套，系統版只有要直接剪片才裝（見 B 段說明） |
C 段（語音）
| 症狀 | 原因 | 解法 |
|---|
打 edge-tts 說「無法辨識」 | 重開終端機後仍不行 = 模組裝好了但 Scripts 不在 PATH | 改用 python -m edge_tts，參數一模一樣（實測可用） |
| 沒有產生 mp3 檔 | 沒網路，或 --text 是空的 | Edge-TTS 走雲端，一定要連得上網 |
| mp3 有生出來但聽不到 | 播放問題，不是 TTS 問題 | 開音量、確認輸出裝置、用檔案總管點兩下那個 mp3 試聽 |
| 每唸一句就跳出播放器視窗 | 用了 Start-Process／start／open | 改用行內播放（見「播放不要開外部播放器視窗」） |
| 唸中文變成怪腔怪調 | --voice 用到英文或大陸口音聲音 | 換成 zh-TW-YunJheNeural 或 zh-TW-HsiaoChenNeural |
| 用一陣子後突然連不上 | Edge-TTS 是非官方管道，微軟偶爾調整介面 | uv tool upgrade edge-tts（或 uvx edge-tts@latest）再試 |
「一個 agent 裝一次，其他 agent 都能用」只在同一個作業系統、同一份資料夾、同一個 .venv 時才成立。Windows、WSL、Docker、雲端、沙盒之間不能共用 Python 套件。
B 段的系統工具（yt-dlp／ffmpeg／deno）則是裝在作業系統層，同一台電腦的所有 agent 都叫得動——但 WSL 與 Windows 仍然算兩台。
🤖 機器可判讀的成功訊號（三段分別回報）
執行完請完整輸出下面這個區塊，讓後續的 agent（或「一次全裝」那一包）可以直接判讀，不必讀懂中文說明。
三段各自獨立判定：某一段 FAIL 不會讓其他兩段變成 FAIL。
=== OPENCODE_INTERNAL_TOOLKIT ===
result=PARTIAL # PASS | PARTIAL | FAIL（整體，見下方判定規則）
os=windows # windows | macos | linux
# --- 標配 A：文件處理 ---
section_a=PASS # PASS | FAIL | SKIPPED
a_python=3.12.8 # 版本號 | missing
a_venv=D:\ai-agent-ep03\.venv # 路徑 | missing
a_core=CORE_OK 10/10 # verify_core.py 的原始輸出 | CORE_FAIL n/10 | CORE_SMOKE_FAIL
# --- 標配 B：影音工具 ---
section_b=SKIPPED # PASS | FAIL | SKIPPED（現場時間不夠可正當跳過）
b_ytdlp=2026.07.21 # 版本號 | missing
b_ffmpeg=bundled # bundled（yt-dlp 自帶）| system（Gyan.FFmpeg）| both | missing
b_deno=2.5.4 # 版本號 | missing（不影響 section_b 判定）
# --- 標配 C：語音 ---
section_c=PASS # PASS | FAIL | SKIPPED
c_edge_tts=installed # installed | uvx（未安裝，臨時執行）| missing
c_audio_bytes=41328 # 驗證音檔位元組數 | 0
c_heard=yes # yes | no | unknown（使用者有沒有回報聽到聲音）
next=03-notebooklm
=== END ===
判定規則（agent 請照這個判斷，不要自行認定）：
| 段 | PASS 的條件 |
|---|
| A | verify_core.py 輸出 CORE_OK: 10/10 且 exit code 為 0 |
| B | yt-dlp --version 有版本號（deno 缺不算失敗；系統版 FFmpeg 沒裝也不算失敗） |
| C | 驗證音檔存在且 c_audio_bytes > 10000 |
整體 result | 條件 |
|---|
PASS | A、B、C 三段都是 PASS |
PARTIAL | 至少一段 PASS，其餘為 SKIPPED 或 FAIL（研習當天只裝 A＋C、B 標 SKIPPED 屬正常，不是出錯） |
FAIL | 三段都不是 PASS |
完成回報格式（給人看的）
內部工具包 三合一 安裝完成回報：
【A 文件處理】
✅ uv：已存在／已安裝
✅ Python：3.x.x（下限 3.11）
✅ 環境：<資料夾>/.venv
✅ 標配套件：CORE_OK: 10/10（exit code 0）
ℹ️ pandas / pdfplumber / xlsxwriter：已由標配相依自動帶入（正常，不需處理）
🟡 A 段其餘選配：未安裝（正確）
【B 影音工具】
✅ yt-dlp：<版本>
✅ FFmpeg：yt-dlp 自帶版（系統版未裝，正確——要直接剪片時再裝）
✅ deno：<版本>／未裝（不影響下載）
（時間不夠跳過的話寫：⏭️ B 段本次跳過，課後再補，不影響 A、C）
【C 語音】
✅ edge-tts：已安裝
✅ 驗證音檔：<路徑>（<位元組數> bytes）
🔊 已聽到聲音：是／否
ℹ️ 要完整語音回覆技能 → github.com/mathruffian-dot/agent-speak-skill
下一步：所有 Python 程式請用 <venv 的 python 路徑> 執行
失敗時只列出失敗步驟與原始錯誤摘要，不要自動安裝選用工具當補救，也不要因為某一段失敗就把其他兩段一起標成失敗。
已知修正（A 段：相對於 ai-agent-ep03 原始文件）
本包修正了三處實測發現的問題，原 repo 若尚未更新，以本文件為準：
-
「選配未安裝」的說法與現實不符。
原文件把 pandas、pdfplumber、xlsxwriter 列在「選配、預設不要裝」，回報範本還要 agent 印「🟡 選用套件：未安裝（正確）」——但實際跑完標配安裝後，這三個都已經在 .venv 裡，那句話是假的。
實際來源（uv pip compile 解析驗證）：pandas ← markitdown[xlsx]、pdfplumber ← markitdown[pdf]、xlsxwriter ← python-pptx（注意：xlsxwriter 是標配的 python-pptx 帶的，不是 markitdown extras）。
本包已在選配表逐項加註來源，並把回報範本那句改成「已由標配相依自動帶入（正常）」。
-
matplotlib 版本落後。 原 requirements-core.txt 釘 3.11.0，PyPI 最新為 3.11.1。本包 A 段步驟 A2 要求安裝前先改掉。
-
Python 版本下限沒寫。 原文件只提 3.12，讀者會誤以為非 3.12 不可。依相依關係推算實質下限是 3.11（matplotlib 3.11.1 要求 >=3.11；3.10 會直接解析失敗）。本包補上完整版本對照表。
另補兩個原工具包的缺口：
-
只有 Windows 安裝腳本。 跑 WSL／macOS／Linux 的人會斷在這裡。本包補上 uv 建 venv ＋ 裝 requirements 的等價手動步驟。
-
AGENT_SETUP_教學檔案處理工具包.md 不是 agent 自動載入的慣例檔名。 本包補上「怎麼讓 agent 記得」三種做法（一次性遞交／專案 AGENTS.md 常駐／全域技能）。
本次三合一擴充做了什麼（給維護者）
原本這一包只有 A 段（Python 套件），影音與語音的資料散在三個地方，老師要裝齊得自己拼。本次把三處合併：
| 段 | 原本在哪 | 合併時的處理 |
|---|
| A | 本檔既有內容 | 原樣保留，只加 A1～A5 編號與 --scope user 備案 |
| B | 私人筆記「agents 必需工具」（從未公開） | 整理成安裝步驟＋指令備忘表；保留兩個實測踩坑（--print 隱含 simulate、重開終端機刷 PATH） |
| C | agent-speak-skill / claude-speak-skill 兩個 repo | 只搬「安裝＋最小可用驗證」，完整語音回覆技能仍指向 agent-speak-skill，不在本包重寫 |
合併時解掉的三處衝突（原文件互相矛盾之處）：
- A 段選配表原本寫「
edge-tts、yt-dlp 預設不要裝」，與新增的 B、C 段直接打架 → 兩列改標「已升級為標配 B／C」，並在七條規則第 2 條加註記。
- A 段系統工具表原本寫「ffmpeg：文件處理不需要」＋「不要因為讀到這張表就去跑
winget install」 → ffmpeg 那列改指向 B 段，禁令加上唯一例外。
- 「怎麼讓 agent 記得」原本用 A／B／C 當三種做法的編號，與標配 A／B／C 撞名 → 改成「做法一／二／三」。
刻意沒做的事： 不在本包寫死任何價格與版本號（A 段既有的 requirements-core.txt 釘選除外，那是刻意釘的）；B、C 段的工具都會持續更新，寫死只會讓文件過期。
