xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b3acb5afc2fe9c4e5e941aada16e24913a0348ac
XCEngine/docs/used/API文档并行更新任务池_2026-04-02.md

43 KiB
Raw Blame History

API 文档并行更新任务池（2026-04-02）

目的

基于 2026-04-02 当前工作树，这份清单用于把 API 文档更新任务拆成可并行认领的独立块，供多个会话同时推进。

认领规则

  • 一次只认领 1 个任务块，先改 状态 和 认领人。
  • 只修改自己任务块的 写入范围，不要跨任务顺手改别的模块页。
  • 除 T09 之外，其他任务不要更新 docs/api/_meta/rebuild-status.md，避免多人冲突。
  • 每个任务都要以源码、实现、测试、真实调用点为依据，不允许只按命名猜测行为。
  • 如果任务执行中发现需要新增 guide，统一放到 docs/api/_guides/<Module>/ 下。

当前并行推荐

  • 历史任务 T01-T20 已完成，本轮文档内容同步与收口已落地。
  • 如果继续并行推进，重点不再是补历史缺页，而是：
    • 跟踪新增源码 API
    • 继续人工抽样审阅审计中提示的高风险单页目录
  • 2026-04-03 00:24:08 这轮复核后，已新增 T21-T27；优先从 Input、Editor 项目工作流、Game View -> Runtime Input 三块并行切入。

任务池

T01 Editor / Viewport 子模块补齐与重写

  • 状态: DONE
  • 认领人: Codex-Viewport
  • 优先级: P0
  • 写入范围: docs/api/XCEngine/Editor/Viewport/**、docs/api/XCEngine/Editor/panels/SceneViewPanel/**、docs/api/XCEngine/Editor/panels/ViewportPanelContent/**
  • 主要源码依据: editor/src/Viewport/**、editor/src/panels/SceneViewPanel.*、editor/src/panels/ViewportPanelContent.h、tests/editor/test_scene_viewport_camera_controller.cpp
  • 当前缺口: Viewport 整个 canonical 树尚未建立；以下页面当前缺失: SceneViewportCameraController、SceneViewportMoveGizmo、SceneViewportRotateGizmo、SceneViewportScaleGizmo、SceneViewportOverlayRenderer、ViewportHostService、ViewportHostRenderFlowUtils、SceneViewportEditorOverlayData、SceneViewportOverlayBuilder、ViewportPanelContent
  • 完成标准: 补齐 Viewport/Viewport.md 与所有类型页；SceneViewPanel 文档重写到当前 gizmo / overlay / host flow 实现；写清楚生命周期、交互链路、渲染路径和测试覆盖

T02 Editor / ScriptComponentEditor 补齐

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P0
  • 写入范围: docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditor/**、docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditorUtils/**、docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md、docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/**
  • 主要源码依据: editor/src/ComponentEditors/ScriptComponentEditor.h、editor/src/ComponentEditors/ScriptComponentEditorUtils.h、editor/src/ComponentEditors/ComponentEditorRegistry.cpp
  • 当前缺口: ScriptComponentEditor 与 ScriptComponentEditorUtils 还没有 canonical 页面；组件编辑器总览也需要纳入脚本组件编辑器
  • 完成标准: 补齐缺页；说明 Inspector 侧脚本字段绘制、字段元数据来源、与 ScriptEngine / ScriptComponent 的关系

T03 Core / AssetDatabase 新建与资产数据库链路说明

  • 状态: DONE
  • 认领人: Codex-Asset
  • 优先级: P0
  • 写入范围: docs/api/XCEngine/Core/Asset/AssetDatabase/**、docs/api/XCEngine/Core/Asset/Asset.md
  • 主要源码依据: engine/include/XCEngine/Core/Asset/AssetDatabase.h、相关 .cpp 实现、项目目录下新增的 .meta 与 Library 资产缓存变化
  • 当前缺口: AssetDatabase 对应的 canonical 类型页完全缺失；Core/Asset 模块总览需要反映新的数据库/导入缓存方向
  • 完成标准: 建立 AssetDatabase 页面，明确 GUID、path、meta、导入缓存、查询职责，以及它和 ProjectPanel / ResourceManager / 资源导入流程的关系

T04 Rendering / Passes 子模块与 BuiltinObjectIdOutlinePass 补齐

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P0
  • 写入范围: docs/api/XCEngine/Rendering/Passes/**
  • 主要源码依据: engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h、engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp
  • 当前缺口: Rendering/Passes 目录当前没有 canonical 文档树；BuiltinObjectIdOutlinePass 页面缺失
  • 完成标准: 新建 Passes/Passes.md 和 BuiltinObjectIdOutlinePass 类型页；写清楚对象 ID / 轮廓高亮的输入输出、依赖资源、典型使用位置和当前限制

T05 Scripting 模块内容重构

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Scripting/**、docs/api/_guides/Scripting/**
  • 主要源码依据: engine/include/XCEngine/Scripting/IScriptRuntime.h、Mono/MonoScriptRuntime.h、NullScriptRuntime.h、ScriptComponent.h、ScriptEngine.h 及对应 .cpp；tests/scripting/**
  • 当前缺口: 结构存在，但脚本运行时、字段同步、项目脚本程序集、空运行时回退等内容需要按当前实现重写
  • 完成标准: 明确运行时抽象、Mono 后端、Null 后端、字段存储与组件生命周期；必要时补一篇项目脚本程序集 / 字段同步 guide

T06 Editor 运行时胶水层与面板内容更新

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Editor/Application/**、docs/api/XCEngine/Editor/Core/EventBus/**、docs/api/XCEngine/Editor/panels/InspectorPanel/**、docs/api/XCEngine/Editor/panels/ProjectPanel/**、docs/api/XCEngine/Editor/UI/Widgets/**、docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/**、docs/api/XCEngine/Editor/Commands/EntityCommands/**
  • 主要源码依据: editor/src/Application.*、editor/src/Core/EventBus.h、editor/src/panels/InspectorPanel.*、editor/src/panels/ProjectPanel.*、editor/src/UI/Widgets.h、editor/src/Actions/HierarchyActionRouter.h、editor/src/Commands/EntityCommands.h
  • 当前缺口: 这些页面虽然大多存在，但内容容易落后于当前交互链路；ProjectPanel 虽已较新，仍要根据这轮源码变化做二次核对
  • 完成标准: 把“Editor 主循环 -> EventBus -> 面板 -> Action/Command”这条链路写清楚；Inspector/Project/Hierarchy 相关页内容与当前实现严格对齐

T07 Rendering 相机请求与对象 ID 渲染链路更新

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Rendering/CameraRenderRequest/**、docs/api/XCEngine/Rendering/CameraRenderer/**、docs/api/XCEngine/Rendering/RenderMaterialUtility/**、docs/api/XCEngine/Rendering/Rendering.md
  • 主要源码依据: engine/include/XCEngine/Rendering/CameraRenderRequest.h、engine/src/Rendering/CameraRenderer.cpp、engine/src/Resources/Material/MaterialLoader.cpp、engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp
  • 当前缺口: 文档需要反映这轮 renderer 里对象 ID、outline、camera request、材质 render state 的新关系
  • 完成标准: 写清楚 camera request 的职责边界、camera renderer 的主流程、object-id/outline 的接入点，以及材质 render state 对渲染路径的影响

T08 Components / MeshFilterComponent 与资源绑定链路更新

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Components/MeshFilterComponent/**、docs/api/XCEngine/Components/Components.md
  • 主要源码依据: engine/include/XCEngine/Components/MeshFilterComponent.h、相关 .cpp、tests/Resources/Mesh/test_mesh_loader.cpp、tests/Resources/Material/test_material_loader.cpp
  • 当前缺口: MeshFilterComponent 页面存在，但需要重新核对 mesh handle / path / 资源解析链路；模块总览也应补充 MeshFilter 在渲染和资产导入链路中的定位
  • 完成标准: 说明 MeshFilterComponent 如何保存 mesh 引用、如何与资源系统和渲染提取流程衔接，以及当前限制

T09 根总览与最终审计

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P2
  • 写入范围: docs/api/XCEngine/XCEngine.md、受影响的模块总览页、docs/api/_meta/rebuild-status.md
  • 主要源码依据: 前面所有任务的完成结果
  • 当前缺口: 已完成根总览与模块总览收口；2026-04-02 23:22:27 的最终审计结果显示 246/246 个 public headers 全量覆盖，结构性问题保持 0
  • 完成标准: 在 T10-T13 完成后统一调整总览页导航；重新执行 audit_api_docs.py、覆盖校验与链接校验；确认未覆盖 public headers 归零后写回最终 rebuild-status.md

审计结论（2026-04-02 23:22:27）

  • 本轮全量审计已执行: python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题为 0: 无失效 .md 链接、无非 .md 相对链接、无旧模板页面、无扁平 header 页面、无缺失目录总览页
  • 当前剩余覆盖缺口: 0 个 public headers 未覆盖
  • 受影响模块:
    • Core: 0
    • Rendering: 0
    • Resources: 0
    • Scene: 0
  • 说明:
    • T01-T13 对应的结构重构、基础层补页与总览收口已全部落地
    • AssetImportService 与 ProjectAssetIndex 两个 Core/Asset 尾项已补齐
    • canonical API 文档树当前与 engine/include/XCEngine 的 public header 集合保持全量对齐

T10 Core / Asset 标识与产物格式补齐

  • 状态: DONE
  • 认领人: Codex-Asset2
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Core/Asset/ArtifactFormats/**、docs/api/XCEngine/Core/Asset/AssetGUID/**、docs/api/XCEngine/Core/Asset/AssetRef/**
  • 主要源码依据: engine/include/XCEngine/Core/Asset/ArtifactFormats.h、engine/include/XCEngine/Core/Asset/AssetGUID.h、engine/include/XCEngine/Core/Asset/AssetRef.h、相关使用点 engine/src/Components/MeshFilterComponent.cpp、engine/src/Resources/*/*Loader.cpp、tests/core/Asset/test_resource_manager.cpp、tests/Resources/Texture/test_texture_loader.cpp
  • 当前缺口: 已补齐 ArtifactFormats、AssetGUID、AssetRef 三个 canonical 页面，并将资产身份 / 引用 / artifact 格式链路并入 Core/Asset 模块叙述
  • 完成标准: 建立三个 canonical 类型页，写清楚 GUID 格式、AssetRef 结构语义、artifact 产物文件格式在资源导入与反序列化链路中的作用

T11 Rendering / RenderPass 与 SceneRenderRequest 基础层补齐

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Rendering/ObjectIdEncoding/**、docs/api/XCEngine/Rendering/ObjectIdPass/**、docs/api/XCEngine/Rendering/RenderPass/**、docs/api/XCEngine/Rendering/RenderSceneUtility/**、docs/api/XCEngine/Rendering/SceneRenderRequestPlanner/**、docs/api/XCEngine/Rendering/SceneRenderRequestUtils/**
  • 主要源码依据: engine/include/XCEngine/Rendering/ObjectIdEncoding.h、ObjectIdPass.h、RenderPass.h、RenderSceneUtility.h、SceneRenderRequestPlanner.h、SceneRenderRequestUtils.h，对应 .cpp，以及 tests/Rendering/unit/test_render_pass.cpp、test_render_scene_utility.cpp、test_scene_render_request_planner.cpp、test_scene_render_request_utils.cpp、test_camera_scene_renderer.cpp、tests/Editor/test_viewport_render_flow_utils.cpp
  • 当前缺口: 已补齐 ObjectIdEncoding、ObjectIdPass、RenderPass、RenderSceneUtility、SceneRenderRequestPlanner、SceneRenderRequestUtils 六个基础层页面，并回写 Rendering 总览导航
  • 完成标准: 补齐六个类型页，明确 render pass 生命周期、object-id 编解码语义、scene request 规划规则，以及这些基础设施与 CameraRenderer / editor viewport 的衔接

T12 Resources / BuiltinResources 补齐

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Resources/BuiltinResources/**
  • 主要源码依据: engine/include/XCEngine/Resources/BuiltinResources.h、engine/src/Resources/BuiltinResources.cpp、相关调用点 editor/src/Commands/EntityCommands.h、engine/src/Rendering/Passes/BuiltinObjectIdPass.cpp、engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp、engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp、tests/Resources/Shader/test_shader_loader.cpp
  • 当前缺口: 已建立 BuiltinResources canonical 页面，并纳入 Resources 模块总览
  • 完成标准: 建立 BuiltinResources 类型页，写清楚内置 mesh / material / shader / primitive display name 的职责边界、典型调用点与当前限制

T13 Scene / RuntimeLoop 补齐

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Scene/RuntimeLoop/**
  • 主要源码依据: engine/include/XCEngine/Scene/RuntimeLoop.h、engine/src/Scene/RuntimeLoop.cpp、editor/src/Core/PlaySessionController.h、tests/Scene/test_runtime_loop.cpp
  • 当前缺口: 已建立 RuntimeLoop canonical 页面，并把 fixed step / pause / step-frame 语义并入 Scene 模块导航
  • 完成标准: 建立 RuntimeLoop 类型页，说明 fixed step / max delta / max fixed steps 这些设置的语义，以及它与 play mode、scene tick 生命周期的关系

T14 Core / Asset 服务与索引尾项补齐

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Core/Asset/AssetImportService/**、docs/api/XCEngine/Core/Asset/ProjectAssetIndex/**、必要时补充 docs/api/XCEngine/Core/Asset/Asset.md
  • 主要源码依据: 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
  • 当前缺口: 已补齐 AssetImportService、ProjectAssetIndex 两个 canonical 页面，并把它们补入 Core/Asset 模块总览
  • 完成标准: 建立两个类型页，写清楚 AssetDatabase -> AssetImportService -> ProjectAssetIndex -> ResourceManager 这条项目资产查询链路

二次审核结论（2026-04-02 23:31:03）

  • 本轮全量结构审计已执行: python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题为 0: 无失效 .md 链接、无非 .md 相对链接、无旧模板页面、无扁平 header 页面、无缺失目录总览页
  • 当前剩余覆盖缺口: 0 个 public headers 未覆盖
  • 审计口径说明:
    • 当前 docs/api/_meta/rebuild-status.md 的覆盖口径仍是 engine/include/XCEngine 的 public headers。
    • Editor 下基于 editor/src/** 的源文件页、方法页颗粒度，以及说明性内容是否跟随源码重构同步，仍需要人工复核。
  • 抽样确认出的实际遗留问题:
    • Editor/Application 目录当前只有 Application.md，ReloadScriptingRuntime()、RebuildScriptingAssemblies()、GetScriptRuntimeStatus() 只在总览页有概述，缺少按商业级 API 文档颗粒度拆出的独立方法页。
    • Editor/panels/SceneViewPanel 目录当前只有 SceneViewPanel.md，尚未把 pivot / center、global / local、scene icon 命中优先级、transient overlay 注入链路拆开讲透。

T15 Components / MeshRendererComponent 内容同步

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P0
  • 写入范围: docs/api/XCEngine/Components/MeshRendererComponent/**、必要时 docs/api/XCEngine/Components/Components.md
  • 主要源码依据: engine/include/XCEngine/Components/MeshRendererComponent.h、engine/src/Components/MeshRendererComponent.cpp、tests/Components/test_mesh_render_components.cpp
  • 当前缺口: 已核对 MeshRendererComponent.md、Serialize.md、Deserialize.md、GetMaterial.md、GetMaterialHandle.md、SetMaterialPath.md 与 Components.md；文档已覆盖 materialPaths + materialRefs 双轨序列化、deferred async material load 与首次访问触发加载的当前行为
  • 完成标准: 重写 MeshRendererComponent.md、Serialize.md、Deserialize.md、GetMaterial.md、GetMaterialHandle.md、SetMaterialPath.md 等核心页面，写清楚 deferred load、asset ref 回填与测试覆盖

T16 Scripting / ScriptEngine 固定步长配置补齐

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P0
  • 写入范围: docs/api/XCEngine/Scripting/ScriptEngine/**、必要时 docs/api/XCEngine/Scripting/Scripting.md、docs/api/_guides/Scripting/**
  • 主要源码依据: engine/include/XCEngine/Scripting/ScriptEngine.h、engine/src/Scripting/ScriptEngine.cpp、tests/scripting/test_script_engine.cpp
  • 当前缺口: 已补齐 SetRuntimeFixedDeltaTime()、GetRuntimeFixedDeltaTime()、DefaultFixedDeltaTime 页面，并把 fixed delta 配置、运行时启停复位语义与 OnFixedUpdate() 的关系补入 ScriptEngine 与 Scripting 总览
  • 完成标准: 补齐固定步长相关页面，并写清楚它与 OnFixedUpdate()、运行时启动/停止、脚本类重绑定之间的关系

T17 Editor / Application 脚本运行时方法页补齐

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Editor/Application/**、必要时 docs/api/XCEngine/Editor/Scripting/**
  • 主要源码依据: editor/src/Application.h、editor/src/Application.cpp、editor/src/Scripting/EditorScriptAssemblyBuilder.h、editor/src/Scripting/EditorScriptRuntimeStatus.h、tests/Editor/test_editor_script_assembly_builder.cpp
  • 当前缺口: 已补齐 ReloadScriptingRuntime()、RebuildScriptingAssemblies()、GetScriptRuntimeStatus() 独立页面，并补入“程序集缺失时如何降级到不可用状态”的明确说明
  • 完成标准: 为上述方法补齐独立页面，写清楚构建成功/失败路径、Mono 后端缺失时的回退、状态快照如何供 Inspector/脚本 UI 消费

T18 Editor / SceneViewPanel 交互语义深化

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Editor/panels/SceneViewPanel/**、必要时 docs/api/XCEngine/Editor/Viewport/**、docs/api/_guides/Editor/**
  • 主要源码依据: editor/src/panels/SceneViewPanel.h、editor/src/panels/SceneViewPanel.cpp、editor/src/Viewport/SceneViewportOverlayHandleBuilder.h、editor/src/Viewport/SceneViewportOverlayHitTester.h、editor/src/Viewport/IViewportHostService.h
  • 当前缺口: 已重写 SceneViewPanel.md，并新增 SceneView Interaction And Gizmo Model guide；文档已明确 pivot / center 的计算依据、global / local 轴向语义、scene icon 与 gizmo 的命中优先级，以及 cached / interaction / transient 三层 overlay 数据流
  • 完成标准: 把 Scene View 交互模型补成商业级说明，尤其是 selection pivot、transform space、overlay hit-test 与 scene icon 选择这几条链路

T19 审计工具口径扩展

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P2
  • 写入范围: docs/api/_tools/audit_api_docs.py、必要时 docs/api/_meta/rebuild-status.md
  • 主要源码依据: 当前审计脚本口径与 docs/api/XCEngine/Editor/** 的实际页面分布
  • 当前缺口: 自动审计目前能确认 public headers 与链接结构，但无法自动暴露 Editor 源文件页是否缺少方法页，也无法报告像 Application、SceneViewPanel 这种“只有总览页”的高风险目录
  • 完成标准: 让审计结果至少能额外报告 source-file 页覆盖概况或方法页缺口统计，降低后续人工抽样成本

T20 二次内容收口与最终复核

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P2
  • 写入范围: docs/api/_meta/rebuild-status.md、docs/plan/API文档并行更新任务池_2026-04-02.md、必要时受影响的模块总览页
  • 主要源码依据: T15-T19 的完成结果
  • 当前缺口: 已在 2026-04-03 00:16:11 重新执行 python docs/api/_tools/audit_api_docs.py 并回写 rebuild-status.md；结构性问题继续保持 0，246/246 public headers 与 120/120 Editor source headers 继续全量覆盖；审计中的 Editor 高风险单页目录数: 19 属于启发式抽样信号，不等同于仍有 19 处缺页
  • 完成标准: 在 T15-T19 完成后重新执行结构审计与人工抽样复核，把新的结论写回进度表

收口结论（2026-04-03 00:16:11）

  • 本轮收口审计已执行: python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题继续为 0:
    • 无失效 .md 链接
    • 无非 .md 相对链接
    • 无旧模板页面
    • 无扁平 header 页面
    • 无失效 header / source ref
  • 当前覆盖状态:
    • public headers 246/246
    • Editor source headers 120/120
  • 本轮内容级收口结果:
    • MeshRendererComponent 内容同步已完成
    • ScriptEngine 固定步长配置页已补齐
    • Application 脚本运行时方法页已补齐
    • SceneViewPanel 交互语义与 guide 已补齐
  • 审计提示解释:
    • Editor 高风险单页目录数: 19 是新增启发式报告，用于提示“目录只有单页但实现较大，建议继续人工抽样”
    • 它不是“当前仍缺 19 个 canonical 页面”的等价表达

三次审核结论（2026-04-03 00:24:08）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题仍为 0
    • public headers 246/246
    • Editor source headers 120/120
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增问题不在“结构覆盖”，而在“内容与源码同步”
  • 经过 git diff、源码抽样与文档抽样，当前确认的内容级缺口有：
    • Input/InputManager 文档已失准
      • Input.md / InputManager.md 仍把 GetAxisRaw() 解释成“按下边沿”语义
      • GetButtonUp() 的未注册按钮返回值说明仍是旧行为
      • 缺少 IsKeyReleased.md、IsMouseButtonReleased.md、IsAnyKeyDown.md、IsAnyKeyPressed.md
    • Editor 的 Game View 输入桥接链路没有写完整
      • GameViewPanel 还在按“薄视口壳层”描述
      • EditorEvents 还没纳入 GameViewInputFrameEvent
      • GameViewPanel -> EventBus -> PlaySessionController -> InputManager 这条运行时输入链路没有统一说明
    • Editor 项目工作流文档落后于当前功能
    • Core/Asset 局部页存在陈旧说明
      • AssetDatabase 仍提到已不存在的 ResourceManager::m_ioMutex
      • 新增的 artifact 依赖快照、BuildLookupSnapshot() 热路径、AssetImportService + ProjectAssetIndex 分层关系需要再校对一次叙述是否完全一致
    • Scripting 虽已补齐 fixed delta 页面，但托管输入桥接与类发现/类切换行为还没有在模块页和 guide 层讲透
  • 另外有一个文档组织问题需要收口：
    • docs/api/_guides/Editor/Scene-View-Interaction-Model.md
    • docs/api/_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md
    • 这两篇主题重叠，当前链接入口分叉，需统一 canonical guide
  • Editor 高风险单页目录数: 19 仍保留为抽样队列，不等同于这 19 处都已确认失准

T21 Input / InputManager 内容校准与方法补页

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P0
  • 写入范围: docs/api/XCEngine/Input/**、必要时 docs/api/_guides/Input/**
  • 主要源码依据: engine/include/XCEngine/Input/InputManager.h、engine/src/Input/InputManager.cpp、tests/Input/test_input_manager.cpp
  • 当前缺口:
    • 已重写 Input.md、InputManager.md 与 Input-Flow-and-Frame-Semantics.md
    • 已补齐 IsKeyReleased.md、IsMouseButtonReleased.md、IsAnyKeyDown.md、IsAnyKeyPressed.md
    • 文档已按当前源码校正 GetAxisRaw()、GetButtonUp()、ProcessKeyUp()、ProcessMouseButton() 与 Update() 的帧语义
    • 已进一步补充 IsKeyPressed() / GetButtonDown() / IsAnyKeyPressed() 的 repeat 语义，以及 IsKeyUp() / IsMouseButtonUp() 和释放边沿接口的区别
  • 完成标准: 重写模块页与类型页，补齐 4 个方法页，并把键鼠释放态、any-key 语义、默认映射和测试覆盖按当前源码写清楚

T22 Editor / Game View 输入桥接链路补写

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P0
  • 写入范围: docs/api/XCEngine/Editor/panels/GameViewPanel/**、docs/api/XCEngine/Editor/Core/EditorEvents/**、docs/api/XCEngine/Editor/Core/PlaySessionController/**、必要时 docs/api/_guides/Editor/**
  • 主要源码依据: editor/src/panels/GameViewPanel.cpp、editor/src/Core/EditorEvents.h、editor/src/Core/PlaySessionController.h、editor/src/Core/PlaySessionController.cpp、tests/editor/test_play_session_controller.cpp
  • 当前缺口:
    • 已重写 GameViewPanel.md，补入 ImGui 键鼠采集、逐帧发布 GameViewInputFrameEvent 与空事件释放语义
    • EditorEvents.md 已纳入 GameViewInputFrameEvent
    • PlaySessionController.md 已明确“只有运行态 Update() 才会把 Game View 输入桥接到 InputManager”及 hovered/focused 门控规则
    • 已补齐 GameViewPanel/Constructor.md 与 GameViewPanel/Render.md
    • 已新增 docs/api/_guides/Editor/Game-View-Runtime-Input-Bridge.md，把 GameViewPanel -> EventBus -> PlaySessionController -> InputManager 收口成单条连续说明
  • 完成标准: 把 GameViewPanel -> EventBus -> PlaySessionController -> InputManager 这条桥接链路写成一组可追踪的 API 文档，明确 hovered/focused、键鼠状态快照与帧边界

T23 Editor / 项目工作流与脚本菜单同步

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P0
  • 写入范围: docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/**、docs/api/XCEngine/Editor/Actions/EditorActions/**、docs/api/XCEngine/Editor/Actions/ProjectActionRouter/**、docs/api/XCEngine/Editor/Commands/ProjectCommands/**、docs/api/XCEngine/Editor/Core/IProjectManager/**、docs/api/XCEngine/Editor/Managers/ProjectManager/**、必要时 docs/api/XCEngine/Editor/panels/ProjectPanel/**
  • 主要源码依据: 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
  • 当前缺口:
    • 已重写 MainMenuActionRouter.md，补入 Scripts 菜单、Migrate Scene AssetRefs 文件菜单入口，以及菜单到 ProjectCommands / EventBus 的下游链路
    • 已重写 ProjectCommands.md，补入 RebuildScriptAssemblies、MigrateSceneAssetReferences、SwitchProject 与 SaveProject 的真实 guard 和执行流程
    • 已重写 IProjectManager.md / ProjectManager.md，补入 SceneAssetReferenceMigrationReport 结构、Assets/**/*.xc 批量迁移流程、ResourceManager::ScopedDeferredSceneLoad 与日志/刷新语义
    • 已进一步补充“菜单层不消费返回值”“脚本重建产物不在 ProjectPanel 视图内”“.meta sidecar 跟随规则”“迁移报告只给汇总计数”的边界说明
    • 已校对 ProjectPanel.md 与 EditorActions.md，明确面板只消费资源级命令，而项目保存 / 脚本重建 / 场景迁移入口位于主菜单
  • 完成标准: 把项目工作流文档升级到“菜单入口 -> command -> manager -> 场景重写报告”的完整链路，并校对 ProjectPanel 对这些命令的消费关系

T24 Core / AssetDatabase 与项目资产快照链路复核

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Core/Asset/AssetDatabase/**、docs/api/XCEngine/Core/Asset/ResourceManager/**、必要时 docs/api/XCEngine/Core/Asset/Asset.md
  • 主要源码依据: engine/include/XCEngine/Core/Asset/AssetDatabase.h、engine/src/Core/Asset/AssetDatabase.cpp、engine/include/XCEngine/Core/Asset/ResourceManager.h、engine/src/Core/Asset/ResourceManager.cpp、engine/src/Resources/Material/MaterialLoader.cpp、tests/core/Asset/test_resource_manager.cpp
  • 当前缺口:
    • 已移除 AssetDatabase.md 中陈旧的 m_ioMutex 叙述，并改成当前 AssetImportService::recursive_mutex 的真实封装关系
    • 已重写 BuildLookupSnapshot()、TryGetAssetRef()、EnsureArtifact() 和 Asset.md 中关于 snapshot 消费链路、cache miss 自刷新和 artifact 导入边界的说明
    • 已补入材质纹理绑定依赖、.obj -> .mtl -> texture 依赖快照，以及 BuildLookupSnapshot() 只导出主资产 path/GUID 表而不导出 artifact 路径的语义
    • 已继续重写 ResourceManager 下残留的通用占位方法页，补齐 Get()、AddRef()/Release()、Find()/Exists()、Unload*()、ResolvePath()、LoadGroup() 等真实行为与当前限制
  • 完成标准: 把 AssetDatabase -> ResourceManager 的当前链路与依赖快照行为写实，并消除与 AssetImportService / ProjectAssetIndex 相关的陈旧描述

T25 Scripting / 托管输入桥接与类发现链路补强

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Scripting/**、必要时 docs/api/_guides/Scripting/**
  • 主要源码依据: engine/include/XCEngine/Scripting/IScriptRuntime.h、engine/include/XCEngine/Scripting/Mono/MonoScriptRuntime.h、engine/include/XCEngine/Scripting/NullScriptRuntime.h、engine/include/XCEngine/Scripting/ScriptComponent.h、engine/include/XCEngine/Scripting/ScriptEngine.h、对应 .cpp、managed/XCEngine.ScriptCore/Input.cs、managed/XCEngine.ScriptCore/Time.cs、managed/XCEngine.ScriptCore/KeyCode.cs、tests/scripting/test_mono_script_runtime.cpp、tests/scripting/test_script_engine.cpp
  • 当前缺口:
    • 已重写 Scripting.md、ScriptEngine.md 与 MonoScriptRuntime.md，把托管 Input / Time internal call、Time.fixedDeltaTime 配置来源，以及 InputManager 消费边界收口到同一条说明链。
    • 已补强 TryGetAvailableScriptClasses()、SetScriptClass()、ClearScriptClass() 与 IScriptRuntime 契约页，明确排序、按程序集过滤、项目程序集发现和类切换重建语义。
    • 已重写两篇 Scripting guide，把 project/Assets/**/*.cs -> GameScripts.dll -> ScriptClassDescriptor -> ScriptComponent::SetScriptClass() 以及运行时切类后的实例销毁/重建流程串成连续入口。
  • 完成标准: 在不扩散成两套文档体系的前提下，把原生 ScriptEngine、Mono internal call、项目脚本类发现与类切换重建写成一组连续说明

四次审核结论（2026-04-03 11:39:21）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题继续为 0
    • public headers 246/246
    • Editor source headers 121/121
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增与收口结果:
    • EditorConsoleSink 已从单页目录重构为“类型页 + record 页 + 方法页”
    • ConsoleFilterState 已按真实字段与别名关系重写
    • 工作树新增的 editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h 已补入 canonical 文档树
  • 审计抽样结果:
    • Editor 高风险单页目录数 已从 14 下降到 10
    • ConsolePanel 与 EditorConsoleSink 已移出高风险单页目录清单
    • 当前剩余抽样池见 T26

五次审核结论（2026-04-03 11:56:30）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题继续为 0
    • public headers 246/246
    • Editor source headers 121/121
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增与收口结果:
    • 已补齐 GameViewPanel/Constructor.md 与 GameViewPanel/Render.md
    • 已新增 Game View Runtime Input Bridge guide，并把 GameViewPanel、EditorEvents、PlaySessionController 和 Editor-Architecture-And-Workflow 串成统一入口
  • 审计抽样结果:
    • Editor 高风险单页目录数 已从 10 下降到 5
    • 当前剩余抽样池已进一步收缩到 Viewport gizmo + SceneManager

六次审核结论（2026-04-03 12:00:34）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题继续为 0
    • public headers 246/246
    • Editor source headers 121/121
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增与收口结果:
    • 已重写 SceneManager.md，并补齐实体编辑、场景文件生命周期、快照恢复相关方法页
    • ISceneManager.md 已按当前实现职责更新接口说明
  • 审计抽样结果:
    • Editor 高风险单页目录数 已从 5 下降到 0
    • T26 对应的启发式抽样队列已全部清空

T26 Editor / 高风险单页目录抽样复核队列

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P2
  • 写入范围: docs/api/XCEngine/Editor/Managers/SceneManager/**、docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/**、docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/**、docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/**、docs/api/XCEngine/Editor/Viewport/SceneViewportOrientationGizmo/**
  • 主要源码依据: docs/api/_meta/rebuild-status.md 中的高风险单页目录清单及对应 editor/src/**
  • 当前缺口:
    • 2026-04-03 12:00:34 这轮复核后，审计中的 Editor 高风险单页目录数 已下降到 0。
    • 启发式抽样队列已收口完成，当前不再保留剩余目录。
  • 完成标准: 至少抽样复核一遍源码与现有页面；若发现失准则直接重写，若确认足够则在任务认领记录里注明“已复核”

T27 Editor / Scene View 交互 guide 去重与入口收口

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P2
  • 写入范围: docs/api/_guides/Editor/Scene-View-Interaction-Model.md、docs/api/_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md、以及所有引用这两篇 guide 的 API 页面
  • 主要依据: 当前 guide 内容本身与 SceneViewPanel / IViewportHostService / ViewportHostService / Viewport.md 的交叉链接分布
  • 当前缺口:
    • 已确认 SceneView-Interaction-And-Gizmo-Model.md 作为唯一 canonical guide；旧 Scene-View-Interaction-Model.md 保留为兼容入口页，只负责跳转说明。
    • 已把残留的业务页引用统一切到 canonical guide，当前仓库里已无 API 页面继续把旧 guide 当主入口。
  • 完成标准: 统一保留一个 canonical guide 或明确拆分两篇职责，并把全部入口链接收口到一致命名

四次审核结论（2026-04-03 11:44:52）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题仍为 0
    • public headers 246/246
    • Editor source headers 121/121
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增收口结果:
    • T21 Input / InputManager 已补充 Pressed / Up / Released / repeat 的内容级语义说明
    • Input-Flow-and-Frame-Semantics.md 已提升为面向接入与设计理解的 canonical guide
  • 当前自动审计提示:
    • Editor high-risk single-page dirs: 10
    • 这仍是人工抽样优先队列，不等同于已经确认存在 10 处失准
  • 后续并行优先级建议保持为:
    • T23
    • T24 / T25
    • T26 / T27

五次审核结论（2026-04-03 11:53:48）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题仍为 0
    • public headers 246/246
    • Editor source headers 121/121
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增收口结果:
    • T23 Editor / 项目工作流与脚本菜单同步 已继续补强内容级说明
    • 已明确主菜单层只负责触发项目维护动作，不消费 RebuildScriptAssemblies / MigrateSceneAssetReferences 的返回结果
    • 已明确 ProjectPanel 只投影 <Project>/Assets，因此脚本重建成功后不保证出现可见树变化
    • 已明确 ProjectManager 的 .meta sidecar 跟随语义、resource root 临时切换 / 恢复，以及迁移报告只提供汇总计数
  • 当前自动审计提示:
    • Editor high-risk single-page dirs: 6
    • 仍属于人工抽样队列，不等同于已经确认失准
  • 后续并行优先级建议调整为:
    • T24 / T25
    • T26
    • T27

六次审核结论（2026-04-03 11:57:51）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题仍为 0
    • public headers 246/246
    • Editor source headers 121/121
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增收口结果:
    • T24 Core / AssetDatabase 与项目资产快照链路复核 已完成
    • 已修正 AssetDatabase 的锁模型、BuildLookupSnapshot() 的真实消费链路、TryGetAssetRef() 与 EnsureArtifact() 的职责边界
    • 已把材质贴图依赖与模型依赖快照的真实采集方式补入文档
  • 当前自动审计提示:
    • Editor high-risk single-page dirs: 4
    • 仍属于人工抽样队列，不等同于已经确认失准

七次审核结论（2026-04-03 12:16:18）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题仍为 0
    • public headers 246/246
    • Editor source headers 121/121
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增收口结果:
    • T24 已继续补齐 ResourceManager 目录下残留的占位方法页
    • ResolvePath()、Exists()/Find()、Unload*()、LoadGroup() 等方法页已改成按源码解释当前行为与限制
  • 当前自动审计提示:
    • Editor high-risk single-page dirs: 0
    • 当前追踪表中的内容级收口任务已全部落地
  • 后续并行优先级建议调整为:
    • T25
    • T26
    • T27

八次审核结论（2026-04-03 12:21:03）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题仍为 0
    • public headers 246/246
    • Editor source headers 121/121
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增收口结果:
    • T25 Scripting / 托管输入桥接与类发现链路补强 已完成最后一轮内容级重写
    • 已把托管 Input / Time internal call、Time.fixedDeltaTime 配置来源、TryGetAvailableScriptClasses() 的排序与按程序集过滤语义、SetScriptClass() / ClearScriptClass() 的运行时重建链路补入模块页、类型页与 guide
    • MonoScriptRuntime 与两篇 Scripting guide 已明确项目脚本程序集入口、类发现约束、字段默认值与本地覆盖同步的设计边界
  • 当前自动审计提示:
    • Editor high-risk single-page dirs: 0
    • 当前任务池中的内容级收口任务已全部完成
  • 后续并行优先级建议调整为:
    • 跟踪后续源码新增 API
    • 发现新的内容失准后再按模块开新任务
    • 保持 docs/api/_meta/rebuild-status.md 的周期性审计回写

T28 Rendering / BuiltinForwardPipeline 资源契约与描述符布局同步

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/**、必要时 docs/api/XCEngine/Rendering/Pipelines/Pipelines.md、docs/api/XCEngine/Rendering/Rendering.md
  • 主要源码依据: engine/include/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h、engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp、tests/Rendering/unit/test_builtin_forward_pipeline.cpp
  • 当前缺口:
    • 已重写 BuiltinForwardPipeline.md、Initialize.md、Render.md、Shutdown.md，把 RenderPassSequence、PassResourceLayout、动态/静态 descriptor set 分流与 legacy binding 回退补齐到当前实现。
    • 已新增 Constructor.md 与 BuildInputLayout.md，补齐公开构造入口和 StaticMeshVertex 输入布局契约。
    • 已新增 BuiltinForwardPipelineAsset/BuiltinForwardPipelineAsset.md、BuiltinForwardPipelineAsset/CreatePipeline.md，补清默认 pipeline asset 工厂与 runtime pipeline 的衔接关系。
    • 已更新 Pipelines.md、RenderPipeline.md、RenderPipelineAsset.md、RenderPipelineAsset/CreatePipeline.md、Rendering.md 与渲染 guide，使 ForwardLit 资源契约、visibleItems 和默认 pipeline asset 链路保持一致。
  • 完成标准: 把 BuiltinForwardPipeline 类型页与核心方法页重写到当前实现，明确 shader pass 资源契约、descriptor set 生命周期、legacy 回退语义和当前限制

T29 Rendering / SceneRenderer 与 RenderSceneExtractor 口径复核

  • 状态: DONE
  • 认领人: Codex
  • 优先级: P1
  • 写入范围: docs/api/XCEngine/Rendering/SceneRenderer/**、docs/api/XCEngine/Rendering/RenderSceneExtractor/**、docs/api/XCEngine/Rendering/VisibleRenderObject/**
  • 主要源码依据: engine/include/XCEngine/Rendering/SceneRenderer.h、engine/src/Rendering/SceneRenderer.cpp、engine/include/XCEngine/Rendering/RenderSceneExtractor.h、engine/src/Rendering/RenderSceneExtractor.cpp、tests/Rendering/unit/test_camera_scene_renderer.cpp、tests/Rendering/unit/test_scene_render_request_planner.cpp
  • 当前缺口:
    • 已重写 SceneRenderer.md、Constructor.md、Destructor.md、SetPipeline.md、GetPipeline.md、Render.md，纠正“SceneRenderer 直接做 scene extraction / 直接创建 BuiltinForwardPipeline”的旧口径。
    • 已新增 BuildRenderRequests.md、SetPipelineAsset.md、GetPipelineAsset.md，补齐 SceneRenderer 当前公开方法页。
    • 已重写 RenderSceneExtractor.md 与 Extract.md，并新增 ExtractForCamera.md、SelectCamera.md，把 visibleItems、相机选择、光照提取与排序规则同步到当前实现。
    • 已重写 VisibleRenderObject.md，把它明确为 VisibleRenderItem 的兼容别名入口，并补齐 material / section / renderQueue / cameraDistanceSq 等当前字段。
  • 完成标准: 把 SceneRenderer 更新为“请求规划 + 转发到 CameraRenderer”的真实职责模型；把 RenderSceneExtractor 更新为 visibleItems 与当前排序 / 相机选择语义

九次审核结论（2026-04-03 13:30:05）

  • 已重新执行 python docs/api/_tools/audit_api_docs.py
  • 当前结构性问题仍为 0
    • public headers 246/246
    • Editor source headers 121/121
    • 失效 .md 链接 0
    • 无效 header / source ref 0
  • 本轮新增收口结果:
    • T28 Rendering / BuiltinForwardPipeline 资源契约与描述符布局同步 已完成
    • 已补齐 BuiltinForwardPipeline/Constructor.md、BuiltinForwardPipeline/BuildInputLayout.md 与 BuiltinForwardPipelineAsset 类目录
    • 已把默认 BuiltinForwardPipelineAsset -> BuiltinForwardPipeline -> CameraRenderer 链路补入 Pipelines、RenderPipelineAsset、RenderPipeline、Rendering 与 rendering guide
  • 当前自动审计提示:
    • Editor high-risk single-page dirs: 0
    • 当前 canonical API 树与 public headers / Editor source headers 仍保持全量覆盖

备注

  • T01-T20 当前已全部完成
  • T21-T27 当前也已全部完成
  • 下一阶段重点已经从“补历史缺页”切换为“跟踪源码新增行为并持续校正文档内容”
Reference in New Issue View Git Blame Copy Permalink