NodeKit Present
将已验证的开发制品转化为活的演示文稿。将幻灯片视为变更记录的投影，而非独立的主张来源。
在创建或更新演示文稿制品之前，请阅读变更故事契约。
工作流程
- 对变更进行分级。忽略琐碎工作的幻灯片组；针对小修小补使用变更卡片，针对重大功能使用 3-5 页的迷你幻灯片组，针对发布或黑客松使用完整的幻灯片组加附录。
- 创建或更新
changes/<change-id>/change.yaml。记录受众、问题、先前状态、决策、备选方案、受影响的系统、用户工作流程、证据需求、局限性和演示层级。 - 在工作进行时捕获证据：基线状态和变更后的截图、确切的提交记录、部署身份、测试、基准测试、追踪记录、制品、导出结果以及已知故障。保留原始凭证。
- 构建证据索引。为每一个实质性主张赋予一个状态和证据 ID。明确区分已计划、推断得出、用户断言和已测量的主张。
- 在渲染前规划每张幻灯片。说明其任务、观众问题、要点、叙事角色、主要视觉元素、证据 ID、密度预算和演讲者备注目标。
- 按以下顺序使用已安装的 NodeSlide 传输方式：仓库原生适配器、NodeSlide CLI、NodeSlide MCP 或包 API。首先检查能力，切勿假设托管写入、导出或审批是可用的。
- 针对钉死的幻灯片版本提出变更。通过宿主策略进行验证、比较和应用；切勿为了方便而绕过 NodeSlide 的治理机制。
- 对照当前提交或部署验证每一个实质性主张。刷新过时的截图和指标。让局限性保持可见。
- 导出请求的可编辑格式，然后重新打开它。验证渲染的幻灯片、演讲者备注、源代码绑定以及任何 PPTX 的往返过程。
- 从相同的变更故事和证据索引中衍生出演示脚本、README 部分、发布说明和提交文案。
演示剪辑是渲染的导览，而非屏幕录制
本节之所以存在，是因为一个实际发生过的失败案例。一次生产部署通过了 11/11 的验证，使用的是录制剪辑，但该剪辑是一个原始的 Playwright 捕获：没有焦点框定、没有说明文字、没有可见的流式处理或工具调用、没有幻灯片。而上述每一项的现有工具都已经存在，并且本技能没有提及其中任何一个，所以它们被糟糕地手动拼凑，而没有得到良好的驱动。
FeatureClipStudio (feature-walkthrough-gif/) 是捕获到渲染的管道，它涵盖了原始捕获永远缺乏的四件事：
| 原始捕获缺乏的内容 | 该管道提供的内容 |
|---|---|
| 聚焦重点 | 自动缩放聚焦镜头，带动画光标滑向每次点击并带有涟漪效果 |
| 解释说明 | 针对每个状态的步骤说明文字 |
| 工作过程可见 | 实时加载和流式播放捕获内容——旋转器在旋转，结果在到达 |
| 当主张依赖于内部细节时，展示内部细节 | 原始 JSON/状态证据面板 |
npm run capture # Playwright 驱动实时流程并记录每一个 UI 状态
npm run studio # 把捕获的状态组织成故事板
npm run render # Remotion 渲染导览
npm run judge # Gemini 观看渲染结果并评分
judge-video.mjs 是关卡，也是在宣布剪辑完成之前需要运行的一个步骤。它根据一个反英雄镜头评分准则观看渲染的 MP4，并以 P0/P1/P2 的等级返回带时间戳的缺陷——P0 会阻止发布。其自身的头部声明了要点：最终剪辑不再仅仅是人类眼睛检查的阶段。评判 MP4 而非 GIF；GIF 不是受支持的视频 MIME 类型。
对于评委已经通过的 P2 缺陷，不要进入重新渲染的抛光循环。
两个轴，而第二个轴才是经常失败的那个
judge-video.mjs 针对 CRAFT（光标真实感、节奏、清晰度、动效）进行评分，并单独针对 COMPREHENSION（理解度）评分，后者是观众必须实际带走的十项内容：
人物 · 目的 · 用例 · 功能清晰度 · 完整交互
响应性 · 流程 · 结果 · 非专家理解度 · 迁移性
它们是正交的，一个剪辑可能制作精良但不可理解。在一个真实的渲染上测量：工艺评分为 publish，而理解度在十项上全部得分为 1——没有一项缺失，也没有一项明确，所有内容都仅仅是暗示——评委指出 0:06 是丢失非专家观众的时刻（"层级架构概念和终端日志输出"）。
non_expert_sense（非专家理解度）是妈妈测试，它会独立地阻止发布，无论总分如何。一个通过了自己评委的、而评委认为该视频对圈外人士来说难以理解的视频，不能算作一个有效的关卡。所有十项的均匀得分会被标记出来，而不是取平均值，因为“全部得 1 分”意味着所有内容都是暗示而非陈述，这是一个发现，而非中庸的及格。
循环是默认操作，而非最终检查：渲染、评审、阅读评委指出的缺失内容、重新剪辑、再次评审。对一个视频的三次剪辑将其从 10/20 分提升到了 13/20 分，更重要的是，它让制作者意识到故事是围绕着一个错误时刻构建的——这是任何数量的自我审查都无法发现的事情。当理解度指标通过且剩余缺陷仅为 P2 时停止。
NodeSlide 用于幻灯片组，NodeVideo 用于帧级证据——一个作为运行中产品呈现的帧必须绑定到其来源的部署，而 presentedAs 正是使这一点可被检查的属性。
参考视频的来源
Mobbin 适用于 UI，因为它是一个你可以观察和引用但从不复制的语料库。视频需要同样的纪律，并分为两种类型，它们是不可互换的：
流程参考——一个真实产品实际执行的操作，一步步来。 Page Flows 是直接的类比：记录的用户旅程而非屏幕截图，20000+ 个应用，按任务组织——注册、升级、取消——包括同意对话框、字段验证、空状态和成功页面。它自身的框架是从另一面阐述的反英雄镜头规则：Mobbin 向你展示目的地，Page Flows 向你展示旅程。ScreensDesign 涵盖了引导流程和付费墙，并附带了收入信号。使用这些来回答“这类真实流程包含哪些状态，我又跳过了哪些？”
工艺参考——一部发布视频是如何构建的。从 YouTube 开始。 评委可以直接读取 YouTube URL ——已确认：Gemini 仅通过 URL 就观看并描述了一个 YouTube 视频的开场几秒和时长，无需下载。因此，一个参考是被引用的，从不被复制，这完全解决了许可问题，并使定位符变为 URL 加上时间戳：
代理自行构建其语料库，而不是等待被提供。yt-dlp 搜索 YouTube 并读取元数据；不下载任何内容，Gemini 观看 URL：
node find-references.mjs "Raycast 产品演示" "Linear 产品演示" # 搜索、分类、观察
node judge-video.mjs out/demo.mp4 # 自动使用语料库
node judge-video.mjs out/demo.mp4 --no-reference # 选择退出
find-references.mjs 在花费 tokens 之前进行分类：默认拒绝任何超过 180 秒的内容，因为其格式和成本都不适合简短的导览，并会打印原因。在一次真实运行中测量——一个 39 秒的第一方演示花费了 3.9k 的提示 tokens，而一个 18 分钟的则花费了 102k。然后它写入 references/video/<id>.json：带时间戳的原子事实（0:07 动效——按键在按下时变为绿色）、吸引点（hookSeconds）、展示的状态（statesShown）、可借鉴之处（whatToSteal）和不可借鉴之处（whatNotToSteal），以及一个用于无法确定的内容的 notRun 列表。事实，而非形容词——事实可以用来评估候选视频，而形容词不能。
评分结果会获得一个 reference 块——singleMoment（单一时刻）, statePacing（状态节奏）, motionPurpose（动效目的）, whatToSteal（可借鉴之处）, 和 whatNotToSteal（不可借鉴之处）——并且对参考视频的每一个主张都需要有时间戳。每一个值得研究的优秀产品发布视频都已经在 YouTube 上，并且是主要来源；下面列出的精选库是其上的一个发现层，用于寻找候选视频，而非用于观看它们。
成本是真实的：一个 18 分钟的参考视频测量消耗了 102k 的提示 tokens。优先选择 30-90 秒的剪辑，最多传递两到三个参考视频。
FlowJam 提供手工精选的 SaaS 和产品发布视频； Tella 的库 和 Vidico 的分析 发布带有推理过程的例子。使用这些来学习节奏、单一时刻，以及动效在何时起作用、何时仅仅装饰。
不要将任何一种类型作为散文粘贴到评分准则中。像 Mobbin 观察记录那样记录它们：一个原子事实，带有一个对于视频来说是时间戳的 locatorDescription，引用到源 URL。主张应该是“在 0:12 处，加载状态持续了 1.4 秒之后才显示结果”，而不是“他们的节奏很好”。从带时间戳的观察中得出的规则是可以评分的；形容词则不能。
许可：观察和注明出处，绝不重新托管。观察模式中的 licenceMode 是一个枚举的单一值，这是有意的——将其扩展到新的源类别需要经过许可审查和细致的模式编辑，而不是一个简单的字符串。
发布视频是被导演出来的，然后被渲染——发布视频契约
以上所有内容都是在评判一个已经存在的剪辑。一个发布视频的失败发生得更早：它围绕错误的时刻构建，或者在发布后交付，而评委循环无法挽回这两点。在 Motion Studio 现场研究（面向 YC 级别初创公司的发布视频）：他们的流程是“导演 → 初稿 → 修改 → 交付”，并且“人类导演做出每一个品味决策”。这个顺序就是产品本身。nodekit launch-video 将其作为一个可以拒绝的契约来执行，因此驱动的编码代理会逐步执行各个阶段，而不是直接跳到 npm run render：
nodekit launch-video declare --application <slug> --out launch-video.json
# 1 简报 填充产品、故事（利益相关者的原话）、受众、发布日期、渠道
# 2 导演 单一时刻、有序节拍、通过 find-references.mjs 获取的参考资料（带时间戳的
# 事实，而非形容词）、目标时长（秒）≤ 180——然后需要**人类批准**
# 3 草稿 捕获 → 故事板 → 渲染（FeatureClipStudio 或 NodeVideo），对 MP4 运行
# judge-video.mjs，记录循环：剪辑、评委评分、人工笔记、处置方式
# 4 交付 最终剪辑 + 评委收据 + 人类批准，在发布日期前已交付（deliveredAt）
nodekit launch-video check --contract launch-video.json # 在每个阶段出口拒绝不符合契约的操作
每个拒绝的原因：
- 在方向获批之前的草稿——第一个剪辑要对齐方向，而不是发现方向；在方向反馈回来之前做出的渲染是修改的账单。
- 没有时间戳的参考主张——“他们的节奏很好”无法评分；“在 0:12 处加载状态持续了 1.4 秒”则可以。
- 最终循环未通过
non_expert_sense——妈妈测试可以单独阻止交付，与上述评委循环的规则相同；契约将其作为阶段退出条件而非建议。 deliveredAt在launchDate之后——在发布活动之后交付的发布视频是事后回顾。- 交付时没有人类批准——评委仅提供建议；品味决策由人做出。
评委循环仍然是第 3 阶段的内循环，完全如上所述。契约增加了循环本身从未持有的东西：按顺序的阶段、在两个品味关卡处的人类，以及日期。
并行通道
对于大型实现，将演示工作作为构建和 QA 旁边的一个主要读取通道来运行。尽早起草问题和架构；只使用来自后期关卡的经验证证据替换占位符。仅在以下情况下阻止发布：存在未经证实的主张、缺少所需的证明、证据过时或导出功能损坏。
完成语言
- 当幻灯片计划存在时，说
drafted（已起草）。 - 当每一个实质性主张都解析为当前证据时，说
evidence-bound（已绑定证据）。 - 仅当请求的输出成功重新打开后，说
export-verified（已验证导出）。 - 仅当应用程序证明和演示证明都通过时，说
release-ready（准备发布）。
不要将绿色的单元测试变成生产环境的主张，不要将 HTTP 200 变成浏览器的证明，也不要将建议性的模型判断变成权威性的裁定。