XCEngine/docs/plan/API文档并行更新任务池_2026-04-02.md

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

## 目的

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

## 认领规则

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

## 首批并行推荐

- 优先并行启动: `T01`、`T03`、`T04`、`T05`、`T07`
- 第二批跟进: `T02`、`T06`、`T08`
- 收尾整合: `T09`

## 任务池

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

- 状态: `IN_PROGRESS`
- 认领人: `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 新建与资产数据库链路说明

- 状态: `IN_PROGRESS`
- 认领人: `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 运行时胶水层与面板内容更新

- 状态: `TODO`
- 认领人: `未认领`
- 优先级: `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 与资源绑定链路更新

- 状态: `IN_PROGRESS`
- 认领人: `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 根总览与最终审计

- 状态: `TODO`
- 认领人: `未认领`
- 优先级: `P2`
- 写入范围: `docs/api/XCEngine/XCEngine.md`、受影响的模块总览页、`docs/api/_meta/rebuild-status.md`
- 主要源码依据: 前面所有任务的完成结果
- 当前缺口: 根总览和模块总览需要在前面任务落地后统一收口；审计状态文件只能由一个会话最终更新
- 完成标准: 统一调整总览页导航；执行 `audit_api_docs.py`、覆盖校验与链接校验；写回新的 `rebuild-status.md`

## 备注

- 如果只有 `2-3` 个会话，优先拿 `T01`、`T05`、`T07`
- 如果有 `4-6` 个会话，推荐并行拿 `T01`、`T03`、`T04`、`T05`、`T06`、`T07`
- `T09` 必须最后做