249 lines
11 KiB
Markdown
249 lines
11 KiB
Markdown
# 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` 作为持续性并行入口，用来承接你后续重构带来的新文档漂移。
|