docs: define api doc tree refactor phases

docs/api/XCEngine/Editor/Editor.md

@@ -69,6 +69,12 @@
 - 这套代码整体属于应用层源码，不应误解为已经整理成稳定插件 SDK。
 - 自动审计脚本目前主要覆盖 `engine/include/XCEngine/**` 的 public headers；Editor 这组文档更依赖目录并行约束、链接校验和人工核对源码行为。
 
+## 文档边界更新（2026-04-09）
+
+- `docs/api/XCEngine/Editor/**` 当前严格对应旧 `editor/src/**`。
+- `new_editor/include/XCEditor/**` 与 `new_editor/src/**` 已经形成新的 Editor 基础层主线，不再适合继续并入这棵旧树。
+- 后续会为 `XCEditor` 单独建立新的 API 文档根树，并把 `Collections / Fields / Foundation / Shell / Widgets` 迁到新结构下。
+
 ## 目录
 
 - [Application](Application/Application.md) - 顶层编辑器应用入口。

docs/plan/API文档目录重构计划_2026-04-09.md

@@ -0,0 +1,134 @@
+# API文档目录重构计划
+
+## 1. 背景
+
+当前 API 文档树已经出现明显的“双主线错位”：
+
+- `docs/api/XCEngine/Editor/**` 主要对应旧 `editor/src/**` 的 ImGui 编辑器应用层。
+- `new_editor/include/XCEditor/**` 与 `new_editor/src/**` 已经形成新的 Editor 基础层主线，但几乎没有进入当前 canonical API 树。
+- 现有审计脚本只覆盖 `engine/include/XCEngine/**` 与 `editor/src/**`，没有覆盖 `new_editor/include/XCEditor/**`。
+
+这意味着继续只在 `docs/api/XCEngine/Editor/**` 上增量修补，会越来越偏离真实代码结构。
+
+## 2. 当前判断
+
+### 2.1 旧 `Editor` 文档树继续保留，但必须收紧边界
+
+- `docs/api/XCEngine/Editor/**` 继续只文档化旧 `editor/src/**`。
+- 不再把它当成未来 Editor 主线 API 树。
+- 其中 `Application / EditorResources / Theme / XCUIBackend / panels / Viewport` 等内容，明确视为旧编辑器应用层。
+
+### 2.2 新主线应拆出独立文档树
+
+建议新增：
+
+- `docs/api/XCEditor/`
+
+首层目录直接镜像 `new_editor/include/XCEditor/**`：
+
+- `Collections`
+- `Fields`
+- `Foundation`
+- `Shell`
+- `Widgets`
+
+这样做的原因很直接：
+
+- 与真实 include 路径一致，后续自动审计最容易做。
+- 不会把新主线继续混进旧 `XCEngine/Editor` 树里。
+- 可以允许页面里的命名空间继续写真实值 `XCEngine::UI::Editor` / `XCEngine::UI::Editor::Widgets`，而目录只负责和头文件路径对齐。
+
+### 2.3 新旧两棵树的职责应明确分开
+
+- `docs/api/XCEngine/Editor/**`
+  - 旧编辑器应用层、宿主层、过渡层、当前产品参考实现。
+- `docs/api/XCEditor/**`
+  - `new_editor` 的新 Editor 基础层与宿主骨架。
+
+## 3. 已确认的结构漂移
+
+### 3.1 文档树覆盖不到 `new_editor/include/XCEditor`
+
+当前新主线 public headers 已经至少包含：
+
+- `XCEditor/Collections/*`
+- `XCEditor/Fields/*`
+- `XCEditor/Foundation/*`
+- `XCEditor/Shell/*`
+- `XCEditor/Widgets/*`
+
+但 `docs/api` 里没有对应的 `XCEditor` 根树。
+
+### 3.2 旧树中仍混有已经过时的过渡页
+
+当前至少已经发现：
+
+- `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md`
+  - 仍引用已不存在的 `editor/src/panels/XCUIDemoPanel.h`
+
+这类页面需要单独清理，不能继续假设旧源码路径仍成立。
+
+### 3.3 审计工具口径落后
+
+当前 `docs/api/_tools/audit_api_docs.py` 的覆盖口径没有把：
+
+- `new_editor/include/XCEditor/**/*.h`
+
+纳入 canonical 统计，所以即使新主线完全缺文档，审计也不会报警。
+
+## 4. 分阶段执行
+
+## Phase A：收紧旧树边界
+
+- 在 `docs/api/XCEngine/Editor/Editor.md` 明确“这里只对应旧 `editor/src/**`”。
+- 修掉旧树里已经失效的 source refs。
+- 继续补齐旧 `editor/src/**` 当前缺失的 canonical 页，避免现有审计长期失真。
+
+## Phase B：建立 `XCEditor` 新根树
+
+- 新建 `docs/api/XCEditor/XCEditor.md`
+- 新建 5 个首层 overview：
+  - `Collections`
+  - `Fields`
+  - `Foundation`
+  - `Shell`
+  - `Widgets`
+- 建立 `docs/api/main.md` 到新根树的入口链接
+
+## Phase C：接入新审计口径
+
+- 扩展审计脚本识别 `new_editor/include/XCEditor/**/*.h`
+- 统计 `docs/api/XCEditor/**` 的 canonical 覆盖率
+- 区分：
+  - 旧 `editor/src/**` 应用层源码页
+  - 新 `XCEditor/**` public header 页
+
+## Phase D：按新主线分批补页
+
+推荐顺序：
+
+1. `Foundation`
+2. `Widgets`
+3. `Collections`
+4. `Fields`
+5. `Shell`
+
+原因：
+
+- `Foundation` 与 `Widgets` 是多数页面的前置语义。
+- `Collections` / `Fields` 数量多，但结构相对规整，适合并行。
+- `Shell` 依赖最多，最好放后面统一写。
+
+## Phase E：旧树去历史包袱
+
+- 删除或改写已经脱离旧源码的过渡页
+- 把“旧 editor 参考实现”和“new_editor 正式主线”在相关 overview 中互相链接，但不再混放
+- 避免后续继续把 `new_editor` 内容塞进 `docs/api/XCEngine/Editor/**`
+
+## 5. 本轮执行口径
+
+本轮先按两条线同时推进：
+
+1. 先把现有审计缺口补齐，保证旧树不继续烂下去。
+2. 同时开始落 `XCEditor` 文档树重构计划和入口边界说明，为下一轮结构迁移做准备。
+