【整合】框架使用规则

2026-07-10 17:50:20 +08:00
parent db0143be83
commit 001d9e5ef5
45 changed files with 1716 additions and 4062 deletions
--- a/rules/10-架构说明.md
+++ b/rules/10-架构说明.md
@@ -1,144 +1,67 @@
 # 架构说明

-> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
-
-项目文档按三类组织：**核心运行时**、**编辑器工具**、**业务参考**。详细模块索引见 [模块索引](../modules/模块索引.md)。
-
---
-
-## 分类口径
-
- **核心运行时**：支撑游戏运行的内部系统，例如实体、UI、网络、资源、事件、场景、对象池。
- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。
- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。
-
---
+本文档定义 StrayFog 项目的代码分层、真实源码位置与生成边界。具体项目路径不同的时候，以项目配置和生成器实现为准。

 ## 总体分层

 ```text
-┌─────────────────────────────────────────────────────────────┐
-│                     StrayFog Framework                      │
-├─────────────────────────────────────────────────────────────┤
-│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────┐  │
-│  │   GameGeneral    │  │     GameHF       │  │    Core   │  │
-│  │   通用工具层     │  │   业务核心层     │  │  基础框架 │  │
-│  └────────┬─────────┘  └────────┬─────────┘  └─────┬─────┘  │
-├───────────┼─────────────────────┼──────────────────┼─────────┤
-│           │                     │                  │         │
-│           ▼                     ▼                  ▼         │
-│  ┌─────────────────────────────────────────────────────┐    │
-│  │                   Unity Engine                      │    │
-│  └─────────────────────────────────────────────────────┘    │
-└─────────────────────────────────────────────────────────────┘
+游戏业务（GameFunction / GameMono / GameHFResource）
+                    |
+                    v
+生成后的运行时框架（CopyToHF / GameGeneral）
+                    |
+                    v
+StrayFog Core / Unity Engine / 第三方插件
+
+StrayFog Editor / CopyToX --------------> 生成运行时代码与资源
 ```

-### 各层职责
+## 源码与生成结果

-| 层级 | 路径 | 职责描述 |
-|------|------|---------|
-| **Core 层** | `Assets/StrayFog/Core` | 核心基础框架，模拟行为系统、全局数据管理 |
-| **HF 层** | `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架，资源管理、事件系统、相机管理、UI 管理等 |
-| **General 层** | `Assets/Game/GameGeneralScripte` | 通用工具层，状态机、辅助工具、扩展方法等 |
-
---
-
-## 核心运行时层
-
-核心运行时按技术职责命名，可以对应内部目录。
-
- **Hotfix 启动/目录**：`GameFunction/GameRoot/`
- **实体系统**：`GameFunction/GameEntity/`、`Logic/EntityData/`
- **UI 系统**：`CopyToHF/UIWindowMgr/`、`GameFunction/UIWindows/`、`GameMono/Scripts/UIMono/`
- **场景系统**：`GameFunction/SceneManager/`、`GameMono/Scenes/`
- **网络系统**：`CopyToHF/Network/`、`GameFunction/WebSocket/`、`GoogleProtobufNetwork/`（如项目使用）
- **资源系统**：`CopyToHF/AssetBundle/`、`CopyToHF/SpriteAtlas/`、`GameHFResource/`
- **事件系统**：`CopyToHF/Event/`、`GameFunction/Event/`
- **对象池**：`CopyToHF/MemoryManager/`、`GameFunction/GameEntity/EntityPool/`
- **通用框架**：`GameGeneralScripte/`、`StrayFog/Core/`
-
---
-
-## 编辑器工具层
-
- `Assets/StrayFog/Editor/`：StrayFog 编辑器扩展。
- `Assets/Editor/`：项目编辑器资源与脚本。
- `Assets/AutoBuildScript/Editor/`：编辑器生成工具（如项目使用）。
-
---
-
-## 程序集边界
-
-已识别 asmdef：
-
-| 程序集 | 主要路径 | 分类 |
+| 路径 | 类型 | 修改规则 |
 |---|---|---|
-| `StrayFogCore` | `Assets/StrayFog/Core/` | 核心运行时 |
-| `SFEditor` | `Assets/StrayFog/Editor/` | 编辑器工具 |
-| `GameHF` | `Assets/Game/GameHFScripte/` | 核心运行时 / hotfix 承载 |
-| `GameGeneral` | `Assets/Game/GameGeneralScripte/` | 核心运行时 / general |
-| `SFMono` | `Assets/Game/GameMono/` | 核心运行时 / Mono 桥接 |
+| `Assets/StrayFog/Core` | 直接维护的框架运行时源码 | 按框架需求直接修改并构建 `StrayFogCore` |
+| `Assets/StrayFog/Editor` | Editor 工具与生成器源码 | 直接修改；运行时代码不得反向依赖 |
+| `Assets/StrayFog/Editor/CopyToX/CopyToHF` | `ESF_` 热更框架源码 | 框架修改的主要源头，修改后执行 CopyToX |
+| `Assets/StrayFog/Editor/CopyToX/CopyToGeneral` | General 层生成源码 | 修改后执行 CopyToX |
+| `Assets/Game/GameHFScripte/CopyToHF` | CopyToX 生成的 `HF_` 运行时代码 | 禁止手改，只检查生成差异 |
+| `Assets/Game/GameGeneralScripte/CopyToGeneral` | CopyToX 生成的 General 代码 | 禁止手改，只检查生成差异 |
+| `Assets/Game/GameHFScripte/GameFunction` | 项目热更业务代码 | 业务需求直接修改 |
+| `Assets/Game/GameMono` | 项目 Mono 桥接和组件代码 | 直接修改并构建 `SFMono` |
+| `Assets/Game/GameHFResource` | Prefab、图集、配置和 AssetBundle 资源 | 通过 Unity 或已有工具修改并验证序列化结果 |
+| `Assets/Editor/Command` | 项目 Editor/MCP 工具 | 直接修改，在 Unity 主线程验证 Editor API |

---
+CopyToX 会删除并重新生成目标子目录，同时把 `ESF_` 标记转换为 `HF_`。因此目标目录中的手工改动会丢失，也不能作为下一次生成的源码。
+
+## 程序集
+
+| 程序集 | 主要职责 |
+|---|---|
+| `StrayFogCore` | StrayFog 基础运行时 |
+| `SFEditor` | StrayFog Editor 工具 |
+| `GameGeneral` | 生成后的通用运行时层 |
+| `GameHF` | 热更框架与业务代码 |
+| `SFMono` | MonoBehaviour、UIMono 和桥接层 |
+
+项目接入第三方插件时，以 asmdef 依赖为准，不把第三方源码复制为框架规则。

 ## 依赖方向

-```text
-业务功能（PVE、PVP、背包、商店等，放在外部业务参考层）
-        |
-        v
-核心运行时（GameRoot、GameEntity、UIWindowMgr、SceneManager、Network、AssetBundle、Event 等）
-        |
-        v
-通用框架 / 第三方插件（StrayFog Core、Spine、DOTween 等）
-        |
-        v
-Unity Engine / .NET Runtime
+- 业务代码可以依赖公开框架入口和通用层。
+- 业务调用优先通过 `HFFunCatalogue` 等项目统一入口，不绕过封装直接依赖内部单例。
+- Core 和生成后的框架运行时不能依赖具体业务模块。
+- 运行时代码不能依赖 Editor 程序集。
+- Editor 工具可以读取或生成运行时代码和资源，但生成结果不能成为生成器的反向依赖。

-编辑器工具 -----------------> 读取/生成 核心运行时代码
-```
+## 当前验证基线

-### 依赖规则
-
-| 上层 | 可以依赖 | 禁止依赖 |
-|---|---|---|
-| 业务功能 | 核心运行时、通用框架 | 编辑器工具、第三方插件源码 |
-| 核心运行时 | 通用框架、第三方插件 | 具体业务功能、编辑器工具 |
-| 编辑器工具 | 核心运行时源码、生成模板 | 被运行时代码反向引用 |
-
-### 说明
-
- 运行时代码不要依赖 Editor 程序集。
- 第三方插件不应反向依赖具体玩法模块。
- 业务功能代码按业务命名，代码目录可以仍然按框架/实现组织。
-
---
-
-## 文档与代码分层对应
-
-| 文档层 | 对应代码层 | 示例 |
-|--------|-----------|------|
-| `modules/frameworks/` | 核心运行时 | 实体系统、UI 系统、事件系统等 |
-| `modules/frameworks/通用框架/框架架构.md` | 核心运行时 + 规范 | StrayFog 整体架构分析 |
-| `rules/` | 规范与流程 | 开发规则、工作流清单、架构说明 |
-
---
-
-## 待确认
-
- 各项目实际使用的 StrayFog 版本与目录可能略有差异，文档中路径以当前仓库描述的 `Assets/StrayFog/` 和 `Assets/Game/` 结构为准。
- 网络系统、配置生成系统是否为所有使用 StrayFog 的项目标配，需按具体项目确认。
-
---
+AI 每次都应读取目标项目的 `ProjectSettings/ProjectVersion.txt`，不把文档中的版本当作永久值。当前 CrystalBattle_Client 的验证基线为 Unity `2022.3.29f1`。

 ## 文档关联

-> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
-
 | 文档 | 关联原因 |
 |---|---|
-| [modules/frameworks/通用框架/框架架构.md](../modules/frameworks/通用框架/框架架构.md) | 实现视角的框架架构分析 |
-| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是架构说明的落地入口，分类口径需一致 |
-| [rules/30-模块登记规则.md](30-模块登记规则.md) | 模块登记口径、状态定义与架构分层互相影响 |
-| [rules/20-开发规则.md](20-开发规则.md) | 程序集边界、依赖方向与开发规则互相引用 |
-| [rules/项目规则入口.md](项目规则入口.md) | 架构说明是项目规则入口索引的关键规则 |
+| [开发规则](20-开发规则.md) | 源码边界对应具体修改规则 |
+| [工作流清单](40-工作流清单.md) | 生成和验证步骤引用本架构 |
+| [模块索引](../modules/模块索引.md) | 模块职责和入口 |
+| [通用框架](../modules/frameworks/通用框架/框架架构.md) | StrayFog 实现视角的架构说明 |