description: "在创建 PR 前，本地生成、确认并验证会话持久化类型变更。"

实操手册：审阅持久化类型变更

English | 中文

概述

在已安装依赖的贡献者检出目录中修改会话持久化类型声明后，使用本教程。提供双语兼容性说明，再用一条命令分类变更并生成记录。记录参考解释文件和自动规则。所有比较输入都在检出目录中；不需要基线分支或网络访问。

目录

• 可选：检查变更
• 1. 记录变更
• 2. 检查、提交并推送
• 更新尚未接受的记录
• 开发备注

可选：检查变更

若需在记录前预览，在仓库根目录运行：

pnpm --silent run verify-persistence-changes --json

消费 JSON 时使用 --silent：否则 pnpm 会把生命周期失败文本追加到标准输出。失败命令仍以退出码 1 结束。

阅读报告中的根、路径、变更种类和版本要求。被引用类型可能影响多个事件摘要；检查每个受影响的根。在历史覆盖新 schema 之前，验证会失败。陈旧生成清单也会导致验证失败；记录命令会刷新它。若重排字段或联合类型分支后 changes 为空，运行 pnpm run gen-persistence-catalog 并重新检查。即使复制的声明或源码位置产生目录 diff，未变的摘要也无需新增确认记录。

要独立于确认历史评审 PR，先将 base 和 head 的目录保存为本地 JSON 文件，再运行：

pnpm --silent run persistence-review --before .artifacts/base.schema.json --after docs/persistence-schema.json

在报告旁记录这些文件对应的 commit。添加 --json 可获取结构化输出。此只读比较将共享变更与受影响的根类型归组，使用实际字面量 kind/form 值代替联合类型位置。无法唯一匹配的候选项保留为独立的新增与删除。兼容性部分复制每个根类型的权威分类结果；结构说明不替代确认检查。当前目录标签和声明名称是描述元数据；结构锚点和指纹标识类型。

当前机器清单在 roots 中保存完整图。每个 types 条目包含 digest、names 和 sources；若根无法精确重建该图，条目还会保存显式 schema。读取器按摘要从根的子图恢复省略的图，并直接验证显式图，保留每个类型及其元数据。历史完整条目仍然可读。formatVersion 标识规范化规则；存储压缩不改变根指纹，也不需要确认记录。

1. 记录变更

先检查已接受基线，保留其锁定记录。向后兼容的演进使用新的同版本确认记录；记录破坏性变更之前，先实现更高的写入器版本。

编写包含 en 和 zh 的本地 JSON 文件，两者分别包含 summary、compatibility 和 verification 字符串。以下输入描述一个经过验证的钩子审计字段从必选改为可选的变更。用你所做变更的事实替换说明和测试证据；CLI（命令行界面）不会证明这些声明。

将输入保存为 .artifacts/persistence-change.prose.json，必要时创建该被忽略的目录：

{
  "en": {
    "summary": "Makes the persisted hook audit decision optional.",
    "compatibility": "Existing records remain valid. Hook execution consumes HookOutput instead of replaying this audit field. Producers still write decisions, and absence does not imply pass.",
    "verification": "pnpm exec vitest run packages/hooks/hook-protocol/tests/events.spec.ts: 10 tests passed."
  },
  "zh": {
    "summary": "将持久化的钩子审计决策改为可选。",
    "compatibility": "已有记录仍然有效。钩子执行消费 HookOutput，不回放此审计字段。写入方仍然记录决策，缺失不代表 pass。",
    "verification": "pnpm exec vitest run packages/hooks/hook-protocol/tests/events.spec.ts：10 个测试通过。"
  }
}

用日期和描述性短名替换示例 id：

pnpm --silent run persistence-changes --record 2026-09-11-poc-optional --prose .artifacts/persistence-change.prose.json --json

命令在写入前验证历史和双语说明、推断最低版本决策，并检查所需的头部版本递增。它生成记录对、完整的变更后 schema、两份目录、机器清单和配对记录。提交前审阅说明及返回的 changes、roots 和 files。省略 --prose 会创建未完成草稿，验证将拒绝它们，直到说明补齐。

推断遵循固定兼容性规则，不会更改源码或放宽规则。需要升版本时，先遵循添加会话格式版本。记录必须包含其自身的 SessionHeader.version 递增转换；无关的历史升版本不能授权它。日常变更不创建另一条基线。

2. 检查、提交并推送

根据测试政策选择变更所属模块的行为检查，再运行文档检查：

pnpm run doc-sync

doc-sync 检查持久化清单和目录新鲜度、完整历史及双语配对。记录命令的 ok: true 不能替代这些检查，也不能替代所属模块的行为与迁移测试。JSON 失败响应保留 ok: false、诊断 code 和退出码 1。结构化变更包含稳定种类和逐根的变更前后摘要，自动化无需解析描述文本。

记录生成负责其目录和记录的双语对；包 README 或其他双语页面的编辑仍遵循常规配对流程。审阅并暂存预期差异，然后正常提交和推送。暂存 lint、配对、空白 hooks，以及 pre-push Host/Client 类型检查仍须执行。

更新尚未接受的记录

记录后源码再次变化时，审阅兼容性说明，并刷新同一条尚未接受的末端记录：

pnpm --silent run persistence-changes --update 2026-09-11-poc-optional --prose .artifacts/persistence-change.prose.json --json

命令刷新机器声明、schema、目录和配对。没有 --prose 时，它保留已有说明。更新会拒绝初始基线、其他记录所依赖的记录，以及已被定稿检查点锁定的记录。定稿检查点之外，目录不会推断审阅接受状态：保留已接受历史，并创建后继。

集成产生竞争末端记录时，根据剩余历史更新尚未接受的记录，再重新评估最终差异。无关根的确认无需刷新。机制决策解释为何保留完整快照和逐根前驱。

显式 --decision 仍是受检查的断言。若已有属性的值类型发生变化，下面这个故意错误的断言会在写入前失败：

pnpm --silent run persistence-changes --update 2026-09-11-poc-optional --decision same-version --json

开发备注