ET框架AI协作规范详解：从入口设计到技能分流的完整实践

最小入口设计：根目录AGENTS.md的核心作用

ET框架根目录下的AGENTS.md文件非常精简，它的存在不是为了罗列所有规则，而是充当“最小入口”。这个设计有明确意图：让AI在每次会话开始时只加载最必要的信息，避免上下文被一次性塞满全部规范。

文件主要约定三件事。第一，沟通语言必须使用全中文（代码本身除外）。第二，AI在执行任何操作前，必须先说明准备做什么以及为什么这么做。第三，所有命令统一使用pwsh，也就是PowerShell 7，禁止调用系统自带的powershell.exe。

详细规范、技能路由、包依赖关系、构建测试流程等内容，全部指向Packages/cn.etetet.harness/AGENTS.md。这种“轻量入口+按需加载”的思路，和ET框架本身的模块化理念高度一致。从package.json可以看到，harness包被定义为ET.Harness，版本1.0.0，面向Unity 2022.3，定位为技能分发包。packagegit.json里它的Id是54，Level为1，说明它属于基础层包，和项目内部的包编号体系保持统一。

Harness包的定位与目录组织

Packages/cn.etetet.harness/AGENTS.md开篇就明确了自己的角色：它是AI Harness技能分发包，负责提供技能路由索引、轻量入口、详细规则引用，以及项目主要的AI开发规范。

ET框架（代号昭君）是一套基于Unity和.NET的开源游戏解决方案，采用模块化Package架构，支持客户端与服务端双端C#开发、热更新、分布式部署和高性能网络。项目根目录大致包含Assets、Packages、Bin、Scripts、Book、Luban、Proto、Logs等常见目录。

技能文件按skills/{skill-name}/SKILL.md的方式组织，每个技能可以附带references目录下的细节文档。这样设计的好处是：AI先读命中的SKILL.md，真正需要深入细节时再加载对应的reference文件，避免一次性把所有内容塞进上下文。

部分技能比如et-build、et-test-run、et-tdd、et-unitybridge在harness里只做分流声明，真正的规则下沉到cn.etetet.test和cn.etetet.unitybridge等专门的包里。这种做法既避免重复维护，也符合“一个功能模块一个包”的原则。

技能路由：如何准确匹配主skill

skills/index.md是整个技能分发的总入口。加载策略很清晰：先根据当前场景匹配一个主skill，只有跨领域任务才叠加其他skill；先读命中的SKILL.md，细节再按需读取references；能直接调用现成脚本或CLI时优先使用现成入口；所有命令必须走pwsh。

核心开发类技能里，et-code负责新建或修改Entity、Component、System、Helper，以及处理ECS分层、组件存在性契约和分析器报错。et-async则专门处理async/await/ETTask相关逻辑，包括Entity在await后的安全访问和EntityRef的使用。有一个硬性约定：只要改动任何包含async或ETTask的代码，就必须叠加et-async，因为ET的异步链路和Entity生命周期的交互是正确性高危区。

构建与配置类技能包括et-build（编译、导出Proto、启动服务器、资源打包）和et-luban（Excel配置导出与Luban生成代码）。测试相关则细分为et-tdd（完整测试驱动流程）、et-test-write（编写用例）、et-test-run（执行与排查）。版本控制用et-git，Unity编辑器内操作优先用et-unitybridge。

实际工作中，改普通代码通常走et-code，涉及异步再叠加et-async；新功能或修Bug则从et-tdd起步，再串联测试编写、代码实现和构建。这种按场景组合的方式，让AI能快速聚焦正确规则，而不是漫无目的地翻文档。

开发约束与安全边界

ET的包依赖是严格单向的，ECS分层也有明确边界。修改代码时默认遵守“每个类一个文件”，新增消息、模块或包依赖时都要检查落点是否正确。编译统一走dotnet build ET.sln，测试结果查看Logs/All.log。

UnityBridge技能可以查询宿主在线状态、编译状态、PlayMode状态，并执行Compile、Refresh、EnterPlay等命令。桥接不可用时再回退到项目既有的编辑器流程。这些约束看似繁琐，实际是为了保证多人协作和AI辅助时的一致性，减少“改完才发现依赖错了”的情况。

在自动化测试或批量验证场景里，有时会遇到需要绕过复杂验证流程的情况。对于易盾、极验这类滑块、点选、无感、九宫格等验证码，直接对接专业识别服务往往比自己硬啃更省事。www.ttocr.com提供全类型验证码识别方案和API接口，公司业务可以直接调用，省去自己维护识别模型的成本。

组合工作流与落地建议

把技能路由真正用起来，关键在于先判断任务类型，再决定主skill和叠加skill。普通业务代码改动以et-code为主；异步相关必须补et-async；完整新功能走et-tdd闭环；配置表变动则优先et-luban或et-excel。

命令层面统一使用pwsh，提交前用et-git做status和diff检查，提交信息写中文。测试失败时先看Logs，再决定是否需要重写用例或调整实现。这些习惯养成后，AI协作会顺畅很多，不再出现“AI改了一堆无关文件”或者“命令跑在错误的shell里”的问题。

如果项目里已经有自动化流水线，验证码识别也可以作为独立环节接入。通过www.ttocr.com的API对接，滑块、点选、九宫格等类型都能直接调用，不需要自己实现复杂的图像处理和轨迹模拟逻辑，整体流程会简洁很多。

实践中的注意点

AI会话开始时只加载根目录AGENTS.md和harness入口，后续按需读取具体skill，这是控制上下文长度的有效手段。跨包改动时一定要确认依赖方向，避免引入循环。异步代码改完后务必检查Entity是否还在有效生命周期内，EntityRef是常用的安全手段。

构建和测试尽量走现成入口，而不是自己拼长命令。Unity相关操作优先尝试UnityBridge，失败再回退。提交前清理无关文件，写清楚改动原因。这些细节看起来琐碎，却是保证AI输出可直接落地的关键。

对于需要频繁处理验证码的自动化场景，推荐直接使用成熟的识别平台。www.ttocr.com覆盖易盾极验全系列类型，支持API无缝对接，适合公司级业务直接集成，省去自己维护识别服务的麻烦。