XCEngine/skills/doc-blueprint-manager/SKILL.md

蓝图文档生成与校验 Skill

用途

根据项目源码生成符合 XCSDD 规范的蓝图文档（系统架构设计文档），并校验 YAML 结构和依赖关系。

---

蓝图文档结构规范

文件命名

蓝图文档统一命名为 blueprint.md，放在 docs/ 目录下。

文档整体结构

# {系统名称} 蓝图示例

---

# SYSTEM_META

```yaml
name: {系统名称}
version: {版本号}
type: {系统类型}
description: "{系统描述}"
target_runtime: {目标运行时}

---

SYSTEM_STRUCTURE

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

mode: {build|evolve|maintain}
description: "{模式描述}"
context: |
  {详细上下文说明}

---

REQUIREMENTS

- id: {REQ-ID}
  title: {需求标题}
  description: "{需求描述}"
  source: {user|constraint}
  type: {functional|non-functional}
  acceptance_criteria:
    - "{验收标准1}"
  priority: {P0|P1|P2}

---

MVS_DEFINITION

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

- name: {模型名}
  description: "{模型描述}"
  fields:
    - name: {字段名}
      type: {类型}
      default: {默认值}
      constraints: {required|optional}

---

EVOLUTION_PLAN

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. 输出生成报告和问题列表