ET 框架 AI 技能体系（ET Skills）深度指南：加载策略、任务入口与组合流程

ET 框架 AI 技能体系ET Skills深度指南加载策略、任务入口与组合流程【免费下载链接】ETUnity3D Client And C# Server Framework项目地址: https://gitcode.com/GitHub_Trending/et/ET导读本文档基于 ETUnity3D Client And C# Server Framework仓库中的技能索引 Packages/cn.etetet.harness/skills/index.md 展开系统讲解这套面向 AI Agent编程助手/LLM 工具链的Skills 技能路由体系它用场景匹配 → 按需加载 → 最小化上下文的方式把 ET 框架中代码编写、异步安全、构建导出、Luban 配置、Excel 操作、测试驱动、Git 提交、Unity 编辑器桥接等高频开发任务拆解成et-code、et-async、et-luban、et-test-run等一组可独立加载的技能文件。读完本文你将掌握这套索引的加载策略、每个技能的适用场景与默认动作、底层代码规范ECS 分层、EntityRef 异步安全、包依赖规则以及如何把多个技能组合成一条完整的开发流水线。一、ET Skills 索引是什么ET 仓库的Packages/cn.etetet.harness包内维护了一套技能Skills体系。与把海量文档一次性喂给 Agent 不同这套体系采用先读索引、按需加载的策略索引文件Packages/cn.etetet.harness/skills/index.md 只负责分流禁止一次性读取全部 skill 正文技能正文每个技能是一个SKILL.md说明何时使用、不要加载、默认动作、快速分流、输出要求细节参考技能内部再按需读取references/*.md存放更细的规则与示例。这样的分层设计使 Agent 在任意任务中只加载当前场景命中的技能 必要参考把上下文占用降到最低同时保证每个技能文件本身自洽、可独立被检索和引用。技能文件在仓库中的实际落点类别文件路径相对仓库根目录技能索引Packages/cn.etetet.harness/skills/index.md核心开发技能Packages/cn.etetet.harness/skills/et-code/SKILL.md、Packages/cn.etetet.harness/skills/et-async/SKILL.md构建与导出技能Packages/cn.etetet.harness/skills/et-build/SKILL.md、Packages/cn.etetet.harness/skills/et-luban/SKILL.md数据与提交技能Packages/cn.etetet.harness/skills/et-excel/SKILL.md、Packages/cn.etetet.harness/skills/et-git/SKILL.md技能细节参考skills/*/references/*.md如 et-code-rules.md、et-async-rules.md测试分流Packages/cn.etetet.test/AGENTS.mdUnity 桥接分流Packages/cn.etetet.unitybridge/AGENTS.md二、加载策略索引文件的 7 条铁律索引文件开篇即强调先读本文件禁止先完整读取所有 skill 正文随后给出 7 条加载策略是整个技能体系的运行准则场景匹配一个主 skill先用场景匹配 1 个主 skill只有跨域任务才叠加其它 skill。避免一次加载全部技能控制上下文规模。分层补读先读命中的SKILL.mdharness 内技能位于skills/{skill-name}/SKILL.md包内专属技能按索引给出的包路径读取需要细节时再读该 skill 的references/*.md。优先现成入口能直接调用现成脚本或 CLI 时优先现成入口不重复展开长命令。例如 Luban 导出直接使用dotnet ./Bin/ET.ExcelExporter.dll而不是手工拼接命令。命令统一使用pwsh所有命令必须使用pwshPowerShell 7绝对不要使用 Windows 自带的powershell.exe。这与仓库 Scripts 目录下的Publish.ps1、Launch.ps1等脚本面向 PowerShell 7 的定位一致。测试任务三选一完整 TDD 用et-tdd只写测试用et-test-write只执行或排查测试用et-test-run命中后读取 Packages/cn.etetet.test/AGENTS.md由 test 包说明继续分流到具体 skill。Unity 编辑器操作走桥接涉及 Unity 编辑器内操作时优先使用et-unitybridge命中后读取 Packages/cn.etetet.unitybridge/AGENTS.md 继续分流若桥接工具不可用再回退到项目既有编辑器流程。一类一文件修改或新增 C# 代码时默认遵守每个类一个文件除天然绑定的极小枚举/结构外不要把多个类塞进同一个.cs。第 7 条与et-code的代码规范高度一致详见下文文件与包落点这是从加载策略到编码规范的全链路约束。三、任务入口总览索引按职责把 11 个技能入口分为五类便于 Agent 按任务类型快速定位主 skill分类技能核心场景核心开发et-codeEntity / Component / System / Helper、包依赖、程序集、Handler 结构、组件契约、Module analyzer、新建或移动 C# 文件核心开发et-asyncasync/await/ETTask/ETCancellationToken、EntityRefawait 安全、NewContext(...)、并发等待Unity 编辑器操作et-unitybridge查询 Unity 心跳/状态、操作 Editor、触发编译/刷新/PlayMode/热更新 Reload构建与导出et-build编译dotnet build ET.sln、导出 Proto、启动服务器、发布构建与导出et-luban导出 Luban 生成的 C# 配置/数据代码、刷新聚合luban.conf、排查导出失败测试验证et-tddTDD 驱动开发、完整测试闭环测试验证et-test-write编写/修改ATestHandler测试用例、补Test.md测试验证et-test-run执行测试、查看Logs/All.log、调试失败、回归验证数据与提交et-excel通过ET.ExcelMcp读写 Excel、维护 Luban 配置表数据与提交et-git提交前检查、整理 diff、中文提交信息、rebase 同步下面按分类逐一展开每个技能的内容与底层实现细节。四、核心开发et-code与et-async4.1et-codeET 代码编写与审查入口何时使用新建或修改Entity、Component、System、Helper新建或修改MessageLocationHandler、MessageHandlerT、MessageSessionHandler新建或移动 C# 文件、检查.meta、程序集与包内落点新增消息、模块、程序集或包依赖处理 ECS 分层、组件存在性契约、Module analyzer、分析器报错。不要加载只是执行测试、导出配置或操作 Excel只做 Unity 编辑器操作应使用et-unitybridge。默认动作SKILL.md 原文先确认改动所在 package、程序集层级和包内AGENTS.md规则检查代码是否位于Packages/cn.etetet.*并确认是否需要关注packagegit.json、PackageType.cs先判断 Entity / System 分离、HandlerRun规范、包依赖单向、Module analyzer、禁止 hard code 是否受影响新增组件或判空前先确认组件存在性契约按设计必然存在的组件不要偷偷兜底创建涉及async/await/ETTask/EntityRef时叠加et-async新建类前优先复用现有结构默认一类一文件严禁 AI 手工生成.meta或手工修改.csproj移动 C# 文件时必须同步移动对应.meta以保留 GUID严禁为注册表、缓存、映射关系随手新增静态可变字段先确认生命周期与 owner。输出要求说明代码落点、包依赖、程序集层次是否正确是否影响.meta、.csproj、Unity 刷新或工程文件生成是否影响EntityRef/await安全、HandlerRun规范是否引入新的 analyzer 风险、静态状态风险或模块边界问题。4.1.1 文件与包落点规则et-code-rules.md 细化了文件摆放规范包命名cn.etetet.{模块名}所有代码必须在Packages/cn.etetet.*下每个包必须有packagegit.jsonId 全局唯一、Scripts/Model/Share/PackageType.cs编号与 Id 一致、包内AGENTS.mdModel 层Scripts/Model/或Scripts/ModelView/Hotfix 层Scripts/Hotfix/或Scripts/HotfixView/新建 C# 文件不手工创建.meta由 Unity 自动生成移动 C# 文件必须同步移动.meta保证 GUID 不变严禁手工修改.csproj需要刷新工程文件时通过 UnityBridge 或项目既有 Unity 流程。4.1.2 ECS 分离与静态状态Entity/Component只包含数据禁止业务方法System静态 partial 类包含逻辑通过静态扩展方法实现复杂业务逻辑放XXXHelper不要无边界扩散进 SystemSingleton 类如RobotCaseDispatcher可以包含方法不需要额外创建 System跨实体、跨模块、跨流程的编排优先抽到XXXHelper禁止为省事新增static Dictionary/static List/static HashSet/ 静态缓存字段或全局可变状态Attribute 扫描结果、节点注册表、配置缓存等必须有明确 ownerowner 优先使用SingletonT、框架已有 Dispatcher、配置 Category、Scene/Fiber 组件或专门管理组件静态只读常量必须是不可变数据在热重载、测试隔离、多 Fiber、多 Scene 场景下进程级静态状态默认视为风险点。4.1.3 组件存在性契约与 Handler Run组件来源必须清楚由FiberInit_*预创建、当前方法AddComponentT()创建或业务上本来可选组件按设计必须存在时直接使用缺失应暴露 bug不要偷偷补齐只有业务上确实可选的组件才允许判空分支新增if (x null)、ThrowIfNull、?? throw、GetComponentT() ?? AddComponentT()前先确认是否真有合法为空路径TimerComponent、CoroutineLockComponent这类在Awake已回写Scene的组件AddComponent后不要再手工回填引用MessageLocationHandler/MessageHandlerT/MessageSessionHandler的Run入口无需额外判空实体如有await必须在await后通过EntityRef重新获取再使用。4.1.4 包依赖规则与 Module analyzer包之间只能单向依赖不能循环A 依赖 BB 永远不能反向访问 A依赖变更时递归补齐跨包访问必须显式声明依赖只能高层包依赖低层包遇到模块双向耦合时优先拆公共 Helper、公共消息或把调用入口上移到更高层Module analyzer类可通过Module(ModuleName.X)声明模块未标注时默认属于GlobalA 模块调用 B 模块的方法后B 模块不能反向调用 AA 也不能直接读 B 的字段分析器报错先看模块边界、程序集落点、包依赖方向再动代码消息类字段统一使用PascalCase命名空间按 package 组织避免重复定义同名类。4.2et-async异步与 EntityRef 安全入口ET 框架的异步基于ETTask类似 .NET 的Task但专为游戏框架设计。由于await会跨越 Fiber 协程调度边界await后不能直接复用旧Entity变量这是 ET 异步编程最重要的一条红线。et-async技能正是围绕这条红线建立的审查流程。何时使用新增、修改或 reviewasync/await/ETTask/ETTaskT判断某段逻辑是否应该异步化或改回同步处理await后Entity访问、EntityRefT、HandlerRun异步安全设计并发等待、ETTask.WaitAll(...)、ETCancellationToken、NewContext(...)。不要加载代码完全同步且不涉及异步边界、安全或取消控制只是编译、导出、跑测试、操作 Unity / Excel。默认动作SKILL.md 原文先判断是否真的需要异步并明确谁在等待返回值只有 RPC、IO、定时器、协程锁、跨 Fiber 结果或其它真实异步资源才保留async/ETTask调用方不依赖返回值时优先改成同步方法、普通消息、Send或独立协程只要存在await后继续访问 Entity 的路径就在await前创建EntityRefT并在await后重新获取函数参数可以传 Entity字段、属性、集合中保存EntityRefT不要长期持有 Entity在消费结果的协程里直接await不要设计返回一个ETTask句柄后面再 await的桥接层NewContext(...)只承担独立协程与取消边界需要携带实体时使用EntityRefT。4.2.1 EntityRef 正误示例et-async-rules.md 给出了可直接套用的代码模板正确写法 —— await 前后通过 EntityRef 重建引用public static async ETTask ProcessUpdate(this UpdateCoordinatorComponent self, UpdateTask task) { EntityRefUpdateCoordinatorComponent selfRef self; EntityRefUpdateTask taskRef task; await SomeAsyncOperation(); self selfRef; task taskRef; task.UpdateProgress(done); }正确写法 —— 集合中保存 EntityRef 而非 Entitypublic class SomeComponent : Entity, IAwake { public Dictionaryint, EntityRefProcessInfo ProcessDict { get; set; } }错误写法三连踩坑// 错误 1await 后直接访问旧实体 await SomeAsyncOperation(); self.DoSomething(); // 错误 2用 .Entity 属性手动拆包访问应直接赋值 ProcessInfo process processRef.Entity; // 错误 3集合中长期持有裸 Entity public ListProcessInfo Processes { get; set; }4.2.2 并发等待、取消与边界并发等待为每一路启动独立收集协程内部直接await外层只负责触发、ETTask.WaitAll(...)和汇总不要先返回多个未消费ETTask再在远处补 await并发结果需要实体时收集协程内部同样使用EntityRefTETCancellationToken只表达取消或超时不承载业务状态NewContext(...)只用于启动独立协程并传递取消边界不要把Scene、Unit等 Entity 当 context 透传需要跨协程携带实体时传EntityRefT或稳定 Id再重新查实体Handler 与测试同规则HandlerRun有await时同样必须用EntityRef重新获取测试协程、普通系统方法、Helper 方法都遵守同一套规则不因入口是 Handler、测试或临时工具而放宽实体安全常见错误还包括返回ETTaskETTaskT、写RunXxx ETTask.Create SetResult中转封装、把 Entity 塞进NewContext(...)或等待结果对象、为了接口统一提前异步化。五、Unity 编辑器操作et-unitybridgeet-unitybridge是 harness 索引中指向Unity 本地文件桥接包的技能。按 Packages/cn.etetet.unitybridge/AGENTS.md 的说明该包由三部分组成路径说明DotNet~纯命令行ET.UnityBridge含ET.UnityBridge.csproj与命令行入口Scripts/EditorUnity Editor 文件宿主汇入ET.Editor承载宿主、处理器与分发逻辑Scripts/Model/Share桥接命令、错误码、路径与共享文件协议技能使用场景查询 UnityBridge 宿主是否在线、Unity 是否正在编译、PlayMode 状态、CodeMode、Unity 版本AI 操作 Unity Editor资源、场景、选择集、GameObject、Transform、Inspector、Prefab、菜单、截图、GameView、Editor 测试执行Compile/Refresh/RegenProject/EnterPlay/ExitPlay/Reload等跨 Unity 状态变化的命令排查 UnityBridge 返回的Error/Message。加载策略命中et-unitybridge后读取 Packages/cn.etetet.unitybridge/AGENTS.md由 unitybridge 包说明继续分流到具体 skill架构规范看et-code、编译构建看et-build若桥接工具不可用再回退到项目既有编辑器流程。六、构建与导出et-build与et-luban6.1et-build编译、Proto 导出、服务器启动与发布何时使用编译项目、导出 Proto 文件.proto→ C#、启动服务器、发布版本。不要加载只是改代码、写测试还没到编译环节只是导出 Luban 配置用et-luban只是查询架构规范或包依赖用et-code。默认动作编译和分析器验证统一使用dotnet build ET.sln不单独编译包或 IDE 私有方案服务器必须在Unity 项目根目录启动不在Bin/目录启动运行服务器前先清理旧Logs/方便排查Model / Hotfix 程序集不能用 IDE 编译必须走项目规定的 Unity / ET 编译入口。优先入口命令原样保留可直接执行# 编译整个解决方案唯一编译入口 dotnet build ET.sln # 导出 Proto.proto - C# dotnet ./Bin/ET.Proto2CS.dll # 启动服务器--Console1 表示控制台模式 dotnet ./Bin/ET.App.dll --Console1 # 发布PowerShell 7绕过执行策略 pwsh -ExecutionPolicy Bypass -File ./Scripts/Publish.ps1需要细节时补读et-build的 references 文档Luban 配置导出转et-luban测试执行路由到 Packages/cn.etetet.test/AGENTS.md。6.2et-lubanLuban 配置导出入口何时使用导出 Luban 生成的 C# 配置代码与 C# 数据代码修改Packages/cn.etetet.*/Luban/**、__tables__.xlsx、__beans__.xlsx、__enums__.xlsx、Defines/后重新导出刷新聚合后的luban.conf排查ET.ExcelExporter、LubanGen.ps1、luban.conf导出失败核对导出后的CodeMode/Model/**与CodeMode/Config/**。不要加载只是读取/写入 Excel 单元格、批量改表用et-excel只是编译、导出 Proto、启动服务器、发布用et-build只是查询 Unity 编辑器状态用et-unitybridge。默认动作命令必须在项目根目录执行避免Packages/相对路径和LubanGen.ps1定位错误当前 Luban 脚本统一走cs-code与cs-code-data导出结果是 C# 代码不是 json 或二进制导出前先区分改表和生成产物只改表时先用et-excel导出过程会扫描Packages/cn.etetet.*/Luban/*并刷新聚合luban.conf导出后检查控制台、生成结果与 diff区分真实配置变化和自动聚合变化。优先入口# 命令行入口 dotnet ./Bin/ET.ExcelExporter.dll # Unity 菜单入口 ET/Excel/ExcelExporter细节导出流程、结果落点、常见失败排查补读references/et-luban-export.md。在仓库中可以找到对应的配置表源例如 cn.etetet.startconfig/Luban含__tables__.xlsx、luban.conf、LubanGen.ps1等以及各业务包的Luban/目录。七、测试验证et-tdd/et-test-write/et-test-run三个测试技能只负责分流命中测试任务后按需读取 Packages/cn.etetet.test/AGENTS.md 中对应的补读路径不要一次性加载全部测试规则技能使用场景et-tdd测试驱动方式开发新功能或修复 Bug需要完整需求 → 测试方案 → 测试用例 → 实现 → 编译 → 运行 → 回归闭环叠加et-test-write、et-test-run涉及业务代码时叠加et-codeet-test-write编写新的ATestHandler测试用例、修改现有用例、补Test.md或最小验证清单et-test-run执行测试全部/指定用例、查看测试日志与失败原因、验证修改后代码通过目标测试或回归7.1 test 包的底层实现Packages/cn.etetet.test/AGENTS.md 说明这是通用测试用例包基于ConsoleMode.Test运行按[Test]特性自动发现并分发到对应处理器执行支持按包名与用例名的正则过滤批量执行。其核心类如下文件说明TestConsoleHandler.cs控制台处理器解析命令并进入测试模式TestDispatcher.cs按包名与处理器名正则筛选匹配的测试用例ATestHandler.cs测试基类约定Handle(...)接口FiberInit_TestCase.csTestCase场景初始化每个用例均为全新服务器环境TestArgs.cs命令行参数定义ITestHandler.cs测试处理器接口结合et-code的异步规则测试协程同样适用EntityRef安全约束——不因入口是 Handler、测试或临时工具而放宽实体安全。八、数据与提交et-excel与et-git8.1et-excel通过 ET.ExcelMcp 读写 Excel何时使用通过Bin/ET.ExcelMcp.dll读写 Excel处理单元格、区域、样式、公式、图表、工作表批量数据导入导出、筛选、排序、合并单元格维护 Luban 配置表内容但还没有进入导出阶段。不要加载只是编译、跑测试、做 Unity 编辑器操作只是执行 Luban 导出用et-luban只是讨论表结构。默认动作先cli list或cli help 工具名不要硬背完整工具表能批量就批量优先excel_range/excel_data_operations不要逐格操作JSON 参数只传本次调用最小字段集pwsh中优先外层单引号写操作优先使用绝对路径覆盖原文件前先确认目标文件改完表如果需要生成配置产物再叠加et-luban。优先入口命令# 列出可用工具 dotnet ./Bin/ET.ExcelMcp.dll cli list # 查看某个工具的用法 dotnet ./Bin/ET.ExcelMcp.dll cli help 工具名 # 执行工具JSON 参数外层单引号 dotnet ./Bin/ET.ExcelMcp.dll cli 工具名 JSON参数细节工具选择、pwshJSON 传参、常用示例补读references/et-excel-cli.md。工作流上et-excel负责改表et-luban负责导出产物两者通常按顺序衔接。8.2et-git提交准备与变更审查该技能有一条红线禁止直接使用git pull。远端同步必须使用git pull --rebase或先git fetch再git rebase。若与远端冲突只能用rebase处理禁止merge。何时使用准备提交本次改动检查git status、git diff、git diff --staged筛除日志、临时文件、自动生成文件和无关改动编写中文commit message拆分提交、整理暂存区、审查提交范围、与远端同步。不要加载只是改代码、跑测试、导出配置还没进入交付阶段只是查看项目背景或架构规范。默认动作先看git status --short与git diff --stat确认影响范围只保留本次任务相关改动排除Logs/、临时文件、无关自动生成文件和无关文件如果本次任务需要提交.meta、导出结果或生成代码则保留对应文件并说明原因准备提交前再看git diff与git diff --staged确认没有混入无关改动提交信息统一使用中文优先写成动作 对象 影响范围/原因风险操作拆分提交、回滚、cherry-pick、rebase先说明影响再执行。优先入口命令git status --short、git diff --stat、git diff、git diff --staged、git pull --rebase、git fetch、git rebase。细节提交前检查、变更筛选、中文提交信息、rebase 规范与风险操作补读references/et-git-workflow.md。九、组合场景把技能串成完整流水线索引文件给出的组合场景是这套体系真正的落地形态——单一技能解决单一问题组合技能解决完整任务任务技能流水线改普通 ET 代码et-code→ 涉及异步叠加et-async→ 必要时et-build/et-test-run创建新功能或修 Buget-tdd→et-test-write→et-code→et-build→et-test-run只做异步链路梳理或 reviewet-async→ 必要时et-code架构合规检查et-code做 Unity 编辑器内操作et-unitybridge→ 确认就绪后执行对应操作改配置表并导出et-excel→et-luban→ 必要时et-build只做 Luban 导出et-luban只做编译 / Proto / 运行 / 发布et-build只执行测试或排查测试失败et-test-run准备提交或审查 diffet-git完成开发准备提交对应开发 skill → 必要时et-build/et-test-run→et-git以创建新功能或修 Bug为例完整闭环为et-tdd设计测试方案 →et-test-write编写ATestHandler用例 →et-code按 ECS 分层与包依赖规则实现 →et-build用dotnet build ET.sln编译验证 →et-test-run执行并查看Logs/All.log回归。若涉及异步链路在实现环节叠加et-async确保EntityRef安全。十、设计理念与使用要点上下文最小化索引先分流命中才读SKILL.md需要细节才读references/*.md避免把整套开发规范一次性灌入 Agent 上下文约定优于记忆Agent 不必背熟所有工具表与命令通过cli list、cli help、references按需获取安全红线显式化pwsh强制、禁止git pull、禁止手改.meta/.csproj、禁止静态可变状态、禁止await后复用旧 Entity——这些红线以技能规则的形式固化降低 AI 编码出错概率可组合、可回退技能之间按主 skill 叠加 skill组合UnityBridge 不可用时回退到项目既有流程保证工具链有兜底。这套技能体系与 ET 框架的 ECS 架构、ETTask异步模型、Luban 配置流水线深度耦合是理解 ET 工程规范与 AI 辅助开发工作流的重要入口。如需深入某个技能按索引分层补读对应 SKILL.md 与 references 即可。【免费下载链接】ETUnity3D Client And C# Server Framework项目地址: https://gitcode.com/GitHub_Trending/et/ET创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考