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

34 KiB
Raw Blame History

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 作为持续性复核入口，用来承接后续源码变更带来的新文档漂移。
Reference in New Issue View Git Blame Copy Permalink