470 lines
14 KiB
Markdown
470 lines
14 KiB
Markdown
# XCEngine 蓝图文档编写与校验 Skill
|
||
|
||
## 用途
|
||
|
||
根据 XCEngine C++ 引擎源码生成符合规范的蓝图文档（系统架构设计文档），用于在 XCSDD 中
|
||
以 3D 可视化图谱方式展示系统的模块结构、子系统依赖关系和接口定义。
|
||
|
||
在开始编写任何蓝图文档之前，必须先完整阅读并深刻理解目标系统的源码上下文——包括设计目的、
|
||
模块划分、依赖关系、数据流、边界条件等。切忌在未读懂系统架构的情况下仅凭目录结构或猜测
|
||
来编写蓝图文档。
|
||
|
||
---
|
||
|
||
## 文档目录结构
|
||
|
||
```
|
||
docs/
|
||
├── blueprint.md # 蓝图总文档
|
||
├── plan/ # 规划类文档
|
||
└── api/ # API 文档（由 api-skill 管理）
|
||
```
|
||
|
||
**文件命名：** 蓝图文档统一命名为 `blueprint.md`，放在 `docs/` 目录下。
|
||
|
||
---
|
||
|
||
## 文档整体结构
|
||
|
||
蓝图文档由多个 YAML 代码块通过 Markdown 标题分隔组成，所有 YAML 代码块共同构成
|
||
系统的完整蓝图定义。文档结构如下：
|
||
|
||
```markdown
|
||
# {系统名称} 蓝图
|
||
|
||
---
|
||
|
||
# SYSTEM_META
|
||
|
||
```yaml
|
||
# 系统元信息
|
||
```
|
||
|
||
---
|
||
|
||
# SYSTEM_STRUCTURE
|
||
|
||
```yaml
|
||
# 系统结构定义（核心必填）
|
||
```
|
||
|
||
---
|
||
|
||
# EVOLUTION_MODE
|
||
|
||
```yaml
|
||
# 演化模式
|
||
```
|
||
|
||
---
|
||
|
||
# REQUIREMENTS
|
||
|
||
```yaml
|
||
# 需求列表
|
||
```
|
||
|
||
---
|
||
|
||
# MVS_DEFINITION
|
||
|
||
```yaml
|
||
# 最小可行方案定义
|
||
```
|
||
|
||
---
|
||
|
||
# DATA_MODELS
|
||
|
||
```yaml
|
||
# 数据模型定义
|
||
```
|
||
|
||
---
|
||
|
||
# EVOLUTION_PLAN
|
||
|
||
```yaml
|
||
# 演化计划
|
||
```
|
||
|
||
---
|
||
|
||
## 页面类型与模板
|
||
|
||
### 1. SYSTEM_META（元信息）
|
||
|
||
SYSTEM_META 是整个蓝图文档的元信息区，必须完整填写。
|
||
|
||
```yaml
|
||
name: {系统名称}
|
||
version: {版本号}
|
||
type: {系统类型}
|
||
description: "{系统一句话描述}"
|
||
target_runtime: {目标运行时}
|
||
```
|
||
|
||
### 2. SYSTEM_STRUCTURE（系统结构）—— 核心必填
|
||
|
||
SYSTEM_STRUCTURE 定义系统的子系统和模块结构，是 XCSDD 3D 可视化的核心数据来源。
|
||
`subsystems` 和 `modules` 两个数组都被解析为 3D 图谱节点，依赖关系（`depends_on`）被解析为连线。
|
||
|
||
```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: {返回类型}
|
||
```
|
||
|
||
### 3. EVOLUTION_MODE（演化模式）
|
||
|
||
```yaml
|
||
mode: {build|evolve|maintain}
|
||
description: "{模式描述}"
|
||
context: |
|
||
{多行上下文说明}
|
||
```
|
||
|
||
### 4. REQUIREMENTS（需求列表）
|
||
|
||
```yaml
|
||
- id: {REQ-ID}
|
||
title: {需求标题}
|
||
description: "{需求描述}"
|
||
source: {user|constraint}
|
||
type: {functional|non-functional}
|
||
acceptance_criteria:
|
||
- "{验收标准1}"
|
||
priority: {P0|P1|P2}
|
||
```
|
||
|
||
### 5. MVS_DEFINITION（MVS 最小可行方案）
|
||
|
||
```yaml
|
||
mvs_solutions:
|
||
- id: {MVS-ID}
|
||
name: {方案名称}
|
||
goal: "{目标描述}"
|
||
|
||
verification_criteria:
|
||
- "{验证标准1}"
|
||
|
||
scope:
|
||
- subsystem: {子系统名}
|
||
components: [{组件名}]
|
||
- external: [{外部依赖}]
|
||
|
||
code_structure:
|
||
- file: {文件名}
|
||
purpose: "{文件用途}"
|
||
contains:
|
||
- "{包含的功能1}"
|
||
standalone: {true|false}
|
||
|
||
integration_plan:
|
||
- step: "{集成步骤1}"
|
||
|
||
status: {pending|in_progress|completed}
|
||
```
|
||
|
||
### 6. DATA_MODELS（数据模型）
|
||
|
||
```yaml
|
||
- name: {模型名}
|
||
description: "{模型描述}"
|
||
fields:
|
||
- name: {字段名}
|
||
type: {类型}
|
||
default: {默认值}
|
||
constraints: {required|optional}
|
||
```
|
||
|
||
### 7. EVOLUTION_PLAN（演化计划）
|
||
|
||
```yaml
|
||
fix_plan:
|
||
- issue_id: {BUG-ID}
|
||
description: "{问题描述}"
|
||
root_cause: "{根本原因}"
|
||
minimal_change:
|
||
- file: {文件路径}
|
||
verification: "{验证方法}"
|
||
|
||
refactor_plan:
|
||
- target: "{重构目标}"
|
||
constraints: ["{约束条件}"]
|
||
steps: ["{步骤1}"]
|
||
|
||
feature_plan:
|
||
- feature_id: {FEAT-ID}
|
||
name: "{功能名称}"
|
||
addition: "{功能描述}"
|
||
integration_point: "{集成点}"
|
||
steps: ["{步骤1}"]
|
||
```
|
||
|
||
---
|
||
|
||
## 元信息字段规范
|
||
|
||
### SYSTEM_META
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `name` | 是 | 系统名称，唯一标识 |
|
||
| `version` | 是 | 版本号，格式 x.y.z |
|
||
| `type` | 是 | 系统类型，如 `game-engine`、`web-framework`、`api-service` |
|
||
| `description` | 是 | 系统一句话功能描述 |
|
||
| `target_runtime` | 否 | 目标运行时，如 `C++17`、`WebAssembly`、`Python 3.10` |
|
||
|
||
### SYSTEM_STRUCTURE
|
||
|
||
#### subsystems 数组
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `name` | 是 | 子系统名称，唯一标识 |
|
||
| `responsibilities` | 是 | 职责列表，至少 1 项 |
|
||
| `provides` | 是 | 提供的接口列表，表示该子系统对外暴露的能力 |
|
||
| `depends_on` | 是 | 依赖的子系统列表，引用的子系统必须存在 |
|
||
| `boundary` | 否 | 边界定义 |
|
||
| `boundary.inputs` | 否 | 该子系统的外部输入项 |
|
||
| `boundary.outputs` | 否 | 该子系统的外部输出项 |
|
||
|
||
#### modules 数组
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `name` | 是 | 模块名称，唯一标识 |
|
||
| `parent_subsystem` | 是 | 所属子系统名称，引用的子系统必须存在 |
|
||
| `responsibility` | 是 | 模块职责描述 |
|
||
| `public_api` | 是 | 公共 API 列表，至少 1 项 |
|
||
| `public_api[].fn` | 是 | 函数名 |
|
||
| `public_api[].params` | 是 | 参数列表 |
|
||
| `public_api[].params[].name` | 是 | 参数名 |
|
||
| `public_api[].params[].type` | 是 | 参数类型 |
|
||
| `public_api[].returns` | 否 | 返回值定义 |
|
||
| `public_api[].returns.type` | 是（当有 returns 时） | 返回类型 |
|
||
|
||
### EVOLUTION_MODE
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `mode` | 是 | `build`（从零构建）、`evolve`（演进迭代）、`maintain`（维护修复） |
|
||
| `description` | 是 | 模式一句话描述 |
|
||
| `context` | 是 | 多行详细上下文说明，使用 `\|` 语法 |
|
||
|
||
### REQUIREMENTS
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `id` | 是 | 需求 ID，格式 `REQ-XXX` |
|
||
| `title` | 是 | 需求标题，简短明确 |
|
||
| `description` | 是 | 需求详细描述 |
|
||
| `source` | 是 | `user`（用户需求）、`constraint`（约束条件） |
|
||
| `type` | 是 | `functional`（功能性）、`non-functional`（非功能性） |
|
||
| `acceptance_criteria` | 是 | 验收标准，至少 1 项 |
|
||
| `priority` | 是 | `P0`（关键，阻塞开发）、`P1`（重要）、`P2`（次要） |
|
||
|
||
### MVS_DEFINITION
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `id` | 是 | MVS ID，格式 `MVS-XXX` |
|
||
| `name` | 是 | 最小可行方案名称 |
|
||
| `goal` | 是 | 目标描述 |
|
||
| `verification_criteria` | 是 | 验证标准，至少 1 项 |
|
||
| `scope` | 是 | 涉及范围（子系统 + 外部依赖） |
|
||
| `code_structure` | 是 | 代码结构文件列表，至少 1 项 |
|
||
| `code_structure[].file` | 是 | 文件名 |
|
||
| `code_structure[].purpose` | 是 | 文件用途描述 |
|
||
| `code_structure[].contains` | 是 | 包含的功能列表 |
|
||
| `code_structure[].standalone` | 是 | 是否独立可运行 |
|
||
| `integration_plan` | 是 | 集成计划步骤 |
|
||
| `status` | 是 | `pending`（待开始）、`in_progress`（进行中）、`completed`（已完成） |
|
||
|
||
### DATA_MODELS
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `name` | 是 | 模型名称 |
|
||
| `description` | 是 | 模型描述 |
|
||
| `fields` | 是 | 字段列表 |
|
||
| `fields[].name` | 是 | 字段名 |
|
||
| `fields[].type` | 是 | 字段类型 |
|
||
| `fields[].default` | 否 | 默认值 |
|
||
| `fields[].constraints` | 否 | `required`（必填）或 `optional`（可选） |
|
||
|
||
### EVOLUTION_PLAN
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `issue_id` | 是（在 fix_plan 项中） | 缺陷 ID，格式 `BUG-XXX` |
|
||
| `description` | 是 | 问题描述 |
|
||
| `root_cause` | 是（在 fix_plan 项中） | 根本原因 |
|
||
| `minimal_change` | 是（在 fix_plan 项中） | 最小修改文件列表 |
|
||
| `verification` | 是（在 fix_plan 项中） | 验证方法 |
|
||
| `target` | 是（在 refactor_plan 项中） | 重构目标 |
|
||
| `constraints` | 是（在 refactor_plan 项中） | 约束条件列表 |
|
||
| `steps` | 是（在 refactor_plan 项中） | 重构步骤列表 |
|
||
| `feature_id` | 是（在 feature_plan 项中） | 特性 ID，格式 `FEAT-XXX` |
|
||
| `name` | 是（在 feature_plan 项中） | 功能名称 |
|
||
| `addition` | 是（在 feature_plan 项中） | 功能描述 |
|
||
| `integration_point` | 是（在 feature_plan 项中） | 集成点 |
|
||
|
||
---
|
||
|
||
## 必需章节规范
|
||
|
||
### SYSTEM_META
|
||
|
||
1. `name` — 系统名称
|
||
2. `version` — 版本号
|
||
3. `type` — 系统类型
|
||
4. `description` — 系统描述
|
||
5. `target_runtime` — 目标运行时
|
||
|
||
### SYSTEM_STRUCTURE
|
||
|
||
1. `root` — 根模块名
|
||
2. `subsystems` — 子系统列表，每个子系统至少包含 name、responsibilities、provides、depends_on
|
||
3. `modules` — 模块列表，每个模块至少包含 name、parent_subsystem、responsibility、public_api
|
||
|
||
### EVOLUTION_MODE
|
||
|
||
1. `mode` — 演化模式
|
||
2. `description` — 模式描述
|
||
3. `context` — 详细上下文
|
||
|
||
### REQUIREMENTS
|
||
|
||
每个需求项至少包含 id、title、description、source、type、acceptance_criteria、priority。
|
||
|
||
### MVS_DEFINITION
|
||
|
||
每个 MVS 方案至少包含 id、name、goal、verification_criteria、scope、code_structure、integration_plan、status。
|
||
|
||
### DATA_MODELS
|
||
|
||
每个数据模型至少包含 name、description、fields。
|
||
|
||
### EVOLUTION_PLAN
|
||
|
||
fix_plan、refactor_plan、feature_plan 至少包含各自必需字段。
|
||
|
||
---
|
||
|
||
## 依赖关系规范
|
||
|
||
### 子系统依赖
|
||
|
||
- `subsystems[].depends_on` 中引用的子系统名称必须在 `subsystems` 数组中存在
|
||
- 不允许循环依赖（A → B → A），应在校验阶段检测并报告
|
||
- 每个子系统的 `provides` 接口应当被其他子系统的 `depends_on` 引用（强推荐）
|
||
|
||
### 模块归属
|
||
|
||
- `modules[].parent_subsystem` 引用的子系统必须在 `subsystems` 数组中存在
|
||
|
||
---
|
||
|
||
## 命名规范
|
||
|
||
### 驼峰命名（必需）
|
||
|
||
所有标识符（子系统名、模块名）必须使用**驼峰命名法**，严禁使用下划线分隔。
|
||
|
||
| 正确示例 | 错误示例 |
|
||
|---------|---------|
|
||
| `CoreTypes` | `Core_Types`、`CoreTypes_` |
|
||
| `MathVector` | `Math_Vector`、`mathvector` |
|
||
| `RHICommandList` | `RHI_CommandList`、`RHICommand_List` |
|
||
| `DebugLogger` | `Debug_Logger` |
|
||
| `ResourcesManager` | `Resources_Manager` |
|
||
|
||
**规则：**
|
||
- 子系统名：`{子系统}{子模块}` 或直接 `{子系统}`（如 `Core`、`Math`、`RHI`）
|
||
- 模块名：`{子系统}{功能描述}`（如 `CoreTypes`、`MathVector`、`RHICommandList`）
|
||
- 若子系统名本身是多词组合（如 `RHI_D3D12`），模块名前缀应使用完整子系统名（如 `RHID3D12Device`）
|
||
|
||
### ID 格式
|
||
|
||
| 对象 | ID 格式 | 示例 |
|
||
|------|---------|------|
|
||
| 需求 | `REQ-XXX` | `REQ-001`、`REQ-002` |
|
||
| MVS 方案 | `MVS-XXX` | `MVS-001`、`MVS-002` |
|
||
| 缺陷 | `BUG-XXX` | `BUG-001`、`BUG-002` |
|
||
| 特性 | `FEAT-XXX` | `FEAT-001`、`FEAT-002` |
|
||
|
||
---
|
||
|
||
## 文档一致性检查
|
||
|
||
生成或修改蓝图文档时，需检查：
|
||
|
||
1. **驼峰命名规范** — 所有子系统名和模块名必须使用驼峰命名，严禁下划线
|
||
2. **SYSTEM_STRUCTURE 一致性** — `modules[].parent_subsystem` 引用的子系统必须存在
|
||
3. **依赖关系一致性** — `subsystems[].depends_on` 引用的子系统必须存在，无循环依赖
|
||
4. **命名唯一性** — `subsystems[].name` 和 `modules[].name` 在各自数组内唯一
|
||
5. **ID 格式一致性** — 所有 ID 字段遵循统一格式（REQ-XXX、MVS-XXX 等）
|
||
6. **provides/depends_on 配对** — 子系统的对外接口最好被依赖方引用
|
||
7. **MVS 与 REQUIREMENTS 关联** — MVS 的 scope 应覆盖对应 REQ 涉及的所有子系统
|
||
8. **YAML 语法正确性** — YAML 代码块可正常解析，无缩进错误、无重复键
|
||
|
||
---
|
||
|
||
## 生成流程
|
||
|
||
> **核心原则：在动手写蓝图文档之前，必须先完整阅读并深刻理解系统源码上下文。**
|
||
|
||
1. **阅读源码**：完整阅读目标系统的核心头文件和关键实现，理解设计目的、模块划分、
|
||
数据流、依赖关系、边界条件。不要只看目录结构就写蓝图。
|
||
2. **识别子系统**：根据功能边界和依赖关系，划分子系统。每个子系统应有明确的职责边界
|
||
和对外接口。子系统划分不宜过粗（导致职责重叠）也不宜过细（导致过度碎片化）。
|
||
3. **提取模块和接口**：从代码中提取核心模块及其 public API（函数签名、参数、返回值）。
|
||
4. **构建依赖图**：分析子系统间的依赖关系，确保无循环依赖。
|
||
5. **生成 SYSTEM_META**：填写系统元信息。
|
||
6. **生成 SYSTEM_STRUCTURE**：构建 subsystems 和 modules，确保依赖关系准确。
|
||
7. **生成 REQUIREMENTS**：从源码 TODO、BUG 注释、需求文档中提取需求。
|
||
8. **生成 MVS_DEFINITION**：为关键功能生成最小可行方案，指导分阶段实现。
|
||
9. **补充可选章节**：根据需要补充 DATA_MODELS 和 EVOLUTION_PLAN。
|
||
10. **校验输出**：运行所有一致性检查，检查依赖关系和命名一致性。
|
||
11. **输出报告**：列出生成内容、子系统划分理由、缺失信息和发现的问题。
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
用户输入：
|
||
```
|
||
为 XCEngine 生成蓝图文档
|
||
```
|
||
|
||
AI 执行：
|
||
1. 扫描 XCEngine 源码目录，分析代码结构和模块划分
|
||
2. 识别核心子系统（Core、Rendering、Physics、Resource、Scripting 等）
|
||
3. 提取各子系统的模块和 public API
|
||
4. 分析子系统间的依赖关系，构建依赖图
|
||
5. 生成 `blueprint.md` 文件
|
||
6. 运行校验检查 YAML 结构和依赖关系
|
||
7. 输出报告：子系统划分理由、生成内容、缺失信息
|