zeroz-lab Visual Scrollytelling
目标
根据用户提供的主题，生成一个可直接运行、响应式、可回退的滚动叙事网页。
技术栈固定为：
- Three.js：场景、对象、材质、空间关系、摄像机和渲染。
- Anime.js：统一动画时间轴、对象状态插值、转场和滚动进度映射。
- 原生 HTML、CSS、JavaScript：内容结构、滚动检测、无障碍和响应式布局。
不得改用 GSAP、ScrollTrigger、React、Vue、Framer Motion 或其他动画、三维框架，除非用户明确修改技术约束。
核心原则
滚动叙事不是“文字随滚动出现”，而是让一个对象、过程或系统随着滚动真实运行。
视觉必须承担主要解释职责，文字只负责标题、短标签、条件和结论校准。
设计完成后，即使隐藏主要说明文字，用户仍应大致理解：
- 画面中有哪些关键对象；
- 当前发生了什么变化；
- 为什么会产生这一变化；
- 变化如何影响下一阶段；
- 整个过程如何结束。
协作式设计流程（默认）
视觉取舍会显著改变结果，默认分阶段交给用户选择。只有用户明确说“你决定”“直接做”“不要询问”时，才自主完成全部决策；用户也可以只授权某一个决策门。
进入全权委托分支时，内部完成四项选择，向用户展示一份简短决策记录作为知情说明，并继续完成用户要求的交付物，不把记录变成审批点。
开始时从主题中提取学习目标、核心对象、参与者、状态变化、因果关系、反馈机制和终止条件。普通技术细节可合理假设，叙事、审美、构图和体验方向必须进入决策门。
决策门规则
每次只处理当前阶段，一次只呈现一个决策门：
- 提供 2—3 套彼此完整、明显不同的方案，每套都以一致组合呈现；
- 推荐项排第一，说明推荐理由、用户会看到的效果、主要取舍和实现影响；
- 要求用户明确选择，也允许“选 A，但修改一个维度”；
- 记录已锁定的选择，后续方案必须服从；修改已锁定选择时先说明影响；
- 用户选择后才进入下一阶段。等待期间以当前方案说明为完成边界。
统一使用简短格式：
决策 2/4：视觉方向
A（推荐）— 预期效果；主要取舍
B — 预期效果；主要取舍
C — 预期效果；主要取舍
请选择 A/B/C，或指定要调整的一个维度。
决策 1：叙事模型
编码前提供 2—3 套章节结构。每套明确学习目标、贯穿对象、关键事件、反馈方式和结束状态。用户选定后，输出简短决策记录。
决策 2：视觉方向
读取 references/design-layers.md，形成 2—3 套一致的设计包。每套同时包含画面形式、主要动作、时间结构、美术语言、三色调色板、镜头方式和文字空间关系。用户选定后锁定，后续设计保持同一方向。
决策 3：关键分镜
写 Three.js 场景前，先展示首屏、关键转折和终态的分镜方案。环境支持时给出静态概念图或可查看稿；否则使用清晰的文字线框。让用户确认对象造型、构图、镜头和文字位置。
决策 4：动态样段
先实现前 2—3 章作为 tracer prototype，提供可查看入口，让用户体验滚动节奏、信息密度、动画幅度和反馈是否清楚。确认后再扩展完整页面。
Three.js 对象复用、时间轴实现、像素比限制、resize、键盘导航、响应式、无障碍、reduced-motion 和 WebGL fallback 等工程细节由技能自主完成。
美术方向（必做，在写任何场景之前）
叙事结构清楚之后、写任何 Three.js 代码之前，必须先锁定一个具体的美术方向。没有美术方向的"对象/关系/状态"会退回到最通用、最像 AI 默认产物的长相（黑底 + 发光几何体 + 玻璃面板）。
第一步：选一个方向，并贯彻到底
从主题气质出发选一个方向，整页只能有一个。混合多个方向等于没有方向。可参考的方向（不限于）：
- 编辑极简（纸底、墨色、衬线大标题、大量留白、正交相机）；
- 电影夜景（近黑底、深青、一束暖光、体积雾、景深）；
- 有机生物（暖色渐变、柔体、膜、涟漪，无锐角无发光）；
- 技术档案 / 野兽派印刷（骨白、墨、一个专色、等宽字、暴露网格、双色丝网印刷质感）。
方向选定后，整页的材质、字体、相机、色板都必须服从它。不要在"电影夜景"里突然出现"编辑极简"的衬线面板。
第二步：定死调色板
整页最多 3 个颜色角色：底色、主色、一个强调色。强调色只承担一个语义（如"当前激活/建立"），不得用同一种颜色表达多个互相冲突的状态。在注释里写明每个 hex 和它的语义角色。过程不得临时新增颜色。
禁止的 AI 默认长相
下面这些是模型最常见的、让作品立刻显得"AI 味重"的默认产物，不得作为审美方向：
- 半透明毛玻璃面板（
backdrop-filter: blur）堆叠当主要文字容器； - 黑底 + 自发光几何体 + bloom，即 Three.js 入门教程的默认长相；
- 仪表盘 chrome：顶部细进度条、底部药丸状态标签、右上角浮动提示卡同时出现；
- 语义状态色（蓝/绿/橙/红/紫）全部上齐，像流程图配色；
- 对称居中的"两节点 + 中间连线"教科书构图，缺乏层次；
- 所有元素同时发光、同时高亮。
如果第一版看起来像上面任何一条，先换美术方向，不要靠调参数硬救。
叙事建模
将主题转化为四类视觉元素。
对象
表示系统中存在的实体。不同类别必须使用不同造型，不能全部设计为相似矩形卡片。
建议映射：
- 目标：晶体、胶囊、终点核心；
- 数据：粒子、卡片、数据包；
- 状态：仓库、容器、插槽、抽屉；
- 决策：分叉轨道、候选卡、筛选器；
- 工具：终端、雷达、机械设备；
- 外部环境：城市、网络、建筑或独立空间；
- 验证：天平、对比台、锁定装置；
- 失败：断裂、阻断、反弹或红色回流；
- 完成：闭合、稳定、锁定或持续点亮。
关系
通过空间、路径和运动表达：
- 包含；
- 输入与输出；
- 依赖；
- 控制；
- 分支；
- 反馈；
- 对比；
- 因果。
静态可能关系使用低透明度轨道；当前实际路径使用高亮轨道、方向箭头和运动数据包。不要同时高亮所有连线。
状态
对象至少应区分：
- 未出现；
- 未激活；
- 当前处理；
- 已选择；
- 执行中；
- 成功；
- 失败；
- 已淘汰；
- 已验证；
- 已完成。
状态变化不能只依靠文本替换，应通过物体位置、形态、连接、亮度、颜色或容器内容变化体现。
事件
优先使用具有机制含义的变化：
- 拆解；
- 组合；
- 插入；
- 移除；
- 展开；
- 筛选；
- 选择；
- 发送；
- 返回；
- 阻断；
- 回流；
- 比较；
- 锁定；
- 停止。
淡入、旋转、漂浮和发光只能作为辅助，不得成为主要叙事动作。
场景设计
使用一个持续存在的视觉舞台，不要为每章重新创建互不相关的画面。
核心对象必须贯穿始终，并在不同阶段发生结构或状态变化。
复杂度应逐步增加：
核心对象
→ 出现第一个关系
→ 加入状态或容器
→ 展开候选路径
→ 连接外部环境
→ 出现反馈或失败
→ 修正并重新执行
→ 验证结果
→ 展示完整系统
第一屏不要一次展示全部模块和连线。
章节设计
每个章节只回答一个认知问题：
- 现在应该看什么；
- 发生了什么变化；
- 为什么发生；
- 变化后形成了什么新状态。
每章的局部时间轴建议划分为：
0.00—0.15：镜头进入或对象聚焦
0.15—0.55：核心结构变化
0.55—0.80：保持稳定，供用户观察
0.80—1.00：准备进入下一阶段
关键变化后必须留出稳定观察区间，不要让画面始终运动。
至少包含一次由反馈引发的修正：
执行原路径
→ 得到异常结果
→ 结果回写
→ 原方案失效
→ 新路径被选择
→ 再次执行
如果主题本身没有失败机制，可改为对比、筛选、排除或纠正错误假设。
镜头规则
摄像机是教学指针，不是装饰。
每章只能有一个主要视觉焦点：
- 当前对象：清晰、高亮、靠近镜头；
- 相关对象：保留但降低权重；
- 背景对象：降至约 10%—25% 的视觉强度。
镜头应根据叙事任务选择：
- 讲整体结构：拉远；
- 讲内部组成：靠近或进入容器；
- 讲对象流转：跟随运动对象；
- 讲选择：正面对准候选路径；
- 讲失败：停在阻断位置；
- 讲验证：使用便于比较的正面视角；
- 讲完成：重新拉远，呈现完整系统。
避免无目的的持续摇摆、环绕和大幅缩放。
文字规则
文字只保留：
- 阶段标题；
- 一句核心解释；
- 对象短标签；
- 必要约束；
- 新增或删除的状态差异；
- 最终结论。
禁止：
- 大段正文占据主要视觉区域；
- 左右两块固定文字面板同时争夺注意力；
- 重复描述画面已经表达的过程；
- 依赖大量英文标签才能区分对象；
- 用文字宣布一个画面没有证明的结论。
优先把说明贴近相关对象，而不是集中放入独立信息面板。
文字与画面的空间关系（必选一种，写任何章节文字之前先定）
这是最常见的构图固化陷阱：没有提前决定文字怎么放，结果每章都退回到"左边一个文字框、右边一个文字框"交替贴边的安全默认。连续几章这样排，整页会显得机械、模板化，画面也拿不到完整空间当主体。
在写任何章节文字之前，先从下面选一种空间关系，整页贯彻一种为主（可少量混用，但必须有主导模式）：
- 顶部标题带：所有文字统一收在画面顶部一条窄带（序号 + 标题 + 一句话），画面占据下方主体。文字位置固定，章节切换时只换内容、不换位置。适合画面是绝对主角、文字只做点题的场景。
- 中央字幕层：文字直接叠在画面中央，像电影章节卡，随滚动淡入淡出。画面始终在文字背后。适合电影感、氛围重的叙事。
- 引线注释：文字是从画面里某个对象拉出的一根细线 + 短注释，紧贴它解释的那个对象，位置随该对象移动。适合需要精确指认局部机制的图解。
- 画面优先纯镜：大部分章节没有独立文字，画面独自承担叙事，只在关键转折处出现一行标题或结论。适合对象本身表现力强、机制一目了然的题材。
不论选哪种，都不得出现"每章交替地在左侧、右侧贴一个独立文字框"的模板化排版。如果发现连续两章以上的文字位置只是左右镜像，停下来重新选空间关系，而不是继续复制框。
移动端可以简化（例如引线注释退化为顶部短标签），但主导模式不能丢。
视觉语法
为整个页面建立稳定的语义，过程中不得随意改变。
语义角色是固定的（成功/完成、失败/阻断、未激活/可能、信息、执行等），但具体用什么颜色表达，必须来自美术方向里定死的 3 色调色板——不要为了凑齐所有语义而铺开一整套彩虹色板。
把语义映射到调色板，而不是反过来。典型做法：
- 强调色（唯一）→ 当前选中、成功、完成、建立；
- 主色 → 信息、数据、只读、执行；
- 次级/降权色（主色的低透明度或灰）→ 未激活、可能路径、失败/阻断。
当多个语义需要区分、但调色板颜色不够时，优先用形态、位置、明度、纹理区分，而不是新增颜色。一种颜色不要承担多个互相冲突的含义。
技术实现
页面使用单一 Three.js 渲染循环。
滚动处理分为两层：
- 章节状态：使用 IntersectionObserver 或元素视口位置判断当前章节；
- 章节进度：计算当前章节内部的
0—1局部进度。
全局滚动百分比只能用于页面总进度条，不得直接控制全部叙事动画。
将局部滚动进度映射到 Anime.js 时间轴：
section local progress
→ Anime.js timeline seek
→ Three.js 对象状态
→ Three.js render
所有核心变化必须能够由时间轴进度推导，确保用户向上滚动时可以自然恢复旧状态。
避免只执行一次、无法反转的命令式动画。
性能要求
devicePixelRatio最大限制为 2；- 避免实时阴影和高成本后处理；
- 复用几何体和材质；
- 避免在渲染循环中创建新对象；
- 控制透明材质和粒子数量；
- DOM 不得在每帧进行大规模更新；
- resize 后重新计算摄像机、渲染尺寸和章节位置；
- 页面滚动过程中保持视觉、文字和状态同步。
响应式与降级
桌面端可以展示空间关系和多对象协作。
移动端不能只是缩小桌面版，应改为：
- 每阶段只保留核心对象；
- 隐藏次要连线和背景结构；
- 缩短镜头移动；
- 减少粒子与透明材质；
- 将状态说明改为短标签；
- 避免固定面板遮挡主体。
必须支持 prefers-reduced-motion：
- 固定摄像机；
- 取消大幅移动、环绕和连续缩放；
- 使用状态切换和轻度淡入替代；
- 保留完整信息和章节顺序。
WebGL 不可用时，显示清楚的静态后备说明，不得留下空白页面。
禁止事项
- 不要把所有内容做成发光矩形卡片；
- 不要把 Three.js 当成动态背景；
- 不要用大量文字弥补对象设计不清晰；
- 不要让所有对象始终同时高亮；
- 不要让连线缺少方向和当前状态；
- 不要用粒子、光晕和旋转掩盖机制不清楚；
- 不要使用通用 SaaS Hero、Features、Stats、CTA 结构；
- 不要制造没有依据的数据、结果或指标；
- 不要引入与 Three.js、Anime.js 角色重复的第三方框架。
输出要求
默认交付一个完整、可直接保存运行的 HTML 文件，包含：
- HTML 结构；
- 响应式 CSS；
- Three.js 场景；
- Anime.js 时间轴；
- 滚动进度映射；
- 键盘上下章节导航；
- reduced-motion 降级；
- WebGL 错误处理；
- 必要代码注释。
如果项目复杂，可拆分为：
index.html
styles.css
main.js
scene.js
timeline.js
content.js
但必须保证入口清晰、无需补写核心代码即可运行。
验证
交付前依次检查：
结构检查
- 是否存在贯穿全程的核心对象；
- 不同概念是否具有不同造型；
- 系统内部与外部边界是否清楚；
- 当前路径与潜在路径是否可区分。
美术检查
- 是否在写场景前就锁定了一个具体美术方向，并贯彻到底；
- 调色板是否不超过 3 个颜色角色，且每个 hex 的语义在注释里写明；
- 是否避开了"AI 默认长相"清单（玻璃面板、黑底自发光、仪表盘 chrome、全语义彩虹色板）；
- 换掉美术方向能否解决，而不是靠调参数硬救。
叙事检查
- 每章是否只有一个主要焦点；
- 每次滚动是否带来一个有意义的变化；
- 前后阶段是否存在明确因果；
- 关键变化后是否有观察停顿；
- 向上滚动是否可以恢复状态。
构图检查
- 是否在写章节文字前就选定了一种文字-画面空间关系，并贯穿整页；
- 是否出现了"每章左右交替贴一个独立文字框"的模板化排版——出现就重做。
无文字测试
隐藏长说明后，仅看物体、路径和短标签，用户是否仍能复述主要过程。
静帧测试
在任何阶段暂停，是否能判断：
- 当前处理哪个对象；
- 系统处于什么状态；
- 刚刚发生了什么；
- 下一步可能发生什么。
技术检查
至少完成：
- HTML 结构检查；
- JavaScript 静态语法检查；
- 桌面尺寸检查；
- 移动尺寸检查；
- reduced-motion 检查；
- 浏览器滚动和反向滚动检查。
不得把静态检查描述为真实浏览器端到端验证。
完成标准
只有同时满足以下条件，任务才算完成：
- 视觉对象而非长文字承担主要解释；
- 用户始终知道当前应该看哪里；
- 滚动可以前进，也可以恢复旧状态；
- 动画表达机制变化，而不是单纯装饰；
- 桌面、移动端和低动态模式均可理解；
- 用户看完后能够复述完整过程及其因果关系。
先把知识转换成对象、关系、状态和事件，再用 Three.js 构建持续存在的视觉世界，用 Anime.js 将每个章节的局部滚动进度映射为可逆时间轴；文字只做标注，动画必须直接解释机制。