90CNServer/pvf/docs/MOD.md

Mod 格式扩展

分层

• internal/mod 定义中立包模型、格式注册表和独立的 Reader / Writer 接口，不依赖 Wails、归档服务或版本库。
• Package 保存名称和操作集合。replace 携带明确编码的文件内容，merge-list / merge-strings 携带键值条目，delete 表达整文件删除。
• services.ExportService 将选中文件、相对 HEAD 的工作区改动或提交前后状态适配为包模型；负责依赖补齐、预检、修订校验和目录发布。
• 前端四类导出入口只指定来源，不包含格式专属的目录或编码规则。

添加格式

向注册表注册稳定 ID、显示名称、支持的操作以及读取器或写入器。读取和写入能力根据实际接口计算，不使用空实现冒充支持。

写入器先通过 Validate 检查包是否可表达，Files 描述实际输出路径及对应的包条目，再通过 Write 写入隔离的临时目录。Files 中没有 EntryPath 的文件为必需的生成元数据，不可移除。写入器不负责目录选择、覆盖确认或修改归档。

导入通过 Reader.Detect(fs.FS) 识别格式，Reader.Read(fs.FS) 返回同一 Package，再由服务层执行导入预览和归档暂存事务。外部文件路径不能直接成为写入路径；导入器需要校验包内路径和操作，并复用现有暂存、索引重建及版本变更记录流程。当前已注册 110USextend 和 115CN-mod，现有“导入”弹窗中的“Mod”选项提供入口。实现 ArchiveWriter 的格式直接发布单个 ZIP，其余格式保留目录发布。

110USextend

导出结果是父目录下的 <mod名称>-<版本号>/，包含 pack.json 和实际用到的 pvf/、merge/。版本号可填写，默认或留空为 1.0，不强制 semver；最多 128 字节，不允许控制字符和首尾空格。优先级 100、启用，types 记录整文件替换项的 PVF 类型。文本使用 UTF-8，无 BOM。

普通脚本和文本整份放入 pvf/<归档路径>；.lst、.str 使用 merge/<归档路径>。版本导出只包含新增、修改的表条目（新增表以空表为基线）；选中文件、文件集或未启用版本控制的内存改动没有准确基线，跳过显式选择的整表，不全量导出。列表按编号匹配，文字表按第一个 > 分割并保留空值及文字中的空格；忽略有缩进的 // 注释和空行。

该格式不支持删除，预检会提示跳过的文件或表条目删除。只有删除或没有可应用条目的包不能导出。无法解析的文字表行跳过；无法解析或读取的依赖表、无法准确提取改动的合并表及未能补齐的依赖也跳过，记录文件路径、行号或原因到 [pvfine:export] 日志，并在确认弹窗汇总警告。非法目标路径、不能表达的输出内容仍阻止导出，不以改名绕过安全校验。

依赖补齐默认关闭。开启后，从同一来源状态补齐脚本引用的文字表条目、表号映射及配置列表中匹配的登记项；显式内容优先，重复项去重。历史版本使用该提交快照，不读取当前工作区内容。不补齐任意脚本、sprite、sounds、npk 资源。

直接导出保留既有行为：版本新增或修改输出后状态，删除输出前状态。导出不会应用编辑器草稿、创建版本或保存 PVF。

未启用版本控制的“当前内存改动”从归档 overlay 枚举所有现存修改和新增文件；mod 模式跳过无版本基线的 lst/str，直接导出仍保留整文件；已删除文件不在该范围中。

所有确认弹窗列出完整输出树，勾选文件可控制最终输出范围。排除作用于已冻结的预览，不重新计算依赖，也不会自动补回被排除的依赖文件。已有预览刷新或切换模式时保留相同输出路径的排除，新弹窗重置；选空时不可导出。mod 元数据根据最终保留条目重新生成。

未选择合并来源时，只改名称或版本号会复用同一有效内容快照，不重新解码文件、计算差异或扫描依赖。快照过期时间不延长，归档、工作区或版本会话变化后不可复用。日志分别记录锁等待、来源读取、差异提取、依赖补齐和总耗时；普通脚本不读取不必要的修改前内容，无文字表引用时不读取表号映射或文字表。

导出时合并已有 MOD

导出为 mod 时，可在依赖开关后选择一个相同格式的已有 MOD。110USextend 选择目录；115CN-mod 可选择目录、ZIP 或 .dnfmod。普通文件同路径冲突时使用本次内容；同类型的 lst/str 合并操作按键合并，同键使用本次值，保留已有 MOD 的其余文件及键。选择已有 MOD 后，自动读取包内名称及版本号；纯数字分段版本递增最后一段（如 1.0 → 1.1、1.2.3 → 1.2.4），保留末段前导零，其他版本保留原值并提示手动修改。名称和版本号仍可编辑，ID 使用本次输入。输出目录名为 <mod名称>-<版本号>/，ZIP 为 <mod名称>-<版本号>.zip，不覆盖已有 MOD。版本号留空时包名采用格式默认版本；名称与版本号组合必须是合法文件名。

已有内容经过读取、合并和格式校验后进入同一预览树，可以取消勾选。每次准备预览都会重新读取合并来源；执行时使用冻结内容，不再读取源 MOD。切换格式或重新打开弹窗会清除来源；取消文件选择保留原来源。115CN 的全部组件合并为基础内容；互斥组件或组件目标冲突会阻止合并。

当前仅合并 PVF 内容，不复制 NPK/BK2 等客户端资源、包级依赖/冲突和其他包元数据。

Mod 导入

工具栏“导入”中选择“Mod”和导入格式，再选择单个 mod 目录。格式选项由 ModImportService.Formats() 从注册表加载，只列出拥有 Reader 的格式；服务按显式传入的格式 ID 调用对应的 Detect / Read，目录与所选格式不匹配时拒绝预览，不回退到其他读取器。后续格式注册读取器后即可出现在导入选项中。110USextend 目录需包含 pack.json。当前支持读取本工具导出的 110USextend 包；pvf/ 中每个替换文件必须在 pack.json.types 中声明类型（1 为脚本、3 为文本），声明的文件必须存在。仅处理 pvf/ 和 merge/，不导入 sprite、sounds、npk 等游戏资源，不支持删除操作。

预览显示所有文件的新增/更新状态、整文件替换或表合并方式；展开表文件显示每个传入键的新增/覆盖状态、新值和原值。整文件替换使用包中声明的类型；.lst 按编号合并，.str 按第一个 > 拆分后按文字键合并，同键覆盖并保留无关条目。文字表保留空值、值中的空格和 >，以及当前表中未改动的行和注释。归档中不存在的合并表会新建；已有合并表类型必须匹配。

读取器拒绝非法路径、大小写路径冲突、文件/目录冲突、符号链接、非普通文件、敏感配置路径、无效编码、重复传入合并键及无法解析的合并行。包内文本必须是无 BOM 的 UTF-8；合并行忽略空行和有缩进的 // 注释。现有目标表无法准确解析时阻止导入，避免丢失条目。

ModImportService 在隔离归档上预检并冻结合并后的文件内容，确认时不重新读取目录。预览有效期为 10 分钟；归档、工作区修订或版本会话发生变化后必须重新预览。取消或重新选择会释放旧预览。确认导入复用文件导入暂存事务、索引更新及版本记录，预检或暂存失败不安装部分文件。启用版本控制时记录一组“导入 Mod”变更，可撤销；不会自动提交版本或保存 PVF。编辑器草稿仍由既有归档变更刷新流程处理。

115CN-mod

格式 ID 为 115CN-mod。配置使用 UTF-8 mod.json，要求 schema: 1、client: "115CN"、kind: "resource"。读取目录、.zip、.dnfmod，配置可在根目录或唯一的一层包目录内；也兼容旧 ZIP 的 GB18030 中文包目录。RAR、7z、JAR 不接受。不解压到游戏目录，不执行包内程序或脚本。

PVF 操作通过 component 关联组件，source 相对包根目录，path 为小写 PVF 路径：

• add：仅新增，目标存在时整批预检失败。
• replace：整份替换，目标不存在时新增。
• merge：仅支持 .lst 按编号合并、.str 按文字键合并。同键覆盖，其他条目保留。
• type：示例包使用的可选字段，1 为脚本、3 为文本。省略时 .str / .nut 推断为 3，其他为 1；合并表必须匹配对应类型。
• patch：提供的文档片段和示例包未包含标签补丁字段协议，当前明确拒绝，不猜测、忽略或降级成整文件替换。需补充登录器 ModExamples/README.md 中的完整协议后接入。

导入预览按 defaultSelected 初始化组件，勾选后从冻结的包内容重新预检。requires 必须同时选中，exclusiveGroup 同组最多选一项；未知组件、循环依赖、所选组件的重复目标及文件/目录冲突拒绝。全不选时禁止执行。切换不延长原预览的 10 分钟期限，源 ZIP 变化不影响已冻结的内容，归档修订变化后必须重新预览。现有 Unicode 文字表的尾部 NUL 终止符原样保留，其他无法解析的行仍阻止合并。

files 中的客户端资源仅校验声明的组件、路径、size 与 sha256 字段格式，并在预览警告中报告；不读取或校验资源正文摘要、不写入 PVF、不安装或备份 NPK/BK2。包级 requires / conflicts 提示用户在登录器核对，不模拟 MOD 管理器的安装、排序、关闭或恢复状态。资源安装、已有视频恢复和依赖管理仍由登录器负责。

导出复用现有来源、精确表差异和依赖补齐，生成 <名称>.zip，根目录为 mod.json 和 pvf/，单个默认组件 base。新增独立 MOD ID 输入框：初次生成唯一 ID，发布同一 MOD 的更新需填回原 ID；ID 只能为 1–64 个小写字母、数字、-、_。名称/版本/ID 更新复用有效内容快照。筛选文件后同步重建清单，不携带被排除的载荷。ZIP 写完后原子发布，拒绝覆盖已有同名包。MCP export_prepare 选择此格式时同样必须提供 modId。

ZIP 拒绝路径穿越、大小写路径冲突、符号链接、特殊文件和敏感配置路径；声明文件读取也检查父目录链接。限制 ZIP 最多 20,000 项、单项 64 MiB、总展开大小 512 MiB，清单 4 MiB。目录包同样限制 PVF 单文件和累计读取大小。不会读取未登记的 PVF 载荷。

验证

运行 go test ./...、前端 npm test 和 npm run build。真实归档的新增导出验证需要设置 PVF_TESTFILE；示例包和游戏目录不作为可写测试目标。

115CN 示例读取回归：设置 PVF_MOD_TESTFILE 为 ZIP 路径，运行 go test ./internal/mod -run '^TestCN115RealMOD$' -v。真实归档预检另外设置 PVF_MOD_ARCHIVE 为测试 PVF，运行 go test ./services -run '^TestCN115RealMODPreflight$' -v -timeout 15m。两者均只读源文件，不自动执行或保存 PVF。