papercut-setup

Papercut 设置

围绕 install.sh 的引导式封装。它会检查已安装的内容，询问用户需要安装多少内容，以非交互方式运行安装程序并报告结果。其他 papercut 技能发现缺少内容时，请使用此工具。

安装前检查

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

1. Doctor

./install.sh --doctor

如果技能安装到了检测出的默认位置之外，请添加 --project DIR、--skills-dir DIR 或 --target <names>；doctor 只会检查你指定的位置，不传入 --target 时，任一完整的安装位置即可。它会输出 [ok]（正常）、[--]（缺失）或 [!!]（错误）。用通俗语言总结检查结果：

• 已安装的技能、配置文件和 PAPERCUT_LIB
• node 20+、npm、ffmpeg、python3
• Remotion Agent 技能、Python 工具（numpy + Pillow）
• 语音：qwen_tts 可导入，Hugging Face 缓存中有一个 CustomVoice 模型
• 库文件已就位

然后说明这些情况对应哪种安装模式（参见 papercut-explainer 中的 Install modes）。

2. 提问

只询问尚未确定的事项，并一次性提问（例如，使用 Agent 的提问工具，如 Claude Code 中的 AskUserQuestion）。如果需要了解检测到哪些 harness（--target auto，默认值），请先运行 ./install.sh --dry-run --mode minimal --yes：

问题	选项
要安装多少内容？	Minimal：仅技能，几秒钟。Standard：使用占位语音进行渲染，约 0.7 GB，耗时几分钟。Full：Standard + 本地配音，额外占用 4-6 GB（1.5 GB 的 venv，以及 2.3 GB 或 4.2 GB 的模型），并进行 2 分钟的冒烟测试。Custom：选择组件。
使用哪些 Agent？	此计算机上检测到的 Agent（默认值，--target auto；如果未检测到，则使用 Claude Code）、类似 --target claude,codex,gemini 的列表，或 --target all。名称见 harnesses.sh；README 的 Works with 表格会注明经过测试的对象。
技能安装到哪里？	用户级（默认值）或单个项目（--project DIR）。
复制还是链接？	符号链接（默认值，随 git pull 更新）或 --copy（快照）。
场景 Agent 模型，针对带有文件子 Agent 的每个 Agent（claude、opencode、codex、gemini；跳过其余 Agent）？	每个选定的 Agent 分别提问，并提供 Inherit（使用会话模型）选项。Claude Code：Sonnet（默认值：最便宜，也是场景 Agent 的调优目标）· Opus（能力最强；每个并行场景 Agent 都按 Opus 费率计费）· Haiku · Inherit。对应 --claude-model sonnet|opus|haiku|inherit|<id>。其他 Agent：默认使用 Inherit，或输入该 Agent 格式的模型 ID（例如，opencode 使用 provider/model-id，如 anthropic/claude-sonnet-5-5；Codex 和 Gemini 使用纯 ID）。对应 --opencode-model M 或 --agent-model codex=M。
使用其他提供商的模型（DeepSeek 等）？	仅在用户提出要求时使用。先在 Agent 内连接该提供商（OpenCode 使用 /connect；Codex 使用 config.toml 中的 provider；Claude Code 使用 ANTHROPIC_* 变量），然后按上述方式传入其模型 ID。README 的 Models other than Claude 部分介绍了操作步骤和 DeepSeek ID。明确说明此方案尚未经过端到端测试，而且较弱的模型需要更多 QA 轮次，成本也更高。
TTS 模型大小（Full）	1.7B，韵律更自然，约 4.2 GB（默认值）。0.6B，更轻、更快，约 2.3 GB。
语音克隆模型（Full）	不使用（默认值），或使用 --with-clone：再下载一个相同大小的 Base 模型。

下载任何大小达数 GB 的内容前，请先征得确认。对于没有 GPU 的计算机（非 Apple Silicon，也没有 NVIDIA GPU），TTS 每生成一句需要几分钟；建议改为录制配音，或使用占位语音。

3. 安装

./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 会按照每个执行环境各自的格式编写一份副本（Claude 和 OpenCode 使用 Markdown，Codex 使用 TOML，Gemini 使用 Markdown），并采用指定的模型行；如果选择 Inherit，则不设置模型行。没有文件子 Agent 的执行环境不会生成该文件；此时 papercut-build 会自行构建场景，或使用该执行环境自带的并行任务。Skills 仍使用符号链接。之后如需更改模型：./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 链接到每个已选执行环境的 skills 和 agents 文件夹中。Standard 会添加依赖检查、Remotion Agent Skills（对每个已选执行环境运行一次 npx skills add remotion-dev/skills -g -y -a <harness id>，安装到用户级别，因此确认计划时请说明这一点）、包含 numpy、Pillow 和 soundfile 的 Python venv，以及自检渲染。Full 会添加 library/voice/setup_tts.sh：包含 Qwen3-TTS 的语音 venv、ASR 后端（Apple Silicon 上使用 mlx-whisper，其他平台使用 faster-whisper）、模型下载和一行冒烟测试。
• 安装程序会将 PAPERCUT_HOME、PAPERCUT_LIB、PAPERCUT_PY、QWEN_TTS_PY 和 ASR_PY 写入 ~/.config/papercut-explainer/config.env。现有 Skill 文件夹若与此检出版本不同，会备份到 ~/.config/papercut-explainer/backups/（而不是 skills 文件夹中，以免重复加载）；相同的副本（例如通过 npx skills add 安装的副本）则会直接替换。

4. 验证并报告

使用相同的 --project、--skills-dir 或 --target，再次运行 ./install.sh --doctor。报告已安装的内容、每个 Agent 使用的 scene-agent 模型、失败项（安装程序会打印带有组件名称的 needs attention:），以及修复方法。新的 Claude Code、Codex 或 Gemini CLI 会话会加载新链接的 Skills（请重启会话）；opencode 会自动重新加载配置。然后建议用户：“制作一个关于 的 papercut 讲解”，或逐个完成阶段（“为……写一个 hook”、“为这个脚本制作分镜”、“设置语音”）。

故障排除

症状	解决方法
node 版本低于 20，或未安装	安装 Node 20+（nodejs.org、brew install node），然后运行 ./install.sh --mode custom --components deps,verify --yes。
缺少 ffmpeg	运行 brew install ffmpeg 或 apt install ffmpeg。
语音虚拟环境提示：“need Python 3.10-3.12”	Qwen3-TTS 没有适用于较新 Python 版本的 wheel。安装 uv（https://docs.astral.sh/uv/）或运行 brew install [email protected]，然后重新运行 tts 组件。
Hugging Face 下载卡住或失败	重新运行；已完成的文件会保留，脚本会重试 3 次。脚本会设置 HF_HUB_DISABLE_XET=1；手动下载时请自行设置。
首次渲染很慢	Remotion 会下载一次无头 Chrome。音频渲染和 capture.mjs 会使用你自己的 Chrome；如果 Chrome 不在常见位置，请设置 CHROME_PATH。
自检失败	直接运行 library/tools/selftest.sh，查看失败的步骤。
未显示技能	重启 Claude Code、Codex 或 Gemini CLI（opencode 会重新加载）。检查运行环境的文件夹（harnesses.sh；大多数情况下是 ~/.agents/skills），然后运行 ./install.sh --doctor。
opencode：“Configuration is invalid ... tools”	opencode 的 Agent 文件夹中有一份旧版 Claude Agent 文件。重新运行 ./install.sh --target opencode；脚本会写入 opencode 版本。
场景 Agent 成本过高或使用了错误的模型	使用其他模型重新运行技能步骤：./install.sh --mode custom --components skills --claude-model sonnet --yes（或 --opencode-model inherit）。inherit 表示使用会话模型。
从 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 会移除它记录的链接。它会保留 config.env、~/.local/share/papercut-explainer 下的虚拟环境以及 Hugging Face 缓存；如需释放空间，请手动删除这些内容。
Windows	不直接支持。请使用 WSL。

交接

返回将你引导至此处的技能，或返回 papercut-explainer 查看阶段表。状态保存在文件中：config.env 存储库路径，因此其他技能无需再次询问即可解析该路径。