f3e21c6b98
Accumulated uncommitted work: GHOST Web backend, WebGL/GPU web layer, web workflow engine and protocol, tooling, docs and task records. Large generated evidence, user-testing archives, build snapshots and imported test assets remain untracked. Co-Authored-By: Claude Code <noreply@anthropic.com>
86 lines
12 KiB
Markdown
86 lines
12 KiB
Markdown
# 执行上下文规则
|
||
|
||
本仓库的任务执行必须使用最小上下文。不要把完整路线图、项目状态、parity ledger 或全部 `docs/status/` 日志作为默认上下文。
|
||
|
||
领取任务时只做以下操作：
|
||
|
||
1. 阅读 `docs/EXECUTION_QUEUE.md`。
|
||
2. 运行 `node tools/web/print-task-context.mjs`；它只会输出当前任务、parent manifest、parent status 和聚焦命令。
|
||
3. 只打开输出中列出的任务卡、生产入口、测试入口和最小 fixture。
|
||
4. 全部功能实现前不运行上下文检查或其他验证命令。直接依据当前任务卡与 parent `nextTask` 工作，不要手工推进队列。
|
||
|
||
默认上下文预算：队列 4 KiB、任务卡 8 KiB、parent manifest 24 KiB、parent status 6 KiB，合计约 3,500 tokens。历史和长期文档只能按任务卡列出的具体小节追加读取。
|
||
|
||
实现阶段只记录任务报告、manifest、status 和聚焦实现变更，不运行验证命令。下一任务只认新 manifest 的 `nextTask`。
|
||
|
||
## 移植铁律
|
||
|
||
- **验证前置条件优先。** 验证时，先准备前置条件，之后再验证；前置条件准备也必须考虑依赖关系和先后顺序，以提高验证的准确性和效率。按依赖顺序准备构件与资源、运行环境、服务与接口、数据与场景；前置条件不满足时先补齐，不重复运行依赖它的下游验证。复用仍有效的前置检查结果，环境或依赖变化后仅重新检查受影响项；如实记录缺项、失败及验证范围。
|
||
- **按合理的小批次推进。** 每批只处理一个明确业务缺口及其必要调用链；单次读源码≤30行、修改≤2文件且增删合计≤10行（含交接）。按实际字节控制提交提示、交接与工具输出，区分已统计内容与系统附加内容；断流/超量后缩小下一批，连续稳定交接后才有界放宽。达到预算先保留源码与continuationNotes（断点、已完成、残余、下一动作）再续接，禁止堆叠全量历史、盲目重发大包或靠删缺口缩量；不改变实现期禁止验证的规则。
|
||
- **当前工作定位：用户明确“桌面 Blender → Web Blender 移植”基本完成，后续仅以补充具体功能缺口为主，不得重新开展整体移植或偏离主线。科学、高效率地充分复用已有源码、模块、适配接口、WASM 和应用产物，使操作者能使用全面完整的功能。**
|
||
- 领取任何补缺工作，先定位对应业务的已有实现和最新交接，只修改明确缺失、未接通或阻塞实际操作的环节。历史任务卡的 planned/in_progress、旧 remaining 或未验证状态，不得单独作为重新实现已有功能的依据；不得将补缺扩大成无关重构、重复造轮子或无限底层加固。
|
||
- 无人值守执行者必须自行定位并处理空转、阻塞、冷却、反复重启、等待和遗漏，完成查缺补漏。每个问题必须对应具体原因、受影响的用户功能和下一修复动作；同一路径反复失败应改变有源码依据的修复策略，保留部分成果并继续可独立推进的缺口，不得只重复报告或盲目重启、重编译。外部限流或权限限制应如实分类并合理退避，不得绕过限制或伪称已解决。
|
||
- “基本完成”是本阶段复用成果、聚焦补缺的工作定位，不等于所有功能已验证或验收通过。实际残余缺口必须保留并解决；不得通过删除缺口、调整统计、推进队列或编译成功来宣称完整可用。
|
||
|
||
- 为了正常推进移植项目工作，用户已授权执行代理在无人值守流程中自主完成必要工作，包括自行修改 Blender 源码、Web/WASM 适配层、协议、Worker、前端入口、构建脚本和任务交接产物；无需为常规实现动作重复请求确认。所有修改仍须遵守本文件其余铁律，并如实记录未验证状态。
|
||
|
||
- 功能先打通，只有全部功能实现完成后，用户才在使用时验证。全部功能完成是主要工作，中途不进行任何形式的验证，包括测试、回归、冒烟、浏览器验收、类型检查、独立语法检查、上下文检查和证据审计。优先复用本机源码和产物，集中实现真实业务入口；仅为生成所需产物进行增量编译，不把编译成功当作功能完成或验收通过。未验证功能如实记录，不得伪造通过结果。
|
||
|
||
- 遇到阻塞项，必须优先利用用户提供的 Blender 源码及本地资料定位并修复；不得仅因缺少执行契约、适配层或验收证据就停止推进或反复空转。暂未解决时记录具体失败业务、源码依据和下一步修复动作，保留已有产物并继续独立实现任务。全部功能实现完成后，才进入用户使用验证阶段。
|
||
|
||
- OCCT WASM 已提供，几何算法必须统一到这一内核出口；优先复用已有 OCCT WASM 产物、绑定和适配接口，不另造或并行维护同类几何算法实现。
|
||
- Three.js 只负责显示，消费几何内核输出；不得承担几何算法、拓扑计算或几何布尔运算。
|
||
- 优先复用本机现有源码、WASM、模块和有效证据，不重复造轮子。先核对产物版本、接口与哈希；仅在产物缺失、失效或必要修改时增量构建受影响模块。
|
||
|
||
- 坚持以功能模块业务和功能路由带动桌面 Blender 到 Web Blender 的移植，按“模块 -> 用户工作流 -> 功能路由 -> 源码/operator case”落实实现与验收。
|
||
- 遇到问题先检索用户提供的 `blender-5.2.0` 对应源码，再查当前模块相关资料；源码行为优先于路由分类、前端近似实现或外部资料。
|
||
- 源码检索使用聚焦工具，可通过 `--unit <source-unit-id>` 限定当前源码单元；禁止默认加载完整源码 inventory 或历史计划。
|
||
- 计时、索引、构建和验证是执行保障，不能代替业务功能完成；报告必须说明工作流、具体功能路由及源码依据。
|
||
|
||
## 工作方式铁律
|
||
|
||
- **通过案例，找到缺口，完善程序，稳步实现项目桌面程序到 WEB 移植的完整功能。**
|
||
每个工作批次必须先落到一个具体的用户案例（桌面 Blender 可复现的操作路径或仓库内已有 fixture/对比案例），在 Chromium 中实走该路径，找出与桌面行为的真实差异；差异必须是用户可见的功能缺口，而不是测试口径、证据簿记或统计口径。找到缺口后直接完善程序实现，再继续下一个案例。禁止用「跑通已有 spec」「补充证据」「重绑覆盖率」替代功能推进。
|
||
|
||
## 已验证的工作流（后续批次直接复用，不重新摸索）
|
||
|
||
**一条案例的固定推进顺序**
|
||
|
||
1. **选案例**：从 `blender-5.2.0/tests/files/` 取真实资产，按"桌面可复现的操作路径"定义，不造合成场景。
|
||
2. **查源码**：先读桌面实现（operator exec、RNA 写路径、DNA 字段），确认桌面语义，再动 Web 侧。
|
||
3. **走真实入口**：Chromium 里用产品自身入口（`blend-file-input`、菜单按钮、`__nativeWorkflowEngine`），不另建第二个 `/browser` 写者。
|
||
4. **定位缺口**：行为差异必须用户可见；区分"我造成的回归"和"既有缺口"，必要时用 A/B（临时禁掉自己那行）判定。
|
||
5. **最小修复**：改到能解释现象的那一处，优先扩展已有函数，不新增并行实现。
|
||
6. **增量构建 + 同步**：`cmake --build build_web_blender6 --target web_engine -j8` → `node tools/web/sync-web-engine-runtime.mjs`；不要手工拷贝产物。
|
||
7. **复测并留证**：结果写入该 case 的 validation，标 `NOT_CLAIMED`；绑定回执不得被复跑覆盖（写目标用 `WBV2_BATCH_PRODUCTION` 之类的可覆盖路径）。
|
||
8. **交接**：continuation 记录断点/已完成/残余/下一动作，status 追加一节。
|
||
|
||
**探针技法（已验证有效）**
|
||
|
||
- 驱动 App 自己的 worker：`window.__nativeWorkflowEngine.postMessage({requestId, command})`，按 `requestId + kind==='result'` 收结果；`command()` 等 `__nativeWorkflowRequests/Responses` 增长。
|
||
- 每次打开后等 `main.blender-app` 的 `data-project-id` 与 `engine-status` 含 `SceneIR`，否则会沿用上一个 Main 导致假结论。
|
||
- 点击被原生画布遮挡时先 `exposeWebTools(page)`；保存要靠 `waitForEvent("download")`。
|
||
- 状态判定用 `snapshot` 的语义摘要（剔除 `revision`）与 `saveBlend` 的 SHA-256 摘要分开比较，能区分"数据变了"和"仅序列化抖动"。
|
||
- 判断某分支是否真的执行，用能留痕的副作用（场景名、输出行、打印），不要只看返回 ok。
|
||
- 源码/产物一致性用 `grep -a` 查二进制；`cd` 后相对路径会失效，一律用绝对路径或每批重新 `cd`。
|
||
|
||
**判定原则**
|
||
|
||
- 首次调用与后续调用不等价时（一次性运行期初始化），比较"相邻两次重复操作"而不是"前后各一次"。
|
||
- 放宽守卫必须配反向用例：构造真实违规路径，确认仍被拒绝。
|
||
- 编译通过、探针 ok、单 case 通过都只是证据素材，不是验收通过，不给整体完成度。
|
||
|
||
## 主线铁律（最高优先）
|
||
|
||
- **唯一主线：把桌面 Blender 的既有功能移植到 Web，让用户能在浏览器里真实操作。** 任何批次的产出都必须落在这条线上：真实的用户入口、真实的原生执行、真实的读回与撤销。
|
||
- **不发散探查。** 不为「查覆盖率」「查声明是否符合」这类台账问题开批次；不连读多看源码只为准确定位一个函数；不为疑似缺口编写大量探针。源码只需读到能改对那一处为止。
|
||
- **每批只做一件事：** 一个用户可见缺口 → 一处原生/前端修复 → 一次编译同步 → 一条有界 Chromium 复测 → 断点落盘。做完即收尾，不顺手扩范围。
|
||
- **方向（2026-11-01 用户书面确认，最高优先）：不做单条失败用例的考古式推进。** 按「盘点已实现能力 → 打包候选 → 全模块实测 → 只修真实阻塞」推进：先枚举现有可用入口、构件与用例并实际跑通，最大化复用已实现功能，尽快形成可验证、可上线的候选；只有实测暴露的真实用户功能阻塞才开修复批次，且一次只改到能解释现象的那一处。
|
||
- **铁律 A — 资产优先，不重复实现。** 先盘清“已接通/已实现”功能清单，再谈缺口；已实现的功能直接复用，不重新走实现流程。队列、任务卡、continuation 只作为“证据来源与资产索引”，不作为推进节拍器。
|
||
- **铁律 B — 阻塞分级，只修真实阻塞。** 失败分三类：真实功能缺陷 / 异步时序 / 测试误操作。只有第一类进入修复，后两类走证据纠正或测试修正，且需证据支撑。同一路径反复失败，先改源码策略，不盲目重跑、重启、重编译。
|
||
- **铁律 C — 打包候选优先于逐例深挖。** 以冻结候选 `build_web_main_desktop/versioning-filepath-20261101` 为基线，按模块打包实测；不以单例通过替代模块结论，也不以单例失败阻塞全量盘点。单例深挖只在“该例阻塞某个模块整体验收”时才做。
|
||
- **铁律 D — 证据必须绑定构件身份。** 正式候选测试绑定绝对路径与构件哈希；开发服务器结果不代替发布验收；不覆盖冻结候选与历史回执。本地 WASM 与原生后端分别记录，互不代替。
|
||
- **铁律 E — 绝对路径 + 最小上下文。** 所有文件、库、构件、日志引用一律绝对路径；读取遵守本文件字节预算，不默认加载完整路线图、parity ledger、源码 inventory、全部历史日志。
|
||
- **铁律 F — 不降标准达成“完成”。** 不删缺口、不缩承诺、不放宽断言、不跳必测项、不调统计。RUN、单例通过、编译成功、源码覆盖统计均不等于整体验收。
|
||
- **缺口按用户能否触发排序。** 用户点得到但无效果 > 用户点不到 > 已接通待验证。台账、能力表、静态清单不与功能实现混在同一批。
|