887 lines
62 KiB
Markdown
887 lines
62 KiB
Markdown
# API文档实时同步任务池（2026-04-03，第三轮）
|
||
|
||
## 文档定位
|
||
|
||
这份任务池接替已归档的第二轮计划，现已转为归档基线：
|
||
|
||
- `docs/used/API文档实时同步任务池_2026-04-03_第二轮归档.md`
|
||
|
||
当前活跃 API 工作请优先查看：
|
||
|
||
- `docs/plan/API文档目录*.md`
|
||
|
||
前两轮已经完成的重点包括：
|
||
|
||
- canonical API 目录结构收口
|
||
- 大批缺页补齐
|
||
- 多轮模板页清理与内容重写
|
||
- 结构层审计修复到全绿
|
||
|
||
第三轮不再以“结构补齐”为主，而是专门处理“源码/测试已经变化，但 API 文档内容还没有跟上”的增量漂移。
|
||
|
||
## 当前复核快照
|
||
|
||
- 最近一次结构审计时间：`2026-04-10 17:02:06`
|
||
- 审计命令：`python -B docs/api/_tools/audit_api_docs.py`
|
||
- 当前结果：
|
||
- `Public headers: 384`
|
||
- `Editor source headers: 144`
|
||
- `Valid header refs (canonical): 384`
|
||
- `Invalid header refs: 0`
|
||
- `Invalid source refs: 0`
|
||
- `Valid source refs (Editor canonical): 144`
|
||
- `Broken .md links: 0`
|
||
- `Missing directory index pages: 0`
|
||
- `Stale canonical doc tokens: 0`
|
||
- `Stale editor doc tokens: 0`
|
||
- `Stale editor canonical pages: 0`
|
||
- `Editor high-risk single-page dirs: 0`
|
||
|
||
这说明当前 canonical public header 覆盖与全部 Editor source-backed API 都已跟上重大重构后的最新头文件集；在 `Volume`、`Selection/Volumetric Passes`、`UI/Widgets Helpers` 与 Editor helper/source-backed 页面收口后，本轮新增进入审计口径的 `XCEditor`、`Resources/Model` 与 `Resources/GaussianSplat` 入口也已补齐。
|
||
|
||
### 已复核、暂不新开任务的区域
|
||
|
||
- `Resources/Material` / `RenderMaterialUtility` / `BuiltinForwardPipeline`
|
||
- `Components/MeshFilterComponent` / `MeshRendererComponent`
|
||
- `Scene` 中 builtin mesh / material 路径 round-trip
|
||
- `Components/GameObject` 辅助访问器与层级辅助页
|
||
|
||
这些区域本轮已对照当前源码和测试抽查，暂时没有发现新的明确失配。
|
||
|
||
## 认领规则
|
||
|
||
- 一次只认领 `1` 个任务块。
|
||
- 先把 `状态` 改成 `DOING`，再写 `认领人`。
|
||
- 只允许修改自己任务块声明的 `写入范围`。
|
||
- 所有改动都必须基于“当前头文件 + 当前实现 + 当前测试 + 当前真实调用链”。
|
||
- 如果需要同步 `_guides` 或模块总览页，必须在对应任务块内明确列出，避免多人撞写。
|
||
- 做完后必须补一次最小复核，至少确认相关链接和交叉引用没有坏掉。
|
||
|
||
## 任务池
|
||
|
||
## T01 Core / Asset `AssetDatabase` 显式重导入接口补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Core/Asset/AssetDatabase/**`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Core/Asset/AssetDatabase.h`
|
||
- `engine/src/Core/Asset/AssetDatabase.cpp`
|
||
- `tests/Core/Asset/test_resource_manager.cpp`
|
||
- 已确认问题:
|
||
- 头文件已新增 `TryGetImportableResourceType()`、`ReimportAsset()`、`ReimportAllAssets()`，但 canonical 目录下没有对应方法页。
|
||
- `AssetDatabase.md` 的公开方法表仍停在旧集合，没有把“可导入类型探测 / 单资产重导入 / 批量重导入”纳入公开能力。
|
||
- `kCurrentImporterVersion` 已升到 `5`，总览页需要同步当前 importer 版本口径。
|
||
- 产出要求:
|
||
- 新增 `TryGetImportableResourceType.md`、`ReimportAsset.md`、`ReimportAllAssets.md`。
|
||
- 更新 `AssetDatabase.md`，必要时同步 `ResolvedAsset.md` 的交叉引用。
|
||
- 文档必须写清以下真实边界：
|
||
- 只接受项目 `Assets/...` 内、存在且非目录的 source asset。
|
||
- `TryGetImportableResourceType()` 只返回当前 importer 的 primary `ResourceType`；`Unknown` 直接失败。
|
||
- `ReimportAsset()` 会重建单个 artifact、更新 source/artifact DB，并返回可直接消费的 `ResolvedAsset`。
|
||
- `ReimportAllAssets()` 会遍历全部可导入 source record；单个条目失败不会中断全量循环，但最终返回总体成功位。
|
||
|
||
## T02 Core / Asset `AssetImportService` Library 工具接口与 `ImportedAsset` 语义同步
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Core/Asset/AssetImportService/**`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Core/Asset/AssetImportService.h`
|
||
- `engine/src/Core/Asset/AssetImportService.cpp`
|
||
- `tests/Core/Asset/test_resource_manager.cpp`
|
||
- 已确认问题:
|
||
- 缺少 `ClearLibraryCache.md`、`ReimportAllAssets.md`、`ReimportAsset.md`、`TryGetImportableResourceType.md`。
|
||
- `AssetImportService.md` 还没有把这批显式工具接口纳入生命周期和能力说明。
|
||
- `ImportedAsset` 页虽然已存在，但需要按当前 `ConvertResolvedAsset()` 口径复核 `runtimeLoadPath`、`artifactDirectory`、`mainLocalID` 和成功路径语义。
|
||
- 产出要求:
|
||
- 新增缺失方法页，并更新 `AssetImportService.md`、必要时同步 `ImportedAsset.md` 与 `EnsureArtifact.md`。
|
||
- 文档必须写清以下真实边界：
|
||
- `ClearLibraryCache()` 会关停数据库、删除整个 `Library` 目录、再重新初始化；它本身不会批量重导入所有资产。
|
||
- `RebuildLibraryCache()` 等于 `ClearLibraryCache() + ReimportAllAssets()`。
|
||
- `ReimportAsset()` 会先 `Refresh()`，再强制重导入指定路径，返回 `ImportedAsset`。
|
||
- `TryGetImportableResourceType()` 只是服务层转发；项目根无效时必须返回失败并把输出设为 `Unknown`。
|
||
- `AssetImportService_Test.RebuildLibraryCacheKeepsStableAssetRefs` 证明：重建 `Library` 不应破坏现有 `.meta` 驱动的稳定 `AssetRef`。
|
||
|
||
## T03 Core / Asset `ResourceManager` 项目资产工具入口同步
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Core/Asset/ResourceManager/**`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Core/Asset/ResourceManager.h`
|
||
- `engine/src/Core/Asset/ResourceManager.cpp`
|
||
- `tests/Core/Asset/test_resource_manager.cpp`
|
||
- 已确认问题:
|
||
- 缺少 `CanReimportProjectAsset.md`、`ReimportProjectAsset.md`、`ClearProjectLibraryCache.md`。
|
||
- `ResourceManager.md` 还没有覆盖当前项目资产工具入口，也没有把这些接口和 `UnloadAll()` / `ProjectAssetIndex::RefreshFrom()` 的关系写清。
|
||
- `RebuildProjectAssetCache.md`、`GetProjectLibraryRoot.md` 需要和新接口形成正确对比与交叉链接。
|
||
- 产出要求:
|
||
- 新增缺失方法页，更新 `ResourceManager.md`，必要时补交叉链接。
|
||
- 文档必须写清以下真实边界：
|
||
- 这批接口都要求 `m_resourceRoot` 非空；否则直接失败。
|
||
- `CanReimportProjectAsset()` 只做“当前路径是否可导入”的无副作用判断。
|
||
- `ReimportProjectAsset()` 会先 `UnloadAll()`，再重导入单路径资产，随后刷新 `ProjectAssetIndex`，成功时补记 `RememberResolvedPath(...)`。
|
||
- `ClearProjectLibraryCache()` 会先卸载运行时资源，再清空 `Library`，然后刷新 snapshot，但不会自动批量重导入。
|
||
- `ResourceManager_Test.ReimportProjectAssetBuildsArtifactForSelectedPath` 与 `RebuildProjectAssetCacheRefreshesLookupState` 是当前最直接的行为锚点。
|
||
|
||
## T04 Scripting / Mono `[SerializeField] private` 字段发现与持久化语义同步
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Scripting/Mono/Mono.md`
|
||
- `docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/**`
|
||
- `docs/api/_guides/Scripting/Scripting-Runtime-And-Field-Model.md`
|
||
- `docs/api/_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Scripting/Mono/MonoScriptRuntime.h`
|
||
- `engine/src/Scripting/Mono/MonoScriptRuntime.cpp`
|
||
- `managed/XCEngine.ScriptCore/SerializeField.cs`
|
||
- `managed/GameScripts/FieldMetadataProbe.cs`
|
||
- `managed/GameScripts/SerializeFieldProbe.cs`
|
||
- `tests/Scripting/test_mono_script_runtime.cpp`
|
||
- `tests/Scripting/test_project_script_assembly.cpp`
|
||
- 已确认问题:
|
||
- `Mono.md`、`TryGetClassFieldMetadata.md`、两篇 scripting guide 仍在沿用“只收录 public 实例字段”的旧口径。
|
||
- 当前真实实现已经变成：
|
||
- 过滤掉 `static` / `literal` / `init-only`
|
||
- 然后接受“public 字段”或“标了 `[SerializeField]` 的 private 字段”
|
||
- 最后再按支持类型过滤
|
||
- 测试已经明确覆盖 `HiddenFlag`、`HiddenCounter`、`HiddenEnabled` 这类 `[SerializeField] private` 字段的元数据发现、默认值读取、运行时写回与场景 round-trip。
|
||
- 未标 `[SerializeField]` 的 private 字段仍应保持忽略，但当前文档没有把这条边界讲清。
|
||
- 产出要求:
|
||
- 至少同步 `Mono.md`、`MonoScriptRuntime.md`、`TryGetClassFieldMetadata.md`、`TryGetClassFieldDefaultValues.md`。
|
||
- 两篇 guide 需要补上 Unity 风格设计解释：
|
||
- 为什么支持 `[SerializeField] private`
|
||
- 这样做对 Inspector、字段持久化、重构安全性有什么好处
|
||
- 哪些 private 字段仍不会进序列化层
|
||
- 文档必须明确当前排除项：
|
||
- `static`
|
||
- `const/literal`
|
||
- `readonly/init-only`
|
||
- 不支持的字段类型
|
||
- 未标 `[SerializeField]` 的 private 字段
|
||
|
||
## T05 Editor / Viewport `SceneViewportOverlayBuilder` provider-registry 口径同步
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/Viewport.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**`
|
||
- 主要源码依据:
|
||
- `editor/src/Viewport/SceneViewportOverlayBuilder.h`
|
||
- `editor/src/Viewport/SceneViewportOverlayBuilder.cpp`
|
||
- `editor/src/Viewport/SceneViewportOverlayProviders.h`
|
||
- `editor/src/Viewport/SceneViewportOverlayProviders.cpp`
|
||
- `editor/src/Viewport/ViewportHostService.h`
|
||
- `tests/Editor/test_scene_viewport_overlay_providers.cpp`
|
||
- 已确认问题:
|
||
- `SceneViewportOverlayBuilder.md` 与 `Build.md` 仍沿用旧版“静态 / 无状态 / 单体 builder”口径，没有同步当前实例 builder + provider registry 模型。
|
||
- `SceneViewportOverlayBuilder` 目录缺少 `Constructor.md` 与 `GetProviderRegistry.md`，导致新公开入口没有 canonical 页面。
|
||
- `Viewport.md`、`ViewportHostService.md` 与 `SceneView-Overlay-Frame-Data.md` 仍把基础 editor overlay 的来源写成 `SceneViewportOverlayBuilder::Build(...)`，没有同步宿主当前持有成员 `m_sceneViewportOverlayBuilder` 且默认聚合 camera / light provider 的事实。
|
||
- 完成记录:
|
||
- 已重写 `SceneViewportOverlayBuilder.md` 与 `Build.md`，改成当前实例 builder + registry 分发语义。
|
||
- 已新增 `Constructor.md` 与 `GetProviderRegistry.md`。
|
||
- 已同步 `Viewport.md`、`ViewportHostService.md` 与 `SceneView-Overlay-Frame-Data.md` 的上层调用链表述。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，并确认 `Broken .md links: 0`、`Stale editor doc tokens: 0`、`Stale editor canonical pages: 0`。
|
||
|
||
## T06 Editor / Viewport HUD / interaction-actions / canonical overlay-state 口径同步
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/Viewport/Viewport.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/IViewportHostService/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionResolver/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionActions/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportEditorOverlayData/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/**`
|
||
- `docs/api/XCEngine/Editor/panels/SceneViewPanel/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHandleBuilder/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/**`
|
||
- 主要源码依据:
|
||
- `editor/src/Viewport/SceneViewportHudOverlay.h`
|
||
- `editor/src/Viewport/SceneViewportHudOverlay.cpp`
|
||
- `editor/src/Viewport/SceneViewportInteractionResolver.h`
|
||
- `editor/src/Viewport/SceneViewportInteractionResolver.cpp`
|
||
- `editor/src/Viewport/SceneViewportInteractionActions.h`
|
||
- `editor/src/Viewport/SceneViewportInteractionActions.cpp`
|
||
- `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||
- `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.cpp`
|
||
- `editor/src/Viewport/IViewportHostService.h`
|
||
- `editor/src/Viewport/ViewportHostService.h`
|
||
- `editor/src/Viewport/SceneViewportOverlayBuilder.h`
|
||
- `editor/src/Viewport/SceneViewportOverlayProviders.h`
|
||
- `editor/src/Viewport/SceneViewportOverlayProviders.cpp`
|
||
- `editor/src/Panels/SceneViewPanel.cpp`
|
||
- `editor/src/Viewport/SceneViewportOverlayHandleBuilder.h`
|
||
- `editor/src/Viewport/SceneViewportMoveGizmo.h`
|
||
- `editor/src/Viewport/SceneViewportRotateGizmo.h`
|
||
- `editor/src/Viewport/SceneViewportScaleGizmo.h`
|
||
- `tests/Editor/test_scene_viewport_interaction_actions.cpp`
|
||
- `tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp`
|
||
- `tests/Editor/test_scene_viewport_interaction_resolver.cpp`
|
||
- `tests/Editor/test_scene_viewport_overlay_providers.cpp`
|
||
- 已确认问题:
|
||
- `IViewportHostService` / `ViewportHostService` / `SceneViewPanel` 文档仍在使用 `GetSceneViewInteractionOverlayFrameData(...)` 与 `SetSceneViewTransientTransformGizmoOverlayData(...)` 的旧双轨口径，但当前真实接口只剩 `SetSceneViewTransformGizmoOverlayState(...)` + `GetSceneViewEditorOverlayFrameData(...)`。
|
||
- `SceneViewportOverlayBuilder` / `SceneViewportOverlayProviders` 文档没有同步当前 optional `transformGizmoOverlayState`、`CreateSceneViewportTransformGizmoOverlayProvider()`，以及默认 registry 已注册 camera / light / transform gizmo provider 的事实。
|
||
- `SceneViewportEditorOverlayData` / `SceneViewportEditorOverlayPass` / `SceneViewportOverlayHitTester` 文档仍把 canonical frame 当成“仅世界线和图标”，没有同步 `screenTriangles` 与 `handleRecords` 已并入统一 frame data。
|
||
- 缺少 `SceneViewportInteractionActions.h` 的 canonical 目录，导致交互动作规范层没有文档入口。
|
||
- 缺少 `SceneViewportTransformGizmoCoordinator.h` 的 canonical 目录，且 `SceneViewPanel` 文档没有同步当前 overlay submission / lifecycle command helper 链路。
|
||
- move / rotate / scale gizmo 的 draw-data 与 state-query 页面仍在传播“面板直接把 `GetDrawData()` 变成临时 render overlay”的旧口径，未同步统一 gizmo state + provider 模式。
|
||
- 完成记录:
|
||
- 已新增 `SceneViewportInteractionActions/**`，补齐 hover-state / click-action / dispatch API 页面。
|
||
- 已新增 `SceneViewportTransformGizmoCoordinator/**`，补齐 overlay submission 与 gizmo lifecycle command 页面。
|
||
- 已重写 `Viewport.md`、`IViewportHostService/**`、`ViewportHostService/**`、`SceneViewPanel/**`，统一到当前 `SetSceneViewTransformGizmoOverlayState(...)` + canonical `SceneViewportOverlayFrameData` 链路。
|
||
- 已同步 `SceneViewportOverlayBuilder/**`、`SceneViewportOverlayProviders/**`、`SceneViewportEditorOverlayData/**`、`SceneViewportOverlayHitTester/**` 与 `SceneViewportEditorOverlayPass/**` 到当前 provider-registry + 统一 gizmo state 架构。
|
||
- 已同步 move / rotate / scale gizmo 的 draw-data / state-query 页面到当前统一 state 消费口径。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，结果为：`Valid source refs (Editor canonical): 129`、`Invalid header refs: 0`、`Invalid source refs: 0`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。
|
||
|
||
## T07 Scripting guide / 项目脚本程序集测试输出目录口径修正
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md`
|
||
- 主要源码依据:
|
||
- `managed/CMakeLists.txt`
|
||
- `tests/Scripting/CMakeLists.txt`
|
||
- `tests/Scripting/test_project_script_assembly.cpp`
|
||
- 已确认问题:
|
||
- guide 仍把 `tests/Scripting/test_project_script_assembly.cpp` 描述成“直接把 `assemblyDirectory` 指向 `project/Library/ScriptAssemblies`”。
|
||
- 当前真实测试口径已经改成优先使用 `XCENGINE_TEST_PROJECT_MANAGED_OUTPUT_DIR`，由 `xcengine_test_project_managed_assemblies` target 提供测试专用输出目录；未配置时 fallback 到 `build/managed/ProjectScriptAssemblies`。
|
||
- `project/Library/ScriptAssemblies/` 仍是 editor/runtime 项目程序集的真实输出目录，但它和测试专用输出目录不能混写成同一个概念。
|
||
- 完成记录:
|
||
- 已改写 `Project-Script-Assembly-And-Field-Sync.md`，把“真实项目输出目录”和“测试专用输出目录”拆开描述。
|
||
- 已明确 `test_project_script_assembly.cpp` 验证的是“项目 `Assets/**/*.cs` 被编译成可发现的 `GameScripts.dll`”这条链路，而不是直接依赖工作树里的 `project/Library/ScriptAssemblies/` 快照。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，结果为：`Public headers: 244`、`Editor source headers: 129`、`Broken .md links: 0`、`Stale canonical doc tokens: 0`、`Stale editor canonical pages: 0`。
|
||
|
||
## T08 Rendering / `RenderMaterialUtility` builtin-pass 元数据与资源绑定契约补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Rendering/RenderMaterialUtility/**`
|
||
- `docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/**`
|
||
- `docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/**`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Rendering/RenderMaterialUtility.h`
|
||
- `engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp`
|
||
- `engine/src/Rendering/Passes/BuiltinObjectIdPass.cpp`
|
||
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
|
||
- `tests/Rendering/unit/test_render_scene_extractor.cpp`
|
||
- 已确认问题:
|
||
- `RenderMaterialUtility.h` 当前已经公开 `BuiltinMaterialPass`、binding-plan struct、legacy fallback 绑定构造和 builtin pass 元数据匹配 helper，但 canonical 文档树仍只覆盖旧的材质解析 / render-state 子集。
|
||
- `MaterialConstantPayloadView` 与 `ResolveSchemaMaterialConstantPayload()` 文档仍停留在“只有 `data + size`”的旧口径，没有同步当前 `layout` 视图和 `layout.size == size` 的有效性约束。
|
||
- `BuiltinForwardPipeline` 与 `BuiltinObjectIdPass` 文档虽然已经写到 explicit resource contract，但还没有把 canonical 入口回链到 `RenderMaterialUtility` 的 binding-plan helper。
|
||
- 完成记录:
|
||
- 已新增 builtin pass 元数据 / 资源绑定契约页面，覆盖 `BuiltinMaterialPass`、`BuiltinPassResourceBindingPlan`、`TryBuildBuiltinPassResourceBindingPlan()`、legacy fallback 绑定构造与 shader-pass 元数据匹配 helper。
|
||
- 已新增 `MaterialConstantLayoutView.md`、`FindShaderPropertyBySemantic.md`，并同步 `MaterialConstantPayloadView.md`、`ResolveSchemaMaterialConstantPayload.md` 到当前 layout-aware 语义。
|
||
- 已重写 `RenderMaterialUtility.md` 的公开类型 / 函数索引，把 builtin pass 规范化与 binding-plan 契约纳入模块总览。
|
||
- 已同步 `BuiltinForwardPipeline.md` 与 `BuiltinObjectIdPass.md` 到当前 explicit binding-plan + legacy fallback 口径。
|
||
|
||
## T09 Rendering / `RenderMaterialUtility` 顶层 helper completeness 补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Rendering/RenderMaterialUtility/**`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Rendering/RenderMaterialUtility.h`
|
||
- `engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp`
|
||
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
|
||
- `tests/Rendering/unit/test_render_scene_extractor.cpp`
|
||
- 已确认问题:
|
||
- `RenderMaterialUtility.h` 的顶层公开符号里，`IsForwardPassName()` 等 pass-name alias helper、`ToRHI*` 状态映射 helper，以及 `MaterialRenderStateHash` 仍无对应 canonical 页面。
|
||
- `RenderMaterialUtility.md` 的索引也没有把这批顶层 helper 纳入公开函数 / 类型列表，导致文档目录和实际公开符号仍有一层颗粒度缺口。
|
||
- 完成记录:
|
||
- 已新增 `IsForwardPassName.md`、`IsUnlitPassName.md`、`IsDepthOnlyPassName.md`、`IsShadowCasterPassName.md`、`IsObjectIdPassName.md`。
|
||
- 已新增 `ToRHICullMode.md`、`ToRHIComparisonFunc.md`、`ToRHIBlendFactor.md`、`ToRHIBlendOp.md` 与 `MaterialRenderStateHash.md`。
|
||
- 已同步 `RenderMaterialUtility.md`，把这批 helper 和 hash functor 纳入模块索引。
|
||
- 已对照 `RenderMaterialUtility.h` 的顶层公开类型 / 函数名，确认当前 canonical 页已全覆盖。
|
||
|
||
## T10 Active API docs / 测试路径大小写按真实目录统一
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/_guides/**`
|
||
- `docs/api/XCEngine/**`
|
||
- 主要源码依据:
|
||
- `tests/`
|
||
- 已确认问题:
|
||
- 活跃文档里曾残留 `tests/core/...`、`tests/math/...`、`tests/scripting/...` 这类小写路径。
|
||
- 当前工作树真实目录名是 `tests/Core/`、`tests/Core/Math/`、`tests/Scripting/`；继续沿用小写写法会让文档和工程现实脱节。
|
||
- 这类问题与此前已收口的 `tests/Editor/` 一样，属于 Windows 工作树里最容易被忽略、但会持续制造噪音的路径口径漂移。
|
||
- 完成记录:
|
||
- 已把活跃 guide 与 canonical API 文档中的 `tests/Core/...`、`tests/Core/Math/...`、`tests/Scripting/...` 统一改成真实目录大小写。
|
||
- 本轮只收口活跃文档；`docs/plan/used/`、`docs/used/` 等归档材料继续保留历史写法。
|
||
|
||
## T11 Editor / Viewport 新增 header helper 补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/Viewport/Viewport.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/**`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `editor/src/Viewport/SceneViewportEditorModes.h`
|
||
- `editor/src/Viewport/SceneViewportInteractionFrame.h`
|
||
- `editor/src/Viewport/SceneViewportNavigation.h`
|
||
- `editor/src/Panels/SceneViewPanel.cpp`
|
||
- 已确认问题:
|
||
- 工作树里新增了 `SceneViewportEditorModes.h`、`SceneViewportInteractionFrame.h`、`SceneViewportNavigation.h` 三个 editor source header，但 canonical 文档树还没有对应目录页。
|
||
- `Viewport.md` 也没有把这三块新 helper 纳入当前职责拆分，导致 Scene View 交互装配和导航状态管理的真实入口在模块总览里缺席。
|
||
- 完成记录:
|
||
- 已新增 `SceneViewportEditorModes/SceneViewportEditorModes.md`，收口 tool / pivot / transform-space 三类模式枚举。
|
||
- 已新增 `SceneViewportInteractionFrame/SceneViewportInteractionFrame.md`，补齐 tool state、frame geometry、interaction frame state 与 resolve request 装配语义。
|
||
- 已新增 `SceneViewportNavigation/SceneViewportNavigation.md`，补齐快捷键、look/pan 导航、capture flags 与 `SceneViewportInput` 构建逻辑。
|
||
- 已补齐 `BuildSceneViewportTransformGizmoOverlayState.md`，并重写 `SceneViewPanel/**`、`SceneViewportOverlayHandleBuilder/**` 与 `SceneView-Interaction-And-Gizmo-Model.md` 的残留旧口径。
|
||
- 已顺手修复 `BuildSceneViewportGridPassData.md` 指向旧页名的坏链接。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Editor source headers: 133`、`Valid source refs (Editor canonical): 133`、`Invalid source refs: 0`、`Broken .md links: 0`。
|
||
|
||
## T12 Editor / Viewport `SceneViewportInteractionFrame` Phase 5G focus 与 presentation helper 同步
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationUpdate.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/Viewport.md`
|
||
- `docs/api/XCEngine/Editor/panels/SceneViewPanel/**`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `editor/src/Viewport/SceneViewportInteractionFrame.h`
|
||
- `editor/src/panels/SceneViewPanel.cpp`
|
||
- `tests/Editor/test_scene_viewport_interaction_frame.cpp`
|
||
- 已确认问题:
|
||
- `SceneViewportInteractionFrame.h` 当前已经新增 `ShouldFocusSceneViewportAfterInteraction()`、`SceneViewportPresentationRequest` 与 `RefreshAndDrawSceneViewportPresentation()`，但 canonical 目录下还没有对应页面，模块总览也仍停在“只做交互前 frame-state 装配”的旧口径。
|
||
- `SceneViewportNavigationUpdate.md` 仍写成 `beginLookDrag` / `beginPanDrag` 直接决定 `ImGui::SetWindowFocus()`；当前真实逻辑已经改成由 `ShouldFocusSceneViewportAfterInteraction(...)` 统一折叠 tool command、interaction action 与 navigation begin 标志。
|
||
- `Viewport.md` 与 `SceneViewPanel/**` 对 `SceneViewportInteractionFrame` 的职责描述还没有完整纳入 focus / presentation helper 这一层尾段语义。
|
||
- 完成记录:
|
||
- 已新增 `ShouldFocusSceneViewportAfterInteraction.md`、`SceneViewportPresentationRequest.md` 与 `RefreshAndDrawSceneViewportPresentation.md`，补齐 `SceneViewportInteractionFrame.h` 的新增公开入口。
|
||
- 已重写 `SceneViewportInteractionFrame.md`，把模块职责从“交互前 frame-state 装配”扩展到当前真实的 focus 决策与 presentation 尾段收口语义。
|
||
- 已同步 `SceneViewportNavigationUpdate.md`、`Viewport.md`、`SceneViewPanel/Render.md` 与 `SceneViewPanel.md`，移除 `SetWindowFocus()` / presentation tail 的旧口径描述。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Editor source headers: 133`、`Valid source refs (Editor canonical): 133`、`Invalid source refs: 0`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。
|
||
|
||
## T13 Editor / Viewport `SceneViewportChrome` 与 `SceneViewPanel` 当前编排链补正
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/**`
|
||
- `docs/api/XCEngine/Editor/panels/SceneViewPanel/**`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `editor/src/Viewport/SceneViewportChrome.h`
|
||
- `editor/src/Viewport/SceneViewportChrome.cpp`
|
||
- `editor/src/panels/SceneViewPanel.h`
|
||
- `editor/src/panels/SceneViewPanel.cpp`
|
||
- `tests/Editor/test_scene_viewport_chrome.cpp`
|
||
- 已确认问题:
|
||
- `SceneViewportChrome.md` 仍写成“没有独立单元测试”，但当前工作树已经存在 `tests/Editor/test_scene_viewport_chrome.cpp`，并覆盖工具命令折叠与执行规则。
|
||
- `SceneViewPanel.md` 与 `Render.md` 仍残留旧的 helper 列表和编排口径，没有完整对齐当前真实调用顺序，包括工具命令执行、focus 决策以及 `RefreshAndDrawSceneViewportPresentation(...)` 收口。
|
||
- 完成记录:
|
||
- 已修正 `SceneViewportChrome.md` 的测试锚点描述，明确区分“命令折叠规则已有单测”和“UI 绘制细节仍由源码调用链锚定”。
|
||
- 已重写 `SceneViewPanel.md` 与 `Render.md`，按当前源码同步 `Chrome -> InteractionFrame -> Navigation -> InteractionActions -> Presentation` 的真实编排链。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Editor source headers: 133`、`Valid source refs (Editor canonical): 133`、`Invalid source refs: 0`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。
|
||
|
||
## T14 Core / Asset `ArtifactFormats` shader artifact 正文布局补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Core/Asset/ArtifactFormats/ArtifactFormats.md`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Core/Asset/ArtifactFormats.h`
|
||
- `engine/src/Core/Asset/AssetDatabase.cpp`
|
||
- `engine/src/Resources/Shader/ShaderLoader.cpp`
|
||
- `tests/Resources/Shader/test_shader_loader.cpp`
|
||
- 已确认问题:
|
||
- `ArtifactFormats.md` 的 shader artifact 小节当前只列出了几种头结构名，没有像 material / mesh 一样写清真实正文布局，缺少 name/source-path 字符串、property 段、per-pass tag/resource/variant 段以及 `compiledBinary` payload 的写入顺序。
|
||
- 同页“读取侧”当前漏写了 `.xcshader` 的真实消费者 `ShaderLoader`。
|
||
- 写入侧对 shader 只写了“产出 shader artifact”，没有和当前实现保持同样的主 artifact 文件名口径 `main.xcshader`。
|
||
- 完成记录:
|
||
- 已为 `ArtifactFormats.md` 的 shader artifact 小节补齐当前正文布局，明确名称/路径字符串、property 段、pass tag/resource/variant 段以及 `compiledBinary` payload 的写入顺序。
|
||
- 已补充 shader artifact 的 schema 值、`main.xcshader` 主 artifact 文件名，以及读取侧 `ShaderLoader` 的真实消费链。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 244`、`Editor source headers: 133`、`Invalid header refs: 0`、`Invalid source refs: 0`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。
|
||
|
||
## T15 Resources / Material `Material.h` 公开符号 completeness 补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Resources/Material/Material/**`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Resources/Material/Material.h`
|
||
- `engine/src/Resources/Material/Material.cpp`
|
||
- `tests/Resources/Material/test_material.cpp`
|
||
- `tests/Resources/Material/test_material_loader.cpp`
|
||
- `tests/Rendering/unit/test_render_scene_extractor.cpp`
|
||
- 已确认问题:
|
||
- `Material.h` 当前已经公开 `renderQueue / renderState / shaderPass / tags / constant layout / change version` 这一整组运行时接口，但 canonical 文档树仍主要停留在“数值属性 + 纹理绑定”子集，缺少大量类型页与方法页。
|
||
- 缺页不仅包括 `SetRenderQueue()`、`SetRenderState()`、`SetShaderPass()`、tag API、`GetConstantLayout()`、`FindConstantField()`、`GetChangeVersion()`、`RecalculateMemorySize()`，还包括 `MaterialRenderQueue`、`MaterialRenderState`、`MaterialConstantFieldDesc`、`MaterialTagEntry`、`PendingTextureLoadState` 等公开类型。
|
||
- `Material/Material.md` 的声明索引也没有把这批 render metadata / tag / constant-layout 相关公开符号纳入模块总览。
|
||
- 完成记录:
|
||
- 已补齐 `Material.h` 当前公开的 render metadata / tag / constant-layout 相关类型页与方法页，并重写 `Material.md` 的模块索引。
|
||
- 已把 `renderQueue / renderState / shaderPass / tags / texture bindings / properties / constant layout / change version` 这一整组运行时接口同步到 canonical 文档树。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 136`、`Invalid header refs: 0`、`Invalid source refs: 0`、`Broken .md links: 0`。
|
||
|
||
## T16 Editor / Viewport `SceneViewportOverlaySpriteResources` 新增头文件补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/Viewport.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/**`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `editor/src/Viewport/SceneViewportOverlaySpriteResources.h`
|
||
- `editor/src/Viewport/SceneViewportOverlaySpriteResources.cpp`
|
||
- `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.h`
|
||
- `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.cpp`
|
||
- `tests/Editor/test_scene_viewport_overlay_sprite_resources.cpp`
|
||
- 已确认问题:
|
||
- 工作树当前新增了 `SceneViewportOverlaySpriteResources.h`，但 canonical 文档树还没有对应目录页，导致结构审计一度出现 `Editor source headers: 136` / `Valid source refs (Editor canonical): 135`。
|
||
- `SceneViewportEditorOverlayPass` 文档仍把 camera / light icon 纹理描述成 pass 内部细节，没有同步当前已经拆出的“资源路径解析 + RGBA 解码 + descriptor set 缓存”辅助层。
|
||
- `SceneViewportOverlaySpriteTextureKind` 当前已经不再直接隐含具体文件路径；真实资源解析口径来自新头文件里的 helper 与 cache。
|
||
- 完成记录:
|
||
- 已新增 `SceneViewportOverlaySpriteResources` canonical 目录，补齐 texture-kind 映射、asset spec、pixel payload、像素加载与 GPU 资源缓存页面。
|
||
- 已同步 `Viewport.md`、`SceneViewportEditorOverlayData.md` 与 `SceneViewportEditorOverlayPass/**`，把 sprite overlay 资源准备链路改写为当前真实的 helper-header + cache 模型。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 136`、`Valid source refs (Editor canonical): 136`、`Invalid source refs: 0`、`Broken .md links: 0`。
|
||
|
||
## T17 Editor / Viewport `SceneViewportShaderPaths` 兼容层化与 pass-spec wrapper 类型口径收口
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/**`
|
||
- `docs/api/XCEngine/Resources/BuiltinResources/BuiltinResources.md`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `editor/src/Viewport/SceneViewportShaderPaths.h`
|
||
- `editor/src/Viewport/SceneViewportResourcePaths.h`
|
||
- `editor/src/Viewport/SceneViewportPassSpecs.h`
|
||
- `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
|
||
- `editor/src/Viewport/SceneViewportRenderPlan.h`
|
||
- `editor/src/Viewport/Passes/SceneViewportGridPass.h`
|
||
- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp`
|
||
- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.h`
|
||
- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp`
|
||
- `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.h`
|
||
- `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.cpp`
|
||
- `engine/include/XCEngine/Resources/BuiltinResources.h`
|
||
- `tests/Editor/test_scene_viewport_shader_paths.cpp`
|
||
- `tests/Editor/test_viewport_render_flow_utils.cpp`
|
||
- 已确认问题:
|
||
- `SceneViewportShaderPaths.h` 当前已经退化为只包含 `SceneViewportResourcePaths.h` 的兼容头，但部分文档仍把它写成路径 helper 的真实 owner。
|
||
- `BuildSceneViewportGridPassData()`、`BuildSceneViewportSelectionOutlineStyle()`、两类 factory alias，以及 grid / selection-outline pass 适配页仍沿用旧签名，把 editor wrapper 类型写成 runtime `InfiniteGridPassData` / `ObjectIdOutlineStyle`。
|
||
- `SceneViewportEditorOverlayPass` 与 `BuiltinResources.md` 仍残留一部分旧口径，没有完全同步 sprite resource cache 和新的 builtin shader 集合。
|
||
- 完成记录:
|
||
- 已把 `SceneViewportShaderPaths/**` 收口为“兼容 include 层 + 迁移说明”口径，并统一回链当前真实 owner `SceneViewportResourcePaths`。
|
||
- 已同步 `ViewportHostRenderFlowUtils/**`、`SceneViewportRenderPlan/**`、`SceneViewportGridPass/**` 与 `SceneViewportSelectionOutlinePass/**` 到当前 `SceneViewportGridPassData` / `SceneViewportSelectionOutlineStyle` wrapper 类型，以及 `ToBuiltin...` 转换链。
|
||
- 已补充 `SceneViewportEditorOverlayPass/**` 对 `SceneViewportOverlaySpriteResourceCache` 的引用，并把 `BuiltinResources.md` 改到当前 builtin shader 集合 `forward-lit / unlit / depth-only / shadow-caster / object-id`。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 136`、`Valid header refs (canonical): 247`、`Valid source refs (Editor canonical): 136`、`Broken .md links: 0`。
|
||
|
||
## T18 Rendering / `CameraRenderer` depth-only 与 shadow-caster pass 注入链补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Rendering/CameraRenderer/**`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Rendering/CameraRenderer.h`
|
||
- `engine/src/Rendering/CameraRenderer.cpp`
|
||
- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
|
||
- 已确认问题:
|
||
- `CameraRenderer.h` 当前已经公开 `SetDepthOnlyPass()`、`SetShadowCasterPass()`、`GetDepthOnlyPass()`、`GetShadowCasterPass()`，但 canonical 文档树还停留在只有主管线与 object-id pass 的旧索引。
|
||
- `Constructor.md` 仍把最高阶构造重载写成只有 `(pipeline, objectIdPass)`，没有同步当前 `depthOnlyPass / shadowCasterPass` 注入点。
|
||
- `Render.md` 仍把执行链写成 `pre -> pipeline -> object-id -> post -> overlay`，没有同步当前先跑 `shadowCaster` 和 `depthOnly` 请求的真实顺序。
|
||
- 完成记录:
|
||
- 已补齐 `SetDepthOnlyPass.md`、`SetShadowCasterPass.md`、`GetDepthOnlyPass.md`、`GetShadowCasterPass.md`。
|
||
- 已重写 `CameraRenderer.md`、`Constructor.md`、`Render.md` 与 `Destructor.md`，同步当前 depth-only / shadow-caster pass 的持有、回退与执行链语义。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Broken .md links: 0`、`Stale canonical doc tokens: 0`。
|
||
|
||
## T19 Editor / Viewport `SceneViewportOverlayFrameCache` 新增头文件补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/Viewport.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/ViewportHostService/SceneView-Overlay-Frame-Data.md`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `editor/src/Viewport/SceneViewportOverlayFrameCache.h`
|
||
- `editor/src/Viewport/SceneViewportOverlayFrameCache.cpp`
|
||
- `editor/src/Viewport/ViewportHostService.h`
|
||
- `tests/Editor/test_scene_viewport_overlay_frame_cache.cpp`
|
||
- 已确认问题:
|
||
- 工作树新增了 `SceneViewportOverlayFrameCache.h`，但 canonical 文档树没有对应目录页，导致结构审计一度出现 `Editor source headers: 137` / `Valid source refs (Editor canonical): 136`。
|
||
- `Viewport` 与 `ViewportHostService/SceneView-Overlay-Frame-Data.md` 仍在用“宿主类内部散落 cache key”的旧口径，没有把 viewport 尺寸解析、内容签名与重建判定收口到新 helper header。
|
||
- 完成记录:
|
||
- 已新增 `SceneViewportOverlayFrameCache/**`，补齐 cache state、viewport 尺寸解析、内容签名、overlay 比较与重建判定页面。
|
||
- 已同步 `Viewport.md` 与 `ViewportHostService/SceneView-Overlay-Frame-Data.md`，把 Scene View editor overlay frame 的缓存链路改写到当前 helper-header 模型。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 137`、`Valid source refs (Editor canonical): 137`、`Broken .md links: 0`。
|
||
|
||
## T20 Editor / Viewport `SceneViewportRenderPassBundle` 上层总览与 guide 口径同步
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/Viewport/Viewport.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/SceneViewportGridPass.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md`
|
||
- `docs/api/_guides/Editor/Scene-Viewport-Render-Plan-And-Failure-Flow.md`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `editor/src/Viewport/ViewportHostService.h`
|
||
- `editor/src/Viewport/SceneViewportRenderPassBundle.h`
|
||
- `editor/src/Viewport/SceneViewportRenderPassBundle.cpp`
|
||
- `editor/src/Viewport/SceneViewportRenderPlan.h`
|
||
- `editor/src/Viewport/Passes/SceneViewportGridPass.h`
|
||
- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.h`
|
||
- `tests/Editor/test_scene_viewport_render_pass_bundle.cpp`
|
||
- `tests/Editor/test_viewport_render_flow_utils.cpp`
|
||
- 已确认问题:
|
||
- `SceneViewportRenderPassBundle` 的 canonical 页面虽然已经存在，但 `Viewport.md`、`ViewportHostService.md`、`Initialize-And-Shutdown.md`、`RenderRequestedViewports.md`、`SceneViewportRenderPlan.md` 与 Scene View render-plan guide 仍在传播旧口径，把宿主服务写成“直接持有三个 pass renderer”或“直接调用 `BuildSceneViewportRenderPlan(...)`”。
|
||
- `SceneViewportGridPass.md`、`SceneViewportSelectionOutlinePass.md` 与 `SceneViewportGridPassFactory.md` 仍把 factory 绑定位置写成 `ViewportHostService` 上的旧 renderer 成员，而不是当前 bundle 内部成员。
|
||
- `Viewport.md` 还没有把 `SceneViewportResourcePaths`、`SceneViewportPassSpecs`、`SceneViewportRenderPlan`、`SceneViewportRenderPassBundle` 与 `ViewportHostRenderFlowUtils` 纳入当前模块总览。
|
||
- 完成记录:
|
||
- 已同步 `Viewport.md`、`ViewportHostService/**`、`SceneViewportRenderPlan/**` 与 Scene View render-plan guide 到当前真实链路：`ViewportHostService -> SceneViewportRenderPassBundle -> BuildSceneViewportRenderPlan / ApplySceneViewportRenderPlan`。
|
||
- 已修正 grid / selection-outline 相关页面，把 factory 绑定和 renderer 生命周期表述改成 bundle 持有模型，并补上新的上层交叉链接。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 138`、`Valid source refs (Editor canonical): 138`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。
|
||
|
||
## T21 XCUI / `Resources/UI` / `UI/Types` / `UI/DrawData` / Editor transition header 补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Resources/UI/**`
|
||
- `docs/api/XCEngine/UI/UI.md`
|
||
- `docs/api/XCEngine/UI/Types/**`
|
||
- `docs/api/XCEngine/UI/DrawData/**`
|
||
- `docs/api/XCEngine/Editor/Editor.md`
|
||
- `docs/api/XCEngine/Editor/XCUIBackend/**`
|
||
- `docs/api/XCEngine/Editor/Platform/Platform.md`
|
||
- `docs/api/XCEngine/Editor/Platform/D3D12WindowRendererImGuiInterop/**`
|
||
- `docs/api/XCEngine/Editor/panels/panels.md`
|
||
- `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/**`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Resources/UI/UIDocumentTypes.h`
|
||
- `engine/include/XCEngine/Resources/UI/UIDocumentCompiler.h`
|
||
- `engine/include/XCEngine/Resources/UI/UIDocuments.h`
|
||
- `engine/include/XCEngine/Resources/UI/UIDocumentLoaders.h`
|
||
- `engine/src/Resources/UI/UIDocumentCompiler.cpp`
|
||
- `engine/src/Resources/UI/UIDocuments.cpp`
|
||
- `engine/src/Resources/UI/UIDocumentLoaders.cpp`
|
||
- `engine/include/XCEngine/UI/Types.h`
|
||
- `engine/include/XCEngine/UI/DrawData.h`
|
||
- `editor/src/XCUIBackend/ImGuiTransitionBackend.h`
|
||
- `editor/src/XCUIBackend/XCUIDemoRuntime.h`
|
||
- `editor/src/Platform/D3D12WindowRendererImGuiInterop.h`
|
||
- `editor/src/panels/XCUIDemoPanel.h`
|
||
- `editor/src/panels/XCUIDemoPanel.cpp`
|
||
- `editor/src/Application.cpp`
|
||
- `editor/src/Core/EditorWorkspace.h`
|
||
- `tests/Resources/UI/test_ui_document_loader.cpp`
|
||
- `tests/Resources/UI/test_ui_schema_document.cpp`
|
||
- `tests/UI/Core/unit/test_ui_core.cpp`
|
||
- `tests/Editor/test_xcui_imgui_transition_backend.cpp`
|
||
- `tests/Editor/test_window_renderer_api.cpp`
|
||
- 已确认问题:
|
||
- `Resources/UI` 模块总览已经存在，但四个 public header 仍缺少 canonical 页面。
|
||
- `UI/Types.h` 与 `UI/DrawData.h` 已被 runtime、Scene 和 editor transition backend 大量使用，但根模块入口页还没有把它们纳入顶层 API。
|
||
- `editor/src/XCUIBackend`、`editor/src/Platform/D3D12WindowRendererImGuiInterop.h` 与 `editor/src/panels/XCUIDemoPanel.h` 没有 source-backed API 页面，导致 Editor 侧 XCUI transition 链路存在结构缺口。
|
||
- 完成记录:
|
||
- 已新增 `UIDocumentTypes`、`UIDocumentCompiler`、`UIDocumentLoaders`、`UIDocuments`、`Types`、`DrawData`、`XCUIBackend`、`ImGuiTransitionBackend`、`XCUIDemoRuntime`、`D3D12WindowRendererImGuiInterop`、`XCUIDemoPanel` 页面。
|
||
- 已同步 `Resources/UI/UI.md`、`UI/UI.md`、`Editor.md`、`Platform.md` 与 `panels.md`，把 UI 资源层、XCUI transition backend 和 demo panel 纳入当前模块入口。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Editor source headers: 142`、`Valid source refs (Editor canonical): 142`、`Invalid source refs: 0`、`Broken .md links: 0`。
|
||
|
||
## T22 RHI / Shader formalization 文档补页与 `MaterialRenderState` 归位
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/RHI/ShaderCompiler/**`
|
||
- `docs/api/XCEngine/Resources/Shader/**`
|
||
- `docs/api/XCEngine/Resources/Material/**`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/RHI/ShaderCompiler/SpirvShaderCompiler.h`
|
||
- `engine/src/RHI/ShaderCompiler/SpirvShaderCompiler.cpp`
|
||
- `engine/src/RHI/Vulkan/VulkanShaderCompiler.cpp`
|
||
- `engine/src/RHI/OpenGL/OpenGLDevice.cpp`
|
||
- `engine/include/XCEngine/Resources/Shader/ShaderKeywordTypes.h`
|
||
- `engine/src/Resources/Shader/ShaderLoader.cpp`
|
||
- `engine/src/Resources/Shader/Shader.cpp`
|
||
- `engine/include/XCEngine/Resources/Material/MaterialRenderState.h`
|
||
- `engine/src/Resources/Material/Material.cpp`
|
||
- `tests/Resources/Shader/test_shader_loader.cpp`
|
||
- `tests/Resources/Shader/test_shader.cpp`
|
||
- `tests/Resources/Material/test_material.cpp`
|
||
- `tests/Rendering/unit/test_render_scene_extractor.cpp`
|
||
- 已确认问题:
|
||
- `SpirvShaderCompiler.h` 与 `ShaderKeywordTypes.h` 已进入当前工作树，但 canonical API 树缺少对应入口页。
|
||
- `MaterialRenderState` 及其相关枚举页仍沿用旧归属，`头文件` 元信息还停在 `Material.h`。
|
||
- 复核过程中发现 `ShaderRenderState.h` 并不在当前 public header 集合里，说明不能把计划中的 formalized pass-state 设想误写成现有 API 页面。
|
||
- 完成记录:
|
||
- 已新增 `SpirvShaderCompiler/SpirvShaderCompiler.md` 与 `ShaderKeywordTypes/ShaderKeywordTypes.md`，并同步 `ShaderCompiler.md`、`Resources/Shader/Shader.md`。
|
||
- 已把 `MaterialRenderState`、`MaterialCullMode`、`MaterialComparisonFunc`、`MaterialBlendOp`、`MaterialBlendFactor` 的 `头文件` 归位到 `MaterialRenderState.h`，并更新 `Resources/Material/Material.md`。
|
||
- 已删除误建的 `ShaderRenderState` canonical 页面，并重新运行审计，确认 `Public headers: 304`、`Invalid header refs: 0`、`Broken .md links: 0`。
|
||
|
||
## T23 UI / Core + Input header coverage 补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/UI/Core/**`
|
||
- `docs/api/XCEngine/UI/Input/**`
|
||
- `docs/api/XCEngine/UI/UI.md`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/UI/Core/UIBuildContext.h`
|
||
- `engine/include/XCEngine/UI/Core/UIContext.h`
|
||
- `engine/include/XCEngine/UI/Core/UIElementTree.h`
|
||
- `engine/include/XCEngine/UI/Core/UIInvalidation.h`
|
||
- `engine/include/XCEngine/UI/Core/UIViewModel.h`
|
||
- `engine/include/XCEngine/UI/Input/UIFocusController.h`
|
||
- `engine/include/XCEngine/UI/Input/UIInputDispatcher.h`
|
||
- `engine/include/XCEngine/UI/Input/UIInputPath.h`
|
||
- `engine/include/XCEngine/UI/Input/UIInputRouter.h`
|
||
- `engine/include/XCEngine/UI/Input/UIShortcutRegistry.h`
|
||
- `engine/src/UI/Core/**`
|
||
- `engine/src/UI/Input/**`
|
||
- `tests/UI/Core/unit/**`
|
||
- `tests/UI/Runtime/unit/**`
|
||
- 已确认问题:
|
||
- 最新审计显示 `UI` 模块当前只覆盖 `2 / 37`，剩余缺口里最基础的一批就是 `Core` 与 `Input`。
|
||
- 这些头文件已经有真实 `.cpp`、单测和 runtime 调用链，但 canonical API 树仍停留在目录总览页。
|
||
- 完成记录:
|
||
- 已新增 `UIBuildContext`、`UIContext`、`UIElementTree`、`UIInvalidation`、`UIViewModel`、`UIFocusController`、`UIInputDispatcher`、`UIInputPath`、`UIInputRouter`、`UIShortcutRegistry` 页面。
|
||
- 已同步 `Core.md`、`Input.md` 与 `UI.md`，把 retained-mode build / diff 主链和输入分发主链纳入当前模块入口。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Valid header refs (canonical): 279`、`Invalid header refs: 0`、`Invalid source refs: 0`、`Broken .md links: 0`。
|
||
|
||
## T24 UI / Layout + Runtime + Style + Text + Widgets header coverage 补页
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/UI/Layout/**`
|
||
- `docs/api/XCEngine/UI/Runtime/**`
|
||
- `docs/api/XCEngine/UI/Style/**`
|
||
- `docs/api/XCEngine/UI/Text/**`
|
||
- `docs/api/XCEngine/UI/Widgets/**`
|
||
- `docs/api/XCEngine/UI/UI.md`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/UI/Layout/*.h`
|
||
- `engine/include/XCEngine/UI/Runtime/*.h`
|
||
- `engine/include/XCEngine/UI/Style/*.h`
|
||
- `engine/include/XCEngine/UI/Text/*.h`
|
||
- `engine/include/XCEngine/UI/Widgets/*.h`
|
||
- `engine/src/UI/Runtime/**`
|
||
- `engine/src/UI/Style/**`
|
||
- `engine/src/UI/Text/**`
|
||
- `engine/src/UI/Widgets/**`
|
||
- `tests/UI/Core/unit/**`
|
||
- `tests/UI/Runtime/unit/**`
|
||
- `tests/Scene/test_scene_runtime.cpp`
|
||
- 已确认问题:
|
||
- `Layout / Runtime / Style / Text / Widgets` 还剩 `25` 个未覆盖 public headers，是当前 API 文档最大的连续缺口。
|
||
- 这些头文件里既有 header-only layout / interaction helper，也有真实 source-backed runtime / style / widget 状态模型；如果不拆开写，overview 很容易继续混淆“声明契约”和“当前实现行为”。
|
||
- 当前进展:
|
||
- 已新增 `LayoutTypes`、`LayoutEngine`、`UISplitterLayout`、`UITabStripLayout`、`UIScreenTypes`、`UISceneRuntimeContext`、`UIScreenDocumentHost`、`UIScreenPlayer`、`UIScreenStackController`、`UISystem`、`StyleTypes`、`StyleSet`、`Theme`、`StyleResolver`、`DocumentStyleCompiler`、`UITextEditing`、`UITextInputController`、`UIExpansionModel`、`UIFlatHierarchyHelpers`、`UIKeyboardNavigationModel`、`UIPopupOverlayModel`、`UIPropertyEditModel`、`UISelectionModel`、`UISplitterInteraction`、`UITabStripModel` 页面。
|
||
- 已同步 `Layout.md`、`Runtime.md`、`Style.md`、`Text.md`、`Widgets.md` 与 `UI.md`，把 header-only helper 和 source-backed runtime/style/widget 状态模型拆开归位。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，结果为：`Valid header refs (canonical): 304`、`UI: 37/37`、`Invalid source refs: 0`、`Broken .md links: 0`。
|
||
|
||
## T25 Editor UI 壳层与 `RenderMaterialResolve` 增量漂移复核
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P1`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md`
|
||
- `docs/api/XCEngine/Editor/panels/ViewportPanelContent/ViewportPanelContent.md`
|
||
- `docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md`
|
||
- `docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md`
|
||
- 主要源码依据:
|
||
- `editor/src/UI/ImGuiSession.h`
|
||
- `editor/src/panels/ViewportPanelContent.h`
|
||
- `editor/src/Layout/DockLayoutController.h`
|
||
- `engine/include/XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||
- `engine/src/RHI/D3D12/D3D12ResourceView.cpp`
|
||
- `engine/include/XCEngine/Input/InputTypes.h`
|
||
- `engine/include/XCEngine/Threading/TaskSystem.h`
|
||
- 已确认问题:
|
||
- `ImGuiSession.md` 仍停留在旧的“单字体 + 简单初始化”口径，没有同步 `SetProjectPath()` / `GetIniPath()`、双字体回退链和 DPI 配置。
|
||
- `ViewportPanelContent.md` 没有写出当前 `AllowWhenOverlappedByItem` 的 hover/click 采样语义，容易误解 toolbar 覆盖视口时的交互行为。
|
||
- `DockLayoutController.md` 没有同步当前 main viewport work-area、dock tab bar chrome 配置和 reset 延迟到下一帧重建的真实路径。
|
||
- `RenderMaterialResolve.md` 漏掉了一批已经公开的 render-queue / legacy pass-fallback helper，也没把常量 payload 有效性和 skybox 模式优先级写清。
|
||
- 完成记录:
|
||
- 已重写 `ImGuiSession.md`，补齐 `Initialize(projectPath, mainDpiScale)`、`GetIniPath()`、`SetProjectPath()`、Segoe UI + 微软雅黑 fallback 和 DPI 钳制逻辑。
|
||
- 已更新 `ViewportPanelContent.md`，补上 overlappable 交互表面、root-child focus 与状态文案依赖 item rect 的当前实现说明。
|
||
- 已更新 `DockLayoutController.md`，同步 dock host work-area、tab bar chrome 配置与 reset/rebuild 触发链。
|
||
- 已更新 `RenderMaterialResolve.md`，补齐 render queue tag 解析、legacy builtin pass fallback、skybox 纹理模式优先级和常量 payload 有效性边界。
|
||
- 抽查 `InputTypes`、`TaskSystem` 与 `D3D12ResourceView` 后，本轮未发现新的明确文档失配。
|
||
|
||
## T26 API 文档目录重大重构回归波次（2026-04-09 / 2026-04-10）
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Resources/Volume/**`
|
||
- `docs/api/XCEngine/Components/VolumeRendererComponent/**`
|
||
- `docs/api/XCEngine/Rendering/FrameData/**`
|
||
- `docs/api/XCEngine/Rendering/Passes/**`
|
||
- `docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/**`
|
||
- `docs/api/XCEngine/UI/Widgets/**`
|
||
- `docs/api/XCEngine/Editor/ComponentEditors/**`
|
||
- `docs/api/XCEngine/Editor/panels/**`
|
||
- `docs/api/XCEngine/Editor/Viewport/Passes/**`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Resources/Volume/VolumeField.h`
|
||
- `engine/include/XCEngine/Resources/Volume/VolumeFieldLoader.h`
|
||
- `engine/include/XCEngine/Components/VolumeRendererComponent.h`
|
||
- `engine/include/XCEngine/Rendering/FrameData/VisibleVolumeItem.h`
|
||
- `engine/include/XCEngine/Rendering/Passes/BuiltinSelectionMaskPass.h`
|
||
- `engine/include/XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass.h`
|
||
- `engine/include/XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`
|
||
- `engine/include/XCEngine/UI/Widgets/UIDragDropInteraction.h`
|
||
- `engine/include/XCEngine/UI/Widgets/UIScrollModel.h`
|
||
- `editor/src/ComponentEditors/VolumeRendererComponentEditor.h`
|
||
- `editor/src/panels/MaterialInspectorMaterialState.h`
|
||
- `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||
- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.h`
|
||
- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp`
|
||
- 已确认问题:
|
||
- 重大重构后，`Volume` 资源、体渲染组件、`visibleVolumes` 帧数据主链、selection mask / outline pass、UI widget helpers 与若干 Editor source-backed 页面尚未完全进入 canonical API 树。
|
||
- `SceneViewportSelectionOutlinePass` 文档仍停留在旧的 object-id outline 口径，与当前 `BuiltinSelectionMaskPass + BuiltinSelectionOutlinePass` 的两段链路不符。
|
||
- `XCUIDemoPanel` 历史页与若干旧交叉引用已不再对应当前源码树，需要从 active source-backed 叙事中清理。
|
||
- 完成记录:
|
||
- 已补齐 `Volume.md`、`VolumeField.md`、`VolumeFieldLoader.md`、`VolumeRendererComponent.md`、`VisibleVolumeItem.md`、`BuiltinSelectionMaskPass.md`、`BuiltinSelectionOutlinePass.md`、`BuiltinVolumetricPass.md`、`UIDragDropInteraction.md`、`UIScrollModel.md`、`VolumeRendererComponentEditor.md`、`MaterialInspectorMaterialState.md`、`MaterialInspectorMaterialStateIO.md` 等缺页，并同步相关 overview 页面。
|
||
- 已把 `RenderSceneData`、`RenderSceneExtractor`、`BuiltinForwardPipeline`、`Passes.md` 与 `SceneViewportSelectionOutlinePass/**` 对齐到当前真实调用链。
|
||
- 已清理 `XCUIDemoPanel` 作为当前 source-backed 页面/调用链入口的残留口径。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 313`、`Editor source headers: 144`、`Valid header refs (canonical): 313`、`Valid source refs (Editor canonical): 144`、`Broken .md links: 0`、`Missing directory index pages: 0`、`Editor high-risk single-page dirs: 0`。
|
||
|
||
## T27 Rendering / 目录归位收口与新结构口径修正（2026-04-10）
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Rendering/**`
|
||
- `docs/api/_tools/audit_api_docs.py`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- `docs/plan/API文档目录结构第二轮并行任务板_2026-04-09.md`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Rendering/Execution/CameraRenderer.h`
|
||
- `engine/include/XCEngine/Rendering/Execution/SceneRenderer.h`
|
||
- `engine/include/XCEngine/Rendering/Planning/CameraRenderRequest.h`
|
||
- `engine/include/XCEngine/Rendering/Planning/SceneRenderRequestPlanner.h`
|
||
- `engine/include/XCEngine/Rendering/Extraction/RenderSceneExtractor.h`
|
||
- `engine/include/XCEngine/Rendering/Extraction/RenderSceneUtility.h`
|
||
- `engine/src/Rendering/Execution/CameraRenderer.cpp`
|
||
- `engine/src/Rendering/Execution/SceneRenderer.cpp`
|
||
- `engine/src/Rendering/Planning/SceneRenderRequestPlanner.cpp`
|
||
- 已确认问题:
|
||
- `Rendering` 根目录旧位置页已经删除，但总览页、planner 说明和审计脚本的 stale-token 路径仍部分停留在重构前口径。
|
||
- `Rendering.md` 仍把 fullscreen 阶段漏在主流程外，并继续把 `RenderMaterialUtility` 描述成当前真实头文件入口。
|
||
- `SceneRenderRequestPlanner.md` / `BuildRequests.md` 还没有写出 `DirectionalShadowPlanningSettings` 和自动方向光阴影计划的真实补全过程。
|
||
- `audit_api_docs.py` 的 canonical stale-token 检查仍挂在旧的 `Rendering/CameraRenderer`、`Rendering/CameraRenderRequest` 路径上，无法覆盖新的 `Execution/`、`Planning/` 目录。
|
||
- 完成记录:
|
||
- 已确认旧顶层 `CameraRenderer`、`SceneRenderer`、`CameraRenderRequest`、`SceneRenderRequestPlanner`、`SceneRenderRequestUtils`、`RenderCameraData`、`RenderResourceCache`、`RenderSceneExtractor`、`RenderSceneUtility` canonical 目录都已退出 active 树，只保留真实子模块位置。
|
||
- 已更新 `Rendering.md`、`Builtin.md`、`Materials.md`，把 builtin / materials 拆分后的真实入口与兼容主题页边界写清，并把 `postProcess -> finalOutput -> objectId` 重新纳入主流程顺序。
|
||
- 已更新 `SceneRenderRequestPlanner.md` 与 `BuildRequests.md`，补齐 `DirectionalShadowPlanningSettings`、planner 的 setter/getter，以及自动方向光阴影计划写回 `shadowCaster` override 的当前实现。
|
||
- 已把审计脚本中的 stale canonical path 从旧顶层 Rendering 目录迁到新的 `Planning/CameraRenderRequest` 与 `Execution/CameraRenderer` 位置。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 384`、`Valid header refs (canonical): 384`、`Editor source headers: 144`、`Valid source refs (Editor canonical): 144`、`Broken .md links: 0`、`Missing directory index pages: 0`、`Editor high-risk single-page dirs: 0`。
|
||
|
||
## T28 Resources / `Model` + `GaussianSplat` canonical 入口补齐（2026-04-10）
|
||
|
||
- 状态: `DONE`
|
||
- 认领人: `Codex`
|
||
- 优先级: `P0`
|
||
- 写入范围:
|
||
- `docs/api/XCEngine/Resources/Model/**`
|
||
- `docs/api/XCEngine/Resources/GaussianSplat/**`
|
||
- `docs/api/XCEngine/Resources/Resources.md`
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
- 主要源码依据:
|
||
- `engine/include/XCEngine/Resources/Model/AssimpModelImporter.h`
|
||
- `engine/include/XCEngine/Resources/Model/Model.h`
|
||
- `engine/include/XCEngine/Resources/Model/ModelArtifactIO.h`
|
||
- `engine/include/XCEngine/Resources/Model/ModelLoader.h`
|
||
- `engine/include/XCEngine/Resources/GaussianSplat/GaussianSplat.h`
|
||
- `engine/include/XCEngine/Resources/GaussianSplat/GaussianSplatArtifactIO.h`
|
||
- `engine/include/XCEngine/Resources/GaussianSplat/GaussianSplatLoader.h`
|
||
- `engine/src/Resources/GaussianSplat/GaussianSplat.cpp`
|
||
- `engine/src/Resources/GaussianSplat/GaussianSplatArtifactIO.cpp`
|
||
- `engine/src/Resources/GaussianSplat/GaussianSplatLoader.cpp`
|
||
- 已确认问题:
|
||
- `Resources/Model` 细页已经存在，但目录级 `Model.md` 缺失，导致 `../Model.md` 反向链接和目录索引一起失效。
|
||
- 新增的 `Resources/GaussianSplat/**` public headers 已经进入源码树与 `Resources.md` 导航，但 canonical API 树还没有对应目录和头文件页。
|
||
- 这些缺口属于新 dplan 落地后的新增资源子模块入口缺页，不再是旧 Rendering 目录错位问题。
|
||
- 完成记录:
|
||
- 已补建 `Resources/Model/Model.md`，把 `Model` 目录收口为正式 submodule 入口，消除了 `AssimpModelImporter`、`Model`、`ModelArtifactIO`、`ModelLoader` 细页对 `../Model.md` 的失效链接。
|
||
- 已补建 `Resources/GaussianSplat/**`，覆盖 `GaussianSplat` submodule、`GaussianSplat` 运行时资源、`GaussianSplatArtifactIO` 与 `GaussianSplatLoader` 三个 public headers。
|
||
- 已同步 `Resources.md`，把 `GaussianSplat` 纳入 `Resources` 模块子目录导航。
|
||
- 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 384`、`Editor source headers: 144`、`Valid header refs (canonical): 384`、`Valid source refs (Editor canonical): 144`、`Invalid header refs: 0`、`Invalid source refs: 0`、`Broken .md links: 0`、`Missing directory index pages: 0`。
|
||
|
||
## 当前结论
|
||
|
||
- 第三轮复核当前已确认 `28` 组失配；`T01` 到 `T28` 已完成，其中 `T27` 收口了 Rendering 目录归位后的总览口径和审计路径，`T28` 补齐了 `Resources/Model` 与 `Resources/GaussianSplat` 的 canonical 入口。
|
||
- 当前 `engine/include/XCEngine/**`、`new_editor/include/XCEditor/**` 与 `editor/src/**` 三条 canonical 审计主线都已经回到全绿：`Valid header refs (canonical) = 384`、`Valid source refs (Editor canonical) = 144`、`Broken .md links = 0`、`Missing directory index pages = 0`。
|
||
- 本轮新增纳入审计口径的 `XCEditor`、`Resources/Model` 与 `Resources/GaussianSplat` 已经进入 canonical API 树，不再是遗留缺口；Rendering 目录错位、overview 口径漂移和 stale-token 路径也已同步收口。
|
||
- 后续如果 `docs/plan/` 再出现新的 API 相关计划，或工作树新增/改动 public header、Editor source header，应继续在此任务池追加新任务块，并在收口前重新运行 `python -B docs/api/_tools/audit_api_docs.py`。
|