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 模块内容重构

• 状态: TODO
• 认领人: 未认领
• 优先级: 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 必须最后做