Files

T

2026-09-10 19:18:15 +02:00

12 KiB

Raw Blame History

This site is not endorsed by or affiliated with Electronic Arts, or its licensors. Trademarks are the property of their respective owners. Game content and materials copyright Electronic Arts Inc. and its licensors. All Rights Reserved.

RA3 Mod XML is an unofficial player-made tool. It requires a separately installed RA3 Mod SDK.

English | 中文

RA3 Mod XML

AI 生成项目

本扩展几乎完全由 AI 生成，因此可能存在意外 bug 或边界情况。欢迎提交 bug 报告、修正与反馈。

一款面向 《命令与征服：红色警戒 3》 XML 模组的 VS Code 扩展，提供 IntelliSense、导航、引用追踪与诊断 能力。

它理解 RA3 Mod SDK 的 XML schema、资产类型、引用、include 以及原版游戏数据——编辑大型模组的体验会更接近真正的编程语言。

源码：GitHub 镜像 · Gitea

智能补全

转到定义

引用感知补全

功能特性

智能补全

基于 RA3 XML schema 与项目数据，提供上下文感知的补全。

基于 RA3 XSD 的元素与属性
必填属性、类型、文档与默认值
资产引用，如 Weapon、CommandSet 与 inheritFrom
枚举值与标志位列表，如 KindOf 与 Surfaces
文本内容元素中的资产 ID，如 <CreateObject> 与 <RequiredUpgrade>
DATA:、ART: 与 AUDIO: 路径
编辑标志位列表时的自动续写

引用补全是类型感知的，因此资产 ID 只会在其类型有效的位置被提示。

语法高亮

在保留内置 XML 语法的基础上，额外高亮 RA3 特有的结构。

导航与引用

直接在编辑器中浏览模组的资产关系图。

资产引用的转到定义（Ctrl+Click）
基于语义引用信息的查找所有引用
引用 CodeLens：显示资产被引用了多少次
元素、属性、引用与 $DEFINE 的悬停信息
Include 与 xi:include 的 Ctrl+Click 导航
顶层资产与 $DEFINE 的文档大纲

诊断

在编辑时发现常见的模组编写错误。

XML 语法错误
未知元素与属性
缺失或重复的资产 ID
无法解析的资产引用
引用了错误的资产类型
未定义的 $DEFINE

项目分析

扩展可以分析整个工作区，而不仅仅是当前打开的文件。

查找未引用的资产 会列出工作区中任何地方都未被引用的项目资产，帮助识别过时或意外未使用的定义。

运行：

RA3 Mod XML: Find unreferenced assets…

你也可以使用编辑器右键菜单查找当前资产类型的未引用资产。

原版 SDK 集成

扩展可以使用 RA3 Mod SDK 中的资产定义，让原版游戏资产参与补全、悬停、导航与诊断。

当对应的 SDK 数据可用时，支持 <Include type="reference"> 引用的 manifest，例如 SDK builtmods 目录下的 static.manifest、global.manifest 与 audio.manifest。

大型模组支持

工作区索引在后台运行，并使用持久化缓存，避免每次启动 VS Code 时都重建全部数据。

扩展已在大型 RA3 模组日冕 Mod 上测试：

32000+ 资产
8000+ XML 文件
3000+ W3X 文件
完整索引： 约 3 分钟
缓存启动： 约 40 秒校验缓存数据并重建内存索引

以上数据在机械硬盘上测得。实际性能取决于硬件与项目结构。

开始使用

从 VS Code Marketplace 安装扩展。
在 VS Code 中打开 RA3 Mod 项目文件夹。
确保工作区包含 Data/Mod.xml、Data/additionalmaps/mapmetadata_*.xml 或 *.babproj 文件。
如有必要，配置 RA3 Mod SDK 路径——扩展可以从 Windows 注册表自动检测已安装的 SDK，也可以手动选择文件夹；留空则进入仅项目模式。
打开任意 *.xml 文件开始编辑。

扩展会自动检测 RA3 Mod 工作区并在后台开始索引。当缺少 SDK 时，状态栏会给出提示，并在每个会话中提供一次一键设置入口。

配置

设置	默认值	说明
`ra3modxml.sdkPath`	(空)	RA3 Mod SDK 的路径；留空则禁用原版 SDK 功能（仅项目模式）
`ra3modxml.indexSageXml`	`true`	索引 SDK `SageXml` 目录中的原版 XML 定义
`ra3modxml.reportUnresolvedReferences`	`warning`	无法解析引用的诊断级别：`warning`、`information` 或 `none`
`ra3modxml.diagnoseUnknownElements`	`true`	报告未知的 XML 元素与属性
`ra3modxml.definitionMode`	`all`	导航引用时选择项目定义或原版定义
`ra3modxml.additionalDataSearchPaths`	`[]`	额外的 `DATA:` 路径搜索目录

如果已安装 SDK，扩展会从注册表检测到它并提供一键设置；也可以手动设置 ra3modxml.sdkPath，或使用 RA3 Mod XML: Configure SDK path… 命令。

ra3modxml.sdkPath 的默认值本身就是空字符串。不修改该设置不会抑制 SDK 设置提示；只有显式把它设为空字符串，才表示永久禁用 SDK 功能。

命令

RA3 Mod XML: Re-index workspace（重新索引工作区）
RA3 Mod XML: Show index report（显示索引报告）
RA3 Mod XML: Clear caches and rebuild（清除缓存并重建）
RA3 Mod XML: Configure SDK path…（配置 SDK 路径）
RA3 Mod XML: Show cache report（显示缓存报告）
RA3 Mod XML: Find unreferenced assets…（查找未引用的资产…）
RA3 Mod XML: Find unreferenced assets of this type（查找此类型的未引用资产）
RA3 Mod XML: Enable AI Agent access…（启用 AI Agent 访问…）
RA3 Mod XML: Install Agent Skill…（安装 Agent Skill…）
RA3 Mod XML: Export AI Agent index snapshot（导出 AI Agent 索引快照）

AI Agent 访问

扩展可以通过本地只读 MCP（Model Context Protocol）Server，把语义索引提供给 AI Agent 使用。该功能可选，不会修改 PATH，也不会注册全局命令。

运行：

RA3 Mod XML: Enable AI Agent access…

该命令会：

为当前项目导出稳定的索引快照；
在 ~/.ra3modxml/ 下创建稳定 launcher；
在 VS Code 运行期间启动本地只读查询服务；
让用户选择：
- 安装 ra3-mod-xml Agent Skill 到 ~/.agents/skills/（也可选择 Claude Code 或项目级目录）；
- 写入 Claude Desktop / Cursor 的 MCP 配置；
- 复制通用 MCP 配置。

MCP Server 在扩展运行时优先查询内存中的实时索引；扩展关闭后回退到最近一次导出的快照。暴露的工具包括资产定义查询、语义引用查询、正向引用边（get_asset_references：该资产用了哪些资产、通过哪个元素/属性、写在 XML 的哪一行）、文件是否有效 include、$DEFINE 查询以及 Include source 解析。

get_asset_references 会沿 inheritFrom 祖先链遍历，并用 definedIn 标出条目实际写在哪个祖先的文件里，因此"这个单位自己没有 WeaponSetUpdate，但它继承的基础单位有"可以在一次调用里回答。它受 depth（默认 1，上限 3）、targetTypes 与 maxEdges 三重限制，并在截断时显式报告，而不是静默丢弃结果。

Endpoint 按项目存放（~/.ra3modxml/endpoints/<project>.json），因此多个 VS Code 窗口可以同时启用 AI Agent 访问而不互相覆盖，客户端也不会被静默地用另一个项目的数据回答。每个窗口还会在 ~/.ra3modxml/instances/ 下登记自己，并由一份合并的只读 ~/.ra3modxml/index.json 列出当前实例与项目根。崩溃残留的实例会被下一个启动的实例顺手清理，不需要先重新打开同一个工作区。

不需要安装 Node。 launcher 使用 VS Code 自带的 Electron 二进制（ELECTRON_RUN_AS_NODE=1）运行内置的 MCP Server，只有在该二进制缺失时才回退到 PATH 上的 node。launcher 在每次激活时重写，所以升级或移动 VS Code 都不会让已有的 MCP 配置失效。

MCP Server 本质上就是 stdio 上的 JSON-RPC，因此 agent 也可以完全不做 MCP 配置，直接把请求管道给 launcher。另有一个配套 CLI（cli.js，与 mcpServer.js 同在 dist/agent/）：VS Code 运行时走实时索引，否则读导出的快照；需要元素上下文的命令会明确说明，而不是返回空结果。

完整设计与进度见 docs/ai-agent-integration-plan.md。

环境要求

Visual Studio Code
安装 Red Alert 3 Mod SDK，以获得完整的 schema 与原版资产支持
包含 Data/Mod.xml、Data/additionalmaps/mapmetadata_*.xml 或 *.babproj 文件的 RA3 Mod 项目

开发

npm install

npm run generate-model   # 从 SDK XSD 生成运行时 schema 模型
npm test                 # 运行单元测试
npm run build            # 构建扩展
npm run package          # 打包 .vsix

测试夹具位于 test/fixtures/minimod，覆盖 include、重复 ID、同名不同类型 ID 以及 manifest 回退等场景。

架构

扩展围绕一个与 VS Code 无关的解析与索引核心组织：

src/
  extension.ts
  projectRoot.ts
  workspace.ts
  settings.ts

  language/
    xmlParser.ts
    context.ts
    typeContext.ts
    semanticTokens.ts

  model/
    schemaModel.ts
    schema-model.json   # 生成的 XSD 模型，随扩展打包
    asset-types.json    # 生成的 AssetType 哈希表，随扩展打包

  indexer/
    includeResolver.ts
    existence.ts
    manifestParser.ts
    fileScanner.ts
    refs.ts
    referenceIndex.ts
    xpointer.ts
    logicalTree.ts
    localScope.ts
    shallowScan.ts
    records.ts
    caches.ts
    diskCache.ts
    indexer.ts
    types.ts

  features/
    completion.ts
    hover.ts
    navigation.ts
    references.ts
    codeLens.ts
    unreferenced.ts
    diagnostics.ts
    semanticTokens.ts

syntaxes/
  ra3modxml.tmLanguage.json   # 注入式领域语法（保留内置 XML 语法）

tools/
  xsd-to-model.mjs            # 从 SDK XSD 生成 schema-model.json
  extract-asset-types.mjs     # 从 OpenSAGE 提取 AssetType 哈希

参考

OpenSAGE ManifestFile.cs — manifest 格式参考

12 KiB Raw Blame History Unescape Escape