Ra3ModXmlExt/README.md

RA3 Mod XML（VS Code 扩展）

面向《命令与征服：红色警戒 3》Mod XML（SAGE / BinaryAssetBuilder 格式）的 VS Code 工具扩展。

功能

• 语法高亮：在普通 XML 高亮之上叠加领域标记（$DEFINE 常量、inheritFrom、xai:joinAction、结构标签）；XML 语法异常（如未闭合引号）期间由语义 token 兜底，标签/属性/值着色不中断。
• 自动补全：
  • 元素名：按当前父元素的 XSD 模型补全子元素；顶层资产（AssetDeclaration 内）补全 GameObject、WeaponTemplate 等 295 种类型。已输入 < 时补全保留该 <、只替换名称区（不会出现 <<）；需要填文本的 simple-content 元素（如 <CreateObject>）补全为 <CreateObject>$1</CreateObject> 并自动弹出值补全，而不是无法填值的自闭合标签。
  • 属性名：必填属性优先，附带类型/文档/默认值；自动提示 xai:joinAction 与 xmlns:xai。接受补全时自动避免与上一个属性贴在一起，并按文件已有的排版补空格或换行（换行的基础缩进由编辑器提供，插件不再内嵌缩进以免叠加）；数字/角度/时间等标量属性直接填入 XSD 默认值或类型示例（如 0d、0s），引用/枚举/布尔等保留真正的 $1 占位符并弹出值补全。
  • 属性值：
    • 引用型属性（如 CommandSet、Weapon）按 xas:refType 补全对应类型的资产 ID（同名 ID 只补全匹配类型）；
    • inheritFrom 补全可继承的资产 ID；
    • 枚举与位标志列表（如 Include type、LocomotorTemplate@Surfaces、KindOf；列表值在空格后自动继续补全下一项，已使用的 flag 不再重复推荐，闭合值末尾可直接追加新 flag）；
    • 布尔值、$DEFINE 常量；
    • <Include source> 补全可解析的 DATA: / ART: / AUDIO: 与项目相对路径。
  • 元素文本内容：simple-content 引用元素（如 <CreateObject>、<RequiredUpgrade>、<SpawnTemplate>）直接在标签间补全对应类型的资产 ID（GameObjectWeakRef → GameObject）、枚举或 $DEFINE。 接受片段后的 $1 光标位置会立即弹出值补全，而不是属性名；引用列表超过 400 条时标记为不完整，继续输入会重新请求，因此 CrateDebris_01 这类排在 列表后部的 id 不会因首屏截断而消失。
• 悬停提示：元素/属性显示 XSD 文档、类型、必填/默认值；引用值显示定义位置；$DEFINE 显示值与定义位置；Include source / xi:include href 显示解析后的目标文件；xi:include 元素与属性给出 XInclude 说明。
• 引用导航：从引用值（CommandSet="..."、Weapon="..."、inheritFrom、<CreateObject>ID</CreateObject> 等元素文本）跳转到定义（严格按引用类型过滤，候选由 ra3modxml.definitionMode 控制：all 列出 mod + 原版、project-only 优先项目内定义）；Ctrl+点击 Include / xi:include href 打开目标文件；Find All References 基于语义引用索引（属性引用 + simple-content 文本 + inheritFrom，排除 id 定义点 / Poid / $DEFINE，不再全文搜索）；文档大纲列出顶层资产与 $DEFINE。
• 引用计数（CodeLens）：在“设计上应被引用”的顶部资产类型上显示 0 references / 1 reference / N references（0 也显示），点击直接打开 references peek；设置类、地图元数据、w3x 子结构等自动注册类型不显示， 避免满屏 0；manifest 资产有对应 SageXml 源码时，引用按源码定义归并计数 （打开 SageXml 源码同样能看到引用数）。
• 未引用资产：RA3 Mod XML: Find unreferenced assets… 命令按类型列出 所有零引用的项目资产并跳转；编辑器右键菜单 Find unreferenced assets of this type 可直接使用光标所在资产类型。
• 当前文档局部作用域（T1）：即使一个文件不在任何全局流里（没有从 Data/Mod.xml / additionalmaps 可达），插件也会按当前文件自身的资产、 $DEFINE 及其 include 链建立局部索引。xi:include 会在逻辑树中展开， 使 include 进来的内容获得正确的父上下文；AttachModuleId / ModuleId / AutoResolveBody 等管线局部（Poid）引用可以补全、悬停与跳转到同一 GameObject 内的模块（含通过 xi:include 拼入的兄弟模块）。
• 错误检查：XML 格式错误、未知元素/属性（xi: 等外来命名空间不误报）、顶层资产缺 id、重复 ID、未解析引用（含属性值与元素文本内容、类型不匹配）、Include / 嵌套 xi:include 目标找不到、$DEFINE 未定义。
• manifest 支持：<Include type="reference"> 指向的 static/global/audio.manifest（SDK builtmods）会被解析，manifest 中的原版资产 ID 可用于补全/悬停/导航/诊断。
• 美术资产（.w3x）：W3X.xml / ART: include 链中的 .w3x 模型文件会被 索引（W3DContainer / W3DMesh / W3DHierarchy 等顶层资产），因此 Model@Name、Hierarchy、Mesh 等引用可以解析、悬停与跳转。超大模型 （几十 MB 的顶点/三角形数据）采用浅扫描——只提取顶层资产记录、不建 DOM 树， 结果在 workspace 级缓存并跨重建复用，保存文件触发的重建不会重读未变化的模型文件。
• 索引分阶段与部分可用性：先建立 XML + manifest 索引（首建早期即可用）， w3x 美术资产随后台扫描补齐。索引完成前，语法/模型诊断、枚举与子元素补全、 Include 跳转/悬停照常工作；引用类诊断会“显示但标注” （unresolved-reference-indexing + (index incomplete) 说明），不会把 未完成的索引误当成最终结论。
• 大项目性能：索引记录（资产 / Define / Include / 引用 / 行号）与 include 解析结果跨重建缓存，保存触发的重建零 stat、零重读（Corona 实测约 2 秒）； DOM 树只按需保留并设元素预算，避免内存膨胀。编辑器外的文件改动（git pull、 导出工具）会触发防抖重建；构建期间文件再次被修改时，已发布索引会标记 (stale) 并自动重跑。include 路径解析使用目录枚举建立的文件集快照（无 statSync 风暴）；records 缓存会持久化到磁盘（gzip + 多信号 stat 校验 + 内容哈希 + 原子写），重启 VS Code 后冷启动只需秒级校验，Corona 实测约 11 秒 （首次全量约 2 分钟）。引用索引只从构建期实际消费的 records 构建；打开文档 时若发现当前文本的 records 与快照不一致（如外置盘重连后缓存过时），会自动 定向重建自愈；Re-index workspace 会对 stat 匹配的 XML 也做内容校验。

使用

1. 用 VS Code 打开 RA3 Mod 项目文件夹（含 Data/Mod.xml 或 mod.babproj）。
2. 插件自动激活并开始后台索引（状态栏显示阶段与资产数量；扩展也会在打开 任意 XML 文件时激活，非 RA3 工作区不会显示 RA3 专属功能）。
3. 编辑任意 *.xml 即可获得补全、跳转与诊断。

设置（settings.json）

设置	默认值	说明
ra3modxml.sdkPath	C:\Apps\RA3-MODSDK-X	Mod SDK 根目录
ra3modxml.indexSageXml	true	是否索引 SDK 的 SageXml 原版源码
ra3modxml.reportUnresolvedReferences	warning	未解析引用诊断级别（warning/information/none）
ra3modxml.diagnoseUnknownElements	true	是否报告未知元素/属性（自定义 XSD 项目可关闭）
ra3modxml.definitionMode	all	跳转候选：all 列出 mod 定义与原版定义（mod 优先）；project-only 仅在项目内已有定义时直接跳转 mod 定义
ra3modxml.additionalDataSearchPaths	[]	追加的 DATA: 搜索目录

命令

• RA3 Mod XML: Re-index workspace：手动重建索引。
• RA3 Mod XML: Show index report：查看索引统计。
• RA3 Mod XML: Clear caches and rebuild：清空内存/磁盘缓存并强制全量重建。
• RA3 Mod XML: Show cache report：查看磁盘缓存路径、大小、校验统计与命中数。
• RA3 Mod XML: Find unreferenced assets…：按类型查找零引用的项目资产。
• RA3 Mod XML: Find unreferenced assets of this type：右键菜单入口， 直接查找光标所在顶部资产类型的未引用资产。

开发

npm install
npm run generate-model   # 从 SDK XSD 重新生成 src/model/schema-model.json
npm test                 # 单元测试（tsc + node --test）
npm run build            # esbuild 打包到 dist/
npm run package          # 生成可安装的 .vsix

测试夹具：test/fixtures/minimod（含 include、重复 ID、同名不同类型 ID、manifest 回退等场景）。

架构

src/
  extension.ts            激活入口与 provider 注册
  workspace.ts            项目检测、索引生命周期、状态栏
  settings.ts             配置读取（sdkPath、definitionMode 等）
  language/
    xmlParser.ts          带源码偏移的轻量 XML 解析器（容错、行尾恢复）
    context.ts            补全上下文分析
    typeContext.ts        上下文感知元素类型解析
    semanticTokens.ts     语义 token 兜底高亮（纯 TS）
  model/
    schemaModel.ts        XSD 模型运行时（schema-model.json / asset-types.json 由 tools 生成）
  indexer/
    includeResolver.ts    Include 路径解析（纯 TS，移植 check_duplicate_ids.py）
    existence.ts          文件集存在性快照（目录枚举 Set，替代逐路径 statSync）
    manifestParser.ts     .manifest 二进制解析（移植 OpenSAGE ManifestFile.cs）
    fileScanner.ts        目录扫描与 Include source 候选
    refs.ts               引用目标解析（按引用类型过滤）+ “设计上可被引用类型”判定
    referenceIndex.ts     引用记录 → 反向引用索引（定义 → 引用位置）+ 未引用报告
    xpointer.ts           xi:include xpointer 子集解析（纯 TS）
    logicalTree.ts        当前文档逻辑树（xi:include 拼接、局部作用域）
    localScope.ts         文档局部索引 overlay（自身链 + include 链）
    shallowScan.ts        .w3x 等大体积美术资产顶层浅扫描（纯 TS，不建 DOM）
    records.ts            每文件紧凑索引记录（资产/Define/Include/xi/引用 + 行号偏移）
    caches.ts             跨重建持久缓存（DocumentCache / IndexRecordsCache /
                          IncludeResolveCache）+ 失效纪元 InvalidationsEpoch
    diskCache.ts          跨会话磁盘缓存（gzip JSON、原子写、多信号 stat 校验）
    indexer.ts            工作区索引器（后台、缓存、记录驱动重建、分阶段发布）
  features/               completion / hover / navigation / references / codeLens /
                          unreferenced / diagnostics / semanticTokens
syntaxes/                 TextMate 注入语法
tools/                    XSD → 模型、AssetType 枚举提取

解析/索引核心不依赖 VS Code API，可被其他工具复用（见 docs/plan.md 的远期目标：搜索与索引复用）。

参考

• 领域说明与需求：docs/requirements.md
• 调研与设计决策：docs/plan.md
• 问题分析与修复记录：docs/analysis-issues.md
• 引用计数 / 语义 FAR / 未引用资产功能设计：docs/features-reference-counts.md
• Manifest 格式参考：OpenSAGE src/OpenSage.Game/Data/StreamFS/ManifestFile.cs（本仓库 OpenSAGE/ 子目录，commit d45d361）