X4 Claude Code 模组制作工具包

[center][url=https://github.com/WingedGuardian/x4-claude-toolkit][size=6][b]GitHub 仓库[/b][/size][/url][/center] center[/center]

[color=#e06666][size=5][b]这是什么？[/b][/size][/color]

[url=https://claude.ai/code]Claude Code[/url] 是 Anthropic 开发的一款 AI 助手，直接运行在你的电脑上。与 ChatGPT 或普通的 Claude 聊天不同，它可以读取你的文件、运行命令、编辑配置和执行脚本——所有这些都需要你的许可。可以把它想象成一位坐在你身边、能实际修改你文件的模组专家。

X4 模组制作充满了无声的失败模式。一个 sel= 不匹配任何内容的 diff 补丁，能干净地通过验证、干净地加载，然后什么也不做。多文件更改中漏掉一个文件，物品就不会出现。另一个模组悄悄覆盖了你刚设置的值。这些情况都不会崩溃，只是不生效，而你通常要玩上一个小时才会发现。

大多数尝试使用 AI 助手进行模组制作的人，都会耗费数天时间来连接工具、解释引擎机制、建立防护栏，以免它搞坏自己的安装。[b]本工具包已经把这些全部解决好了[/b]——此外还附带了一套专为 X4 编写的专用工具，能回答任何现成工具都无法解答的问题。

[color=#e06666][size=5][b]v2.7 新增——工具现在会告诉你哪个模组发生了变动[/b][/size][/color]

这里的每个工具宁可拒绝基于过期数据作答，也不愿给你一个信誓旦旦但错误的数字。这曾经是正确的行为，但也让人非常恼火：它只会告诉你世界变了，却从不告诉你变了什么。要定位一个更新的模组，需要经过九个调查步骤。

[b][font=Courier New]x4modlist changed[/font][/b] 现在可以直接回答这个问题，[font=Courier New]x4modlist snapshot[/font] 则为你提供用于对比的基线。

[b]现在它能看见两件以前确实看不到的事。[/b]一个模组的_文件_发生了更改而其 [font=Courier New]content.xml[/font] 保持不变——这是常见的“编辑文件，然后复制进去”的工作流程——以前是完全不可见的：在真实的 121 个模组列表上测量，其中 72 个至少有一个文件比其自身清单文件更新，而每个工具都报告 FRESH，同时描述的却是截然不同的模组集合。这在安全方向上失败了。在游戏自带的模组菜单中启用或禁用模组的情况也是如此，因为切换操作只会重写配置文件清单。

[i]本版本还包含：[/i] 一个过期数据警告，其提到的命令在上一版本并未真正附带（现在已附带）；过期警告现在会同时显示两个指纹，因此无需编写脚本就能回答“移动了多远”的问题；以及一套针对工具包自身自检的修复——该自检会故意破坏代码以确认测试能发现异常。它现在能在运行中途被终止时恢复目录树，并且会如实报告其测量范围而不再静默缩小。现在在它运行时，每个工具都会警告你它正在基于被故意破坏的代码作答，任何会写入数据的操作都会被直接拒绝。

[color=#e06666][size=5][b]v2.6 新增——一次跨所有文件提问[/b][/size][/color]

[b]BaseX 语料库搜索现已随工具包一起提供**（此前仅内部使用）。它为整个语料库建立索引——基础游戏、所有 DLC 以及每个已安装的模组，共 3600 万个节点——并能在大约一秒钟内回答递归 grep [i]不诚实地[/i]回答的那类问题。

[b]它具体解决的问题是：**“没有东西引用这个宏”是模组制作中最危险的句子，因为 grep 无法区分_这不存在_和_我没有全面查找_——而且大约 62% 的模组 XML 位于 grep 永远无法打开的打包归档文件中。因此，除非它能说明自己搜索过的文档总数，否则它拒绝把零结果当作发现来输出，然后会说 “在 N/M 个文档中确认无结果”，并列出每一个排除项。如果索引已过期，它同样拒绝作答，而不是给你一个信誓旦旦但错误的数字。

两个索引：[font=Courier New]x4raw[/font]（每个文件_按原样写入_]）和 [font=Courier New]x4eff[/font]（游戏实际看到的合并树，diff 按加载顺序应用）。对于任何关于实时数值的说法，请使用第二个索引——第一个索引会很高兴地引用你模组列表已覆盖的原版数值。

[b]开始前请对自己诚实地评估成本：** 它需要 Java 17+、约 3 GB 磁盘空间，以及一次以分钟计而非秒计的一次性构建。BaseX 本身已内置（BSD-3-Clause），无需额外下载。它完全可选——工具包的其余部分不需要 JVM。

[i]本版本还包含：[/i] 预检功能，首次运行时会告诉你真正的问题所在——以前缺少 JVM 会显示为 [font=Courier New]BaseX query failed: [WinError 2][/font]，错误地归咎于 BaseX 而实际是缺少 Java，而未构建的索引则打印原始错误，从不提及构建脚本。同时修复了 Linux 测试失败问题（所有 8 个都是测试端问题，而非库缺陷），不过 Linux 仍然明确不提供支持保证——请参阅下方的诚实性说明。

[color=#e06666][size=5][b]工具——以及各自的作用[/b][/size][/color]

已捆绑并预配置八个命令行工具。如果觉得它们像外语一样难懂也不必紧张——Claude 会在需要时为你驱动它们；当然你也可以自己运行。它们都能读取打包模组（[font=Courier New].cat[/font]/[font=Courier New].dat[/font]，包括 VRO）以及松散模组。

[size=4][color=#e06666]x4validate[/color] —— 旗舰工具：在启动前发现无声的无效操作[/size]

• [b]每个 diff [font=Courier New]sel=[/font] 都会针对真实的合并树进行解析（基础游戏 + 所有 DLC + 你启用的模组），因此不匹配任何内容的补丁是_错误_，而不是干净通过。
• [b]引用检查——你模组引入的每个物品、宏和 [font=Courier New]{page,t}[/font] 文本 ID 都必须指向真实存在的内容。
• [b]完整性——将新内容与类似的原版内容对比，在物品变得无价却无法购买之前回答“我是不是漏掉了什么？”
• [b][font=Courier New]--tier b[/font] 按加载顺序合并你_已安装_] 的模组列表，使跨模组补丁能真实解析——并能捕获看似成功实则失败的状况：另一个模组移除了的内容。（开发中的真实案例：一个模组移除了一个原版宏且从未重新添加，导致其他六个模组引用了孤立内容——基础游戏+DLC 验证认为没问题，实际却产生了 415 个引擎错误。）
• [b]它模拟了 X4 的补丁规则，而朴素的 XML 合并会搞错这些规则，每条规则都可能导致无声无效操作：匹配多个节点的 [font=Courier New]sel=[/font] 会应用nothing（RFC 5261——在某个真实模组列表中，有 236 个此类操作被静默跳过），[font=Courier New]if=[/font] 守卫在选择器之前门控操作，而 [font=Courier New]extensions/<target>/<rel>[/font] 路径属于该模组，而非基础游戏。
• [b]针对引擎本身验证，而非针对自身验证——测试工具会重放 X4 自身日志拒绝的每一个补丁操作，并要求得到相同的裁决（目前 234/234 完全一致，零错误通过）。

[size=4][color=#e06666]x4effective[/color] —— "X4 的 xEdit"：每个最终值及其来源[/size] 基础游戏 + DLC + 你所有模组中每个物品、宏和工作的有效值，在可查询存储中带有逐属性溯源（[font=Courier New]base -> modA -> modB[/font]）。跨所有内容读取单个列（如“所有导弹及其伤害”），查看完整记录，获取仅是谁设置的链，列出单个模组覆盖的所有内容，或转储任意路径的实时合并 XML。别再猜哪个模组最终生效了。

[size=4][color=#e06666]x4compat[/color] —— 如果我安装这个，会破坏什么？[/size] 对有效树进行冲突检测：两个模组编辑同一个节点（一个静默失效）、定义相同的注册表 ID、完全覆盖同一个文件，或者——阴险的那种——后加载的模组替换整个元素，从而抹掉所有先前模组在其内部的编辑。候选模式能回答“这个新模组会与什么冲突？”[i]在您安装它之前。

[size=4][color=#e06666]x4xref[/color] —— 谁调用这个？谁在监听？[/size] 一个覆盖基础游戏 + DLC + 你的模组中所有 Mission Director 和 AI 脚本的谁调用/谁监听/线索索引。一条查询就能回答“还有别的东西对这个事件起反应吗？”，而无需多轮 grep 那些与你真正想询问的内容毫无共同关键词的标记。

[size=4][color=#e06666]x4stats[/color] —— 这在我的游戏里平衡吗？[/size] 咨询性数值比较：模组的物品/武器定价和属性在_你的_有效游戏中与所有其他内容的对比情况，包括已安装大修模组的重新调整值。为平衡性讨论提供依据；不冒充能一锤定音。

[size=4][color=#e06666]x4similar[/color] —— 我已经有这艘船了吗？[/size] 咨询性近似重复检测：按类别和用途过滤，标记模组中的某艘船可能是你已有的“同款船”，只是名字和 ID 不同。

[size=4][color=#e06666]x4modlist[/color] —— 分类整理你的整个模组列表[/size] 一个基于物理安装内容构建的已安装模组注册表（每个模组自己的清单文件——文件夹名不可靠），并与你的配置文件交叉核对。使用可选的 Nexus API 密钥，它可以拉取上游版本、更新日期、更新日志和状态，然后将所有内容分类到不同轨道：就绪 / 频繁更新中 / 早于你的游戏版本 / 本地自定义 / 作者已弃用。

[size=4][color=#e06666]x4diff[/color] —— 区分你的编辑和作者的编辑[/size] 模组两个版本之间的语义化 XML 差异比较，支持多基线——专为解决“我几个月前修改了这个模组，作者刚刚更新了它”的问题而设计。

[size=4][color=#e06666]BaseX 语料库搜索** —— 超级武器：这在所有内容里是什么样的？[/size] 对整个索引语料库执行 XQuery，适用于那些跨越文件而非存在于单个文件中的问题：这个属性在所有飞船上有哪些值？谁引用了这个宏？哪些模组定义了没有生产商的物品？这是这里唯一能支持_否定_结论的工具，因为它会说明自己搜索的文档总数。可选——需要 Java 17+ 和一次性索引构建。

[color=#e06666][size=5][b]你会得到什么[/b][/size][/color]

这不是一份告诉你要自己安装和配置什么的指南。这是一个完整的、可直接运行的环境——每个工具都已预先校准，引擎的怪癖已记录在案，陷阱已得到防护。解压，运行安装程序，粘贴一段提示词，你就可以开始了。

[size=4]包含内容：[/size]

• [b]上述九种工具——已捆绑、预配置，并由 Claude 代为驱动。638 个自动化测试和 26 道关卡运行在真实模组列表和 X4 自身引擎日志上，而非固定测试数据上。
• [b]X4 引擎知识，已预加载——XML 模式模式、diff 补丁惯用法、扩展合并和加载顺序模型（覆盖与联合的区别——搞错这一点你的补丁就会无声失效）、7.x -> 9.0 迁移地图（[font=Courier New]space=[/font] 要求、已废弃的 Lua_Loader、受保护的 UI 模式），以及用于推理平衡性连锁反应的机制联动地图。
• [b]一个 7.x -> 9.0 迁移检查器——将其指向旧模组，就能在开始手动移植前，列出所有机制性破坏并能通过模式检查。
• [b]安全挂钩——Claude 不能写入你解包出来的参考树，不能直接编辑 [font=Courier New].cat[/font]/[font=Courier New].dat[/font] 文件，并且在接触模组清单或你的存档配置文件前必须征得同意。
• [b]自动备份 + 审计跟踪——Claude 编辑的每个文件都会复制到一个带时间戳的备份文件夹，并附带更改内容和时间的日志。
• [b]防护措施经过测试——一个测试工具会向每个挂钩提供合成的工具调用 JSON，并断言其返回的决策（33 项断言，覆盖两种安装布局）。这样做是因为_无声_的防护比没有防护更糟：曾有多个挂钩在数个版本中处于失效状态，而代码审查从未发现。
• [b]置信度系统——Claude 会评估其置信度（0-100%）并在提出更改[i]之前]列出其假设。没有“这应该没问题”这种话。
• [b]预演工作流程——批量编辑会让你看到所有将更改的文件和值，并在写入任何内容之前等待你的批准。
• [b]基线捕获——记录已知良好的快照（游戏版本、已安装模组哈希、规范化 debug.txt 错误指纹），以便你在添加 50 个模组后能对比新错误。
• [b]技能（斜杠命令）——[font=Courier New]/x4-debug[/font]（读取 debug.txt，过滤良性噪音，显露真实错误）、[font=Courier New]/x4-modlist-review[/font]（分类整理你的模组列表）、[font=Courier New]/x4-mod-interaction[/font]（针对一个模组对你整个安装环境的完整交互简报）、[font=Courier New]/x4-scaffold[/font]（根据类似的原版内容，为新增内容搭建完整的跨文件足迹框架）、[font=Courier New]/x4-update-mod[/font]（将模组移植到更新的游戏版本）。
• [b]子代理——[i]cross-file-impact[/i] 在你开始前追踪所有需要修改的文件；[i]mod-research[/i] 读取模组的 Nexus 页面（描述、更新日志、错误报告）并在你盲目编辑前提供简报。
• [b]引导式跨平台安装程序——三种布局，自动检测你的游戏、配置文件和 XRCatTool，并将结果写入配置文件。没有硬编码内容；[font=Courier New]x4validate --paths[/font] 会打印出它解析到的确切内容。

[color=#e06666][size=5][b]安装设置（4 个步骤）[/b][/size][/color]

[b][color=#e06666]第一步：[/color]获取 Claude Code[/b]（推荐——但你也可以使用像 Opencode 这样的免费替代品，并让其适当调整文件名。我的说明是 Claude 专属的，因为我觉得它能力更强。）

[b]首先备份你的 X4 安装目录和存档配置文件！** 是的，这个工作流程内置了备份系统，但最好手边有已知良好的安装和存档以防万一。（存档位于 [font=Courier New]Documents\Egosoft\X4\<你的配置文件ID>\[/font]。)

安装 Claude Code——任选其一：

• [b]桌面应用（最简单）： 从 [url=https://claude.ai/code]claude.ai/code[/url] 下载，安装，打开。
• [b]命令行： 安装 [url=https://nodejs.org/]Node.js[/url]（点击绿色 LTS 大按钮），打开 Windows Terminal 并运行：

npm install -g @anthropic-ai/claude-code

订阅 Claude Pro（20 美元/月）或 Claude Max（100 美元/月）——Claude Code 需要付费计划（或使用 Opencode 的免费模型；一分钱一分货）。

[b][color=#e06666]第二步：[/color]解压并运行安装程序[/b]

1. 下载此模组（手动下载）并将 zip 文件解压到_任意位置_。
2. 运行引导式安装程序——[font=Courier New]bash install.sh[/font]（Windows Git Bash / Linux / macOS）或 [font=Courier New]powershell -ExecutionPolicy Bypass -File install.ps1[/font]（PowerShell；使用显式形式是因为标准 Windows 会拒绝裸脚本）。
3. 当询问时选择一个布局。它会自动检测你的游戏、配置文件和 XRCatTool，并将结果写入 [font=Courier New].claude/x4-paths.env[/font] — 没有硬编码内容。

[b]三种安装布局：**]

• [b]separate — 工具包位于自己的文件夹中，通过配置指向游戏。如果你不确定，推荐这种：它不碰游戏文件夹，也无需对 [font=Courier New]C:\Program Files[/font] 的写权限。
• [b]in-game — 将工具包复制到你的 X4 文件夹中（经典的单工作区模式）。
• [b]global — 将技能安装到 [font=Courier New]~/.claude[/font]，使工具包能在多个模组仓库中工作。

[b][color=#e06666]第三步：[/color]在你的 X4 文件夹中打开 Claude Code[/b] [b]桌面应用：** 打开 Claude Code 并导航到你的 X4 文件夹。 [b]命令行：** 打开 Windows Terminal 并输入（使用你的真实路径）：

cd "C:\Program Files (x86)\Steam\steamapps\common\X4 Foundations"
claude

[b][color=#e06666]第四步：[/color]粘贴这段提示词（就这样）[/b]

我刚刚将 X4 基础版本 Claude Code 模组制作工具包安装到此文件夹中。运行 "bash setup.sh" 进行设置。为我安装任何缺失的必备组件（jq、uv/Python 3.13），然后确认捆绑的 x4validate 能运行（其测试套件应通过）。设置完成后，询问我想使用哪些可选工具（XRCatTool 用于解包基础游戏 / 打包模组、X4-XMLDiffAndPatch、X4_Customizer、X4CodeComplete），并帮我设置我选择使用的工具。指导我使用 XRCatTool 将我自己的基础游戏解包到本地 reference\ 文件夹中（你不会重新分发任何游戏数据）。还要询问我是否需要可选的 Nexus API 集成（模组更新检测 / 版本和更新日志检查）；如果需要，请说明如何获取免费的 Personal API Key 并将其存储在 X4_NEXUS_KEY 环境变量中。根据我的游戏版本和已安装的 DLC 定制环境。如果我们使用 BaseX，请确保设置并建立索引。检查 GitHub 是否有更新的版本，如果可用请访问 https://github.com/WingedGuardian/x4-claude-toolkit。用简单英语解释所有内容，并询问我你可能需要问的任何问题。

Claude 会处理其余部分。[b]就这样。你完成了。[/b]

_[i]关于参考树的说明：** x4validate 在指向基础游戏的解包副本时最为强大（这样它可以针对真实的合并树解析每个 [font=Courier New]sel=[/font] 和引用）。解包使用 Egosoft 的 XRCatTool——一个独立的外部工具，因此与其他工具一样未捆绑；设置程序会指引你获取并使用它。你解包自己的副本；游戏数据绝不会被共享。

[color=#e06666][size=5][b]可选：Nexus API 集成[/b][/size][/color] 给 Claude 一个免费的 Personal API Key，它就能检查模组版本、更新日期、更新日志和依赖关系——非常适合回答“我的模组有更新吗？”以及预调查之类的问题。完全可选。

• 获取免费密钥：[url=https://www.nexusmods.com/users/myaccount?tab=api]nexusmods.com > 网站偏好设置 > API 访问[/url] > 复制你的 Personal API Key。
• 将其保存到 [font=Courier New]X4_NEXUS_KEY[/font] 环境变量（[font=Courier New]setx X4_NEXUS_KEY "<你的密钥>"[/font]）。或者在设置过程中直接粘贴给 Claude，它会为你存储。
• [b]安全性： 仅供个人/本地使用。切勿分享、公开粘贴或提交。如果泄露，请在同一个页面上重新生成。

[color=#e06666][size=5][b]使用方法[/b][/size][/color] 从现在起，无论何时在你的 X4 文件夹中打开 Claude Code，完整的环境都会自动加载——知识库、安全挂钩、验证器，一切就绪。直接开始对话即可。一些可以尝试的事情：

[b]编辑与平衡性调整：**]

• "将所有的 L/XL 护盾回复速度提高 15%——先显示预演结果，然后进行验证。"
• "添加一个以能量电池为原型的新型可交易物品，包含所需的每个文件，并对照原版物品检查完整性。"
• "将 Asgard 的主炮伤害提高 10%，并告诉我这会产生哪些连锁影响。"

[b]移植、调试、调查：**]

• "这个模组是为 7.x 制作的。运行迁移检查器并修复所有 9.0 的不兼容问题。"
• "读取我的 debug.txt，告诉我哪些错误是真实的，哪些是无害噪音。"
• "我的 diff 补丁在游戏中不生效——检查 sel= 是否真的匹配合并树。"
• "这个 Nexus 模组是做什么的，在我使用前是否存在已知的 9.0 问题？"

[b]从整体上看待你的模组列表：**]

• "如果我安装这个模组会破坏什么？对照我已经安装的所有模组检查一下。"
• "现在哪个模组在真正设置 Asgard 的船体值，其他模组想设置什么？"
• "对照 Nexus 对我的模组列表进行分类处理——哪些已更新、过时，或已针对 9.0 弃用？"
• "捕获一个已知良好的基线，这样我可以在添加另外 50 个模组后对比新错误。"

[color=#e06666][size=5][b]常见问题解答[/b][/size][/color] [b]问：支持哪些游戏版本/DLC？** 知识库面向 X4 v7.x-v9.x，并包含 7.x->9.0 迁移地图。支持所有 DLC；只需告诉 Claude 你的版本和已安装的内容即可。 [b]问：我需要懂编程吗？** 不需要。你用简单英语描述你想要什么；Claude 负责 XML。工具的存在既是为了发现错误，同样也是为了捕捉你自己的失误。 [b]问：Claude 会弄坏我的模组或存档吗？** 安全挂钩应该能防止这种情况——Claude 不能写入你的参考树或直接编辑 .cat/.dat 文件，编辑模组/配置文件前必须征求许可，并会备份所有内容并留存审计日志。但 LLM 是概率性的；请保留你自己的备份（尤其是 X4 存档）。 [b]问：我必须解包基础游戏吗？** 仅为了 x4validate 的完整交叉引用能力。没有它你也可以开始；准备就绪时，设置程序会指导你使用 XRCatTool 进行解包。 [b]问：它能与 VRO / 大型大修模组一起使用吗？** 可以——而这正是重点所在。这些工具能读取打包的模组，因此大修模组重新调整的数值会出现在有效树、平衡性比较和冲突检查中。 [b]问："jq not found"？** 运行 [font=Courier New]winget install jqlang.jq[/font] 并重启 Claude Code。 [b]问：如何更新工具包？** 下载新版本并重新运行安装程序（或直接解压覆盖旧版本）。你的知识库新增内容会保留。

[color=#e06666][size=5][b]系统要求[/b][/size][/color]

• Claude Code、Opencode，或你选择的任何 Agentic 编码助手
• （如果使用 Claude）需要一个 Claude Pro 或 Max 订阅（20-100 美元/月）
• [b]Windows 10/11、Linux 或 macOS（英文原文为 Windows 10/11, Linux, or macOS）
• [b]bash — 必需；所有安全挂钩都在其下运行。Linux/macOS 自带；在 Windows 上安装 [url=https://git-scm.com/download/win]Git for Windows[/url]（Git Bash）。没有它，挂钩会静默失效。
• [b]jq — 安全挂钩所需的小型 CLI（设置程序会通过 winget/apt/brew 安装）
• [b]Wine — 仅限 Linux/macOS，用于运行 Egosoft 的 XRCatTool（一个 Windows .exe 程序）
• [b]uv + Python 3.13 — 运行捆绑的工具（设置程序会协助安装）

可选但推荐（设置程序会提供安装协助）：

• [b]XRCatTool（Egosoft）——解包基础游戏到 [font=Courier New]reference\[/font] 目录，并打包模组以供分发
• [b]X4-XMLDiffAndPatch — 生成并检查 diff 补丁格式
• [b]X4_Customizer — 程序化批量属性编辑
• [b]X4CodeComplete — 用于脚本属性和 Lua 的 VS Code 自动补全（编辑器端创作辅助工具）

无需模组管理器。解压到任意位置并运行安装程序。开源（MIT）——源代码、完整更新日志和问题追踪请访问 [url=https://github.com/WingedGuardian/x4-claude-toolkit]GitHub[/url]。X4: Foundations 是 Egosoft GmbH 的商标。