hyper3d-documentary

---
name: hyper3d-documentary
description: 用 Hyper3D（Rodin Gen-2.5）把一个科普题材做成可分享的单文件网页 3D 纪录片：需求问答 → 写脚本 → 生参考图 → 生成 3D 模型 → 模型库审核 → 动画成片，外加一个项目总览管理页。
---

# 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`，任何会被分享的文件里都不能出现它。