mathruffian-dot/opencode-lazy-packs/02-file-toolkit

內部工具包 三合一（文件／影音／語音）

研習六「作品階梯」的內部工具級：不是給學生用的網頁作品，而是讓 agent 長出手腳的一組工具。裝好之後，你對 OpenCode 說一句人話，它就能真的幫你產出獎狀、成績表、簡報、PDF、QR Code，也能下載影片抽字幕，還能開口把結論唸給你聽。

這一包裝三類工具，各自解決什麼

🔀 三段彼此獨立，任一段失敗不影響其他兩段。

每段都有自己的驗證步驟與成功訊號。研習現場如果進度落後，先裝 A 和 C（今天要用），B 留課後自己補——B 沒裝完全不影響 A、C 能不能用。

這一份是懶人包入口。A 段實際的安裝腳本與驗證程式放在另一個 repo：

https://github.com/mathruffian-dot/ai-agent-ep03（預設分支是 master，不是 main）

本文件只負責：這是什麼、怎麼裝、怎麼驗、卡住怎麼辦。細部腳本以那個 repo 為準。

這包能幹嘛（裝完就能對 agent 說的話）

A 段（文件）

B 段（影音）

C 段（語音）

先備條件

共同

• [ ] 網路連線（三段都需要：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，這是本次擴充的刻意變更，不是誤裝。舊版文件把這兩個列在「預設不要裝」，以本文件為準。

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

```powershell

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 轉回文字比對。判讀方式：

只有看到 `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。

`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。所以：

🟡 A 段選配（預設不要裝）

前三項（pandas、pdfplumber、xlsxwriter）裝完標配後就已經在 `.venv` 裡了，這是相依關係自動帶進來的，不是誰裝錯。不要為了「清乾淨」去 uninstall，會把 markitdown 或 python-pptx 弄壞。

其餘項目使用者日後明確點名任務時，再由 agent 裝進同一個 .venv。不要一次把整張表裝完。

⚙️ A 段用不到的其他系統工具（不是 pip 套件，預設不要裝）

不要因為讀到這張表就去跑 `winget install`（唯一例外是已升級為標配 B 的 ffmpeg，照 B 段步驟裝）。

🎬 標配 B：影音工具（yt-dlp／FFmpeg／deno）

⏭️ 今天不會用到，第二、三天的影片剪輯與逐字稿會用到。

現場時間不夠可以整段跳過，回家再補；跳過完全不影響 A 段與 C 段。

這一段裝的是系統工具（不是 Python 套件），不進 .venv，跟 A 段的環境無關。

B 段裝什麼、為什麼

⚠️ FFmpeg 有兩套，不要重複裝

這是最容易多花 20 分鐘的地方：

兩者可以並存，不會互相打架。 但如果你只是要下載影片和字幕，裝完 yt-dlp 就夠了，不需要再裝系統版。

B 段步驟

B1. 安裝 yt-dlp（會自動帶 FFmpeg 與 deno）

Windows

winget install --id yt-dlp.yt-dlp -e --accept-source-agreements --accept-package-agreements

🔒 沒有管理員權限時（學校電腦常見）：

```powershell

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

這裡刻意用 ; 不用 &&：&& 會在第一個缺的工具就中斷，你會看不到後面兩個到底有沒有裝好。

deno 沒有也不算失敗——它是 yt-dlp 遇到 YouTube 新格式時才用到的相依工具。只要 `yt-dlp --version` 有輸出，B 段就算通過；deno 缺了等實際下載失敗再補。

yt-dlp 常用指令備忘（第二、三天會回來查這張表）

📌 不是每支影片都有字幕。 很多官方宣導頻道既沒上字幕、也沒開自動字幕，下載前先用 `--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。