xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): sync active and archived API entry docs

Browse Source
This commit is contained in:
ssdfasd
2026-04-10 17:27:29 +08:00
parent e2e4e08479
commit 46fac8a215
6 changed files with 109 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
AGENT.md
View File

@@ -20,9 +20,11 @@
- [docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md)
- [docs/plan/Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md)
- [docs/plan/Editor架构说明.md](docs/plan/Editor架构说明.md)
- [docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md](docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md)
- [docs/plan/Unity风格模型导入与Model资产架构重构计划_2026-04-10.md](docs/plan/Unity风格模型导入与Model资产架构重构计划_2026-04-10.md)
- [docs/plan/NanoVDB体积云加载阻塞与Runtime上传修复计划_2026-04-10.md](docs/plan/NanoVDB体积云加载阻塞与Runtime上传修复计划_2026-04-10.md)
- [docs/plan/3DGS专用PLY导入器与GaussianSplat资源缓存正式化计划_2026-04-10.md](docs/plan/3DGS专用PLY导入器与GaussianSplat资源缓存正式化计划_2026-04-10.md)
- [docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md](docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md)
- [docs/plan/XCUI完整架构设计与执行计划.md](docs/plan/XCUI完整架构设计与执行计划.md)
- [docs/plan/XCUI_Phase_Status_2026-04-05.md](docs/plan/XCUI_Phase_Status_2026-04-05.md)
- [docs/plan/C#脚本模块下一阶段计划.md](docs/plan/C%23脚本模块下一阶段计划.md)
- [tests/TEST_SPEC.md](tests/TEST_SPEC.md)
- [tests/UI/TEST_SPEC.md](tests/UI/TEST_SPEC.md)
@@ -30,22 +32,35 @@
已归档但当前仍常用的背景文档：
- [Library资产导入与缓存系统收口计划（归档）](docs/used/Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md)
- [API 文档第三轮任务池（归档基线）](docs/used/API文档实时同步任务池_2026-04-03.md)
- [XCUI Phase Status 2026-04-05（归档）](docs/used/XCUI_Phase_Status_2026-04-05.md)
- [Shader与Material系统下一阶段计划（归档）](docs/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md)
- [Unity 风格 Shader 体系正式化计划（归档）](docs/used/Renderer下一阶段_Unity风格Shader体系正式化计划_完成归档_2026-04-07.md)
- [Renderer 当前阶段正式收口（阶段归档）](docs/used/Renderer当前阶段正式收口计划_阶段归档_2026-04-10.md)
- [NanoVDB 后续正式化（阶段归档）](docs/used/NanoVDB稀疏体积渲染后续正式化计划_阶段归档_2026-04-10.md)
- [SceneViewport Overlay / Gizmo 重构计划（归档）](docs/used/SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md)
- [Unity式 SceneView Gizmo 正式化方案（归档）](docs/used/Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md)
- [NanoVDB 第一阶段完成归档](docs/used/NanoVDB稀疏体积渲染正式集成计划_第一阶段完成归档_2026-04-09.md)
如果任务落在 API 文档：
1. 先检查 `docs/plan/` 下有没有日期更晚的 API 相关计划或归档；当前活跃任务池是 [docs/plan/API文档实时同步任务池_2026-04-03.md](docs/plan/API文档实时同步任务池_2026-04-03.md)。这份任务池目前已经推进到第三轮 `T01-T20` 全部完成，结构审计保持全绿，但开始新一轮前仍要先确认是否又追加了新任务块。
2. 再看 [docs/api-skill.md](docs/api-skill.md)。
3. 再看 `docs/api/_meta/rebuild-status.md`。
4. 一次只认领一个任务块，先改状态为 `DOING`，只写自己任务块允许的范围。
1. 先检查 `docs/plan/` 下最新的 API 相关计划或并行任务板。当前工作树里已经存在多份 2026-04-09 的活跃文件，例如：
- [docs/plan/API文档目录重构计划_2026-04-09.md](docs/plan/API文档目录重构计划_2026-04-09.md)
- [docs/plan/API文档目录结构重大重构并行任务板_2026-04-09.md](docs/plan/API文档目录结构重大重构并行任务板_2026-04-09.md)
- [docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md](docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md)
- [docs/plan/API文档目录结构第二轮并行任务板_2026-04-09.md](docs/plan/API文档目录结构第二轮并行任务板_2026-04-09.md)
- [docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md](docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md)
2. 如果这些活跃文件都不覆盖当前问题，再回看 [docs/used/API文档实时同步任务池_2026-04-03.md](docs/used/API文档实时同步任务池_2026-04-03.md) 作为最近一轮完成基线。
3. 再看 [docs/api-skill.md](docs/api-skill.md)。
4. 再看 `docs/api/_meta/rebuild-status.md`。
5. 一次只认领一个任务块，先改状态为 `DOING`，只写自己任务块允许的范围。
## 2. 当前工程事实
- 顶层 `CMakeLists.txt` 当前纳入 `engine/`、`editor/`、`new_editor/`、`managed/`、`mvs/RenderDoc/` 和 `tests/`。
- `engine/` 构建静态库 `XCEngine`；`editor/` 构建 `XCEditor`，但输出文件名仍是 `editor/bin/<Config>/XCEngine.exe`。
- `new_editor/` 当前构建 `XCUIEditorLib`、`XCUIEditorHost`；启用 `XCENGINE_BUILD_XCUI_EDITOR_APP` 时会输出 `new_editor/bin/<Config>/XCUIEditor.exe`。
- `editor/` 目前继续保留为当前正式编辑器、行为对照和视觉基线来源。
- `new_editor/` 当前构建 `XCUIEditorLib`、`XCUIEditorHost`；启用 `XCENGINE_BUILD_XCUI_EDITOR_APP` 时会输出 `new_editor/bin/<Config>/XCUIEditor.exe`，并被视为未来正式编辑器主线，而不再只是临时 sandbox。
- editor 默认把仓库内的 `project/` 识别为工程根目录，也支持 `--project <path>` 覆盖。
- 当前工程真实使用 `Assets/ + .meta + Library/` 的项目布局；`project/Library/` 是当前 workflow 的一部分，不是可随手忽略的垃圾目录。
- Mono 运行时与 editor 的脚本类发现都从 `<project>/Library/ScriptAssemblies/` 加载程序集。
@@ -81,8 +96,13 @@
- `ObjectId` 渲染与 editor picking
- `BuiltinInfiniteGridPass`
- `BuiltinObjectIdOutlinePass`
- `directional shadow`
- `skybox`
- `CameraRenderRequest::postScenePasses`
- `CameraRenderRequest::overlayPasses`
- `post-process / final color` 当前处于正式化收口阶段，不再是纯预留接口。
- `NanoVDB` 体积渲染已进入当前正式运行链路，但 Vulkan / OpenGL 的 rollout 和多后端能力边界仍在继续收口。
- 当前资源与导入主线正在继续向 `Model` 资产架构与 `3DGS GaussianSplat` 资源链扩展，不要再把 `.obj/.fbx/.ply` 简化理解为“文件直读后立刻渲染”的旧 sample 流程。
- 当前主线不是 render graph，而是 shader / material contract、builtin pass contract 和 renderer-owned feature contract。
### 3.3 Editor
@@ -126,13 +146,13 @@
### 3.4 XCUI / New Editor
- `new_editor/` 是当前 `XCUI` editor sandbox 主线；旧 `editor/` 的整体替换仍处于延后状态，不要把 `XCUI` 计划误读成“已经整体替换现有 editor”。
- `new_editor/` 是未来正式编辑器主线，不再只是 sandbox；旧 `editor/` 当前继续保留为正式编辑器、行为对照和视觉基线。
- 当前宿主分层是：
- `XCUIEditorLib`
- `XCUIEditorHost`
- `XCUIEditorApp`（可选应用壳）
- 共享 UI core、runtime screen host 与 widget 基础能力主要沉淀在 `engine/include/XCEngine/UI/` 与 `engine/src/UI/`；`new_editor/` 负责 XCUI editor 壳、宿主与 widget sandbox。
- XCUI / new_editor 的测试规范以 [tests/UI/TEST_SPEC.md](tests/UI/TEST_SPEC.md) 为准；根目录虽然有 `tests/NewEditor/`，但当前具体测试实现主要放在 `tests/UI/` 下。
- 共享 UI core、runtime screen host 与 widget 基础能力主要沉淀在 `engine/include/XCEngine/UI/` 与 `engine/src/UI/`；`new_editor/` 负责 XCUI editor 壳、宿主与产品装配。
- `tests/UI/` 是当前 XCUI `Core / Editor / Runtime` 三层的唯一正式基础层验证入口；`new_editor/` 不承担测试堆场职责。
### 3.5 Scripting
@@ -262,15 +282,21 @@
只要任务涉及 `docs/api/`：
1. 先检查 `docs/plan/` 下有没有更新日期更晚的 API 计划或归档。
2. 以最新任务池和 [docs/api-skill.md](docs/api-skill.md) 为执行规范。
3. 改完必须重新执行：
1. 先读 `docs/plan/API文档目录*.md` 里日期最新的 API 计划 / 并行任务板。
2. 再看 [docs/api-skill.md](docs/api-skill.md) 和 `docs/api/_meta/rebuild-status.md`。
3. 如果活跃计划没有覆盖当前问题，再回看 [docs/used/API文档实时同步任务池_2026-04-03.md](docs/used/API文档实时同步任务池_2026-04-03.md) 作为最近一轮归档基线。
4. 改完必须重新执行：
```powershell
python -B docs/api/_tools/audit_api_docs.py
```
如果审计没回绿，不算完成。
当前审计口径已经同时覆盖：
- `engine/include/XCEngine/**`
- `new_editor/include/XCEditor/**`
- `editor/src/**`
## 5. 推荐构建与验证入口
@@ -321,9 +347,10 @@ ctest --test-dir build -C Debug --output-on-failure
- 资源导入与工程布局：`engine/include/XCEngine/Core/Asset/`、`engine/src/Core/Asset/`、`editor/src/Managers/ProjectManager.cpp`、`project/Assets/`、`project/Library/`
- Material / shader / artifact：`engine/include/XCEngine/Resources/Material/`、`engine/src/Resources/Material/`、`engine/include/XCEngine/Core/Asset/ArtifactFormats.h`、`tests/Resources/Material/`
- Editor viewport / gizmo / picking：`editor/src/Viewport/`、`editor/src/panels/SceneViewPanel.cpp`、`tests/Editor/`
- XCUI / new_editor：`engine/include/XCEngine/UI/`、`engine/src/UI/`、`new_editor/include/XCEditor/`、`new_editor/src/`、`tests/UI/`
- Editor actions / project routing：`editor/src/Actions/`、`editor/src/Commands/`、`editor/src/Core/`、`editor/src/Managers/`、`tests/Editor/test_action_routing.cpp`
- 脚本运行时与程序集：`engine/include/XCEngine/Scripting/`、`engine/src/Scripting/`、`managed/`、`project/Assets/Scripts/`、`tests/Scripting/`
- API 文档：`docs/api/XCEngine/`、`docs/api/_guides/`、`docs/api/_tools/audit_api_docs.py`、`docs/plan/API文档实时同步任务池_2026-04-03.md`
- API 文档：`docs/api/main.md`、`docs/api/XCEngine/`、`docs/api/XCEditor/`、`docs/api/_guides/`、`docs/api/_tools/audit_api_docs.py`、`docs/plan/API文档目录*.md`、`docs/used/API文档实时同步任务池_2026-04-03.md`
## 7. 适合当前仓库的工作方式