239 lines
5.6 KiB
Markdown
239 lines
5.6 KiB
Markdown
# 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. 没有修改归档目录。
|
||
|
||
---
|
||
|
||
## 目标
|
||
|
||
最终产物应当让后来者只看当前蓝图，就能理解：
|
||
|
||
- 这套工作区现在真正有哪些子系统
|
||
- 它们通过什么链路接起来
|
||
- 当前稳定的数据边界在哪里
|
||
- 下一阶段应该在什么约束下继续演进
|