xEdit 自动化 — 中枢技能
此技能是任何 xEdit 工作的始终加载入口点。它是“使用哪个路径”和“绝对不能做什么”的唯一真实来源。专门的任务技能(例如 xedit-conflict-audit)继承其路由、反模式和验证纪律;它们不会重复陈述这些内容。
工具箱概览(渐进式公开,r6 感知)
分叉的 xEdit 守护进程最好被视为一个渐进式公开界面:
从小型 MCP 意图工具开始,向实时守护进程询问其支持的 r6 能力块,然后仅在相应的 system.capabilities.supports.* 键存在时切换到更丰富的单次调用模式。
- 发现与会话 —
xedit_session、xedit_list_capabilities。每次对话首先调用xedit_session。然后调用一次xedit_list_capabilities以查看命令摘要、contractVersionExpected和 r6supports.*锚点。 - 读取记录和冲突 —
xedit_find_record、xedit_read_record、xedit_inspect_conflicts。这些是 W2(冲突审计)的骨干;当 W2 需要任何意图工具尚未公开的 r6 响应块时,则分支到原子直通。 - 原子直通 —
xedit_call(command, args)。用于尚无相应意图工具的任何本机守护进程命令。仍然运行完整管道(验证 → 状态 → 规则 → 审计)。当意图工具不适用时使用它。
对于深度参考资料,首先查询结构化 BGS KB(bgs_kb_query / bgs_kb_get)。深度参考记录位于 knowledge/bgs-kb/packs/core/records/xedit/(可通过 bgs_kb_query / bgs_kb_get 查询)。
路由原则(使用哪个路径)
| 任务类型 | 路径 |
|---|---|
| 高频已知意图(审计冲突、读取记录、运行作业、编写补丁) | MCP 意图工具 |
| 新颖/调试/本机命令的自由组合 | MCP 原子直通:xedit_call(command, args) — 仍在框架内 |
| 探索性原子操作风暴(试错、重复读取-评估、假设测试) | 委派给一个只读的调查子代理,并加载此技能;子代理消耗自己的上下文,返回浓缩的摘要 |
| 大型可形式化的批量修改 | MCP xedit_run_script(批次 4+)配合试运行 + 快照 |
| 守护进程明确处于默认(非 MCP)模式,仅限手动调试 | 直接使用 xedit-client.ps1 是可以接受的 — 但仅当用户已明确接受风险且守护进程未处于 -automation-mcp-mode 时 |
代理永远不应有理由绕过 MCP。 原子直通就是为了这个目的而存在的。
补丁创作判断
概述
补丁创作不是“消除红色”。它是一个小的兼容性论证:保留当前胜者,仅转发那些应该继续存在的上游值,并留下一个可逆的补丁插件,其内容表明了你的意图。排序是一个单一选择杠杆;补丁是同时保持两个模组意图值的方式。但原则上的正确不等于包规模上的正确:如果计划是拼接每个 FormID,因为“xEdit 可以修复一切”,那么这个计划已经失败了。
当你即将通过 MCP 创作或判断补丁时,请使用此部分。当问题仍然是“什么胜出、什么冲突、以及这应该是补丁还是重新排序?”时,首先使用 xedit-conflict-audit。该技能拥有补丁与重新排序决定的决定权;此部分则拥有你即将编写的补丁是否结构良好的决定权。
决策流程:此补丁结构是否良好?
digraph patch_authoring_judgment {
// 待关闭保存会阻止生命周期操作;请参阅下面的脏状态和重启控制。重启不是持久性机制。
rankdir=TB;
node [shape=box];
start [shape=doublecircle, label="需要补丁?"];
audit [label="审计实际胜者 + 冲突字段\n(如果尚未完成,使用 xedit-conflict-audit)"];
reorder [shape=diamond, label="仅重新排序是否足够\n而不会丢失所需的值?"];
no_patch [shape=doublecircle, label="无需补丁:重新排序 / 保留胜者\n然后验证回读"];
winner [label="复制/定位当前胜者\n而不是较旧的败者"];
intent [label="命名要转发的每个值\n它做什么?为什么它应该存在?"];
noise [shape=diamond, label="是否存在任何未更改的复制值\n或绿色/ITM 风格噪声?"];
clean [label="移除未更改/无意图的值"];
refs [shape=diamond, label="正在删除或标记删除\n记录/元素?"];
referenced [label="运行 referenced_by / reference 审计\n如果后果未知,则停止"];
esl [label="有意选择补丁形式\n通常是安全时标记为 ESL 的 ESP;如果排序自由度重要,则避免原生 ESL/ESM"];
reversible [shape=diamond, label="单独的可逆补丁\n(不直接编辑源模组,不进行非托管覆盖溢出)?"];
fix_shape [label="移动到受管理的 MO2 模组\n或创建专用的补丁插件"];
verify [label="保存 + 重启 + 回读\n胜出覆盖显示预期的值"];
pass [shape=doublecircle, label="结构良好的补丁"];
start -> audit -> reorder;
reorder -> no_patch [label="是"];
reorder -> winner [label="否,需要组合值"];
winner -> intent -> noise;
noise -> clean [label="是"];
noise -> refs [label="否"];
clean -> refs;
refs -> referenced [label="是"];
refs -> esl [label="否"];
referenced -> esl;
esl -> reversible;
reversible -> fix_shape [label="否"];
reversible -> verify [label="是"];
fix_shape -> verify -> pass;
// 合约 0.23 待保存使用 xedit_flush;仅重启不是证据。
verify [label="保存 + 检查待处理状态;如果需要则使用 xedit_flush;进行全新回读"];
}
延迟保存更正: 图中历史上的
保存 + 重启 + 回读节点已被取代。如果session.save报告非零的savePendingShutdownCount,请检查xedit_dirty,然后在合约 0.23 的守护进程上使用xedit_flush。该工具验证排空响应并确认守护进程承诺的自行退出。partial或未知的lastFlush不是持久性证据。当存在活动的待处理队列时,正常的停止/重启仍被拒绝;force:true会放弃状态,绝不是持久性的证据。
创作检查
- 转发胜者。 游戏读取某个 FormID 的最终/胜出覆盖。从当前胜者构建补丁,然后仅转发那些仍然需要存在的较旧模组值。
- 没有未更改的负荷。 如果复制的值没有改变含义,那么它就是 ITM 风格噪声,而不是兼容性。除非你可以说明为什么有意携带它,否则请移除它。
- 将补丁作为单独层。 不要仅仅因为源模组今天是右列就直接将值拖入其中。补丁应可通过禁用/移除补丁层来逆转,而不是手动从他人的插件中删除字段。
- 保留引用。 如果计划中涉及删除或标记删除,请停止并首先运行被引用/回读路径。未知的引用意味着未知的影响范围。
- 有意选择插件形式。 普通的兼容性补丁通常需要正常的 ESP 排序自由度,并在安全时添加 ESL 标记。原生 ESL/ESM 的加载顺序行为不是免费的整洁升级。
- 好补丁 vs 权宜补丁。 好的补丁对每个转发的值都有命名的意图,并减少冲突债务。权宜补丁复制整个记录、编辑源模组,或试图拼接每个 FormID,因为排序被视为无关紧要。
KB 查询纪律
此判断部分与游戏无关。查询 KB 以获取特定游戏的补丁技巧、记录系列注意事项和当前工具链事实,而不是在此处固化它们。
bgs_kb_query({ query: "xedit 补丁创作注意事项", domains: ["xedit", "load-order"], games: ["<当前游戏>"] })
如果 KB 无响应,请标记 [GAP] 并将补丁规则保持在框架级别,而不是发明特定于游戏的原则。
红旗(停止)
| 想法 | 现实 |
|---|---|
| “它是红色的,所以复制左边的值。” | 红色是提示要检查。它不是败者值应该存在的裁决。 |
| “最右边的模组错了;我直接编辑它。” | 那么你让源模组成为了补丁。使用单独的覆盖补丁以便干净地逆转。 |
| “排序无关紧要,因为 xEdit 可以修补任何东西。” | 原则上是的;跨数十万个 FormID 则不然。使用排序来减少修复债务,然后修补有意义的部分。 |
| “绿色/未更改的复制值是无害的。” | 它们是无意图的负荷。如果它们不改变含义,请移除它们。 |
| “原生 ESL 比标记为 ESL 的 ESP 更干净。” | 原生 ESL/ESM 会付出正常排序自由度的代价。当补丁形状安全时,使用标记为 ESL 的 ESP。 |
| “这看起来未使用;删除它。” | 首先检查被引用。在没有引用知识的情况下删除意味着未知的影响范围。 |
合理化
| 借口 | 现实 |
|---|---|
| “我只需将一个字段拖入胜出的插件。” | 一个字段仍然是对源模组的编辑。制作一个补丁层,否则未来的你将逐个手动移除散落的字段。 |
| “补丁应该保留任何模组触及的所有内容。” | 保留意图,而不是历史。有些编辑是模组的核心;有些是偶然的作者偏好,应该让位于系统规则。 |
| “我不知道这个字段做什么,所以我复制看起来合理的版本。” | 未知的字段含义是一个研究任务,而不是一个骰子。阅读记录结构、CK/维基/社区示例以及包内的实际行为。 |
| “覆盖没问题;MO2 能看到它。” | 覆盖是溢出。真正的补丁属于一个有名称的受管理模组层,未来的你能理解其含义。 |
| “响应说没问题;补丁完成了。” | 补丁被接受意味着在保存/重启后,胜出覆盖回读显示预期的值,并且没有意外的负荷。 |
R6 渐进式公开能力检查
不要假设每个守护进程都是 r6。读取一次 xedit_list_capabilities 并根据下面的支持键进行分支。在 pre-r6 守护进程上,回退到较旧的显式记录列表/子元素遍历/每条记录循环模式;在 r6+ 守护进程上,使用单次调用或分页感知形式以减少往返次数并保留上下文。
| 能力键 | 合约 | 优先使用此模式 | KB 记录 |
|---|---|---|---|
supports.childGroupNavigation | 0.13 | 通过 elements.children 存根导航 CELL/WRLD/DIAL/QUST 子组 | xedit.childgroup-navigation.v1 |
supports.createParentSpec | 0.16 / 0.18 | 使用 records.create parent 直接在父级子组下创建记录 | xedit.records-create-parent-spec.v1 |
supports.elementsChildrenPagination | 0.17 | 使用 limit / offset 对 elements.children 进行分页 | xedit.elements-children-pagination.v1 |
supports.reverseNavigation | 0.19 | 添加 includeParents:true 并读取 relations.parents | xedit.reverse-navigation.v1 |
有关整个 r6 合约变更,请查询 KB 记录 xedit.r6-contract-summary.v1。
子组导航(supports.childGroupNavigation)
在 r6+ 守护进程上,CELL、WRLD、DIAL 和 QUST 记录上的 elements.children 返回一个虚拟子条目,其 kind: "child_group"。将该条目视为只读导航存根,而不是真正的可变元素。
一次使用一个世代:
elements.children({ file, formId, path: "\\Child Group" })
elements.children({ file, formId, path: "\\Child Group\\Persistent" })
elements.children({ file, formId, path: "\\Child Group\\Temporary" })
elements.children({ file, formId, path: "\\Child Group\\Visible when Distant" })
elements.children({ file, formId, path: "\\Child Group\\Block X, Y" })
elements.children({ file, formId, path: "\\Child Group\\Block X, Y\\Sub-Block M, N" })
- 仅遍历下一个级别;当一页或一个子组标签足够时,不要请求整个树。
\\Child Group...路径是合成的并且是只读的。修改动词必须使用扁平的 FormID 定位器({ file, formId })或records.create.parent规范;不要将合成的定位器路径传递给修改器。- 对于 WRLD 单元格,根据目标子元素组使用
Persistent或 Block/Sub-Block/坐标路径。 - 深度参考:
xedit.childgroup-navigation.v1。
elements.children 分页(supports.elementsChildrenPagination)
在 r6+ 守护进程上,elements.children 接受 limit 和 offset:
elements.children({ file, formId, path, limit: 200, offset: 0 })
limit被限制在 1-1000,默认为 200。- 响应包括
count、total、offset和truncated。 - 如果
truncated为 true,则保持相同的limit,将count加到offset上,并获取下一页,直到覆盖完全。 - 不要假设 CELL 子组很小:FO4 原版 CELL
00000025的Temporary包含 742 条记录。 - 深度参考:
xedit.elements-children-pagination.v1。
反向导航(supports.reverseNavigation)
在 r6+ 守护进程上,当你需要在不使用第二个动词的情况下了解所有权或包容关系时,添加 includeParents: true。支持的读取调用包括:
records.getrecords.find_by_form_id/records.find_by_editor_id和 MCP 包装器,例如xedit_find_recordrecords.master_or_selfrecords.winning_overrideelements.getelements.children
响应可能包括:
relations.parents: [{ locator, object }, ...]
父级按最近优先顺序排列,守护进程深度上限为 16。这是回答“哪个 CELL 拥有这个 REFR?”或“哪个 QUST/DIAL 组包含这个子项?”的首选方式。使用父链作为回读证据;除非支持键缺失,否则不要构建自定义的反向索引循环。深度参考:xedit.reverse-navigation.v1。
records.create 父级规范(supports.createParentSpec)
在子组中进行修改性记录创建是 r6 门控的,并且仍然需要正常的 MCP 修改同意路径。当支持时,显式指定目标父级,而不是试图修改合成的 \\Child Group …
…[为翻译而截断]