XCEngine/docs/plan/API文档增量回归并行任务板_2026-04-10_晚间.md

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，确认是否已经收口，再决定是否继续接下一块。