用途
papercut-setup 是围绕 papercut 工具链安装脚本 install.sh 的引导式封装。它用于安装、检查或升级 papercut 工具链:先检查当前环境已安装哪些组件,询问用户希望安装到什么程度,再以非交互方式运行安装脚本并报告结果。其他 papercut 技能在发现缺少组件时,可引导用户使用该技能完成安装。
主要能力
- 预检(Doctor):运行
./install.sh --doctor,检查技能是否安装、配置文件与 PAPERCUT_LIB、node 20+、npm、ffmpeg、python3、Remotion 代理技能、Python 工具(numpy 与 Pillow)、语音相关依赖(qwen_tts 可导入、Hugging Face 缓存中有 CustomVoice 模型)以及库文件是否存在,并以 [ok]、[--]、[!!] 标记状态。 - 安装规模选择:Minimal 仅安装技能与场景构建智能体;Standard 增加依赖检查、Remotion 代理技能、含 numpy/Pillow/soundfile 的 Python 虚拟环境与自测渲染;Full 在 Standard 基础上增加语音虚拟环境(Qwen3-TTS、ASR 后端)、模型下载与冒烟测试;Custom 可自选组件。
- 安装参数处理:支持
--target指定目标智能体(auto/all/具体列表)、--project或--skills-dir指定位置、--copy选择复制而非符号链接、按智能体设置场景模型(--claude-model、--opencode-model、--agent-model NAME=M)、TTS 模型大小(1.7B/0.6B)、--with-clone启用声音克隆等。 - 验证与报告:安装后再次运行 doctor,报告已安装内容、各智能体获得的场景模型、失败项(安装脚本会输出 needs attention 及组件名)与修复方法。
使用方式
需先定位仓库根目录(即 install.sh 所在位置):通过已安装技能文件夹的 readlink 结果推断,或检查各智能体的 skills 文件夹(如 ~/.claude/skills、~/.agents/skills、~/.config/opencode/skills 或项目下同名目录),或读取 ${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 命令需在该根目录下运行。
安装脚本自身的交互提示需要终端,而代理的 shell 工具没有终端,因此需始终传入 --yes 及对应参数;可提示用户自行运行 ./install.sh 使用交互菜单。示例:
./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
Standard 与 Full 模式耗时数分钟(npm install、Remotion 的 Chrome、虚拟环境、模型下载),应在后台运行并检查输出。多 GB 下载前需向用户确认。
安装脚本会将 PAPERCUT_HOME、PAPERCUT_LIB、PAPERCUT_PY、QWEN_TTS_PY、ASR_PY 写入 ~/.config/papercut-explainer/config.env;与本检出不同的已有技能文件夹会备份到 ~/.config/papercut-explainer/backups/。
适用场景
- 其他 papercut 技能发现组件缺失时触发安装或修复。
- 首次配置 papercut 环境,按需选择 Minimal、Standard、Full 或 Custom。
- 排查技能不显示、场景智能体模型成本过高或运行在错误模型、从 Minimal 升级到 Standard、后续补充语音能力等问题。
- 卸载:
./install.sh --uninstall会移除已记录的链接,但保留 config.env、~/.local/share/papercut-explainer 下的虚拟环境与 Hugging Face 缓存,需手动删除以释放空间。
限制
- 需要 bash,支持 macOS 或 Linux;Windows 不直接支持,需使用 WSL。
- 语音虚拟环境要求 Python 3.10–3.12,因为 Qwen3-TTS 没有更新版本 Python 的 wheel。
- 无 GPU 的机器(非 Apple Silicon、无 NVIDIA)上 TTS 生成每行需数分钟,建议改用录音或占位语音。
- 使用其他提供商模型(如 DeepSeek)需先在智能体内连接该提供商,并将模型 id 作为参数传入;文档说明该方式未经端到端测试,较弱模型会增加 QA 轮次。
- 首次渲染较慢,因 Remotion 需下载一次无头 Chrome。