AI 文档
SuperCore-Unity 是用于演示框架能力的公开 Demo，其中提供了一套面向 AI 的项目文档示例。开发者把框架用于自己的游戏后，应根据实际项目改写并维护自己的 AI 文档。
Demo 示例文档入口：
- AGENTS.md：项目级 AI 规则和文档索引。
- ProjectDocs：框架、模块、编辑器工具和 Demo 业务手册。
- AI 快速入口：根据任务类型定位最小必读内容。
能解决什么问题
AI 初次进入一个 Unity 项目时，通常需要反复搜索入口、生命周期、配置和调用关系。Demo 中的 AI 文档展示了如何整理这些信息，并规定修改前仍需检查当前代码、Prefab、Scene、配置和生成物。
它主要用于：
- 快速定位 Runtime Module、Editor 工具和项目业务代码。
- 明确
SuperCore / Module / Procedure / GameSystem的职责边界。 - 约束配置、资源、构建、错误处理和自动收集等高风险修改。
- 在长任务、上下文恢复或多人协作时保留一致的项目规则。
- 让代码修改、当前手册、方案状态和修改日志保持同步。
首次使用
- 克隆或下载 SuperCore-Unity，了解 Demo 的框架接入、目录和 AI 文档结构。
- 创建自己的游戏项目和项目仓库，再将需要的 SuperCore 框架内容接入项目。
- 以 Demo 的
AGENTS.md和ProjectDocs为模板，复制到自己的项目根目录。 - 删除或改写 StarForce 专属内容，使目录、Module、资源、配置和业务说明与自己的项目一致。
- 让 AI 工具以自己的项目根目录作为工作目录，再读取
AGENTS.md、AI 快速入口和对应手册。 - 要求 AI 重新检查当前代码与调用点，再进行分析或修改。
支持 AGENTS.md 的工具通常会自动发现根目录规则。其他 AI 工具可以手动把 AGENTS.md、AI 快速入口和当前任务对应手册加入上下文。
迁移到自己的项目
Demo 文档不能原样代表新的游戏项目。第一次迁移后建议完成以下整理：
- 修改
AGENTS.md中的项目名称、实际目录、框架边界和文档索引。 - 根据自己的启动流程、Module 配置和资源组织重写
01_项目总览。 - 保留与当前 SuperCore 版本一致的
02_模块手册和03_编辑器规范，删除没有使用的能力说明。 - 删除 StarForce 专属的
04_业务逻辑内容，重新编写自己项目的流程、系统、实体、数值和资源映射。 - 清空 Demo 的方案与日志，只在自己的
08_方案记录和09_日志中记录后续项目工作。 - 最后检查
AGENTS.md和00_AI快速入口.md，确保所有入口都指向自己项目中真实存在的文档。
从这一刻开始，AI 文档由使用者在自己的项目中维护。
推荐提问方式
只分析问题：
text
请先读取 AGENTS.md、AI 快速入口和相关模块手册，再检查当前代码，分析问题原因，不要修改文件。实现需求：
text
请按当前项目的 AI 文档流程实现这个需求。修改前读取当前实现和全部调用点，完成后更新对应手册与日志，并说明是否运行了 Unity 或构建。继续未完成任务：
text
请重新读取 AGENTS.md、AI 快速入口和 08_方案记录中的对应方案，以当前工作区为准继续处理，不要重复已经完成的步骤。审查文档：
text
请对照当前代码、配置、Prefab 和 Scene 审查相关 AI 文档，列出不一致项；未经确认不要修改运行时代码。文档结构
| 位置 | 用途 |
|---|---|
AGENTS.md | 全局规则、架构边界和文档索引 |
00_AI快速入口.md | 根据任务类型选择最小必读文档 |
01_项目总览 | 项目结构、工作流程、编码与维护规范 |
02_模块手册 | SuperCore 通用运行时 Module |
03_编辑器规范 | SuperCoreKit、Build、资源工作台和生成器 |
04_业务逻辑 | 当前游戏项目自己的流程、系统、实体、数值和资源映射 |
08_方案记录 | 复杂任务的待实现、实现中、待验收和已完成方案 |
09_日志 | 已经发生的修改记录，仅用于追溯 |
后续如何维护
以下维护都在开发者自己的项目中进行。AI 文档应与自己的代码一起评审，并提交到自己的项目仓库：
- 修改项目架构、目录或全局规则时，更新
01_项目总览。 - 修改通用运行时 Module 时，更新
02_模块手册。 - 修改编辑器工具或内容构建规则时，更新
03_编辑器规范。 - 修改自己项目的业务流程、资源或数值时，更新
04_业务逻辑。 - 复杂任务先在
08_方案记录/待实现创建方案，再随任务状态移动。 - 实际修改完成后，按日志规范写入
09_日志。 - 新增、重命名或删除手册时，同步更新
AGENTS.md和 AI 快速入口。
升级 SuperCore 版本时，可以对照新版 Demo 选择性同步通用模块说明，并保留自己项目的业务文档。
.agents、.codex 等本地 AI 工具目录只保存个人环境或会话数据，建议在自己的项目仓库中继续忽略。
事实优先级
AI 文档用于提高理解和协作效率，但不替代实际工程。发生冲突时，按以下顺序判断：
- 当前代码、资源、Prefab、Scene、配置和生成物。
- 标记为“当前有效”的项目总览、模块、编辑器和业务手册。
08_方案记录/已完成中的设计与验收结论。- 其他状态方案和修改日志。
发现文档过期时，应以当前实现修正文档。不能为了兼容过期说明而给框架增加回退分支，也不能只更新日志而不更新当前手册。