14 KiB
14 KiB
XCEngine 蓝图文档编写与校验 Skill
用途
根据 XCEngine C++ 引擎源码生成符合规范的蓝图文档（系统架构设计文档），用于在 XCSDD 中 以 3D 可视化图谱方式展示系统的模块结构、子系统依赖关系和接口定义。
在开始编写任何蓝图文档之前，必须先完整阅读并深刻理解目标系统的源码上下文——包括设计目的、 模块划分、依赖关系、数据流、边界条件等。切忌在未读懂系统架构的情况下仅凭目录结构或猜测 来编写蓝图文档。
文档目录结构
docs/
├── blueprint.md # 蓝图总文档
├── plan/ # 规划类文档
└── api/ # API 文档（由 api-skill 管理）
文件命名： 蓝图文档统一命名为 blueprint.md，放在 docs/ 目录下。
文档整体结构
蓝图文档由多个 YAML 代码块通过 Markdown 标题分隔组成，所有 YAML 代码块共同构成 系统的完整蓝图定义。文档结构如下：
# {系统名称} 蓝图
---
# SYSTEM_META
```yaml
# 系统元信息
SYSTEM_STRUCTURE
# 系统结构定义（核心必填）
EVOLUTION_MODE
# 演化模式
REQUIREMENTS
# 需求列表
MVS_DEFINITION
# 最小可行方案定义
DATA_MODELS
# 数据模型定义
EVOLUTION_PLAN
# 演化计划
页面类型与模板
1. SYSTEM_META（元信息）
SYSTEM_META 是整个蓝图文档的元信息区，必须完整填写。
name: {系统名称}
version: {版本号}
type: {系统类型}
description: "{系统一句话描述}"
target_runtime: {目标运行时}
2. SYSTEM_STRUCTURE（系统结构）—— 核心必填
SYSTEM_STRUCTURE 定义系统的子系统和模块结构，是 XCSDD 3D 可视化的核心数据来源。
subsystems 和 modules 两个数组都被解析为 3D 图谱节点，依赖关系（depends_on）被解析为连线。
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（演化模式）
mode: {build|evolve|maintain}
description: "{模式描述}"
context: |
{多行上下文说明}
4. REQUIREMENTS（需求列表）
- id: {REQ-ID}
title: {需求标题}
description: "{需求描述}"
source: {user|constraint}
type: {functional|non-functional}
acceptance_criteria:
- "{验收标准1}"
priority: {P0|P1|P2}
5. MVS_DEFINITION（MVS 最小可行方案）
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（数据模型）
- name: {模型名}
description: "{模型描述}"
fields:
- name: {字段名}
type: {类型}
default: {默认值}
constraints: {required|optional}
7. EVOLUTION_PLAN（演化计划）
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
name— 系统名称version— 版本号type— 系统类型description— 系统描述target_runtime— 目标运行时
SYSTEM_STRUCTURE
root— 根模块名subsystems— 子系统列表，每个子系统至少包含 name、responsibilities、provides、depends_onmodules— 模块列表，每个模块至少包含 name、parent_subsystem、responsibility、public_api
EVOLUTION_MODE
mode— 演化模式description— 模式描述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 |
文档一致性检查
生成或修改蓝图文档时，需检查：
- 驼峰命名规范 — 所有子系统名和模块名必须使用驼峰命名，严禁下划线
- SYSTEM_STRUCTURE 一致性 —
modules[].parent_subsystem引用的子系统必须存在 - 依赖关系一致性 —
subsystems[].depends_on引用的子系统必须存在，无循环依赖 - 命名唯一性 —
subsystems[].name和modules[].name在各自数组内唯一 - ID 格式一致性 — 所有 ID 字段遵循统一格式（REQ-XXX、MVS-XXX 等）
- provides/depends_on 配对 — 子系统的对外接口最好被依赖方引用
- MVS 与 REQUIREMENTS 关联 — MVS 的 scope 应覆盖对应 REQ 涉及的所有子系统
- YAML 语法正确性 — YAML 代码块可正常解析，无缩进错误、无重复键
生成流程
核心原则：在动手写蓝图文档之前，必须先完整阅读并深刻理解系统源码上下文。
- 阅读源码：完整阅读目标系统的核心头文件和关键实现，理解设计目的、模块划分、 数据流、依赖关系、边界条件。不要只看目录结构就写蓝图。
- 识别子系统：根据功能边界和依赖关系，划分子系统。每个子系统应有明确的职责边界 和对外接口。子系统划分不宜过粗（导致职责重叠）也不宜过细（导致过度碎片化）。
- 提取模块和接口：从代码中提取核心模块及其 public API（函数签名、参数、返回值）。
- 构建依赖图：分析子系统间的依赖关系，确保无循环依赖。
- 生成 SYSTEM_META：填写系统元信息。
- 生成 SYSTEM_STRUCTURE：构建 subsystems 和 modules，确保依赖关系准确。
- 生成 REQUIREMENTS：从源码 TODO、BUG 注释、需求文档中提取需求。
- 生成 MVS_DEFINITION：为关键功能生成最小可行方案，指导分阶段实现。
- 补充可选章节：根据需要补充 DATA_MODELS 和 EVOLUTION_PLAN。
- 校验输出：运行所有一致性检查，检查依赖关系和命名一致性。
- 输出报告：列出生成内容、子系统划分理由、缺失信息和发现的问题。
使用示例
用户输入：
为 XCEngine 生成蓝图文档
AI 执行：
- 扫描 XCEngine 源码目录，分析代码结构和模块划分
- 识别核心子系统（Core、Rendering、Physics、Resource、Scripting 等）
- 提取各子系统的模块和 public API
- 分析子系统间的依赖关系，构建依赖图
- 生成
blueprint.md文件 - 运行校验检查 YAML 结构和依赖关系
- 输出报告：子系统划分理由、生成内容、缺失信息