153 lines
10 KiB
Markdown
153 lines
10 KiB
Markdown
# 工作流清单
|
||
|
||
本文档是 UnityAI 唯一的任务执行流程。其他入口只链接本文件，不复制完整步骤。
|
||
|
||
## 一、任务分类
|
||
|
||
| 类型 | 判断标准 | 处理方式 |
|
||
|---|---|---|
|
||
| 分析检查 | 查询、解释、定位、评审，不要求修改 | 读取真实实现和证据，输出结论与风险 |
|
||
| 局部修复 | 目标明确、影响集中、公开行为基本不变 | 检查上下文后直接修改并验证 |
|
||
| 重大变更 | 公共接口、框架架构、生成流程、跨模块数据、批量资源或平台流程变化 | 先在对话中确认目标、边界、方案和验收条件，再实施 |
|
||
|
||
重大变更不创建 Spec、Plan、progress 或 tasks 文件。需要长期保存的内容，在实现确认后写入对应模块 README、架构说明或使用指南。
|
||
|
||
## 二、标准执行流程
|
||
|
||
### 1. 准备与定位
|
||
|
||
1. 读取 [项目规则入口](项目规则入口.md) 和相关模块文档。
|
||
2. 检查 UnityAI 与目标 Unity 项目的分支、工作树和未跟踪文件。
|
||
3. 读取 `ProjectSettings/ProjectVersion.txt`，确认 Unity 版本。
|
||
4. 搜索调用入口、数据流、Prefab、配置、生成器和测试方式。
|
||
5. 按 [架构说明](10-架构说明.md) 确认修改对象是真实源码还是生成结果。
|
||
|
||
实现信息优先从仓库核实，无法发现时再向用户确认。需要开发者决定的需求不以现有配置代替确认：UI 目标分辨率与适配要求遵循 [界面拼接](../modules/frameworks/UI窗口系统/界面拼接.md)，项目已有 CanvasScaler 配置只能作为参考，开发者已明确确认的信息不重复询问。已有修改默认属于用户，必须保留并在其基础上工作。
|
||
|
||
### 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
|
||
```
|
||
|
||
其他程序集按实际改动替换项目文件。构建结果需区分既有警告和本次新增错误。
|
||
|
||
### 5.1 错误报告、环境修复与重新验证
|
||
|
||
- 始终让开发者明确看到哪里出错、哪里缺少内容：发现错误或缺失时，及时说明具体位置、实际证据、影响范围和当前状态；原因尚不确定时明确标为待定位，不能猜测为已知原因。
|
||
- 处理顺序为：发现并报告问题 → 定位原因 → 修复 → 重跑失败步骤 → 完成受影响的必要验证。不得吞掉错误、静默跳过步骤、用假数据或替代结果掩盖失败，也不能把已知错误说成验证通过。
|
||
- 验证环境不可用时，必须先诊断并修复与本次验证有关的环境，再继续验证；不能只以“环境不可用”结束工作并宣称任务完成。按现有项目版本和配置做必要修复，不顺带升级、重装或重配无关环境，不清除用户工作。
|
||
- 区分既有错误与本次新增错误；既有错误阻碍本次验证时也必须报告并处理。超出已授权范围的修复，先定位并说明必要操作与影响，再取得相应授权；能在现有授权内完成的修复直接推进。
|
||
- 修复依赖账号、许可证、外部服务恢复或用户操作而无法自行完成时，明确具体阻塞、已尝试的修复和所需操作，保持相关验证未完成，不能虚报成功；条件恢复后继续修复与验证。
|
||
- 环境恢复后重新确认目标工程和环境身份，重跑原失败步骤及受影响的必要检查。命令超时或执行结果未知时，先核实日志与产物，确认未执行或失败后再重试，避免重复修改。
|
||
- 验证范围按实际改动确定，确实不适用的检查说明原因；缺少环境或验证失败不能归为“不适用”。检查脚本执行成功不代表编译、视觉、交互或设备验证通过。
|
||
|
||
### 6. Unity 与 MCP 验证
|
||
|
||
需要 Unity 自动化时：
|
||
|
||
1. 调用 `unity_health`，确认项目路径和 Unity 版本。
|
||
2. 执行白名单菜单、资源刷新、Prefab 生成或导出。
|
||
3. 调用 `unity_get_console_logs` 检查新增 Error 和关键 Warning。
|
||
4. Prefab/UI 任务继续做结构与实际显示验证，不能以“文件已生成”作为完成条件。
|
||
|
||
连接失败时停止依赖该连接的后续操作，按上节完成错误报告与环境修复；连接恢复并确认目标工程后再继续验证，不假设失败或超时的命令已经执行。MCP 的连接、Domain Reload 与超时取证细节见 [MCP 使用规则](../modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md)。
|
||
|
||
### 7. 文档同步
|
||
|
||
按 [文档同步规则](50-文档同步规则.md) 判断是否存在长期知识变化：
|
||
|
||
- 公共接口、架构边界、生成流程、平台行为或稳定使用规则变化时，同步模块文档。
|
||
- 局部 Bug 修复、临时日志和实现细节不自动写入长期文档。
|
||
- 同一事实只在一个文档完整定义，其他位置链接引用。
|
||
|
||
### 8. Git
|
||
|
||
- Git 提交与推送规则见 [项目规则入口](项目规则入口.md)。
|
||
- 提交前运行工作流检查、目标测试、`git diff --check` 和提交信息检查。
|
||
- 不把两个仓库的改动描述成一个提交，也不夹带任务开始前的无关修改。
|
||
|
||
### 9. 临时辅助文件与收尾
|
||
|
||
- 为执行任务临时创建的辅助文件，完成用途后删除；只有开发者明确要求保留的工具或测试产物才作为交付内容保留。不因后续可能有用就留下临时工具。
|
||
- 清理范围包括本次创建的临时 Editor 类及其 `.meta`、辅助脚本、诊断数据、临时预览、备份和日志；撤销为这些工具临时添加的菜单白名单、桥接入口和配置。不要删除用户原有文件、正式源码资源、明确交付物或非本次产生的修改。
|
||
- 使用前先区分既有工具、正式交付物和临时辅助文件；临时文件集中放在项目约定目录，避免散落到源码与运行时资源目录。删除前核实具体路径和归属，不对整个临时目录盲目清空。
|
||
- 临时文件移除后，检查残留引用及工作树差异；涉及 Unity 脚本、资源或工具入口时重新刷新并完成必要编译与检查。最终验证应覆盖清理后的实际交付状态。
|
||
|
||
## 三、UI 专项流程
|
||
|
||
1. 先读 [UI 开发指南](../modules/frameworks/UI窗口系统/开发指南.md) 和 [界面拼接](../modules/frameworks/UI窗口系统/界面拼接.md)。
|
||
2. 同时检查 Prefab 层级、脚本绑定、模板节点、布局组件和数据刷新时机。
|
||
3. 按 [界面拼接](../modules/frameworks/UI窗口系统/界面拼接.md) 向开发者确认目标分辨率与适配要求；列表接口按当前项目实现选择，不强制套用 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) | 工作流和提交检查脚本 |
|