xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b7ce8618d2f027f199264f97b7c121ad616704bd
XCEngine/docs/plan/API文档目录结构重大重构并行任务板_2026-04-09.md

6.7 KiB
Raw Blame History

API 文档目录结构重大重构并行任务板（2026-04-09）

背景

项目近期经过了大规模重构，docs/api/XCEngine 当前 canonical 树已经和实际源码出现新的结构偏差。 本任务板用于给多会话 / 多代理并行协作时直接认领任务，避免重复劳动和目录冲突。

本轮结论来自两类事实源：

  • 源码目录对照：
    • engine/include/XCEngine
    • editor/src
    • new_editor/include/XCEditor
  • 文档审计：
    • python -B docs/api/_tools/audit_api_docs.py
    • 最新生成时间：2026-04-10 17:07:09

当前关键问题

当前审计状态

  • 当前 docs/api/XCEngine/** + docs/api/XCEditor/** + editor/src/** 范围内审计已经全绿：
    • Invalid header refs = 0
    • Invalid source refs = 0
    • Broken .md links = 0
    • Missing directory index pages = 0
  • 本轮补页已经覆盖：
    • VolumeRendererComponent
    • VisibleVolumeItem
    • BuiltinSelectionMaskPass
    • BuiltinSelectionOutlinePass
    • BuiltinVolumetricPass
    • Volume
    • VolumeField
    • VolumeFieldLoader
    • UIDragDropInteraction
    • UIScrollModel
    • VolumeRendererComponentEditor
    • MaterialInspectorMaterialState
    • MaterialInspectorMaterialStateIO
  • 新增 canonical 根树与资源子模块：
    • docs/api/XCEditor/**
    • XCEngine/Resources/Model/**
    • XCEngine/Resources/GaussianSplat/**
  • XCUIDemoPanel 已从 canonical API 树中移除；活跃 overview 只保留当前真实调用点和历史说明。

剩余结构问题

  • RHI、Rendering/Passes、Rendering/Materials 等高风险内容回归任务已经完成，当前审计维持全绿。
  • 历史空目录与重复目录的进一步清理仍待继续验证，这部分仍对应 S9。
  • 后续重点已经从“大面积补缺页”转成“任务板/入口状态同步 + 空目录收口 + 新增头文件增量同步”。

当前发现的可疑空目录

以下目录当前为空，优先视为历史迁移残留；删除前需要先 rg 检查是否仍有链接引用：

  • docs/api/XCEngine/Core/Core
  • docs/api/XCEngine/Core/Containers/Containers
  • docs/api/XCEngine/Debug/Debug
  • docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayRenderer
  • docs/api/XCEngine/Rendering/CameraRenderRequest/BuiltinPostProcessRequest
  • docs/api/XCEngine/Rendering/Passes/BuiltinPostProcessPassPlan
  • docs/api/XCEngine/Rendering/Passes/BuiltinPostProcessPassSequenceBuilder
  • docs/api/XCEngine/Resources/Shader/ShaderRenderState

说明：

  • docs/api/XCEngine/Components/VolumeRendererComponent
  • docs/api/XCEngine/Rendering/FrameData/VisibleVolumeItem
  • docs/api/XCEngine/Rendering/Passes/BuiltinSelectionMaskPass
  • docs/api/XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass
  • docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass
  • docs/api/XCEngine/Resources/Volume/VolumeField
  • docs/api/XCEngine/Resources/Volume/VolumeFieldLoader

这些空目录是本轮结构补齐时创建的目标目录，不属于历史残留，需要补页面而不是删除。

并行认领规则

  • 一个任务块只允许一个会话认领。
  • 每个任务块必须同时处理：
    • 主页面
    • 所在模块索引页
    • 相关交叉链接
  • 删除任何目录或页面前，先执行：
    • rg -n "<名称>" docs/api/XCEngine docs/api/_guides
  • 每个任务块完成后都要执行：
    • python -B docs/api/_tools/audit_api_docs.py

任务块

ID 范围 目标改动 主要路径 状态 认领人
S1 Resources / Volume 新建 Volume.md、VolumeField.md、VolumeFieldLoader.md，并更新 Resources.md docs/api/XCEngine/Resources/Volume/** completed 当前会话
S2 Components / Volume 新建 VolumeRendererComponent.md，并更新 Components.md docs/api/XCEngine/Components/VolumeRendererComponent/** completed 当前会话
S3 Rendering / Volume FrameData 新建 VisibleVolumeItem.md，并更新 FrameData.md docs/api/XCEngine/Rendering/FrameData/** completed 当前会话
S4 Rendering / Volume & Selection Passes 新建 BuiltinSelectionMaskPass.md、BuiltinSelectionOutlinePass.md、BuiltinVolumetricPass.md，并更新 Passes.md docs/api/XCEngine/Rendering/Passes/** completed 当前会话
S5 UI / Widgets Helpers 新建 UIDragDropInteraction.md、UIScrollModel.md，并更新 Widgets.md docs/api/XCEngine/UI/Widgets/** completed 当前会话
S6 Editor / ComponentEditors 新建 VolumeRendererComponentEditor.md，并更新 ComponentEditors.md docs/api/XCEngine/Editor/ComponentEditors/** completed 当前会话
S7 Editor / panels Material Authoring 新建 MaterialInspectorMaterialState.md、MaterialInspectorMaterialStateIO.md，并更新 panels.md docs/api/XCEngine/Editor/panels/** completed 当前会话
S8 Editor 旧页清理 删除 XCUIDemoPanel 旧页与空目录，修正所有反向链接 docs/api/XCEngine/Editor/panels/XCUIDemoPanel/** completed 当前会话
S9 Canonical 空目录清理 清理历史空目录并验证无死链 见“可疑空目录”列表 pending
S10 全量回归 运行审计，更新状态，补最后的索引 / 链接 / 空目录问题 docs/api/_meta/rebuild-status.md completed 当前会话

各任务块的最低验收标准

S1 - S7

  • 目录结构与源码平行。
  • 每个类型都是“一个文件夹 + 一个同名主页面”。
  • 页面必须基于当前源码和测试写内容，不能凭旧文档照搬。
  • 必须同步更新所属模块总览页中的目录列表 / 页面列表。

S8

  • XCUIDemoPanel 页面与目录从 canonical 树中移除。
  • 所有指向它的链接都替换为当前真实调用点描述，或者直接删除。
  • 审计中的 Invalid source refs 归零。

S9

  • 只清理已经确认无源码对应、且无链接引用的目录。
  • 不能误删本轮待补页面目录。

S10

  • Invalid header refs = 0
  • Invalid source refs = 0
  • Broken .md links = 0
  • Missing directory index pages = 0
  • 缺页计数进一步下降，最好清零

推荐执行顺序

  1. S8
  2. S1
  3. S2
  4. S3
  5. S4
  6. S5
  7. S6
  8. S7
  9. S9
  10. S10

备注

  • 当前阶段已经从“补缺页”转为“空目录清理 + 入口状态同步 + 增量回归维护”。
  • 下一轮优先收口：
    • S9 对应的历史空目录清理
    • docs/api/_meta/rebuild-status.md 的例行审计回写
    • 后续新增或继续波动的高风险源码路径增量同步：
      • engine/include/XCEngine/RHI/**
      • engine/include/XCEngine/Rendering/Passes/**
      • new_editor/include/XCEditor/**
Reference in New Issue View Git Blame Copy Permalink