Imported from TYHH100/hd2_ArmorIsolation (
AGENTS.md). Install upstream withnpx skills add TYHH100/hd2_ArmorIsolation. Copyright stays with the author.
项目约定
- 使用中文回复，控制篇幅，按明确问题逐步推进，避免过度审计。
- 临时复制的测试文件在完成后删除；优先按需读取并在内存中解析游戏数据。
- Git 提交和推送相关信息遵守 Conventional Commits。
- 重复出现的项目问题，将必要的正确做法和易错点补充到此文件。
- 要提供外部参考的链接来源
游戏护甲分析要点
- 记录 DLL 版本和 SHA-256；明确区分磁盘文件偏移、RVA、运行时地址。
- 区分本地确认、社区结构和待验证推断。加壳 DLL 的字符串未命中，不等于功能不存在。
- Filediver 的套装/被动解析使用内置明文数据快照，不能默认已经解密本机
.dl_bin；核对版本后再使用字段和数值。 - Slim 安装通过
bundles.nxa定位包。散装 Archive 文件不存在，不等于资源缺失；避免为了查询少量 Unit 整包解压。 - 护甲显示评级、受击区域装甲值、外观部件 Weight 分开处理。共享 Unit 不代表共享被动或属性。
- 资源共用需核对类型和资源 ID；主数据相同不等于 GPU 数据、材质及运行时结果全部相同。
- 普通分析请求默认只读，不用未验证的旧偏移修改游戏。CM-14体甲与头盔、B-01 revision 4已由用户确认测试正常；现阶段开发通用生成工具，不自动部署。部署必须等游戏正常退出。
.pdata的单条异常展开范围可能只是函数片段。先核对真实入口和分支，再跨片段反汇编；不要从指令中间开始，也不要把首片段当完整函数。- 部位枚举勿混用：Slot0 头盔、1 披风、2 躯干、3 髋部；Piece 的 Type 与 Weight 是不同字段。
- 读取运行中模块后可以给出同版本原生证据，但这仍不是动态调用跟踪。UI 属性、预览对象和实际场景装配分别记录，不凭同名字符串合并。
- 资源隔离必须按
(Kit ID, 类型, 原资源 ID)建映射；改补丁文件名或只按原 ID 全局改名仍会共享。修改64位资源引用时保留32位槽/用途哈希及骨骼索引。 - 披风选择路径通常只修改既有 Slot1 Unit 的材质；按体甲隔离默认披风与按所选披风隔离模型是不同目标，不能以改 Piece.Path 的离线校验替代场景验证。
- 本机ReShade6.5.1对应SDK API17；不要直接用本机另一仓库的API20头文件构建。先按安装版本匹配SDK。
- 重打包TOC除三路磁盘偏移外，还需重算主/GPU内存缓冲偏移与头部大小；本版本按资源大小逐项向上对齐256字节累计，不能沿用旧Mod头字段。
- 私有资源补丁必须停用同目标旧ID覆盖版本；插件发布成功只代表引用更新，须另验资源加载、两种体型及其他套装外观。停用/卸载要退出游戏，已发布配置不做热恢复。
- 同名体甲与头盔是不同Kit；按套装裁剪模组前分别核对armor-names/helmet-names及目标Unit，不能将体甲Kit外的所有Unit判作污染。CM-14头盔与TR-117共享Unit，须按头盔Kit再建私有材质/纹理映射。
- 资源段 size=0 时无有效数据，TOC偏移可能是略超EOF的对齐位置；只对非空段校验读取边界，不能把空段误判为截断，也不能放宽非空段检查。
- 大型替换包按目标Unit和动态Piece纹理追踪实际依赖，勿为每个Kit复制所有源材质/纹理。外部材质既要查修改纹理交集，也要查BaseMaterial是否指回源修改材质。
- 按用户确认的隔离边界分配资源：本次B-01的Unit按Kit隔离，同一模组内部的相同材质/纹理使用一套模组私有ID共享；不要为8个变体重复复制整套纹理。与原版/其他模组隔离不等于禁止模组内部复用。
- 目标已APPLIED仍缺模型时，应检查源Unit的LOD选择与MeshInfo顺序；新增辅助网格可能令旧LOD索引失效。按原版MeshInfo标识匹配新位置并加源哈希/旧值守卫，不能盲目统一加偏移。修正候选仍须游戏实测；Unit.Bones是bones资源引用，不要误当Unit自引用重命名。
通用处理工具
- 共享 Unit 命中只表示候选影响范围，不能推断模组作者的替换意图；目标体甲和头盔必须显式选择，禁止默认全选。
- 生成器针对已验证 DLL 与 Kit 快照、完整非披风 Unit 替换；支持单补丁及通过依赖检查的旧版/V1 模组目录。部分模型、纯材质/纹理、无清单多补丁、嵌套子选项及需补克隆外部材质的输入明确报不支持，不输出半成品。
- 私有命名空间须包含输入三路内容和目标集合；同模组材质/纹理共享，每个 Kit 只等待自己的实际依赖。不同包选择相同 Kit 仍冲突，不能靠不同 DLL 文件名解决。
- B-01 的 LOD 修正仅精确匹配已验证源 Unit SHA 时应用；同资源 ID 不代表另一模组也要改相同索引。
- 生成流程在自有临时目录完成，资源及运行时配置检查通过后发布结果，失败清理；不得写入源模组或游戏目录，不覆盖已有输出。
- 通用包与固定实验包分开构建。两个固定样本游戏实测通过，不等于所有新生成包自动通过游戏验收。
- 本机 MSVC 的中文
/showIncludes曾使 Ninja 依赖记录为空；通用构建使用新临时目录和--clean-first，回归不得只运行可能陈旧的测试二进制。PowerShell 子进程和 Python 日志统一 UTF-8，避免构建成功后因输出编码中断打包。 - 通用 ReShade 插件固定为
ArmorIsolation.addon64，启动时整组读取ArmorIsolation/*.json；生成模组只输出数据和配置并复用已校验的 DLL，不再逐包编译。 - 多包配置必须先整体验证，重复 Kit、资源 ID/high32 冲突或损坏配置不得部分发布。已加载配置及发布后的内存不做热更新/热恢复，变更需完整重启游戏。
- 配置中的 Body/Piece 存储须在 Profile 移动后保持指针稳定；按 Kit 预索引 required 依赖，避免每秒在全部资源与依赖之间重复线性扫描。
- 旧包迁移从对应 manifest 导出，保留原私有 ID；CM14/B01 专用补丁兼容配置不能用于重新生成的不同 ID 补丁。旧专用插件与通用插件同时加载时通用版停止写入。
- 模块化模组先解析组件选择，再跨补丁追踪依赖；本体没有材质不等于资源缺失。不能递归启用父目录下全部 SubOptions，缺目录默认项也须显式记录，不能把任意缺文件当合法空操作。
- 有 manifest 即走模块化入口时须兼容缺 Version 的旧版清单：字符串 Options 为一组多选一，缺/null/空 Options 读取根目录；非空 Options 不叠加根补丁，目录读取不递归。仅在内存归一，保留原清单字节和格式，不靠补写 Version 规避兼容。
- 可选补丁的相同
(类型, 原 ID)可能是不同 main/GPU 的模型版本；保留完整三路来源与覆盖记录，不按文件名或原 ID 盲目去重，不把 manifest 顺序当作已验证的游戏覆盖优先级。 - 保留配件开关时整个组件集合共用一致私有映射，覆写本体的配件 Unit 使用对应私有 ID；原目录、补丁名、manifest 字节和附带文件保留。未选目标的资源也须私有改名保留，其 ID 纳入并存预留，不能复制原 ID 活动补丁继续污染。
- SubOptions 始终是单选。4K/8K 可能共用 Material ID 却使用不同 Texture ID；仅在互斥纯材质分支的材质槽和其它主数据一致、引用独占且无别名碰撞时归一逻辑纹理 ID，绝不能要求两个分辨率同时加载。同一 JSON 的依赖须证明每个允许分支均可提供；详见
docs/modular-isolation-tool.md。 - 头盔 Kit 不一定只有 Slot0；绑定快照的 TG-122 头盔还含 Slot1 默认披风。允许保留其元数据，但披风仍不参与隔离和等待，不能因头盔类型误拒绝整包，也不能放宽为允许任意体甲 Slot。
- 单文件 EXE 的内置数据从
sys._MEIPASS读取，持久输出用 EXE 所在目录，不能落在解压临时目录。窗口模式可能没有 stdout/stderr，入口须提供日志；动态 builder 和 LZ4 扩展须显式收集。打包验收要移动单个 EXE、清除 Python 搜索环境并完成实际生成，不能仅凭 GUI 启动判定依赖齐全。