代码纪录片（code-doc-film）

把一个题目做成一条 1–3 分钟的片子：画面全部由代码实时渲染（three.js），地图用真实高程数据，配音接任何语音合成（默认先用系统自带的声音出一版），配乐和环境声用 numpy 合成。没有图片素材、没有视频素材、没有曲库。

这套做法来自两条成片：陆上的《长征》（2 分 44 秒、43 个镜头）和海上的《郑和下西洋》（examples/zheng-he，2 分 05 秒、30 个镜头）。做它们时翻过的车——机位钻进山里、从地底往上看、画面和旁白错位、夜景照成白天、数字写错——现在都由引擎和检查脚本兜住。你的工作是把内容做对、把镜头做好看，而不是重新踩一遍。

它擅长什么、不擅长什么

擅长：有地点、有路线、有过程的题目——行军、迁徙、航行、战役、考察、河流与山脉、城市的兴衰。场景库里有河谷、峡谷、湖、雪山垭口、沼泽、黄土高原、一线天、街巷、桌面特写、外海、海岸港湾，以及行军队伍、渡船、浮桥、铁索桥、帆船船队、码头、集市、驼队、火、烟、雨、雪、枪炮。地图既能画陆上路线，也能画跨洋航线。

不擅长：需要人脸、表演、特写人物的题目（小人是远景剪影，近看是方块）；海战、现代城市、室内群戏、机械和车辆这类场景库里没有的东西——能做，但要写新的地形或道具，慢得多，开工前要和用户说清楚。

用户只说了一句话时

「做一条郑和下西洋的视频」这样的一句话就够开工。默认这样走：

1. 先自己把题目想清楚（讲哪几个节点、多长、给谁看），只问会改变做法的事：发在哪（决定横竖屏和时长上限）、多长。声音、风格用上次的或默认的，说一声就行。
2. 查资料、写稿，把稿子和事实表给用户确认——这一步保留，因为历史和数字错一处就是硬伤，而且云端配音通常按次付费。
3. 用户确认后一路做到出片，中途只在遇到要下载数据、要写场景库以外的新场景时停下来说一声。

如果用户明说「不用确认，直接出」，就跳过第 2 步的等待，但稿子和事实表仍然要做，并在交付时一起给出，把没核到链接的事实标出来。

流程

所有命令都在工程目录里运行。film.py 是唯一的入口。

# SK = 这份 SKILL.md 所在的目录。装在哪就是哪，例如：
SK=~/.claude/skills/code-doc-film        # 或 ~/.agents/skills/code-doc-film
python3 $SK/scripts/new_project.py videos/<slug>      # 新建工程（HyperFrames 初始化 + 引擎 + three.js）
cd videos/<slug>

每到一个节点记一笔：python3 scripts/film.py log "稿子确认"。出片时的用时、渲染时间都从这份记录里来，帖子里的数字才有出处。

film.json 是唯一的事实来源

旁白、镜头切点、地图镜头、数字标注、日期地点、配乐情绪、环境声，全部写在 film.json 里；scenes/*.js 只负责把三维镜头画出来。完整写法见 references/film-json.md，这里只说最重要的一条：

镜头切点绑定到旁白的第几句，不写秒数。 "until": "cue:2" 表示「这个镜头到第 2 句开始时结束」。配音出来以后切点自动落在句子上，画面和旁白就不会错位；以后改稿、换语速，也不用重排镜头。

{ "id": "ceylon", "scene": "f06_ceylon", "station": 4,
  "narration": ["1409年，锡兰山，今天的斯里兰卡。", "郑和在这里立下一块石碑，", "碑上刻着3种文字：中文、泰米尔文、波斯文。", "这块碑，今天还在。"],
  "shots": [
    { "id": "map", "until": "cue:1", "map": { "fit": ["满剌加", "苏门答剌", "锡兰山"], "draw": { "from": "满剌加", "to": "锡兰山", "t": [0.1, 3.0] } } },
    { "id": "stele", "until": "cue:3", "music": "calm", "ambience": ["sea", "wind"] },
    { "id": "coast", "music": "hope", "ambience": ["sea"] }
  ],
  "callouts": [{ "cue": 2, "num": "3", "unit": "种文字 · 一块石碑" }] }

地图镜头（"map": {…}）不用写代码。三维镜头在场景文件里按 id 实现：

export default {
  setup() { const W = coastWorld({ seed: 52, palette: 'tropic' }); …; return { worlds: [W], W, … }; },
  shots: {
    stele({ t, lt, k, S }) { …; S.W.track(k, { pos: [[0, […]], [1, […]]], at: […] }); return { world: S.W }; },
  },
};

写场景时守住的几条（为什么）

• 机位用 world.cam / world.track，不要直接摆相机。 它会把机位抬到地面以上、视线被山挡住时抬高，并把每次修正记成警告。上次的大部分翻车都是手填坐标造成的。警告出现时去改镜头，别当它不存在——被自动抬过的镜头构图通常不是你想要的。
• 机位关键帧用归一化时间 k（0→1），不用秒。旁白长度一变，按秒写的运镜就会走不完或停在半路。
• 每个镜头开头先把这个世界里的东西全部关掉，再打开自己要的。 同一个世界里的几个镜头共用演员，不清场就会把上一个镜头的火、船、人带过来。
• 地形里的高度问地形要：W.on(x, z, 离地高度)、W.H(x, z)。黄土塬顶有 150 米高，雪坡是斜的，写死 y = 20 一定会出事。
• 事件要对上旁白就用 cue(i)（第 i 句在本镜头里的开始时间），比如爆炸、天亮、旗子升起。
• 人物只做远景剪影，不做任何可辨认的真人形象；会议、人物类节点用建筑、器物、地图来讲。原因见 references/rules.md。

检查是流程的一部分，不是可选项

python3 scripts/film.py qa --frames

它做三件事：核对旁白里的每个数字在 facts 里有出处、每个镜头都有实现；无头渲染每个镜头的开头/中间/结尾三帧，报出全黑、过曝、一片平、机位被修正的帧；生成带镜头名和时间的总览图 build/qa/contact-N.jpg。总览图要自己看一遍（把图片打开来看）——脚本能发现「黑」和「白」，发现不了「人太小」「构图空」「字幕压住了主体」。

调试单个镜头用浏览器预览更快，做法和坑（缓存、视口、总览图工具）见 references/qa.md。

参考文档

examples/ 下每个目录都是一条完整的片子（film.json + scenes/）。本机可能还有没随 skill 公开的范例，开工前 ls examples/ 看一眼。

升级已有工程的引擎（不动 film.json、scenes/、assets/、audio/）：

python3 $SK/scripts/new_project.py videos/<slug> --sync