# KV1 文本兼容性

本说明描述当前实际实现，不代表 KV1、KV2、KV3 的全部行为。

| 功能 | 当前行为 |
|---|---|
| 文档根 | 零个或多个键值条目 |
| 对象 | 花括号包围的有序条目数组 |
| 重复键 | 保留全部项与顺序 |
| 字符串 | 引号字符串和不带引号的 token |
| 空字符串／空键 | 支持带引号形式 |
| 注释 | 支持 token 之间的 `//` 行注释 |
| URL 中的 `//` | 在字符串内作为普通数据 |
| Unicode | 保留 Unicode 标量，不做规范化 |
| BOM | 接受文档开头的一个 BOM |
| 换行位置 | 支持 LF、CRLF 和 CR 行计数 |
| 转义 | 默认支持反斜杠、双引号、换行、回车、制表符的转义；其他转义报错 |
| 字面模式 | `escape_sequences: false` 时反斜杠按字面处理 |
| 规范化写出 | 总是输出启用转义的带引号文本 |
| `#include`／`#base` | 根级指令通过 `load_resolved` 和显式加载回调展开；普通 `parse` 拒绝根级指令；对象内部同名键为普通数据 |
| `[$WIN32]` 等条件 | `conditions: Some([...])` 显式求值；默认 `None` 拒绝条件 |
| 等号 | 可选的键值分隔符，条件可位于键后、等号后、值后；不带引号的等号需改用引号字符串 |
| 标准二进制 KV1 | 独立类型模型支持标准 0–7、10 类型和结束标记 8，详见扩展说明 |
| 外部字符串表 | 可显式提供键表读写二进制索引，Steam appinfo 41 自动读取其表 |
| Steam 缓存 | appinfo 39/40/41、packageinfo 39/40；未知版本拒绝 |
| 文本 KV3 | 独立模型支持，详见 [进阶功能](advanced.md) |
| KV2、二进制 KV3、VBKV | 未实现 |
| 原始注释与排版保留 | SourceDocument 保留未求值条件与引用，支持风格沿用、局部编辑和事务；stringify 规范化写出 |

普通字符串查询区分大小写，路径中的每一层选择第一个同名条目。Steam 模型的字段查询使用 ASCII 不区分大小写匹配，同样选择首项。`Document::to_json` 将每层对象输出为 `[{"key":...,"value":...}]`，不静默折叠成普通 JSON 对象。

默认限制为：8,388,608 个输入字符、1,048,576 个单 token 解码后字符、100,000 个全局条目、128 层对象。输入和 token 计数按 Unicode 标量；解析诊断的偏移也是 Unicode 标量索引。行列从 1 开始，偏移从 0 开始。配置的解析深度上限不能超过 256；写出器独立限制为 128 层。

默认模式对于未知的反斜杠转义采用严格错误处理。读取未转义的 Windows 路径时，应由调用方显式选择字面模式。规范化输出总是启用转义，因此应使用默认解析模式重新读取。

根级 `#include` 和 `#base` 被保留为指令键，规范化写出器拒绝将其作为根级普通条目生成。NUL 不可作为 KV1 字符串数据解析或写出。

兼容性证据包括独立测试、生成式测试、与 `vdf==3.4` 的文本双向差分检查和 24 组二进制参考向量。差分验证覆盖共同支持的字符串、对象和重复键，不代表完整 Valve 行为兼容。Python 参考实现对空根二进制、UTF-16 宽字符串、严格非法 UTF-8 和未知转义的处理存在差异，因此这些边界使用单独的格式与错误测试，未混入共同子集对比。

文件引用、平台条件与源编辑的语义及限制见 [扩展 API](extensions.md)。引用加载由调用方授权，不自动访问磁盘。引用累计预算包含每次加载与全部解析条目；`#base` 对同名项按出现次序配对递归合并，本地标量优先。二进制限制的计量单位为字节，文本限制为 Unicode 标量。

`parse_preserving` 与流式事件接口提供原文视图，不使用普通 parse 的条件拒绝策略：它们验证条件语法并保留所有分支，根级引用作为原文条目保留。条件过滤与文件加载须通过独立接口显式执行。与第二个成熟参考实现的共同子集及三个固定版本差异见 [参考差异](reference-differences.md)。