xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dd467d2468ad4fa7df8d9eec447fcec7fbddecdc
XCEngine/docs/used/API文档实时同步任务池_2026-04-03.md

62 KiB
Raw Blame History

API文档实时同步任务池（2026-04-03，第三轮）

文档定位

这份任务池接替已归档的第二轮计划：

  • docs/plan/used/API文档实时同步任务池_2026-04-03_第二轮归档.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。
Reference in New Issue View Git Blame Copy Permalink