XCEngine/docs/blueprint-skill.md

# XCEngine 蓝图文档编写与校验 Skill

## 用途

根据 XCEngine 当前工作树生成或重写 `docs/blueprint.md`，用于描述真实已落地的系统结构、子系统依赖、关键数据模型和当前演进方向。

蓝图不是愿景文档，也不是过期设计稿的搬运。它必须服从当前 checkout、当前 `CMakeLists.txt`、当前测试、当前项目布局和当前文档主线。

---

## 当前仓库里的事实来源顺序

处理蓝图任务时，按下面顺序建立上下文：

1. 当前工作树与相关 `CMakeLists.txt`
2. [AGENT.md](../AGENT.md)
3. [README.md](../README.md) 与 [editor/README.md](../editor/README.md)
4. 对应模块的测试目录与聚合 target
5. `docs/plan/` 下仍活跃的设计 / 计划文档

如果旧文档与当前代码冲突，先信当前代码，再修文档。

---

## 必须同步的活跃文档

当蓝图所描述的架构事实发生变化时，不要只改 `docs/blueprint.md`。

通常至少要检查这些活跃文档是否需要同步：

- `docs/blueprint.md`
- `docs/blueprint-skill.md`
- `README.md`
- `editor/README.md`
- `AGENT.md`

如果同时触及 API 术语、Editor 调用链或 source-backed API 页面：

1. 先检查 `docs/plan/` 下是否有更新的 API 相关任务池或计划。
2. 再检查 `docs/api-skill.md`。
3. 必要时同步对应 `docs/api/**` 页面。

---

## 不要改的归档区域

以下目录默认视为归档背景材料，只读，不在本轮蓝图收口里直接改写：

- `docs/plan/used/**`
- `docs/used/**`

如果需要引用归档内容，只把它当历史上下文，不能让它覆盖当前事实。

---

## 蓝图写作的硬约束

### 1. 必须以当前工程结构为准

当前蓝图至少要覆盖这些活跃部分：

- `engine/`
- `editor/`
- `managed/`
- `project/`
- `tests/`

不要再传播这些过期说法：

- “只有 D3D12 和 OpenGL 双后端”
- “还没有脚本系统”
- “还没有 Editor 主链”
- “`project/Library/` 可以忽略”
- “根目录存在 `native/` 占位项”

### 2. Project / Library 是当前 workflow 的一部分

蓝图必须明确当前工程真实采用：

- `Assets/ + .meta + Library/`
- `Project.xcproject`
- `Library/SourceAssetDB/assets.db`
- `Library/ArtifactDB/artifacts.db`
- `Library/Artifacts/`
- `Library/ScriptAssemblies/`

不要把 `project/Library/` 写成“无关生成垃圾目录”。

### 3. Editor 是宿主，不是第二套渲染器

蓝图里描述 editor 时，要保持当前口径：

- editor 是 `D3D12` 宿主应用
- Scene / Game viewport 通过引擎 `Rendering + RHI` 离屏渲染
- Scene View 当前 helper 链要按真实实现书写

当前主链以实际代码为准，最近主线是：

`SceneViewportChrome -> SceneViewportInteractionFrame -> SceneViewportNavigation -> SceneViewportTransformGizmoCoordinator -> ViewportHostService`

### 4. 脚本系统必须按当前 Mono 链路描述

蓝图必须体现当前脚本链路至少由这几部分构成：

- `managed/XCEngine.ScriptCore/`
- `managed/GameScripts/`
- `project/Assets/**/*.cs`
- `project/Library/ScriptAssemblies/`
- `engine/src/Scripting/`
- `editor/src/Scripting/`

如果本轮涉及脚本蓝图，额外核对：

- `managed/CMakeLists.txt`
- `editor/src/Scripting/EditorScriptAssemblyBuilder.cpp`
- `tests/Scripting/`
- `tests/Editor/`

### 5. Windows 路径大小写按真实目录名写

文档里统一写真实目录名，例如：

- `tests/Core/`
- `tests/Rendering/`
- `tests/Editor/`
- `tests/Scripting/`

不要制造无意义的大小写漂移。

---

## 蓝图文档结构

`docs/blueprint.md` 维持以下固定章节：

```markdown
# XCEngine 蓝图

---

# SYSTEM_META

```yaml
...
```

---

# SYSTEM_STRUCTURE

```yaml
...
```

---

# EVOLUTION_MODE

```yaml
...
```

---

# REQUIREMENTS

```yaml
...
```

---

# MVS_DEFINITION

```yaml
...
```

---

# DATA_MODELS

```yaml
...
```

---

# EVOLUTION_PLAN

```yaml
...
```
```

要求：

- 所有 YAML 代码块都必须能被正常解析
- `SYSTEM_STRUCTURE` 里的子系统、依赖和模块名称要能在当前代码里找到对应锚点
- 不要在同一份蓝图里同时保留互相矛盾的新旧架构

---

## 推荐收口流程

1. 先读 `AGENT.md`、`README.md`、相关 `CMakeLists.txt`。
2. 只抽取与本次蓝图相关的关键头文件、关键源文件、测试目录。
3. 识别当前真实子系统边界，而不是沿用旧蓝图里的命名。
4. 重写 `SYSTEM_META`、`SYSTEM_STRUCTURE`、`EVOLUTION_MODE`。
5. 再补 `REQUIREMENTS`、`MVS_DEFINITION`、`DATA_MODELS`、`EVOLUTION_PLAN`。
6. 回读整份蓝图，检查有没有把旧时期说法残留到新结构里。
7. 如涉及主文档口径变化，同步检查 `README.md` / `editor/README.md` / `AGENT.md`。

---

## 一致性检查清单

完成蓝图修改后，至少确认：

1. 后端数量与当前代码一致，`RHI` 现在是 `D3D12 / OpenGL / Vulkan`。
2. `Rendering` 主链写成当前真实链路，而不是旧 sample 分支。
3. `Editor` 被描述为宿主层，Scene View helper 链与当前实现一致。
4. `Resources` / `Core/Asset` 明确覆盖 `.meta`、`assets.db`、`artifacts.db`、`Artifacts/`。
5. `Scripting` 明确覆盖 `XCEngine.ScriptCore.dll`、`GameScripts.dll`、`project/Assets/**/*.cs` 和 `Library/ScriptAssemblies/`。
6. `Project` 明确覆盖 `Project.xcproject`、`Assets/Scenes/*.xc` 和 `Library/`。
7. `Tests` 与当前 `tests/` 目录和聚合 target 口径一致。
8. 没有修改归档目录。

---

## 目标

最终产物应当让后来者只看当前蓝图，就能理解：

- 这套工作区现在真正有哪些子系统
- 它们通过什么链路接起来
- 当前稳定的数据边界在哪里
- 下一阶段应该在什么约束下继续演进