SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsopencode-file-toolkit

opencode-file-toolkit

Coding & development

View repository

Updated 10-15 23:39

About this skill

Internal Toolkit All-in-One (Documents/Audio & Video/Voice)

Workshop 6 "Work Ladder"'sinternal toolslevel: not a web project for students, butgiving the agent hands and feeta set of tools. Once installed, you say one plain sentence to OpenCode, and it can actually help you produce certificates, grade sheets, slides, PDFs, QR Codes, and also download videos and extract subtitles, and evenspeak the conclusions out loud to you。

This package installs three types of tools; what each one solves

Section What to install What problem it solves Will it be used today
Standard A: Document Processing Python 10 packages (uv installed into the project .venv） Read PDFs to generate lesson plans, mail-merge certificates, calculate grades, make slides, generate QR Codes ✅ Will be used this afternoon
Standard B: Audio & Video Tools yt-dlp／FFmpeg／deno(system tools,winget／brew） Download videos, extract subtitles, convert to mp3 to feed AI ⏭️ Not used today; the video editing on the second and third days will
Standard C: Voice edge-tts(Python module, Microsoft cloud voice, no key required) Lets the agent speak the conclusions out loud in Taiwan Mandarin ✅ Used today; you can hear it within 30 seconds after installation

🔀 The three sections are independent of one another; if any one section fails, it does not affect the other two. Each section has its own verification steps and success signals. If the workshop is running behind schedule,install A and C first (needed today), and leave B to make up after class— not installing B does not affect whether A or C can be used at all.

This one is thelazy-pack entry point. The actual installation script and verification program for Section A are in another repo: **https://github.com/mathruffian-dot/ai-agent-ep03**（預設分支是 master, not main) This document is only responsible for: what this is, how to install it, how to verify it, and what to do if you get stuck. For detailed scripts, that repo is authoritative.

What this package can do (things you can say to the agent once installed)

Section A (Documents)

What you want to do Say directly after installation
Mail-merge certificates/notices "Read this name list Excel, merge it into this certificate Word template, and produce one copy per person"
Grade calculation + mark in red "Calculate total scores and rankings, mark failing ones in red, and put each class average in the last row"
Outline to slides "Turn this teaching material outline into one slide per key point"
PDF merge/extract pages/watermark "Merge these PDFs, save pages 5–8 separately, and add a light gray watermark to each page"
Links to QR Codes "Generate one QR Code for each of these 5 links"
Convert textbooks to clean text to feed AI "Convert this PDF to Markdown"

Section B (Audio & Video)

What you want to do Say directly after installation
Grab subtitles from public videos as transcripts "Help me grab the Chinese subtitles for this video and convert them to SRT"
Just feed the audio to AI for summarization "Download this video as mp3"
Download source footage for editing "Download this video in the highest quality"

Section C (Speech)

What you want to do Just say it after installation
Have the agent read the conclusion aloud "Read the conclusion just now back to me with speech"
Generate a narration audio file "Save this course explanation as mp3, I want to put it into a video"

Prerequisites

Common

  • Network connection (all three sections need it: A fetches packages, B fetches videos, C uses Microsoft cloud speech)

Section A / Section C

  • uv Already installed (if not, run 00-env-setup）
  • Python ≥ 3.11(see the minimum version notes below)

Section B

  • Windows：winget Available (winget --version has output)
  • macOS：brew Available / Linux:apt or the official installation script

⛔ Seven rules for the Agent (read before installing; these are for foolproofing)

When the user says "install the internal toolkit" or "install the teaching file processing toolkit",follow them one by one：

  1. Work only inside the project folder — Section A uses the ai-agent-ep03 folder as its root; do not scan other drives or other agents' directories.
  2. Install only the three standard sets (A's 10 packages, B's three system tools, C's edge-tts) — The "optional" and "other system tools" items under Section A below must not be installed unless the user explicitly names a use for them.

    📌 As of v2, edge-tts and yt-dlp have been upgraded from "optional" to standard B/C, this is a deliberate change in this expansion, not a mistaken install. Older documentation listed these two under "do not install by default"; this document takes precedence.

  3. No global pip install — Section A must always be installed into that folder's .venv, and Section C uses uv tool install(an isolated environment); do not pollute the user's existing Python.
  4. Do not research online item by item — Leave version resolution to uv; do not open web pages for each package, write lengthy plans, or repeat explanations.
  5. Retry at most once — If it fails, report the original error message and suggestions; do not repeatedly change commands, reinstall, or escalate privileges on your own.
  6. Do not automatically switch execution environments — Windows, WSL, Docker, and sandboxes are different environments; do not jump to WSL or switch agents on your own just to make the install succeed.
  7. The three sections are independent and report separately — If any of A/B/C fails,continue and finish the other two sections, and mark them by section in the success signal at the end; do not abort the whole thing, and do not use "installing another section" to compensate for the failed section.
🟢 Standard A: Document processing (10 Python packages)

✅ You'll use it this afternoon. Only after installation can the agent read PDFs to generate lesson plans, print certificates, and make slides. This section does not need anything from Sections B or C at all.

Section A steps

A1. Get the toolkit

git clone https://github.com/mathruffian-dot/ai-agent-ep03.git
cd ai-agent-ep03

⚠️ The default branch is master. Do not force-specify -b main, it will fail.

A2. Confirm the version pin is the latest

Open requirements-core.txtand confirm the contents are as follows (matplotlib should be 3.11.1; older versions of the file may still say 3.11.0, please change it):

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. Install

Windows (there is a ready-made script, take this route)

Inside the ai-agent-ep03 folder, run:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\install_windows.ps1"

The script will sequentially: find uv(if not present, install the official astral-sh.uvvia WinGet) → create .venv → install according to requirements-core.txt → run verify_core.py。

🔒 When there are no administrator privileges(common on school computers): the script's built-in winget install --id astral-sh.uv may be blocked. First run a user-scope installation yourself, then rerun the script:

winget install --id astral-sh.uv --exact --scope user --accept-source-agreements --accept-package-agreements

If it still does not work, use the official script as a fallback:powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux / WSL (the original repo has no script, use this equivalent set of manual steps)

# 沒有 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 hardcodes Python 3.12 and only recognizes the existing 3.12 .venv. For the manual route, it is likewise recommended to use 3.12 (most stable), but 3.11–3.14 all work.

A4. Verify section A (sections B and C are not required)

# Windows
.\.venv\Scripts\python.exe verify_core.py
# macOS / Linux / WSL
.venv/bin/python verify_core.py

verify_core.py not only imports, but actually produces a docx/xlsx/pptx/pdf/png/QR/chart, then uses MarkItDown to convert back to text for comparison. How to interpret:

Result Standard output Exit code
✅ Success CORE_OK: 10/10 imports and file smoke tests (Python 3.x.y) 0
❌ Missing packages CORE_FAIL: n/10 + item-by-item errors 1
❌ Import passed but actual operation failed CORE_SMOKE_FAIL: <錯誤類型>: <訊息> 1

Only when you see CORE_OK: 10/10 and the exit code is 0is the installation considered successful.

A5. Tell the agent which Python to use

After installation,all Python programs must be run with this interpreter, do not use the system's python：

  • Windows：.\.venv\Scripts\python.exe
  • macOS / Linux / WSL：.venv/bin/python

Section A standard set of 10 (these are installed by default)

Already tested in Windows + Python 3.14 and all installed successfully,verify_core.py output CORE_OK: 10/10。

Package Purpose
python-docx Generate/read and write Word
openpyxl Read, write, and format Excel
python-pptx Generate/rewrite PowerPoint
pypdf PDF merge, split, watermark
PyMuPDF PDF extract text, extract pages, convert to images
reportlab Generate PDFs and watermark layers
Pillow Image cropping, white-edge removal, compositing
matplotlib Generate statistical charts
qrcode[pil] Generate QR Code
markitdown[pdf,docx,pptx,xlsx] Convert PDF/Word/PPT/Excel to Markdown

markitdown must include extras. If you only install the bare markitdown it will not enable the various document formats,pdf,docx,pptx,xlsx only the four groups match the demonstration purposes.

PyMuPDF 's import name: Since 1.28.0 the official new name is import pymupdf, but the old usage import fitz is still available, either is fine, no need to change existing code.

Minimum version: Python 3.11 (not only 3.12 can run)

The original document only mentions 3.12, but based on actual dependency calculations: the tightest constraint in the standard set is matplotlib 3.11.1（requires_python >=3.11), followed by PyMuPDF／Pillow／markitdown requiring ≥3.10. So:

Python Result
3.10 and below ❌ Resolution failed (uv will directly report that matplotlib is unsupported)
3.11 ✅ Installable (effective lower bound)
3.12 ✅ Install script default, most stable
3.13 / 3.14 ✅ Installable, tested on 3.14 CORE_OK: 10/10

🟡 Section A optional (do not install by default)

Package Why it is not standard
pandas Already included by markitdown[xlsx] extras automatically, no separate install needed. When doing large-scale data analysis, it is already there anyway.
pdfplumber Already included by markitdown[pdf] extras automatically, no separate install needed. Use it directly when precisely extracting PDF tables.
xlsxwriter Already included by python-pptx dependency automatically, no separate install needed.
docxcompose Only needed when "merging multiple Word files".
pdf2image Requires separate Poppler install; for PDF to image, PyMuPDF is enough.
fpdf2 Overlaps with the standard reportlab functionality.
ocrmypdf Requires Tesseract (＋Windows may also need Ghostscript), not suitable for fully automatic installation at a workshop.
docx2pdf Only supports Windows／macOS, and Microsoft Word must be installed locally.
pywin32 Only needed for Windows Office COM automation.
edge-tts Has been upgraded to standard C, see below "Standard C: Voice". Do not install here.
yt-dlp Has been upgraded to standard B, see below "Standard B: Media Tools". In Section B, use winget／brew to install the system version, do not use pip to install into .venv。
youtube-transcript-api Only needed when grabbing existing YouTube subtitles; videos without subtitles cannot be processed.Standard B's yt-dlp can already grab subtitles, usually no need to install this.

The first three items (pandas、pdfplumber、xlsxwriter）After installing the standard set, are already in .venv 里了, this is brought in automatically by dependencies, not because someone installed it wrong. Do not uninstall to "clean up", it will break markitdown or python-pptx .

For the remaining items, when the user explicitly names a task later, the agent can install them intothe same .venv. Do not install the entire table at once.

⚙️ Other system tools not used in Section A (not pip packages, do not install by default)

System tool When it is needed Limitations
Tesseract OCR OCR for scanned PDF／images Traditional Chinese also requires chi_tra language data
Ghostscript OCRmyPDF for some PDF/A workflows Windows installation may require administrator
Poppler Use pdf2image Standard set already uses PyMuPDF for image conversion, can skip installation
ffmpeg Media download, conversion, merging Has been upgraded to standard B, see below "Standard B: Media Tools"
Microsoft Office docx2pdf、pywin32 COM Cannot be used without Word／PowerPoint

Do not run winget installjust because you read this table (the only exception is ffmpeg, which has been upgraded to standard B; install it according to Section B steps).

🎬 Standard B: Media Tools (yt-dlp／FFmpeg／deno)

⏭️ It will not be used today; it will be used for video editing and transcripts on the second and third days. If there is not enough time on site, you can skip the whole section and make it up at home;skipping it does not affect Section A and Section C at all. What this section installs issystem tools(not a Python package), not included in .venv, unrelated to the A section's environment.

What the B section installs, and why

Tool Purpose Why it's needed
yt-dlp Download videos, audio, and subtitles from video platforms Grab public videos as teaching materials, grab subtitles as transcripts
FFmpeg Convert media formats, merge audio and video When yt-dlp downloads high-quality video, the audio and video are separate tracks, and FFmpeg is needed to combine them
deno JavaScript runtime yt-dlp needs it when parsing new YouTube formats,installed automatically with yt-dlp, no need to install it yourself

⚠️ There are two versions of FFmpeg, don't install it twice

This is where it's easiest to waste an extra 20 minutes:

Version Where it comes from Do you need to install it yourself
yt-dlp-specific version（yt-dlp.FFmpeg） Bundled automatically when installing yt-dlp ❌ No, installing yt-dlp gives you this
System version（Gyan.FFmpeg） winget install Gyan.FFmpeg 🟡 Only install it if you want to use the ffmpeg command directly elsewhere (editing, converting)

The two can coexist without conflicting with each other. But if you just want to download videos and subtitles,installing yt-dlp is enough, no need to install the system version。

B section steps

B1. Install yt-dlp (brings FFmpeg and deno automatically)

Windows

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

🔒 When you don't have administrator privileges(common on school computers):

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

If both fail, use the Python version as a fallback (no administrator needed):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

🍎🐧 On macOS / Linux, deno is not installed automatically. "Installing yt-dlp also brings deno" is Windows winget 's behavior. On Mac/Linux, wait until you actually hit a "needs a JS runtime" error during a download, then add it: brew install deno（macOS）／curl -fsSL https://deno.land/install.sh | sh（Linux）

B2. (Optional) Install the system version of FFmpeg

Onlyneeded if you want to use the ffmpeg command directly for editing or converting. If you're just downloading videos/subtitles, skip this step.

Windows

winget install --id Gyan.FFmpeg -e --accept-source-agreements --accept-package-agreements

🔒 No administrator privileges: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. 🚨 Reopen the terminal (skipping this step will make you think the install failed)

After installing,a terminal that's already open can't read the new PATH, so typing yt-dlp will definitely say "not found" — it's not that the install failed, it's that the window is too old.

What to do: close the current PowerShell/terminal and open a new one.

If you don't want to close the window, on Windows you can refresh PATH in place:

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

macOS / Linux：source ~/.zshrc(or source ~/.bashrc）。

B4. Verify the B section (A and C sections not needed)

Windows (in PowerShell use ; , not &&）

yt-dlp --version; ffmpeg -version; deno --version

macOS / Linux

yt-dlp --version; ffmpeg -version; deno --version

Here we deliberately use ; instead of &&：&& will stop at the first missing tool, and you won't be able to see whether the next two are actually installed.

Result Looks like
✅ Success yt-dlp prints a date-style version (e.g. 2026.xx.xx）、ffmpeg prints ffmpeg version …
❌ Failure You see "not recognized"/command not found → nine times out of ten you didn't reopen the terminal, go back to B3

deno Not having it doesn't count as a failure either—it's a dependency tool that yt-dlp only uses when it encounters a new YouTube format.As long as yt-dlp --version produces output, Section B passes；deno If it's missing, wait until an actual download fails before adding it.

yt-dlp common commands cheat sheet (you'll come back to check this table on days two and three)

What you want to do Command
First check whether this video has subtitles yt-dlp --list-subs <網址>
Download Chinese subtitles and convert to SRT yt-dlp --skip-download --write-subs --sub-langs "zh-Hant,zh-TW,zh" --convert-subs srt <網址>
Grab manual subtitles and auto-generated subtitles together yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs "zh-Hant,zh-TW,zh,en" --convert-subs srt <網址>
Download audio only as mp3 (for feeding into NotebookLM) yt-dlp -x --audio-format mp3 <網址>
Download the entire video (highest quality) yt-dlp -f "bv*+ba/b" <網址>
Self-update (run this whenever YouTube changes its format) yt-dlp -U

📌 Not every video has subtitles. Many official awareness channels neither upload subtitles nor enable auto-generated subtitles,Before downloading, first use --list-subs to confirm. If there really are no subtitles, you have to take the "download mp3 → speech-to-text" route (09-groq-api）。

⚠️ Two pitfalls in Section B you absolutely must know

Pitfall 1:--print will secretly become "simulate only, don't download"

--print This parameter willimplicitly enable simulate mode. In other words, you think you're downloading "print the titleanddownload subtitles":

# ❌ 這樣寫不會真的下載到任何字幕檔
yt-dlp --print "%(title)s" --write-subs --sub-langs "zh-Hant" <網址>

In reality yt-dlp will only print the subtitles,not save a single file. To print and download at the same time, you mustalso add --no-simulate：

# ✅ 正確：印出標題，同時真的把字幕存下來
yt-dlp --print "%(title)s" --no-simulate --write-subs --sub-langs "zh-Hant" <網址>

🩹 I've actually hit this pitfall in practice: processing 76 videos in one batch, because it was missing --no-simulate，all 76 falsely reported "no subtitles"—in fact the subtitles were all there, they just weren't downloaded at all. If you see a result as suspiciously uniform as "the whole batch has no subtitles," first go back and check whether --print。

Pitfall 2: PATH only takes effect after restarting the terminal

See B3. This is the most common false failure right after a fresh install: the command is correct and the thing is installed, it's just that the window is too old.

🔊 Standard setup C: Speech (Edge-TTS)

✅ You'll use it today, and you'll hear sound within 30 seconds of installing it. This section is completely unrelated to Sections A and B,you can install this section first even if Section A isn't finished。

Edge-TTS uses the Microsoft cloud speech behind the Edge browser's "Read Aloud":no API key application, no payment, and the voice is very natural. Once installed, the agent can read the conclusions aloud to you.

Section C steps

C1. Install edge-tts

Works on all platforms (using the 00-env-setup installed by uv, no need to finish Section A first)

uv tool install edge-tts

uv tool install will install edge-tts into anisolated environmentand add it to PATH, without polluting the system Python or touching Section A's .venv。

💡 Don't want to install, just want to try it once: replace edge-tts in all the commands below with uvx edge-tts，uv it will be temporarily fetched and run without staying on your computer.

🔒 Without uv(for example if you skipped 00-env-setup）：pip install --user edge-tts that's fine too, but stilldo notuse system administrator privileges to do a global pip install。

⚠️ installed but typing edge-tts Says command not found? First restart the terminal (same reason as B3). If it still doesn't work after restarting, it means the module is installed, but that Python's Scripts folder is not on PATH—Replace edge-tts in all commands with python -m edge_tts, with exactly the same arguments(note the module name uses an underscore edge_tts, and the command name uses a hyphen edge-tts). Testing confirms this fallback can produce sound normally.

C2. 🎉 Hear sound in one line (the wow moment at the workshop)

Windows (PowerShell, copy and paste the whole thing, just one line)

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)

If you hear sound, it succeeded. This is the verification for section C—your ears are the verification tool。

C3. Verify section C (for machine interpretation)

Hearing sound with your ears is verification for humans; if an agent needs to interpret it, checkwhether the audio file was actually created：

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
Result Interpretation
✅ Success File existsand size > 10000 bytes(about 1 second or more of speech)
❌ Failure File does not exist, or size is 0 (usually no internet, or --text is empty)

The file was created but no sound can be heard → it is not an edge-tts problem, it is aplaybackproblem (volume, output device, headphones not plugged in). First turn up the volume, then double-click that mp3 in File Explorer to confirm.

🧹 Before rerunning verification, first delete the old hello.mp3 Delete, otherwise even though this run failed, it may read the file left from last time and falsely judge success. Windows:Remove-Item "$env:TEMP\hello.mp3" -Force -ErrorAction SilentlyContinue／mac、Linux：rm -f /tmp/hello.mp3

Recommended voice (Taiwan Mandarin)

Voice code Gender Feel
zh-TW-YunJheNeural Male Steady, suitable for reading conclusions and narration (default recommendation）
zh-TW-HsiaoChenNeural Female Friendly, suitable for teaching prompts and student-facing explanations
zh-TW-HsiaoYuNeural Female Another Taiwanese female voice, for when you want a change

The above three areall Taiwan Mandarin voices confirmed to exist by testing edge-tts --list-voices Confirm all existing Taiwan Mandarin voices. Other voices starting with zh-CN-* are mainland accents; they sound odd when read to Taiwanese students, so they are not recommended.

To change the voice, just change the string after --voice . To see all available voices:

edge-tts --list-voices

🪟 Playback should not open an external player window

At workshops (and in daily use), the most annoying thing isa player window popping up every time a sentence is read. In practice, avoid commands like Start-Process／start／open that "hand the file to the system default program to open," and useinline playback：

Platform Inline playback method Does it pop up a window?
Windows PowerShell System.Windows.Media.MediaPlayer(this is what the C2 line uses) ❌ No
Windows (advanced) ffplay -nodisp -autoexit(requires FFmpeg from section B) ❌ No
macOS afplay ❌ No
Linux mpv --no-video or ffplay -nodisp -autoexit ❌ No
any platform Start-Process ／ start ／ open ✅ Yes, don't use

Want the complete "answer with voice" skill?

This packageonly handles installation and confirming that sound can be produced. The truly useful voice reply skill (streaming playback, first sound in about 1–2 seconds, offline fallback,-Voice／-Out parameters) is already a separate skill,don't rewrite it here, just install that one:

https://github.com/mathruffian-dot/agent-speak-skill

Copy that repo's speak/ folder into OpenCode's skills directory ~/.config/opencode/skills/speak/, then tell the agent "answer me with voice" or "read it to me" and it will trigger.

That skill also supports Claude Code/Codex/OpenCode/AntiGravity, and the skills directories are different for each; see that repo's README for details.

How to make the agent "remember" these rules

⚠️ The "Method 1/2/3" in this section arethree ways to make the agent remember the rules, and have nothing to do with the standard A/B/C sections above; don't mix them up.

ai-agent-ep03 that AGENT_SETUP_教學檔案處理工具包.md filename inis not a conventional filename that any agent will automatically load. It won't take effect on its own; you have to submit it actively. Choose one of the three methods:

Method 1: One-time submission (simplest) Drag that file into the conversation, or say:

"Read ai-agent-ep03/AGENT_SETUP_教學檔案處理工具包.md, install only the core tools; don't install the optional tools yet."

Method 2: Make it persistent in that project (recommended) In the ai-agent-ep03/ root directory, create AGENTS.md(OpenCode's project instruction file, which loads automatically), and write:

# 本專案 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 開播放器視窗。

Method 3: Make it persistent globally Install this SKILL.md as a global skill, and afterward saying "install the internal toolkit" in any project will load it:

npx skills add mathruffian-dot/opencode-lazy-packs --skill 02-file-toolkit -g -y

Common blockers

Section A (document processing)

Symptom Cause Solution
The script says it can't find uv 's new PATH The terminal still has the old environment variables Restart OpenCode and run it again (don't modify PATH yourself)
The script says the existing .venv is not 3.12 There is another old environment in the folder Rename the old .venv and rerun;do notlet the agent delete it automatically
import fitz cannot be found PyMuPDF is not installed, or the wrong interpreter is used Confirm that it is using the .venv python, not the system python
Installed in WSL but unusable in Windows The Python environments on the two sides are independent of each other Create another copy in WSL .venv, they cannot be shared
CORE_SMOKE_FAIL The package is installed but actual operation is broken Post the complete error message,do notuse "install all the optional packages" to force a fix

Section B (audio/video tools)

Symptom Cause Solution
After installation, run yt-dlp and it says "unrecognized" Terminal is too old and can't read the new PATH Nine times out of ten it's this: restart the terminal (B3), or run the PATH refresh part of B3
winget says it needs administrator privileges No administrator on a school computer Add --scope user and rerun; if that still doesn't work, use uv tool install yt-dlp
All videos in the batch show "no subtitles" The command contains --print, which implicitly enables simulate Add --no-simulate(see B section pitfall 1)
Downloaded videos have no sound / very low quality High-quality video and audio are separate tracks; without FFmpeg they can't be merged Confirm that ffmpeg -version has output; if not, go back to B1/B2
It could download yesterday, but suddenly broke today YouTube changed its format Run yt-dlp -U to self-update, then try again
I've already installed FFmpeg, do I still need to install it again Confusion between the two FFmpeg installations No. yt-dlp comes with its own; only install the system version if you want to edit video directly (see B section explanation)

C section (voice)

Symptom Cause Solution
Run edge-tts and it says "not recognized" Still doesn't work after restarting the terminal = the module is installed but Scripts is not in PATH Switch to python -m edge_tts, the parameters are exactly the same (tested and working）
No mp3 file is generated No internet, or --text is empty Edge-TTS goes through the cloud and must be able to connect to the internet
mp3 is generated but can't be heard A playback problem, not a TTS problem Turn up the volume, confirm the output device, and double-click that mp3 in File Explorer to test it
A player window pops up after every sentence Used Start-Process／start／open Switch to inline playback (see "Don't open an external player window for playback")
Reading Chinese turns into a weird accent --voice An English or mainland Chinese voice is being used Switch to zh-TW-YunJheNeural or zh-TW-HsiaoChenNeural
Suddenly can't connect after using it for a while Edge-TTS is an unofficial channel; Microsoft occasionally adjusts the interface uv tool upgrade edge-tts(or uvx edge-tts@latest) and try again

"Install once in one agent, and all other agents can use it" only holdson the same operating system, the same folder, and the same .venv . Windows, WSL, Docker, the cloud, and sandboxes cannot share Python packages. The B section's system tools (yt-dlp/ffmpeg/deno), however, areinstalled at the operating system layer, and all agents on the same computer can invoke them—but WSL and Windows still count as two different machines.

🤖 Machine-readable success signals (report separately for all three sections)

After running, please output the following block in full, so that later agents (or the "install everything at once" package) can directly interpret it without having to understand the Chinese instructions. The three sections are judged independently: if one section FAIL it will not make the other two sections 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 ===

Judgment rules (agent, judge according to this; do not decide on your own):

section PASS conditions for
A verify_core.py outputs CORE_OK: 10/10 and exit code is 0
B yt-dlp --version has a version number (deno missing does not count as failure; system FFmpeg not installed also does not count as failure)
C Verify that the audio file existsand c_audio_bytes > 10000
overall result conditions
PASS Sections A, B, and C are all PASS
PARTIAL at least one section PASS, the rest are SKIPPED or FAIL（On the day of the workshop, only A+C are installed and B is marked SKIPPED is normal, not an error）
FAIL None of the three sections is PASS

Completion report format (for humans)

內部工具包 三合一 安裝完成回報：

【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 路徑> 執行

On failure, list only the failed steps and the original error summary,do notautomatically install optional tools as a remedy, and alsodo notmark the other two sections as failed just because one section failed.

Known fixes (Section A: relative to ai-agent-ep03 original document)

This package fixes three issues found in actual testing. If the original repo has not yet been updated, this document prevails:

  1. The statement "optional not installed" does not match reality. The original document lists pandas、pdfplumber、xlsxwriter under "optional, do not install by default," and the report template even has the agent print "🟡 Optional packages: not installed (correct)"—but after actually running the standard installation, these threeare already in .venv in, so that statement is false. Actual sources (uv pip compile resolved and verified):pandas ← markitdown[xlsx]、pdfplumber ← markitdown[pdf]、xlsxwriter ← python-pptx(Note: xlsxwriter comes with the standard python-pptx and is not from markitdown extras). This package has added source notes item by item in the optional table, and changed that line in the report template to "automatically brought in by standard dependencies (normal)."

  2. matplotlib version is outdated. original requirements-core.txt pinned 3.11.0, PyPI latest is 3.11.1. This package's Section A step A2 requires changing it before installation.

  3. The Python version lower bound is not stated. The original document only mentions 3.12, so readers may mistakenly think 3.12 is required. Based on dependency relationships, the effective lower bound is 3.11（matplotlib 3.11.1 requires >=3.11; 3.10 will fail directly during resolution). This package adds a complete version comparison table.

Also fills two gaps in the original tool package:

  1. Only a Windows installation script. People running WSL/macOS/Linux will get stuck here. This package adds equivalent manual steps for creating a venv with uv + installing requirements.

  2. AGENT_SETUP_教學檔案處理工具包.md is not a conventional filename that agents automatically load. This package adds three ways to "make the agent remember" (one-time submission/project AGENTS.md resident/global skill).

What this three-in-one expansion did (for maintainers)

Originally this package had only Section A (Python packages), and the audio/video and speech materials were scattered in three places, so teachers had to piece them together themselves to install everything. This time the three places are merged:

section Originally located at Handling during merge
A Existing content of this file Kept as is, only added A1～A5 numbering and --scope user fallback
B Private notes "agents essential tools" (never made public) organized into installation steps + command cheat sheet;keep two real-world pitfalls（--print implicitly simulate, reopen terminal to refresh PATH)
C agent-speak-skill / claude-speak-skill two repos only carry over "installation + minimal usable verification", the full voice reply skill still points to agent-speak-skill, not rewritten in this package

three conflicts resolved during the merge (places where the original documents contradicted each other):

  1. Section A's optional table originally said "edge-tts、yt-dlp not installed by default", which directly clashed with the newly added Sections B and C → the two rows were relabeled "upgraded to standard B/C", and a note was added to rule 2 of the seven rules.
  2. Section A's system tools table originally said "ffmpeg: not needed for document processing" + "don't run winget installjust because you read this table" → the ffmpeg row was changed to point to Section B, and the prohibition gained a single exception.
  3. "How to make the agent remember" originally used A／B／C as the numbering for three approaches, clashing with the standard A/B/C names → changed to "Approach One/Two/Three".

Deliberately not done: no prices or version numbers are hardcoded in this package (the existing requirements-core.txt pin in Section A is the exception, and that was pinned deliberately); the tools in Sections B and C will keep updating, and hardcoding would only make the document go stale.