owainlewis/ai-reel-editor

编辑一条 Reel

你是编辑。reel CLI 负责机械工作；所有创意决策由你做出。 在规划前，请阅读 docs/STYLE.md 和 docs/RULES.md。RULES.md 中的规则来自实际笔记，优先于此处所有其他内容。

1. 设置

npm run reel -- new <slug> <video> [--broll a.mp4 b.mp4]
npm run reel -- transcribe <slug>

• 从头到尾阅读 projects/<slug>/transcript.txt。修正 transcript.json 中听错的名字（工具、公司、人名）。绝不改变原话内容。
• 查看 checks/frame.jpg 并测量脸部：中心 x、中心 y 和头部高度（从头顶到下巴）占画面的比例。这些数据将填入 face 字段。
• 如果素材下方已有音乐，则将 "music" 设置为 false。

2. 设计前先调研

屏幕上出现的每一个工具、公司、仓库、数字或声明，在展示前都必须与其来源核对。

• 找到主要来源（仓库、文档、公司网站）。阅读它。记录支持讲演者所说内容的事实。
• 如果讲演者所说与来源矛盾，请停止并告知用户。不要试图用图形“修复”它。
• 绝不编造数字、结果、引文或用户界面。图形只能展示讲演者所述内容或来源所示内容。

3. 收集真实视觉素材

优先级顺序（见 STYLE.md）：用户的 B-roll、真实产品或页面、官方标志、然后才是设计的图形。

npm run reel -- capture <slug> <url> --name repo --width 1280 --height 1500
npm run reel -- capture <slug> <url> --name readme --width 520 --selector "article.markdown-body"
npm run reel -- fetch <slug> <logo-url> --name github.svg

• 页面 chrome 和标题区域以 1280 宽度截取。对于段落，以 520 宽度截取，使文本包裹成列，在手机上可读。
• 标志来自品牌自己的网站、仓库或媒体工具包。绝不重新绘制或近似处理。GitHub 组织头像即官方标志。
• 使用“读取”工具查看每张截取，并记录你将框选和突出显示的确切矩形区域。
• 你截取或下载的所有内容都会记录在 assets/ledger.json 中，并注明来源。

B-roll 素材库

Owain 自己的电影感镜头（打字、工作、桌面细节）存放在 broll/ 目录中。它们能让 Reel 感觉像是真实拍摄的，而非生成的。

npm run reel -- index            # 将新文件分割成镜头，裁剪黑边，写入 broll/index.json
npm run reel -- broll typing     # 列出所有片段，最佳匹配优先

• 在 index 之后，查看 broll/sheet.jpg（或 broll/.clips/<id>.jpg），并在 broll/index.json 中填写每个新片段的 description 和 tags。描述你看到的内容，而非其含义。
• 使用 { "kind": "video", "src": "broll:<id>" } 格式的片段。validate 会将其复制到项目中。
• 将 B-roll 放在人情味或抽象表述上（例如“如果你正在用 AI 构建东西”、“它在本地运行”）。将截取和标志用于事实性声明。B-roll 不能作为证据。
• 单个镜头的时长不能超过其对应片段的时长；如果超过，validate 会报错。每个片段在每条 Reel 中只使用一次。

4. 选择格式、规划故事、再定镜头

首先设置 format（见 docs/STYLE.md）：

• 工具发布（新仓库、发布、功能或帖子）：react。将其规划为对源码的逐项解读：每个声明都需有截取，并在讲演者所述内容上添加高亮。仅在分屏内部使用 B-roll。
• 工作原理 或 我的设置：mixed。

然后设置 header 为吸引眼球的短标题（它将成为第一帧屏幕上的文本），并规划章节：在每个章节开始的镜头上设置新的 header。选择 split：当带有文本的截取主导 Reel 时使用 inset，当讲演者表述占主导时使用 half。

编写 projects/<slug>/edit.json（模式定义见 src/schema.ts）。首先，在你的脑海中或通过一个 note 决定：

• 钩子（0 到 3 秒）： 观众在第一帧看到什么而留下。优先展示产品运行中的画面或提及真实事物。
• 证据： 一个证明声明真实性的镜头（仓库、源代码行、页面上的数字）。
• 机制： 工作原理，以图示或来源自身的文字高亮形式展示。
• 收益： 观众现在可以做什么。以讲演者的脸部结束。

然后是镜头。每个镜头从讲演者所说的某个短语开始（at），按顺序排列。经验法则：

• 一个镜头一个想法。平均时长 1.2 到 1.6 秒。除非内部有揭示值得更长，否则不超过 2.8 秒。
• 每个列表项、步骤和标志都有自己的 at，以便与对应文字对齐。
• 混合布局：证据用分屏，讲演者说服力满格用全屏，强调和最后一行用放大，最重要的单个视觉用媒体片，B-roll 铺满全屏用切出。
• 图形展示示例或关系。它不重复字幕。
• accents：整条 Reel 中四到六个最关键的词，承载含义。

截取画面取景

对于 image 类型的视觉元素，from 和 to 是矩形 [x, y, w, h]，使用 0 到 1 的图像坐标系。矩形填满面板，摄像机从一位置平滑移动到另一位置。

• 结尾要紧凑。当页面文本在手机上可能过小时，validate 会发出警告。
• 使用带 at 的 highlight 来将标记扫过正在被讲演的具体文字。添加 label 作为标注标签。
• 矩形是必须保持可见的区域；摄像机将其扩展到面板形状，周围显示页面内容。你不需要匹配面板的比例。

5. 渲染前检查

npm run reel -- validate <slug>   # 解析时间轴，打印镜头表格，检查内部规则
npm run reel -- stills <slug>     # 每个镜头一帧 -> checks/stills.jpg

读取 checks/stills.jpg。对每个镜头问自己：手机尺寸下能看清吗？它填满面板了吗？画面是否遮挡了嘴巴？它展示了新的内容吗？修复并重复，直到每个镜头都通过。

6. 渲染并验证

npm run reel -- render <slug>     # 混音，渲染至 projects/<slug>/renders/final.mp4
npm run reel -- check <slug>      # 剪切条、起始帧、响度、文字检查

读取 checks/opening.jpg（前 2.5 秒）和 checks/cuts.jpg（每个剪切点两侧的帧）。检查是否存在单帧闪烁、风格错误的字幕、空面板。响度应在 -14 LUFS，真峰值不超过 -1 dBTP。

将 MP4 发送给用户。明确指出你检查了什么，以及你未能检查什么（例如你无法听到混音效果，请如实告知）。

7. 将备注转化为规则

当用户对草稿给出备注时：

1. 修改编辑内容。
2. 决定修复方案归属于何处：docs/RULES.md 中的一条规则、tools/ 中的一个检查、或 src/ 中一个组件的更改。当问题可以通过机械方式检测或预防时，优先选择检查或代码更改，而非书面规则。
3. 在 docs/RULES.md 的日志中添加一行：备注内容（使用用户的原话）以及更改了什么。

同一备注不应出现两次。