155 lines
6.5 KiB
Markdown
155 lines
6.5 KiB
Markdown
|
# 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 只保留当前真实调用点和历史说明。
|
|||
|
|
|
|||
|
|
### 剩余结构问题
|
|||
|
|
|
|||
|
|
- `AGENT.md`、`docs/api-skill.md` 与 `docs/used/**` 的 active/archive 入口口径仍需同步到新根树与新任务板。
|
|||
|
|
- `RHI`、`Rendering/Passes`、`Rendering/Materials` 等高风险内容回归任务仍未收口。
|
|||
|
|
- 历史空目录与重复目录的进一步清理仍待继续验证。
|
|||
|
|
|
|||
|
|
### 当前发现的可疑空目录
|
|||
|
|
|
|||
|
|
以下目录当前为空，优先视为历史迁移残留；删除前需要先 `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`
|
|||
|
|
|
|||
|
|
## 备注
|
|||
|
|
|
|||
|
|
- 当前阶段已经从“补缺页”转为“入口口径同步 + 高风险内容回归”。
|
|||
|
|
- 下一轮优先收口：
|
|||
|
|
- `AGENT.md`
|
|||
|
|
- `docs/api-skill.md`
|
|||
|
|
- `docs/used/API文档实时同步任务池_2026-04-03*.md`
|
|||
|
|
- `docs/api/XCEngine/RHI/**`
|
|||
|
|
- `docs/api/XCEngine/Rendering/**`
|