362 lines
11 KiB
Markdown
362 lines
11 KiB
Markdown
# XCEngine / XCEditor API Documentation Skill
|
||
|
||
|
||
## 目标
|
||
|
||
这份规范面向维护 `XCEngine` / `XCEditor` API 文档的 coding agent。它的目标不是“批量生成一套看起来完整的文档”，而是持续把当前源码、测试和真实调用链路同步到当前活跃的 canonical API 文档树里。
|
||
|
||
当前仓库已经进入“增量同步”阶段。重点不再是补骨架，而是：
|
||
|
||
- 跟住最新 public header 和 Editor source header 的真实变化
|
||
- 清理过期 API 页面和过期叙述
|
||
- 保持 overview / guide / method page 的口径一致
|
||
|
||
## 当前范围
|
||
|
||
API 文档的正式范围包含三部分：
|
||
|
||
1. 引擎 public API
|
||
- 对齐 `engine/include/XCEngine/**`
|
||
2. 新 Editor public API
|
||
- 对齐 `new_editor/include/XCEditor/**`
|
||
- canonical 文档入口放在 `docs/api/XCEditor/**`
|
||
3. Editor source-backed API
|
||
- 对齐 `editor/src/**`
|
||
- canonical 文档入口仍放在 `docs/api/XCEngine/Editor/**`
|
||
|
||
辅助目录也属于工作流的一部分：
|
||
|
||
- `docs/api/_guides/**`
|
||
- 教程、架构说明、工作流说明
|
||
- `docs/api/_meta/**`
|
||
- 审计结果、阶段性状态
|
||
- `docs/api/_tools/**`
|
||
- 审计、生成、修链脚本
|
||
- `docs/plan/API文档目录*.md`
|
||
- 当前活跃 API 计划、重构计划与并行任务板
|
||
- `docs/plan/API文档目录结构阶段进度_XCEditor与Model收口_2026-04-10.md`
|
||
- 最近一轮 `XCEditor / Model / GaussianSplat` 收口记录
|
||
- `docs/used/API文档实时同步任务池_2026-04-03.md`
|
||
- 最近一轮已完成的归档基线
|
||
- `README.md` / `editor/README.md` / `AGENT.md`
|
||
- 这些不是 canonical API 页，但一旦它们引用 API 模块结构、测试目录或 Editor helper 分层，就属于必须同步的活跃协作文档
|
||
|
||
## 硬约束
|
||
|
||
1. `docs/api/XCEngine/**` 与 `docs/api/XCEditor/**` 是当前两棵 canonical API 树；`docs/api/XCEngine/Editor/**` 继续承载 `editor/src/**` 的 source-backed 文档入口。
|
||
2. 文档必须以“当前 header + 当前实现 + 当前测试 + 当前真实调用点”为依据，不能按旧文档或命名猜行为。
|
||
3. 删除的 API 页面要一起删除，相关交叉链接也必须一起清理。
|
||
4. 方法页优先使用源码中的原始函数名；不要擅自改成 kebab-case 或小写别名。
|
||
5. 不要把“设计意图”写成“当前实现行为”。
|
||
6. 不要为已经删除的 API 保留默认兼容入口页，除非任务明确要求。
|
||
7. `rebuild-status.md` 以审计脚本输出为准；并发场景下，stdout 比旧文件内容更可信。
|
||
8. 默认先收口活跃文档；只有当任务明确涉及归档链、入口路径或历史基线说明时，才修改 `docs/used/**`。
|
||
9. Windows 工作树里的路径大小写按真实目录名写，例如 `tests/Editor/`、`tests/Core/`、`tests/Scripting/`，不要继续传播 `tests/editor/`、`tests/core/` 之类的历史噪音。
|
||
|
||
## 工作流
|
||
|
||
### 1. 开工前先看两类文件
|
||
|
||
- 最新活跃计划：
|
||
- `docs/plan/API文档目录*.md`
|
||
- `docs/plan/API文档目录结构阶段进度_XCEditor与Model收口_2026-04-10.md`
|
||
- 最新审计：
|
||
- `docs/api/_meta/rebuild-status.md`
|
||
|
||
如果活跃计划和工作树不一致，以当前源码和重新执行审计后的结果为准。
|
||
|
||
如果当前活跃计划没有覆盖你的问题，再回看：
|
||
|
||
- `docs/used/API文档实时同步任务池_2026-04-03.md`
|
||
|
||
作为最近一轮完成归档的基线。
|
||
|
||
如果 `docs/plan/` 下出现日期更晚的 API 相关计划，优先读取日期更晚的活跃文件；当前仓库里的归档根目录是 `docs/used/**`，不要再假设存在 `docs/plan/used/**`。
|
||
|
||
如果工作内容会改到 `README.md`、`editor/README.md` 或 `AGENT.md`：
|
||
|
||
- 先对照真实工作树、`Get-ChildItem` 输出和当前测试目录
|
||
- 再改目录树与模块说明
|
||
- 不要沿用旧摘要、旧计划里的目录快照
|
||
|
||
### 2. 认领规则
|
||
|
||
- 一次只认领一个任务块。
|
||
- 先把任务状态改成 `DOING`，再写认领人。
|
||
- 只修改该任务块的写入范围。
|
||
- 如果发现新的失配，但不属于当前任务块，向任务池追加新任务，不顺手扩写。
|
||
|
||
### 3. 写文档前的取证
|
||
|
||
至少完成下面四步：
|
||
|
||
1. 读对应 header
|
||
2. 读对应 `.cpp` 或内联实现
|
||
3. 搜测试和真实调用点
|
||
4. 确认生命周期、线程语义、失败路径、所有权、平台限制
|
||
|
||
如果是 Editor source-backed API，至少额外确认两类锚点：
|
||
|
||
1. `tests/Editor/` 下是否已有对应单测
|
||
2. `SceneViewPanel.cpp`、`ViewportHostService.*` 或其他真实上层调用链是否已经切到新 helper
|
||
|
||
落文前至少能回答这些问题：
|
||
|
||
- 这个类型或函数解决什么问题，边界在哪里？
|
||
- 调用前需要什么前置条件？
|
||
- 失败时返回什么，或者会不会静默 no-op？
|
||
- 谁拥有对象，谁负责释放资源？
|
||
- 当前实现是完整能力、轻量封装、stub，还是占位入口？
|
||
|
||
### 4. 改完后的收口
|
||
|
||
必须重新执行：
|
||
|
||
```powershell
|
||
python -B docs/api/_tools/audit_api_docs.py
|
||
```
|
||
|
||
至少关注这些指标：
|
||
|
||
- `Invalid header refs`
|
||
- `Invalid source refs`
|
||
- `Broken .md links`
|
||
- `Old template pages`
|
||
- `Flat header pages`
|
||
- `Stale editor doc tokens`
|
||
- `Stale editor canonical pages`
|
||
|
||
如果审计没回绿，不算完成。
|
||
|
||
## Canonical 目录规则
|
||
|
||
### 1. 模块总览页
|
||
|
||
- 根入口：
|
||
- `docs/api/main.md`
|
||
- API 根页：
|
||
- `docs/api/XCEngine/XCEngine.md`
|
||
- `docs/api/XCEditor/XCEditor.md`
|
||
- 模块页：
|
||
- `docs/api/XCEngine/{ModuleName}/{ModuleName}.md`
|
||
- `docs/api/XCEditor/{ModuleName}/{ModuleName}.md`
|
||
- 子模块页：
|
||
- `docs/api/XCEngine/{ModuleName}/{SubmoduleName}/{SubmoduleName}.md`
|
||
- `docs/api/XCEditor/{ModuleName}/{SubmoduleName}/{SubmoduleName}.md`
|
||
|
||
示例：
|
||
|
||
- `docs/api/XCEngine/Core/Core.md`
|
||
- `docs/api/XCEngine/Core/Asset/Asset.md`
|
||
- `docs/api/XCEngine/Rendering/Passes/Passes.md`
|
||
- `docs/api/XCEngine/Editor/Viewport/Viewport.md`
|
||
- `docs/api/XCEditor/Foundation/Foundation.md`
|
||
- `docs/api/XCEditor/Shell/Shell.md`
|
||
|
||
### 2. Header / source-backed 目录
|
||
|
||
当前不是“每个类型再套一层目录”，而是：
|
||
|
||
- 每个 public header 或 Editor source header 对应一个文档目录
|
||
- 该目录内放主类型页、辅助类型页和方法页
|
||
|
||
示例：
|
||
|
||
```text
|
||
docs/api/XCEngine/Core/Asset/ResourceManager/
|
||
├── ResourceManager.md
|
||
├── Load.md
|
||
├── LoadAsync.md
|
||
├── RefreshProjectAssets.md
|
||
├── RebuildProjectAssetCache.md
|
||
└── GetProjectLibraryRoot.md
|
||
```
|
||
|
||
多类型 / helper 同头文件示例：
|
||
|
||
```text
|
||
docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/
|
||
├── SceneViewportRenderPlan.md
|
||
├── SceneViewportRenderPlanBuildResult.md
|
||
├── BuildSceneViewportRenderPlan.md
|
||
└── ApplySceneViewportRenderPlan.md
|
||
```
|
||
|
||
### 3. umbrella header 例外
|
||
|
||
如果一个 header 只是聚合入口，通常不单独建同名类型页，直接并入模块页：
|
||
|
||
- 文件主要由 `#include` 组成
|
||
- 不声明独立 class / struct / enum / function family
|
||
- 单独建页只会制造重复入口
|
||
|
||
## 命名规则
|
||
|
||
### 1. 主页面
|
||
|
||
- 主类型页通常用主类型名：
|
||
- `ResourceManager.md`
|
||
- `BuiltinInfiniteGridPass.md`
|
||
- helper 类型页直接用真实类型名：
|
||
- `ImportedAsset.md`
|
||
- `LookupSnapshot.md`
|
||
|
||
### 2. 方法页
|
||
|
||
- 用真实函数名：
|
||
- `Initialize.md`
|
||
- `TryResolveAssetPath.md`
|
||
- `BuildInfiniteGridParameters.md`
|
||
|
||
重载共享同一页，在页内按签名分节说明。
|
||
|
||
### 3. 特殊命名
|
||
|
||
- 构造函数：
|
||
- `Constructor.md`
|
||
- 析构函数：
|
||
- `Destructor.md`
|
||
- 运算符：
|
||
- `operator=` -> `OperatorAssign.md`
|
||
- `operator[]` -> `OperatorSubscript.md`
|
||
- `operator()` -> `OperatorCall.md`
|
||
|
||
## 页面职责
|
||
|
||
### 1. 模块页
|
||
|
||
必须说明：
|
||
|
||
- 模块职责
|
||
- 与相邻模块的边界
|
||
- 典型使用链路
|
||
- 关键入口页
|
||
|
||
不要在模块页里平铺所有方法细节。
|
||
|
||
### 2. 类型页
|
||
|
||
必须包含：
|
||
|
||
- 命名空间
|
||
- 类型分类
|
||
- `头文件` 或 `源文件`
|
||
- 角色概述
|
||
- 生命周期
|
||
- 线程语义
|
||
- 所有权 / 资源管理方式
|
||
- 当前实现限制
|
||
- 相关方法与相关 guide
|
||
|
||
如果是 `struct` / `enum`，还要写清字段或枚举值的实际语义。
|
||
|
||
### 3. 方法页
|
||
|
||
必须写清：
|
||
|
||
- 准确签名
|
||
- 调用目的
|
||
- 前置条件
|
||
- 当前实现行为
|
||
- 返回值
|
||
- 副作用
|
||
- 失败路径或 no-op 条件
|
||
- 线程语义
|
||
- 真实调用点或测试锚点
|
||
|
||
不能只写“获取对象”“设置状态”这种空描述。
|
||
|
||
## 写法规则
|
||
|
||
### 1. 区分三层信息
|
||
|
||
文档里要明确区分：
|
||
|
||
- 接口契约
|
||
- 来自 header，可被调用方依赖
|
||
- 当前实现行为
|
||
- 来自 `.cpp`、测试和调用链
|
||
- 合理推断
|
||
- 只有必要时才写，并明确标注是推断
|
||
|
||
推荐措辞：
|
||
|
||
- “当前实现中……”
|
||
- “按 `engine/src/...` 的实现……”
|
||
- “测试 `tests/...` 当前验证了……”
|
||
|
||
### 2. 优先写真实链路
|
||
|
||
如果一个 API 真正只是更大链路中的一环，要把链路写出来。
|
||
|
||
示例：
|
||
|
||
- `ResourceManager`
|
||
- 不只写“负责资源加载”
|
||
- 要写清 `AssetImportService -> ProjectAssetIndex -> loader` 的真实路径
|
||
- `SceneViewportRenderPlan`
|
||
- 不只写“构建后处理 plan”
|
||
- 要写清它如何给 Scene View 组装 `postScenePasses` / `overlayPasses`
|
||
|
||
### 3. 明确不成熟部分
|
||
|
||
对未完成能力要直接写明：
|
||
|
||
- 当前是 stub
|
||
- 当前只支持某个平台
|
||
- 当前只覆盖某条 backend 路径
|
||
- 当前仍要求调用方手动轮询或手动 shutdown
|
||
|
||
不要把不成熟接口包装成成熟系统。
|
||
|
||
## Guide / Overview 规则
|
||
|
||
`_guides` 不是第二套 API 参考，而是解释：
|
||
|
||
- 为什么这样组织模块
|
||
- 推荐从哪里开始读
|
||
- 典型工作流是什么
|
||
- 与 Unity / Unreal 等常见心智模型的关系
|
||
|
||
适合写 guide 的内容：
|
||
|
||
- 架构图景
|
||
- 推荐使用顺序
|
||
- 设计权衡
|
||
- 常见误区
|
||
|
||
不适合：
|
||
|
||
- 重复抄一遍类型页和方法页
|
||
- 延续已经过期的旧工作流
|
||
|
||
## 常见失误
|
||
|
||
- 按名字猜 API 行为，不看实现和测试
|
||
- 保留已经删除的 API 页面或链接
|
||
- overview 还在传播旧心智，但类型页已经改新了
|
||
- 把 helper / wrapper 当成独立大系统来写
|
||
- 把 Editor source-backed API 当成 public header 处理，漏掉 `源文件` 语义
|
||
- 审计没跑或没回绿就宣布完成
|
||
- README / AGENT / editor README 的目录树还停留在旧快照，和当前工作树脱节
|
||
- Windows 上真实已有新测试，但类型页还在写“没有独立单元测试”
|
||
|
||
## 推荐命令
|
||
|
||
```powershell
|
||
rg --files docs/api/XCEngine docs/api/XCEditor
|
||
rg --files tests/Editor
|
||
rg -n "SymbolName" engine/include engine/src editor/src tests docs/api
|
||
python -B docs/api/_tools/audit_api_docs.py
|
||
```
|
||
|
||
## 一个最小完成定义
|
||
|
||
一次 API 文档任务只有同时满足下面条件才算完成：
|
||
|
||
- 对应源码、测试、调用链已经核对
|
||
- 文档页内容已经改到当前实现
|
||
- 过期页面和交叉链接已经清理
|
||
- 任务池记录已最小更新
|
||
- 审计脚本重新执行且结果全绿
|