# 踩坑与修复

| 现象 | 原因 | 修复 |
|---|---|---|
| `hyperframes check` lint error `font_family_without_font_face`（microsoft yahei, noto sans cjk sc） | CSS 的 font-family 里出现未声明 @font-face 的字体 | CSS 只写 `font-family:Science,sans-serif`；`Science` 由随工程携带的 `sans-sc.woff2` 声明。canvas 内 FONT 串可保留回退字体（lint 不扫） |
| `safezone_audit.py: error: the following arguments are required: html` | 该脚本必须传 html 路径 | `python scripts\safezone_audit.py index.html` |
| `npm run check` 约 4 分钟无输出 | 它会开浏览器做 layout/contrast 采样 | 耐心等；日志首行 `browserGpuMode probe` 出现即在跑 |
| `canvas_content_at_edge`（info） | 全屏 canvas 有内容贴边（背景星空/渐变） | 信息级，可忽略；如要消除给 canvas 加 `data-layout-allow-overflow` |
| `nested_structure_needs_subcomposition` ×8（warning） | 场景 section 内含嵌套 div | 可忽略 |
| 终端输出噪声大、大日志读不出 | 共享 pty + render 进度条 | 所有命令写成 `.ps1`，输出重定向到 `output\*.log`，再用 `fs_read` 读；日志超大时 fs_read 会把结果存到本地文件，改用 python 过滤掉 `Capturing frame`/`checkpoint` 行后看尾部 |
| `rm -rf *` 复合命令被拦截 | 沙箱策略 | 不要用破坏性复合命令；用显式路径 |
| 云端 npm / edge_tts 不可用 | 网络白名单 | 云端只做视觉原型；真 TTS/渲染在开发机 |
| 中文乱码（测试页） | 缺 `<meta charset>` | 页面加 `<meta charset="UTF-8">`，script 标签加 `charset="utf-8"` |
| 真 TTS 后关键帧顺序错乱 | 线索时间与预估不同 | `keys()` 前用 `fixKeys` 保证单调；线索缺省给比例回退值 |
| `fs_write` 报 "An error occurred invoking"（写新目录下的文件） | 目标父目录不存在 | 先 `fs_mkdir` 目标目录（含子目录）再写 |
| 大文件重新输出易出错 | 需要整文件再输出一遍 | 传完立刻 sha256 对比；不一致就重写该文件；开发机上已有文件用 `fs_copy` 复制 |
| 渲染极慢 | 软件 GPU + 全屏 canvas 逐像素地球 | 预算 ≈ 7 倍实时（138 s 片 ≈ 16 min）；减小地球半径/减少同屏地球数量可提速；`--workers 2` 已是推荐值 |
| 无法把 MP4 发回对话 | AHP 只能传小文本，fs_read_binary 单次≤1MiB 且无分片读 | 告知用户开发机路径；SRT/JSON 可读出后发送 |

## 其它经验
- 开发机终端 id 会变；先 `term_list`/沿用已有终端。命令用 `pwsh -NoProfile -File x.ps1; echo MARK`，日志里写 `*_DONE` 标记便于判断完成。
- 写 `.ps1` 时中文路径/输出用 `Out-File -Encoding utf8`；Python 子进程设 `$env:PYTHONIOENCODING='utf-8'`。
- 每个 Step 记录 `EXIT(name)=$LASTEXITCODE`，一眼看出哪步失败。
- 修改 `build_seasons.py` 后记得重新跑 build，再跑 check/render（render 前确认 index.html 是最新的）。
- 不要把 `science_review` 改成 true 来过审；`--allow-unreviewed` 只是放行流水线，不代表审核。
- 用户中途追问时，一句话说明当前在做什么，再继续，不要沉默超过几分钟。