papercut-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Papercut setup

Papercut 设置

A guided wrapper around

install.sh

. It checks what is installed, asks how much the user wants, runs the installer non-interactively and reports. Use it whenever another papercut skill finds something missing.

install.sh

的引导式封装。它会检查已安装的内容，询问用户希望安装的范围，以非交互方式运行安装程序并报告结果。当其他 papercut skill 发现缺少内容时，使用此流程。

Preflight

预检查

Find the repo root (where
```
install.sh
```
lives):
```
readlink
```
on the installed skill folder ends in
```
<root>/skills/papercut-setup
```
. Look in each harness's skills folder in turn (the table is
```
harnesses.sh
```
; typically
```
~/.claude/skills
```
,
```
~/.agents/skills
```
,
```
~/.config/opencode/skills
```
, or the same under
```
<project>/
```
). Failing that,
```
PAPERCUT_HOME=
```
in
```
${XDG_CONFIG_HOME:-~/.config}/papercut-explainer/config.env
```
. If neither exists, the skills probably came from
```
npx skills add
```
(skills only, no library). Ask where to clone the repo (default
```
~/papercut-explainer
```
), run
```
git clone https://github.com/0xS4N4TG/papercut-explainer <dir>
```
, and use that as the root. The installer then replaces the copied skill folders with links into the checkout (it backs up real folders first). Never guess a path.
Run every
```
install.sh
```
command from that root. It needs bash, and macOS or Linux (Windows: use WSL).
The installer's own prompts need a terminal, which the agent's shell tool lacks. Always pass
```
--yes
```
and the answers as flags. Tell the user they can run
```
./install.sh
```
themselves for the interactive menu.

找到仓库根目录（其中包含
```
install.sh
```
）：已安装 skill 文件夹上的
```
readlink
```
结果应以
```
<root>/skills/papercut-setup
```
结尾。依次检查每个 harness 的 skills 文件夹（对应列表在
```
harnesses.sh
```
中；通常为
```
~/.claude/skills
```
、
```
~/.agents/skills
```
、
```
~/.config/opencode/skills
```
，或
```
<project>/
```
下的对应目录）。如果仍找不到，则在
```
${XDG_CONFIG_HOME:-~/.config}/papercut-explainer/config.env
```
中查找
```
PAPERCUT_HOME=
```
。如果两者都不存在，skills 很可能来自
```
npx skills add
```
（仅包含 skills，不含 library）。询问用户要把仓库克隆到哪个位置（默认
```
~/papercut-explainer
```
），运行
```
git clone https://github.com/0xS4N4TG/papercut-explainer <dir>
```
，并将该目录用作 root。安装程序随后会把复制来的 skill 文件夹替换为指向 checkout 的链接（替换前会备份真实文件夹）。绝不猜测路径。
所有
```
install.sh
```
命令都必须从该 root 运行。安装程序需要 bash，并支持 macOS 或 Linux（Windows：使用 WSL）。
安装程序自身的交互式提示需要终端，而 Agent 的 shell 工具没有终端。始终传入
```
--yes
```
，并将答案作为标志传递。告知用户可以自行运行
```
./install.sh
```
使用交互式菜单。

1. Doctor

1. Doctor（诊断）

./install.sh --doctor

Add

--project DIR

--skills-dir DIR

--target <names>

if the skills went somewhere other than the detected defaults; the doctor only looks where you point it, and with no

--target

one complete install location is enough. It prints

[ok]

[--]

(missing) or

[!!]

(wrong). Summarise it in plain words:

skills installed, config file and
```
PAPERCUT_LIB
```
node 20+, npm, ffmpeg, python3
Remotion agent skills, Python tools (numpy + Pillow)
voice:
```
qwen_tts
```
importable, a CustomVoice model in the Hugging Face cache
library files present

Then say which install mode that adds up to (see

papercut-explainer

, Install modes).

./install.sh --doctor

如果 skills 被安装到了检测到的默认位置之外，添加

--project DIR

、

--skills-dir DIR

或

--target <names>

；doctor 只检查你指定的目录，不带

--target

时，一个完整的安装位置就足够了。它会打印

[ok]

、

[--]

（缺失）或

[!!]

（错误）。用通俗语言总结：

已安装的 skills、配置文件及
```
PAPERCUT_LIB
```
node 20+、npm、ffmpeg、python3
Remotion agent skills、Python 工具（numpy + Pillow）
语音：
```
qwen_tts
```
可导入，Hugging Face 缓存中有 CustomVoice 模型
library 文件已存在

然后说明这些项目对应哪种安装模式（参见 papercut-explainer 的“安装模式”）。

2. Ask

2. Ask（询问）

Ask only what is still open, in one call (your agent's question tool, for example AskUserQuestion in Claude Code). Run

./install.sh --dry-run --mode minimal --yes

first if you need to know which harnesses it detected (

--target auto

, the default):

Question	Options
How much?	Minimal: skills only, seconds. Standard: render with a placeholder voice, ~0.7 GB and a few minutes. Full: Standard + local voiceover, +4-6 GB (a 1.5 GB venv plus a 2.3 or 4.2 GB model) and a 2-minute smoke test. Custom: pick components.
Which agents?	Detected on this machine (default, `--target auto` ; Claude Code if none), a list such as `--target claude,codex,gemini` , or `--target all` . Names are in `harnesses.sh` ; the README's Works with table says which are tested.
Where do the skills go?	User-wide (the default) or one project ( `--project DIR` ).
Copy or link?	Symlink (default, updates with `git pull` ) or `--copy` (a snapshot).
Scene-agent model, per agent with file subagents ( `claude` , `opencode` , `codex` , `gemini` ; skip the rest)?	One question per selected agent, each with Inherit (use the session model) as an option. Claude Code: Sonnet (default: cheapest, what the scene agents were tuned on) · Opus (strongest; every parallel scene agent bills at Opus rates) · Haiku · Inherit. Maps to `--claude-model sonnet\|opus\|haiku\|inherit\|<id>` . Other agents: default Inherit, or a model id in that agent's own format (opencode `provider/model-id` , for example `anthropic/claude-sonnet-5-5` ; Codex and Gemini plain ids). Maps to `--opencode-model M` or `--agent-model codex=M` .
Another provider's model (DeepSeek and others)?	Only if the user asks. Connect the provider inside the agent first (OpenCode `/connect` ; Codex `config.toml` provider; Claude Code's `ANTHROPIC_` variables), then pass its model id as above. The README's Models other than Claude* section has the steps and the DeepSeek ids. Say plainly that it is untested end to end and that weaker models cost more QA rounds.
TTS model size (Full)	1.7B, better prosody, ~4.2 GB (default). 0.6B, lighter and faster, ~2.3 GB.
Voice-clone model (Full)	No (default), or `--with-clone` : the Base model of the same size again.

Confirm before any multi-GB download. On a machine with no GPU (not Apple Silicon, no NVIDIA), TTS generation takes minutes per line; suggest recording the voiceover or the placeholder voice instead.

只询问尚未确定的事项，并在一次调用中完成（例如使用 Agent 的 question 工具，如 Claude Code 中的 AskUserQuestion）。如果需要知道检测到了哪些 harness（

--target auto

，默认值），先运行

./install.sh --dry-run --mode minimal --yes

：

问题	选项
安装多少？	Minimal：仅安装 skills，数秒。Standard：使用 placeholder voice 渲染，约 0.7 GB，需要数分钟。Full：Standard + 本地 voiceover，额外需要 4-6 GB（1.5 GB venv，加上 2.3 或 4.2 GB 模型），并进行一次 2 分钟的 smoke test。Custom：自行选择组件。
使用哪些 Agent？	本机检测到的 Agent（默认， `--target auto` ；如果没有检测结果，则使用 Claude Code）、指定列表（如 `--target claude,codex,gemini` ）或 `--target all` 。名称列在 `harnesses.sh` 中；README 的 Works with 表列出了经过测试的 Agent。
Skills 放在哪里？	用户级目录（默认）或单个项目（ `--project DIR` ）。
复制还是链接？	Symlink（默认，可随 `git pull` 更新）或 `--copy` （快照）。
Scene-agent 模型（仅针对支持 file subagents 的 Agent，即 `claude` 、 `opencode` 、 `codex` 、 `gemini` ；跳过其他 Agent）？	每个选中的 Agent 单独询问一次，选项均包含 Inherit（使用 session model）。Claude Code：Sonnet（默认；成本最低，也是 scene agents 的调优目标）· Opus（能力最强；每个并行 scene agent 都按 Opus 费率计费）· Haiku · Inherit。对应 `--claude-model sonnet\|opus\|haiku\|inherit\|<id>` 。其他 Agent：默认 Inherit，或使用该 Agent 自身格式的 model id（opencode 使用 `provider/model-id` ，例如 `anthropic/claude-sonnet-5-5` ；Codex 和 Gemini 使用纯 id）。对应 `--opencode-model M` 或 `--agent-model codex=M` 。
另一个 provider 的模型（DeepSeek 等）？	仅在用户提出要求时询问。首先在 Agent 内连接 provider（OpenCode `/connect` ；Codex `config.toml` provider；Claude Code 的 `ANTHROPIC_` variables），然后按上述方式传入 model id。README 的 Models other than Claude* 一节提供了具体步骤和 DeepSeek ids。请明确说明：该方案未经过端到端测试，较弱的模型需要更多 QA 轮次，因此成本更高。
TTS 模型大小（Full）	1.7B，韵律效果更好，约 4.2 GB（默认）。0.6B，更轻量、更快速，约 2.3 GB。
Voice-clone 模型（Full）	不使用（默认），或传入 `--with-clone` ：再次安装相同大小的 Base 模型。

在下载任何数 GB 的内容之前先确认。如果机器没有 GPU（既不是 Apple Silicon，也没有 NVIDIA），TTS 每行生成需要数分钟；建议录制 voiceover 或改用 placeholder voice。

3. Install

3. Install（安装）

./install.sh --mode <minimal|standard|full> --yes [--target auto|all|claude,codex,...] [--claude-model M] [--opencode-model M] [--agent-model NAME=M] [--skills-dir DIR | --project DIR] [--copy] [--tts-model 1.7B|0.6B] [--with-clone]
./install.sh --mode custom --components skills,deps,remotion-skills,pytools,tts,verify --yes

Add
```
--dry-run
```
first if the user wants to see the plan; it changes nothing.
The scene-builder agent is written as a copy per harness, in that harness's own format (Claude and OpenCode markdown, Codex TOML, Gemini markdown), with the chosen model line or none for Inherit. Harnesses without file subagents get none;
```
papercut-build
```
then builds scenes itself or uses the harness's own parallel tasks. Skills stay symlinks. To change a model later:
```
./install.sh --mode custom --components skills --target codex --agent-model codex=<id> --yes
```
(or
```
--claude-model
```
,
```
--opencode-model
```
).
Standard and Full take minutes (npm install, Remotion's Chrome, venvs, model download). Run them in the background and check the output; do not hold a foreground call.
What each mode does: Minimal links the skills and the scene-builder agent (into each selected harness's skills and agents folders). Standard adds a dependency check, the Remotion agent skills (
```
npx skills add remotion-dev/skills -g -y -a <harness id>
```
once per selected harness, installed user-wide, so say so when you confirm the plan), a Python venv with numpy, Pillow and soundfile, and a self-test render. Full adds
```
library/voice/setup_tts.sh
```
: a voice venv with Qwen3-TTS, an ASR backend (mlx-whisper on Apple Silicon, faster-whisper elsewhere), the model download and a one-line smoke test.
The installer writes
```
PAPERCUT_HOME
```
,
```
PAPERCUT_LIB
```
,
```
PAPERCUT_PY
```
,
```
QWEN_TTS_PY
```
and
```
ASR_PY
```
into
```
~/.config/papercut-explainer/config.env
```
. An existing skill folder that differs from this checkout is backed up to
```
~/.config/papercut-explainer/backups/
```
(not into the skills folder, so it is not loaded twice); an identical copy, such as one from
```
npx skills add
```
, is just replaced.

./install.sh --mode <minimal|standard|full> --yes [--target auto|all|claude,codex,...] [--claude-model M] [--opencode-model M] [--agent-model NAME=M] [--skills-dir DIR | --project DIR] [--copy] [--tts-model 1.7B|0.6B] [--with-clone]
./install.sh --mode custom --components skills,deps,remotion-skills,pytools,tts,verify --yes

如果用户希望先查看计划，先添加
```
--dry-run
```
；它不会更改任何内容。
scene-builder Agent 会按 harness 分别写入一份副本，采用该 harness 自己的格式（Claude 和 OpenCode 使用 markdown，Codex 使用 TOML，Gemini 使用 markdown），并写入所选 model；如果选择 Inherit，则不写 model 行。不支持 file subagents 的 harness 不会获得该 Agent；此时
```
papercut-build
```
会自行构建场景，或使用 harness 自身的并行任务。Skills 保持为 symlink。以后更换 model：运行
```
./install.sh --mode custom --components skills --target codex --agent-model codex=<id> --yes
```
（或使用
```
--claude-model
```
、
```
--opencode-model
```
）。
Standard 和 Full 需要数分钟（npm install、Remotion 的 Chrome、venv、模型下载）。应在后台运行并检查输出；不要让调用一直占用前台。
各模式具体执行的内容：Minimal 将 skills 和 scene-builder Agent 链接到每个所选 harness 的 skills 与 agents 文件夹。Standard 增加依赖项检查、Remotion agent skills（每个所选 harness 执行一次
```
npx skills add remotion-dev/skills -g -y -a <harness id>
```
，安装在用户级目录，因此确认计划时应说明这一点）、包含 numpy、Pillow 和 soundfile 的 Python venv，以及一次自测渲染。Full 增加
```
library/voice/setup_tts.sh
```
：一个包含 Qwen3-TTS 的 voice venv、一个 ASR backend（Apple Silicon 上使用 mlx-whisper，其他平台使用 faster-whisper）、模型下载，以及一次单行 smoke test。
安装程序会将
```
PAPERCUT_HOME
```
、
```
PAPERCUT_LIB
```
、
```
PAPERCUT_PY
```
、
```
QWEN_TTS_PY
```
和
```
ASR_PY
```
写入
```
~/.config/papercut-explainer/config.env
```
。如果现有 skill 文件夹与此 checkout 不同，会将其备份到
```
~/.config/papercut-explainer/backups/
```
（不会放进 skills 文件夹，以免被加载两次）；如果副本完全相同（例如来自
```
npx skills add
```
），则直接替换。

4. Verify and report

4. Verify and report（验证并报告）

Run

./install.sh --doctor

again with the same

--project

--skills-dir

--target

. Report what is installed, which scene-agent model each agent got, what failed (the installer prints

needs attention:

with component names), and the fix. A new Claude Code, Codex or Gemini CLI session picks up newly linked skills (restart it); opencode reloads configuration automatically. Then suggest: "make a papercut explainer about <link>", or one stage at a time ("write a hook for...", "storyboard this script", "set up the voice").

使用相同的

--project

、

--skills-dir

或

--target

再次运行

./install.sh --doctor

。报告已安装的内容、每个 Agent 获得了哪个 scene-agent model、哪些项目失败（安装程序会打印

needs attention:

及组件名称）以及相应的修复方法。Claude Code、Codex 或 Gemini CLI 的新会话会加载新链接的 skills（需重启）；opencode 会自动重新加载配置。随后建议：“为一个关于 <link> 的主题制作 papercut explainer”，或者一次完成一个阶段（“为……编写 hook”、“为这个脚本制作 storyboard”、“设置语音”）。

Troubleshooting

故障排除

Symptom	Fix
`node` older than 20, or missing	Install Node 20+ (nodejs.org, `brew install node` ), then `./install.sh --mode custom --components deps,verify --yes` .
`ffmpeg` missing	`brew install ffmpeg` or `apt install ffmpeg` .
Voice venv: "need Python 3.10-3.12"	Qwen3-TTS has no wheels for newer Python. Install `uv` (https://docs.astral.sh/uv/) or `brew install python@3.12` , rerun the `tts` component.
Hugging Face download stalls or fails	Rerun; finished files are kept and the script retries 3 times. It sets `HF_HUB_DISABLE_XET=1` ; set it yourself for manual downloads.
First render is slow	Remotion downloads its headless Chrome once. The audio render and `capture.mjs` use your own Chrome; set `CHROME_PATH` if it isn't in a usual place.
Self-test fails	Run `library/tools/selftest.sh` directly to see the failing step.
Skills don't show	Restart Claude Code, Codex or Gemini CLI (opencode reloads). Check the harness's folder ( `harnesses.sh` ; `~/.agents/skills` for most) and run `./install.sh --doctor` .
opencode: "Configuration is invalid ... tools"	An old copy of the Claude agent file sits in an opencode agents folder. Rerun `./install.sh --target opencode` ; it writes the opencode version.
Scene agents cost too much, or run on the wrong model	Rerun the skills step with another model: `./install.sh --mode custom --components skills --claude-model sonnet --yes` (or `--opencode-model inherit` ). `inherit` means the session model.
Move from Minimal to Standard	`./install.sh --mode custom --components deps,remotion-skills,pytools,verify --yes`
Add the voice later	`./install.sh --mode custom --components tts --yes [--tts-model 0.6B] [--with-clone]`
Remove it	`./install.sh --uninstall` removes the links it recorded. It leaves `config.env` , the venvs under `~/.local/share/papercut-explainer` and the Hugging Face cache; delete those by hand for the space.
Windows	Not supported directly. Use WSL.

症状	修复方法
`node` 版本低于 20 或缺失	安装 Node 20+（nodejs.org、 `brew install node` ），然后运行 `./install.sh --mode custom --components deps,verify --yes` 。
缺少 `ffmpeg`	运行 `brew install ffmpeg` 或 `apt install ffmpeg` 。
Voice venv： `need Python 3.10-3.12`	Qwen3-TTS 没有适用于较新 Python 的 wheel。安装 `uv` （https://docs.astral.sh/uv/）或运行 `brew install python@3.12` ，然后重新运行 `tts` component。
Hugging Face 下载停滞或失败	重新运行；已完成的文件会保留，脚本会重试 3 次。它会设置 `HF_HUB_DISABLE_XET=1` ；手动下载时请自行设置。
首次渲染较慢	Remotion 首次会下载 headless Chrome。音频渲染和 `capture.mjs` 使用你自己的 Chrome；如果 Chrome 不在常见位置，请设置 `CHROME_PATH` 。
自测失败	直接运行 `library/tools/selftest.sh` ，查看具体失败的步骤。
Skills 未显示	重启 Claude Code、Codex 或 Gemini CLI（opencode 会自动重新加载）。检查 harness 的文件夹（ `harnesses.sh` ；大多数环境位于 `~/.agents/skills` ），并运行 `./install.sh --doctor` 。
opencode： `Configuration is invalid ... tools`	opencode 的 agents 文件夹中残留了 Claude agent 文件的旧副本。重新运行 `./install.sh --target opencode` ；它会写入 opencode 专用版本。
Scene agents 成本过高或使用了错误的 model	使用另一个 model 重新运行 skills 步骤： `./install.sh --mode custom --components skills --claude-model sonnet --yes` （或 `--opencode-model inherit` ）。 `inherit` 表示使用 session model。
从 Minimal 升级到 Standard	`./install.sh --mode custom --components deps,remotion-skills,pytools,verify --yes`
以后再添加语音	`./install.sh --mode custom --components tts --yes [--tts-model 0.6B] [--with-clone]`
卸载	`./install.sh --uninstall` 会删除已记录的 links。它会保留 `config.env` 、 `~/.local/share/papercut-explainer` 下的 venvs 以及 Hugging Face 缓存；如需释放空间，请手动删除这些内容。
Windows	不直接支持。请使用 WSL。

Hand-off

交接

Return to the skill that sent you here, or to

papercut-explainer

for the stage table. Files hold the state:

config.env

carries the library path, so the other skills resolve it without asking again.

返回调用此 skill 的 skill，或返回 papercut-explainer 查看阶段表。文件会保存状态：

config.env

记录 library 路径，因此其他 skills 无需再次询问即可解析该路径。