UnityAI/rules/40-工作流清单.md

# 工作流清单

本文档是 UnityAI 唯一的任务执行流程。其他入口只链接本文件，不复制完整步骤。

## 一、任务分类

| 类型 | 判断标准 | 处理方式 |
|---|---|---|
| 分析检查 | 查询、解释、定位、评审，不要求修改 | 读取真实实现和证据，输出结论与风险 |
| 局部修复 | 目标明确、影响集中、公开行为基本不变 | 检查上下文后直接修改并验证 |
| 重大变更 | 公共接口、框架架构、生成流程、跨模块数据、批量资源或平台流程变化 | 先在对话中确认目标、边界、方案和验收条件，再实施 |

重大变更不创建 Spec、Plan、progress 或 tasks 文件。需要长期保存的内容，在实现确认后写入对应模块 README、架构说明或使用指南。

## 二、标准执行流程

### 1. 准备与定位

1. 读取 [项目规则入口](项目规则入口.md) 和相关模块文档。
2. 检查 UnityAI 与目标 Unity 项目的分支、工作树和未跟踪文件。
3. 读取 `ProjectSettings/ProjectVersion.txt`，确认 Unity 版本。
4. 搜索调用入口、数据流、Prefab、配置、生成器和测试方式。
5. 按 [架构说明](10-架构说明.md) 确认修改对象是真实源码还是生成结果。

无法从仓库发现的信息才向用户确认。已有修改默认属于用户，必须保留并在其基础上工作。

### 2. 分析与确认

- 分析检查：继续读取直到结论有代码、资源、配置或日志支撑。
- 局部修复：说明准备修改的位置和行为，然后直接实施。
- 重大变更：在对话中确认目标、范围、兼容性、数据流、失败行为和验证标准。
- 存在多个真实取舍时提供备选方案；没有实际取舍时不制造方案数量。

### 3. 实施

- 遵循附近文件的结构、命名和语言特性。
- 修改保持在需求涉及的模块内，不顺带重构无关代码。
- 使用结构化 API 处理 JSON、XML、Prefab 和配置，不使用脆弱的字符串替换。
- 修改资源时优先通过 Unity Editor、已有生成器或 MCP 工具，避免无意义的 Prefab 重序列化。
- 不修改任务无关文件，不回退已有工作树变更。

### 4. 生成代码

修改 `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。

### 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、失败回退和日志 |

常用命令：

```powershell
dotnet build SFMono.csproj --no-restore -v:minimal
dotnet build GameHF.csproj --no-restore -v:minimal
```

其他程序集按实际改动替换项目文件。构建结果需区分既有警告和本次新增错误。

### 6. Unity 与 MCP 验证

需要 Unity 自动化时：

1. 调用 `unity_health`，确认项目路径和 Unity 版本。
2. 执行白名单菜单、资源刷新、Prefab 生成或导出。
3. 调用 `unity_get_console_logs` 检查新增 Error 和关键 Warning。
4. Prefab/UI 任务继续做结构与实际显示验证，不能以“文件已生成”作为完成条件。

连接失败时停止后续 Unity 命令并报告原因，不假设命令已经执行。

### 7. 文档同步

按 [文档同步规则](50-文档同步规则.md) 判断是否存在长期知识变化：

- 公共接口、架构边界、生成流程、平台行为或稳定使用规则变化时，同步模块文档。
- 局部 Bug 修复、临时日志和实现细节不自动写入长期文档。
- 同一事实只在一个文档完整定义，其他位置链接引用。

### 8. Git

- 只有用户明确要求“提交”“commit”“推送”时才执行 Git 写操作。
- UnityAI 和目标 Unity 项目是独立仓库，分别检查、暂存、提交和推送。
- 提交前运行工作流检查、目标测试、`git diff --check` 和提交信息检查。
- 提交格式：`[模块][类型]: 描述`，类型为 `feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
- 不把两个仓库的改动描述成一个提交，也不夹带任务开始前的无关修改。

## 三、UI 专项流程

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 或小游戏路径可用；平台路径和存储回调必须分别验证。
- 下载完成计数只在单个文件完整写入并通过校验后推进。

## 五、完成检查

- [ ] 修改了真实源码，没有误改生成文件。
- [ ] 必要生成步骤已经执行并检查差异。
- [ ] 相关程序集编译通过。
- [ ] Unity Console 无本次新增错误。
- [ ] UI/Prefab 或平台行为完成实际验证。
- [ ] 长期文档按影响同步，没有写入流水账。
- [ ] 两个仓库状态分别检查，未触碰用户无关修改。
- [ ] 未经明确要求没有提交或推送。

## 文档关联

| 文档 | 关联原因 |
|---|---|
| [项目规则入口](项目规则入口.md) | 指向本工作流的快速入口 |
| [架构说明](10-架构说明.md) | 源码与生成代码边界 |
| [开发规则](20-开发规则.md) | 实施阶段的代码与 Unity 规范 |
| [文档同步规则](50-文档同步规则.md) | 完成后的长期知识同步 |
| [共享检查](../hooks/Hook共享层.md) | 工作流和提交检查脚本 |