xuanchi/XCEngine

Fork 0

Files

ssdfasd 31756847ab docs: sync api and planning docs

2026-04-08 16:07:03 +08:00

5.6 KiB

Raw Permalink Blame History

XCEngine 蓝图文档编写与校验 Skill

用途

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

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

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

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

当前工作树与相关 CMakeLists.txt
AGENT.md
README.md 与 editor/README.md
对应模块的测试目录与聚合 target
docs/plan/ 下仍活跃的设计 / 计划文档

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

必须同步的活跃文档

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

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

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

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

先检查 docs/plan/ 下是否有更新的 API 相关任务池或计划。
再检查 docs/api-skill.md。
必要时同步对应 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 维持以下固定章节：

# XCEngine 蓝图

---

# SYSTEM_META

```yaml
...

SYSTEM_STRUCTURE

...

EVOLUTION_MODE

...

REQUIREMENTS

...

MVS_DEFINITION

...

DATA_MODELS

...

EVOLUTION_PLAN

...


要求：

- 所有 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. 没有修改归档目录。

---

## 目标

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

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

5.6 KiB Raw Permalink Blame History Unescape Escape