用途
在由智能体驱动的 UE5 工作中,最昂贵的失败往往不是代码写得差,而是智能体凭空发明模块名、假定引擎版本、针对一个并未启用的插件写三个文件。每一次猜测单独看都很便宜,但会叠加放大。本技能的做法是把项目事实外部化到一个文件里,让每个技能在行动之前都先读取它。
主要能力
- 先建立契约:发现而非假设。引擎版本、引擎安装路径和插件状态来自在本机运行的命令,不来自先验知识。在 macOS 上,通过 ue5-macos-apple-silicon 获取这些信息。
- 写入事实文件:使用 references/context-template.md 将事实写入 .agents/ue5-project-context.md。一个文件,放在仓库根目录,纳入版本控制。
- 声明模块依赖方向:不仅声明模块名称,还要声明模块之间的依赖方向。表现层不得驱动模拟层。详见 references/module-boundaries.md。
- 一次性声明单位与约定:厘米、秒、度,以及项目使用的每一种换算(节、米、千米)。单位漂移是载具类项目中静默玩法 bug 的首要来源。
- 记录阶段禁用项:把由 ue5-phase-bans 决定的阶段禁用项记录到该文件中。本技能负责该行的格式以及该章节的存在,但不决定其中应放什么。如果没有这一章节,一个加载了优秀复制技能的智能体就会“好心”地给单人原型加上复制功能。
- 只记录实际运行过的命令:附带真实的绝对路径和最后成功日期。一份看起来合理但未经验证的命令手册比没有手册更糟。
- 在漂移时重新校验:引擎升级、插件变更或命令失败都会使该文件失效。过时的上下文正是本技能在缺乏维护时会制造出来的失败模式;应把 last_verified 视为承重字段。
使用方式
仅按需加载:
- references/context-template.md — 要写入的文件模板。
- references/module-boundaries.md — 拆分模块并保持依赖方向单向。
- 关于禁用什么以及何时解除,加载 ue5-phase-bans。本技能只存储结果。
当本技能触发时,返回以下答案格式:
- 发现的事实 — 引擎版本、引擎路径、编辑器目标、平台与架构,每一项都附上产生它的命令。
- 模块表 — 名称、职责、允许的依赖(单向)。
- 单位与约定 — 换算写清楚。
- 插件状态 — 对项目打算使用的每个插件:已启用 / 可用但关闭 / 不存在。
- 阶段禁用项 — 被禁用的系统、原因,以及可重新考虑的阶段。
- 已验证命令 — 命令、用途、最后成功日期。
- 未知项 — 每一个无法验证的事实,标记为未验证,并附上人类必须运行的命令。
硬性规则
- 绝不写入任何不是从本机或本仓库读到的引擎路径、版本或模块名。如果发现失败,写“未验证”并停止,不要用看似合理的默认值填补空白。
- 上下文文件陈述事实与禁用项,不是教程。如果超过约 200 行,它就已经变成了文档;应把叙述性内容移出。
- 依赖方向是单向的。UI 和 VFX 模块可以读取模拟状态;模拟模块不得引用 UI 或 VFX 类型。这里的循环依赖不是风格问题——它会让模拟无法在无头模式下测试,从而破坏 ue5-deterministic-sim-tests。
- 由玩法调优的配置(操控、伤害、散布、AI 参数)应放在可 diff 的数据中——Data Assets、Data Tables、CSV 或 JSON——而不是 C++ 常量,也不是蓝图图表。在上下文文件中说明所选格式。
- 蓝图可以组装场景并绑定 UI。任何决定比赛结果的规则都不得只存在于蓝图图表中;智能体无法对其做 diff 或测试。
- 阶段禁用项优先于已安装的技能。如果加载的技能推荐了被禁用的系统,以禁用项为准,并记录该冲突。裁决流程见 ue5-phase-bans。
验证
当一个新的智能体仅凭该仓库、没有任何对话历史,就能运行所列的构建与冒烟命令,并无需提问即可到达可运行的编辑器或打包构建时,上下文文件才算正确。请字面地测试这一点:开启一个新会话,把文件交给它,数一数它问了多少个问题。它不得不问的每一个问题,都是缺失的一行。
适用范围
本技能不自行发现工具链(由平台技能负责),不选择玩法架构,也不涵盖源代码管理或 CI 配置。