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

22 KiB
Raw Blame History

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

文档定位

这份任务池现已归档，并且是当前仓库中可追溯到的首轮 API 文档归档起点。更早的 2026-04-02 初始任务池原件当前不在仓库内，因此这里不再保留失效链接。

旧任务池解决的是：

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

本轮不再以“补结构”为主，而是以“跟踪当前工作树真实实现变化，持续清理失准内容和过期 API 页面”为主。

本轮复核方法

本轮按下面三层做交叉复核：

  1. 重新执行 python docs/api/_tools/audit_api_docs.py
  2. 检查当前工作树里真实发生变化的源码与测试：
    • engine/src/Components/MeshFilterComponent.cpp
    • engine/src/Components/MeshRendererComponent.cpp
    • editor/src/Actions/EditorActions.h
    • editor/src/Actions/MainMenuActionRouter.h
    • editor/src/Commands/ProjectCommands.h
    • editor/src/Core/IProjectManager.h
    • editor/src/Managers/ProjectManager.h
    • editor/src/Managers/ProjectManager.cpp
    • tests/Components/test_mesh_render_components.cpp
    • tests/Scene/test_scene.cpp
    • tests/editor/test_action_routing.cpp
  3. 反向搜索 API 文档里对旧行为、旧菜单和旧序列化键的残留描述

当前总判断

  • 旧的内容级失准问题已经全部关闭：
    • Editor：旧的项目迁移菜单、命令、接口、manager 和报告结构残留页已在 2026-04-03 14:04:49 收口完成
    • Components：MeshFilterComponent / MeshRendererComponent 的旧键名、普通项目路径 fallback 和模块总览口径已在 2026-04-03 14:09:47 对齐到当前源码 / 测试
  • 新暴露出的 SceneViewportRenderPlan.h 缺页问题已在 2026-04-03 14:17:02 收口完成
  • 当前结构项重新回到全绿：
    • public headers 246/246
    • Editor source headers 122/122
    • 失效 .md 链接 0
    • 无效 header / source ref 0
    • Editor 显式过期符号残留 0
    • Editor 残留 canonical 旧页面 0

这说明当前审计工具已经同时具备三种能力：兜住结构一致性、自动报出已删除 API 的旧符号残留、以及发现工作树中新冒出的未补页 header；后续工作进入“继续跟踪新增 API 与计划文件新增任务块”的阶段。

认领规则

  • 一次只认领 1 个任务块，先改 状态 和 认领人
  • 只修改自己任务块的 写入范围，不要跨任务顺手扩写其它模块
  • 每个任务都要以当前工作树源码、测试和真实调用点为依据，不允许只按旧文档重写旧文档
  • 除最后的审计收口任务外，不要随意覆盖 docs/api/_meta/rebuild-status.md
  • 如果任务涉及删除过期 API 页面，必须同步清理所有交叉链接

任务池

T01 Components / Mesh 资产引用最终协议同步

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P0
  • 写入范围:
    • docs/api/XCEngine/Components/MeshFilterComponent/**
    • docs/api/XCEngine/Components/MeshRendererComponent/**
    • 必要时 docs/api/XCEngine/Components/Components.md
    • 必要时 docs/api/_guides/Components/**
  • 主要源码依据:
    • engine/src/Components/MeshFilterComponent.cpp
    • engine/src/Components/MeshRendererComponent.cpp
    • tests/Components/test_mesh_render_components.cpp
    • tests/Scene/test_scene.cpp
    • engine/include/XCEngine/Components/MeshFilterComponent.h
    • engine/include/XCEngine/Components/MeshRendererComponent.h
  • 当前确认缺口:
    • MeshFilterComponent.md 仍写“反序列化会读取 mesh=<path>”，而当前实现只识别 meshPath
    • MeshFilterComponent.md / Serialize.md 仍写“序列化输出 mesh=<path>”，而当前实现对项目资产已转向 meshRef 主路径，只在 virtual scheme 下保留 meshPath
    • MeshFilterComponent::Deserialize.md 仍写“只有路径时会补算 AssetRef 并接受普通路径”，而当前实现已忽略没有 AssetRef 的普通项目路径，只保留 virtual scheme 路径
    • MeshRendererComponent.md / Serialize.md / Deserialize.md 仍写“兼容 materials= 历史键”和“项目资产路径 fallback 仍是主恢复路径”，而当前实现已经不再读取 materials=，并且会清掉无 AssetRef 的普通 materialPaths
    • 组件模块总览当前对“路径 + AssetRef + 运行时句柄双轨”的描述仍偏旧，没有强调“项目资产主协议已经收口为 AssetRef，路径主要保留给 builtin:// / 其它 virtual scheme”
  • 完成标准:
    • 把 MeshFilterComponent / MeshRendererComponent 类型页和序列化方法页全部改到当前实现
    • 明确“项目资产只依赖 AssetRef，普通项目路径不再作为长期兼容协议”
    • 明确“只有 virtual scheme 路径会稳定保留在 meshPath / materialPaths 里”
    • 清掉所有关于 mesh=、materials= 仍被当前实现兼容的说法
  • 完成记录:
    • 已重新核对 MeshFilterComponent.h/.cpp、MeshRendererComponent.h/.cpp、tests/Components/test_mesh_render_components.cpp 与 tests/Scene/test_scene.cpp
    • MeshFilterComponent.md、Serialize.md、Deserialize.md 与 MeshRendererComponent.md、Serialize.md、Deserialize.md 已确认按当前实现描述 meshRef / materialRefs 主协议
    • 已继续修正 SetMeshPath.md、SetMaterialPath.md 与 Components.md，把“运行时路径缓存”和“正式序列化协议”明确拆开
    • 2026-04-03 14:09:47 审计后，当前仓库中这组页面不再把 mesh= / materials= 或普通项目路径 fallback 写成当前协议

T02 Editor / 移除场景资产引用迁移链路文档与过期页

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P0
  • 写入范围:
    • docs/api/XCEngine/Editor/Actions/EditorActions/**
    • docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/**
    • docs/api/XCEngine/Editor/Commands/ProjectCommands/**
    • docs/api/XCEngine/Editor/Core/IProjectManager/**
    • docs/api/XCEngine/Editor/Managers/ProjectManager/**
    • docs/api/XCEngine/Editor/panels/ProjectPanel/**
    • 必要时 docs/api/_guides/Editor/**
  • 主要源码依据:
    • editor/src/Actions/EditorActions.h
    • editor/src/Actions/MainMenuActionRouter.h
    • editor/src/Commands/ProjectCommands.h
    • editor/src/Core/IProjectManager.h
    • editor/src/Managers/ProjectManager.h
    • editor/src/Managers/ProjectManager.cpp
    • tests/editor/test_action_routing.cpp
  • 当前确认缺口:
    • EditorActions.md 仍包含 MakeMigrateSceneAssetReferencesAction
    • MainMenuActionRouter.md 仍把 File -> Migrate Scene AssetRefs 当成当前菜单项
    • ProjectCommands.md 仍写 CanMigrateSceneAssetReferences() / MigrateSceneAssetReferences()
    • IProjectManager.md 仍声明 SceneAssetReferenceMigrationReport 和 MigrateSceneAssetReferences()
    • ProjectManager.md 仍把“场景资产引用迁移”写成当前公开职责
    • ProjectPanel.md 仍把 Migrate Scene AssetRefs 记为项目级命令之一
    • 过期 canonical 页面仍存在：
      • docs/api/XCEngine/Editor/Managers/ProjectManager/MigrateSceneAssetReferences.md
  • 完成标准:
    • 把上述页面全部改成当前源码状态
    • 删除已不存在的 API 页面，并清理所有交叉引用
    • 把项目工作流文档收口到当前仍存在的入口：项目切换、保存、脚本重建、资源浏览与文件操作
  • 完成记录:
    • 已重写 EditorActions.md、MainMenuActionRouter.md、ProjectCommands.md、IProjectManager.md、ProjectManager.md、ProjectPanel.md
    • 已把 IProjectManager 进一步拆成 Current Items And Selection、Navigation And Path、Initialization And Refresh、File Operations 四页，按当前头文件分组收口
    • docs/api/XCEngine/Editor/Managers/ProjectManager/MigrateSceneAssetReferences.md 已删除；旧迁移 API 不再保留兼容入口页
    • 2026-04-03 14:04:49 已重新执行 python docs/api/_tools/audit_api_docs.py，结果为：
      • Stale editor doc tokens: 0
      • Broken .md links: 0
      • Valid source refs (Editor canonical): 121

T03 Cross-Module / 资产引用协议与编辑器工作流交叉说明收口

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围:
    • docs/api/XCEngine/Components/Components.md
    • docs/api/XCEngine/Scene/Scene.md
    • docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md
    • 必要时 docs/api/main.md
  • 主要源码依据:
    • engine/src/Components/MeshFilterComponent.cpp
    • engine/src/Components/MeshRendererComponent.cpp
    • editor/src/Actions/MainMenuActionRouter.h
    • editor/src/Commands/ProjectCommands.h
    • editor/src/Managers/ProjectManager.cpp
    • tests/Scene/test_scene.cpp
    • tests/editor/test_action_routing.cpp
  • 当前确认缺口:
    • 模块总览层还没有把“项目资产最终序列化协议已收口到 AssetRef，virtual path 只保留给 builtin/虚拟资源”讲透
    • Editor 架构层仍有旧项目维护入口的残留心智，需要删掉“场景迁移”这条已不存在的分支
    • 目前用户如果只读模块总览，仍容易得出“普通项目路径仍是第一公民协议”“主菜单还带场景迁移入口”的错误结论
  • 完成标准:
    • 模块页和 guide 页不再沿用旧心智模型
    • 用户只看总览页，也能得出当前正确结论：
      • 项目资产靠 AssetRef
      • builtin:// / 其它 virtual scheme 才保留路径
      • 主菜单已无 Migrate Scene AssetRefs
  • 完成记录:
    • 已修正 docs/api/XCEngine/Components/Components.md，明确项目资产正式协议优先 AssetRef
    • 已复核 docs/api/XCEngine/Scene/Scene.md、docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md 与 docs/api/main.md，确认不再传播旧菜单入口或“普通项目路径仍是第一公民协议”的说法
    • 当前仅阅读模块总览 / guide，也能得出“项目资产靠 AssetRef、virtual scheme 才稳定保留路径、主菜单没有旧迁移入口”的正确结论

T04 API 审计工具补强 / 过期 API 页面检测

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围:
    • docs/api/_tools/audit_api_docs.py
    • 必要时 docs/api/_meta/rebuild-status.md
    • 必要时在 docs/plan 中补充审计口径说明
  • 主要依据:
    • 本轮复核结论
    • 当前 audit 全绿但仍漏报 MigrateSceneAssetReferences 这类已删除 API 残留页
  • 当前确认缺口:
    • 现有审计能发现“缺页”和“断链”，但不能发现“源码已经删除，文档页仍然存在”
    • 也不能发现模块页仍在描述已删除菜单项或已删除 helper
  • 完成标准:
    • 至少新增一种轻量检测，能把“已删除 API 的残留 canonical 页面”或“显式过期 helper 名称残留”暴露出来
    • 让后续复核不再完全依赖人工 grep
  • 完成记录:
    • docs/api/_tools/audit_api_docs.py 已新增 Editor 显式过期符号残留检测
    • 2026-04-03 13:53:21 审计已能自动报出 49 处 MigrateSceneAssetReferences 相关残留

T05 收口审计与进度回写

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P2
  • 写入范围:
    • docs/api/_meta/rebuild-status.md
    • docs/used/API文档实时同步任务池_2026-04-03.md
  • 主要依据:
    • T01-T04 完成结果
  • 完成标准:
    • 重新执行 python docs/api/_tools/audit_api_docs.py
    • 回写新的审计时间和结果
    • 明确记录本轮哪些失准点已关闭、哪些仍待继续跟踪
  • 完成记录:
    • 已在 2026-04-03 14:20:04 重新执行 python docs/api/_tools/audit_api_docs.py
    • 已回写 docs/api/_meta/rebuild-status.md
    • 本轮已关闭：
      • T01 对应的 Components / Mesh 资产引用协议失准
      • T02 对应的 Editor 旧迁移链路文档残留
      • T03 对应的跨模块总览与 guide 口径收口
      • T07 对应的 SceneViewportRenderPlan.h 缺页
    • 本轮剩余待继续跟踪：
      • 当前任务池内无未完成块；后续按新增 API 或新增计划任务继续开块

最新收口结论（2026-04-03 14:20:04）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题重新回到 0
    • public headers 246/246
    • Editor source headers 122/122
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增收口结果:
    • T01 Components / Mesh 资产引用最终协议同步 已完成
    • T02 Editor / 移除场景资产引用迁移链路文档与过期页 已完成
    • T03 Cross-Module / 资产引用协议与编辑器工作流交叉说明收口 已完成
    • T07 Editor / SceneViewportRenderPlan 新增头文件补页 已完成
    • T09 Editor / EditorConsoleSink 生命周期与 Managers 总览口径复核 已完成
    • IProjectManager 已按当前头文件拆成 4 个职责页，ProjectManager / ProjectCommands / MainMenuActionRouter / EditorActions / ProjectPanel 已全部同步到当前源码
    • Components 模块总览与 mesh/material 组件页已统一到“项目资产优先 AssetRef、virtual scheme 才稳定保留路径”的当前协议
    • 对应的旧迁移 canonical 页已删除，已删除 API 名称也不再出现在正文里
    • EditorConsoleSink 文档已改回当前真实生命周期：GetInstance() 没有 fallback 实例，未注册时会返回 nullptr
    • docs/api/_meta/rebuild-status.md 当前显示：
      • Markdown pages (canonical): 3273
      • Stale editor doc tokens: 0
      • Stale editor canonical pages: 0
      • Editor high-risk single-page dirs: 0
  • 当前仍待处理的内容级问题:
    • 当前任务池内无未完成块

T06 Rendering / CameraRenderer 与主管线职责边界收口

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围:
    • docs/api/XCEngine/Rendering/CameraRenderer/**
    • docs/api/XCEngine/Rendering/RenderPipeline/**
    • docs/api/XCEngine/Rendering/RenderPipelineAsset/**
    • docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipelineAsset/**
    • 必要时 docs/api/XCEngine/Rendering/Rendering.md
  • 主要源码依据:
    • engine/include/XCEngine/Rendering/CameraRenderer.h
    • engine/src/Rendering/CameraRenderer.cpp
    • engine/include/XCEngine/Rendering/RenderPipeline.h
    • engine/include/XCEngine/Rendering/RenderPipelineAsset.h
    • engine/include/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h
    • tests/Rendering/unit/test_camera_scene_renderer.cpp
  • 当前缺口:
    • 已重写 CameraRenderer.md、Constructor.md、Render.md、Rendering.md、RenderPipeline.md，把“SceneRenderer 负责请求规划、CameraRenderer 负责执行单 request”的真实分层，以及默认 BuiltinForwardPipelineAsset -> BuiltinForwardPipeline 链路同步到当前实现。
    • 已继续重写 RenderPipeline/Initialize.md、Render.md、Shutdown.md、Destructor.md，明确 RenderPipeline 只覆盖主场景 runtime 绘制，不承担 object-id / builtin post-process / overlay 编排；同时写清 Initialize() 不是上层强制预热点，Shutdown() 调用路径由 CameraRenderer 托管。
    • 已校正 RenderPipelineAsset.md、CreatePipeline.md、BuiltinForwardPipelineAsset.md、CreatePipeline.md，把“asset 负责创建 runtime pipeline”与“空 asset / 空返回后的 fallback 由 CameraRenderer 处理”拆开说明，避免把调用方策略误记到 asset 接口本身。
  • 完成标准:
    • 用户只看 CameraRenderer / RenderPipeline / RenderPipelineAsset 这一组页面，也能得出当前正确结论：
      • SceneRenderer 负责请求规划，CameraRenderer 负责执行单 request
      • RenderPipeline 只负责主场景 runtime 绘制
      • fallback 属于调用方装配逻辑，不属于 RenderPipelineAsset 接口本身

T07 Editor / SceneViewportRenderPlan 新增头文件补页

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围:
    • docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**
    • 必要时 docs/api/XCEngine/Editor/Viewport/Viewport.md
    • 必要时 docs/api/_guides/Editor/**
  • 主要源码依据:
    • editor/src/Viewport/SceneViewportRenderPlan.h
    • editor/src/Viewport/ViewportHostService.h
  • 当前缺口:
    • docs/api/_tools/audit_api_docs.py 于 2026-04-03 14:11:12 报出新增未覆盖 header：editor/src/Viewport/SceneViewportRenderPlan.h
    • 当前缺的不只是类型页，还包括内联 helper：
      • SceneViewportRenderPlan
      • SceneViewportRenderPlanBuildResult
      • BuildSceneViewportRenderPlan(...)
      • ApplySceneViewportRenderPlan(...)
    • 从 ViewportHostService.h 的调用关系看，这个头文件已经成为 Scene View request 装配链的一部分，不能继续留白
  • 完成标准:
    • 为 SceneViewportRenderPlan.h 建立 canonical 目录与类型页
    • 把 plan 结构、build result、build/apply 两个 helper 的职责边界写清楚
    • 用户只看这组页面，也能得出当前正确结论：
      • 它负责把 Scene View 的 builtin post-process、overlay passes 与 clear-color override 收口成一个 request plan
      • Build... 负责从 overlay / targets 生成 plan
      • Apply... 负责把 plan 回写到 CameraRenderRequest
  • 完成记录:
    • 已新增：
      • docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md
      • docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlanBuildResult.md
      • docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md
      • docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/ApplySceneViewportRenderPlan.md
    • 已同步更新：
      • docs/api/XCEngine/Editor/Viewport/Viewport.md
      • docs/api/XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md
    • 2026-04-03 14:20:04 审计结果已恢复为：
      • Editor source headers 122/122
      • 失效 .md 链接 0
      • Stale editor doc tokens 0
      • Stale editor canonical pages 0

T08 Rendering / RenderCameraData 与 builtin forward 材质契约补齐

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P2
  • 写入范围:
    • docs/api/XCEngine/Rendering/RenderCameraData/**
    • docs/api/XCEngine/Rendering/RenderSceneUtility/**
    • docs/api/XCEngine/Rendering/RenderMaterialUtility/**
  • 主要源码依据:
    • engine/include/XCEngine/Rendering/RenderCameraData.h
    • engine/include/XCEngine/Rendering/RenderSceneUtility.h
    • engine/src/Rendering/RenderSceneUtility.cpp
    • engine/include/XCEngine/Rendering/RenderMaterialUtility.h
    • tests/Rendering/unit/test_render_scene_extractor.cpp
    • tests/Rendering/unit/test_render_scene_utility.cpp
  • 当前缺口:
    • 已重写 RenderCameraData.md，补齐此前遗漏的 clearFlags 字段，以及 RenderClearFlags / HasRenderClearFlag(...) 的当前位标志语义；同时写清 BuildRenderCameraData() 不负责 clear mode 推导，真正的 per-request clear 规则由 CameraRenderer 回写。
    • 已重写 RenderSceneUtility.md 中 BuildRenderCameraData() 的职责边界，明确它只构建矩阵、世界位置、默认清屏色和 viewport，不直接决定相机 request 的 clear 规则。
    • 已补齐 ResolveBuiltinBaseColorFactor.md、ResolveBuiltinBaseColorTexture.md、BuildBuiltinForwardMaterialData.md，并更新 RenderMaterialUtility.md，把 builtin forward 当前公开消费的 base-color 因子 / 贴图契约、semantic 优先级、别名回退与 alpha-only fallback 写到当前实现。
  • 完成标准:
    • 用户只看 RenderCameraData / RenderSceneUtility / RenderMaterialUtility，也能得出当前正确结论：
      • clear flags 不是 extractor 里按相机直接定死的，而是 request 层再覆盖写回
      • builtin forward 当前公开消费的材质契约至少包括 baseColorFactor 与 base-color 贴图解析规则

T09 Editor / EditorConsoleSink 生命周期与 Managers 总览口径复核

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P2
  • 写入范围:
    • docs/api/XCEngine/Editor/Core/EditorConsoleSink/**
    • docs/api/XCEngine/Editor/Managers/Managers.md
    • docs/api/_tools/audit_api_docs.py
    • 必要时 docs/api/_meta/rebuild-status.md
    • 必要时 docs/used/API文档实时同步任务池_2026-04-03.md
  • 主要源码依据:
    • editor/src/Core/EditorConsoleSink.h
    • editor/src/Core/EditorConsoleSink.cpp
    • tests/Editor/test_editor_console_sink.cpp
    • editor/src/Managers/ProjectManager.h
    • editor/src/Managers/ProjectManager.cpp
  • 当前缺口:
    • EditorConsoleSink.md、GetInstance.md、Destructor.md 仍把 GetInstance() 写成“无活动实例时回退到 fallback sink”，但当前实现只是直接返回 s_instance
    • 新增测试 GetInstanceTracksRegisteredSinkOnly 已明确要求：活动实例析构后 GetInstance() 返回 nullptr
    • Managers.md 仍把“场景资产引用迁移”写成 ProjectManager 的当前职责之一，与本轮已删除的旧迁移链路不一致
  • 完成标准:
    • EditorConsoleSink 生命周期相关页面全部对齐到当前实现：
      • GetInstance() 可能返回 nullptr
      • 没有静态 fallback sink
    • Managers.md 不再残留旧迁移职责表述
    • 审计工具新增轻量兜底，后续若 EditorConsoleSink 文档再次写回 fallback 语义，能够被自动报出
  • 完成记录:
    • 已修正 EditorConsoleSink.md、GetInstance.md、Destructor.md
    • 已修正 Managers.md 中 ProjectManager 的职责概述
    • docs/api/_tools/audit_api_docs.py 已新增针对 EditorConsoleSink 旧 fallback 生命周期表述的定向检测

现阶段优先级建议

  • 当前这份实时任务池里的已知问题已全部收口
  • T01、T02、T03、T05、T06、T07、T09 都已完成，不再作为并行入口重复认领
  • 若工作树继续新增 API 或计划文件继续追加任务块，再按新增内容开新任务

一句话结论

旧任务池解决了“API 文档树有没有建起来”的问题；这份实时任务池目前已经把 Editor 旧迁移链路、Components 资产引用协议、跨模块总览口径、SceneViewportRenderPlan.h 的缺页，以及 EditorConsoleSink 生命周期文档失准全部收口，后续只需要继续跟踪新增 API 与新增计划任务。

Reference in New Issue View Git Blame Copy Permalink