docs: 重写 api-skill.md，完善文档规范与生成流程

2026-03-19 12:41:53 +08:00
parent 5257f3d75c
commit 7e1782e203
1 changed files with 450 additions and 0 deletions
--- a/docs/api-skill.md
+++ b/docs/api-skill.md
@@ -0,0 +1,450 @@
+# XCEngine API 文档编写与校验 Skill
+
+## 用途
+
+根据 XCEngine C++ 引擎源码生成符合规范的 API 文档，并进行格式校验和查漏补缺。
+
+在开始编写任何文档之前，必须先完整阅读并深刻理解对应的源码上下文——包括设计目的、
+实现细节、边界条件、线程安全约定、与其他模块的依赖关系等。切忌在未读懂源码的情况下
+仅凭方法签名或猜测来编写文档。
+
+---
+
+## 文档目录结构
+
+```
+docs/api/
+├── main.md                     # 总索引
+├── {module}/
+│   ├── {module}.md            # 模块总览页
+│   ├── {class}/
+│   │   ├── {class}.md         # 类/结构体/枚举总览页
+│   │   ├── {method}.md        # 方法详情页
+│   │   └── ...
+│   └── ...
+└── ...
+```
+
+**命名规则：**
+
+- 模块总览：`{module}/{module}.md`（如 `threading/threading.md`）
+- 类/结构体文件夹：`{class-name}/`（小写，如 `task-group/`）
+- 类总览页：`{class-name}/{class-name}.md`
+- 方法详情页：`{class-name}/{method-name}.md`
+- 构造函数/析构函数：`constructor.md`、`destructor.md`、`~typename.md`
+- 运算符重载：`operator-assign.md`、`operator-plus.md`、`operator-subscript.md`
+- 枚举详情页（单独文件夹时）：`{enum-name}/{enum-name}.md`
+
+---
+
+## 页面类型与模板
+
+### 1. 模块总览页
+
+```markdown
+# {ModuleName} 模块概览
+
+**命名空间**: `{namespace}`
+
+**类型**: `module`
+
+**描述**: {模块一句话描述}
+
+## 概述
+
+{模块功能详细介绍}
+
+## 模块内容
+
+### {子分类名}
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [{ComponentName}](component/component.md) | `{Header.h}` | {描述} |
+...
+
+## {可选：对标/对比表格}
+
+| 选项 | 适用场景 | 特点 |
+|------|----------|------|
+| `Foo` | 场景A | 特点X |
+
+## 使用示例
+
+```cpp
+{完整可运行代码}
+```
+
+## 相关文档
+
+- [{DocName}](../{module}/{doc}.md) - {描述}
+```
+
+### 2. 类总览页
+
+```markdown
+# {ClassName}
+
+**命名空间**: `{namespace}`
+
+**类型**: `class` / `class (abstract)` / `class (singleton)`
+
+**头文件**: `XCEngine/Path/Header.h`
+
+**描述**: {一句话功能描述}
+
+## 概述
+
+{类的详细介绍}
+
+## {可选章节}
+
+### 类型别名
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `SizeType` | `size_t` | 大小类型 |
+
+### 常量
+
+| 常量 | 值 | 描述 |
+|------|-----|------|
+| `static constexpr SizeType npos` | `-1` | 无效位置标识 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [{MethodName}](method-name.md) | {描述} |
+| `virtual ~ClassName()` | 虚析构函数 |
+
+## 受保护方法（如有）
+
+| 方法 | 描述 |
+|------|------|
+| `ClassName()` | 默认构造函数 |
+
+## 使用示例
+
+```cpp
+{完整可运行代码}
+```
+
+## 相关文档
+
+- [{RelatedClass}](../module/class.md) - {描述}
+```
+
+### 3. Struct 总览页
+
+```markdown
+# {StructName}
+
+**命名空间**: `{namespace}`
+
+**类型**: `struct`
+
+**头文件**: `XCEngine/Path/Header.h`
+
+**描述**: {一句话功能描述}
+
+## 结构体成员
+
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| [{memberName}](membername.md) | `type` | {描述} | {默认值} |
+
+## 使用示例
+
+```cpp
+{完整可运行代码}
+```
+
+## 相关文档
+
+- [{RelatedDoc}](../module/doc.md) - {描述}
+```
+
+### 4. Enum 总览页
+
+```markdown
+# {EnumName}
+
+**命名空间**: `{namespace}`
+
+**类型**: `enum class`
+
+**头文件**: `XCEngine/Path/Header.h`
+
+## 概述
+
+{枚举用途描述}
+
+## 枚举值
+
+| 枚举值 | 数值 | 描述 |
+|--------|------|------|
+| `ValueName` | {N} | {描述} |
+...
+
+## 使用示例
+
+```cpp
+{完整可运行代码}
+```
+
+## 相关文档
+
+- [{RelatedDoc}](../module/doc.md) - {描述}
+```
+
+### 5. 方法详情页（单重载）
+
+```markdown
+# {ClassName}::{MethodName}
+
+{一句话描述方法功能}
+
+```cpp
+{完整方法签名}
+```
+
+{详细描述，包括设计目的和使用场景}
+
+**参数：**
+- `paramName` - {参数描述}
+
+**返回：** {返回值类型} - {返回值含义}
+
+**线程安全：** ✅ / ❌ {可选说明}
+
+**复杂度：** O(n) {可选}
+
+**注意：** {可选，重要警告或注意事项}
+
+**示例：**
+
+```cpp
+{完整可运行代码}
+```
+
+## 相关文档
+
+- [{ClassName} 总览](class-name.md)
+- [{RelatedMethod}](related-method.md)
+```
+
+### 6. 方法详情页（多重载）
+
+当方法有多个重载时，使用 `## 重载 N:` 分节：
+
+```markdown
+# {ClassName}::{MethodName}
+
+{一句话描述方法功能}
+
+## 重载 1: {简短描述}
+
+```cpp
+{签名1}
+```
+
+{描述}
+
+**参数：**
+- `param` - {描述}
+
+**返回：** {类型} - {含义}
+
+**复杂度：** O(n)
+
+## 重载 2: {简短描述}
+
+```cpp
+{签名2}
+```
+
+...
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+{完整可运行代码}
+```
+
+## 相关文档
+
+- [{ClassName} 总览](class-name.md)
+```
+
+---
+
+## 元信息字段规范
+
+| 字段 | 必需 | 适用页面 | 说明 |
+|------|------|----------|------|
+| `**命名空间**` | 是 | 所有 | C++ 命名空间 |
+| `**类型**` | 是 | 所有 | `class`、`struct`、`enum class`、`module` 等；class 可加修饰如 `(abstract)`、`(singleton)` |
+| `**描述**` | 是 | 所有 | 一句话功能描述 |
+| `**头文件**` | 是 | 类/struct/enum | 相对路径形式，如 `XCEngine/Threading/Task.h` |
+
+---
+
+## 必需章节规范
+
+### 模块总览页
+
+1. `## 概述` — 模块功能介绍
+2. `## 模块内容` — 分类表格（含组件名、文件、描述三列）
+3. `## 使用示例` — 完整代码
+4. `## 相关文档` — 交叉引用
+
+### 类总览页
+
+1. `## 概述` — 类功能介绍
+2. `## 公共方法` — 方法列表（纯虚方法加标注 `(pure virtual)`）
+3. `## 受保护方法` — 如有
+4. `## 使用示例` — 完整代码
+5. `## 相关文档` — 交叉引用
+
+### Struct 总览页
+
+1. `## 结构体成员` — 成员表格（含类型、描述、默认值三列）
+2. `## 使用示例` — 完整代码
+3. `## 相关文档` — 交叉引用
+
+### Enum 总览页
+
+1. `## 枚举值` — 枚举值表格（含枚举值、数值、描述三列）
+2. `## 使用示例` — 完整代码
+3. `## 相关文档` — 交叉引用
+
+### 方法详情页
+
+1. **方法签名** — 完整 `cpp` 代码块
+2. **详细描述** — 语义和使用场景
+3. **参数列表** — 每个参数的含义
+4. **返回值** — 类型和含义
+5. **示例代码** — 完整可运行代码
+6. **相关文档** — 返回类总览的链接
+
+---
+
+## 链接规范
+
+- 同一类文件夹内跳转：`[MethodName](method-name.md)`
+- 指向类总览：`[ClassName 总览](class-name.md)`
+- 指向模块总览：`[../module.md](../module.md)` 或 `[模块名](../module.md)`
+- 跨模块跳转：`[{DocName}](../module/class.md)`
+- 链接文本使用中文（如"返回类总览"）而非英文
+
+---
+
+## 特殊章节
+
+### Singleton 类
+
+Singleton 类在 `## 公共方法` 后可加 `## 单例访问` 章节：
+
+```markdown
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static ClassName& Get()` | 获取单例实例 |
+```
+
+### std::hash 特化
+
+String 等需要 hash 的类，在方法列表后加：
+
+```markdown
+## std::hash 特化
+
+```cpp
+namespace std {
+    template<>
+    struct hash<XCEngine::Containers::String> {
+        size_t operator()(const XCEngine::Containers::String& str) const noexcept;
+    };
+}
+```
+
+{描述 hash 算法细节}
+```
+
+### 构造函数详细表
+
+某些类（如 ConsoleLogSink）在类总览页末尾用表格记录构造函数参数默认值：
+
+```markdown
+## 构造函数详细
+
+| 属性 | 值 |
+|------|-----|
+| 默认 `m_colorOutput` | `true` |
+```
+
+---
+
+## 代码示例规范
+
+- 语言标签：`cpp`
+- 包含必要的 `#include`
+- 示例完整可运行（不是代码片段）
+- 代码注释使用中文
+
+---
+
+## 线程安全标注
+
+- `✅` — 线程安全
+- `❌` — 非线程安全
+- 可附加括号说明：`✅ (内部使用 mutex 保护)`
+
+---
+
+## 文档一致性检查
+
+生成或修改文档时，需检查：
+
+1. **元信息完整性** — 每页都有命名空间、类型、描述、头文件（类/struct/enum）
+2. **链接有效性** — 所有相对链接指向的文件确实存在
+3. **内容无重复** — 同一页面中不要出现重复的描述、参数、示例等
+4. **类型匹配** — `**类型**` 字段与实际 C++ 类型一致
+5. **枚举数值** — enum 页面包含数值列
+6. **默认值** — struct 页面成员表格包含默认值列
+7. **命名一致** — 页面文件名与 H1 标题一致
+
+---
+
+## 生成流程
+
+> **核心原则：在动手写文档之前，必须先完整阅读并深刻理解源码上下文。**
+
+1. **阅读源码**：完整阅读目标类的头文件（.h）和实现文件（.cpp），理解设计意图、数据成员、
+   工作流程、边界条件、线程安全约定、与其他模块的依赖关系。不要只看签名就写文档。
+2. **扫描提取**：在充分理解的基础上，系统性提取方法签名、成员变量、枚举值、文档注释等信息。
+3. **创建结构**：为每个类创建文件夹，生成类总览页和方法详情页。
+4. **检查一致性**：运行链接检查、字段完整性检查。
+5. **补充缺失**：对照源码，检查现有文档是否完整，如有缺失的 .md 文件（类总览页、方法详情页等）
+   必须自行创建；如现有文档中缺少示例、枚举值说明、参数描述等内容，也要自行补充完整，不要留空。
+6. **输出报告**：列出生成文件列表、缺失内容、发现的问题。
+
+---
+
+## 使用示例
+
+用户输入：
+```
+完善 docs/api 文档，检查并修复错误
+```
+
+AI 执行：
+1. 扫描指定源码目录
+2. 识别所有头文件中的 class/struct/enum
+3. 对比现有文档，找出缺失文件和错误引用
+4. 生成或修复 Markdown 文档
+5. 输出生成报告和问题列表