# 模块登记规则

> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。

这里定义模块登记口径、状态含义和拆分规则。项目模块总入口统一维护在 [模块索引](../modules/模块索引.md)，本文件不重复维护模块清单。

---

## 口径

- **核心框架**：支撑游戏运行的内部系统，例如实体系统、UI 窗口系统、事件系统、资源管理、对象池、场景管理、网络、配置生成。
- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。
- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。

---

## 唯一事实来源

模块清单、模块状态和模块入口统一维护在：

```text
modules/模块索引.md
```

其他规则文档只链接到模块索引或具体模块文档，不再复制模块表。

---

## 状态定义

- **未识别**：还没有稳定线索。
- **已识别**：已发现目录、类、资源或协议线索，但未完成梳理。
- **初步梳理**：已写入核心路径、职责、数据流或使用规则，仍可能有待确认项。
- **待验证**：文档已有结论，但需要通过 Unity、运行时、生成器或日志验证。
- **已完成**：文档和验证都闭环，后续只需随代码演进维护。
- **未发现实现**：按关键词和目录扫描后暂未发现实现，可作为规划占位。

避免使用“已开始”作为状态；它不能说明到底是只建了文件，还是已经完成了一轮梳理。

---

## 登记规则

- 新增核心框架模块时，登记到 [模块索引](../modules/模块索引.md) 的“核心框架”。
- 新增编辑器工具时，登记到 [模块索引](../modules/模块索引.md) 的“编辑器工具”。
- 新增业务参考时，登记到 `business-reference/` 下对应项目目录，不进入主模块索引。
- 框架内部规则优先写进对应框架模块文档，例如 UI 写入 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。
- 模块开始有独立设计、进度、任务时，再拆 `modules/<module>/`。
- 新增或拆分模块后，同步检查 [架构说明](10-架构说明.md) 和相关模块文档。

---

## 文档关系

- `modules/模块索引.md`：项目模块总入口和事实表。
- `modules/frameworks/*`：核心框架职责和框架使用规则。复杂模块拆分为文件夹，入口为 `README.md`。
- `modules/<module>/业务参考总入口.md`：复杂模块稳定说明。
- `modules/<module>/progress.md`：复杂模块阶段进度。
- `modules/<module>/tasks.md`：复杂模块待办事项。
- `rules/`：跨模块的通用规则、工作流、扫描范围和归档规则。
- `business-reference/`：外部项目业务参考，不进入主索引。

---

## 相关文档

- [模块索引](../modules/模块索引.md)：按分类整理的模块详细索引。
- [架构说明](10-架构说明.md)：总体分层、程序集边界和依赖方向。

---

## 文档关联

> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

| 文档 | 关联原因 |
|---|---|
| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是模块登记规则的唯一事实来源 |
| [rules/10-架构说明.md](10-架构说明.md) | 分类口径、依赖方向与架构说明互相影响 |
| [rules/项目规则入口.md](项目规则入口.md) | 模块登记规则是项目规则入口索引的关键规则 |
| [modules/frameworks/*.md](../modules/frameworks/) | 框架模块的状态、拆分规则需与登记规则一致 |