RA3CoronaDevelopers/Ra3ModXmlExt
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
656fab349da725b9de27d4ffa3eb49add1b01f28
Ra3ModXmlExt/docs/analysis-issues.md
T
lanyi 656fab349d 修 id 解析
2026-08-01 14:15:13 +02:00

21 KiB
Raw Blame History

问题分析：AttachTest 高亮异常与误报诊断

日期：2026-08-01。基于在 AttachTest Data/Mod.xml 上复现的问题。 本文件只做分析，代码尚未修改，修复方案见文末，待审阅后实施。

一、现象

  1. 语法高亮异常：
    • <?xml version="1.0" encoding="UTF-8"?> 显示为纯文本颜色；
    • <Includes 之后的 > 无高亮；
    • <Include type="reference" ...> 中 Include 之后的内容全部无高亮；
    • 整体表现为"只有少量标签名被着色，其余按纯文本处理"。
  2. 误报诊断：
    • <Include type="reference"> 的 type 值报 Unresolved reference "reference"；
    • <Include source="DATA:Static.xml"> 的 source 值报 Unresolved reference；
    • 同一处 hover 显示解析结果为 C:\Apps\RA3-MODSDK-X\SageXml\Static.xml，但实际应按编译参数解析到 SDK 根目录 C:\Apps\RA3-MODSDK-X\Static.xml。

二、实测证据

用当前构建代码对 AttachTest 索引后验证：

[resolve] DATA:Static.xml -> C:\Apps\RA3-MODSDK-X\Static.xml     ← 解析器结果正确
[candidate] 精确匹配      -> C:\Apps\RA3-MODSDK-X\SageXml\Static.xml  ← hover 用的是这条
[model] Include@type  refType: null  enum: [reference, instance, all]
[model] Include@source refType: null  type: anyURI
[diag]  Include@type='reference' targets: 0

三个问题均稳定复现。

三、根因分析

1. 高亮异常：grammar 注册方式覆盖了内置 XML 语法

package.json 中的 grammar 贡献写法：

{
  "language": "xml",
  "scopeName": "source.ra3modxml",
  "injectTo": ["source.xml"]
}

同时填写 language 与 injectTo 时，VS Code 会把该 grammar 注册为 xml 语言的主 grammar（替换内置 XML 语法），而不仅是注入。结果是：

  • 内置 source.xml 的完整 token 化规则不再生效；
  • 我的语法只有几个领域关键词模式，没有 XML 声明、标签括号、属性名/值的规则；
  • 于是 <?xml ...?>、>、属性区全部退化为纯文本，只有 $DEFINE、inheritFrom、结构标签名等被我的模式着色——与现象完全吻合。

正确的做法是注入式 grammar 不声明 language（VS Code 官方注入语法示例即省略该字段）。

2. 误报 Unresolved reference：诊断把所有属性值都当成"引用"检查

诊断代码在 checkValueReferences 中先调用 resolveReferenceTargets(...)，并以其返回空数组作为"未解析"依据。而 resolveReferenceTargets 对非引用属性（如 Include@type 枚举、Include@source 的 anyURI）也返回空数组——两者无法区分。

这是早期实现回归：最初代码有 isRef（检查 refType 或 inheritFrom）守卫，重构为共享函数后丢失了该守卫。

同理，hover 对非引用属性值也会走到"未找到匹配定义"分支，显示误导性文案。

3. DATA:Static.xml hover 路径错误：候选表优先于解析器，且候选表大小写不统一

  • 解析器 resolveSource 按搜索路径正确解析到 SDK 根 Static.xml；
  • 但 hover/定义跳转/文档链接都是先查 idx.sourceCandidates 精确匹配；
  • 候选表里同一 source 字符串 DATA:Static.xml 出现两条：一条来自 SageXml\Static.xml（扫描更早、排在前面），一条来自 SDK 根目录浅扫描；
  • find 精确匹配返回第一条 → 显示 SageXml 路径，而按 BAB 顺序应先命中 SDK 根目录。

修复方向相应调整为：候选表只服务补全；hover/跳转/链接一律先走 resolveSource（按 BAB 顺序校验文件存在）。候选表本身也按 source 去重并让 SDK 根目录条目排前。

另外，当前搜索路径来自 check_duplicate_ids.py 的简版（[SDK根, 项目Data, Mods, SDK/SageXml]），与 BAB 编译参数不完全一致，缺少 modGranParent 与 SDK\Mods 两个条目。defaultscript.cs 的 getIncludePaths() 实际参数为：

/data:  ".;{modGranParent};{0}\Data;.\Mods;{1};.\SageXml"
/art:   ".;{modGranParent};{0}\Art1;{0}\Art;.\Mods;{1};.\Art"
/audio: ".;{modGranParent};{0}\Audio1;{0}\Audio;.\Mods;{1};.\Audio"
其中 {0}=ModPath, {1}=modParentPath, {2}=modGranParent, "." = SDK 根目录（编译时 cd 到 SDK）

展开后（以 AttachTest 为例）：

前缀 搜索路径（BAB 顺序）
DATA SDK根 → modGranParent → Mod\Data → SDK\Mods → modParentPath → SDK\SageXml
ART SDK根 → modGranParent → Mod\Art1 → Mod\Art → SDK\Mods → modParentPath → SDK\Art
AUDIO SDK根 → modGranParent → Mod\Audio1 → Mod\Audio → SDK\Mods → modParentPath → SDK\Audio

DATA:Static.xml 在 BAB 顺序下首先命中 SDK 根的占位文件（与用户预期一致）。

四、修复方案

4.1 语法高亮（P0）

  • package.json 的 grammars 条目移除 "language": "xml"，只保留 scopeName、path、injectTo，使其成为纯粹的注入语法，叠加在内置 XML 语法之上。
  • 精简 syntaxes/ra3modxml.tmLanguage.json：保留不冲突的模式（$DEFINE 常量、inheritFrom、xai:joinAction、TODO 注释、结构标签名）；删除对 Replace/Remove 的裸词匹配（避免误染普通内容）。
  • 验证方式：扩展开发宿主中打开 Data/Mod.xml，确认 XML 声明、标签、属性恢复完整高亮且领域关键词仍有专属颜色。

4.2 诊断与 hover 的引用判断（P0）

  • 恢复"是否引用属性"守卫：仅当属性为 inheritFrom 或模型中有 refType 时才进入未解析引用检查；Include@type、Include@source 等不再误报。
  • hover 同步加守卫：非引用属性值不再显示"未找到匹配定义"文案；Include@source 走专门的"Include 源文件"分支。

4.3 Include 源解析（P0）

  • hover / 定义跳转 / 文档链接统一改为优先调用 resolveSource（按 BAB 顺序、校验文件存在），候选表只作为兜底与补全来源。
  • buildSearchPaths 对齐 BAB 编译参数：DATA/ART/AUDIO 各补上 modGranParent 与 SDK\Mods 两个搜索条目，顺序与 defaultscript.cs 一致。
  • 候选表去重改为大小写不敏感（按 source.toLowerCase() 去重），避免同一文件因大小写不同出现两条候选。

4.4 测试补充

  • 新增/更新单测：
    • 非引用属性（Include@type、Include@source）不会产生 unresolved-reference 目标；
    • DATA:Static.xml 按 BAB 顺序解析到 SDK 根目录而非 SageXml；
    • buildSearchPaths 展开结果与 BAB 参数一致（构造 SDK 内/外两种项目布局断言顺序）。
  • 回归验证：AttachTest / GenEvoTest / Corona 各索引一次，确认 0 误报、补全/跳转正常。

4.5 不在本次范围

  • P1 搜索与索引复用设计；
  • manifest 深度解析（资产类型不匹配提示的进一步细化）。

五、风险与影响

  • grammar 改动只影响高亮层，不影响索引与诊断逻辑；
  • 搜索路径顺序变化可能影响个别 include 的解析结果（更接近 BAB 真实行为），需在三个真实项目上回归；
  • 候选表去重策略变化理论上减少补全条目重复，不影响条目正确性。

六、实施结果（2026-08-01）

已按上述方案完成修复并验证：

  1. grammar 改为纯注入：package.json 的 grammars 条目移除 "language": "xml"，内置 XML 语法恢复为主语法，领域关键词以注入方式叠加。
  2. 引用属性守卫恢复：新增 isReferenceAttribute() 纯函数，诊断与 hover 仅对 inheritFrom / 带 refType 的属性做未解析引用检查；Include@type、Include@source 不再误报。
  3. Include 源解析优先 resolveSource：hover / 定义跳转 / 文档链接统一先按 BAB 顺序解析；候选表仅作补全来源并按 source 去重、SDK 根目录条目排前。
  4. 搜索路径对齐 BAB 参数：buildSearchPaths 的 DATA/ART/AUDIO 各补入 modGranParent 与 SDK\Mods，顺序与 defaultscript.cs 的 /data /art /audio 一致。

实测（AttachTest，C: 盘）：

DATA:Static.xml resolves to: C:\Apps\RA3-MODSDK-X\Static.xml   (OK，不再指向 SageXml)
DATA:static.xml candidates: 1 -> C:\Apps\RA3-MODSDK-X\Static.xml (去重生效)
isReferenceAttribute(Include,type)   = false
isReferenceAttribute(Include,source) = false
CommandSet 引用仍能解析到 LogicCommandSet 定义（无回归）

单元测试 24/24 通过（新增：BAB 搜索路径顺序、SDK 根优先于 SageXml、isReferenceAttribute 判定）。

注：本环境当前无法访问 D:\Mods\CoronaMod（D: 盘不可见），GenEvoTest / Corona 的实机回归待 D: 盘可用后补跑；相关逻辑已被 AttachTest 与单元测试覆盖。

七、问题分析（第二轮，2026-08-01）

用户在 AttachTest Guardian Tank\GameObject.xml 上报了三个新问题，均已修复并验证。

问题 A：Side="Allies" 误报"未被定义"

现象：Side="Allies" 报 unresolved reference，但 global.manifest 中存在 PlayerTemplate:Allies。

根因：Side 属性确实是引用（PlayerTemplateWeakRef → PlayerTemplate），但 manifest 解析器依赖 OpenSAGE AssetType.cs 的 TypeId 哈希表，而该表不完整（实测 Global.manifest 11268 个资产中有 2707 个哈希未知，PlayerTemplate 即缺失）。未知类型被记成 #哈希，无法与 refType=PlayerTemplate 匹配。

修复：manifest 资产名本身是 类型名:ID 格式（如 PlayerTemplate:Allies），新增 deriveAssetType()——哈希已知时用哈希；未知时从名称前缀推导类型（资产 ID 不允许含冒号，切分无歧义）。修复后 Side="Allies" 正确解析到 PlayerTemplate@Global.manifest。

问题 B：<Weapon> 报没有 Ordering 属性

现象：WeaponSetUpdate → WeaponSlotTurret → Weapon 链中 <Weapon Ordering=...> 报未知属性；XSD 里 WeaponSlot_WeaponData 确实有 Ordering。

根因：模型用"元素名→类型"的全局单映射，同名元素（如 <Weapon> 出现在武器槽、慢速死亡、引用等许多上下文）以"先到先得"注册。Weapon 被注册成 WeaponRef，因此按全局映射查不到 Ordering。这是典型的上下文相关类型问题。

修复：新增上下文感知类型解析：

  • childTypeOf(父类型, 子元素名) / elementTypeIn(父元素, 子元素名) / attributesOfType(类型)；
  • resolveElementType(元素) 沿解析树向上逐层用父类型的子元素声明解析真实类型，失败时回退全局映射。

修复后 Weapon（在 WeaponSlotTurret 下）解析为 WeaponSlot_WeaponData，Ordering 合法；且 Ordering 本身不是引用，不再被误判。

问题 C：嵌套 xi:include（第 248 行）未处理

现象：<xi:include href="DATA:Includes/HeadlightDraw2.xml" xpointer="..."> 位于元素内部（非 AssetDeclaration 直接子级），原实现只处理根级 xi:include，嵌套的一律静默忽略。

根因：索引器 walk() 只遍历根的直接子元素处理 xi:include。

修复：解析后遍历文档全部元素，对任意层级的 xi:include：解析 href（按 BAB 搜索路径）；目标缺失时产生 include-not-found 诊断（不再静默）；目标存在时记录并 walk 目标文件，使其内容/资产进入索引。href 的文档链接（Ctrl+点击）此前已可用。

举一反三的测试

  • test/typeContext.test.mjs：用真实结构（GameObject → BehaviorModules → WeaponSetUpdate → WeaponSlotTurret → Weapon）验证上下文类型解析；childTypeOf 原语断言。
  • test/manifestTypes.test.mjs：deriveAssetType 前缀推导（含无冒号/前导冒号边界）；模拟 PlayerTemplate:Allies 后 Side 引用解析成功；isReferenceAttributeOfType 判定。
  • test/indexer.test.mjs：新增嵌套 xi:include 断言——目标文件被索引、目标资产可用、缺失目标产生诊断。
  • AttachTest 实机验证：Side="Allies" → PlayerTemplate@Global.manifest；Weapon 类型 → WeaponSlot_WeaponData（含 Ordering）；HeadlightDraw2.xml 进入索引、无相关诊断。

单元测试 28/28 通过，.vsix 已重新打包。

八、问题分析（第三轮，2026-08-01）

用户在 AttachTest Guardian Tank\GameObject.xml 上报了三个问题，均已修复并验证。

问题 A：Locomotor="..." 误报 "has no definition of type true"

现象：LocomotorSet/@Locomotor 引用报错，且类型显示为 true。

根因：模型生成器把简单类型的 xas:isRef="true" 当成了 refType 值。Locomotor 的类型是 AssetReference（只有 xas:isRef="true"、没有 refType），于是 refType 被写成字符串 "true"，导致任何类型匹配都失败。这是生成器 refType 取值逻辑的 bug。

修复：

  • 生成器只从 xas:refType 取 refType，xas:isRef 只作为布尔标记 isRef（属性条目新增该字段）；
  • isReferenceAttributeOfType 对 refType 或 isRef 都视为引用；
  • resolveReferenceTargetsForType 对无类型引用（isRef 且无 refType）不做类型过滤，直接匹配同名 id——正是 Locomotor 这类"引用任意已声明资产"的语义。

修复后 Locomotor="AlliedAntiVehicleVehicleTech1Locomotor" 正确解析到 mod 的 LocomotorTemplate（以及 static.manifest 中的同名原版资产）。

问题 B：Name="AUAntiVehicleVehicleTech1_SKN" 误报 BaseRenderAssetType 未定义

现象：W3D 模型名引用报"no definition of type BaseRenderAssetType"，但资产确实存在于 static.manifest。

根因：两个叠加原因：

  1. manifest 名格式是 类型:子类型:文件名（如 W3dContainer:W3DContainer:AUANTIVEHICLEVEHICLETECH1_SKN），旧的 id 提取只切掉第一个前缀，得到 W3DContainer:AUANTIVEHICLEVEHICLETECH1_SKN，无法匹配 XML 里的 AUAntiVehicleVehicleTech1_SKN；
  2. manifest 哈希表里的类型名是 W3dContainer（小写 d），而 XSD 类型名是 W3DContainer，大小写不一致导致继承链匹配失败。

修复：

  • deriveAssetId 改为取最后一个冒号段（资产 ID 不允许含冒号），兼容 PlayerTemplate:Allies 与 W3dContainer:W3DContainer:... 两种格式；
  • canonicalTypeName 大小写不敏感规范化，typeChain / isAssignableTo / 属性查询统一走规范化；manifest 资产入库时类型名也规范化。

类型匹配严格遵循 XSD 继承链：W3DContainer / W3DMesh → BaseRenderAssetType ✓；W3DHierarchy → BaseAssetType（不是 BaseRenderAssetType）✗。实测 _SKN 只解析出 W3DContainer@Static.manifest 一个候选，碰撞盒（id 带 .OBBOX 后缀）与层级自然排除。

问题 C：跳转候选"只能打开文件、不能精确定位"

现象：Template="AlliedAntiVehicleVehicleTech1Cannon" 有两个候选——mod 定义和 SageXml\globaldata\weapon.xml（由 manifest 的 manifestSource 映射而来）。后者只打开文件、不定位。

修复：

  • 所有 XML 定义的跳转改为精确范围：用 id 属性值的起止偏移构造 Range（找不到时回退到元素起始标签），mod 与 SageXml 一致；
  • manifest 定义映射到源码文件时，同样在源码文件内查找同名 id 并精确定位（实测定位到 weapon.xml:2357）；
  • 新增配置 ra3modxml.definitionMode：all（默认，mod + 原版全部列出，mod 优先）或 project-only（项目内已定义时只跳 mod 定义）。

举一反三的测试（31/31 通过）

  • test/manifestTypes.test.mjs：deriveAssetId 最后一段提取（含 W3D/纹理双前缀、无冒号边界）；大小写规范化后的 isAssignableTo（W3dContainer→BaseRenderAssetType 为真、W3dHierarchy 为假）。
  • test/refs.test.mjs：无类型引用（LocomotorSet/@Locomotor）解析到任意声明类型的同名 id；非引用属性仍返回空。
  • AttachTest 实机：三个原始场景全部按预期（Locomotor 命中 LocomotorTemplate、_SKN 命中 W3DContainer、cannon 双候选均可精确定位）。

.vsix 已重新打包（13:33）。D 盘恢复后照旧可补跑 GenEvoTest / Corona 回归。

九、问题分析（第四轮，2026-08-01）：模块 id 被误报为未解析引用

问题：id="ModuleTag_Draw" 误报 Unresolved reference

现象：AttachTest Allied Vehicle\Guardian Tank\GameObject.xml 第 45 行

<TruckDraw
    id="ModuleTag_Draw"
    ...>

报 Unresolved reference "ModuleTag_Draw" (not found in the current index)， hover 同时显示 No matching definition of the expected declared type...。 但该 id 是 TruckDraw（GameObject 模块）自身的标识，只在所属 <GameObject /> 内部有效， 此处就是定义处，全局资产索引中不存在（也不应存在）它的定义。

根因（两层叠加）：

  1. 模型生成器丢失属性级 xas:refType：ModuleData@id 在 XSD 中声明为

    <xs:complexType name="ModuleData" xas:isPolymorphic="true">
  <xs:attribute name="id" type="Poid" xas:refType="ModuleData" />
</xs:complexType>

    refType 写在 <xs:attribute> 节点上，而 tools/xsd-to-model.mjs 只从 simple type 描述符读取 refType，属性级声明被丢弃。Poid 本身带 xas:isWeakRef="true"（“管线对象 ID”），于是该 id 在模型里变成 { type: "Poid", refType: null, isRef: true }——一个 “无类型引用”，导致所有继承自 ModuleData 的模块类型（以及 ObjectFilter、MapObject、 GameScript、AIStateTactic 等共 430 个类型）的 id 都被当作全局引用检查。

  2. id 的语义是“定义点”而非“引用”：即便 refType 正确，嵌套元素（模块、nugget、 地图对象）的 id 也只是其局部标识，检查全局 unresolved 必然误报。反过来，XSD 里确有一类 真正引用其他资产类型的 id（如 RoadObject@id 为 AssetReference + xas:refType="Road"）， 这类检查必须保留。

验证：

  • 用未修改的生成器对当前 SDK XSD 重新生成模型，与仓库内模型逐字段一致（0 差异）， 证明修复后重新生成的 diff 只落在属性级 refType 上，无无关噪音。
  • 修复后 W3DTruckDrawModuleData@id → refType: ModuleData； isReferenceAttributeOfType(...) === false；空索引下 TruckDraw@id 不再产生诊断； 全文件扫描 0 个 id 误报，61 处真实引用属性（inheritFrom、CommandSet、Side、 Locomotor、TrackMarks 等）行为不变。

修复：

  1. 生成器（tools/xsd-to-model.mjs）：collectAttributes 改为 attr["@_refType"] ?? desc?.refType（属性级优先、simple type 兜底），重新生成 schema-model.json——共恢复 444 处 refType（含继承传播），isRef 与其他字段零变化。 附带收益：Locomotor → LocomotorTemplate、Armor → ArmorTemplate、 ThingTemplate → GameObject 等此前被当作“无类型引用”的属性恢复真实类型 （第三轮中 Locomotor“无 refType”的结论实为该生成器 bug 的误判）。
  2. 局部引用规则（src/indexer/refs.ts 新增 isLocalReferenceAttribute）：
    • id：无 refType，或 refType 与元素自身类型兼容（isAssignableTo，如 W3DTruckDrawModuleData → ModuleData）→ 定义点，不做全局引用检查； refType 指向不同类型（RoadObject@id → Road）→ 保留真实引用检查；
    • 非 id 且类型为 Poid 的属性（ModuleId、AutoResolveBody、SoundRef、 AttachModuleId…）→ 管线局部引用，全局索引无法判定，不检查。 isReferenceAttributeOfType 与 resolveReferenceTargetsForType 同步使用该守卫， 诊断 / hover / 跳转 / 补全行为一致。
  3. 补全（src/features/completion.ts）：id 与 Poid 属性不再按 refType 提供 全局资产补全（模块 id 是局部的，全局资产列表是错误建议）。

测试（31 → 37，全部通过）：

  • refs.test.mjs：TruckDraw 实景结构（GameObject → Draws → TruckDraw）下 id 不再是 引用且不解析；RoadObject@id 仍是引用并能解析到 Road；AttachModuleId 等 Poid 属性 不误报；Locomotor 改为严格类型引用（同名 GameObject 不再匹配）；
  • schemaModel.test.mjs：ModuleData@id / MapObject@id / ThingTemplate / RoadObject@id / AttachModuleId 的属性级 refType 断言；
  • 回归：原有 31 个用例全部保持通过。

后续可做：GameObject 内模块 id 的“局部作用域”解析——AttachModuleId、 ModuleId 等模块引用指向同一 GameObject 内的兄弟模块，但部分引用（如武器上的 AttachModuleId）目标 GameObject 跨文件无法静态确定，本轮先统一不检查；待局部 作用域建模落地后再启用这些引用的解析与诊断。

Reference in New Issue View Git Blame Copy Permalink