# API 文档实时同步任务池（2026-04-03，第二轮） ## 文档定位 这份任务池现已归档，接替的是第一轮归档： - `docs/used/API文档实时同步任务池_2026-04-03_第一轮归档.md` 第一轮已经解决的重点是： - canonical 目录结构收口 - 历史缺页补齐 - 第一轮大规模内容重写 本轮重点不再是“补结构”，而是： - 重新对照当前工作树源码与测试 - 清理最近重构后重新出现的内容级失配 - 继续维护一份适合多人并行认领的增量同步清单 ## 当前复核快照 - 最近一次结构审计时间：`2026-04-03 16:21:55` - 审计命令：`python -B docs/api/_tools/audit_api_docs.py` - 当前结果： - `Public headers: 244` - `Editor source headers: 126` - `Invalid header refs: 0` - `Invalid source refs: 0` - `Broken .md links: 0` - `Stale canonical doc tokens: 0` - `Stale editor doc tokens: 0` - `Stale editor canonical pages: 0` 这说明当前结构层面已经恢复全绿；本轮已确认的内容级失配也已收口，后续以持续巡检为主。 ## 认领规则 - 一次只认领 `1` 个任务块。 - 先把 `状态` 改成 `DOING`，再写 `认领人`。 - 只能改自己任务块的 `写入范围`。 - 所有改动都必须以“当前源码 + 当前测试 + 当前真实调用链”为依据，不允许按旧文档续写旧行为。 - 如果清理了过期 API 页面，必须同时清理交叉链接。 ## 任务池 ## T01 Editor / Viewport 渲染计划与宿主流程内容同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P0` - 写入范围: - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**` - `docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/**` - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**` - 必要时 `docs/api/XCEngine/Editor/Viewport/IViewportHostService/**` - 主要源码依据: - `editor/src/Viewport/SceneViewportRenderPlan.h` - `editor/src/Viewport/ViewportHostRenderFlowUtils.h` - `editor/src/Viewport/ViewportHostService.h` - `tests/editor/test_viewport_render_flow_utils.cpp` - 已关闭问题: - 旧文档仍把 Scene View 当前主路径写成 builtin post-process 主导 - 没写清 grid / selection outline 现在已转为显式 `postScenePasses` - 没写清 overlay pass 是 `editorOverlayFrameData + transientOverlayFrameData` 合并后再创建 - 没写清 `Scene object id shader view is unavailable` 是局部降级警告，不是整帧失败 - 完成记录: - 已重写 `SceneViewportRenderPlan.md`、`BuildSceneViewportRenderPlan.md`、`ApplySceneViewportRenderPlan.md` - 已同步 `ViewportHostRenderFlowUtils.md`、`ViewportHostService.md`、`RenderRequestedViewports.md` - 已清理 `IViewportHostService` 中残留的旧表述 ## T02 Core / Asset 缓存接口改名与语义重构同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P0` - 写入范围: - `docs/api/XCEngine/Core/Asset/ResourceManager/**` - `docs/api/XCEngine/Core/Asset/AssetImportService/**` - `docs/api/XCEngine/Core/Asset/ProjectAssetIndex/**` - 必要时 `docs/api/XCEngine/Core/Asset/Asset.md` - 必要时 `docs/api/XCEngine/Core/Asset/ArtifactFormats/**` - 主要源码依据: - `engine/include/XCEngine/Core/Asset/ResourceManager.h` - `engine/src/Core/Asset/ResourceManager.cpp` - `engine/include/XCEngine/Core/Asset/AssetImportService.h` - `engine/src/Core/Asset/AssetImportService.cpp` - `engine/include/XCEngine/Core/Asset/ProjectAssetIndex.h` - `engine/src/Core/Asset/ProjectAssetIndex.cpp` - `tests/core/Asset/test_resource_manager.cpp` - 已关闭问题: - `RefreshAssetDatabase` 已经不存在，但旧文档仍在沿用 - `RefreshProjectAssets` / `RebuildProjectAssetCache` / `GetProjectLibraryRoot` 缺页或未写清 - `AssetImportService::EnsureArtifact()` 旧文档仍把输出写成 `ResolvedAsset` - `BuildLookupSnapshot()` 旧文档仍按“双 map 出参”描述，而不是 `LookupSnapshot` - `ImportedAsset::runtimeLoadPath` 语义未同步到上层文档 - 完成记录: - 已删除过期页 `ResourceManager/RefreshAssetDatabase.md` - 已补齐 `RefreshProjectAssets.md`、`RebuildProjectAssetCache.md`、`GetProjectLibraryRoot.md` - 已补齐 `LookupSnapshot.md`、`ImportedAsset.md`、`GetLibraryRoot.md`、`RebuildLibraryCache.md` - 已同步 `Asset.md`、`ArtifactFormats.md`、`ResourceManager/Load.md` 的 `runtimeLoadPath` 口径 ## T03 Scripting / Mono 托管销毁入口同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/**` - 主要源码依据: - `engine/include/XCEngine/Scripting/Mono/MonoScriptRuntime.h` - `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` - `tests/scripting/test_mono_script_runtime.cpp` - 已关闭问题: - `DestroyManagedObject(MonoObject*)` 已进入头文件与测试，但文档树没有对应页面 - `MonoScriptRuntime.md` 没写清 `Object.Destroy(...)` 会回落到原生对象 / 组件销毁 - 完成记录: - 已新增 `DestroyManagedObject.md` - 已更新 `MonoScriptRuntime.md` 的 internal call 说明与方法总表 ## T04 Cross-Module / 教程层与模块总览口径持续复核 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P2` - 写入范围: - `docs/api/_guides/**` - `docs/api/XCEngine/*/*.md` - 仅限与本轮已确认 API 变更直接相关的总览页 - 任务目标: - 继续检查教程页、模块总览页是否仍在传播旧心智模型 - 尤其关注： - Scene View 仍被写成 builtin post-process 主导 - 资源导入链仍被写成 `artifactMainPath` / `RefreshAssetDatabase` 时代的口径 - 托管对象销毁路径未在教程层被解释 - 产出要求: - 只修正已确认失配的 guide / overview 页面 - 不做与当前源码无关的泛化扩写 - 完成记录: - 已完成一轮 guide / overview 复核 - 已确认 `GameObject / Scene` 教程层仍在传播“tag 只是 name 别名”的旧心智 - 已把后续需要实改的页面收口到 `T08` ## T05 增量变更监控 / 新一轮差异发现 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P2` - 写入范围: - 只读检查 `engine/include/**`、`engine/src/**`、`editor/src/**`、`tests/**` - 必要时只向本任务池追加新任务块 - 任务目标: - 继续结合工作树最新改动，找出新的“源码已变但文档还没跟上”的内容级失配 - 优先检查： - 最近改动过的 public headers - 最近改动过的 Editor source headers - 最近新增或更新过的测试 - 产出要求: - 只记录已确认的问题 - 每条新任务都要写明： - 受影响文档 - 主要源码依据 - 真实失配点 - 建议写入范围 - 完成记录: - 已重新扫描当前工作树改动过的 public header、Editor source header、实现文件和测试 - 已确认并追加 `T08` 与 `T09` 两组新的内容级失配 ## T06 Rendering / Camera request、Passes 与执行链旧口径清理 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Rendering/CameraRenderRequest/**` - `docs/api/XCEngine/Rendering/CameraRenderer/**` - `docs/api/XCEngine/Rendering/Passes/**` - `docs/api/XCEngine/Rendering/ObjectIdPass/**` - `docs/api/XCEngine/Rendering/RenderPipeline/**` - `docs/api/XCEngine/Rendering/SceneRenderer/**` - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**` - `docs/api/XCEngine/Editor/Viewport/Passes/**` - 必要时 `docs/api/XCEngine/Editor/Viewport/Viewport.md` - 必要时 `docs/api/XCEngine/XCEngine.md` - 必要时 `docs/api/_tools/audit_api_docs.py` - 主要源码依据: - `engine/include/XCEngine/Rendering/CameraRenderRequest.h` - `engine/include/XCEngine/Rendering/CameraRenderer.h` - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdPass.h` - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h` - `engine/include/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h` - `engine/include/XCEngine/Rendering/ObjectIdPass.h` - `engine/include/XCEngine/Rendering/RenderPipeline.h` - `engine/include/XCEngine/Rendering/SceneRenderer.h` - `engine/src/Rendering/CameraRenderer.cpp` - `engine/src/Rendering/SceneRenderer.cpp` - `tests/Rendering/unit/test_camera_scene_renderer.cpp` - `editor/src/Viewport/SceneViewportRenderPlan.h` - `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` - `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` - `editor/src/Viewport/ViewportHostRenderFlowUtils.h` - `tests/Editor/test_viewport_render_flow_utils.cpp` - `tests/Editor/test_scene_viewport_overlay_renderer.cpp` - 已关闭问题: - `CameraRenderRequest.md` 仍描述已删除的 `builtinPostProcess` 子请求 - 页面仍链接到不存在的 `BuiltinPostProcessRequest/BuiltinPostProcessRequest.md` - Scene View 已改为通过 `postScenePasses` / `overlayPasses` 写回 request，但该页口径未同步 - `CameraRenderer.md` 仍保留已删除的 `m_builtinPostProcessBuilder` 历史口径 - `Passes.md` 的典型链路只写了 `postScenePasses`，遗漏当前 `overlayPasses` 组装路径 - `Rendering/Passes` 下仍残留已删除的 `BuiltinPostProcessPassPlan` / `BuiltinPostProcessPassSequenceBuilder` 页面 - `BuiltinObjectIdPass`、`BuiltinInfiniteGridPass` 多个公开入口缺页 - `ObjectIdPass.md`、`RenderPipeline.md`、`SceneRenderer.md` 与顶层 `XCEngine.md` 仍在传播 builtin-post-process 心智模型 - 完成记录: - 已重写 `CameraRenderRequest.md` - 已清理 `2` 个失效 `.md` 链接 - 已同步 `CameraRenderer.md` 与 `Passes.md` 的当前执行链路表述 - 已删除 `BuiltinPostProcessPassPlan.md`、`BuiltinPostProcessPassSequenceBuilder.md` - 已补齐 `BuiltinObjectIdPass` / `BuiltinInfiniteGridPass` 缺失页面，并补充 `SceneViewportRenderPlan` 下 grid / selection outline pass factory 页面 - 已新增 `SceneViewportGridPass` / `SceneViewportSelectionOutlinePass` 页面，并同步 `Editor/Viewport/Passes/Passes.md` 与 `Viewport.md` 的当前口径 - 已同步 `ObjectIdPass.md`、`RenderPipeline.md`、`SceneRenderer.md` 与 `XCEngine.md` 的当前口径 - 已补充 Rendering guide、`CameraRenderer::Render` 与 `ViewportHostService::RenderRequestedViewports` 的 request 级 pass 注入说明 - 已为 `builtinPostProcess` / `BuiltinPostProcessRequest` / `m_builtinPostProcessBuilder` 增加 canonical 过期符号审计 - 已复跑结构审计并确认 `Broken .md links: 0` ## T07 Editor / Core `EditorConsoleSink` 生命周期说明同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Editor/Core/EditorConsoleSink/**` - 必要时 `docs/api/XCEngine/Editor/Managers/Managers.md` - 必要时 `docs/api/_tools/audit_api_docs.py` - 主要源码依据: - `editor/src/Core/EditorConsoleSink.h` - `editor/src/Core/EditorConsoleSink.cpp` - `editor/src/panels/ConsolePanel.cpp` - `editor/src/Core/EditorLoggingSetup.h` - `tests/Editor/test_editor_console_sink.cpp` - 已关闭问题: - `EditorConsoleSink::GetInstance()` 旧文档仍把它写成会返回 fallback 实例 - 相关 overview 页面没有写清活动 sink 销毁后会返回 `nullptr` - 审计脚本此前无法自动拦截这类旧生命周期表述 - 完成记录: - 已同步 `EditorConsoleSink.md`、`GetInstance.md`、`Destructor.md` - 已同步 `Managers.md` 中对控制台 sink 生命周期的引用口径 - 已为 `fallback 实例` 与“不会返回空指针”旧表述增加定向审计 ## T08 Components / Scene / Scripting `GameObject` tag-layer 语义同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P0` - 写入范围: - `docs/api/XCEngine/Components/GameObject/**` - `docs/api/XCEngine/Scene/Scene/**` - `docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/**` - 必要时 `docs/api/_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md` - 必要时 `docs/api/_guides/Scene/Scene-Lifecycle-And-Serialization.md` - 主要源码依据: - `engine/include/XCEngine/Components/GameObject.h` - `engine/src/Components/GameObject.cpp` - `engine/src/Scene/Scene.cpp` - `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` - `managed/XCEngine.ScriptCore/GameObject.cs` - `managed/XCEngine.ScriptCore/Component.cs` - `managed/XCEngine.ScriptCore/InternalCalls.cs` - `tests/Components/test_game_object.cpp` - `tests/Scene/test_scene.cpp` - `tests/scripting/test_mono_script_runtime.cpp` - 已确认问题: - `GameObject.md` 仍写“没有真正的 tag 系统”，并把 `FindGameObjectsWithTag()` 描述成按名字匹配；这与当前 `m_tag` / `CompareTag()` / `SetTag()` 实现已不符 - `Scene.md` 与 `FindGameObjectWithTag.md` 仍在传播“按名字查 tag”的旧口径 - `GameObject` 目录缺少 `GetTag.md`、`SetTag.md`、`CompareTag.md`、`GetLayer.md`、`SetLayer.md` - `Serialize.md` / `Deserialize.md` 尚未同步 `tag=` 字段、默认 `Untagged` 以及 layer clamp 语义 - `MonoScriptRuntime` 总览页尚未解释 Unity 风格 `GameObject.tag` / `layer` / `CompareTag()` 已通过 internal call 暴露到托管侧 - 产出要求: - 类型页与方法页都要明确区分当前原生实现、场景查询语义和托管暴露语义 - 教程页要从“tag 只是名字别名”改成“当前已有独立 tag 字段，但仍是轻量 Unity 风格模型” - 需要写清：空 tag 会回落到 `Untagged`，layer 会 clamp 到 `[0, 31]` - 完成记录: - 已重写 `GameObject.md`、`Scene.md`、`FindGameObjectWithTag.md` - 已补齐 `GetTag.md`、`SetTag.md`、`CompareTag.md`、`GetLayer.md`、`SetLayer.md` - 已同步 `Serialize.md` / `Deserialize.md` 的 `tag=`、`layer=`、`Untagged` 与 clamp 语义 - 已同步 `MonoScriptRuntime.md` 对托管 `GameObject.tag` / `layer` / `CompareTag()` 的 internal call 桥接说明 - 已同步 `GameObject-Component-Lifecycle-And-Serialization.md` 与 `Scene-Lifecycle-And-Serialization.md` 的心智模型口径 - 已补充 `Constructor`、`AddComponent`、`SetActive`、`SetParent`、`IsActive`、`IsActiveInHierarchy`、`Find`、`FindObjectsOfType`、`Awake`、`Start`、`Update`、`FixedUpdate`、`LateUpdate`、`OnDestroy`、`Destroy` 的真实生命周期与查询语义 ## T09 Resources / Material 与材质 Artifact v2 语义同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P0` - 写入范围: - `docs/api/XCEngine/Resources/Material/**` - `docs/api/XCEngine/Core/Asset/ArtifactFormats/**` - `docs/api/XCEngine/Core/Asset/AssetDatabase/**` - 必要时 `docs/api/XCEngine/Core/Asset/Asset.md` - 主要源码依据: - `engine/include/XCEngine/Resources/Material/Material.h` - `engine/src/Resources/Material/Material.cpp` - `engine/src/Resources/Material/MaterialLoader.cpp` - `engine/include/XCEngine/Core/Asset/ArtifactFormats.h` - `engine/src/Core/Asset/AssetDatabase.cpp` - `tests/Resources/Material/test_material.cpp` - `tests/Resources/Material/test_material_loader.cpp` - 已确认问题: - `Resources/Material/Material.md` 仍是旧模板式总览，没有覆盖当前公开语义 - `Material` 目录缺少 `SetTextureAssetRef.md`、`GetTextureBindingAssetRef.md`、`GetTextureBindingLoadedTexture.md` - `ArtifactFormats.md` 仍写 `kMaterialArtifactSchemaVersion = 1`、magic `XCMAT01`，与当前 schema v2 / `XCMAT02` 不符 - 材质 artifact 文档还没写清每个 texture binding 现在会序列化“编码后的 `AssetRef` + 可选 artifact/path 字符串” - `Material` 文档尚未解释纹理绑定现在既有 loaded handle，也有稳定 `AssetRef` 元数据，并且 `GetTexture()` 可在首次访问时通过 `TryResolveAssetPath()` 兑现延迟资源 - 产出要求: - 重写 `Material.md`，把 shader 属性、texture binding 元数据、lazy resolve、路径与 `AssetRef` 的边界写清 - 为新增公开方法补页，并把现有 `SetTexture` / `GetTexture` / `GetTextureBindingCount` 等页面更新到当前实现 - 更新 `ArtifactFormats.md` 与 `AssetDatabase` 相关页面，写清材质 artifact v2 的字段顺序、兼容边界和设计动机 - 完成记录: - 已重写 `docs/api/XCEngine/Resources/Material/Material.md` 与 `docs/api/XCEngine/Resources/Material/Material/Material.md` - 已新增 `SetTextureAssetRef.md`、`SetTexturePath.md`、`GetTextureBindingName.md`、`GetTextureBindingAssetRef.md`、`GetTextureBindingPath.md`、`GetTextureBindingLoadedTexture.md`、`GetTextureBindingTexture.md` - 已同步 `SetTexture.md`、`GetTexture.md`、`GetTextureBindingCount.md` 的当前 lazy-load 与 binding metadata 语义 - 已更新 `ArtifactFormats.md`，把材质 artifact 修正到 schema v2 / `XCMAT02`，并写清 texture binding 三元组布局 - 已更新 `AssetDatabase.md` 的当前 importerVersion 常量，并在 `Asset.md` 补充 `.xcmat` v2 的跨模块说明 - 已为旧 `kMaterialArtifactSchemaVersion = 1` / `XCMAT01` 文案增加审计回归保护 - 已复跑结构审计并确认 `Broken .md links: 0` ## T10 Editor / Viewport `SceneViewportShaderPaths` canonical 补页 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/**` - 必要时 `docs/api/XCEngine/Editor/Viewport/Viewport.md` - 主要源码依据: - `editor/src/Viewport/SceneViewportShaderPaths.h` - `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` - `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` - 已关闭问题: - `editor/src/Viewport/SceneViewportShaderPaths.h` 新进入工作树后还没有 canonical 页面 - 结构审计一度出现 `Editor source headers: 125` 但 `Valid source refs (Editor canonical): 124` - 完成记录: - 已新增 `SceneViewportShaderPaths.md` 与 5 个 helper/function 页面 - 已同步 `Viewport.md` 的目录结构总览 - 已复跑结构审计并确认 `Valid source refs (Editor canonical): 125` ## T11 Platform / 概述页与方法页模板化表述清理 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Platform/**` - 主要源码依据: - `engine/include/XCEngine/Platform/GameTime.h` - `engine/include/XCEngine/Platform/PlatformTypes.h` - `engine/include/XCEngine/Platform/IClock.h` - `engine/include/XCEngine/Platform/IWindow.h` - `engine/include/XCEngine/Platform/IFileSystem.h` - `engine/include/XCEngine/Platform/IPlatform.h` - `engine/include/XCEngine/Platform/IDynamicLibrary.h` - `engine/include/XCEngine/Platform/IDisplayEnumerator.h` - `engine/include/XCEngine/Platform/Window.h` - `engine/include/XCEngine/Platform/Windows/WindowsWindow.h` - `engine/include/XCEngine/Platform/Windows/WindowsInputModule.h` - `engine/src/Platform/Window.cpp` - `engine/src/Platform/Windows/WindowsWindow.cpp` - `engine/src/Platform/Windows/WindowsInputModule.cpp` - 已关闭问题: - `Platform` 下多组概述页仍把自己写成“canonical 总览”，没有说明符号本身的职责和边界 - 大量方法页仍残留“获取相关状态或对象”“公开方法，详见头文件声明”“参数语义详见头文件声明”等模板废话 - `WindowsInputModule::PumpEvents()` 当前是空实现，但旧页没有说明，容易误导成真实消息泵入口 - `WindowsWindow` 的 Win32 当前实现路径没有写清，例如 `Create()`、`Destroy()`、`PumpEvents()`、`SetFullscreen()` 与 `ShouldClose()` - 完成记录: - 已重写 `GameTime`、`PlatformTypes`、`IClock`、`IWindow`、`IFileSystem`、`IPlatform`、`IDynamicLibrary`、`IDisplayEnumerator`、`Window`、`WindowsWindow`、`WindowsInputModule` 相关 overview 与方法页 - 已把 `Platform` 下残留模板短语、参数占位语和 canonical 占位说明清理到 `0` - 已写清 `Window` / `WindowsWindow` / `WindowsInputModule` 的当前实现语义与输入桥接关系 - 已复跑结构审计并确认 `Old template pages: 0`、`Broken .md links: 0` ## T12 Cross-Module / canonical 式概述废话清理 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/RHI/D3D12/**` - `docs/api/XCEngine/Resources/**` - 主要源码依据: - `engine/include/XCEngine/RHI/D3D12/D3D12Types.h` - `engine/include/XCEngine/RHI/D3D12/D3D12Common.h` - `engine/include/XCEngine/RHI/D3D12/D3D12Enums.h` - `engine/include/XCEngine/RHI/D3D12/D3D12RootSignature.h` - `engine/include/XCEngine/RHI/D3D12/D3D12PipelineState.h` - `engine/include/XCEngine/Resources/Resources.h` - `engine/include/XCEngine/Resources/Texture/Texture.h` - `engine/include/XCEngine/Resources/Texture/TextureLoader.h` - `engine/include/XCEngine/Resources/Texture/TextureImportSettings.h` - `engine/include/XCEngine/Resources/Mesh/Mesh.h` - `engine/include/XCEngine/Resources/Mesh/MeshLoader.h` - `engine/include/XCEngine/Resources/Mesh/MeshImportSettings.h` - `engine/include/XCEngine/Resources/Shader/Shader.h` - `engine/include/XCEngine/Resources/Shader/ShaderLoader.h` - `engine/include/XCEngine/Resources/AudioClip/AudioClip.h` - `engine/include/XCEngine/Resources/AudioClip/AudioLoader.h` - 已关闭问题: - `RHI/D3D12` 与 `Resources` 下仍有一批 overview 页把“概述”写成“当前页面作为平行目录中的 canonical 总览”，没有解释符号本身做什么 - `Texture`、`Mesh`、`Shader`、`AudioClip` 等资源类型页没有把类型边界、持有的数据和辅助声明写清 - `D3D12Types`、`D3D12Common`、`D3D12Enums` 这类 helper header 页没有说明它们是转换 / 构造 / 检查函数集合 - 完成记录: - 已重写 `RHI/D3D12` 与 `Resources` 下全部 `16` 个 canonical 式 overview 页 - 已把全仓库 `docs/api/XCEngine/**` 中“当前页面作为平行目录中的 canonical 总览”这类概述废话清理到 `0` - 已复跑结构审计并确认 `Broken .md links: 0`、`Old template pages: 0` ## T13 Components / `GameObject` 剩余辅助页内容化补齐 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P2` - 写入范围: - `docs/api/XCEngine/Components/GameObject/DetachChildren.md` - `docs/api/XCEngine/Components/GameObject/DetachFromParent.md` - `docs/api/XCEngine/Components/GameObject/Destructor.md` - `docs/api/XCEngine/Components/GameObject/GetChild.md` - `docs/api/XCEngine/Components/GameObject/GetChildCount.md` - `docs/api/XCEngine/Components/GameObject/GetChildren.md` - `docs/api/XCEngine/Components/GameObject/GetComponent.md` - `docs/api/XCEngine/Components/GameObject/GetComponentInChildren.md` - `docs/api/XCEngine/Components/GameObject/GetComponentInParent.md` - `docs/api/XCEngine/Components/GameObject/GetComponents.md` - `docs/api/XCEngine/Components/GameObject/GetComponentsInChildren.md` - `docs/api/XCEngine/Components/GameObject/GetID.md` - `docs/api/XCEngine/Components/GameObject/GetName.md` - `docs/api/XCEngine/Components/GameObject/GetParent.md` - `docs/api/XCEngine/Components/GameObject/GetScene.md` - `docs/api/XCEngine/Components/GameObject/GetTransform.md` - `docs/api/XCEngine/Components/GameObject/GetUUID.md` - `docs/api/XCEngine/Components/GameObject/RemoveComponent.md` - `docs/api/XCEngine/Components/GameObject/SetName.md` - 主要源码依据: - `engine/include/XCEngine/Components/GameObject.h` - `engine/src/Components/GameObject.cpp` - `tests/Components/test_game_object.cpp` - `tests/Scene/test_scene.cpp` - `tests/scripting/test_mono_script_runtime.cpp` - 已关闭问题: - `GameObject` 模块的核心生命周期、tag/layer 与场景边界已经完成，但上述辅助页仍残留模板式表述 - 这些页面尚未写清模板接口的真实语义，例如 `Transform` 特例、层级递归查询、观察指针返回与移除边界 - 产出要求: - 把这些方法页全部改成基于当前源码的行为说明 - 优先写清组件查询模板、层级辅助接口和对象身份访问器的真实边界 - 不重复改动本轮已经完成内容化的生命周期和 tag/layer 页面 - 完成记录: - 已重写 `DetachChildren.md`、`DetachFromParent.md`、`Destructor.md`、`GetChild.md`、`GetChildCount.md`、`GetChildren.md` - 已重写 `GetComponent.md`、`GetComponentInChildren.md`、`GetComponentInParent.md`、`GetComponents.md`、`GetComponentsInChildren.md`、`RemoveComponent.md` - 已重写 `GetID.md`、`GetName.md`、`GetParent.md`、`GetScene.md`、`GetTransform.md`、`GetUUID.md`、`SetName.md` - 已写清 `Transform` 特例、层级查询顺序、`Scene` / registry 观察指针语义，以及 `RemoveComponent` 当前不会补发 `OnDestroy()` ## T14 Rendering / `RenderMaterialUtility` schema-driven 材质常量 payload 语义同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Rendering/RenderMaterialUtility/**` - `docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/**` - 必要时 `docs/api/_tools/audit_api_docs.py` - 主要源码依据: - `engine/include/XCEngine/Rendering/RenderMaterialUtility.h` - `engine/include/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h` - `engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp` - `engine/include/XCEngine/Resources/Material/Material.h` - `tests/Rendering/unit/test_render_scene_extractor.cpp` - 已关闭问题: - `RenderMaterialUtility` 总览页尚未覆盖新进入 public header 的 `MaterialConstantPayloadView` 与 `ResolveSchemaMaterialConstantPayload(...)` - `BuiltinForwardPipeline.md` 仍把逐材质常量写成“目前只写入 `baseColorFactor`”，没有同步当前优先消费 schema-driven payload、仅在缺失时回退 fallback 的实现 - `BuildBuiltinForwardMaterialData.md` 还没把自己定位成兼容 fallback helper，容易与当前主路径混淆 - 完成记录: - 已新增 `BuiltinForwardMaterialData.md`、`MaterialConstantPayloadView.md`、`ResolveSchemaMaterialConstantPayload.md` - 已重写 `RenderMaterialUtility.md` 与 `BuildBuiltinForwardMaterialData.md`，写清 schema payload 与 builtin forward fallback 的边界 - 已同步 `BuiltinForwardPipeline.md` 与 `Render.md`，补入 `Material::GetConstantBufferData()` 主路径和 `FallbackPerMaterialConstants` 回退逻辑 - 已为“逐材质常量目前只写入 `baseColorFactor`”等旧口径增加 canonical 审计回归保护 - 已复跑结构审计并确认 `Stale canonical doc tokens: 0` ## T15 Editor / Scripting 脚本程序集重建与运行时锁语义同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/**` - `docs/api/XCEngine/Editor/Application/RebuildScriptingAssemblies.md` - 必要时 `docs/api/XCEngine/Editor/Application/Application.md` - 主要源码依据: - `editor/src/Scripting/EditorScriptAssemblyBuilder.cpp` - `editor/src/Application.cpp` - `tests/Editor/test_editor_script_assembly_builder.cpp` - 已关闭问题: - `EditorScriptAssemblyBuilder` 文档仍把 `mscorlib.dll` 写成“每次重建都复制”，没有同步当前“首次复制、后续复用项目本地 corlib”的实现 - `RebuildProjectAssemblies.md` 没写清活动 Mono runtime 仍持有 `GameScripts.dll` 时可能出现文件锁失败 - `Application::RebuildScriptingAssemblies` 文档仍写“构建失败会保留旧 runtime”，与当前先 `ShutdownScriptingRuntime()` 再构建的实现不符 - 完成记录: - 已同步 `EditorScriptAssemblyBuilder.md` 与 `RebuildProjectAssemblies.md`，补入项目本地 `mscorlib.dll` 复用策略、Mono 文件锁失败路径与测试锚点 - 已同步 `Application::RebuildScriptingAssemblies` 与 `Application.md`，写清“先卸载当前 runtime 释放程序集锁，再重建并在成功后重载”的真实顺序 - 已复跑结构审计并确认 `Broken .md links: 0`、`Stale canonical doc tokens: 0` ## T16 Resources / Rendering Passes SceneView shader ownership 口径同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Resources/BuiltinResources/**` - `docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/**` - `docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/**` - 主要源码依据: - `engine/include/XCEngine/Resources/BuiltinResources.h` - `engine/src/Resources/BuiltinResources.cpp` - `engine/include/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h` - `engine/src/Rendering/Passes/BuiltinInfiniteGridPass.cpp` - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h` - `engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp` - `editor/src/Viewport/SceneViewportShaderPaths.h` - 已关闭问题: - `BuiltinResources.md` 仍把 `object-id-outline` / `infinite-grid` 写成 engine `builtin://shaders/*` helper 与 builtin shader 工厂的一部分，但当前头文件与实现已只保留 `forward-lit`、`object-id` - `BuiltinInfiniteGridPass` 与 `BuiltinObjectIdOutlinePass` 已改为由调用方注入 `shaderPath`，文档却仍在传播“固定 builtin shader”口径 - 两个 pass 的文档树缺少 `SetShaderPath.md`、`GetShaderPath.md`；`BuiltinInfiniteGridPass` 还缺少 `Constructor.md` 与 `Destructor.md` - 完成记录: - 已更新 `BuiltinResources.md`，把 builtin shader 集合收口到 `forward-lit` / `object-id`，并写清 Scene View grid / outline shader 现在由 editor 侧 `SceneViewportShaderPaths` 提供 - 已重写 `BuiltinInfiniteGridPass.md`、`Render.md`、`Shutdown.md`，补上 `Constructor.md`、`Destructor.md`、`SetShaderPath.md`、`GetShaderPath.md` - 已重写 `BuiltinObjectIdOutlinePass.md`、`Constructor.md`、`Render.md`、`Shutdown.md`，补上 `SetShaderPath.md` 与 `GetShaderPath.md` ## T17 Editor / Viewport `SceneViewportOverlayProviders` canonical 补页 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/**` - 主要源码依据: - `editor/src/Viewport/SceneViewportOverlayProviders.h` - `editor/src/Viewport/SceneViewportOverlayProviders.cpp` - `editor/src/Viewport/SceneViewportOverlayBuilder.h` - `tests/editor/test_scene_viewport_overlay_providers.cpp` - 已关闭问题: - `editor/src/Viewport/SceneViewportOverlayProviders.h` 新进入工作树后还没有 canonical 页面 - 结构审计出现 `Editor source headers: 126` 但 `Valid source refs (Editor canonical): 125` - 缺少对 overlay build context、provider registry 和默认相机 / 灯光 provider 工厂的当前语义说明 - 完成记录: - 已新增 `SceneViewportOverlayProviders.md`、`SceneViewportOverlayBuildContext.md`、`ISceneViewportOverlayProvider.md`、`SceneViewportOverlayProviderRegistry.md` - 已新增 `CreateSceneViewportCameraOverlayProvider.md`、`CreateSceneViewportLightOverlayProvider.md`、`BuildDefaultSceneViewportOverlayProviderRegistry.md` - 已复跑结构审计并确认 `Valid source refs (Editor canonical): 126`、`Broken .md links: 0` ## T18 Editor / Viewport overlay builder provider 化口径同步 - 状态: `DONE` - 认领人: `Codex` - 优先级: `P1` - 写入范围: - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/**` - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**` - `docs/api/XCEngine/Editor/Viewport/Viewport.md` - 必要时 `docs/api/_guides/Editor/**` - 主要源码依据: - `editor/src/Viewport/SceneViewportOverlayBuilder.h` - `editor/src/Viewport/SceneViewportOverlayBuilder.cpp` - `editor/src/Viewport/SceneViewportOverlayProviders.h` - `editor/src/Viewport/ViewportHostService.h` - `tests/editor/test_scene_viewport_overlay_providers.cpp` - 已关闭问题: - `SceneViewportOverlayBuilder` 文档仍把类型写成“无状态构建器 + static Build(...)”，没有同步当前实例化 builder + provider registry 的实现 - `SceneViewportOverlayBuilder` 目录缺少 `Constructor.md` 与 `GetProviderRegistry.md` - `ViewportHostService.md` 仍把基础 overlay 来源写成 `SceneViewportOverlayBuilder::Build(...)`，没有同步当前成员 `m_sceneViewportOverlayBuilder` - guide 层仍在传播 `overlay builder -> overlay pass` 与“先把 scene icon 塞进 builder”的旧扩展口径 - 完成记录: - 已重写 `SceneViewportOverlayBuilder.md` 与 `Build.md`，把默认 registry、build context 和 provider 聚合链路写清 - 已新增 `Constructor.md` 与 `GetProviderRegistry.md` - 已同步 `ViewportHostService.md`、`Viewport.md` 以及两篇 Editor guide 的当前 provider 化心智模型 - 已把新扩展建议改成 `overlay provider -> overlay builder -> overlay pass` ## 当前结论 - 本轮已经关掉十七组明确的内容级失配： - `Viewport` 渲染计划与宿主流程 - `Core/Asset` 缓存接口与导入服务语义 - `MonoScriptRuntime` 托管销毁入口 - `Rendering` 相机请求、Passes 与单相机执行链旧口径 - `EditorConsoleSink` 生命周期与空指针返回语义 - 跨模块 guide / overview 漂移的本轮复核与拆分 - `Material` / `ArtifactFormats` / `AssetDatabase` 的材质 artifact v2 与 texture `AssetRef` 语义 - `GameObject` / `Scene` / `Mono` 的 tag-layer 与托管暴露语义 - `GameObject` 剩余辅助访问器 / 层级辅助页的内容化补齐 - `SceneViewportShaderPaths` canonical 缺页 - `Platform` 模块概述页与方法页的模板化废话清理 - `RHI/D3D12` 与 `Resources` 的 canonical 式概述废话清理 - `RenderMaterialUtility` / `BuiltinForwardPipeline` 的 schema-driven 材质常量 payload 语义 - `Editor` 脚本程序集重建流程中的 corlib 复用与 runtime 文件锁语义 - `BuiltinResources` 与 Scene View grid / outline shader ownership、`shaderPath` 注入口径 - `SceneViewportOverlayProviders` canonical 缺页 - `SceneViewportOverlayBuilder` / `ViewportHostService` / guide 层的 provider 化心智模型同步 - 当前结构审计为全绿。 - 当前仍建议保留 `T04` 与 `T05` 作为持续性复核入口，用来承接后续源码变更带来的新文档漂移。