studio-setup

工作室设置

两个问题，两个脚本。我现在可以用什么，由随附的 scripts/doctor.py 回答。如何获取其余内容，由 video-studio setup 回答。两者都要根据眼前这台机器的实际情况作答——把已安装的工具说成缺失，只会浪费用户时间，也会让你之后说的一切都显得可疑。

需要

scripts/doctor.py 随此技能一同提供——它只使用标准库，因此安装技能后，状态报告立即可用。它会依次从当前项目中的 .env、~/.config/video-studio/.env，然后从 shell 中读取密钥。

此处不附带 setup.py：它会安装到引擎自己的 composer 目录中，因此不能作为单独文件使用。它需要运行 pip install 'video-studio-engine @ https://github.com/scrollmark/social-skills/archive/refs/heads/master.tar.gz'，并通过 video-studio setup 启动。如果没有安装，就没有安装计划，也无法进行 auto/system/manual 分类——你仍能看到 doctor 报告的可用状态，但会失去那项能阻止 Agent 安装无人要求的软件包管理器组件的功能，只能重新手动修补缺失项。此技能中的 references/tooling-inventory.md 是工具清单；只有 doctor 知道当前状态。

检查环境

python3 scripts/doctor.py           # 当前可用的内容
python3 scripts/doctor.py --json    # 同上，机器可读格式

Doctor 会按类别报告——公有领域档案、素材库、生成视频、生成图像、生成音频、语音——以及必需的二进制文件。它检查的是密钥是否存在，而不是密钥是否有效；密钥仍可能因额度用尽或模型下架而在调用时遭到拒绝，具体情况由各个脚本报告。

要传授工作流，而不是只作描述，可运行 video-studio tutor --list 查看随附的教程；--step <name> <n> 每次只提供一个步骤，这正是它的设计方式。一次性贴出整个教程，只会变成一份文档，不是课程——没人会读中间部分，你也无法判断哪些内容真正理解了。提供一个步骤，让对方尝试，询问是否成功，然后再继续。--show 是供你规划用的，绝不要直接贴出。请从 getting-started 开始；它会预先说明哪些步骤需要本仓库未附带的 composer。

在提供素材来源选项之前先运行检查。推荐一个最终发现没有对应密钥的来源，既会导致估价错误，也会让推荐本身失实。

修复故障项

video-studio setup                  # 报告 + 精确计划，不会更改任何内容
video-studio setup --yes            # 实际执行可运行的修复
video-studio setup --yes --only composer,voice

每个缺失组件都会分类，分类的意义就在于此：

• auto — 操作范围限定在工具链目录内，可幂等执行，可安全重复运行：安装 composer 的 npm 软件包、预热本地语音模型、将 .env.example 复制为 .env。
• system — 会更改该目录之外的机器环境，例如通过软件包管理器安装 ffmpeg 或 node。这类操作仍可运行，但影响的是别人的电脑。
• manual — 必须由人来操作：获取 API 密钥、启用计费、接受条款、让被沙箱隔离的主机在具备网络访问权限的情况下重启。这类操作绝不能自动运行。对机器无法完成的操作只打印“运行此命令”，会损害用户对其余输出的信任。

每次都要先询问，即使是安全操作也不例外。 不带 --yes 时不会运行任何操作，而 --yes 也会执行系统级安装。用用户能理解的说法说明缺少什么（“渲染器尚未安装”），告诉他们你能否修复，然后征求同意。

如果所有内容都已就绪，就不要多说，继续工作。宣告一切正常只是噪音。

Tier-0 基础要求

有三样东西，缺少任何一样都无法运行：ffmpeg + ffprobe（用于测量每个时长、每次剪辑，以及所有响度和抠像操作）、node 18+（合成器通过它渲染和预览），以及 uv（使用各自固定的依赖运行所有捆绑脚本）。其他一切都能扩展你的能力范围；这三样决定了是否能建立起流水线。

除此之外，最有价值的补充是一个免费的 Pexels 密钥。它能让“帮我找这类视频素材”从碰运气变成常规结果，而且无需花费。完整清单、等级、费用和权利说明见 references/tooling-inventory.md。

许可

此技能可访问的每项外部服务、其费用以及你可以如何使用其输出，都列在本文件旁边的 SERVICES.md 中。发布任何内容前都要先查看。音乐这一项最需要留意：免费后端的再分发权利并不明确，付费后端则提供已获许可的曲库。

showwatcher 不可用，而且第 8 步不再等待它

showwatcher 是一个内部分析器，没有在任何地方发布——没有可安装的软件包，也没有可安装的代码仓库。video-studio setup 会列出它，但不提供安装命令；doctor.py 会报告缺少它，这都是准确的。任何要求“从它自己的仓库安装”的说明都已过时。

第 8 步不依赖它。video-production 技能自带 qc_render 脚本，用于检查渲染结果是否符合 build_props 为其编写的 plan.json——时长、计划本身的一致性、黑屏尾帧、结尾冻结、分辨率和 fps。它仅依赖标准库和 ffmpeg/ffprobe，因此完全无需安装。

捆绑脚本无法做到的是判断画面质量：模糊、字幕重叠、颜色不符合调色板以及文字被裁切，都需要解码帧并使用模型。因此，检查仍分两步进行——运行该脚本，然后提取帧并查看它们，而且要明确说你已经查看过。悄悄跳过的人工检查比没有检查关卡更糟。

反模式

• 照搬文档，而不检查机器。 清单是地图，不代表当前状态。声称某个工具可用前，先运行 doctor。
• 未经询问就安装。 --yes 会修改整个系统。那是他们的电脑，每次都要先征得同意。
• 把手动操作伪装成命令。 没人能用 brew install 安装 API 密钥或开通计费账户。应提供具体链接。
• 以为密钥存在就能正常使用。 doctor 只能检查密钥是否存在。配额、计费问题和已撤下的模型会在调用时失败。
• 假定沙盒可以联网。 每次素材检索和生成调用都需要网络；启动时未启用网络的主机会导致超时，看起来像是服务提供方故障。