hyper3d-documentary

一个 AI 技能（Claude Code / 任何能读 Markdown 规则并执行脚本的 Agent 都能用）：把"我想做一个 ×× 的 3D 纪录片"变成一个可分享的单文件网页——自动播放的分镜动画、真实尺寸的 3D 模型、片尾自由旋转 / 拆解 / 点零件看说明。3D 模型由 Hyper3D 的 Rodin Gen-2.5 从参考图生成。

示例：《天宫 · 建成之路》——中国空间站 2021–2026，7 个模型，13 幕，一个 130 MB 的 HTML。

流程

需求问答 → 写脚本 → 生参考图 → 生成 3D 模型 → 模型库审核 → 动画页 → 成片
   ↓          ↓          ↓            ↓             ↓            ↓
 需求.md   脚本.md    参考图.html    模型/       模型.html    成片.html
                                                    └── 管理页.html 总览所有项目

每一步都落盘成用户能打开的文件或网页；用户在网页上做判断（参考图重做、模型通过），AI 按判断推进。

安装

git clone https://github.com/xiaohuailabs/hyper3d-documentary.git ~/.claude/skills/hyper3d-documentary
cd ~/.claude/skills/hyper3d-documentary
cp config.example.json config.json    # 填 Hyper3D API Key、项目根目录、生图命令

需要 Python 3.10+；Node 18+（压缩模型时自动装 gltf-transform）；可选 Playwright（自动截图验收）。渲染引擎（three.js 0.170 + Draco/Meshopt 解码器 + 后期）已打包在 tools/，成片不依赖网络。

生参考图用你手头任何"提示词 → 图片"的命令，填进 config.json 的 image_command；留空则由 AI 用当前环境的生图能力，或请你手工生成放进目录。

目录

SKILL.md              总路由：阶段判断 + 铁律
rules/1-需求问答.md    每一步的规则，按需读
rules/2-写脚本.md
rules/3-参考图.md
rules/4-生成模型.md
rules/5-模型库.md
rules/6-动画页.md
rules/hyper3d-api.md   Rodin Gen-2.5 接口、参数、计费、坑
scripts/hyper3d.py     生成 / 拆零件 / 续传 / 状态 / 余额
scripts/compress_model.sh   原始 glb → 网页版（焊接、webp、Draco）
scripts/library.py     模型库账本：扫描、标状态、列表
scripts/build_refs_page.py / build_models_page.py / build_anim_page.py / build_manage_page.py
scripts/shoot.py       无头浏览器逐幕截图
scripts/prepare_space.py    太空题材：下载地球贴图、星表
templates/动画页-基础.html  动画引擎（配置 / 引擎 / 分镜 三段）
templates/环境-太空.js      地球 + 大气 + 星空 + 太阳模块
templates/参考图页.html · 模型库页.html · 管理页.html
tools/                 渲染引擎打包（含重打包脚本）
examples/天宫空间站-脚本.md  完整脚本范例

安全

config.json 含真实 API Key，已在 .gitignore 里；只分享 config.example.json。

许可

MIT。three.js（MIT）、Draco（Apache-2.0）、Yale 亮星表（公共领域）。