# Blender/Web 移植后续执行安排

更新时间：2026-08-26（America/New_York）

## 1. 目标与当前结论

目标是让 Web 版本在 Chromium 中形成可持续的 Blender 工作流：打开 `.blend`、读取 SceneIR、执行受约束的 Main mutation、保存/重开、恢复和导出，并且每项声明都绑定可复现证据。

当前基线已经可以正常工作，但还不能宣称“与 Blender 全量 parity”：

- quick CI 已修复 Node 堆内存问题：7/7 lane READY，128 个 unit 文件隔离执行。
- Blender 5.2 inventory 有 6,900 条记录，聚合为 15 个 capability family；当前记录仍是 `L0 / METADATA_ONLY`。
- P7-002 已生成 45 个原子任务，即 15 个 family 乘以 `desktopPositive`、`wasmMutation`、`saveReopenExact`。
- P7-003 的恢复链为 READY，但 `parityClosure` 和 `releaseDecision` 为 BLOCKED；当前 9/45 atomic 行为已有可审计 Chromium receipt。
- M12 有 82 条、42 个路径的 SHA 漂移；Git-history snapshot 已恢复 22 条，剩余 60 条保持 `BLOCKED_SOURCE_LOST`，历史 manifest 不得重写。

因此后续安排分为两条并行轨道：

1. 新证据驱动的 Blender/Web 正向移植。
2. M12 原始来源快照恢复与 provenance 重建。

当前机器整合入口为 `node tools/web/generate-wbv2-integration-readiness.mjs`，输出 `tests/golden/WBV2-P7-003/integration-readiness-report.json`；该报告是继续开发的 checkpoint，不是 parity 成功声明。

## 2. 不可违反的规则

1. 只使用 Chromium 作为浏览器证据；Firefox/WebKit 不进入本计划的验收范围。
2. 旧 manifest 的原始 SHA、时间线和状态不可改写。新发现只能追加 corrective evidence。
3. 一个执行任务只负责一个主要行为。共享代码可以复用，但每个行为必须有独立 fixture、报告和 manifest。
4. `FEATURE_PARITY` 只有在以下条件同时满足时才能出现：
   - Blender desktop 正向结果；
   - WASM/Main 正向 mutation；
   - save/reopen 精确保持；
   - Chromium 生产路径通过；
   - malformed、unsupported、cancel、duplicate、over-budget 和 hash-drift 负例均 fail-closed。
5. 任何失败都保持 `in_progress` 或 `blocked`，不能手工推进 `nextTask`。
6. 所有产物必须由 generator/checker 生成，并由 SHA-256 manifest 绑定。

## 3. 阶段安排

### 阶段 A：构建与证据基础设施（第 1-2 天）

目标：让桌面 binary、WASM binary、测试 runner 在同一工作区可重复运行。

工作项：

- 重新配置 `build_blender_5.2.0` 的 CMake cache，使 RUNPATH 指向当前工作区的依赖目录；禁止依赖 `/home/mes123456/working` 的隐式路径。
- 记录 Blender、Emscripten、Node、Chrome、依赖库版本和 SHA；生成一份可复现环境 receipt。
- 保持 `tools/web/run-unit-tests.mjs` 的隔离策略，quick lane 每次提交都运行。
- 为 generated-gap checker 抽出通用的 `open -> snapshot -> mutate -> save -> reopen -> negative` runner，减少各任务重复代码。
- 统一 comparator：对象 ID、Main revision、delta、资源 hash、save/reopen hash 必须使用 canonical JSON 比较。

完成条件：

- `cmake --build build_blender_5.2.0 -j2` 成功；桌面 binary 在不依赖旧工作区路径的情况下启动。
- quick CI、typecheck、lint、context governance 全部通过。
- 同一 fixture 连续生成两次字节一致。

### 阶段 B：三条现有正向链路固化（第 3-5 天）

目标：把已有 C5 pilot 的 Mesh、Modifier、Asset 能力转成标准 Web evidence 模板。

复用模块：

- `web/protocol/corrective-main-transaction.ts`
- `web/protocol/corrective-mesh-command.ts`
- `web/protocol/corrective-modifier-command.ts`
- `web/protocol/corrective-asset-catalog-command.ts`
- 现有 C5 Chromium family reports 和 save/reopen checker

每个 family 必须补齐：

- desktop positive fixture；
- WASM/Main mutation 和 revision 变化；
- undo/redo 与 save/reopen；
- Chromium production interaction；
- malformed payload、stale revision、missing target、budget overflow 负例。

完成条件：

- 三个 family 的 evidence 从 `CANDIDATE` 变为可审计的正向结果。
- 旧 C5/M12 证据只读消费，不改变历史 SHA。
- 共享 runner 能在单条命令中重复三族验证。

### 阶段 C：按风险批量移植高价值 family（第 2-3 周）

采用“一个共享能力实现 + 三个原子证据任务”的节奏。实现一次，证据拆成三个独立任务，不为 6,900 条 legacy 记录重复造轮子。

优先级如下：

| 顺序 | family | 规模 | 先解决的问题 | 主要复用方向 |
| --- | --- | ---: | --- | --- |
| 1 | `UI_EDITOR` | 3,930 | editor/context/keymap 与 Chromium 输入一致性 | editor workflow、keyboard/pointer/input-modal |
| 2 | `MEDIA_IO` | 585 | import/export、媒体资源、外部依赖与 loss report | GLB/OBJ/PLY/STL、asset sandbox、media recovery |
| 3 | `NODES_GRAPH` | 543 | Geometry Nodes/shader allowlist、预算和 compile rollback | geometry-nodes、shader-compiler、render budget |
| 4 | `MESH_EDITING` | 431 | 选择、拓扑 mutation、binary delta | mesh command、mesh geometry delta、topology comparator |
| 5 | `OBJECT_OPERATIONS` | 316 | transform、parent、collection、undo/redo | Main transaction、scene delta、selection history |
| 6 | `RIG_ANIMATION` | 375 | Action、TRS、pose、constraint、skin | animation、NLA、armature、skin protocol |
| 7 | `MATERIAL_RENDER` | 125 | PBR/UV/texture 与渲染路由 | shader graph、render routing、packed assets |
| 8 | `SIMULATION` | 155 | cache identity、cancel、quota、restart | simulation cache、worker fault、storage journal |
| 9 | `SCULPT_PAINT` | 117 | PBVH 限制、笔刷/笔画和非 mesh slice | sculpt、paint、non-mesh binary |
| 10 | `CORE_SCENE_GRAPH` | 66 | Scene/Collection/Object/Depsgraph canonical state | SceneIR、stable IDs、world matrices |
| 11 | `CORE_DNA_RNA` | 38 | RNA metadata read and unsupported retention | reader metadata、unknown-field preservation |
| 12 | `CORE_MESH` | 31 | Mesh datablock schema and attributes | binary mesh、attribute domains |
| 13 | `OTHER_OPERATOR` | 103 | 无法归入高阶 family 的小范围 operator | explicit unsupported/EXCLUDED routing |
| 14 | `CORE_OBJECT` | 2 | Object identity/read compatibility | scene graph reader |

`MODIFIER_SYSTEM`（83）虽然 legacy 记录相对完整，也必须经过同样的 WASM mutation 和 persistence 证明，不能仅凭旧 completed 状态提升 parity。

每个 family 的固定工作包：

1. 选 1 个最小可观察行为，建立 Blender fixture 和 canonical expected state。
2. 在 `web/protocol` 建立或复用 bounded command，统一走 Main transaction。
3. 接入 `web_engine_blend_reader.cpp`，只读取声明的数据，不执行任意 Blender operator 或脚本。
4. 添加桌面 checker、WASM checker、Chromium e2e、unit negatives。
5. 生成该 family 的三个原子 manifest，只有三项证据均通过时才提升 capability 状态。
6. 通过 handoff 后再由 generator 激活下一个任务。

### 阶段 D：完整 45 项原子队列关闭（第 3-4 周）

目标：逐项清空 P7-002 队列，但不把同类 legacy 记录重复实现。

每项任务的最小证据包：

- fixture 和 generator；
- desktop report；
- WASM/Main report；
- Chromium report（涉及生产交互时必须有）；
- persistence/hash report；
- negative matrix；
- status、manifest、task-context；
- parent manifest SHA 和当前 source/build SHA。

队列推进规则：

- 始终只有一个 `active + ready`；
- 当前任务完成后由 manifest 的 `nextTask` 决定下一项；
- 任何 hash drift、环境缺失或测试失败都停在当前任务；
- 每完成一个 family，重新计算 6,900 条 legacy 覆盖映射，已证明的记录保留 regression coverage。

### 阶段 E：M12 provenance 恢复（与阶段 C/D 并行）

这条轨道不依赖 Web 功能实现，责任人必须提供以下任一权威来源：

- 原始 immutable repository snapshot；
- 带签名的 M12 artifact archive；
- CI artifact store 中可验证的原始文件和时间戳。

恢复步骤：

1. 只读导入来源，计算原始 SHA，不覆盖当前文件。
2. 将原始文件与当前观察值做逐项三方比较：`original manifest`、`source snapshot`、`current worktree`。
3. 对能复原的条目生成 `PROVENANCE_RESTORED` corrective evidence。
4. 对仍无法复原的条目保留 `BLOCKED_SOURCE_LOST`。
5. 只有 provenance checker 和 protected hash checker 同时通过，才允许影响 release gate。

在来源恢复前，禁止以下行为：

- 用当前文件反推旧文件；
- 用新 manifest 覆盖旧 manifest；
- 删除 drift entry；
- 把 `BLOCKED_SOURCE_LOST` 改成 `READY` 或 `FEATURE_PARITY`。

### 阶段 F：Release closure（第 5 周）

只有阶段 D 和 E 都完成后执行：

- 重新生成完整 capability parity map；
- 统计 `FEATURE_PARITY`、`READ_COMPATIBILITY`、`NEGATIVE_BOUNDARY`、`EXCLUDED`、`BLOCKED`；
- 运行 quick、Chromium、release、offline、SBOM、rollback 全套 lane；
- 检查所有声明都绑定 manifest 和 immutable source/build SHA；
- 生成 known limitations 和最终 release decision。

release decision 的允许状态：

- `READY`：所有目标 capability 达到声明级别，历史 provenance 完整；
- `BLOCKED`：存在任何未闭合 parity、来源丢失、hash drift、负例不安全或 release lane 失败；
- 不允许使用“近似完成”或隐式降级状态替代上述两种状态。

## 4. 每周产出与效率指标

每周必须产出：

- 完成的 capability family 数；
- 新增正向 desktop/WASM/Chromium evidence 数；
- 从 L0 提升的 legacy 覆盖条目数；
- 仍为 BLOCKED 的条目数及原因分布；
- quick CI 平均耗时与峰值 Node heap；
- fixture 重生成字节一致率；
- M12 provenance 恢复条目数。

建议效率目标：

- 每个 family 至少关闭 3 个原子行为证据，覆盖同族 legacy 记录；
- 每周完成 3-5 个 family，而不是逐条处理 6,900 个 legacy operator；
- 每个 family 的重复 checker 代码不超过一个模板文件的 20%；
- quick lane 保持单次提交可运行，Chromium lane 在 family 合并前运行；
- 失败任务平均恢复时间小于一个工作日，且不通过改历史证据解决。

## 5. 当前立即执行顺序

1. 修复 `build_blender_5.2.0` 的 workspace RUNPATH，并生成环境 receipt。
2. 用现有 C5 Mesh/Modifier/Asset 证据跑通统一 family runner。
3. 激活 P7-002 队列中第一个高风险 family 的 `desktopPositive` 任务。
4. 依次完成该 family 的 `wasmMutation` 和 `saveReopenExact`，再推进下一个 family。
5. 每个 family 完成后更新 parity map 和风险报告，但不修改 M12 历史 manifest。
6. 并行向 provenance 责任人索取 M12 immutable snapshot；在收到前保持 release gate BLOCKED。
7. 只有 45 项原子任务和 M12 provenance 都闭合，才重新运行 P7-003 release gate。

## 6. 回滚与停止条件

出现以下任一情况时立即停在当前任务：

- desktop 与 WASM/Main 状态不一致；
- save/reopen 改变 Main revision、资源 hash 或稳定 ID；
- malformed/unsupported/cancel/over-budget 输入改变 Main；
- source/build/fixture/manifest hash 漂移；
- CMake、Node heap、Chromium 或 Blender 环境不可复现；
- M12 来源仍不可验证。

回滚只删除当前新任务的 fixture、报告、manifest、status 和 context，恢复 parent 的 queue tail；不得触碰已完成任务的历史 evidence，也不得把失败任务标成完成。

## 7. 完成定义

本计划只有在以下条件同时满足时才算完成：

- Web 生产路径可在 Chromium 中完成 open/edit/undo/redo/save/restart/reopen/export；
- 15 个 capability family 的目标 parity level 有逐项证据；
- 45 个原子行为任务全部完成或明确 `EXCLUDED/BLOCKED` 并有原因；
- 负向边界、资源预算、取消、重启、OOM、quota、device loss 均 fail-closed；
- M12 historical SHA 的可复原部分有权威 source snapshot，剩余部分明确保留 blocked；
- quick/Chromium/release/offline/SBOM/rollback 和 protected hashes 全部通过；
- 最终 release gate 不依赖人工解释或手工重写历史文件。

## 8. 项目完成情况总表（整合视图）

这里的“完成”严格指对应任务的机器验收和 manifest handoff 已完成，不把它扩大解释为 Blender 全产品 parity。

| 区域 | 机器状态 | 已有成果 | 仍需整合的内容 |
| --- | --- | --- | --- |
| P0 事实与合同 | 3/3 done | scope、6,900 条 Blender 5.2 inventory、capability/error/budget contract | 将 inventory 条目映射到最终 `FEATURE_PARITY`、`READ_COMPATIBILITY` 或 `EXCLUDED` |
| P1 Runtime/Main | 5/5 done | single/pthread receipt、SceneIR stable ID、Main transaction/history、Worker lifecycle、OPFS/IndexedDB recovery | 将所有后续 family runner 统一接入同一 revision/generation/store |
| P2 核心建模闭环 | 5/5 done | open/context、transform/hierarchy、mesh edit、双 viewport、open-edit-undo-redo-save-reopen | 将已有 P2 证据作为 family regression，不重复实现基础 writer |
| P3 Authoring/IO | 5/5 done | material/UV、animation、rig/skin、GLB round-trip、library append/link/override | 补齐各 family 的统一 WASM mutation receipt 和 Chromium 生产证据 |
| P4 高级本地切片 | 4/4 done | modifier、Geometry Nodes/shader、sculpt/non-mesh/paint、simulation cache | 将能力边界、预算和 recovery 结果汇入 capability ledger |
| P5 Render/Server | 3/3 done | render routing、media recovery、server job binding | 保持 local/server/excluded 分类，不把 server 结果当作本地 parity |
| P6 安全/发布 | 3/3 done | default-deny scripting、故障矩阵、offline/CI/SBOM/rollback | 修复构建环境 receipt 的可复现路径，避免旧工作区依赖 |
| P7 差距程序 | P7-001/P7-002 done，P7-003 blocked | 15 family、45 原子行为任务、release gate；9/45 Chromium receipt 已绑定 | 剩余 36 项 WASM mutation/persistence/Chromium 证据和 M12 provenance |
| Quick CI | READY | 7/7 lane，128 个 unit 文件隔离执行 | 每次 capability 合并继续作为必需回归，不重引入单进程 OOM |
| M12 历史证据 | BLOCKED_SOURCE_LOST | 82 条、42 路径 drift ledger；Git-history snapshot 恢复 22 条，历史文件保持不变 | 取得剩余 immutable snapshot 或签名 artifact 后只读重建 provenance |

## 9. 不重复开发的模块所有权

所有后续工作先按以下所有权表复用；除非现有接口无法表达新行为，否则不创建第二套协议、store、runner 或 comparator。

| 能力 | 唯一生产入口 | 复用的现有证据/测试 | 允许新增的最小内容 |
| --- | --- | --- | --- |
| 文件读取和 SceneIR | `web_engine_blend_reader.cpp`、`web/protocol/scene-ir.ts` | P1/P2/P7 reader receipts | 新字段的 typed parser、fallback、schema negative |
| Main mutation/history | `web/protocol/corrective-main-transaction.ts` 与现有 Main state | P1-003、P2-002、P2-005 | 一个 bounded command 和对应 transaction case |
| Mesh | `corrective-mesh-command.ts`、mesh delta comparator | C5 Mesh、P2-003 | 新拓扑/attribute case，不复制 transaction |
| Modifier | `corrective-modifier-command.ts` | C5 Modifier、P4-001 | 一个声明参数或 apply slice |
| Asset/library | `corrective-asset-catalog-command.ts` 与 library protocols | C5 Asset、P3-005、M12 library receipts | 新 ownership/reload case，不重写 catalog schema |
| 渲染与节点 | render routing、shader/geometry-node protocols | P4-002、P5-001、M12 format receipts | 只添加 allowlist/预算条目 |
| Worker/存储/recovery | runtime lifecycle、OPFS/IndexedDB journal | P1-004/P1-005、P4-004、P6-002 | 新 fault injection 或资源计数，不新建 recovery store |
| CI/release | `run-ci-lane.mjs`、release checkers、manifest | P6-003、quick report | 新 lane 仅在现有 lane 无法表达时增加 |

禁止事项：为同一行为同时新增一个 Web protocol 和一个 corrective protocol；为同一 family 同时维护手工 expected JSON 和 generator 产物；用 UI 像素相似度替代 Main/SceneIR 语义比较。

## 10. 统一整合数据流

所有能力证据按同一条数据流进入 ledger，任何环节缺失都不能提升 parity level：

```text
Blender fixture/generator
        |
        +--> desktop checker --> canonical semantic report
        |
        +--> WASM reader --> SceneIR snapshot --> Main bounded mutation
                                      |
                                      +--> save/reopen + stable-ID/hash report
                                      |
                                      +--> Chromium production interaction
                                                        |
                                                        +--> negative/recovery report
                                                                    |
                                                                    +--> manifest/status/ledger
```

整合时只比较 canonical semantic state：stable ID、Main revision、delta、拓扑/属性、资源 hash、错误码和 save/reopen state。`.blend` 原始字节只用于来源完整性和 fixture 保护，不把 Blender 进程指针字节误当成业务差异。

生成器规则：首次 fixture 生成可以写入目标；验证重跑必须保留已存在目标。P7-003 已实现这一规则，后续 generator 统一采用同一约定，避免重复触发二进制 hash drift。

## 11. 队列整合策略

当前 P7-003 是 release gate，不是新的功能 family。它在 `nextTask=null` 时必须停留在 blocked；不得从历史文档猜测 successor，也不得把 P7-003 改成一个批量实现任务。

队列重新打开的唯一条件：

1. P7-003 依赖的 release receipt、fixture、generator、reports、status、task-context 的 SHA 全部通过 handoff。
2. 由新的机器 manifest 明确给出 successor；手工修改 `nextTask` 无效。
3. successor 只领取一个 family 的一个行为，先完成 `desktopPositive`，再完成 `wasmMutation`，最后完成 `saveReopenExact`。
4. 同一 family 的 Chromium、negative 和 recovery 证据作为该行为的必需门，不另起重复功能实现任务。
5. family 完成后只更新 parity map 和 regression coverage，不修改已完成任务的历史 manifest。

如果现有 45 项原子队列的实现类别与 capability matrix 不一致，先新增一个“分类修正”证据任务，由 generator 重新输出 `READ_COMPATIBILITY`/`EXCLUDED`/`SERVER_EXACT`；不能直接把 metadata-only 或 negative-only 记录标成 feature parity。

## 12. 分阶段整合安排

### I. 基础环境和证据入口

- 重新配置或封装 Blender desktop 运行环境，消除 `/home/mes123456/working` 的隐式 RUNPATH；记录 Blender source/build、Emscripten、Node、Chromium 和依赖库 receipt。
- 抽出一个 family runner 外壳，参数只包含 fixture、行为 catalog、desktop checker、WASM command、Chromium case 和负例集合。
- comparator 统一输出 canonical JSON 和 SHA；命令输出写入任务 evidence 目录，manifest 只绑定最终构件。

### II. 复用现有 C5 正向链路

- 先整合 Mesh、Modifier、Asset 三个已有 pilot，不改它们的协议语义。
- 对每个 pilot 补齐同一个证据形状：desktop state、WASM/Main revision、undo/redo、save/reopen、Chromium result、malformed/stale/missing/budget negatives。
- 三个 pilot 只能在证据字段齐全后提升为 capability ledger 的正向候选；旧 C5/M12 SHA 只读消费。

### III. 按收益和风险推进 family

- 首批：`MESH_EDITING`、`OBJECT_OPERATIONS`、`MEDIA_IO`，因为已有 P2/P3/C5 可复用且能覆盖大量 legacy regression。
- 第二批：`MODIFIER_SYSTEM`、`NODES_GRAPH`、`RIG_ANIMATION`、`MATERIAL_RENDER`。
- 第三批：`SIMULATION`、`SCULPT_PAINT`、`CORE_SCENE_GRAPH`、`CORE_MESH`。
- 最后处理 `UI_EDITOR`、`CORE_DNA_RNA`、`OTHER_OPERATOR`、`CORE_OBJECT`：优先做 read-compatibility 或 explicit excluded 分类，只有存在真实 Main writer 时才创建 mutation task。

每个 family 只选择一个最小可观察行为作为实现入口，已覆盖的 P2/P3/P4/P5 行为直接引用 regression receipt，不重复造 fixture 或 command。

### IV. M12 provenance 并行轨道

- 接收 immutable repository snapshot、签名 artifact archive 或 CI artifact store 原件后，先只读计算原始 SHA。
- 可先从本仓库 Git 历史提取精确匹配项：`node tools/web/build-m12-git-snapshot.mjs`，再执行 intake；该过程不读取或重写当前工作树。
- 统一入口：`node tools/web/intake-m12-immutable-snapshot.mjs --write`；收到快照时追加 `--snapshot <目录或 snapshot-manifest.json>`，工具只读校验并输出 `tests/golden/corrective/rehydration/M12-provenance-intake.json`。
- 运行三方比较：original manifest、source snapshot、current worktree。
- 可复原项生成 `PROVENANCE_RESTORED` corrective evidence，无法复原项继续保留 `BLOCKED_SOURCE_LOST`。
- provenance 修复不得修改 M12 历史 manifest，不得删除 drift entry，也不得覆盖当前工作树文件。

### V. Release closure

- 45 项行为证据和 M12 provenance 都满足后，重新生成 parity map、known limitations 和 release decision。
- 依次运行 quick、Chromium、release、offline、SBOM、rollback 及 protected-hash gates。
- 只有 `FEATURE_PARITY`、`READ_COMPATIBILITY`、`SERVER_EXACT`、`EXCLUDED`、`BLOCKED` 的数量和原因都可从机器证据重算时，才允许 release `READY`。

## 13. 每个整合任务的交付模板

```text
<family>/<behavior>/
  fixture.blend or source fixture reference
  generator.py or generator.mjs
  desktop-report.json
  wasm-main-report.json
  chromium-report.json (when production interaction is involved)
  persistence-report.json
  negative-report.json
  manifest.json
  status.md
  task-context.json
```

交付前固定运行：focused command、determinism check、desktop/WASM comparator、save/reopen、negative matrix、manifest hash、context governance、typecheck/lint 和 quick CI。任何一个命令失败都保留 `in_progress`/`blocked`，不创建 successor。

## 14. 项目级完成判定

项目整合完成需要同时满足：

- P0-P6 的已有生产实现全部由同一 SceneIR/Main/Worker/storage/CI 入口消费；没有重复协议或第二套状态源。
- 已实现能力、只读兼容能力、server/excluded 能力和真正未完成能力可以从 ledger 自动区分。
- P7 inventory 的 6,900 条记录均有稳定 family/implementation class/证据映射；不要求每条记录都拥有独立 writer。
- 45 项原子行为已完成，或明确标记为 `READ_COMPATIBILITY`、`SERVER_EXACT`、`EXCLUDED`、`BLOCKED` 并绑定原因。
- Chromium 是唯一浏览器验收入口，quick CI 保持稳定，不再出现 Node exit 134。
- M12 可复原 SHA 有权威来源；不可复原项继续显式 blocked。
- release gate 可以只从 manifest、status、ledger 和 immutable source/build hash 重新计算，无需人工解释或历史重写。