Shiliang/UnityAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ee1ff7f44484823add0296ccc9a614d86d22f1b3
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

11 KiB
Raw Blame History

UnityAI - 项目规则入口

本文件是 UnityAI / StrayFog 框架知识库的 项目规则入口。

所有 AI / IDE 工具先通过 ai/AI接入入口.md 接入项目，再按任务范围读取本文件和下方链接的具体文档。

不要把项目规则重复写在你的系统提示里；直接引用本文件和 rules/ 下的规则文件。

AI 快速启动

  1. 确认已读取 AI 工具接入入口。
  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 项目用途、文档结构、核心子系统
10-架构说明.md 框架结构、目录职责、依赖方向、程序集边界
20-开发规则.md C# 规范、Unity 资源规则、文档编写规则
30-模块登记规则.md 模块登记口径、状态定义、文档拆分规则
40-工作流清单.md 任务分类、修复流程、Spec 流程、提交前检查
50-归档规则.md 归档时机、归档内容、关联更新原则
60-新特性工作流.md 大需求 / 新模块如何通过 OpenSpec 流程推进
70-项目设置.md AI 工具扫描范围、跳过目录、例外情况

项目知识入口

项目框架、核心功能、编辑器工具的总入口统一维护在 modules/模块索引.md。

规则文件不重复维护模块清单；新增、拆分、改名模块时，以 modules/模块索引.md 为唯一事实来源，并按 30-模块登记规则.md 的口径登记。

常用框架规则入口：

  • 实体系统：实体基类、System-Model 架构、实体池、生命周期。
  • UI 窗口系统：UIWindow、Prefab、层级、生命周期和事件释放。
  • 事件系统：CTC/STC 事件、派发链路、监听规范。
  • 资源管理：AssetBundle、语言资源、图集、加载规则。
  • 对象池：类实例池、行为对象池、实体池、RT 展示对象。

Spec / Plan 索引

类型 文档
Spec 索引 specs/Spec索引.md
OpenSpec 归档 specs/openspec/OpenSpec归档.md
计划进度 plans/

任务流转

简单修复

  • 查询、解释、定位问题。
  • 小范围、明确、影响面低的修改。
  • 用户已给出明确实现方式。

处理：直接开始修复或回答，完成后验证，并执行归档 hook / 归档检查。

旧模块修复

  • 项目中已有模块的 bug 修复、逻辑补全、局部优化。
  • 影响范围主要集中在一个已有功能或框架模块。
  • 不新增大模块，不调整总体架构。

处理：读取相关模块文档和代码/内容，简短分析影响范围后直接修复；完成后验证，并按 50-归档规则.md 执行归档 hook / 归档检查。

Spec 任务

  • 新增大功能或新模块。
  • 调整架构、目录职责、依赖方向。
  • 调整文档结构、生成流程。
  • 涉及多个系统的批量修改、删除、迁移。
  • 用户没有明确方案，需要先权衡。

处理：按 40-工作流清单.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 同步到项目文档：
    • 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。

关键约束

  • 一处定义，多处引用：如果一个事实出现在多个文档中，修改时必须同步所有地方。
  • 优先修改源头文档，不要手动同步复制多份内容。
  • 运行时代码不引用 Editor 程序集。
  • UI 变更遵循 UI 框架。
  • 事件变更遵循 事件框架。
  • 资源变更遵循 资源管理。

归档规则摘要

所有任务完成后都执行归档 hook / 归档检查。归档不是写流水账，只更新和本次任务相关的长期文档。

简单修复如果没有改变长期规则、模块状态、架构或后续任务，可以只在最终回复中说明无需文档更新；旧模块修复和 Spec 任务按影响范围同步相关模块文档。

核心原则：一处定义，多处引用。

详见 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。

接入新 AI 工具时

如果你是新接入的 AI 工具，只需要：

  1. 读取 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 接入入口引用本项目规则入口
AGENTS.md Codex 入口通过 ai/AI接入入口.md 引用本文件
CLAUDE.md Claude Code 入口通过 ai/AI接入入口.md 引用本文件
RULES.md 兼容重定向入口通过 ai/AI接入入口.md 引用本文件
rules/00-项目概览.md 项目概况在本文档中被引用
rules/10-架构说明.md 架构说明在本文档中被引用
rules/20-开发规则.md 开发规则在本文档中被引用
rules/30-模块登记规则.md 模块登记规则在本文档中被引用
rules/40-工作流清单.md 工作流清单在本文档中被引用
rules/50-归档规则.md 归档规则在本文档中被引用
rules/60-新特性工作流.md 大需求/新模块工作流在本文档中被引用
rules/70-项目设置.md 扫描范围规则在本文档中被引用
modules/模块索引.md 模块索引是本文档引用的项目知识入口
specs/Spec索引.md Spec 索引在本文档中被引用
hooks/Hook共享层.md 归档触发机制在本文档中被引用
Reference in New Issue View Git Blame Copy Permalink