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

工作流清单

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

一、任务分类

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

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

二、标准执行流程

1. 准备与定位

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

实现信息优先从仓库核实，无法发现时再向用户确认。需要开发者决定的需求不以现有配置代替确认：UI 目标分辨率与适配要求遵循 界面拼接，项目已有 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、失败回退和日志

常用命令：

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 使用规则。

7. 文档同步

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

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

8. Git

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

9. 临时辅助文件与收尾

• 为执行任务临时创建的辅助文件，完成用途后删除；只有开发者明确要求保留的工具或测试产物才作为交付内容保留。不因后续可能有用就留下临时工具。
• 清理范围包括本次创建的临时 Editor 类及其 .meta、辅助脚本、诊断数据、临时预览、备份和日志；撤销为这些工具临时添加的菜单白名单、桥接入口和配置。不要删除用户原有文件、正式源码资源、明确交付物或非本次产生的修改。
• 使用前先区分既有工具、正式交付物和临时辅助文件；临时文件集中放在项目约定目录，避免散落到源码与运行时资源目录。删除前核实具体路径和归属，不对整个临时目录盲目清空。
• 临时文件移除后，检查残留引用及工作树差异；涉及 Unity 脚本、资源或工具入口时重新刷新并完成必要编译与检查。最终验证应覆盖清理后的实际交付状态。

三、UI 专项流程

1. 先读 UI 开发指南 和 界面拼接。
2. 同时检查 Prefab 层级、脚本绑定、模板节点、布局组件和数据刷新时机。
3. 按 界面拼接 向开发者确认目标分辨率与适配要求；列表接口按当前项目实现选择，不强制套用 LoopListView2 / LoopGridView。
4. 列表初始化放在一次性生命周期，数据数量刷新放在窗口打开或数据变化时。
5. 完成后验证空数据、少量数据、超出视口、重复打开和回收重用。

四、异步与平台规则

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

五、完成检查

• 修改了真实源码，没有误改生成文件。
• 必要生成步骤已经执行并检查差异。
• 相关程序集编译通过。
• Unity Console 无本次新增错误。
• UI/Prefab 或平台行为完成实际验证。
• 错误、缺失和阻塞均已明确报告；必要的环境修复及重新验证已完成，没有把未完成或失败的检查当作通过。
• 长期文档按影响同步，没有写入流水账。
• 本次临时辅助文件和临时工具入口已清理；明确要求保留的工具或测试产物已说明，清理后的最终状态完成必要验证。
• 两个仓库状态分别检查，未触碰用户无关修改。
• 未经明确要求没有提交或推送。

文档关联

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