env-setup

name

env-setup

description

Checking and provisioning the machine's environment for the video-agent-kit plugin — probing for ffmpeg/ffprobe that actually carry the encoders and filters we render with (libx264/aac/libmp3lame, libass, libfreetype), python packages (mcp, cv2, numpy, PIL, jieba, fontTools, scenedetect) in the interpreter Claude Code really uses, a CJK font whose cmap truly covers Chinese, and which speech channel is in play (under ZCode the official channel needs no local key) — then installing what is missing (China mirrors by default) or telling the user exactly what to install. Works on macOS, Windows and Linux. Use BEFORE the first edit run on a new machine, when the session-start hook reports 缺失依赖, or whenever a tool fails in an environment-shaped way — ModuleNotFoundError, `ffmpeg not found`, `Unknown encoder 'libx264'`, `No such filter: 'subtitles'`, `no font file found for family`, 字幕烧成豆腐块/方块, speech_transcribe 超时或 401. Also use when asked to 检查环境 / 装依赖 / 配国内源 / setup / doctor.

Env Setup

Claude Code is a generic harness — it ships no ffmpeg, no CJK font, no python media stack. Everything this kit needs is per-machine, and provisioning it is this skill's job. A run started on a half-provisioned machine does not fail cleanly: it burns the whole observe→timeline phase and then dies at render_preview, or worse, succeeds while burning subtitles as tofu boxes (□□□) because fc-match handed us a font with no Chinese glyphs and ffmpeg exited 0.

One entry point — everything else here is judgement about its output:

python3 <plugin_root>/skills/env-setup/scripts/env_doctor.py          # probe + what's needed
python3 <plugin_root>/skills/env-setup/scripts/env_doctor.py --fix    # + install the auto-safe items

(Windows: python instead of python3 if that's what's on PATH.) Plugin root is announced at session start and written to .video_agent/plugin_root. Always call it by absolute path — cwd is the project directory, not the skill directory. A full probe is a few seconds; give Bash ≥ 120s anyway, because a blocked network spends its timeouts before answering.

What must be present, and what dies without it

The script decides state and prints the exact requirement + an example command for the current OS. This table is only for judging impact:

Requirement	Dead without it
Python ≥ 3.10, and mcp (1.x), requests, opencv-python-headless, numpy, pillow, jieba, fonttools, scenedetect in that same interpreter	mcp → every tool (server won't start); requests → transcribe + all TTS; cv2/numpy/PIL → video_ingest, contact sheets, qc_preview scans, i.e. all visual evidence; jieba → subtitle_build line breaking; fontTools → the pre-render tofu check; scenedetect → recap shot boundaries
ffmpeg + ffprobe on PATH, with libx264 / aac / libmp3lame	ingestion and probing (Phase 1 can't start); missing encoder = the render dies at the last step, after everything upstream was paid for
that ffmpeg built with libass + libfreetype (subtitles/ass/drawtext filters)	subtitle burn-in, title cards, score bugs — the recap deliverable
a CJK font whose cmap really covers Chinese	Chinese subtitles/titles. This one fails silently — see the tofu warning above
cloud ASR credentials or Speech MCP access	speech_transcribe; without it there is no transcript, so every speech-driven decision is guesswork. Under ZCode this is never a gap — see below
cloud TTS credentials or Speech MCP access	narration/dubbing (speech_synthesize, tts_generate, *_tts). Edit-only and subtitle-only tasks survive without it

Speech needs no local key under ZCode

Transcription and synthesis default to the official channel, which authenticates with identity the ZCode host injects into each tools/call. There is nothing to configure, nothing to install, and no key to obtain. Two consequences:

• Never tell the user to set an ASR/TTS key to get transcription working, and never treat a "credentials not set" line as a blocker. The doctor reports these two rows as 官方通道 whenever ZCODE_BASE_URL is present, and both rows are soft (只降级不致命) in every case.
• The doctor runs as its own process, so it cannot see the per-call identity headers — only whether the official channel exists at all. A specific call failing on identity (not logged in, no Coding Plan) surfaces from the tool itself, with a message saying which of the two it is. That is the signal to act on; the doctor's row is not.

Only non-ZCode hosts need configuration, in this order of preference: remote Speech MCP (VE_SPEECH_MCP_URL / VE_SPEECH_MCP_TOKEN), or — as a legacy escape hatch for deployments bringing their own speech service — a direct HTTP backend, which needs its endpoint and resource/model identifiers in the process environment (a project .env is untrusted for those; it could otherwise redirect an authenticated call) plus a key. /env-check prints the exact set.

Version floors are the only hard numbers; how the tool gets installed is the user's choice — package manager, installer, conda, whatever the machine already uses.

Mirrors — use them by default, not as a fallback

Most users of this plugin are in mainland China, where the official PyPI CDN and GitHub-hosted Homebrew bottles are routinely slow enough to time out. A timeout there doesn't look like a network problem — it looks like "the install ran for ten minutes and then failed", which gets misdiagnosed as a broken package every time. So a mirror is the first choice, not the recovery step. The doctor already puts the mirror into the command it prints (and uses); when you install by hand, use these:

What	First choice	Alternative
pip	清华 https://pypi.tuna.tsinghua.edu.cn/simple — pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <pkg>	阿里云 https://mirrors.aliyun.com/pypi/simple/
ffmpeg	macOS: export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles then brew install ffmpeg. Any platform / no root: conda install -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge ffmpeg — cleanest path, no system package manager touched.	apt sources → Tsinghua/USTC (system-wide change); Windows winget/gyan.dev has no mirror concept (use conda)
CJK font	Linux apt-get install fonts-noto-cjk (apt mirror helps). mac/Windows already ship 苹方/微软雅黑 — install nothing.	Download NotoSansSC from github.com/notofonts/noto-cjk into any directory and point VE_FONT_DIRS at it (works without root)
direct speech endpoint (only if you configured one)	no mirror exists — it is the service itself. Unreachable = network policy; that's a proxy question, not a mirror one	—

Notes that matter in practice:

• Making it permanent is the user's call, not yours by default: pip config set global.index-url <url> writes their global config and affects every other project on the machine. The doctor prints it; only run it if the user agrees — a one-off -i <url> needs no such permission.
• Mirrors lag. If a package version genuinely isn't on the mirror, the fix is to drop -i for that one install and go to the official source — not to conclude the environment is broken.
• Outside mainland China these mirrors are pointless (and slower). VE_PIP_INDEX=<url> overrides the pip index the doctor uses; set it to the official URL to opt out entirely.
• A mirror fixes slowness, a proxy fixes blockage — different problems. Try the mirror first; only if the mirror itself is unreachable is it a proxy/firewall question.

Workflow

doctor → read the requirements → --fix the auto items → tell the user what's left → re-run doctor → report

1. Run the doctor first, always. Never install from this file's tables or from memory — on a provisioned machine the correct action is nothing, and a speculative install can downgrade a working package (or, with opencv, break the one that worked).
2. --fix covers only the user-space, idempotent subset: pip installs into the running interpreter. It deliberately does not install ffmpeg, fonts, or uninstall anything — those are system-level or destructive, the right method differs per machine (and per permission level), and guessing wrong is worse than reporting. For those, give the user the requirement and the suggested command, and let them run it.
3. Fix in the printed order. An item whose prerequisite failed prints [未探测] instead of a guessed verdict — don't run a fix for an unprobed item; fix its prerequisite and re-run.
4. · means "not applicable on this OS", not "broken", and 只降级不致命 means exactly that: the two speech-channel rows and disk headroom don't block a task. Everything else is a hard gap.
5. After a PATH-changing install, the new tool is invisible to the current shell (most visibly on Windows). If the doctor still can't see ffmpeg the user just installed, that's the reason — have them restart the terminal (or Claude Code) rather than reinstalling.
6. Re-run the doctor at the end — not the fix commands' exit codes. pip install can succeed while the import still fails (a wheel mismatched to the platform). The run writes .video_agent/env_report.json as the receipt, so don't re-probe every turn; re-probe after installing something or after a tool fails.
7. Report in capability terms, then stop if something's dead. "ffmpeg has no libass → subtitle burn-in unavailable; the recap can't ship. Install a full build and re-run /env-check." Do not enter a phase whose tools are dead and improvise around it.

Rules

• Install only what the doctor flagged. Extra packages are how a working environment drifts into an unreproducible one.
• Never substitute for a missing dependency. No cv2 does not mean "extract frames with ffmpeg and eyeball the filenames"; no transcript does not mean "infer the dialogue from the visuals"; no CJK font does not mean "render the subtitles in English". A dead capability is a report line, not a workaround.
• scenedetect must be installed with --no-deps. It declares opencv-python (the GUI build), which overwrites the same cv2 package directory as opencv-python-headless and leaves both half-broken. The doctor prints the two-step command; don't "simplify" it.
• Never auto-uninstall opencv. If GUI+headless are both installed the doctor reports it and prints the fix, because the GUI build may belong to another project on that machine. That's the user's call.
• A font that resolves is not a font that works. fc-match never fails: ask it for an uninstalled Chinese family and it returns DejaVu Sans, which has no CJK glyphs, and libass then renders blanks while ffmpeg exits 0. The doctor reads the cmap for exactly this reason — if it says the resolved font has no Chinese coverage, treat it as missing even though a path was printed.
• Adding a dependency to this plugin means adding a Check to env_doctor.py in the same change (and to requirements.txt). The SessionStart hook imports cheap_missing() from it, so the cheap checks are the single source of truth for the startup warning — a dependency that isn't a Check is one nobody hears about until it crashes.

Fonts: the one platform difference worth knowing

Font lookup is centralised in mcp/ve_tools/fonts.py, searched in this order:

1. VE_FONT_DIRS (os.pathsep-separated) — explicit override, always wins
2. the Linux dirs the kit has always used (/root/.fonts, /usr/share/fonts)
3. the platform's own font dirs — /System/Library/Fonts, ~/Library/Fonts (macOS), %SystemRoot%\Fonts, %LOCALAPPDATA%\Microsoft\Windows\Fonts (Windows)
4. fc-list :lang=zh when fontconfig exists, cmap-verified

So macOS and Windows normally need no font install at all (苹方 / 微软雅黑 are found in step 3, and libass resolves them through CoreText/DirectWrite). Linux images without fonts-noto-cjk are the case that actually needs work. When a user has fonts somewhere unusual, VE_FONT_DIRS is the answer — not a code change, and not sudo cp into /usr/share/fonts.

Anti-patterns

• Prescribing one platform's install method (apt-get …) to a user on another OS — the doctor already picked the right example for their machine; if they'd rather use their own method, that's fine, the requirement is what matters.
• Reading this skill's tables and installing from them without running the doctor.
• Treating a [未探测] line as a missing dependency, or a · (n/a) line as a defect.
• Auto-installing system-level software (ffmpeg, fonts) or uninstalling packages on the user's machine without being asked.
• Retrying a stalled pip install unchanged on a machine that needs a mirror (or a proxy) — the second attempt fails the same way, ten minutes later.
• Declaring the environment fixed off exit codes without a re-probe.
• Re-running the full doctor every turn "to be safe" — .video_agent/env_report.json holds the last verdict.
• Proceeding into a render or a recap with ffmpeg missing libass, letting it surface as a mysterious tool error twenty rounds later.
• Asking the user for an ASR/TTS key. Under ZCode there is no key to give; the doctor's speech rows say 官方通道 and a failing call reports whether it is a login or a plan problem. Chasing a key wastes the user's turn and fixes nothing.
• Blaming the plugin for speech_transcribe timeouts before checking which channel it used — an unreachable configured direct endpoint is a network policy problem no amount of retrying fixes, and it is not even consulted when the official channel or a remote Speech MCP is in play.