# UnityAI - 项目规则入口 > 本文件是 UnityAI / StrayFog 框架知识库的 **项目规则入口**。 > > 所有 AI / IDE 工具先通过 [ai/AI接入入口.md](../ai/AI接入入口.md) 接入项目，再按任务范围读取本文件和下方链接的具体文档。 > > 不要把项目规则重复写在你的系统提示里；直接引用本文件和 `rules/` 下的规则文件。 --- ## AI 快速启动 1. 确认已读取 [AI 工具接入入口](../ai/AI接入入口.md)。 2. **读取本文件**（`rules/项目规则入口.md`）。 3. 根据任务范围，从下方的 **规则索引**、**项目知识入口**、**Spec 索引** 中选择相关文档读取。 4. **简单修复**：直接开始处理，完成后简短说明结果。 5. **旧模块修复**：定位已有模块文档和相关内容，简短分析后直接修复。 6. **大需求 / 新模块**：新增框架模块、架构调整、文档重组等，先给出 2-3 个方案，用户确认后走 **OpenSpec 流程**。 7. **所有任务结束都执行归档 hook / 归档检查**，按影响范围决定是否更新长期文档。 --- ## 项目概况 - **项目名**：UnityAI - **副标题**：StrayFog 框架文档中心 - **目标读者**：使用 StrayFog 框架的 AI 工具、业务开发人员、框架维护人员 - **核心内容**：StrayFog 框架架构说明、核心功能使用指南、开发规范、开发流程、项目管理规范 - **仓库结构**： - `ai/` / `rules/` / `modules/` / `hooks/`：AI 规则与项目知识库（AI 优先读取） - `modules/frameworks/`：核心框架模块文档（按模块拆分为文件夹） - `business-reference/`：外部实际项目业务参考（与框架核心分离） - **技术栈**：Unity、C#、StrayFog 框架 - **文档语言**：中文 --- ## 语言与工作方式 - **默认使用中文回答用户**。 - **代码、类名、方法名、路径、命令、API 名称保持英文原文**。 - 简单修复直接处理，简短说明结果。 - 旧模块修复先定位已有模块文档和相关内容，简短分析风险后直接修复。 - 大需求 / 新模块先分析目标、影响范围、风险和依赖，给出 2-3 个方案，用户确认后走 OpenSpec。 - 如果用户明确说“直接实现”“按你判断来”，采用保守方案继续执行。 - 所有任务结束都执行归档 hook / 归档检查；不把无长期价值的流水账写入文档。 --- ## 规则索引 `rules/` 下的文件是项目长期规则，按以下顺序按需读取： | 文件 | 用途 | |---|---| | [00-项目概览.md](00-项目概览.md) | 项目用途、文档结构、核心子系统 | | [10-架构说明.md](10-架构说明.md) | 框架结构、目录职责、依赖方向、程序集边界 | | [20-开发规则.md](20-开发规则.md) | C# 规范、Unity 资源规则、文档编写规则 | | [30-模块登记规则.md](30-模块登记规则.md) | 模块登记口径、状态定义、文档拆分规则 | | [40-工作流清单.md](40-工作流清单.md) | 任务分类、修复流程、Spec 流程、提交前检查 | | [50-归档规则.md](50-归档规则.md) | 归档时机、归档内容、关联更新原则 | | [60-新特性工作流.md](60-新特性工作流.md) | 大需求 / 新模块如何通过 OpenSpec 流程推进 | | [70-项目设置.md](70-项目设置.md) | AI 工具扫描范围、跳过目录、例外情况 | --- ## 项目知识入口 项目框架、核心功能、编辑器工具的总入口统一维护在 [modules/模块索引.md](../modules/模块索引.md)。 规则文件不重复维护模块清单；新增、拆分、改名模块时，以 `modules/模块索引.md` 为唯一事实来源，并按 [30-模块登记规则.md](30-模块登记规则.md) 的口径登记。 常用框架规则入口： - [实体系统](../modules/frameworks/实体系统/README.md)：实体基类、System-Model 架构、实体池、生命周期。 - [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md)：UIWindow、Prefab、层级、生命周期和事件释放。 - [事件系统](../modules/frameworks/事件系统/README.md)：CTC/STC 事件、派发链路、监听规范。 - [资源管理](../modules/frameworks/资源管理/README.md)：AssetBundle、语言资源、图集、加载规则。 - [对象池](../modules/frameworks/内存对象管理/README.md)：类实例池、行为对象池、实体池、RT 展示对象。 --- ## Spec / Plan 索引 | 类型 | 文档 | |---|---| | Spec 索引 | [specs/Spec索引.md](../specs/Spec索引.md) | | OpenSpec 归档 | [specs/openspec/OpenSpec归档.md](../specs/openspec/OpenSpec归档.md) | | 计划进度 | [plans/](../plans/) | --- ## 任务流转 ### 简单修复 - 查询、解释、定位问题。 - 小范围、明确、影响面低的修改。 - 用户已给出明确实现方式。 处理：直接开始修复或回答，完成后验证，并执行归档 hook / 归档检查。 ### 旧模块修复 - 项目中已有模块的 bug 修复、逻辑补全、局部优化。 - 影响范围主要集中在一个已有功能或框架模块。 - 不新增大模块，不调整总体架构。 处理：读取相关模块文档和代码/内容，简短分析影响范围后直接修复；完成后验证，并按 [50-归档规则.md](50-归档规则.md) 执行归档 hook / 归档检查。 ### Spec 任务 - 新增大功能或新模块。 - 调整架构、目录职责、依赖方向。 - 调整文档结构、生成流程。 - 涉及多个系统的批量修改、删除、迁移。 - 用户没有明确方案，需要先权衡。 处理：按 [40-工作流清单.md](40-工作流清单.md) 和 [60-新特性工作流.md](60-新特性工作流.md) 走 OpenSpec。 --- ## OpenSpec 工作流（大需求 / 新模块） 1. 分析目标、影响范围、风险和依赖。 2. 给出 2-3 个方案，让用户选择。 3. 用户确认后创建 OpenSpec change： - Claude Code：`/opsx:propose "需求描述"` - CLI 通用：`openspec new change "change-name"` 4. 生成 `proposal.md`、`design.md`、`tasks.md`。 5. 判断是 **新模块** 还是 **已有模块的大改**： - 新模块：创建模块文档、登记模块、补充架构。 - 已有模块的大改：更新模块 progress.md、tasks.md，记录变更。 6. 按 design/tasks 实现代码、资源或配置变更。 7. 验证。 8. 归档 OpenSpec change： - Claude Code：`/opsx:archive` - CLI 通用：`openspec archive "change-name"` 9. 按 [50-归档规则.md](50-归档规则.md) 同步到项目文档： - `specs/openspec//` - 相关模块 `模块索引.md`、`progress.md`、`tasks.md` - `10-架构说明.md`（如涉及架构变化） - `modules/模块索引.md`（如新增模块） - `30-模块登记规则.md`（如改变模块分类、状态定义或登记规则） --- ## 扫描范围 正常分析项目时，**默认跳过**以下目录和文件以节省 token： - `Library/` - `Temp/` - `Logs/` - `UserSettings/` - `.vs/` - `*.csproj` - `*.sln` - `.codex/`（本地 hooks 状态） - `.claude/`（本地 commands/skills 状态） - `Library/PackageCache/` - `obj/` - `bin/` - 图片、音频、模型等二进制资源 详见 [70-项目设置.md](70-项目设置.md)。 --- ## 关键约束 - **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。 - 优先修改源头文档，不要手动同步复制多份内容。 - 运行时代码不引用 Editor 程序集。 - UI 变更遵循 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。 - 事件变更遵循 [事件框架](../modules/frameworks/事件系统/README.md)。 - 资源变更遵循 [资源管理](../modules/frameworks/资源管理/README.md)。 --- ## 归档规则摘要 所有任务完成后都执行归档 hook / 归档检查。归档不是写流水账，只更新和本次任务相关的长期文档。 简单修复如果没有改变长期规则、模块状态、架构或后续任务，可以只在最终回复中说明无需文档更新；旧模块修复和 Spec 任务按影响范围同步相关模块文档。 核心原则：**一处定义，多处引用**。 详见 [50-归档规则.md](50-归档规则.md)。 --- ## 文档变更联动原则 修改任何文档前，先确认它是否被其他文档引用： - 模块文档变更 → 同步检查模块索引、模块登记规则、架构说明。 - 架构/目录变更 → 同步检查模块索引、相关模块 README、架构说明。 - 规则文件变更 → 同步检查本文件、`ai/AI接入入口.md`、`AGENTS.md`、`CLAUDE.md`、`RULES.md`。 - spec/change 完成 → 同步更新相关模块 progress.md，并建立 `specs/openspec/` 归档。 ## 归档触发 文档关联和归档触发逻辑统一放在 `hooks/`： | 触发方式 | 命令/路径 | 说明 | |---|---|---| | Codex Stop hook | `.codex/hooks/archive-reminder.ps1` | 每次任务结束自动调用 `hooks/archive-check.ps1` 输出建议 | | Claude Code 手动 | `/opsx:archive-check` | 手动触发归档检查 | | OpenSpec 自动 | `/opsx:archive` | Spec 流程归档完成后自动调用 `hooks/archive-check.ps1` | | 手动脚本 | `hooks/archive-check.ps1` | 直接运行 PowerShell 脚本 | **重要**：以上触发只输出建议，不会自动修改任何文档。最终是否更新关联文档，需要用户确认。 详见 [hooks/Hook共享层.md](../hooks/Hook共享层.md)。 --- ## 接入新 AI 工具时 如果你是新接入的 AI 工具，只需要： 1. 读取 [ai/AI接入入口.md](../ai/AI接入入口.md)。 2. 再读取本文件（`rules/项目规则入口.md`）。 3. 按任务范围读取本文件索引中的具体规则/模块/spec 文档。 4. 遵循本文件的工作方式、扫描范围、关键约束和归档规则。 不同 AI / IDE 的默认入口、hook 适配方式统一维护在 `ai/AI接入入口.md`。项目根目录的 `AGENTS.md`、`CLAUDE.md`、`RULES.md` 都是指向 `ai/AI接入入口.md` 的薄入口。 --- ## 文档关联 > 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 | 文档 | 关联原因 | |---|---| | [ai/AI接入入口.md](../ai/AI接入入口.md) | AI 接入入口引用本项目规则入口 | | [AGENTS.md](../AGENTS.md) | Codex 入口通过 ai/AI接入入口.md 引用本文件 | | [CLAUDE.md](../CLAUDE.md) | Claude Code 入口通过 ai/AI接入入口.md 引用本文件 | | [RULES.md](../RULES.md) | 兼容重定向入口通过 ai/AI接入入口.md 引用本文件 | | [rules/00-项目概览.md](00-项目概览.md) | 项目概况在本文档中被引用 | | [rules/10-架构说明.md](10-架构说明.md) | 架构说明在本文档中被引用 | | [rules/20-开发规则.md](20-开发规则.md) | 开发规则在本文档中被引用 | | [rules/30-模块登记规则.md](30-模块登记规则.md) | 模块登记规则在本文档中被引用 | | [rules/40-工作流清单.md](40-工作流清单.md) | 工作流清单在本文档中被引用 | | [rules/50-归档规则.md](50-归档规则.md) | 归档规则在本文档中被引用 | | [rules/60-新特性工作流.md](60-新特性工作流.md) | 大需求/新模块工作流在本文档中被引用 | | [rules/70-项目设置.md](70-项目设置.md) | 扫描范围规则在本文档中被引用 | | [modules/模块索引.md](../modules/模块索引.md) | 模块索引是本文档引用的项目知识入口 | | [specs/Spec索引.md](../specs/Spec索引.md) | Spec 索引在本文档中被引用 | | [hooks/Hook共享层.md](../hooks/Hook共享层.md) | 归档触发机制在本文档中被引用 |