Shiliang/UnityAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

【整合】 框架使用规则

Browse Source
This commit is contained in:
Shiliang
2026-07-10 17:50:20 +08:00
parent db0143be83
commit 001d9e5ef5
45 changed files with 1716 additions and 4062 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
rules/40-工作流清单.md
View File

@@ -1,206 +1,135 @@
# 工作流清单
> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
本文档是 UnityAI 唯一的任务执行流程。其他入口只链接本文件，不复制完整步骤。
---
## 一、任务分类
## 任务分类
| 类型 | 特征 | 处理方式 |
| 类型 | 判断标准 | 处理方式 |
|---|---|---|
| **简单修复** | 查询、解释、小范围修改、影响面低、用户已给出明确方式 | 直接处理，完成后验证并归档检查 |
| **旧模块修复** | 已有框架模块的 bug 修复、逻辑补全、局部优化 | 读取模块文档，分析影响范围后修复，验证并归档 |
| **Spec 任务** | 新增框架模块、调整架构/目录/依赖、批量修改迁移 | 走 OpenSpec 流程 |
| 分析检查 | 查询、解释、定位、评审，不要求修改 | 读取真实实现和证据，输出结论与风险 |
| 局部修复 | 目标明确、影响集中、公开行为基本不变 | 检查上下文后直接修改并验证 |
| 重大变更 | 公共接口、框架架构、生成流程、跨模块数据、批量资源或平台流程变化 | 先在对话中确认目标、边界、方案和验收条件，再实施 |
---
重大变更不创建 Spec、Plan、progress 或 tasks 文件。需要长期保存的内容，在实现确认后写入对应模块 README、架构说明或使用指南。
## 简单修复流程
## 二、标准执行流程
1. 确认任务范围。
2. 读取相关模块文档。
3. 直接修改。
4. 验证（如可运行测试、检查链接、预览 Markdown）。
5. 执行归档检查。
6. 简短说明结果。
### 1. 准备与定位
---
1. 读取 [项目规则入口](项目规则入口.md) 和相关模块文档。
2. 检查 UnityAI 与目标 Unity 项目的分支、工作树和未跟踪文件。
3. 读取 `ProjectSettings/ProjectVersion.txt`，确认 Unity 版本。
4. 搜索调用入口、数据流、Prefab、配置、生成器和测试方式。
5. 按 [架构说明](10-架构说明.md) 确认修改对象是真实源码还是生成结果。
## 旧模块修复流程
无法从仓库发现的信息才向用户确认。已有修改默认属于用户，必须保留并在其基础上工作。
1. 定位已有模块文档和相关内容。
2. 简短分析影响范围和风险。
3. 直接修复。
4. 验证。
5. 按 [50-归档规则.md](50-归档规则.md) 同步相关模块文档。
### 2. 分析与确认
---
- 分析检查：继续读取直到结论有代码、资源、配置或日志支撑。
- 局部修复：说明准备修改的位置和行为，然后直接实施。
- 重大变更：在对话中确认目标、范围、兼容性、数据流、失败行为和验证标准。
- 存在多个真实取舍时提供备选方案；没有实际取舍时不制造方案数量。
## Spec 任务流程
### 3. 实施
大需求 / 新模块统一走 OpenSpec：
- 遵循附近文件的结构、命名和语言特性。
- 修改保持在需求涉及的模块内，不顺带重构无关代码。
- 使用结构化 API 处理 JSON、XML、Prefab 和配置，不使用脆弱的字符串替换。
- 修改资源时优先通过 Unity Editor、已有生成器或 MCP 工具，避免无意义的 Prefab 重序列化。
- 不修改任务无关文件，不回退已有工作树变更。
1. 分析目标、影响范围、风险和依赖。
2. 给出 2-3 个方案。
3. 用户确认后创建 OpenSpec change。
4. 生成 `proposal.md`、`design.md`、`tasks.md`。
5. 实现。
6. 验证。
7. 归档并同步文档。
### 4. 生成代码
详见 [60-新特性工作流.md](60-新特性工作流.md)。
修改 `Assets/StrayFog/Editor/CopyToX` 下的 `ESF_` 源码后：
---
1. 通过 Unity 菜单或 MCP 白名单命令执行 CopyToX。
2. 检查 `Assets/Game/GameHFScripte/CopyToHF` 或对应目标目录的生成差异。
3. 确认 `ESF_` 到 `HF_` 的类型名、文件名和调用关系转换正确。
4. 编译目标程序集并读取 Unity Console。
## 开发流程
出现“HF 已修改但 ESF 未修改”时，先判断是否误改生成文件；出现“ESF 已修改但 HF 未变化”时，必须补执行 CopyToX。
### 1. 文档学习
### 5. 分层验证
根据任务类型阅读对应模块文档：
| 改动范围 | 最低验证 |
|---|---|
| `Assets/StrayFog/Core` | 构建 `StrayFogCore.csproj`，再检查 Unity Console |
| `Assets/StrayFog/Editor`、`Assets/Editor` | 构建适用 Editor 程序集或在 Unity 中触发编译，检查 Console 和菜单行为 |
| `GameGeneralScripte` | 构建 `GameGeneral.csproj` |
| `GameMono` | 构建 `SFMono.csproj` |
| `GameHFScripte` | 构建 `GameHF.csproj` |
| Prefab/UI | 刷新资源，检查层级、RectTransform、组件启用状态、引用和实际显示 |
| AssetBundle/分包/下载 | 除 Editor 外，验证目标平台路径、协程、MD5、失败回退和日志 |
| 任务类型 | 必读文档 |
|---------|---------|
| UI 开发 | [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) |
| UI 界面设计 | [UI 界面拼接设计指南](../modules/frameworks/UI窗口系统/界面拼接.md) |
| 相机控制 | [相机系统](../modules/frameworks/相机系统/README.md) |
| 实体开发 | [实体系统](../modules/frameworks/实体系统/README.md) |
| 事件使用 | [事件系统](../modules/frameworks/事件系统/README.md) |
| 资源加载 | [资源管理](../modules/frameworks/资源管理/README.md) |
常用命令：
### 2. 需求分析
1. 明确需求：理解业务需求，确定需要实现的功能。
2. 评估复杂度：判断是否需要核心库支持或扩展。
3. 设计方案：规划代码结构和调用关系。
### 3. 代码编写
1. 在 `GameFunction/` 下按职责创建模块目录。
2. 遵循编码规范，使用核心库提供的 API。
3. 在 Unity 中测试功能正确性。
### 4. 代码审查
1. 自我检查：检查是否符合规范，是否有潜在问题。
2. 团队审查：提交代码进行团队审查。
3. 修复问题：根据审查意见修改代码。
### 5. 集成测试
1. 模块测试：测试单个模块功能。
2. 集成测试：测试模块间交互。
3. 回归测试：确保不影响现有功能。
---
## 文档变更联动检查
修改任何文档前，确认它是否被其他文档引用：
- 模块文档变更 → 同步检查模块索引、模块登记规则、架构说明。
- 架构/目录变更 → 同步检查模块索引、相关模块 README、架构说明。
- 规则文件变更 → 同步检查 `rules/项目规则入口.md`、`ai/AI接入入口.md`、`AGENTS.md`、`CLAUDE.md`、`RULES.md`。
- spec/change 完成 → 同步更新相关模块 progress.md，并建立 `specs/openspec/` 归档。
---
## 提交前检查
### 提交信息格式
推荐格式：
```text
[模块][类型]: 简短描述
- 详细说明 1
- 详细说明 2
```powershell
dotnet build SFMono.csproj --no-restore -v:minimal
dotnet build GameHF.csproj --no-restore -v:minimal
```
类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
其他程序集按实际改动替换项目文件。构建结果需区分既有警告和本次新增错误。
模块名示例：`framework`、`entity`、`ui`、`event`、`resource`、`docs`、`rules`、`hooks`。
### 6. Unity 与 MCP 验证
示例：
需要 Unity 自动化时：
```text
[entity][docs]: 补充实体池索引机制说明
1. 调用 `unity_health`，确认项目路径和 Unity 版本。
2. 执行白名单菜单、资源刷新、Prefab 生成或导出。
3. 调用 `unity_get_console_logs` 检查新增 Error 和关键 Warning。
4. Prefab/UI 任务继续做结构与实际显示验证，不能以“文件已生成”作为完成条件。
- 添加 onlyid -> entity 映射说明
- 补充 HFBasicPool/HFEnemyPool/HFHumanityPool 边界
```
连接失败时停止后续 Unity 命令并报告原因，不假设命令已经执行。
> **历史格式说明**：早期文档使用 `【操作原因】具体操作内容`（如 `【修复】xxx`）。该格式已弃用，新提交统一使用 `[module][type]: description`。
### 7. 文档同步
### 分支管理
按 [文档同步规则](50-文档同步规则.md) 判断是否存在长期知识变化：
| 分支名称 | 用途 |
|----------|------|
| `master` | 主分支，稳定版本 |
| `develop` | 开发分支，日常开发 |
| `feature/*` | 功能分支，开发新功能 |
| `bugfix/*` | Bug 修复分支 |
- 公共接口、架构边界、生成流程、平台行为或稳定使用规则变化时，同步模块文档。
- 局部 Bug 修复、临时日志和实现细节不自动写入长期文档。
- 同一事实只在一个文档完整定义，其他位置链接引用。
### Git 操作原则
### 8. Git
- 执行 Git 操作前确认当前操作路径是否正确。
- 遵循项目既定的分支策略。
- 使用语义化提交信息，清晰描述更改内容。
- 重要功能提交前建议先创建分支进行测试。
- 开发完成后及时推送到远程仓库。
- 只有用户明确要求“提交”“commit”“推送”时才执行 Git 写操作。
- UnityAI 和目标 Unity 项目是独立仓库，分别检查、暂存、提交和推送。
- 提交前运行工作流检查、目标测试、`git diff --check` 和提交信息检查。
- 提交格式：`[模块][类型]: 描述`，类型为 `feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
- 不把两个仓库的改动描述成一个提交，也不夹带任务开始前的无关修改。
### 提交前检查项
## 三、UI 专项流程
- [ ] 文档链接可点击且指向正确。
- [ ] 文档关联表已更新。
- [ ] 模块索引已同步（如新增/拆分了模块）。
- [ ] 无拼写或明显格式错误。
- [ ] 未引入外部项目专属内容。
- [ ] 业务参考内容只出现在 `business-reference/` 下。
1. 先读 [UI 开发指南](../modules/frameworks/UI窗口系统/开发指南.md) 和 [界面拼接](../modules/frameworks/UI窗口系统/界面拼接.md)。
2. 同时检查 Prefab 层级、脚本绑定、模板节点、布局组件和数据刷新时机。
3. 单列列表使用 LoopListView2 接口，多列布局使用 LoopGridView 接口。
4. 列表初始化放在一次性生命周期，数据数量刷新放在窗口打开或数据变化时。
5. 完成后验证空数据、少量数据、超出视口、重复打开和回收重用。
---
## 四、异步与平台规则
## 新增内容流程
- UnityWebRequest、StreamingAssets、CDN 和 WebGL 等待流程使用协程或回调。
- 不在主线程使用阻塞式 `while`、忙等或同步等待网络结果。
- Editor 可用不代表 Android、iOS、WebGL 或小游戏路径可用；平台路径和存储回调必须分别验证。
- 下载完成计数只在单个文件完整写入并通过校验后推进。
### 新增框架模块
## 五、完成检查
1. 在 [模块索引](../modules/模块索引.md) 中登记。
2. 创建 `modules/frameworks/<module>.md`；复杂模块可拆分为 `modules/frameworks/<module>/README.md` 加子文档。
3. 在 [架构说明](10-架构说明.md) 中补充依赖方向。
4. 更新相关模块的文档关联表。
### 新增编辑器工具
1. 在 [模块索引](../modules/模块索引.md) 中登记。
2. 创建 `modules/editor-tools/<tool>.md` 或补充汇总文档。
3. 说明使用入口、生成输出、依赖项。
### 新增业务参考
1. 放入 `business-reference/<project>/`。
2. 不进入 `modules/模块索引.md` 主索引。
3. 在 `business-reference/<project>/业务框架映射接口.md` 中补充映射关系。
---
## 生成/构建流程
若项目使用 StrayFog 框架配套的生成工具：
- 优先修改源表、proto 或 schema，而不是生成输出。
- 生成后检查输出目录，确认变更符合预期。
- 缺失的生成步骤记录到对应模块文档。
---
- [ ] 修改了真实源码，没有误改生成文件。
- [ ] 必要生成步骤已经执行并检查差异。
- [ ] 相关程序集编译通过。
- [ ] Unity Console 无本次新增错误。
- [ ] UI/Prefab 或平台行为完成实际验证。
- [ ] 长期文档按影响同步，没有写入流水账。
- [ ] 两个仓库状态分别检查，未触碰用户无关修改。
- [ ] 未经明确要求没有提交或推送。
## 文档关联
> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
| 文档 | 关联原因 |
|---|---|
| [rules/项目规则入口.md](项目规则入口.md) | 工作流清单是项目规则入口索引的关键规则 |
| [rules/50-归档规则.md](50-归档规则.md) | 归档规则与工作流清单互相引用 |
| [rules/60-新特性工作流.md](60-新特性工作流.md) | 新特性工作流是工作流清单的延伸 |
| [rules/20-开发规则.md](20-开发规则.md) | 提交格式与开发规则互相引用 |
| [modules/模块索引.md](../modules/模块索引.md) | 新增模块登记需同步模块索引 |
| [hooks/commit-check.ps1](../hooks/commit-check.ps1) | 提交检查脚本需与本文件格式一致 |
| [项目规则入口](项目规则入口.md) | 指向本工作流的快速入口 |
| [架构说明](10-架构说明.md) | 源码与生成代码边界 |
| [开发规则](20-开发规则.md) | 实施阶段的代码与 Unity 规范 |
| [文档同步规则](50-文档同步规则.md) | 完成后的长期知识同步 |
| [共享检查](../hooks/Hook共享层.md) | 工作流和提交检查脚本 |