LobeHub Deep Review 发布风险维度解析：Rollout 表面、共享代码爆炸半径与 PR 纯度判定规则

LobeHub 仓库内置的 deep-review 智能评审技能把一次代码变更的发布风险拆成多个可执行的检查维度，本文聚焦其中的 rollout 表面（Rollout Surface）参考规则：如何判定该不该为变更加功能开关（Feature Flag）、如何度量共享组件与包 API 的调用方爆炸半径、如何识别"用户第一分钟"UI 的行为变化，以及如何评估一个 PR 的拆分纯度。读完本文，你可以理解这套规则在评审流水线中的触发位置与验证闭环，并把"该不该加 Flag、该不该拆 PR"从经验判断变成可复现的工程决策。

规则定位：release-risk 维度的三路分流

该文档位于 .agents/skills/deep-review/references/release-risk/rollout-surface.md，是 release-risk 维度定义 中"按变更表面路由"机制下三份子参考之一。维度文件中的路由表规定了：

变更表面	必读参考
迁移、Schema、持久化对象、队列/工作流、Cron、配置、外发通道	persisted-state.md
Prompt、工具/参数描述、上下文组装、持久化 Prompt 默认值	prompt-surface.md
共享 API/组件、第一分钟 UI、功能开关、混合 PR 范围	rollout-surface.md

也就是说，只有当 diff 触及用户可见的主路径、共享组件或包 API、用户第一分钟的交互界面、或包含多个独立需求时，评审代理才会加载本文档所述的规则。维度定义文件的 frontmatter 还给出了 skip_when 条件：diff 不触碰 DB schema、schemaless 持久化载荷、队列/工作流载荷或 cron 调度、配置或环境变量依赖、外发通道、Prompt/工具描述文本、共享组件或包公共 API、高频用户表面，且只有一个明显目的时，整个 release-risk 维度都会被裁剪（prune），本文档规则也随之不会运行。这个设计对应 SKILL.md 的核心原则"Speed is a feature"——一轮并行评审、无关维度前置裁剪，避免为不相关的 PR 付费。

release-risk 是 14 个评审维度中唯一标记 verified + checks 的维度：发现（finding）要经过独立验证子代理的对抗式复核，同时它还能产出第二种输出形态 release_checks——仓库内代码无法回答、只能靠生产状态确认的部署前检查项。这两种输出最终分别渲染进 report-template.md 定义的严重度分桶（P0/P1/P2）与"Pre-deploy checklist"章节。

Rollback granularity：功能开关的四条件判定

原文档第一节的完整规则是：

只有当以下四条全部成立时，才建议加 Feature Flag：

1. 变更改动了用户可见的主路径（user-visible main path）；
2. 坏结果是"静默的错误"（silent wrongness）而非显眼的崩溃——崩溃自己会暴露自己，静默错误不会；
3. 生产数据、流量或第三方依赖使得上线前的完整验证不可能；
4. 整体回滚整个 PR 的代价不成比例地高。

四条是"与"关系，缺一不可。此外，分群灰度（staged cohort rollout） 本身也是加 Flag 的正当理由，但规则要求必须同时写清楚"允许移除 Flag 和旧路径的观测条件"——即 Flag 要有退场标准，不能成为永久性脚手架。

明确不建议加 Flag 的五种场景：

• 纯粹的 bug 修复；
• 脚本、开发工具、agent skill 等仅内部使用的变更；
• Schema 变更本身；
• 该表面已经被一个等效开关覆盖（避免 Flag 叠加）；
• 铺设 Flag 管道的成本高于直接回滚的成本。

这套判定背后是对"回滚颗粒度"的权衡：Flag 的价值在于让回滚从"撤整个 PR"细化为"关一个开关"，但 Flag 管道本身（声明、读取、两端分支维护、清理）是持续成本。维度定义文件把这条规则概括为"回滚颗粒度"检查项：一个用户可见、无法完整预验证的主路径变更，只能靠回滚大 PR 来撤销，而一个作用域受限的运行时开关本可以提供灰度与快速禁用。严重度定义上，需要 Flag 或协调部署才能恢复的破坏属于 P1；只有建议性的 rollout 改进才是 P2。

值得对照的是"不构成违规"清单中有一条"小型、可验证、回滚廉价的变更不需要功能开关"（dimensions/release-risk.md）——与上面"不推荐场景"里的"Flag 管道成本高于回滚成本"是同一枚硬币的两面。

Shared surfaces：共享代码爆炸半径的度量方法

原文档第二节定义了"共享表面"的范围：共享组件目录下的文件、导出的包 API、hooks、工具函数、上下文（context）。对这类表面，规则给出五条操作要求：

1. 统计调用点数量，并把数量写进 finding——爆炸半径必须是一个可度量的数字，不是形容词；
2. 检查变更是否影响：默认值、回退（fallback）行为、事件时机、必需/收窄的 props——这四类是共享契约最容易被打穿的地方；
3. 调用点统计必须包含平台变体和包消费方（本仓库是 monorepo，apps/desktop、apps/cli、src/ 下的 Web 端都可能消费同一份 packages/* 代码），不能只数当前应用；
4. 新增的渲染/副作用/订阅成本要乘以调用点数量评估——一个 hook 里多一次 useEffect 或一次订阅，在 1 个调用点是无感的，在 40 个调用点就是首屏渲染税；
5. 若发现"调用方专属分支被推进了通用共享抽象"，只报告恢复成本与爆炸半径这一侧；抽象归属问题划归 reuse-architecture 维度（见 dimensions/reuse-architecture.md），本维度不越权——维度文件专门强调"Keep dimension ownership sharp"，锁表与成本归 performance，设计质量归 ux，PR 元数据归 workflow。

节末一句是硬约束："没有可度量的爆炸半径、或既有契约没有变化，就没有 release-risk finding。" 这一约束在验证阶段被再次执行：verification/release-risk.md 规定验证子代理必须"reproduce the call-site count"（复现调用点计数），复现不了就判 false positive。也就是说，一条共享表面 finding 从提出到确认要两次证明同一个数字，这是该规则防止"改了一个 hook 吓唬所有人"这类噪声的设计。

First-minute UI：用户第一分钟表面的变更判定

"First-minute 表面"指用户登录后立刻到达的界面，原文档列举为：认证后的入口屏、主工作/聊天界面、导航、侧边栏、命令面板、输入框（composer）——在 LobeHub 这类以 Agent 对话为主界面的产品中，这些正是绝大多数会话的必经之路。

四条判定规则：

• 只报告"既成行为的变化"：控件被移动/删除、默认值被改动、新增确认步骤、键盘/提交语义变化。判定词是 changed established behavior——新增一个从未存在的入口不算；
• 必须写清楚部署后第一次加载时既有用户会体验到什么，以及缺陷到达用户群的传播速度——这就是维度定义中"reach and recovery"的落点：这个表面不是渲染频率，而是"部署完成到用户感知"的时延；
• 纯新增元素、内部重构、样式修复不构成 release-risk finding；
• 设计质量判断归 ux 维度，本维度只判"到达范围"与"恢复方式"。

验证附录对这一条的复核标准同样收紧：确认该表面确实在 first-minute 路径上、且确认改变的是既成行为，"纯增量工作和设计偏好是 false positive"。

PR purity：按子需求聚类，而不是按目录聚类

原文档第四节的完整规则：

1. 按独立子需求聚类变更文件，而不是按目录聚类——目录聚类会把一个需求的完整链路（组件 + store + service + TRPC）误判成"跨模块乱改"；
2. 只有当一个簇可以独立构建/部署，且体量大到值得独立评审和独立回滚时，才建议拆分；
3. 夹带的混合风险改动——顺手重构、格式化、依赖版本提升、无关文案修改——会抬高回滚成本，本身可以成为 finding；
4. 不要仅因体量报问题：一个合理地横跨很多文件的需求是"一个连贯的作用域"；
5. 不要提出会造成中间状态损坏的拆分。

最后一条硬约束：纯度类 finding 严重度封顶 P1，通常不阻断发布，除非被捆绑的那部分独立制造了 P0 风险。这与维度文件的 P 级定义一致：P0 是"灾难性且实际不可逆的数据丢失、财务损失、鉴权/安全失败，或没有恢复窗口的不兼容部署"，P1 是"真实但可恢复的破坏"，P2 是"建议性 rollout、回滚备注、迁移churn 或小纯度改进"。

验证附录对 PR purity 的复核要求是：证明被提议的拆分确实能独立构建和部署，存在共享依赖或中间状态损坏则 finding 无效。这条"证明义务"把"建议拆 PR"从主观偏好变成可检验的工程断言。

规则闭环：验证、输出契约与操作化配套

这三节规则并不是孤立文本，它们嵌在一个有输出契约的流水线里，值得从源码侧看三处证据。

验证环节：references/verification/release-risk.md 对共享表面、first-minute UI、PR purity 分别规定了复核动作（复现调用点计数、确认既成行为变化、证明拆分可独立部署），并且整个维度所有 finding 一律 can_auto_fix: false——发布风险是 ship/no-ship 判断，不做自动修复。scripts/validate-output.ts 中的 zod 模式把这一点固化成了机器校验：确认态 verification 若 can_auto_fix 为 false 必须给出 auto_fix_reason；每条 issue 强制携带 severity: p0|p1|p2、likelihood: high|medium|low、fix_options、fix_cost 等字段，低 likelihood 的 finding 必须附 scenario 前置条件链。release_checks 则是独立的数组（blocks_deploy + item + why），在报告模板中渲染为 Pre-deploy checklist，不计入 finding 统计、绝不变成合并前置条件。

严重度口径：rollout-surface 文档自己没有 P 级定义，但被它引用的维度文件给出了统一标尺，且 PR purity 的 P1 封顶是特例化条款。likelihood 的定义值得留意："likelihood 是危险发生的概率，不是代码执行的频率"；仓库内无法确定的生产状态应转为 release check 而非猜测 likelihood——这正是"静默错误才配加 Flag"那条四条件判定在输出层的呼应。

操作化配套：pr skill 的 Stacked PRs。"建议拆分"这条 finding 要落地，靠的是 pr 技能 中现成的跨层拆分流程：一个横跨 packages/database → 共享包 → src/server TRPC → apps/desktop/apps/cli 调用方 → src/features UI 的分支，按"被调用的层先合入主干"的顺序拆成有序 PR，上层 PR 以 --base 指向下层分支保证物理上无法先合。该流程的核心判定问题与 rollout-surface 的"可独立构建/部署"完全同构："如果这个 PR 此刻单独合入 canary，它能构建并且行为正确吗？" 不能，就属于后面的 PR。pr 技能还给出安全操作序列（先打 backup/x-full 备份分支、--force-with-lease 重写、服务端契约与其仓库内消费方必须同 PR 发出），以及"不要过度拆分"的告诫——两个 PR（契约/调用方）通常就够。可以说，rollout-surface 文档的 PR purity 节回答"什么情况下值得拆"，pr 技能回答"拆的具体 git 操作怎么做"，两者在 release-risk 维度文件的 rule sources 表里被显式挂接（.agents/skills/pr/SKILL.md 列为"独立可发布 PR 拆分"的规则源）。

小结：把"回滚成本"变成可判定的三条测量

这套 rollout 规则的方法论可以压缩成三条可复用的测量：

• 开关判定是四条件合取：用户可见主路径 × 静默错误 × 无法完整预验证 × 整体回滚代价过高，再加"必须写出 Flag 退场观测条件"；五类反例（bug 修复、内部工具、schema 本身、已有等效开关、Flag 比回滚贵）直接否决；
• 爆炸半径必须是数字：共享表面的 finding 以调用点计数为证据，成本按调用点数放大，且要覆盖全部平台变体与包消费方；没有数字就没有 finding；
• 纯度是子需求粒度的构建性证明：按子需求而非目录聚类，拆分建议必须独立可构建且不能产生坏中间态，严重度封顶 P1。

三者共同服务于 release-risk 维度的总目标——"评估当看似正确的代码部署后发现是错的，恢复要花多少代价"——并通过独立验证、zod 输出契约与 P0/P1/P2 报告分桶保证这些判断是可复核、可追溯、不可被主观情绪降级的。对于在 LobeHub 这类多端 monorepo 上运行 AI 评审的团队，这套文档的价值不在于"更聪明地审代码"，而在于把发布风险评审的口径固化成了一组可被代理逐条执行、逐条验证的规则文件。