XCEngine/docs/api-skill.md

XCEngine API Documentation Skill

目标

这份规范面向维护 XCEngine API 文档的 coding agent。它的目标不是“批量生成一套看起来完整的文档”，而是持续把当前源码、测试和真实调用链路同步到唯一的 canonical API 文档树里。

当前仓库已经进入“增量同步”阶段。重点不再是补骨架，而是：

• 跟住最新 public header 和 Editor source header 的真实变化
• 清理过期 API 页面和过期叙述
• 保持 overview / guide / method page 的口径一致

当前范围

API 文档的正式范围包含两部分：

1. 引擎 public API
   • 对齐 engine/include/XCEngine/**
2. Editor source-backed API
   • 对齐 editor/src/**
   • canonical 文档入口仍放在 docs/api/XCEngine/Editor/**

辅助目录也属于工作流的一部分：

• docs/api/_guides/**
  • 教程、架构说明、工作流说明
• docs/api/_meta/**
  • 审计结果、阶段性状态
• docs/api/_tools/**
  • 审计、生成、修链脚本
• docs/plan/API文档实时同步任务池_2026-04-03.md
  • 当前多任务并行同步池
• README.md / editor/README.md / AGENT.md
  • 这些不是 canonical API 页，但一旦它们引用 API 模块结构、测试目录或 Editor helper 分层，就属于必须同步的活跃协作文档

硬约束

1. docs/api/XCEngine/** 是唯一 canonical API 树。
2. 文档必须以“当前 header + 当前实现 + 当前测试 + 当前真实调用点”为依据，不能按旧文档或命名猜行为。
3. 删除的 API 页面要一起删除，相关交叉链接也必须一起清理。
4. 方法页优先使用源码中的原始函数名；不要擅自改成 kebab-case 或小写别名。
5. 不要把“设计意图”写成“当前实现行为”。
6. 不要为已经删除的 API 保留默认兼容入口页，除非任务明确要求。
7. rebuild-status.md 以审计脚本输出为准；并发场景下，stdout 比旧文件内容更可信。
8. 只收口活跃文档；docs/plan/used/**、docs/used/** 等归档材料默认保留历史写法，不要为了“顺手统一”去重写归档。
9. Windows 工作树里的路径大小写按真实目录名写，例如 tests/Editor/、tests/Core/、tests/Scripting/，不要继续传播 tests/editor/、tests/core/ 之类的历史噪音。

工作流

1. 开工前先看两份文件

• 任务池：
  • docs/plan/API文档实时同步任务池_2026-04-03.md
• 最新审计：
  • docs/api/_meta/rebuild-status.md

如果任务池和工作树不一致，以当前源码和重新执行审计后的结果为准。

如果 docs/plan/ 下出现日期更晚的 API 相关计划或归档文件，优先读取更新日期更晚的文件，再判断当前任务池是否已经转入 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. 改完后的收口

必须重新执行：

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/XCEngine/{ModuleName}/{ModuleName}.md
• 子模块页：
  • docs/api/XCEngine/{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

2. Header / source-backed 目录

当前不是“每个类型再套一层目录”，而是：

• 每个 public header 或 Editor source header 对应一个文档目录
• 该目录内放主类型页、辅助类型页和方法页

示例：

docs/api/XCEngine/Core/Asset/ResourceManager/
├── ResourceManager.md
├── Load.md
├── LoadAsync.md
├── RefreshProjectAssets.md
├── RebuildProjectAssetCache.md
└── GetProjectLibraryRoot.md

多类型 / helper 同头文件示例：

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 上真实已有新测试，但类型页还在写“没有独立单元测试”

推荐命令

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

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