skill/reference/pitfalls.md

踩坑与修复

现象	原因	修复
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 只是放行流水线，不代表审核。
• 用户中途追问时，一句话说明当前在做什么，再继续，不要沉默超过几分钟。