ssdfasd
dc850d7739
- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 index.md 为 main.md - 修正所有模块文档中的错误: - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式 - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节 - core: 修复 types 链接错误 - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI - memory: 修复头文件路径, malloc vs operator new, 新增方法文档 - resources: 修复 Shader/Texture 链接错误 - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接 - 验证: fix_links.py 确认 0 个断裂引用
297 lines
7.3 KiB
Markdown
297 lines
7.3 KiB
Markdown
# 蓝图文档生成与校验 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. 输出生成报告和问题列表
|