# 错误、输出与恢复

先保留原文件和错误信息；不要反复对唯一副本执行写入。普通 CLI 成功退出为0；格式/参数错误通常为2，清单等批量报告可能以1表示部分失败。退出码的上下文见 commands.md。

| 现象 | 含义与下一步 |
|---|---|
| Unsupported version / encoding / compression | 已识别格式不在支持子集，或头部损坏。用 capabilities 对照版本和压缩组合；不要强行更改头部数字后重试。 |
| VPK offset exceeds supported range | 偏移超过2147483647。当前版本明确不支持该范围；不能通过增大单文件预算解决。选择其他成熟工具提取后，再处理小文件。 |
| 找不到编号分卷 | 同时选择 `*_dir.vpk` 与对应 `*_NNN.vpk`，文件名、目录和来源版本须匹配；不要用其他归档的同名分卷替代。 |
| CRC32 mismatch | preload 或文件正文不匹配索引，可能缺卷、截断或损坏。重新取得同一来源文件；不要关闭校验后直接分发。 |
| 输入/目录超过预算 | 对照 support.md 的 CLI 与浏览器上限和计量单位。浏览器合计16MiB；CLI资源默认64MiB，VPK目录16MiB。库预算调整也不能突破偏移表示范围。 |
| Cannot write temporary output / backup / EFBIG / ENOSPC | 检查空间、写权限和文件大小限制。失败不会替换原文件；未完成的自建临时文件/备份会清理，已完成的备份可能保留。修正环境后重新预览。 |
| 已有输出目录/文件或备份 | 防止覆盖用户数据。使用新的输出路径；先确认原文件和备份内容，再归档已有备份。 |
| 未解决依赖 | 查看报告中 source/reference/kind/status 和挂载顺序。补充缺失文件或显式基础游戏挂载。strict=false 是保留缺口的人工选择，不是修复。 |
| 输入在保存期间被修改 | 检查发现源文件改变时拒绝替换。先退出会改写同一配置的程序，或编辑副本；保存前检查不等于跨进程排他锁，不承诺非合作写入者之间的原子仲裁。 |
| fuzzy / stale / placeholder | 源文变化或译文不满足选定规则。检查具体令牌及参数身份，复核译文后再导出。 |
| 工作台解析器异常/超过30秒 | 当前操作停止，原文件未写回；修正输入、缩小范围或使用 CLI。后续请求会启动新 Worker。 |
| 新文件读取失败 | 资源面板清除旧模型并禁用相关下载。重新选择有效输入；不把旧模型冒充新文件输出。 |

浏览器文件选择、模型与文本的关系见 editor.md。DMX 文本修改后必须重新解析，才能从新模型导出；二进制 KV3 的 JSON 模型导出仍会经过核心验证。

## 可复现故障信息

报告产品版本、平台、命令（移除私人路径）、完整错误、格式版本，以及允许公开的最小样例。原始 Steam 配置可能含账户或安装信息，应先脱敏。日志不需要包含令牌或密码。