# Web Blender 项目现状与后续连续任务

更新时间：2026-08-12

## 1. 当前结论

项目已经形成可运行的 Web 三维编辑器工程骨架，但还不是“Web 版完整
Blender”。当前成熟度是：Web 基础设施和数据通路已成形，网格轻量化、骨骼
数据、packed image 和 GLB 已有专项实现；完整 Blender Depsgraph、完整 modifier
语义和 Blender 的全部工具仍不是当前承诺；已声明的 Mesh Edit、材质/UV、动画和对象层级
工作流均经过 Blender Main、撤销、原子保存和重开闭环。

浏览器端技术边界保持不变：React 负责界面，Three.js 负责全部实时渲染，
Blender C/C++ 子集编译为 WASM，OPFS 保存大文件，IndexedDB 保存小型元数据。
SQLite WASM 和 Bitbybit/OCCT 均不在当前依赖范围内。Three.js、WASM 和其他
运行时资源全部使用项目本地文件，不依赖 CDN。

## 2. 已完成并有测试覆盖的能力

| 能力 | 当前证据 | 状态 |
| --- | --- | --- |
| React + Blender 风格工作区壳 | Topbar、Viewport、Outliner、Properties、Timeline、状态栏和截图 golden | 已完成基础壳 |
| Three.js 本地渲染 | 本地 vendor、SceneIR 适配、选择/相机/网格显示 | 已完成基础链路 |
| Worker/C ABI/WASM 启动 | EngineWorker、错误协议、内存统计、离线 manifest 哈希 | 已完成 |
| `.blend` 数据读取 | 场景、对象、Mesh、非 Mesh 摘要、材质、图片、相机、灯光、动画和稳定 ID | 已完成已声明子集 |
| OPFS/IndexedDB | 项目、快照、LOD、SHA-256 资产、原子保存 journal 和 Worker 重启恢复 | 已完成当前存储链路 |
| Decimate/LOD | native Collapse、多比例 golden、边界和非流形专项、LOD 缓存发现 | 已完成已声明子集 |
| 蒙皮轻量化 | 四权重重映射、归一化、bind matrix 保留、shape key 重映射和策略阻断 | 已完成专项链路 |
| Blender 变形 golden | Blender 5.2 shape key + armature 基准及 Web 误差检查 | 已完成当前 fixture |
| Packed image | PackedFile、双 tile UDIM、generated、linked library、损坏签名、路径沙箱和 OPFS SHA-256 去重/重发现 | 已完成当前资源矩阵 |
| GLB | 本地导出、严格解析，以及 Blender 5.2 回导比较网格/PBR/纹理/morph/skin/animation | 已完成当前 SceneIR 子集 |
| Modifier/undo | modifier enable 状态、命令 revision、undo/redo 和专项 smoke | 已完成基础命令链路 |
| Mesh Edit | 点/边/面选择，Merge/Dissolve/Extrude/Inset/Bevel/Loop Cut，Main 保存重开 | 已完成当前操作集 |
| 材质与 UV | 材质槽/面分配、UV Map、planar/cube unwrap、限定 Principled/Image/Normal 图、图片打包 | 已完成当前节点集 |
| 动画编辑 | TRS 关键帧、Timeline/Dope Sheet、插值、Action 选择和约束开关/影响 | 已完成当前操作集 |
| 对象层级 | Parent/Unparent、Collection、rename、Join/Separate、Apply Transform、Origin | 已完成当前操作集 |
| SceneIR 扩展 | tangent/split normal/seam/sharp/vertex group/attribute/UV，native WBG1、资源 Delta 和 mesh byte-range patch | 已完成当前数据契约 |
| Sculpt 属性 | Mask/Face Set 的 SceneIR、WBG1 header v2、Delta、Main、undo 和保存重开 | 已完成属性子集；有界四笔刷 Main stroke 已开放，PBVH/完整求值未开放 |
| Simulation cache | Blender 5.2/source blend/hash/frame manifest、OPFS 内容寻址、schema 6、重启逐帧复验 | 已完成缓存安全层；Simulation evaluator 未开放 |
| Shader Main | RGB/Value/Principled/Image Texture/Normal Map/Output 整图事务、资源门和保存重开 | 已完成六节点写回子集；任意图/编译仍阻断 |
| NLA Main | 单对象 Action Clip 整栈写回、SceneIR 重开和 native frame 求值 | 已完成有限 Action Clip 子集 |
| 非 Mesh 数据块 | Curve/Surface/Font/Metaball Main 权威写回与保存重开、真实 evaluated mesh、PointCloud/Curves/Hair 属性、WNM chunks、双 viewport、desktop golden 与 7 对象 GLB/USD round-trip | 有界本地切片 in_progress；VDB renderer、完整 topology editor/跨对象 history/range patch、外部字体导入、跨浏览器 OPFS 性能仍阻断 |

## 3. 部分完成或仍有边界的能力

| 能力 | 已达到 | 尚未达到 |
| --- | --- | --- |
| Native Blender Depsgraph | Blender 5.2 full loader、ID 注册、viewport graph、tagged/frame 求值、复杂 rig 和 100 次重复门已在 wasm32 通过 | 新增 Blender 类型时继续扩大矩阵 |
| Modifier dependency graph | Blender 5.2 类型 0–86 已完整识别；27 类 native 白名单，其余 60 类身份保留并结构化阻断 | 后续扩白名单必须逐类增加 Blender golden，不属于当前矩阵完成条件 |
| 骨骼与层级 | Bone/parent/rest/pose、权重、joint ID、非单位 bind、四骨、父级缩放、IK、Copy Rotation 和 1/5/10/15 golden 已通过 | 新约束类型属于增量 fixture |
| GLB round-trip | Web 严格解析与 Blender 5.2 importer 双门已覆盖网格、变换、PBR、PNG/sRGB、sampler、morph、双骨骼 skin 和动画帧 | 新增相机/灯光、插值和材质扩展时继续扩大独立摘要 |
| `.blend` 保存 | 场景状态、modifier、Mesh Edit、材质/UV、动画/约束和对象层级命令均写 Main；历史、原子保存、快照和日志重放可恢复 | skin/shape-key decimate 保持结构化阻断 |
| Blender UI 对标 | 默认区域、当前 Mesh Edit、raycast、多选、拖拽 gizmo、层级/材质/动画面板和核心快捷键已闭环 | Sculpt、Geometry Nodes 编辑器等未声明能力继续结构化阻断 |
| 未声明能力扩展 | 四项协议/安全门均已细分；Sculpt 属性/有界 Main stroke、Simulation cache、六节点 Shader Main 和 Action Clip NLA Main 已有正例 | PBVH、GN lazy-function/Simulation 求值、其余 Shader Node、Web compiler、完整 NLA/UI/GLB 图映射仍 planned/结构化阻断 |
| 非 Mesh 数据块 | 1M 点 reader budget、ID_MB/PT/VO/VF 注册、Main control-point/topology/body/element/Font style link commands、一维多 spline 与批量 handle/cyclic、二维 Surface topology transaction、undo/save/reopen、真实 evaluated mesh、WNM SHA chunks、handle raycast/gizmo、7 对象 GLB/USD 和 Chromium quota | 多 handle 选择拖拽/gizmo UI、跨对象 history/range delta、新外部字体导入、VDB renderer/voxel upload 仍 planned/阻断 |
| 大场景 | Worker 二进制解码、per-mesh/range transferable、linked Mesh 实例化、LOD/OPFS cache、frustum culling、能力门 OffscreenCanvas Worker、100k/1M 内存门 | 超出当前 WBG1 的网络式渐进流送仍属于后续性能扩展 |
| Decimate 全对标 | Collapse 的当前网格集合已覆盖，错误路径结构化 | Un-Subdivide、Dissolve、所有 delimiter/权重/对称组合及大模型性能矩阵未完成 |

## 4. 关键安全门

`web_engine_evaluate_depsgraph` 现在直接执行 Blender 5.2 native loader、viewport
Depsgraph、tagged update 和 frame change。wasm32 DNA 重建器会递归恢复 64-bit
字段的 8-byte ABI 对齐，避免 `Scene.master_collection` 等成员错位；Web ID 注册表
覆盖 Scene、Collection、Object、Mesh、Material、World、NodeTree、Camera、Light、
Lattice、Curves 和 Grease Pencil。
空场景、基础场景和骨骼/Shape Key 场景均返回 `BlenderDepsgraph/EVALUATED`，并通过
Blender 5.2 变形 golden。任何 loader、graph 或输出结构错误仍必须返回结构化错误，
禁止伪造 Three.js 求值。

## 5. 后续连续执行顺序

以下任务按顺序领取。一个任务的验收未通过，不得把下一个任务标记为完成。

### N-001 恢复 native Depsgraph 安全求值（已完成，转入回归）

1. 建立最小 `empty/basic/rigged` full-loader fixture，单独验证 Main 所有权和释放。
2. 补齐 headless 初始化闭包：ID/CPP type、task scheduler、RNA 必要子集、NodeTree
   数据类型、sequencer modifier 和 image runtime；禁止链接桌面 WindowManager/GPU。
3. 修复 embedded NodeTree 的 ID/DNA 读取，加载阶段不得再产生 invalid embedded ID。
4. 分别验证 graph build、tagged update、frame change、graph free 和 Main free。
5. 连续求值 100 次，检查 live handles、WASM heap 增长和 Worker 重启恢复。
6. 重新启用 native capability，并将重复求值和 golden 纳入持续回归。

验收：三个 fixture 无 trap；最终 positions/indices 合法；rigged 最大/RMS 误差通过；
重复求值无持续泄漏。当前 fixture 已满足；frame/pose 回归已恢复，完整类型矩阵继续由
N-002/N-003 覆盖。

### N-002 Modifier/Depsgraph 能力矩阵（已完成）

1. 建立 Blender modifier 类型清单和 Web 支持矩阵；原生报告已先覆盖 UID、堆栈顺序、模式开关、跨对象依赖边、`EVALUATED/DISABLED/BLOCKED` 以及稳定错误码/建议。
2. 按数据依赖加入 Generate、Deform、Physics、Nodes 类，不按 UI 名称盲目链接；当前 27 类进入 native 白名单。simulation zone 无确定缓存时使用专项阻断；deterministic cache、更多节点、GP 和其余家族属于未来逐批扩白名单，不影响矩阵契约完成。
3. 对 modifier 顺序、viewport/render/edit/cage 开关、对象 target 和循环依赖做 golden；当前 category golden 已覆盖顺序/模式/target，专项 fixture 已覆盖双对象循环和缺 target。
4. modifier 参数编辑、apply、undo/redo、保存和重新打开必须使用同一 revision 协议。
5. 不支持的 modifier 返回类型、对象、参数和建议处理方式，不得静默跳过。

验收：白名单内结果与 Blender 5.2 golden 一致；白名单外全部结构化阻断。

### N-003 骨骼、Shape Key 与变形误差扩展

1. 覆盖多骨骼、多权重、非单位 bind matrix、父级缩放和多个 shape key。
2. 覆盖关键帧区间、Pose constraint、IK 前后的每帧矩阵和最终顶点。
3. 验证简化前后 joint 映射、权重归一化、shape key 相对基准和误差预算。
4. Blender desktop golden 与 native WASM 同时比较；Three.js 消费同一通过校验的 SceneIR/geometry buffer，并由跨浏览器非空像素门验证呈现链路。

验收：每个 fixture 同时满足拓扑、层级、bind matrix、最大误差和 RMS 误差门。

### N-004 Packed image 完整覆盖

1. 单 PackedFile、PackedFile 列表、UDIM/tile、generated image 和 library-linked resource 矩阵已覆盖。
2. 校验 MIME、原始文件名、相对路径、SHA-256、重复资产去重和损坏字节错误。
3. packed 数据进入 OPFS content-addressed asset，并验证刷新后可重新发现。

当前验收：`npm --prefix web run test:image-resources`，以及资产 E2E。SHA-256 去重、路径不可
逃逸项目目录和 OPFS Worker 重启发现均已覆盖。

### N-005 GLB Blender 级 round-trip（当前 SceneIR 子集已完成）

1. 扩展材质、纹理 sampler/色彩空间、morph、skin、animation interpolation 和 hierarchy。
2. 保留当前 Web 严格解析比较作为快速门。
3. 使用桌面 Blender 5.2 导入导出的 GLB，生成独立语义摘要。
4. 比较 node parent、mesh primitive/material、image、skin/joint/inverse bind、动画 channel。
5. warning 分成阻断错误、可接受近似和信息，不允许一条字符串混合多种严重度。

验收：Web 快速门和 Blender 再导入门均通过；所有差异进入机器可读报告。当前命令为
`npm --prefix web run test:glb-blender-roundtrip`，已覆盖显式 sampler、sRGB、morph、双骨骼
层级/权重和帧 1/25 动画。

### N-006 `.blend` 真正回写与恢复

1. 把对象/层级/modifier/mesh/armature/animation 命令写入权威 Blender Main。
2. 实现内存 `.blend` 写出、取消、OOM、OPFS 原子替换和校验和。
3. 保存后清空 Worker，重新打开文件并比较 SceneIR、Depsgraph 和 GLB 摘要。
4. 将 undo/redo 与保存点、自动保存和崩溃恢复统一到 revision 日志。

当前协议命令集已覆盖 frame/visibility/modifier、普通 decimate 的 Main 写入、内存保存和清空
后重开比较；标准 write-file callback 不使用 undo MemFile，动画与 Pose constraint 已通过两代
写出后 animation 1/5/10 与 pose 1/5/10/15 帧等价回归。历史栈恢复 Main，OPFS 以 staging/journal/manifest/SHA-256 原子提交，
并在两个故障点完成新 Worker 恢复。skin/shape-key decimate 继续以
`BLEND_WRITE_REQUIRES_MAIN_AUTHORITY` 阻断；N-007 的 primitive/duplicate/delete/TRS/顶点平移
已复用同一 Main/history/save 契约。

验收：编辑不再只存在于 JSON snapshot；已支持命令重新打开 `.blend` 后语义一致，
其余命令必须明确阻断，不能伪造成功。

### N-007 建模和 UI 对标扩展

当前验收切片已完成 primitive、duplicate、delete、TRS、点/边/面选择、Merge、Dissolve、
Extrude、Inset、Bevel、Loop Cut、raycast、多选、拖拽 gizmo、层级/Collection/Join/Separate、
Apply Transform/Origin 和核心快捷键，并通过 Main/history/save/reopen 门。

### N-008 质量与发布门

100k/1M 性能与内存、Worker 故障、OPFS quota、恶意 `.blend`、许可证、本地依赖和离线
dist 门已完成。N-008 记录的多引擎结果只作为历史证据；后续验收统一以 Chromium 为唯一
浏览器基线。

### N-009 快照、日志与崩溃重放

Schema 6（含 Simulation manifest）、SHA-256 快照保留、命令阈值、revision 排序、损坏隔离、保存点清理，以及提交后
命令重放已完成。验收见 `docs/status/N-009.md`。

### N-010 可复现离线交付

确定性二进制包、对应源码包、source offer、license/notice、文件 manifest 和顶层
`SHA256SUMS.txt` 已纳入连续两次生成摘要一致门。验收见 `docs/status/N-010.md`。

### N-011 至 N-014 未声明能力扩展（有限子集 in_progress）

Sculpt、Geometry Nodes/Simulation、Shader Node 图和 NLA 的详细任务分解、依赖顺序、
协议字段、稳定错误码、停止条件和默认验收命令统一维护在
`docs/UNDECLARED_CAPABILITIES_EXECUTION_PLAN.md`。当前四项均进入
`in_progress`：四项都已超过纯协议阶段，但只开放经过 native/存储闭环验证的有限切片：
Sculpt Mask/Face Set 与有界 Main stroke、GN 外部资源门与 deterministic cache 存储、七节点
Shader Main 写回（含有限 Math）和常量 PBR 映射、单对象 Action Clip NLA Main/Depsgraph reverse/repeat 求值。详细完成项和 planned 项见专项计划；
这些正例不扩大到 PBVH Sculpt、任意 GN/Simulation、任意 Shader Node/Web compiler 或完整 NLA。
Blender 5.2 全域功能矩阵、浏览器/服务端边界和 N-015 至 N-026 后续顺序见
`docs/BLENDER_5_2_WEB_FEATURE_PARITY.md`。

### N-015 非 Mesh 几何数据块（有界本地切片 in_progress）

`NonMeshDataIR`、native SDNA reader、Main 权威 Curve/Surface/Font/Metaball 写回、bounded Poly Curve create/delete、Poly/Bezier conversion、非 Mesh 数据块 rename、Curve 有界 topology/Font geometry、undo/redo、
save/reopen、真实 legacy evaluated mesh、PointCloud/Curves 属性和 WNM 二进制分块已经接通。
主线程与 OffscreenCanvas 消费同一 chunks；GLB 只接受真实 evaluated mesh，USD 提供
`UsdGeomMesh`、`UsdGeomPoints`、`UsdGeomBasisCurves` 和 `OpenVDBAsset` 的机器可读映射/损失。
VDB renderer、完整 Curve handle/cyclic topology editor、二维 Surface mutation、跨对象 history/range patch、新字体导入和跨浏览器 OPFS quota 仍按
`docs/status/N-015.md` 的阻断项推进。

### PBR-001 至 PBR-012 模型物理渲染（核心切片 done_current_scope，资产/高级渲染安全门 in_progress）

`physical-v1` 已完成扩展 Principled 参数的 Main 写回/保存重开、双后端
`MeshPhysicalMaterial`、ACES/sRGB、World exposure、场景灯方向和有界 PCF 阴影。PBR-007
现已接通 SHA-256 GPU 纹理载荷、颜色空间、尺寸预算、ImageBitmap 解码和双后端状态；PBR-008
现已接通 UDIM manifest/缺失资源/多 tile 结构化阻断；PBR-009 已支持有限 packed raster
equirectangular PMREM/IBL 生命周期；PBR-012 已提供 WebGPU、任意 Shader、Volume/SSS 和
高级后处理的能力查询门。HDR/EXR、多 tile 采样、context-loss 恢复、真实 WebGPU renderer、
高级 pass 和未声明 Shader 家族仍不得声称完成。架构映射、细分状态、停止条件和验收命令统一维护在
`docs/PBR_RENDERING_IMPLEMENTATION_PLAN.md`。

## 6. 当前验收命令

```bash
source tools/web/emscripten-env.sh
cmake --build build_web_blender6 --target web_engine -- -j8
bash tools/web/install-web-engine-assets.sh
bash tools/web/check-dual-engine.sh
node tools/web/run-web-engine-smoke.mjs
npm --prefix web run typecheck
npm --prefix web run lint
npm --prefix web test
npm --prefix web run test:golden
npm --prefix web run test:frame-evaluation
npm --prefix web run test:pose-constraint-goldens
npm --prefix web run test:main-roundtrip
npm --prefix web run test:authoring-roundtrip
npm --prefix web run test:modifier-goldens
npm --prefix web run test:modifier-cycle
npm --prefix web run test:modifier-matrix
npm --prefix web run test:image-resources
npm --prefix web run test:glb-blender-roundtrip
npm --prefix web run test:depsgraph
npm --prefix web run test:collapse-ratios
npm --prefix web run test:topology-collapse
npm --prefix web run test:capability-gates
npm --prefix web run test:simulation-cache
npm --prefix web run test:release-performance
npm --prefix web run test:malicious-blends
npm --prefix web run test:browser
npm --prefix web run release:offline
WEB_TEST_PORT=5193 npm --prefix web run test:e2e  # 5173 被占用时指定可用端口
WEB_TEST_PORT=5193 npm --prefix web run test:e2e -- -g "N-015|non-mesh"
```

`test:depsgraph` 默认执行 `DEPSGRAPH_REPEAT=100`；本地快速迭代可显式设置为较小的
正整数，但提交前必须使用默认值。

每次完成 N-001 至 N-015 的一个任务切片，都必须更新本文件、对应 `docs/status/`
记录、fixture/golden 和验证输出。