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

601 lines
34 KiB
Markdown
Raw Normal View History

docs: sync api and planning docs
2026-04-08 16:07:03 +08:00
# API 文档实时同步任务池（2026-04-03，第二轮）
## 文档定位
docs(api): sync active and archived API entry docs
2026-04-10 17:27:29 +08:00
这份任务池现已归档，接替的是第一轮归档：
docs: sync api and planning docs
2026-04-08 16:07:03 +08:00
docs(api): sync active and archived API entry docs
2026-04-10 17:27:29 +08:00
- `docs/used/API文档实时同步任务池_2026-04-03_第一轮归档.md`
docs: sync api and planning docs
2026-04-08 16:07:03 +08:00
第一轮已经解决的重点是：
- 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` 作为持续性复核入口，用来承接后续源码变更带来的新文档漂移。
Reference in New Issue Copy Permalink