先确认是字体替换，还是别的变化
| 观察 | 下一步 |
|---|---|
| 字形骨架、笔画或数字样式明显不同 | 查旧机实际字体文件、新机可读文件与内部 family；这是字体替换的主要线索。 |
| 字形相同，整行宽度或换行不同 | 继续核字体版本、缺字回退和渲染环境；先保留现有字号与字幕带。 |
| 字形相同，整体位置或比例改变 | 核项目画布、PlayRes、边距与成片尺寸；画布不一致属于另一条故障。 |
| 只有少数字符换了样式 | 查主字体是否覆盖这些字符，以及渲染时是否对它们采用了回退字体。 |
先截取旧版与新版中同一句字幕，记录机器、项目版本、画布、模板 ID、字体文件与 family。不要看到位置变化就立即改字号；模板画布不匹配会让位置和比例改变，即使字体文件完全相同。也不要只凭操作系统字体菜单里的显示名判断文件身份，项目需要能够指向真实文件。
建立“文件—family—模板—项目”链条
| 链条节点 | 必须写清的内容 |
|---|---|
| 字体文件 | 项目可访问的真实 .ttf、.otf 或 .ttc 文件；本流程先使用登记记录中的第一份真实字体文件。 |
| 内部 family | 字幕样式用于解析字形的 family 名称；从真实字体信息核对后登记，避免把下载文件名当成 family。 |
| 字体资源 | 稳定资源 ID、文件路径与 family；供模板引用。 |
| 字幕模板 | 通过 font resource <font-id> 引用字体资源，并保留画布、字号、描边、阴影、行数和字幕带。 |
| 项目绑定 | recap_project.json 把 subtitle_style 指向已采用的模板版本；项目开始前解析资源与模板。 |
在所引实现中，绑定会把字体资源的第一份文件下发为 SUBTITLE_FONT_FILE，把资源记录里的 font.family 下发为 SUBTITLE_FONT_NAME。烧录 ASS 字幕时，渲染器把该文件所在目录交给 libass；画面文字使用同一字体文件路径。文件解决“从哪里加载”，family 解决“样式请求哪个字体家族”，两个值要彼此对应。
迁移时先分两条路径。已采用模板原本就引用正确字体资源时，恢复该资源对应的旧项目真实文件与已核 family，模板 ID、版本和参数都不变。若旧模板只有 family、引用错误资源，或必须换到另一字体资源，则复制非字体参数建立新版本，修改字体引用，经过创作者采用后再绑定；旧版本继续作为基准。
这个链条减少对新电脑系统字体安装状态的依赖。它不自动核对字体文件内容是否与旧机完全相同，也不选择 .ttc 内的多个面；当前任务若涉及字体集合，先确认项目所需字形能由登记的首个真实文件和 family 正确解析。
原创纸面案例：把烘焙记录短片迁移到新电脑
下面的《烘焙曲线笔记》是本文原创纸面迁移单。项目名、字幕、资源 ID 与路径均为教学占位，没有创建或读取字体文件，没有在两台机器上渲染，也没有完成视觉对比。真实修复必须替换为实际项目记录和真实输出。
旧版短片用字幕模板 roast-log-caption@v3 标注一批咖啡豆的烘焙节点。该模板已经引用字体资源 roast-log-sans。新电脑打开工程后，“一爆开始 08:42”明显变宽，186°C 的数字与度数符号也换了样式。纸面核对单这样写：
| 项目记录 | 本例填写 |
|---|---|
| 已有字体资源 | roast-log-sans；旧版 roast-log-caption@v3 已经引用它 |
| 设计文件 | resources/font/roast-log-sans/RoastLogSans-Regular.otf |
| 待核内部 family | Roast Log Sans；需从旧项目真实字体信息确认，不能由文件名猜定 |
| 现有字幕模板 | roast-log-caption@v3；画布 1920×1080；字体引用、字号、描边、阴影、行数与字幕带都保持不变 |
| 项目绑定 | bindings.subtitle_style = roast-log-caption@v3 |
| 代表字幕 | 一爆开始 08:42；入豆温度 186°C；Washed Caturra |
| 对比输出 | 旧机 v3 基准帧与新机恢复文件后的 v3 帧；同画布、同非字体参数、同字幕、同时间点 |
本例选择“现有引用正确”路径：从旧项目确认 roast-log-sans 实际使用的文件和内部 family，把同一份可读文件恢复到新机项目可访问位置，并保留 roast-log-caption@v3 的记录与绑定。新机完成真实渲染后，逐条比较中文笔画、英文字母、数字、冒号与度数符号、行宽和缺字。若数字恢复而 ° 仍换字形，继续查该字符的覆盖与回退；不为一个缺字重做整套字幕布局。
若真实核对发现 v3 从未引用 roast-log-sans，就停止这条恢复路径。复制 v3 的画布、字号、描边、阴影、行数与字幕带，建立 roast-log-caption@v4，只把字体项改为正确资源，完成采用后再绑定。此时对比的是旧机 v3 基准与新机 v4 候选，所有非字体参数保持相同，不再声称模板版本相同。
本例中的 1920×1080 只说明模板与对比必须使用同一画布。它不是推荐尺寸，也没有证明任何字体能在该画布上通过审片。
用代表字幕做真实渲染对比
先选少量能暴露差异的真实字幕：一条常规中文、一条含项目关键生僻字、一条含数字与标点、一条含英文或品牌写法。固定字幕文本、画布、时间点、底图以及所有非字体参数，分别取得旧机基准与新机修复后的实际渲染。恢复现有资源文件时沿用同一模板版本；更换字体引用时用已采用的新版本对比旧版基准，并明确只有字体项变化。
| 对比项 | 记录方式 |
|---|---|
| 字形 | 看同一字符的骨架与笔画；标记具体字符，不写笼统的“看起来怪”。 |
| 覆盖 | 查方框、空白或少数字符换成另一套字形；记录发生回退的字符。 |
| 行宽 | 在相同文本与画布上比较行尾位置和换行；差异与字体版本、字距或渲染环境一起查。 |
| 位置 | 看字幕带与边距；若整组统一偏移，先回查画布与模板绑定。 |
| 轮廓 | 比较描边和阴影，同时保持参数不变；这些效果也受渲染实现影响。 |
文件路径和 family 一致只证明配置链条一致。通过条件来自实际代表字幕：项目所需字符齐全，主要字形与接受基准一致，换行没有意外变化，位置仍落在同一字幕带。不同操作系统、字体版本或渲染库仍可能产生边缘栅格差异，因此验收写可见要求和具体观察，不写“逐像素完全相同”。
项目工具能固定什么，仍要人工看什么
在固定版本的 $video-recap 中，字体资源至少包含一份 .ttf、.otf 或 .ttc 文件，可登记 font.family。字幕模板用资源 ID 引用字体，项目文件用 subtitle_style 绑定已采用模板。运行入口的实际参数是：
```bash
python3 scripts/recap.py <video> --project <recap_project.json-or-directory> --work-dir <work_dir>
```
项目解析会检查库、资源和模板，拒绝无效或未采用的模板，并在画布不匹配时停止。显式设置与绑定冲突时也会在开始前报出。它能把选定字体文件与 family 送到现有字幕渲染阶段，不能替人从旧机找回正确字体、读取设计意图、判断字形是否可接受，或保证两台机器逐像素一致。
修复完成后保留一张迁移记录：实际字体文件来源、内部 family、字体资源 ID、模板版本、项目绑定、代表字幕和对比结论。以后模板换字体时建立新版本并重新比较；不要悄悄替换旧资源文件后沿用原验收结论。
常见问题
新电脑安装了同名字体，为什么字幕还会变？
显示名相同仍可能对应不同文件、版本、内部 family 或字符覆盖。核旧项目实际文件与内部名称，再用相同代表字幕渲染对比。
绑定字体文件后能保证两台电脑像素完全相同吗？
文件绑定能减少系统字体回退。字体版本、字符覆盖、操作系统与渲染库仍会影响输出；用代表字幕按可见要求验收。
用 skill 来做
用 $video-recap 修复这个跨电脑字幕字体差异。请确认旧项目实际字体文件和内部 family。若现有已采用模板已经引用正确字体资源，就恢复该资源的同一真实文件与已核 family，不改模板版本；若必须新增或更换字体引用，就复制全部非字体参数建立并采用新版本。用 recap_project.json 绑定选定模板，保持画布、字幕文本和非字体参数不变，渲染含中文、关键字符、数字标点和英文的代表字幕，逐项记录字形、缺字回退、行宽和位置差异；不要承诺逐像素一致。
查看具体方法： 字体资源、字幕模板引用与项目绑定 · 字体文件与 family 的项目解析 · 字幕渲染读取字体文件与字体目录 · 字幕字体名称与文件环境设置 · 项目绑定入口与公开技能交付