76 lines
4.3 KiB
Markdown
76 lines
4.3 KiB
Markdown
|
# API文档增量回归并行任务板（2026-04-10，晚间）
|
|||
|
|
|
|||
|
|
## 当前基线
|
|||
|
|
|
|||
|
|
- 截至 `2026-04-10` 晚间，`python -B docs/api/_tools/audit_api_docs.py` 已恢复全绿：
|
|||
|
|
- `Invalid header refs = 0`
|
|||
|
|
- `Invalid source refs = 0`
|
|||
|
|
- `Broken .md links = 0`
|
|||
|
|
- `Missing directory index pages = 0`
|
|||
|
|
- 最近已经收口并推送的高频变动区包括：
|
|||
|
|
- `RHI`：`CreateBuffer(...)` 初始数据重载、`SetSampleQuality`
|
|||
|
|
- `Rendering`：`RenderSurface`、`RenderPassContext`、`BuiltinFinalColorPass`、`BuiltinColorScalePostProcessPass`、`BuiltinInfiniteGridPass`
|
|||
|
|
- `Rendering/Passes`：`BuiltinObjectIdPass`、`BuiltinObjectIdOutlinePass`、`BuiltinSelectionOutlinePass`、`BuiltinVolumetricPass`
|
|||
|
|
- `UI/Resources`：`UISelectionModel`、`Resources.h` umbrella 页
|
|||
|
|
- 当前主问题已经从“大面积补缺页”转成“增量语义回归 + 历史空目录清理 + 任务板状态同步”。
|
|||
|
|
|
|||
|
|
## 并行认领规则
|
|||
|
|
|
|||
|
|
- 一个任务块只允许一个会话认领。
|
|||
|
|
- 每个任务块必须同时处理：
|
|||
|
|
- 目标页
|
|||
|
|
- 所属模块索引页
|
|||
|
|
- 相关交叉链接
|
|||
|
|
- 删除任何目录或历史页前，先执行：
|
|||
|
|
- `rg -n "<名称>" docs/api docs/plan docs/used`
|
|||
|
|
- 每完成一个任务块后都要执行：
|
|||
|
|
- `python -B docs/api/_tools/audit_api_docs.py`
|
|||
|
|
- 每完成一个阶段都要立即：
|
|||
|
|
- `git commit`
|
|||
|
|
- `git push`
|
|||
|
|
|
|||
|
|
## 当前并发热点
|
|||
|
|
|
|||
|
|
以下代码区域仍在持续波动，认领相关文档时默认按 `high-risk` 处理：
|
|||
|
|
|
|||
|
|
- `editor/src/Viewport/**`
|
|||
|
|
- `engine/include/XCEngine/Rendering/Passes/**`
|
|||
|
|
- `engine/include/XCEngine/Rendering/Planning/**`
|
|||
|
|
- `engine/src/Rendering/Caches/**`
|
|||
|
|
- `new_editor/include/XCEditor/**`
|
|||
|
|
|
|||
|
|
## 并行任务块
|
|||
|
|
|
|||
|
|
| ID | 范围 | 目标改动 | 主要路径 | 风险 | 状态 | 备注 |
|
|||
|
|
|----|------|----------|----------|------|------|------|
|
|||
|
|
| `N1` | Canonical 历史空目录清理 | 复核并清理已确认无源码对应、且无文档反向引用的历史空目录 / 空入口 | `docs/api/XCEngine/**` | `medium` | `pending` | 优先接旧任务板里的 `S9 / G1` 收尾 |
|
|||
|
|
| `N2` | Rendering / Planning & Caches 增量回归 | 对齐 `CameraRenderRequest`、`SceneRenderer`、`FullscreenPassSurfaceCache`、`RenderResourceCache` 在 `sourceSurface` / `sourceColorState` / sample desc 上的新语义 | `docs/api/XCEngine/Rendering/Planning/**`, `docs/api/XCEngine/Rendering/Caches/**` | `high-risk` | `pending` | 适合拆成 1 个小提交 |
|
|||
|
|
| `N3` | Editor / Viewport 增量回归 | 对齐 `SceneViewportSelectionOutlinePass`、overlay builder / hit tester / resource paths 等近期重构后的 API 说明 | `docs/api/XCEngine/Editor/Viewport/**`, `editor/src/Viewport/**` | `high-risk` | `pending` | 当前最容易和别的会话冲突 |
|
|||
|
|
| `N4` | XCEditor / new_editor 壳层回归 | 检查 `Collections`、`Shell` 下近期重构的 dock host / panel frame / viewport slot / tab strip 文档是否仍匹配真实接口 | `docs/api/XCEditor/**`, `new_editor/include/XCEditor/**` | `high-risk` | `pending` | 适合单独开一个高上下文会话 |
|
|||
|
|
| `N5` | Core/Asset 与 Resources 入口复核 | 复核 `AssetDatabase`、`ResourceManager`、`Resources`、`Model`、`GaussianSplat`、`Volume` 入口页的模块级口径是否一致 | `docs/api/XCEngine/Core/Asset/**`, `docs/api/XCEngine/Resources/**` | `medium` | `pending` | 低冲突，适合并行 |
|
|||
|
|
| `N6` | 最终状态回写 | 在本轮增量收口后更新 `rebuild-status`、任务板状态和必要的归档链接 | `docs/api/_meta/rebuild-status.md`, `docs/plan/**`, `docs/used/**` | `low` | `pending` | 必须最后做 |
|
|||
|
|
|
|||
|
|
## 推荐顺序
|
|||
|
|
|
|||
|
|
1. `N2`
|
|||
|
|
2. `N5`
|
|||
|
|
3. `N4`
|
|||
|
|
4. `N3`
|
|||
|
|
5. `N1`
|
|||
|
|
6. `N6`
|
|||
|
|
|
|||
|
|
## 验收口径
|
|||
|
|
|
|||
|
|
- 文档描述必须以当前工作树源码为准，不沿用旧目录结构或旧后端限定说法。
|
|||
|
|
- 不允许把“补充说明”叠在已经过时的主体段落上；发现旧段落和新行为冲突时，应直接重写主体页。
|
|||
|
|
- 新增或改写后的页要优先保证：
|
|||
|
|
- 公开签名正确
|
|||
|
|
- 生命周期 / 状态切换语义正确
|
|||
|
|
- 真实调用链或测试锚点可追溯
|
|||
|
|
- 最终仍需保持审计全绿。
|
|||
|
|
|
|||
|
|
## 备注
|
|||
|
|
|
|||
|
|
- 旧任务板可继续作为历史依据参考，但新的增量认领统一以本文件为准。
|
|||
|
|
- 如果执行过程中又有别的会话提前提交了同一批文档，先检查 `git log --oneline -n 6`，确认是否已经收口，再决定是否继续接下一块。
|