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

11 KiB
Raw Blame History

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

文档定位

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

  • docs/plan/used/API文档实时同步任务池_2026-04-03_第一轮归档.md

第一轮已经解决的重点是：

  • canonical 目录结构收口
  • 历史缺页补齐
  • 第一轮大规模内容重写

本轮重点不再是“补结构”，而是：

  • 重新对照当前工作树源码与测试
  • 清理最近重构后重新出现的内容级失配
  • 继续维护一份适合多人并行认领的增量同步清单

当前复核快照

  • 最近一次结构审计时间：2026-04-03 15:07:08
  • 审计命令：python -B docs/api/_tools/audit_api_docs.py
  • 当前结果：
    • Public headers: 244
    • Editor source headers: 124
    • 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 页面
    • 不做与当前源码无关的泛化扩写

T05 增量变更监控 / 新一轮差异发现

  • 状态: OPEN
  • 认领人: ``
  • 优先级: P2
  • 写入范围:
    • 只读检查 engine/include/**、engine/src/**、editor/src/**、tests/**
    • 必要时只向本任务池追加新任务块
  • 任务目标:
    • 继续结合工作树最新改动，找出新的“源码已变但文档还没跟上”的内容级失配
    • 优先检查：
      • 最近改动过的 public headers
      • 最近改动过的 Editor source headers
      • 最近新增或更新过的测试
  • 产出要求:
    • 只记录已确认的问题
    • 每条新任务都要写明：
      • 受影响文档
      • 主要源码依据
      • 真实失配点
      • 建议写入范围

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/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 页面
  • 已同步 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 实例 与“不会返回空指针”旧表述增加定向审计

当前结论

  • 本轮已经关掉五组明确的内容级失配：
    • Viewport 渲染计划与宿主流程
    • Core/Asset 缓存接口与导入服务语义
    • MonoScriptRuntime 托管销毁入口
    • Rendering 相机请求、Passes 与单相机执行链旧口径
    • EditorConsoleSink 生命周期与空指针返回语义
  • 当前结构审计为全绿。
  • 当前仍建议保留 T04 与 T05 作为持续性并行入口，用来承接你后续重构带来的新文档漂移。
Reference in New Issue View Git Blame Copy Permalink