XCEngine/docs/api-skill.md

# 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
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 文档任务只有同时满足下面条件才算完成：

- 对应源码、测试、调用链已经核对
- 文档页内容已经改到当前实现
- 过期页面和交叉链接已经清理
- 任务池记录已最小更新
- 审计脚本重新执行且结果全绿