Shiliang/UnityAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
db0143be83a2e77cfd3079566e73d3882940e7d4
UnityAI/rules/项目规则入口.md
lms ee1ff7f444 [docs][refactor]: 将旧 01~06 中文教程合并整理为 modules/frameworks 文件夹结构 
- 删除 01~05 旧中文教程目录
- 将 03 核心功能教程拆分为各 framework 模块的子文档
- 06 工具脚本移入 modules/frameworks/编辑器工具/UI工具/
- 非框架内容合并进 rules/20-开发规则.md 与 rules/40-工作流清单.md
- 更新所有交叉链接与文档关联表

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-07 18:36:15 +08:00

253 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/<change-name>/`
- 相关模块 `模块索引.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) | 归档触发机制在本文档中被引用 |
Reference in New Issue View Git Blame Copy Permalink