hyper3d-documentary

# hyper3d-documentary：从一句话想法到 3D 网页纪录片 > 本文档使用自然语言 + 代码片段混合编写。代码部分按其语言语义执行；代码块只写逻辑骨架，判断标准写在代码块外面的正文里。 ## 定位 用户说"我想做一个 ×× 的 3D 纪录片"，本技能带着用户走完整条线，最终交付一个**双击就能打开、可以直接发给别人的单文件 HTML**：自动播放的分镜动画 + 片尾自由旋转、拆解、点零件看说明。3D 模型由 Hyper3D 的 Rodin Gen-2.5 从参考图生成，渲染引擎（three.js）已经打包在技能里，成片不依赖任何网络资源。 技能是原子的：生参考图的方式由用户在 `config.json` 里配置（任何能"提示词 → 图片文件"的命令都行），不依赖其他技能。 ## 运行环境 - Python 3.10+（所有脚本），无第三方依赖 - Node 18+（只在压缩模型时用，首次运行自动 `npm install` 到 `tools/`） - 可选：`pip install playwright && playwright install chromium`，用来给成片自动截图验收 - Hyper3D API Key：在 hyper3d.ai 后台申请。按优先级从环境变量 `HYPER3D_API_KEY` → 本目录 `config.json` 的 `hyper3d_api_key` → 项目目录 `.env` 读取 ## 配置 第一次用时把 `config.example.json` 复制成 `config.json` 再填。`config.json` 含真实 Key，只在本地用；分享技能时只分享 `config.example.json`。各字段含义写在 example 文件的 `_说明` 里。 ## 项目落盘结构 所有项目放在 `config.json` 的 `root` 下，一个项目一个目录，产物全部是用户能直接打开看的文件： ``` <root>/ ├── 管理页.html 所有项目的总览（每做完一步重新生成） ├── 共享缓存/ 地球贴图、星表等跨项目复用的下载 └── <项目名>/ ├── 需求.md 第 1 步：问答定下来的需求 ├── 脚本.md 第 2 步：分镜脚本（人读） ├── 素材清单.json 第 2 步：模型表 + 关键帧表（脚本读） ├── 参考图/M1-<名>/1-四分之三.png … 第 3 步：每个模型四个视角；<视角>-提交.png 是去掉文字标识后送 Hyper3D 的版本 ├── 参考图/K1-<名>.png 第 3 步：分镜关键帧概念图（只给人看，不建模） ├── 参考图.html 第 3 步：审图页 ├── 模型/M1-<名>/ 第 4 步：Hyper3D 回包、原始 glb、零件/、web-4096.glb ├── 模型库.json 第 5 步：每个模型的状态、积分、体积、备注 ├── 模型.html 第 5 步：模型库页（3D 预览 + 审核） ├── 素材/贴图/ 第 6 步：环境贴图（太空题材） ├── 动画页.html 第 6 步：动画源码（AI 按脚本写，可反复改） ├── 成片.html 第 6 步：打包后的单文件成片（发给观众的就是它） └── 验收/ 第 6 步：每幕截图 ``` 模型目录统一叫 `M<序号>-<中文名>`，序号从 1 开始；关键帧叫 `K<序号>-<中文名>`。 ## 总路由 用户的一句话进来后，先定位项目，再判断它走到哪一步，只读那一步的分支文件。 ```python project = 定位项目() # 用户点名的项目；没有就按需求里的题材起一个中文目录名 stage = 判断阶段(project) 读取(f"rules/{stage}.md") 并执行 每一步结束后: python3 scripts/build_manage_page.py ; 告诉用户管理页和本步产物页的路径 ``` 阶段判断，按顺序取第一个成立的： 1. 没有 `需求.md` → **1-需求问答** 2. 没有 `脚本.md` 或 `素材清单.json` → **2-写脚本** 3. 素材清单里任一模型的参考图没齐、或用户在审图页标了重做 → **3-参考图** 4. 任一模型还没有 `模型/M*/web*.glb`、或模型库里有"重做" → **4-生成模型** 5. 模型库里还有"待审" → **5-模型库** 6. 其余 → **6-动画页**（没有成片就写并打包；有成片就按用户反馈改动画页再打包） 用户明确点名某一步（"帮我重生 M3 的参考图"、"改一下第 4 幕镜头"）就直接进那一步，不按顺序重走。 Hyper3D 接口细节（参数、计费、状态、坑）统一放在 `rules/hyper3d-api.md`，第 4 步和排错时读。 ## 铁律 1. **花钱前先报价**：提交 Hyper3D 之前把要生成的模型数、每个的档位、预计积分、余额列给用户，得到同意才提交。 2. **每一步都落盘、都给用户看得见的页面**再进下一步；用户在页面上的判断（重做 / 通过）是流程往前走的依据，不替用户判断。 3. **成片是给观众的**：不含任何内部信息——不写生成参数、积分、文件路径、待办；字幕只讲题材本身。 4. **模型真实尺寸由脚本定**，不在动画里靠眼睛调：素材清单里每个模型写清真实长度和长轴，引擎按它缩放。 5. 会自动展开、旋转、伸缩的部件（太阳翼、天线、起落架、舱门）**不建进模型**，参考图里就去掉，在动画页里用简单几何体做成会动的附件。 6. 参考图**不能有文字、旗帜、标识、水印**，Hyper3D 会把它们当成几何体或贴图烧进模型；有就做一份 `-提交.png`。 7. API Key 只走环境变量 / `config.json` / 项目 `.env`，任何会被分享的文件里都不能出现它。