235 lines
14 KiB
Markdown
235 lines
14 KiB
Markdown
# 项目任务分解与最小上下文指南
|
||
|
||
更新时间：2026-08-19（America/New_York）
|
||
|
||
> 拆分参考（归档）：本文件不进入默认任务上下文。当前任务和依赖只由 `print-task-context` 与
|
||
> parent manifest 提供；这里只在需要设计新的子任务门时读取对应小节。
|
||
|
||
本文件是“如何拆任务、如何领取任务、如何交接”的规划索引，不是实现状态事实源。当前状态仍以
|
||
`docs/EXECUTION_QUEUE.md`、当前任务的 `manifest.json`、对应 `docs/status/<task>.md` 和可复验命令为准。
|
||
本文件的目标是让一次任务只加载必要上下文，不要求阅读整份路线图或历史接续日志。
|
||
|
||
## 1. 30 秒入口
|
||
|
||
每轮只按下面顺序读取：
|
||
|
||
1. `docs/EXECUTION_QUEUE.md`：确认唯一当前 `nextTask`、Chromium-only 规则和专项命令。
|
||
2. `node tools/web/print-task-context.mjs`：取得已经裁剪的单任务 JSON；不要读取 plan、gap audit 或 parity map。
|
||
3. `docs/tasks/<task>.md`：读取目标、输入、范围、验收和回滚。
|
||
4. `tests/golden/<parent>/manifest.json`：确认 parent hash、依赖、运行时和下一任务。
|
||
5. `docs/status/<parent>.md`：只读取上一项的证据摘要和已知风险。
|
||
|
||
只有遇到以下问题才继续读取：
|
||
|
||
| 问题 | 追加读取 |
|
||
| --- | --- |
|
||
| 不确定产品是否承诺 | `WEB_BLENDER_MODELER_V1_SCOPE.md` |
|
||
| 不确定实现事实或已有命令 | `PROJECT_STATUS_AND_NEXT_WORK.md` 的相关小节 |
|
||
| 不确定长期依赖或全域差距 | `BLENDER_5_2_FULL_WEB_PARITY_EXECUTION_PLAN.md` 的对应 M/F 小节 |
|
||
| 不确定 family 状态 | `status/parity-ledger.json` 和 `release-evidence.json` |
|
||
| 不确定协议字段 | 任务卡列出的 `web/protocol/*` 文件，不扫描整个 `web/` |
|
||
|
||
不要把 `README.md`、`后续工作.txt`、完整路线图和全部 status 日志作为每轮默认上下文。
|
||
根目录路线图与历史接续记录仅用于背景；它们不能覆盖机器 manifest 的指针。
|
||
|
||
## 2. 文档职责和冲突处理
|
||
|
||
| 层级 | 唯一职责 | 可以回答 | 不能回答 |
|
||
| --- | --- | --- | --- |
|
||
| 产品契约 | `WEB_BLENDER_MODELER_V1_SCOPE.md` | V1 承诺、非目标、发布门 | 当前领取哪一项 |
|
||
| 短周期入口 | `EXECUTION_QUEUE.md` | 当前任务、parent、专项命令 | 实现是否真的通过 |
|
||
| 任务卡 | `tasks/<task>.md` | 单项范围、最小输入、验收、回滚 | 历史实现日志 |
|
||
| 机器事实 | `tests/golden/*/manifest.json`、`status/*.json` | hash、依赖、运行时、状态轴 | 人类意图 |
|
||
| 完成证据 | `status/<task>.md` | 实际命令、退出码、报告、风险 | 下一任务的推导顺序 |
|
||
| 长期规划 | `BLENDER_5_2_FULL_WEB_PARITY_EXECUTION_PLAN.md` | M12-M23/F 域规划 | 当前队列指针 |
|
||
| 覆盖参考 | `BLENDER_5_2_FULL_PARITY_WBS.md` | Blender 全域检查表 | 独立完成证明 |
|
||
|
||
冲突时使用以下优先级：
|
||
|
||
```text
|
||
可复验命令输出 > manifest/evidence > 当前任务卡 > 执行队列描述 > 长期规划/历史日志
|
||
```
|
||
|
||
如果 manifest、status 和命令互相矛盾，先标记 `blocked`，不要修改 checkbox 或手工推进
|
||
`nextTask`。
|
||
|
||
## 3. 原子任务规则
|
||
|
||
一个任务只能有一个主要行为变化，或一个独立证据变化。把“实现、浏览器接线、发布证据”混在一项
|
||
会导致上下文过大，也会让测试文件存在被误判成生产能力完成。
|
||
|
||
每项任务都要能回答以下六个问题：
|
||
|
||
| 字段 | 最小内容 |
|
||
| --- | --- |
|
||
| 输入 | parent manifest、一个最小 fixture、生产入口 |
|
||
| 行为 | 一个可观察的状态/数据/错误变化 |
|
||
| 边界 | 至少一个非法、取消、超限或重复事件 |
|
||
| 产物 | 一个协议/实现改动 + 一个 focused test/checker |
|
||
| 验收 | 一条首选命令，必要时追加 typecheck/build |
|
||
| 交接 | report、manifest、status、下一任务、回滚点 |
|
||
|
||
### 3.1 建议的子任务门
|
||
|
||
复杂能力按以下门拆开，每个门都可独立复验：
|
||
|
||
| 门 | 交付内容 | 常见文件 |
|
||
| --- | --- | --- |
|
||
| C 契约 | schema、稳定 ID、预算、错误码、revision 规则 | `web/protocol/*` |
|
||
| P 生产路径 | Main/Worker/App/viewport 真正消费契约 | `web/app/src/*`、`web/engine/*` |
|
||
| N 负例 | 非法、重复、取消、迟到、超限不改已提交状态 | `web/tests/unit/*` |
|
||
| B 浏览器 | Chromium 真实用户路径和可见状态 | `tools/web/check-*.mjs`、`web/tests/e2e/*` |
|
||
| R 资源 | dispose、取消、Worker 重启、OPFS/ GPU 预算归零 | Worker、storage、viewport |
|
||
| E 证据 | 报告、SHA-256、manifest、status、回滚 | `tests/golden/*`、`docs/status/*` |
|
||
|
||
任务卡可以把 C/P/N/B/R/E 写成子任务，但只有所有适用门通过后，主任务才可变为 `done`。
|
||
|
||
### 3.2 生成 gap 的细分协议
|
||
|
||
M16 及后续全域 gap 采用“一条 gap、一个任务、五扇证据门”的固定粒度。任务 ID、gap、owner 和
|
||
实现类别由机器 catalog 提供；任务卡只补充该条 gap 的真实 fixture、生产入口和边界，不复制全量
|
||
计划字段。
|
||
|
||
| 门 | 唯一交付 | 失败时的状态 |
|
||
| --- | --- | --- |
|
||
| C | 字段/稳定 ID/错误边界契约 | `in_progress`，不得写入成功报告 |
|
||
| D | desktop fixture 和可重跑报告 | `blocked` 或 `in_progress`，不得接 WASM |
|
||
| W | WASM/Main 消费同一 fixture | `in_progress`，不得声称 parity |
|
||
| R | save/reopen 或 revision 稳定性 | `in_progress`，不得推进队列 |
|
||
| E | comparator、manifest、status、rollback | 只有 E 完成才允许 parent `nextTask` |
|
||
|
||
生成目录中的 `next-task-plan.json` 是盘点输入，不是执行上下文。`generate-task-index.mjs` 将其切成
|
||
带源 hash 的 `task-index.json` 和一行一个任务的 `task-catalog.jsonl`；执行工具按 offset 读取单条
|
||
记录，并由任务卡恢复命令模板。索引失效、任务卡缺失、parent 指针不一致或单卡超过 8 KiB 时，
|
||
领取门直接失败。
|
||
|
||
新任务卡使用 `node tools/web/generate-task-card.mjs --task <task-id>` 按 catalog 单条记录生成；生成器拒绝未知 ID、没有 parent 的首项和已有卡覆盖，除非显式传入 `--force`。生成后必须重新运行上下文门禁。
|
||
|
||
## 4. 项目阶段分解
|
||
|
||
下面是导航级分解；具体领取仍由短周期队列决定。
|
||
|
||
| 阶段 | 主题 | 交付边界 | 当前使用方式 |
|
||
| --- | --- | --- | --- |
|
||
| M0 | 范围与状态模型 | V1 契约、双轴 ledger、P0 用户闭环 | 已完成，持续回归 |
|
||
| M1 | 工作区收口 | 静态门、VDB 基线、P0 一致性 | 已完成，持续回归 |
|
||
| M2 | 大几何 | 10M geometry、LOD、取消、释放、恢复 | 已完成，持续回归 |
|
||
| M3 | 长媒体 | 索引、seek、取消、缓存、重开 | 已完成，持续回归 |
|
||
| M4 | OOM/fault | WASM、OPFS、GPU、VDB 确定性恢复 | 已完成，持续回归 |
|
||
| M5-M6 | V1/可部署 RC | 离线包、SBOM、CI、部署、升级、回滚 | 已完成，持续回归 |
|
||
| M7 | 核心体验 | action/dirty/save/restart/recent projects/input 基础 | 已完成，持续回归 |
|
||
| M8 | VDB 自动分页 | range/OPFS/LRU/双视口/device loss | 已完成，持续回归 |
|
||
| M9 | 非 Mesh/GP/Paint | 有界 reader/writer、Main、保存重开、故障 | 已完成的 V1 slice；全域仍可能 BLOCKED |
|
||
| M10 | GN/Shader/NLA/Simulation | allowlist、compile/cache、错误与恢复 | 已完成的 V1 slice；完整 evaluator 仍排除 |
|
||
| M11 | Render/Compositor/Media | bounded local、server route、codec/revision/audio | 已完成的 V1 slice |
|
||
| M12 | Asset/IO/Editors | 资产库、GLB/OBJ/STL/PLY、编辑器上下文 | 按 manifest 继续领取，不能按总百分比判断 |
|
||
| M13 | Scripting/Security | metadata-only、default-deny、sandbox、server isolation、CSP | 每个安全门独立验收；execution 默认禁用 |
|
||
| M14 | Chromium 设备与输入 | capability、预算、DPR、pointer、IME、keymap、modal、可访问性 | 已归档；后续只按 manifest 回归 |
|
||
| M15 | 全域审计 | Blender 5.2 inventory、operator/node/editor/format gap | 已完成计划/审计门；产出 6,900 条 M16-M22 原子 gap |
|
||
| M16-M22 | 原子 parity gap | 每条 gap 独立 fixture、desktop/WASM 对标、重开和 hash 证据 | 只按 parent manifest 顺序推进；当前任务不在本表缓存 |
|
||
|
||
状态轴必须分开：V1 `releaseStatus=READY` 不等于 Blender 全域 `parityStatus=COMPLETE`。
|
||
|
||
## 5. 历史示例：M14-04F 细分（非当前任务）
|
||
|
||
### 5.1 归档时的已知上下文
|
||
|
||
- parent：`M14-04E`，状态页已记录 keymap fixture 的成功证据。
|
||
- 当前任务：`M14-04F`，任务卡为 `docs/tasks/M14-04F.md`。
|
||
- 协议：`web/protocol/input-modal.ts`。
|
||
- 单测：`web/tests/unit/input-modal.test.mjs`。
|
||
- Chromium 检查器：`tools/web/check-chromium-input-modal.mjs`。
|
||
- 报告/manifest：`tests/golden/M14-04F/`。
|
||
- focused command：`npm --prefix web run test:chromium-input-modal`。
|
||
|
||
当前命令已经能证明协议单测通过，并能在 Chromium 页面派发 touch/pen 事件；完成主任务前还要
|
||
确认事件确实进入生产输入状态和 Main transaction，而不是只在 checker 内构造事件并写入固定
|
||
保证值。
|
||
|
||
### 5.2 子任务清单
|
||
|
||
| 子任务 | 唯一目标 | 最小改动面 | 必须证明 |
|
||
| --- | --- | --- | --- |
|
||
| F-C | 冻结 `InputModalState` schema 和状态转移 | `web/protocol/input-modal.ts` | pointer ID 非法时稳定拒绝；状态转移确定 |
|
||
| F-T | 触控 modal 取消 | protocol + 生产 pointer cancel 入口 | cancel 后 `kind=NONE`、无 Main commit、活动 pointer 清零 |
|
||
| F-2T | 双指导航 session 去重 | protocol + navigation dispatch | 从 1 到 2 个 pointer 只增加一次 `navigationRevision`；重复 down 不增加 |
|
||
| F-P | 笔 stroke 单次提交 | protocol + pen pointerup/cancel 入口 | 第一个合法 up 最多一个 Main commit；late up/cancel 无二次提交 |
|
||
| F-W | 主线程/Offscreen 生产接线 | App、viewport、Worker 输入边界 | 两条生产视口消费同一状态规则；cancel/late result 不污染 revision |
|
||
| F-B | Chromium 真实断言 | checker/e2e + 最小 fixture | 读取 DOM/诊断/Main revision 的真实结果，而不是只检查派发数量 |
|
||
| F-E | 证据和交接 | report、manifest、status | 命令退出 0、artifact hash 非空、风险/回滚清楚 |
|
||
|
||
### 5.3 完成门
|
||
|
||
主任务只有同时满足以下条件才可标记 `done`：
|
||
|
||
1. `F-C`、`F-T`、`F-2T`、`F-P` 的 Node 单测通过。
|
||
2. `F-W` 在生产 App/viewport 中有实际 import 和事件消费路径。
|
||
3. `F-B` 对至少 touch cancel、双指 session、pen late-up/cancel 做真实正负例断言。
|
||
4. 取消或重复事件不产生迟到 Main commit，且 revision/commit counter 可观测。
|
||
5. focused Chromium 命令、必要的 `typecheck`/`build` 和 `git diff --check` 通过。
|
||
6. `docs/status/M14-04F.md`、`tests/golden/M14-04F/manifest.json` 和代码 hash 一致。
|
||
|
||
如果只有协议和测试通过，状态应保持 `in_progress`，不得提前领取 M14-04G。
|
||
|
||
## 6. M14 后续任务草案（归档）
|
||
|
||
这些是领取前的拆分草案；正式任务仍须由 parent manifest 生成任务卡。
|
||
|
||
### M14-04G：响应式布局无重叠/溢出
|
||
|
||
- 输入：M14-04F manifest、App shell、viewport CSS、四档 Chromium viewport。
|
||
- 正例：`1440x900`、`1280x720`、`834x1112`、`390x844`。
|
||
- 检查：`scrollWidth <= clientWidth`；topbar/sidebar/viewport/timeline/status 不互相覆盖；文字不被裁切；触控目标仍可操作。
|
||
- 负例：窄视口、长项目名、错误提示、打开进度、面板展开、DPR 2。
|
||
- 产物：布局 checker、4 档报告、截图或 bounding-box 摘要、manifest、status。
|
||
- 不做：Firefox/WebKit；完整响应式重设计；新增 Blender 功能。
|
||
|
||
### M14-04H：键盘无障碍与焦点恢复
|
||
|
||
- 输入：M14-04G manifest、现有菜单/操作搜索/文件对话入口。
|
||
- 正例：Tab 顺序、Escape 关闭 modal、Enter 提交、焦点回到触发器、按钮有 name/role。
|
||
- 负例：modal 打开时快捷键穿透、焦点丢失、隐藏元素进入 tab 顺序、IME 期间提交 operator。
|
||
- 产物：Chromium keyboard-only checker、焦点轨迹报告、必要的 ARIA/DOM 修复、manifest/status。
|
||
- 不做：screen reader 的浏览器兼容性声明；Firefox/WebKit 证据。
|
||
|
||
### M15-01A 至 M15-01F：全域清单审计
|
||
|
||
1. 从 Blender 5.2 RNA 生成 data-block inventory。
|
||
2. 生成 operator、poll context 和 property inventory。
|
||
3. 生成 modifier、constraint、shader/GN/compositor node inventory。
|
||
4. 生成 sequencer、physics、import/export inventory。
|
||
5. 生成 editor/space/region/workspace/keymap inventory。
|
||
6. 将 inventory ID 映射到 `parity-ledger.json`，拒绝未分类新增项并固定总 hash。
|
||
|
||
每一项都只产出一个稳定 inventory 或映射证据；不要在 M15 直接实现功能。
|
||
|
||
## 7. 交接格式
|
||
|
||
完成任务后，status 页只保留可审计摘要：
|
||
|
||
```text
|
||
status: done | blocked
|
||
task: <ID>
|
||
updated: <timezone>
|
||
scope: 一句话行为变化
|
||
evidence: 命令、退出码、关键结果
|
||
artifacts: report/manifest/代码 SHA-256
|
||
nextTask: 仅复制 manifest.nextTask
|
||
knownRisk: 仍未覆盖的边界
|
||
rollback: 删除本任务产物并恢复 parent 队列尾
|
||
```
|
||
|
||
不要把完整终端日志、实现过程或下一阶段设想复制进 status 页；长日志留在构件目录，任务卡只留
|
||
最小输入和验收入口。
|
||
|
||
## 8. 领取前检查表
|
||
|
||
- [ ] 当前 task 与 parent manifest 的 `nextTask` 一致。
|
||
- [ ] parent status 为 `done`，或明确写出允许并行的 `enablingTask`。
|
||
- [ ] 任务卡只有一个主要行为。
|
||
- [ ] focused command 已存在，或任务明确包含创建该命令。
|
||
- [ ] 生产入口和测试入口分别列出，没有只写“相关代码”。
|
||
- [ ] 至少一个负例、取消或重复事件已列出。
|
||
- [ ] 任务状态不会误改 `parityStatus`/`releaseStatus` 另一条轴。
|
||
- [ ] 完成后能生成 report、manifest、status 和可回滚路径。
|