diff --git a/skills/doc-api-manager/SKILL.md b/skills/doc-api-manager/SKILL.md deleted file mode 100644 index fd363876..00000000 --- a/skills/doc-api-manager/SKILL.md +++ /dev/null @@ -1,184 +0,0 @@ -# XCEngine API 文档编写与校验 Skill - -## 用途 - -根据 XCEngine C++ 引擎源码生成符合规范的 API 文档，并进行格式校验和查漏补缺。 - ---- - -## 文档层次结构规范 - -### 目录结构 - -每个类对应一个文件夹，类文件夹下包含类总览页和方法详情页： - -``` -docs/api/ -├── index.md # 总索引 -├── math/ -│ ├── math.md # Math 模块总览 -│ ├── vector3.md # Vector3 类总览 -│ ├── dot.md # Dot 方法详情 -│ ├── cross.md # Cross 方法详情 -│ └── ... -├── containers/ -│ ├── containers.md # Containers 模块总览 -│ ├── array.md # Array 类总览 -│ ├── emplace.md # Emplace 方法详情 -│ ├── push.md # Push 方法详情 -│ └── ... -└── ... -``` - -**规则：** -- 模块总览页：`{module}/{module}.md`（如 `math/math.md`、`containers/containers.md`） -- 类文件夹：`{class-name}/`（如 `array/`、`vector3/`） -- 类总览页：`{class-name}/{class-name}.md`（如 `array/array.md`） -- 方法详情页：`{class-name}/{method-name}.md`（如 `array/emplace.md`） - -### 类总览页模板 - -```markdown -# {类名称} - -**命名空间**: `{namespace}` - -**类型**: `{type}` - -**描述**: {一句话功能描述} - -## 概述 - -{模块功能详细介绍，包括设计目的和使用场景} - -## 公共方法 - -| 方法 | 描述 | -|------|------| -| [`Emplace`](./emplace.md) | 原地构造元素 | -| [`Push`](./push.md) | 末尾添加元素 | - -## 使用示例 - -```cpp -{代码示例} -``` - -## 相关文档 - -- [{文档名}](./{filename}.md) - {简短描述} -``` - -### 方法详情页模板 - -```markdown -# {类名称}::{方法名} - -```cpp -{完整方法签名} -``` - -{方法详细描述，包括设计目的、使用场景、注意事项} - -**参数：** -- `{param}` - {参数描述} - -**返回：** {返回值描述} - -**异常：** （如有） - -**线程安全：** ✅ / ❌ - -**复杂度：** O(n) - -**示例：** - -```cpp -{可运行的完整示例代码} -``` - -## 相关文档 - -- [{类总览}](./{class}.md) - 返回类总览 -``` - ---- - -## 必需字段规范 - -### 元信息（必须） - -- `**命名空间**`: C++ 命名空间，如 `XCEngine::Math` -- `**类型**`: `class`、`struct`、`enum` 等 -- `**描述**`: 一句话功能描述 - -### 必需章节 - -1. **概述** - 模块功能介绍（设计目的、使用场景） -2. **公共方法** - 表格形式，每个方法链接到详情页 -3. **使用示例** - 完整可运行的代码示例 -4. **相关文档** - 交叉引用 - -### 方法详情页必需章节 - -1. **方法签名** - 完整 C++ 签名 -2. **详细描述** - 语义、使用场景、注意事项 -3. **参数列表** - 每个参数的含义 -4. **返回值** - 返回值含义 -5. **示例代码** - 可运行的完整示例 -6. **相关文档** - 返回类总览的链接 - ---- - -## 校验规则 - -### 1. 格式校验 - -- [ ] 文档结构正确：模块有 `{module}/{module}.md`，类有 `{class}/{class}.md` -- [ ] 元信息完整：`命名空间`、`类型`、`描述` -- [ ] 类总览页的公共方法表格中，每个方法都有对应的详情页 -- [ ] 代码块使用 ``` 包裹，语言标识正确（`cpp`） - -### 2. 引用校验 - -- [ ] 所有 `./{method}.md` 链接指向的文件存在 -- [ ] 引用路径使用相对路径 -- [ ] 不存在循环引用 - -### 3. 内容校验 - -- [ ] 所有 public 方法都已列出 -- [ ] 方法签名与源码一致 -- [ ] 返回值类型正确 -- [ ] 默认参数值标注清楚 -- [ ] 示例代码可编译运行 -- [ ] 命名空间与源码一致 - ---- - -## 生成流程 - -1. **扫描源码**：分析指定目录下的头文件 -2. **识别 API**：查找 `class`、`struct`、`enum`、`namespace` -3. **提取信息**：从源码中提取方法签名、成员变量、枚举值、文档注释 -4. **创建结构**：为每个类创建文件夹，生成类总览页和方法详情页 -5. **生成文档**：按照上述模板生成 Markdown 文件 -6. **校验输出**：运行校验规则，检查格式和引用 -7. **输出报告**：列出生成的文档和发现的问题 - ---- - -## 使用示例 - -用户输入： -``` -完善 docs/api 文档，检查并修复错误 -``` - -AI 执行： -1. 扫描指定源码目录 -2. 识别所有头文件中的 class/struct/enum -3. 对比现有文档，找出缺失文件和错误引用 -4. 生成或修复 Markdown 文档 -5. 运行校验检查格式和引用 -6. 输出生成报告和问题列表 diff --git a/skills/doc-blueprint-manager/SKILL.md b/skills/doc-blueprint-manager/SKILL.md deleted file mode 100644 index 29732b55..00000000 --- a/skills/doc-blueprint-manager/SKILL.md +++ /dev/null @@ -1,296 +0,0 @@ -# 蓝图文档生成与校验 Skill - -## 用途 - -根据项目源码生成符合 XCSDD 规范的蓝图文档（系统架构设计文档），并校验 YAML 结构和依赖关系。 - ---- - -## 蓝图文档结构规范 - -### 文件命名 - -蓝图文档统一命名为 `blueprint.md`，放在 `docs/` 目录下。 - -### 文档整体结构 - -```markdown -# {系统名称} 蓝图示例 - ---- - -# SYSTEM_META - -```yaml -name: {系统名称} -version: {版本号} -type: {系统类型} -description: "{系统描述}" -target_runtime: {目标运行时} -``` - ---- - -# SYSTEM_STRUCTURE - -```yaml -root: {根模块} - -subsystems: - - name: {子系统名} - responsibilities: - - "{职责1}" - - "{职责2}" - provides: [{提供的接口1}, {提供的接口2}] - depends_on: [{依赖的子系统}] - boundary: - inputs: [{输入}] - outputs: [{输出}] - -modules: - - name: {模块名} - parent_subsystem: {所属子系统} - responsibility: "{模块职责}" - public_api: - - fn: {函数名} - params: - - name: {参数名} - type: {参数类型} - returns: type: {返回类型} -``` - ---- - -# EVOLUTION_MODE - -```yaml -mode: {build|evolve|maintain} -description: "{模式描述}" -context: | - {详细上下文说明} -``` - ---- - -# REQUIREMENTS - -```yaml -- id: {REQ-ID} - title: {需求标题} - description: "{需求描述}" - source: {user|constraint} - type: {functional|non-functional} - acceptance_criteria: - - "{验收标准1}" - priority: {P0|P1|P2} -``` - ---- - -# MVS_DEFINITION - -```yaml -mvs_solutions: - - id: {MVS-ID} - name: {最小可行方案名称} - goal: "{目标描述}" - - verification_criteria: - - "{验证标准1}" - - scope: - - subsystem: {子系统名} - components: [{组件名}] - - code_structure: - - file: {文件名} - purpose: "{文件用途}" - contains: - - "{包含的功能}" - standalone: {true|false} - - integration_plan: - - step: "{集成步骤1}" - - status: {pending|in_progress|completed} -``` - ---- - -# DATA_MODELS - -```yaml -- name: {模型名} - description: "{模型描述}" - fields: - - name: {字段名} - type: {类型} - default: {默认值} - constraints: {required|optional} -``` - ---- - -# EVOLUTION_PLAN - -```yaml -fix_plan: - - issue_id: {BUG-ID} - description: "..." - root_cause: "..." - minimal_change: - - file: {文件路径} - verification: ... - -refactor_plan: - - target: "{重构目标}" - constraints: [...] - steps: [...] - -feature_plan: - - feature_id: {FEAT-ID} - name: "{功能名称}" - addition: "..." - integration_point: ... - steps: [...] -``` - ---- - -## YAML 结构规范 - -### SYSTEM_META（必需） - -| 字段 | 类型 | 必填 | 描述 | -|------|------|------|------| -| name | string | 是 | 系统名称 | -| version | string | 是 | 版本号，格式 x.y.z | -| type | string | 是 | 系统类型（game-engine、web-framework、api-service 等） | -| description | string | 是 | 系统一句话描述 | -| target_runtime | string | 否 | 目标运行时环境 | - -### SYSTEM_STRUCTURE（必需） - -#### subsystems 数组 - -| 字段 | 类型 | 必填 | 描述 | -|------|------|------|------| -| name | string | 是 | 子系统名称，唯一标识 | -| responsibilities | string[] | 是 | 职责列表，至少 1 项 | -| provides | string[] | 是 | 提供的接口列表 | -| depends_on | string[] | 是 | 依赖的子系统 | -| boundary | object | 否 | 边界定义 | -| boundary.inputs | string[] | 否 | 输入项 | -| boundary.outputs | string[] | 否 | 输出项 | - -#### modules 数组 - -| 字段 | 类型 | 必填 | 描述 | -|------|------|------|------| -| name | string | 是 | 模块名称，唯一标识 | -| parent_subsystem | string | 是 | 所属子系统名称 | -| responsibility | string | 是 | 模块职责描述 | -| public_api | object[] | 是 | 公共 API 列表 | -| public_api[].fn | string | 是 | 函数名 | -| public_api[].params | object[] | 是 | 参数列表 | -| public_api[].params[].name | string | 是 | 参数名 | -| public_api[].params[].type | string | 是 | 参数类型 | -| public_api[].returns | object | 否 | 返回值 | -| public_api[].returns.type | string | 是（当有 returns 时） | 返回类型 | - -### EVOLUTION_MODE（必需） - -| 字段 | 类型 | 必填 | 描述 | -|------|------|------|------| -| mode | enum | 是 | `build`（从零构建）、`evolve`（演进迭代）、`maintain`（维护修复） | -| description | string | 是 | 模式描述 | -| context | string | 是 | 详细上下文，多行字符串 | - -### REQUIREMENTS（可选） - -| 字段 | 类型 | 必填 | 描述 | -|------|------|------|------| -| id | string | 是 | 需求 ID，格式 REQ-XXX | -| title | string | 是 | 需求标题 | -| description | string | 是 | 需求描述 | -| source | enum | 是 | `user`（用户需求）、`constraint`（约束条件） | -| type | enum | 是 | `functional`（功能性）、`non-functional`（非功能性） | -| acceptance_criteria | string[] | 是 | 验收标准，至少 1 项 | -| priority | enum | 是 | `P0`（关键）、`P1`（重要）、`P2`（次要） | - -### MVS_DEFINITION（可选） - -| 字段 | 类型 | 必填 | 描述 | -|------|------|------|------| -| id | string | 是 | MVS ID，格式 MVS-XXX | -| name | string | 是 | 最小可行方案名称 | -| goal | string | 是 | 目标描述 | -| verification_criteria | string[] | 是 | 验证标准 | -| scope | object[] | 是 | 涉及范围 | -| code_structure | object[] | 是 | 代码结构 | -| integration_plan | string[] | 是 | 集成计划 | -| status | enum | 是 | `pending`、`in_progress`、`completed` | - ---- - -## 校验规则 - -### 1. YAML 语法校验 - -- [ ] YAML 代码块可正常解析 -- [ ] 无缩进错误 -- [ ] 无重复键 -- [ ] 数组格式正确 - -### 2. 结构校验 - -- [ ] `SYSTEM_META` 存在且字段完整 -- [ ] `SYSTEM_STRUCTURE` 存在且包含 `subsystems` -- [ ] `EVOLUTION_MODE` 存在且 mode 有效 -- [ ] 所有 `subsystems` 有唯一 name -- [ ] 所有 `modules` 有唯一 name 且 parent_subsystem 有效 - -### 3. 依赖关系校验 - -- [ ] `subsystems[].depends_on` 引用的子系统存在 -- [ ] `modules[].parent_subsystem` 引用的子系统存在 -- [ ] 无循环依赖（A → B → A） -- [ ] 每个子系统的 `provides` 接口被其他子系统 `depends_on` - -### 4. 数据一致性校验 - -- [ ] 所有 `public_api[].params[].type` 使用标准类型 -- [ ] `REQUIREMENTS[].id` 格式正确（REQ-XXX） -- [ ] `MVS_DEFINITION[].id` 格式正确（MVS-XXX） -- [ ] `MVS_DEFINITION[].status` 值有效 - ---- - -## 生成流程 - -1. **分析源码**：扫描指定目录下的代码文件 -2. **识别子系统**：根据目录结构或模块注释识别子系统 -3. **提取接口**：从代码中提取 public API（函数签名、参数、返回值） -4. **识别依赖**：分析 `import`/`require` 语句确定模块依赖 -5. **生成 SYSTEM_STRUCTURE**：构建 subsystems 和 modules -6. **生成 REQUIREMENTS**：从 TODO、BUG 注释中提取需求 -7. **生成 MVS_DEFINITION**：为关键功能生成最小可行方案 -8. **校验输出**：运行所有校验规则 -9. **输出报告**：列出生成内容和问题 - ---- - -## 使用示例 - -用户输入： -``` -为这个项目生成蓝图文档 -``` - -AI 执行： -1. 扫描指定源码目录分析代码结构 -2. 识别子系统（Core、Rendering、Physics、Scripting 等） -3. 提取模块和 public API -4. 生成 `blueprint.md` 文件 -5. 运行校验检查 YAML 结构和依赖 -6. 输出生成报告和问题列表