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

工作流清单

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

一、任务分类

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

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

二、标准执行流程

1. 准备与定位

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

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

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

常用命令：

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. 文档同步

按 文档同步规则 判断是否存在长期知识变化：

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

8. Git

• Git 提交与推送规则见 项目规则入口。
• 提交前运行工作流检查、目标测试、git diff --check 和提交信息检查。
• 不把两个仓库的改动描述成一个提交，也不夹带任务开始前的无关修改。

三、UI 专项流程

1. 先读 UI 开发指南 和 界面拼接。
2. 同时检查 Prefab 层级、脚本绑定、模板节点、布局组件和数据刷新时机。
3. 单列列表使用 LoopListView2 接口，多列布局使用 LoopGridView 接口。
4. 列表初始化放在一次性生命周期，数据数量刷新放在窗口打开或数据变化时。
5. 完成后验证空数据、少量数据、超出视口、重复打开和回收重用。

四、异步与平台规则

• UnityWebRequest、StreamingAssets、CDN 和 WebGL 等待流程使用协程或回调。
• 不在主线程使用阻塞式 while、忙等或同步等待网络结果。
• Editor 可用不代表 Android、iOS、WebGL 或小游戏路径可用；平台路径和存储回调必须分别验证。
• 下载完成计数只在单个文件完整写入并通过校验后推进。

五、完成检查

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

文档关联

文档	关联原因
项目规则入口	指向本工作流的快速入口
架构说明	源码与生成代码边界
开发规则	实施阶段的代码与 Unity 规范
文档同步规则	完成后的长期知识同步
共享检查	工作流和提交检查脚本