【免费下载链接】skills
Get production-ready images, video, audio, and 3D from any AI agent: skills that pick the right model, price before spending, and keep characters and brands consistent through the Scenario MCP, plus expert teams that drive Blender, Maya, ZBrush, Unreal, and Unity.
在 Unreal Engine 5.8 上让 Agent 动手改资产、跑离线任务、判断渲染结果，最大的风险在于模型把教程中的旧写法、含糊的默认值或自己的推测当成事实，而“记错了”本身并不是最大风险。scenario-unreal-expert 用一份专门的来源文件 references/sources.md 来解决这个问题：它把技能里每一条专家结论、版本事实和默认值都锚定到一场演讲的具体时间戳、一页官方文档或一次本机观测上。本文以这份文档为主体，拆解它的目录约定、表格字段语义、证据分级方式与修订机制，并结合仓库里的 scripts/ 与 tests/ 说明这些来源如何真正落到可执行代码中。
一、这份文档解决的是什么问题
sources.md 的标题是“Sources behind scenario-unreal-expert”，也就是“这个技能背后的来源”。它只负责一件事：交付一份可核对的来源清单，用来回答“这句话凭什么成立”。它不讲解 Unreal 用法。
这一点决定了全文的骨架：文档由一个前置说明段、一张“专家与演讲”主表、一份官方文档清单、一条项目观测记录和一段修订历史构成。它服务三类读者：
- 写技能的人：新增一条规则时，必须先找到来源，再把来源登记进这张表；
- 评审者：抽查任意一条结论，就能顺着表格的时间戳回看原始素材；
- 使用技能的 Agent：在报告里需要写清“每个工具调用背后对应的引擎调用”，并区分 Verified 与 Assumed 两类结论（详见 references/toolkit-map.md）。
关键约束写在开头第一段：逐源专家笔记存放在“项目的 notes/”里，并且从不为了迁就技能而改写（never edited to fit this skill）。这句话确立了单向关系：笔记是原始证据，技能文本只是加工产物；加工出错时改技能，不改证据。
二、文档引用的四层来源结构
sources.md 开头用四行话勾勒出一套分层目录。需要说明的是，这些目录属于技能作者的构建项目，并不在当前仓库的 skills/game-engines/unreal/scenario-unreal-expert/ 目录下；当前仓库该目录只有 references/、scripts/ 与 SKILL.md。理解这个边界很重要，否则会误以为仓库里缺失文件。
| 层级 | 路径 | 内容 | 在文档中的角色 |
|---|---|---|---|
| 逐源笔记 | notes/python/、notes/editor-tools/、notes/pipeline/、notes/profiling/ | 每个来源一份笔记，另加摘要（digest） | 原始证据，永不修改 |
| 摘要 | notes/python/_digest_python_mcp_remote.md、notes/pipeline/_digest_pipeline_testing_build.md、notes/profiling/_digest_profiling_packaging.md | 跨来源的合并结论 | 供技能正文引用，减少重复 |
| 官方文档快照 | sources/docs/ | 保存下来的 UE 5.8 文档页面，检索日期 2026-09-24 | 版本事实的“地面真相” |
| 版本与凭据 | sources/unreal-version-deltas.md、sources/manifest.json | 版本差异图、Mac 特性表、待核实清单、凭据核实状态 | 冲突裁决与不确定性登记 |
这套分层带来一个可操作的规则：摘要可以过期，笔记与文档快照不可改写。当引擎升级导致结论变化时，正确做法是追加新快照并更新 unreal-version-deltas.md，而不是悄悄改旧笔记。
另外两个被点名的文件值得注意：
sources/manifest.json：凭据以此为准，文档明确要求“unverifiedkept where it says so”，即标注为未核实的就保持未核实，不做美化；tests/baseline/answers.md：无技能时的基线答案，用于盲测对比，说明技能的价值需要被度量而不是被宣称。
三、专家与演讲表：字段设计与可核验性
主表有四个字段：Source、Who、Best for、Best timestamps。表面上是一张视频清单，实质上是一份断言到证据的映射表。
3.1 字段的语义
- Source：标题、场合与年份、视频标识。标题里往往就带着版本信息，例如 “Getting Started with MCP in UE 5.8”“Python in Unreal Engine（2019, UE 4.22）”“Unreal Fest Bali 2025（UE 5.5）”。版本写进来源名，是为了防止把 4.x 时代的结论套到 5.8。
- Who：讲者与身份，并明确标注核实状态。例如 Epic 的 Python Editor Script Plugin 工程师 Jamie Dale、Epic 技术产品经理 Warren Drones、M2 Animation 的 Christophe Bardoux；姓名拼写不确定时写“name as spoken”，身份不确定时写“role unverified”。
- Best for：这条来源只用来支撑哪些结论。这一列是防止过度引用的关键：一条来源可以谈 MCP 的三个插件，不意味着它可以为渲染参数背书。
- Best timestamps：
[hh:mm:ss]形式的定位点，通常一条来源给 4～8 个。它是“可复核性”的最小单位。
3.2 表中几条最关键的证据
把表格与技术正文对照，可以看到每个时间戳都在具体代码或规则里落了地：
| 来源锚点 | 结论 | 在仓库中的落点 |
|---|---|---|
Sam Deiter，k0tgmrBuIJc [00:18:13] | “connected but can do nothing”：官方文档漏掉了 Editor Toolset 插件 | SKILL.md 执行通道表的 MCP 行 |
同上 [00:45:31]、[00:46:04] | describe_toolset 载荷巨大（Niagara 接近 25 万字符），只查当前要用的 toolset | SKILL.md 的同一条规则 |
同上 [00:39:27] | 不要整段 HLSL 塞进 Custom 节点 | ue_audit.py 的 forbid_custom_hlsl 默认规则 |
同上 [00:52:23] | “列出、确认、再执行” | python-reliability.md P1 流程 |
Epic MCP/PCG 团队，lDf_y-YPELo [00:17:29] | 照明 Agent 把纯白帧判为“没问题” | ue_review.py 的 image_checks 动机段 |
同上 [00:25:55]、[00:30:32] | 工具设计要为自我纠错服务；技能只承载新信息 | python-reliability.md 错误信息规范 |
Jamie Dale，0guOMTiwmhk [00:21:25] | set_editor_property 等价于 Details 面板编辑 | python-reliability.md 属性章节 |
同上 [01:17:18] | 打开中的编辑器对已加载资产持有写锁 | ue_run.py 的 lock_check |
同上 [01:23:04] | commandlet 加载的模块少于完整编辑器 | ue_run.py 模式说明 |
Matt Oztalay，m6mJ9r7ytks [00:05:10] | 编辑器工具第一件事是“能撤销” | ScopedEditorTransaction 约定 |
同上 [00:13:39] | 未暴露给脚本的属性需要薄 C++ 层 | 能力矩阵“material graphs”行 |
Ari Arnbjörnsson，C-AjCqjKRSs [00:14:13] | 用 -DPCVars= 在初始化前设置 cvar | python-reliability.md 第 9 节 |
同上 [00:34:34]、[00:48:38] | 复杂碰撞默认值、半透明 After DOF | ue_audit.py 的审计规则 |
Bardoux，MjjkWH0eT3U [00:37:22]、[00:55:27] | EXR 关闭 tone curve；未签出就停止脚本 | ue-5.8-traps.md MRQ 与源码管理章节 |
硬件与平台，ufPtQEtk-RQ [00:18:17] | 热节流会让抓帧失真 | SKILL.md macOS 章节 |
这张对照表就是 sources.md 的实际用途：它使正文中的每一句断言都可以回溯。反过来，如果一条规则在表中找不到锚点，就应当被标记为技能的自行推断，而不是专家结论。
3.3 与 [added] / [verify] 标记的配合
文档本身不定义标记，但兄弟文件定义得很清楚。references/ue-5.8-traps.md 开头写明：[added] 表示保存的来源没有陈述，是技能自己的补充；[verify] 表示必须在已安装的引擎上确认。这形成了三档证据强度：
- 有来源锚点：时间戳或文档页可回查；
[added]：技能综合推理，来源不直接支持；[verify]：未验证，需引擎实测。
例如 ue_audit.py 中 lod_triangle_threshold、nanite_hint_triangles 标注为 [added]，而 mesh_flag_default_complex 直接引用演讲时间戳。读者因此能判断哪些阈值是行业经验，哪些是讲者明示。
四、官方文档清单：文件名即证据地址
第二部分列出 2026-09-24 检索的 UE 5.8 文档页面，并给出保存文件名与主题的对应关系。这种写法比“参考官方文档”有用得多，因为文件名本身可被 grep：
automation-pipeline__python-scripting-editor.md：所有运行 Python 的方式、commandlet 与-ExecutePythonScript的区别、路径与四条最佳实践，是ue_run无头模式的“地面真相”；automation-pipeline__python-api-reference-key-classes.md：子系统、AssetTools、AssetImportTask、校验器，以及 docstring 里的危险警告（强制删除、load_level不保存、destination_name被忽略）；automation-pipeline__unreal-mcp-official.md：插件、自动启动、启动参数、cvar、工具搜索、Python toolset、限制；automation-pipeline__remote-control-api.md（五页）：端点、访问规则、事务、路径、WebSocket；automation-pipeline__mcp-community-servers.md：社区服务器的传输与安全模式，并明确“not Epic”；automation-pipeline__automation-tests-gauntlet.md、automation-pipeline__uat-buildcookrun-commandline.md、performance-shipping__packaging-cooking-build.md、performance-shipping__chunking-zen-iostore.md：测试、构建、打包、分块；performance-shipping__profiling-fundamentals-stat-commands.md与unreal-insights.md：stat unit各字段定义，正是ue_stat.bound_by依赖的语义；cinematics__mrq-command-line-and-mrg-scripting.md、lighting-rendering__movie-render-graph.md：渲染命令行与图；automation-pipeline__macos-development-requirements.md、materials__substrate-overview.md、editor-world__naming-conventions-redirectors.md：Mac 要求、Substrate、命名规范（ue_audit使用的 Epic 前缀来源）；- 版本说明
versions__ue-5.X-release-notes.md与 5.8 管线摘录：5.8 的 Remote Control 允许列表、MCP 服务器、TraceQuery、MRG Production Ready、Python 行为变更。
注意“其他被重构补充引用的笔记”这一段的价值：它承认有些结论来自社区文章、领域笔记和 digest，而不是官方文档。例如 Tom Looman 的优化文章第二部分用于 World Partition Insights，tranek 的 GAS 指南 6.2 用于 MacBook 无小键盘的键位重绑。把这些“次级来源”写清楚，比混在官方文档里更诚实。
五、项目观测：一条真实运行记录
文档只有一行“Project observations”，却包含完整上下文：
ue_env.preflight()on this Mac, 2026-09-24: Apple M5 Max, macOS 26.5.1, 48 GB, Xcode 26.6（reported "unlisted" against Epic's 5.8 window）。Unreal Engine not installed（ue_env.find_engine()returns None）。
这一行同时证明三件事：预检脚本真的跑过、Xcode 版本不在 Epic 列表内（需要额外验证）、引擎尚未安装（因此所有引擎内调用未验证）。
这条观测对应 scripts/ue_env.py 的实现。preflight()（L359 起）采集 sw_vers -productVersion、sysctl -n machdep.cpu.brand_string、sysctl -n hw.memsize、xcodebuild -version，并输出 error: / warn: / info: 三类行：
- macOS 低于 5.8 最低要求 14.5 → error；
- 非 Apple Silicon → error，因为 5.8 只支持 Apple Silicon 渲染；
- M1 → warn，Nanite、VSM、Lumen HWRT、MegaLights 需要 M2 及以上；
- 内存低于 16 GB → warn；
- Xcode 缺失 → info（仅蓝图项目可用），
too_old/incompatible→ error，unlisted→ warn（提示先验证 C++ 构建）。
unlisted 这一档正是文档里那条观测的产物：Epic 对 5.8 给出 26.0 最低、26.1.1 推荐、26.4 不兼容，而本机是 26.6，落在列表之外，于是预检只给警告而非错误。
可以直接复现：
python3 skills/game-engines/unreal/scenario-unreal-expert/scripts/ue_env.py --find
python3 skills/game-engines/unreal/scenario-unreal-expert/scripts/ue_env.py --preflight
--find 返回编辑器、editor_cmd、UAT 与版本（可用 UE_ROOT 覆盖），未找到时退出码为 5；--preflight 输出上述 JSON。文档说 find_engine() 返回 None，正是 --find 会以 5 退出的情形。
六、修订历史：来源如何反向驱动代码
文档最后一段记的是 v0.2 重构，起因是首轮盲测（tests/grading/SUMMARY.md 与 U1–U9 评分）。这段历史把“来源”与“代码变更”连成因果链：
- 报告协议：九位评分者中有四位扣掉了可执行性分，因为读者没有
scripts/时无法核对ue_run.run_python(...)之类调用。于是SKILL.md与新增的toolkit-map.md要求每一步都写出背后的引擎调用、控制台命令或 cvar，并以 Verified / Assumed 两列表收尾。 ue_run0.2：从“取日志里最后一条UE_RESULT”改为“只认本次启动、带 job id 的信封”，在 ue_run.py 的模块文档字符串里写得很清楚（L50–L56）：任务只在本轮 boot 的result.json或其UE_RESULT行携带本 job id 时才算通过，退出码从不单独判定成功；任务自己打印的UE_RESULT会被计入foreign_results并忽略，因此“先打印 ok 再崩引擎”判为失败。同时加入wait_for_registry()、-ScriptErrorsAreFatal、写锁检查与strict。- 补齐盲测暴露的缺口：源码管理与 OFPA 提交、生成的 PCG 内容不入 changelist、无头模式下的源码管理、
-cookincremental、cook 校验统计、World Partition Insights、采样分析器、曝光范围警告、Game Overrides、-notexturestreaming、渲染农场管理、ScopedSlowTask、原始截图循环、MacBook 小键盘、域名版本陷阱，分别落到SKILL.md、ue-5.8-traps.md、python-reliability.md。 - 快照留存：v0.1 保存在
skills/_versions/unreal-expert v1 2026-09-24/。在当前仓库中该路径不存在，说明这一保存约定属于作者构建项目，读者应以当前references/为准。
这套流程值得复用：盲测 → 归因（结论错、还是不可核对）→ 先改协议，再改代码 → 记录版本。
七、来源表如何约束实际代码
sources.md 不是装饰。以下三处能直接看到“来源锚点 → 默认值”的传导。
7.1 审计规则里的讲者引用
ue_audit.py 的 DEFAULT_RULES 注释里带来源代号：
"mesh_flag_default_complex": True, # Profiling with Purpose, C-AjCqjKRSs [00:34:34]
"forbid_custom_hlsl": True, # Sam Deiter, k0tgmrBuIJc [00:39:27]
"flag_translucency_after_dof": True, # C-AjCqjKRSs [00:48:38]
同一文件的 EPIC_PREFIXES 注释说明它与 UE4 时代的 Allar 指南不同（SM_ vs S_、FXS_ vs PS_），要求“每个项目选一套并写在这里”——这正是把“命名规范文档”变成可执行规则的方式。
7.2 写锁检查里的时间戳
ue_run.py 在文档字符串 L60–L66 交代：保存类任务绝不可指向已打开编辑器的项目，因为编辑器对已加载资产持有写锁，并附 Jamie Dale 的时间戳引用。实现上，run_python 与 run_commandlet 通过 ps -axo pid=,command= 查找命令行里带该 .uproject 的 UnrealEditor 进程；lock_check="warn" 只报告，"refuse" 直接返回失败且不启动引擎。测试 test_toolkit_offline.py 用真实子进程替代编辑器，验证进程组超时终止、日志完整、Ctrl-C 后不残留进程组。
7.3 图像检查的动因
ue_review.py 开头直接写明动机：Epic 的 MCP 演讲中，照明 Agent 改完云层材质、截图，然后把完全纯白的帧判为“fine”，并附 lDf_y-YPELo [00:17:29]。因此离线检查包含 all_white / all_black / uniform、裁切比例、压暗比例、中心与四周对比等标志，要求“先跑检查、再肉眼判断”。
7.4 性能来源的边界
ue_stat.py 文档字符串把预算单位写死为毫秒：60 fps 对应 16.67 ms，30 fps 对应 33.3 ms，并引用 GuIav71867E [00:03:53]；同时区分“精简抓取（回答是否超预算）”与“富抓取（回答为什么，附加约 20% 开销，C-AjCqjKRSs [00:11:27]）”。文档还说明 CSV profiler 的列名与 5.8 新增 TraceQuery 的 JSONL schema 均标 [verify]，因为保存的文档页没有覆盖；这正是来源表与 [verify] 分工的示例。
八、和兄弟技能的来源表比一比
同一家族的其他技能也有 sources.md，写法不同，能反衬本文件的取舍：
- scenario-unreal-pipeline-automation/references/sources.md 同样声明笔记在
notes/pipeline/、notes/python/等目录，摘要复用_digest_pipeline_testing_build.md与_digest_python_mcp_remote.md； - scenario-unreal-cinematics/references/sources.md 强调“凭据标注 verified 的，是研究 Agent 对照官方议程或 Epic 员工页面核实过的，其余为自述”；
- scenario-unreal-performance/references/sources.md 使用短代码（OZ26、W4R、C-AjCqjKRSs 等）在
procedures.md与脚本注释中复用，便于在代码里低成本引用。
本文件的独特之处是把“谁说的”当作一等字段：它记录讲者的具体职位（例如 Python 插件的实现工程师、广播团队的技术产品经理、平台工程师），因为同样的结论出自插件作者与出自第三方教程，可信度不同。这也是它把 “role unverified”“name as spoken”“surnames unverified” 写进表格的原因。
九、把来源表用于自己的 Unreal Agent 工作流
9.1 引用纪律
一条可复核的结论应当长这样：
- 结论：5.8 默认拒绝远程 UFUNCTION 调用，需要允许列表；
- 锚点：
sources.md官方文档清单中的 5.8 Release Notes 条目； - 落点：ue-5.8-traps.md 第 3 节；
- 影响：ue_remote.py 的
RemoteControl.call错误提示应指向“允许列表”，而不是让调用方反复重试。
反过来，缺少锚点的结论必须降级：
Assumed: r.Substrate 在本项目为开启状态（未读取 DefaultEngine.ini，[verify]）
ue_env.read_ini_value 只解析指定 section/key，不做 Base 层合并，这一点文档也写明了；因此读到的值与最终生效值可能不同，报告里应说明。
9.2 新增来源的最小流程
- 找到一手材料（演讲、官方页、release notes），记下版本与日期；
- 在笔记目录写逐源笔记，不改已有笔记；
- 在
sources.md表格补一行：标题+场合+版本、讲者与凭据核实状态、只用于哪些结论、4～8 个时间戳； - 官方页存入
sources/docs/，文件名保持“领域__主题”格式； - 若与现有结论冲突，写入
unreal-version-deltas.md的 Conflicts 段，而不是二选一硬写； - 代码里引用来源代号或时间戳，让下一位读者能回查。
9.3 适配当前仓库的验证方式
由于引擎尚未安装，仓库内能验证的是离线部分。可用以下命令确认工具链与家庭约束：
python3 -m unittest discover -s tests/scenario-unreal-expert -v
其中 test_family_imports.py 用系统 Python 导入每个脚本，把 unreal、bpy、UnityEngine 等仅存在于应用内的模块视为可跳过，同时静态检查脚本里出现的 scenario-unreal-* 名称必须真实存在；test_specialists_offline.py 覆盖 ue_anim.apply_ini_plan、ue_light 的文件读取子命令、ue_world 的 check-spec。
引擎可用之后，按 ue-5.8-traps.md 第 7 节的首跑清单推进：先 ue_env.py --find 确认版本与 editor_cmd，再跑离线+实机测试，最后逐条确认 -abslog=、-ExecCmds=py 的时序、quit_editor、take_high_res_screenshot 的关键字与落盘位置、Rotator 参数顺序等 [verify] 项，并把结论回写到 ue-5.8-traps.md 与 SKILL.md 的状态行——这正是来源台账的闭环。
十、读这份文档时应记住的三条
- 来源表是断言的可信度约束。
Best for限定用途，Best timestamps提供最小复核单位，Who提供权威度，三者共同决定一条结论能否写进技能正文。 - 未核实就标注，不核实不升级。
unverified、[verify]、[added]、"Unreal Engine not installed"都是正式内容，不是待清理的 TODO。诚实标注不确定性，比给出看似确定的错误默认值更有价值。 - 来源变更要触发代码变更。v0.2 的修订历史表明：当来源暴露出“结论不可核对”时，先改报告协议与工具返回值，再补规则；
ue_run的 job-id 信封、lock_check、image_checks的纯白帧检测，都是这条原则的产物。
如果要继续深入，建议按顺序读 references/toolkit-map.md（每个工具函数背后的引擎调用）、references/ue-5.8-traps.md（5.8 破坏旧代码的完整清单）、references/python-reliability.md（unreal 模块的可靠写法与四段流程），再把它们与本文的来源表对照阅读，就能完整还原这个技能“从证据到代码”的链路。
【免费下载链接】skills
Get production-ready images, video, audio, and 3D from any AI agent: skills that pick the right model, price before spending, and keep characters and brands consistent through the Scenario MCP, plus expert teams that drive Blender, Maya, ZBrush, Unreal, and Unity.
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
