Skip to content

增量、提交与迁移契约 ​

状态:增量契约与接入中实现。聊天、空间、收藏、名单与生成对话任务已接正式归档更新,旧 MessageJournal 仍用于 历史任务兼容。

选项与归档身份 ​

界面不提供增量支持开关,在导出格式旁显示「仅 JSON、JSONL、JSONL(压缩)支持增量导出」。显式选择 WeQ JSON/JSONL 时自动写入增量元数据,不自动追加格式;ChatLab 不属于原生归档。 媒体是否下载独立控制,不为支持增量强制下载。定时任务保留内容策略,并记住成功保存的归档。

启用后选择原正式归档文件或目录,按 archiveId/version/account 校验同一归档;profile 只说明内容范围,不是兼容性或归档身份条件。 单文件可直接更新自身;整包持续在原目录新增/替换正式数据并复用 media。不创建每轮全量 子包。未启用的 JSON/JSONL 仍可读、可分析;之后显式开启时先验证正式文件并建立可重建 索引,不要求此前曾留隐藏基线。不开启的 HTML/TXT/表格任务不另存正文作增量后门。

保持同一账号和对象身份,可以扩展读取范围,旧记录不被新范围筛掉。精确选择任务只读取 本轮明确对象,不能为了增量扫描未选内容;全会话任务重新枚举选中来源,发现晚到历史, 不只以 max(time/seq) 截断。缺少可靠变化游标时完整扫描选中集合,不能用不可靠高水位 冒称无遗漏。来源变化的低成本探测只决定是否尝试读取,不代替记录内容比较。

版本与默认读取 ​

  • 相同 (id, revision) 在 records 只存一次;新来源观察追加到 observations,不复制正文。
  • 正文、业务属性、明确状态或覆盖事实变化生成新 revision;附件取得变化只追加 Resource 回执。相同数据、相同观察 ID、相同资源回执重复重试是幂等 no-op,不追加空批次。
  • Observation.id 在同一次读取重试中保持不变;新一次真实扫描允许新的观察时间与 ID。 不同扫描同内容只增加小型观察,不制造正文版本。
  • 分析默认按 observedAt 选择对象最近观察,时间相同时按已提交顺序确定;来源 modifiedAt 单独提供给分析者,不把不同来源的时间戳假定为同一可信时钟。
  • 历史 observedAt=null 或无时区 local 不能与真实时刻比较,不用 importedAt 替代。 默认将不可排序观察放在可排序观察之前,同类按提交顺序;展示时间不确定及全部冲突版本。
  • 最新观察是 partial 时,只将实际取得的字段作为新事实;缺席字段回看最近可用版本。 对正文、评论、附件集合以完整语义单元回退,不按数组下标拼新旧内容。未知/截断的新 正文不能抹掉完整旧正文;同时展示最新观察缺项以及实际采用的旧版本引用。explicit null 和明确清空不等于缺席,来源证明清空时保留新值和旧版历史。
  • 源间冲突保留各版本、各自来源和观察顺序;默认视图不是“冲突已解决”。full 投影 basic 后相同版本合并,保持所有不同来源观察;未知信息不能从 basic 自动恢复。
  • 明确 deleted 新版 data 保留原身份;没有现存正文可用空 content,coverage 说明原因。 读者展示删除状态并允许查看旧版,不把删除对象默认还原成旧版 present。本轮没有出现、 服务端无权读取或本地缓存清理都不是删除证据。

JSON 的提交 ​

只流读旧正式 JSON 和新增对象,在同目录创建本次独占临时文件;写完、校验 schema 与跨 记录关系、fsync 文件后原子替换,再 fsync 父目录(平台支持时)。原正式文件是恢复依据, 禁止先截断原件。不保留常驻完整 journal 或强制 .bak;临时新文件是一次替换所需空间, 不是零额外空间。写前按旧文件与新增量估算临时峰值,空间不足保持原件并报告失败。

一个 archive 同时只允许一个 writer。锁创建后立即写入进程/主机,归档身份由正式 header 校验,结合正式文件指纹检测外部变化。本机进程已退出时可串行回收遗留锁;仍存活、其他 主机或不可确认锁失效时明确返回“正在更新”,不接管他人写入。移动后的归档按 archiveId 重新建索引,不依赖旧绝对路径。目标掉盘时停止写入,不在旧挂载点创建替代目录。

资源先写同目录临时文件、校验实际 hash/size,独占发布到 media,再提交引用它的数据。 中断可能留下未引用文件;不把它当成功资源,不自动删除未知或历史文件。重复文件核对 实际字节后复用,不仅比较文件大小。不用可修改硬链接连接正式数据与隐藏基线。

业务任务从已保存的文件/整包继续,重新读取原来选中的来源;生成对话例外,继续使用确认 快照而不触发模型。增量轮次仅生成并合并 JSON/JSONL,非结构化副本保持原样。空间相册 分卷保留独立 archive-part 身份,并与说说复用包根的媒体;各正式文件分别提交,某一分卷 失败后重试复用本轮 scanId,已经提交的相同观察不重复追加。删除任务只清理自身缓存。

JSONL 的提交 ​

每一行是 stream.schema.json 的一个对象,UTF-8、LF 结尾;正文换行必须转义。第一行 且仅第一行是 {type:"header",header:...},其后是批次。空归档也写一个 entries=0 的初始 commit,之后不为了重复执行追加空 commit。所有内容行都属于正式可读格式。

行 type字段含义
revisionbatchId、record统一领域结构的新版本,可带 native,不按 header.profile 分派或排斥
observationbatchId、observation来源观察,可引用本批或此前版本
resourcebatchId、resource新资源回执,可引用已经写好的 media
commitbatchId、sequence、entries、sha256、previous批次提交,不含正文

批次连续、不交错;batchId 唯一且持久,sequence 从字符串 "1" 连续增加。 entries 计本批 commit 之前三种内容行数。sha256 为各内容行对象的 C(line) + "\n" 按顺序拼接后的 UTF-8 SHA-256。previous 为前一 commit 对象的 sha256(UTF8(C(commit))), 首批 null。事件源字节允许空白排版变化,但摘要总按 C 计算;不接受重复 JSON 键。

writer 先写内容行并 fsync,再写完整 commit 行并 fsync;只有完整 LF、摘要、前链、计数、 schema、引用和序列全部通过的批次才提交。一个批次内允许前向引用,不能引用 后续尚未提交批次。暂停、失败和续作只承认最近一次有效 commit。

读者不在数据校验错误时静默跳过。EOF 的未换行尾段、尚无 commit 的尾批为未提交;只读 查看可展示已提交前缀并明确提示尾部存在,writer 在独占锁下确认后仅截去未提交尾部。 已完整提交区的坏行、错误 hash、断链、重复 batchId、计数错误或引用失败必须报错并停止 更新,不能按“截断尾巴”掩盖损坏。持久恢复索引丢失时从头流扫验证提交链重建,内存只 保留身份/版本与偏移索引,不全量加载正文。

JSON 与 JSONL 的等价对象是 header + 去重版本集合 + 有序观察/资源回执数组,不含提交 包装;不同类型内容行之间的交织位置不影响等价性,但 observations 和 resources 各自 内部顺序必须保留。最新视图使用该顺序与观察时刻;不允许转换器任意重排后仍称等价。 JSONL 只能追加新对象,不能将旧正文每轮再 写一遍。两种格式同时显式选择时的第二份正文是用户要求的第二格式,不是基线。

内容范围、版本与旧格式迁移 ​

JSONL 压缩存储 ​

jsonl.gz 是导出选项及文件扩展名,不是新的逻辑协议。解压后的 header 仍将 formats / incremental.authority 记为 jsonl,沿用 weq-export/1.0 的完整行与提交语义。 同时显式选择普通和压缩 JSONL 会生成两份文件,各自接受后续增量,不暗中附加正文副本。

存储为串接的标准 gzip 成员。每个成员包含一个完整提交批次,首成员另含 header;gzip 头使用 FEXTRA 和 FHCRC(FLG=6),XLEN=8,子字段标识 WQ、LEN=4、数据为该成员总字节数的 little-endian uint32,随后用 FHCRC 校验块头,避免损坏长度被误认为截断尾部。 标准 gzip 解压器忽略未知 extra 字段,因此可直接还原普通 JSONL。 读取器按成员长度定位、逐块解压并校验 CRC,再校验原 JSONL 提交链;正文批次仍限 64 MiB, 压缩层含 header/commit 的展开块限 65 MiB,避免单个块无限增长。压缩通过异步 zlib 执行。

writer 把完整成员写入后 fsync,更新时不重压既有成员。截断的最后成员不生效,续作在写锁内 截到最后已提交成员的物理偏移后追加;完整成员的 CRC、JSONL 摘要或提交链错误必须报错。 压缩头或长度损坏无法确认属于截断尾部时同样报错,不跳过猜测。媒体仍在已有资源目录中。

首次预览流扫验证并建立可重建的内存索引,只缓存记录偏移、最新版本及资源映射,不缓存整份 展开正文,不生成临时解压文件。缓存最多保留两份归档,以文件身份、大小及修改时间失效。 无筛选分页只读取命中成员;搜索与日期筛选按块遍历。索引不作为正式数据或增量基线。

同一 archiveId 固定主格式版本,basic/full 不构成两套格式。basic→full 重新读取来源后, 可在同一归档以原对象 id 追加带附加数据的版本及新观察,复用已校验媒体,保留原版本; 无法取得的旧字段标记未覆盖,不能给旧数据补空 native 就称完整全量。header.profile 保持首次选择,本次选项写 observation.profile,不因选项变化重写 JSONL header。 full 后继续 basic 不删除已有附加信息。显式 full→basic 是有损派生投影,重算 revision 并重连观察;默认保留对象与归档身份,不原位覆盖或删减原 full。另建独立归档时才另分配 archiveId,不仅因为 basic/full 不同而强制新建。 版本号使用 MAJOR.MINOR,无前导零;当前 writer 仍只写 1.0,不修改应用版本。

  • 已发布 schema 不原位修改;新工具继续读取已支持的旧版。每个发布版本随工具离线提供 对应 schema,小版本发布时使用独立版本标识,不覆盖原 1.0 的 $id 或文件。
  • 新增可选字段、缺席时完全沿用旧含义,走小版本。旧 reader 可读取未来同主版本,按 已知结构校验并保留未知属性;旧 writer 不凭空生成新字段、不降低归档版本。已有类型、 枚举、字段含义、身份/摘要算法与提交规则不能通过小版本改变。
  • 改名、改变类型、新增必填字段、新增不认识的记录/元素类型,或改变身份、引用、默认 读取及提交语义,走主版本并提供具体迁移。未知主版本明确提示不支持,不改写文件。
  • 读取、无损转换、追加和有损投影分别判断。读取未来同主版本不是按该未来版本做完整 schema 验收;writer 新建内容仍按已知 schema 严格校验,已有未知属性从原结构传递, 不从展示模型重建,不改变原 header。无法原样保留时拒绝更新,不悄悄丢字段。
  • full→basic 须有对应版本的投影规则。未知小版本先允许查看和无损转换,不猜测新增字段 属于 basic 还是 full,不执行有损投影。basic→full 仍重新读取来源,不伪造缺失数据。

JSONL header 的版本首次写入后固定,旧 header 下不得追加要求更新版本才能表达的新字段。 只有已知字段的补充内容可在原版本下继续追加;需要升版本时显式迁移为新归档,保留旧 对象/版本引用的映射和来源,完成校验后再选择新归档续作,不原位混写两套结构。

旧来源识别方式转换与缺失处理
WeQ enriched JSONmeta/members/messages映射会话和发送者;保留旧实际元素,缺失行属性不冒称 full
旧裸消息数组/JSONLmsgId/msgSeq/sendTime/elements未知账号、会话/原生 ID 按历史契约表达,不为满足必填项编造或强制补填
header/member/message JSONL实际 _type 或 ChatLab type 行及 meta保留实际行关系,校验后迁入新正式格式,不把新 stream 当旧消息行读取
隐藏 messages-*.jsonl + baseline.json旧 version/selection/journal 清单只读导入日志及可用媒体;旧 selection hash 不是业务消息身份,不复制为新隐藏日志
ChatLabchatlab/meta 与实际消息字段已拍平成文本的媒体/转发无法反推结构;parsing/acquisition 标记缺项,不称无损
generated-content/1原 schema 字符串按本地生成领域迁移,保留 sessionId=null 与工具过程
空间/收藏/邮箱旧包各自原索引/JSON保存已有内容及来源;缺原 HTML、未知字段或原件时明确列缺项

识别器优先新 format/version,再旧格式;不以文件扩展名判定。导入始终生成新归档, 完成校验后再允许显式选择它续作。不自动删除原件、隐藏日志、旧媒体或历史基线。

历史规范化聊天库的字段、旧 archive_message_id/archive_variant_id 引用、多账号集合、 资源及逐字段验收统一遵循历史兼容契约。新增导出与迁移相同语义必须 使用同一字段、身份和版本规则。本轮修订仍是尚未发布的 v1 设计稿,不是对已发布 version=1.0 数据的原位结构变更;正式冻结后变更须按本节版本规则处理。

业务接入顺序与验收 ​

本轮修订实现上述兼容契约的 schema/参考模型及反例;不把规范工具当生产 reader。业务 仍按以下顺序接入,不因尚未实现或不够高频而删减已要求的来源、字段或历史实体。

顺序实施内容必须证明
1新旧格式识别、版本分派和正式读取;保留现有旧 JSON/JSONL reader新格式先于旧格式识别;同主版本未知可选字段原样保留;未知主版本不误读
2查看器接入正式读取模型,再切换各领域导出器新导出能立即查看;旧文件仍可读;不将展示模型当 full 来源
3全部已要求历史来源的迁移适配按 historical.md 与 coverage.md 逐字段/字节/身份/资源对账,缺项如实登记,不缩减历史覆盖
4增量 writer 和定时任务接入新内容严格校验;旧未知字段不丢;header/版本不降级;观察顺序、原子提交及恢复成立

每项分别记录设计、源码接入与实际验收。真实 QQ/历史原件迁移、资源提取、业务查看器、 生产导出与掉盘/断电验收仍未完成;合成规范测试不能替代这些结果。

当前文档对应 v2.7.4 · 已发布内容以 CHANGELOG 为准