工作室初始化(课程步骤 02)
创建一个能够渲染、播放并查看自身帧的影片项目。聊天应用可以编写动画;只有拥有 shell 权限的代理才能关闭渲染、查看、修复循环。这个循环是“还行”的首次尝试与值得发布的影片之间的区别。
请求参数(可以为空),仅显示一次:
1. 选择目录和设置
- 目录:第一个参数;如果工作目录为空则为
.;否则询问(默认为./<标题的 slug>)。切勿在插件目录内搭建项目。 - 请求中的设置:标题、时长、格式、帧率、bpm、循环、品牌 URL。其余设置保持模板默认值(
studio.json:12 秒、60 fps、4 子帧、120 BPM、9x16主格式)。
2. 搭建项目
node "${CLAUDE_SKILL_DIR}/scripts/init.mjs" <dir> --title "<Title>" [--duration S] [--fps N] [--bpm N] [--formats a,b] [--loop] [--brand-url URL] [--install] [--json]
| 标志 | 作用 |
|---|---|
<dir> | 目标目录;如果不存在则创建 |
--title T | studio.json 中的标题和交付文件的 slug |
--duration S, --fps N, --bpm N | 时间设置 |
--formats a,b | 9x16、1x1、16x9、4x5 的子集(或 all);除非列表中不包含,否则 primaryFormat 保持不变 |
--loop | 无缝循环影片(UI 变形) |
--brand-url URL | 将产品 URL 存储在 brand.url 中。在写入任何内容之前,会移除 user:password@ 以及看似秘密的参数(query、;matrix、fragment:token、key、secret、password、auth、sig、session、code……);stderr 会输出被移除的内容,--json 会在 redacted 中列出它们。仍请传入一个普通的公共 URL:作为裸路径段(/reset/<token>)的秘密无法被识别。普通 URL 会按原样存储 |
--install | 在新项目中运行 npm install(在 Windows 上处理 npm.cmd) |
--force | 将旧项目刷新到当前模板(见下表) |
--json | 在标准输出上打印一行 JSON 结果 |
如果目标非空目录已存在,则会进行合并:仅添加缺失的文件,并列出跳过的文件。向用户报告跳过的列表;切勿删除他们的文件。
对已有项目使用 --force(通过 init.mjs 检查):
| 路径 | 使用 --force |
|---|---|
studio.json, film/**, docs/**, assets/fonts/fonts.json | 保留并列为 kept;缺失的文件仍会被创建。诸如 --bpm 等标志仍会修补 studio.json |
package.json | 合并,绝不替换:设置 type: module,添加 private、engines 以及项目缺失的每个模板脚本或依赖项。命令不同的模板脚本会重置为模板命令(init 会打印每条记录为 was ..., now ...,并在 packageReset 中返回它们)。依赖版本从不更改,包括模板依赖项:现有范围保持不变,无论是更新、更旧还是固定版本。名称、版本、其他脚本和其他字段保持不变 |
.gitignore | 合并:在 # motion-studio 下添加缺失的模板行,不移除任何内容 |
其他所有内容(CLAUDE.md, lib/**, tools/**, prompts/**, index.html, .env.example, 捆绑的字体) | 覆盖并列为 overwritten。对这些文件的本地编辑将丢失:请先提交或复制 |
| 你自己的其他文件 | 不受影响 |
未使用 --force 时,package.json 和 .gitignore 的合并方式相同,但命令不同的脚本会保留你的命令。Init 会列出每个与模板不同的脚本和依赖版本,并提示 kept your package.json values, which differ from the template(在 --json 结果中的 packageKept):那些 npm run 名称运行你的命令,而 --force 会重置模板脚本(绝不重置依赖版本)。如果 scripts、devDependencies 或 optionalDependencies 部分不是对象,则保持原样并发出警告。由于 docs/** 被保留,较新的模板文档永远不会到达现有项目:更新后请手动与插件的 template/docs/ 进行比较。
3. 安装、浏览器、诊断
- 未使用
--install时,在项目内运行npm install。playwright是唯一必需的依赖项;ffmpeg-static是可选的,可能在代理后面下载失败。 - 浏览器(
npm run setup:browser与npx命令相同):- Windows:运行
npx playwright install chromium-headless-shell(约 115 MB 下载,270 MB 磁盘空间)。studio.json中的browser: "auto"仅启动该捆绑的无头 shell,绝不启动已安装的 Chrome 或 Edge。原因:使用新配置文件(每次工具运行时)启动已安装的 Chrome 或 Edge 会使 Chrome 测试 Windows 账户的空密码,这算作一次登录失败。实测笔记本电脑在 10 分钟内 10 次登录失败会锁定账户,并在 24 小时内记录了 464 次。除非用户要求并接受风险,否则不要将browser切换为chrome或msedge,也不要将MOTION_CHROME_PATH设置为chrome.exe或msedge.exe:每次启动都会打印警告,10 分钟内的第 4 次启动会被拒绝,3 次可以通过(启动保护)。Shell 未签名,因此实时防病毒软件可能使每次工具运行慢 15 到 25 秒(已测量):告知用户一次;对%LOCALAPPDATA%\ms-playwright添加防病毒排除项由用户或其 IT 部门决定。 - macOS 和 Linux:
auto会先尝试已安装的 Chrome,然后是 Edge,最后是捆绑的浏览器,且无警告。如果都未安装,运行npx playwright install chromium-headless-shell(Linux:npx playwright install --with-deps chromium-headless-shell),或者将MOTION_CHROME_PATH设置为 Chromium 系列的可执行文件。
- Windows:运行
npm run doctor。在交付出前修复每个 FAIL 行,在 Windows 上还需修复 WARN 浏览器行(选择了已安装的 Chrome 或 Edge:清除它并安装无头 shell);每个操作系统的修复方法见 references/troubleshooting.md。带有 librosa 的 Python 是可选的(JS 节拍引擎已覆盖)。仅路线 B 工具需要 Node 22+。- 验证:运行
npm run stills,然后打开out/review/9x16/contact.png(长影片会分页:contact.png是第 1 页,然后是contact-2.png……每页高度不超过 1800 px;打开每一页)并查看。附带的 12 秒演示必须在 0 秒处显示一个合成帧,并且在每个强拍上都有变化。npm run preview打开实时预览(空格键播放/暂停,箭头键逐帧移动,F 键循环切换格式,G 键安全区域参考线)。
4. 向用户解释项目
用几行总结,然后指向参考文档:
- 布局和谁编辑什么:references/project-layout.md
- 所有命令:references/commands.md
- 所有
lib/签名和默认值:新项目中的docs/API.md(完整参考是插件仓库中的docs/ARCHITECTURE.md) - 行为准则存于项目的
CLAUDE.md中,Claude Code 每次运行时都会读取。
如果 init 打印了一行 ★ 星号线(--json 结果中的 starHint;每台机器仅在新项目的首次运行时出现),则用这一行原文结束你的总结。切勿为用户 star 仓库或运行 gh。
| 命令 | 功能 |
|---|---|
npm run preview | 在浏览器中实时预览 |
npm run stills | 每个节拍生成一张静帧联系表 |
npm run critique | 联系表、胶片条、手机测试、指标、评审日志块 |
npm run gate | 评审门槛:3 轮,所有维度 >= 8,无 P0 |
npm run render:final | 每种格式,最终质量(强制通过门槛) |
npm run sfx / npm run mix | 合成提示音效 / 混音至 -14 LUFS 并封装 |
npm run deliver | 交付检查并打包 out/deliver/ 目录 |
npm run build | 音效缺失则生成,音效、最终渲染、混音、交付 |
5. 工作量和路线
| 工作 | 工作量 | 通过以下设置 |
|---|---|---|
| 小修复、重新渲染 | 中等 | /effort medium |
| 一部新影片 | 超高 | /effort xhigh(motion-reel 技能会为你设置) |
| 旗舰产品的开头 3 秒 | 最大 | /effort max |
/model 在选择 Opus 5.5 时也提供工作量选择。路线 A(此引擎)为默认。仅当用户明确指定时才使用 Remotion 或 HyperFrames;/motion-studio:seek-engine 负责交接,包括 Remotion 许可门槛。
6. 密钥
仅在需要密钥时复制 .env.example 到 .env(语音:ELEVENLABS_API_KEY;路线 C 图片/视频:FAL_KEY)。让用户自行将值粘贴到 .env 中。在提示和日志中仅提及变量名。.env 已在项目的 .gitignore 中。
7. 可选伴侣工具
仅在相关时提及。安装命令和注意事项:references/companions.md。
| 伴侣工具 | 用途 | 注意 |
|---|---|---|
| claude-animation (buildwithhanif) | 手绘、笔刷、故事书风格 | MIT;独立的 Node Canvas 渲染器 |
| HyperFrames (heygen-com) | HTML + GSAP 合成 | Apache-2.0;需要 Node 22+ |
| Remotion | React 系列和模板 | 对于超过 3 名员工的企业需要公司许可 |
下一步:使用 /motion-studio:showreel 测试引擎,或使用 /motion-studio:motion-reel 制作一部真正的影片。