# 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. 输出报告：子系统划分理由、生成内容、缺失信息