这是什么
code-doc-film 是一个 Agent Skill，由作者 bangbuilds 开发，专为 Claude Code 设计（也兼容其他能加载 SKILL.md 格式的编程助手）。它的核心能力是：你只需说一句话，
比如“做一条郑和下西洋的 3D 视频”，它就能自动完成从查资料、写旁白、下载真实地形、构建三维场景、配音、合成配乐，到最终渲染出一部 1–3 分钟的 3D 纪录短片。
原视频链接：
整个过程完全由代码实时渲染，不需要任何图片、视频素材或现成音乐。
该仓库目前获得 9 个 Star、2 个 Fork，采用 MIT 许可证，作者为 bangbuilds。项目处于早期阶段，但已能完整跑通一个范例。
适合谁
- 内容创作者：希望快速生成具有地理和历史感的纪录短片，用于自媒体或教育内容。
- 技术型用户：熟悉命令行，愿意折腾 Node.js、Python 和 ffmpeg 环境。
- 历史爱好者：想用可视化方式呈现历史事件，如长征、郑和下西洋等。
- 开发者：对 three.js、地形渲染、程序化音频合成感兴趣，想学习或扩展。
能做什么
根据 README 和 SKILL.md 的描述，这个 Skill 可以：
- 自动调研与写稿：Claude 会搜索资料，撰写旁白稿，并列出每个数字的出处供你确认。
- 真实地形下载：从公开数据源（如 Terrain Tiles on AWS）下载指定区域的真实地形，下载前会告知大小并获得你的同意。
- 三维场景构建：使用 three.js 编写三维场景，包括地形、水体、人物、船队、建筑等，支持多种场景库（河谷、峡谷、湖、雪山垭口等）。
- 配音与配乐：默认使用系统语音（macOS 的 say）或 edge-tts，也可接入自定义语音合成；配乐和环境声由 numpy 合成。
- 自动质检：渲染前会抽帧检查，识别黑屏、过曝、机位异常等问题，并确保每个数字都有出处。
- 输出完整交付物：最终生成成片、封面、上传版和预览版。
使用前准备
在安装之前，你需要准备以下环境：
- Claude Code 或其他能加载 SKILL.md 格式的编程助手（如 Codex，但未实测）。
- Node.js 20+：用于运行渲染引擎（通过 npx 调用 HyperFrames）。
- Python 3.10+：需要安装 numpy 和 Pillow。
- ffmpeg：用于视频处理。
注意：项目目前仅在 macOS（Apple Silicon）上测试过，Linux 和 Windows 未验证。
安装方法
按照 README 中的说明，安装步骤如下：
git clone https://github.com/bangbuilds/code-doc-film ~/.claude/skills/code-doc-film
pip install numpy pillow
如果你使用其他工具（如 Codex），可以克隆到对应的 skill 目录，例如：
git clone https://github.com/bangbuilds/code-doc-film ~/.agents/skills/code-doc-film
安装完成后，在 Claude Code 中直接说题目即可，例如“做一条丝绸之路的 3D 视频”。
使用示例
如果你想不经过 AI，先手动跑一遍范例，可以按以下步骤操作：
SK=~/.claude/skills/code-doc-film # 你克隆到的位置
python3 $SK/scripts/new_project.py zheng-he-demo --example zheng-he
cd zheng-he-demo
python3 scripts/film.py geo # 列出要下载的地形：189 张瓦片，约 14 MB
python3 scripts/film.py geo --download # 同意后下载
python3 scripts/film.py audio # 配音（默认用系统语音）+ 配乐 + 环境声
python3 scripts/film.py qa --frames # 抽帧检查，生成总览图 build/qa/contact-*.jpg
python3 scripts/film.py render # 渲染 + 打包，约 6 分钟
根据 README，范例《郑和下西洋》从一句话到成片耗时约 55 分钟，其中渲染 6 分钟，成片时长 2 分 05 秒，包含 30 个镜头。
风险与注意事项
- 早期版本：项目目前只制作过两条片子，且都在同一台 macOS 机器上测试。Linux、Windows 和其他工具（如 Codex）未经过实测，可能存在兼容性问题。
- 配音质量：默认系统语音机器味较重，适合排片和初版；若要高质量配音，需要自行接入语音合成服务。
- 场景限制：内置场景库有限，如果主题涉及现代城市、车辆、机械等，Claude 会现场编写，速度会慢很多。
- 事实核查：历史题材的旁白稿基于网上可查来源，但务必自己过一遍，skill 会标注每个数字的出处，但有争议的内容可能无法完全核实。
- 地图边界：地图上不绘制任何国界和省界，避免政治敏感问题。
- 数据署名：使用地形数据（Terrain Tiles on AWS）和河流数据（Natural Earth）时，需按照其署名要求注明来源。