opencode-file-toolkit

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 抓套件、B 抓影片、C 走微軟雲端語音）

A 段／C 段

• uv 已安裝（沒有的話先跑 00-env-setup）
• Python ≥ 3.11（見下方版本下限說明）

B 段

• Windows：winget 可用（winget --version 有輸出）
• macOS：brew 可用／Linux：apt 或官方安裝腳本

---

⛔ 給 Agent 的七條規則（安裝前先讀，這幾條是防呆用的）

使用者說「裝內部工具包」「裝教學檔案處理工具包」時，逐條遵守：

1. 只在專案資料夾內工作 — A 段以 ai-agent-ep03 資料夾為根，不要去掃其他磁碟或其他 agent 的目錄。
2. 只裝三段標配（A 的 10 個套件、B 的三個系統工具、C 的 edge-tts） — 下方 A 段「選配」與「其他系統工具」一律不裝，除非使用者明確點名用途。

   📌 v2 起 edge-tts 與 yt-dlp 已從「選配」升級為標配 B／C，這是本次擴充的刻意變更，不是誤裝。舊版文件把這兩個列在「預設不要裝」，以本文件為準。

3. 禁止全域 pip install — A 段一律裝進該資料夾的 .venv，C 段用 uv tool install（獨立隔離環境），都不要污染使用者原有的 Python。
4. 禁止逐項上網研究 — 版本解析交給 uv，不要為每個套件開網頁、寫長篇計畫或重複說明。
5. 最多重試一次 — 失敗就回報原始錯誤訊息與建議，不要反覆改指令、重裝、或自行提權。
6. 不自動切換執行環境 — Windows、WSL、Docker、沙盒是不同環境，不要為了裝成功就自己跳去 WSL 或換 agent。
7. 三段各自獨立、各自回報 — 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 沒有腳本，用這組等價手動步驟）

# 沒有 uv 才需要這行
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 段）

# Windows
.\.venv\Scripts\python.exe verify_core.py
# macOS / Linux / WSL
.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）

# 發行版內建的 yt-dlp 常常太舊，YouTube 一改格式就壞掉，建議用這條
sudo apt update && sudo apt install -y ffmpeg
uv tool install yt-dlp          # uv 來自 00-env-setup；真的沒有 uv 才退而求其次用 sudo apt install -y 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 若尚未更新，以本文件為準：

1. 「選配未安裝」的說法與現實不符。 原文件把 pandas、pdfplumber、xlsxwriter 列在「選配、預設不要裝」，回報範本還要 agent 印「🟡 選用套件：未安裝（正確）」——但實際跑完標配安裝後，這三個都已經在 .venv 裡，那句話是假的。 實際來源（uv pip compile 解析驗證）：pandas ← markitdown[xlsx]、pdfplumber ← markitdown[pdf]、xlsxwriter ← python-pptx（注意：xlsxwriter 是標配的 python-pptx 帶的，不是 markitdown extras）。 本包已在選配表逐項加註來源，並把回報範本那句改成「已由標配相依自動帶入（正常）」。

2. matplotlib 版本落後。 原 requirements-core.txt 釘 3.11.0，PyPI 最新為 3.11.1。本包 A 段步驟 A2 要求安裝前先改掉。

3. Python 版本下限沒寫。 原文件只提 3.12，讀者會誤以為非 3.12 不可。依相依關係推算實質下限是 3.11（matplotlib 3.11.1 要求 >=3.11；3.10 會直接解析失敗）。本包補上完整版本對照表。

另補兩個原工具包的缺口：

4. 只有 Windows 安裝腳本。 跑 WSL／macOS／Linux 的人會斷在這裡。本包補上 uv 建 venv ＋ 裝 requirements 的等價手動步驟。

5. 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，不在本包重寫

合併時解掉的三處衝突（原文件互相矛盾之處）：

1. A 段選配表原本寫「edge-tts、yt-dlp 預設不要裝」，與新增的 B、C 段直接打架 → 兩列改標「已升級為標配 B／C」，並在七條規則第 2 條加註記。
2. A 段系統工具表原本寫「ffmpeg：文件處理不需要」＋「不要因為讀到這張表就去跑 winget install」 → ffmpeg 那列改指向 B 段，禁令加上唯一例外。
3. 「怎麼讓 agent 記得」原本用 A／B／C 當三種做法的編號，與標配 A／B／C 撞名 → 改成「做法一／二／三」。

刻意沒做的事： 不在本包寫死任何價格與版本號（A 段既有的 requirements-core.txt 釘選除外，那是刻意釘的）；B、C 段的工具都會持續更新，寫死只會讓文件過期。