LobeHub deep-review：持久化状态与发布时刻风险的审计方法论

本文以 LobeHub 仓库中 deep-review 技能的 release-risk/persisted-state.md 参考文档为主体，完整拆解它如何审计迁移与 Schema、无 Schema 持久化数据、队列与工作流、定时任务、配置和出站副作用等"持久化状态"的发布风险，并结合仓库内真实的 159 个 Drizzle 迁移文件、db-migrations/drizzle/upstash-workflow 技能文档与验证规则，说明每条审计规则在 LobeHub 项目中的落地依据与实操用法。读完你可以掌握：如何判断一个迁移/数据结构变更是"无发现"还是 P0/P1/P2 问题，以及何时把问题转化为"部署前检查项"而不是代码缺陷。

一、这份参考文档在 deep-review 体系中的位置

persisted-state.md 是 deep-review 技能 下 release-risk（发布风险）维度的三个路由参考文档之一。该技能是一套"多维度、独立评审者 + 对抗式验证"的代码评审流程，其维度表将 release-risk 定义为"ship/no-ship gate"（可发布门禁）：

判定"看起来正确的代码上线后发现是错的"时的恢复成本；发现项必须点名具体的回滚、修复或影响半径后果——仅仅"被很多代码依赖"本身不是缺陷。 —— release-risk 维度文件

维度文件按改动面路由到对应参考文档，其中明确写道：当 diff 触及 Migration、Schema、持久化对象、队列/工作流、cron、配置或出站发送方时，必读 persisted-state.md。该参考文档的开头也给出了触发条件：

Read this reference when the diff touches migrations, schema, structured values stored without a schema migration, queues, workflows, cron jobs, configuration, or outbound side effects.

理解本文档还需要知道 release-risk 维度的两种输出形态（维度文件 "Two output shapes"一节）：

• issues 发现项：代码或 diff 能证明存在恢复风险时输出；
• release_checks 发布检查项：当安全部署取决于仓库无法回答的生产/外部状态（现有行的形状、线上配置值、当前队列内容）时输出。

报告渲染规则（见 report-template.md）进一步规定：release_checks 渲染在 Pre-deploy checklist 下，不计入任何发现项统计，也不得成为合并裁决的前置条件；其中 blocks_deploy: true 的条目优先渲染，并作为"部署时条件"而非"代码阻断项"出现在裁决依据中。一句话概括设计意图：能证明的写进 findings，证明不了的写成一条精确的部署前检查，绝不靠猜。

二、持久化状态审计规则（Persisted State）

这是本文档的第一节，也是 LobeHub 这类重 PostgreSQL 项目（packages/database 下维护了 159 个按序号编号的迁移 SQL，由 meta/_journal.json 的 journal 条目串联成序列）最需要严格执行的部分。

2.1 完整阅读每一条迁移：附加式变更默认不产出发现

原文档规则：

• 完整阅读每一条迁移和生成的 SQL 语句，而不是扫一眼文件名；
• 附加式、可逆的变更——可空列、新表、并发索引（concurrent index）——除非存在具体的执行顺序依赖或生产状态依赖，否则不产出任何发现项或发布检查项。

LobeHub 仓库中这类"无发现"变更随处可见。例如 0039_add_editor_data.sql 的全部内容只有一条语句：

ALTER TABLE "documents" ADD COLUMN IF NOT EXISTS "editor_data" jsonb;

附加可空 jsonb 列 + IF NOT EXISTS 幂等子句，属于典型附加式可逆变更。按本文档的判定标准，它既不是 finding 也不是 release check——这正是该规则要压制的"迁移一出现就报警"式噪声评审。

并发索引的"附加式"判断在 db-migrations 技能 中有一整套配套工程实践：大表上手动执行 CREATE INDEX CONCURRENTLY（避免阻塞生产流量），同时在 Drizzle 迁移里保留幂等的非 CONCURRENTLY 版本（CREATE INDEX IF NOT EXISTS ...），使部署时的迁移重放成为 no-op、新库/自托管库仍能收敛。该技能还强调 CONCURRENTLY 不能放在事务里。

2.2 破坏性 DDL、无重建路径的数据变更、会拒绝存量行的约束

原文档要求重点标记：

• 破坏性 DDL：DROP、收窄类型变更、枚举值移除；
• 没有重建路径的数据变更型迁移；
• 可能拒绝存量行的约束（例如对已有脏数据直接加 NOT NULL 或唯一约束）。

仓库中破坏性迁移同样真实存在，例如 0009_remove_unused_user_tables.sql 含 DROP TABLE 语句（文件名即"移除未使用的用户表"），0007_fix_embedding_table.sql、0010_add_accessed_at_and_clean_tables.sql 等也涉及删表/清理。对这类语句，本文档要求评审者回答"数据能否重建"，而不仅仅是"能不能跑通"。

与之相关的真实案例可参见 drizzle 技能 中记载的历史演进：ai_providers / ai_models 在 workspace 化改造时，其复合主键无法直接加可空的 scope 列，迁移 0110 用代理主键 _id + 部分唯一索引替换了复合主键。这类"主键拆除重建"就是本文档所说的约束/结构层面最敏感的变更——它既不是简单附加式，也涉及存量数据与 onConflictDoUpdate upsert 行为。

2.3 新增 ON DELETE CASCADE：检查被放大的删除半径

原文档规则：检查新增的 ON DELETE CASCADE 是否扩大了删除效应（"newly widened deletion effects"）。

在 LobeHub 中这是高频模式而非例外——初始迁移 0000_init.sql 中就有 31 处 ON DELETE cascade，drizzle 技能 的外键规范示例也直接使用 { onDelete: 'cascade' }。正因为"级联删除"是既有惯例，本文档才特别要求评审增量：新增的每条级联约束都要回答"删除父行时，新挂进来的子数据是否会被一并带走，这个扩大是否被预期"。

2.4 无 DDL 的结构化值 = 持久化契约（持久化状态的核心）

原文档将以下对象统一视为"没有 DDL 的持久化契约"（persisted contracts）：

• jsonb 列的键与值类型；
• Redis/缓存对象；
• 浏览器端 localStorage、IndexedDB 与持久化存储；
• 对象存储中的 manifest 或 JSON blob。

审计动作是：把写入方的新形状与所有读取方逐一比对；旧值会一直存在，直到被显式迁移或过期，因此读取方必须容忍旧形状（legacy shape）。

LobeHub 的 drizzle 技能 在类型层面强制了这条契约：

• 禁止 Record<string, unknown> 这类松散 JSONB 类型，必须定义描述 JSON 形状的具体接口，例如 metadata: jsonb('metadata').$type<UserSignupLogMetadata>()；
• 技能给出的 agents 表示例中，chatConfig: jsonb('chat_config').$type<LobeAgentChatConfig>() 就是"写入方形状"的显式声明；
• 同时，松散类型 JSONB 列常是"投机性预留"的症状——列只有在具体写入方随代码上线时才"挣得存在"，评审发现无写入方的 metadata/extra 列时，修复动作是删列而不是给不存在的数据发明接口。

也就是说：类型系统是"写入方新形状"的权威描述，而 persisted-state 参考文档要求评审者在此基础上再回答"所有读取方是否容忍旧形状"——类型对齐了写入，读取方的兼容才是发布风险的关键一问。

2.5 回滚不对称性与部署顺序

原文档最后一条规则：显式陈述回滚不对称性与部署顺序（"State rollback asymmetry and deploy ordering explicitly"）。判据：

如果"回滚代码、但保留新 Schema"会让上一版本代码无法运行，那么这次发布已经跨过了单向兼容边界（one-way compatibility boundary）。

这是整个 release-risk 维度"恢复成本"视角的浓缩：代码可以回滚，数据很难。评审者必须对每个候选发现写出具体可执行的恢复程序（维度文件 "How to check" 第 2 条），写不出恢复程序的"风险"不成立。

三、开发周期漂移（Dev-cycle Drift）：未发布的可以压，已发布的不能动

原文档第二节针对"同一个 PR 里迁移反复重写"产生的开发残留，给出五条规则：

1. 把本 PR 的迁移当作一个序列阅读。若同一 PR 先创建某个对象、之后又重命名、删除或重做它，应把未发布的中间态压缩（squash）进最终形态；
2. 拒绝只为迁就开发者本地数据库状态而存在的迁移语句——生产从未见过的状态不值得为它写兼容 SQL；
3. 用 diff 中用到的每张表、每个列去核对已提交的 Schema 与迁移——本地库可能残留生产永远不会创建的对象；
4. rebase 之后检查执行顺序：主干（trunk）迁移必须先跑且不与本分支冲突；
5. 仓库内无法定论的事项，转化为一条精确的发布检查项，例如"在干净数据库上重放迁移"或"统计会违反新约束的行数"。

并以一句强约束收尾：

不要建议压缩那些已在任何共享环境中运行过的迁移。它们是历史，不是开发残留。

这五条在 LobeHub 的 db-migrations 技能 中都有对应的工程化操作规程，两者互为表里：

persisted-state.md 的评审规则	db-migrations 技能的配套操作
压缩未发布的中间态	"Before release, if a feature branch accumulated multiple development-only migrations, consolidate them into one migration"：删除本分支所有草稿 SQL、快照、journal 条目后 bun run db:generate 重新生成单一迁移
拒绝本地专用兼容语句	"Do not make a migration compatible with earlier development-only versions of the same branch"：不添加兼容 ALTER ... RENAME，直接用 SQL 修开发库（技能给出了 bun -e + pg 的完整示例）
已运行的迁移不可压缩	"After a migration has reached production or the target default branch, treat it as immutable: add a follow-up migration instead of rewriting it"
rebase 后检查顺序	专门章节 "Rebase conflicts"：保留上游/默认分支迁移、删除本分支迁移、完成 rebase 后重新生成本分支迁移，避免合并两份独立快照或手工拼接 journal
无法定论转为发布检查	技能要求"在真实 Dev 库上验证 rollout 假设"（用临时探针索引、回滚事务中的触发器等可逆探针测量），并明确"单次 Dev 结果只证明观测到的规模，生产结论须标注为推断"

以该技能举的实例来说：若本分支早先草稿创建了 signup_attempt_id 列、之后又改名为 user_signup_log_id，正确做法是修好开发库后重新生成，而不是往迁移里塞兼容语句——这正是规则 1 与规则 2 的联合落地。

LobeHub 当前 159 个迁移构成的 journal 序列（0000_init 到 0132_add_agent_labels 等）就是"当作序列阅读"的具体对象；meta/_journal.json 中每条 entry 的 idx/tag/when/breakpoints 字段为核对顺序与主干冲突提供了机器可读的依据。

四、部署时刻状态（Deploy-moment State）：存量工作流、cron、配置与出站副作用

原文档第三节审视的是"发布动作发生的那一刻"线上已存在的状态，共四条规则。

4.1 队列消息与在途工作流是旧代码生产的

当 payload 字段或工作流步骤顺序发生变化时，消费方至少保持一个部署周期的向后兼容，或者记录一份 drain-and-deploy（排空-部署）流程。

LobeHub 的异步体系基于 Upstash Workflow + QStash，upstash-workflow 技能 描述的三大模式与此直接相关：

• Dry-Run Mode：先统计、不触发真实执行——这正是 drain 前评估积压规模的工具；
• Fan-Out Pattern：把大批量拆成小分片并行处理；
• Single Task Execution：每次工作流执行只处理恰好一个条目，且平台层面要求"重试不能造成双重处理"（幂等性）。

评审视角是：如果新代码改了消息 payload 或步骤顺序，队列里还压着旧代码投递的消息——消费方不向后兼容一个部署周期，或没有 drain 流程文档，就构成部署时刻风险。

4.2 cron 第一次触发即面对生产规模积压

定时任务第一次 tick 会直接处理生产规模的积压。检查幂等性、处理范围，以及调度变更是否会与旧调度重叠。

"重叠"是关键词：改 cron 周期或时间窗时，新旧调度可能同时触发同一批积压，没有幂等保护就会双跑。这与 4.1 的幂等要求一脉相承。

4.3 新配置：声明、默认/失败行为、全部部署目标

对新配置，验证三件事：声明（declaration）、默认/失败行为、每个部署目标。线上未知的取值转化为发布检查项；代码里缺失的声明则是发现项。

维度文件的 "Not violations" 清单给出了对称的另一面：为每个目标声明、且有合理默认值或响亮启动失败的新环境变量，不算违规——只有"声明缺失"才升级为 finding，而"线上现在配的是什么"仓库回答不了，属于 release_checks。

4.4 追踪不可逆的批量出站

追踪批量写入的不可逆扇出（fan-out）：邮件、推送、支付调用、第三方 webhook。回滚无法召回一个已经发出的出站效应。

这是"回滚不对称性"在数据层之外的延伸：数据库变更还有"数据可以重建"的讨论空间，出站效应则完全没有——P0 级"不可逆"在这里最容易出现。

五、验证纪律：从"存在迁移"到"证明危险"

原文档第四节的验证指导（Verification guidance）是防止误报的四条纪律：

1. 从实际 SQL 和读取方确认数据危险，而不是从"存在迁移"确认；
2. jsonb/缓存形状类发现，只有当"真实的旧值到达了一个无法处理它的读取方"时才成立；
3. 开发周期抖动（churn）只有当本 PR 既创建又重做了同一对象时存在；
4. 把迁移成本与锁（归 performance 维度）和可逆性/恢复成本（归本维度）分开——锁表多久是性能问题，回不去是发布风险问题。

配套机制在仓库中有两处硬性落地：

• verification/release-risk.md（验证附加规则）要求验证子代理：数据层必须读实际 SQL 和读取方，附加可逆变更"除非具体的顺序/回滚危险仍然存在，否则是误报"；且 release-risk 维度的所有发现项一律 can_auto_fix: false——风险类问题不允许自动修复，必须人工裁决。
• 报告模板规定 release_checks 渲染为 Pre-deploy checklist，与严重度分桶的 findings 物理隔离，不参与任何统计，也不成为合并前置条件。

结合 deep-review 技能的核心原则"反幻觉"（只看到 diff 片段的评审者会发明 bug，因此候选发现必须由读取完整上下文的独立验证子代理逐条证伪，返回 confirmed / false_positive / need_more_context 三态裁决），可以看出这套体系对"持久化状态"这类证据门槛极高的风险维度采取了最保守的输出策略：证明不了的进 checklist，证明了的才进 findings，且绝不 auto-fix。

六、严重度标尺与实操核对清单

原文档最后给出三级严重度定义，与维度文件的通用标尺对齐：

级别	定义（persisted-state.md 原文标准）	典型场景
P0	破坏性或不可安全撤销的不兼容变更；或针对已知存在的数据必然失败的迁移	对含脏数据的表加唯一约束；DROP 了仍有读取方的表；队列消费方拒绝旧 payload 且无 drain 方案
P1	存量记录或在途 payload 可能损坏，但通过显式迁移、兼容读取方或 drain 流程可以恢复	jsonb 形状变化但保留一个部署周期的向后兼容读取；跨版本部署顺序要求
P2	未发布的迁移抖动（churn）或缺少回滚说明，且没有已证明的运行时失败	同一 PR 内建表又删表的中间态未压缩；PR 未写部署顺序说明

把全文规则压缩成一份可执行的评审清单：

1. 读全 SQL：逐条读 diff 涉及的迁移与生成 SQL；附加可逆变更（可空列、新表、并发索引）无顺序/状态依赖时不产出任何输出；
2. 标破坏项：DROP、类型收窄、枚举值移除、无重建路径的数据变更、可能拒绝存量行的约束；新增 ON DELETE CASCADE 评估删除半径；
3. 审无 Schema 契约：jsonb 键值、缓存对象、localStorage/IndexedDB、对象存储 manifest——比对写入方新形状与每个读取方，旧值未迁移/未过期前读取方必须容忍；
4. 写部署顺序：回滚代码但保留新 Schema 是否可行？不可行即单向兼容边界，显式陈述；
5. 压开发残留：本 PR 未发布且自建自改的中间态压缩为最终形态；本地专用兼容语句拒绝；rebase 后核对主干顺序；已在共享环境跑过的迁移只增不改；
6. 查部署时刻：队列/工作流消费方向后兼容 ≥1 个部署周期或给出 drain 流程；cron 首 tick 的积压处理（幂等、范围、新旧调度重叠）；新配置的声明/默认/目标三查；出站批量扇出不可逆性；
7. 分流输出：仓库能证明的写成 finding（含恢复程序，不可 auto-fix），生产状态相关的写成精确 release check；
8. 定级：按上表落到 P0/P1/P2。

七、相关路径索引

• 主体文档：persisted-state.md
• 技能总纲与维度表：SKILL.md
• release-risk 维度规则：release-risk.md
• 验证附加规则：verification/release-risk.md
• 报告模板（release_checks 渲染规则）：report-template.md
• 迁移工程规范：db-migrations/SKILL.md、drizzle/SKILL.md
• 异步工作流模式：upstash-workflow/SKILL.md
• 迁移序列与 journal：packages/database/migrations、meta/_journal.json
• 附加式迁移示例：0039_add_editor_data.sql；破坏性迁移示例：0009_remove_unused_user_tables.sql

这套"持久化状态审计"规则的价值在于把发布评审从"代码能不能跑"提升到"错了能不能回"：迁移读全、契约比读、顺序写死、残留压净、生产状态留白成检查项——八步走完，一个触碰数据库与异步系统的 PR 是否可发布，便有了可复核的判定依据。