用途
Kortix Presentations 用于构建、编辑、演示或录制 Kortix 的演示文稿（deck）与影片（film）。它明确不处理传统幻灯片文件：不接受 .pptx、Keynote、Google Slides 或 Markdown 形式的 slides 文件，这类产出会被直接拒绝。
主要能力
- 演示即路由：每份 deck 位于 apps/web 下 /presentations/<slug>，是一个 Next.js 路由，风格与营销站点一致，支持键盘操作，并为屏幕录制而设计。
- 单一注册文件：在 registry.ts 的 DECKS 中加入一行即可注册新 deck；路由、索引卡片、幻灯片与构建步数、时长估算、页面元数据全部自动派生。
- 键盘演示引擎：打开 /presentations 选择后按 F。→ / Space / J 前进一个构建步或下一张；← / K 回退一步或返回上一张的完整构建状态；Home / End 首尾；1–9 跳转；G / Esc 打开总览网格；F 全屏；N 显示讲者备注。
- 构建步（Builds）：SlideDef 的 steps 字段表示额外构建步，总按键数为 steps + 1。元素从一开始就在 DOM 中并以低透明度存在，逐步提升不透明度，避免每次按键引发布局回流。engine/diagram.tsx 通过内部 Reveal 处理这一逻辑；唯一的例外是“移动数据包”这类真正瞬态的元素。
- 讲者备注：notes 为口播脚本，可传数组让每个构建步对应一句；抽屉跟随当前步，备注不会渲染到舞台上，录制画面保持干净。
- 图表组件：engine/diagram.tsx 提供 Stage、Box、Chip、Link、Wall、Row；已交付的机器图包括 IsolationDiagram、BrokerDiagram、ChangeRequestDiagram、PrincipalDiagram、LedgerDiagram。标题不随步骤移动，图注承载随步变化的句子。
- 影片渲染：影片位于 /presentations/film/<slug>，每帧是帧号的纯函数，同一 React 树既能实时播放，也能通过无头 Chrome 与 ffmpeg 渲染为 MP4，配乐与音效锁定在小节网格（60 fps、120 BPM、一小节 120 帧）。
使用方式
添加一份 deck 只需两处编辑：
- 在 decks/<slug>.tsx 中编写客户端组件并导出 useSlides()，返回 SlideDef 数组（id、label、node、steps、notes）。
- 在 registry.ts 的 DECKS 中加入一行，包含 slug、title、description、kind、tags 与 useSlides。
影片相关命令（资料原文）：
open http://localhost:<web>/presentations/film/launch # 实时、可拖动
open "http://localhost:<web>/presentations/film/launch?frame=1800" # 单帧
bun apps/web/scripts/film/render.ts launch --url http://localhost:<web> # 1080p60 MP4
bun apps/web/scripts/film/render.ts launch --url http://localhost:<web> --audio-only
MP4 输出到被 gitignore 的 output/film/<slug>/。渲染期间不要编辑影片文件，热重载会进入渲染页面。
录制流程：打开 deck、按 F、录制标签页；先用 N → Full script 读脚本，再关闭抽屉。嵌入产品截图的 deck 建议用浅色主题。录制前重新加载页面，因为开发模式下累积的 keydown 监听会让一次按键跳多步。
结构纪律
- 说有几个部分，就恰好有几个部分。安全 deck 承诺“四个答案”却写了七章，重建为四章并在每张章节页加 Spine 后效果显著提升。
- 章节名写成 deck 文件顶部的 const，并通过 <Spine chapters={CHAPTERS} active={n} /> 渲染。
- 每章一张图，最多一张辅助幻灯片；第五个想法属于营销页而非 deck。
- 章节页只放标题和机器图，不放导语段落；构建步页面上的第二段文字会与旁白竞争。
- 每个构建步约 20 秒旁白，25–30 个构建步大致对应 8–10 分钟视频。
文案准确性
文案必须从营销内容模块（apps/web/src/features/marketing/*/content.ts）导入，不得重新录入。这些文件的头部带有准确性门槛：经过已发布代码验证的主张，以及不得“恢复”的更正。常设陷阱（microVM、密钥范围、“密钥从不位于沙箱中”、谁能合并、认证、许可证名称）记录在 claims.md 第 3 节及其引用的代码中；不在该文件中的主张不得使用。语气与禁用短语见 voice-and-tone.md 第 5.8 节（deck notes）。
视觉语言
视觉取值、字体、颜色与 deck 栏宽定义在 layout.md、typography.md 与 color.md。优先用 engine/parts.tsx 组合（SectionHead、Panel、RowList、KortixAsterisk 项目符号、Shot 中的真实产品截图），而非自造界面。配色始终跟随主题：使用语义 token 与 kortix-* 强调色，禁止强制调色板或 dark: hack。颜色为单色加 kortix-* 仅用于结论（绿=允许/合并，橙=暂扣，红=阻止/拒绝），不得使用 Tailwind 原始色板。幻灯片为一屏且不滚动，截图用 vh 限制高度，例如：
<Shot src="/media/…" alt="…" imgClassName="max-h-[48vh] object-cover object-top" />
object-top 保留屏幕顶部（产品所在处），裁掉空白底部而非加黑边。子组件必须在模块作用域声明，不得在图表渲染内定义，否则每一步都是新类型，React 会重新挂载并重启动画。
交付前 QA
pnpm --filter Kortix-Computer-Frontend typecheck # tsgo；src/app/[locale]/presentations 必须干净
cd apps/web && npx eslint src/app/[locale]/presentations # 0 errors
不要在 apps/web 直接运行 tsc --noEmit：2026-10-21 曾运行 817 秒、占用 3.18 GB 且未完成。应用其他位置的错误属基线（与 origin/dev 比较），不属于本次改动；presentations 下不得出现任何错误。随后在浏览器（chrome-devtools MCP）中验证：按 G 查看总览并在一张截图里确认所有幻灯片均已渲染；手动推进至少一张构建步幻灯片，确认每次按键恰好增加一个阶段且布局不跳动；检查浅色与深色两种主题；控制台干净。每次检查前重新加载页面。
适用场景与限制
适用于 Kortix 内部的产品演示、安全/平台/销售等主题演讲，以及发布视频和产品影片的制作。限制包括：依赖 Kortix 仓库的 apps/web 结构与营销内容模块；必须先加载 kortix-brand；不产出通用幻灯片文件格式；影片渲染依赖无头 Chrome 与 ffmpeg；deck 为链接分享且 noindex，不放在登录之后。