LobeHub Deep Review 实战：基于设计价值观的 UX 评审维度全解析

本篇以 LobeHub 仓库中多维代码评审技能（deep-review）的 UX 维度规则文件为主体，完整解析其"以产品设计价值观而非通用审美"为核心的用户体验评审方法：你将掌握 ux 维度的 9 项快速清单、三步检查流程、"违规/非违规"边界，以及它如何与 review → verify 的多代理流水线协同，把"这个界面改动体验是否过关"变成一个可执行、可验证、可复现的评审过程。

1. UX 维度在 deep-review 体系中的位置

LobeHub 仓库内置了一套名为 deep-review 的多维代码评审技能，规则入口是 SKILL.md，每个评审维度对应 references/dimensions/ 目录下的一份规则文件。UX 维度的规则文件即 ux.md，它的 frontmatter 声明了三个关键字段：

---
id_prefix: ux
verify: true
skip_when: no user-facing surface changed (components, styles, copy, interaction flows)
---

这三个字段决定了 ux 维度在整个流水线中的行为：

• id_prefix: ux：该维度产出的 finding 统一使用 ux- 前缀编号（如 ux-1、ux-2），便于在结构化 JSON 输出和最终报告中定位归属；
• verify: true：ux 维度的发现属于"候选问题"，必须经过独立的 verify 子代理逐条证伪后才进入报告（详见 第 6 节）。在 SKILL.md 的维度表中，ux 一行标注 Verified? yes，覆盖范围为 "empty/loading/error states, async feedback, confirmation flows, design-value adherence"；
• skip_when：与 SKILL.md 中剪枝表（Pruning table）保持一致——当 diff 未触及任何用户可见面（组件、样式、文案、交互流程）时，ux 维度在派发子代理之前就被剪掉，不浪费评审预算。剪枝表还特别说明了一个容易踩坑的边界："docs-only" 仅指人类阅读的散文；.agents/skills/**、AGENTS.md、提示词模板这类"给 Agent 的可执行指令"在剪枝时算作代码，因此修改评审规则文件本身的 diff 永远不会被当作纯文档跳过。

deep-review 支持两种模式，ux 维度在两种模式下的读取深度不同（这一点在 SKILL.md 的 Dimensions 一节明确定义）：

模式	ux 维度读取范围
Light（默认）	只读 Quick checklist 一节（含嵌套示例小节），由一个独立评审者覆盖所有幸存维度
Deep（显式触发）	读完整维度文件（Quick checklist + Rule sources + How to check + Violations + Not violations），再按需读规则源文件

此外，deep-review 支持扩展包机制：包装仓库可以放置形如 deep-review-* 的兄弟技能目录来扩展规则集。若扩展包中的 dimensions/ux.md 与内置维度同名，则是"扩展"而非"替换"——两份文件都会被加载。这意味 ux 评审规则可以按部署方定制而不必 fork 本技能。

2. 评审标尺：四个设计价值观

ux.md 的第一句话就定义了本维度与其他"通用 UX 走查"的根本区别：

Design-level review of user-facing flows, judged against this product's design values — Natural / Meaningful / Certainty / Growth（自然 / 意义感 / 确定性 / 成长）— not generic taste.

评审不是按"通用审美"打分，而是对照本产品自己的设计价值观。完整定义位于 design-values.md（该文件自述适配自 Ant Design 的设计价值观体系，LobeHub 全部采纳），四个价值观各自的含义是：

价值观	核心要求
自然（Natural）	最小化认知负荷：下一步不言自明，产品用合理默认值、AI 辅助决策、平滑过渡主动推着用户往前走，而不是让用户停下来自己琢磨
意义感（Meaningful）	每个界面都锚定用户的真实目标而非孤立功能：目标清晰、每次操作立即反馈、始终指向下一个有意义的步骤；难度校准得当，既不高高在上地过度简化，也不用信息墙压垮用户
确定性（Certainty）	低熵、可预测的交互：复用同一套模式、组件与措辞，让行为永不意外；每个界面聚焦单一重点，且每一个状态（空 / 加载中 / 错误 / 成功）都被设计过，不留未定义；克制优于炫技
成长（Growth）	产品随用户成长：高级能力渐进披露，在功能变得相关的那一刻可被发现，而不挤占新手路径；目标是"人机共生"——用户与 Agent 相互成就、共同进化

当价值观冲突时的优先级（摘自 design-values.md）：

• 逐次交互决策：意义感 ≳ 自然 > 确定性——绝不为了保持一致而牺牲用户目标或前进动量；
• 成长性是更长的时间尺度视角：用于判断功能如何被发现、如何随用户扩展，而不是用来裁决单屏布局取舍。

ux.md 在 "Rule sources" 一节还规定了深度模式下评审者动手前必读的两个规则源，二者分工明确（这一分工同样在 ux 技能 的 "What lives where" 一节中强调）：

• DESIGN.md（仓库根目录）——设计系统：产品长什么样、读起来什么语气。可主题化的 token（颜色、排版、投影、圆角）、组件清单、Voice & Content（措辞与语气）。需要 token 值、组件或文案语气时查它。从源码结构看，DESIGN.md 的 frontmatter 以 YAML 完整列出了 Light 主题的语义 token（如 colorText、colorBgContainer、colorError），并注明组件必须按 token 名消费、Dark 主题使用同名不同值（见 DESIGN.dark.md）；
• .agents/skills/ux/SKILL.md——交互行为：流程随时间应如何表现。空 / 加载 / 错误状态、大列表、选择可见性、数字格式化、草稿安全、按钮层级、实体生命周期、渐进披露等执行清单，按交互类型拆分为 Read、Edit、Act、Feedback、Grow 五个模块，每条清单项都标注其服务的价值观。

经验法则一句话概括：静态外观与措辞查 DESIGN.md；动态行为查 ux 技能。ux.md 维度文件把这两份规则源作为"评审标尺"，确保每个 finding 都能落到具体规则上，而不是停留在"我觉得这里体验不好"。

3. 快速清单：9 项用户面自检

ux.md 的 Quick checklist 是 Light 模式下唯一被读取的部分，也是任何人工 UX 走查可以直接照用的一页纸清单。以下为完整 9 项（逐条对应原文）：

1. 空状态（Empty state）：首次运行与零数据视图必须被设计过，不能是一块空白区域。空状态应是"一个真正的页面"——在 ux 技能的 Read 模块 中该条进一步细化：常驻骨架（工具栏 / 页头）之下仍要有主体空状态；若 Empty 组件自带 search/无匹配变体，必须接线，不要把裸 <Empty/> 用在"搜索零结果"场景（那会把首次引导页误显示为搜索结果）。
2. 加载状态（Loading state）：异步界面必须展示骨架屏 / 加载器 / 乐观反馈——不允许"死帧"（dead frame）。ux 技能的 Feedback 模块给出了项目级具体约束：禁用 antd 的 Spin，使用 NeuralNetworkLoading 等项目加载器；且"每个加载态都必须能失败"——出错或超时时要呈现带 Reload/Retry 的失败态，永不允许无限转圈。
3. 错误状态（Error state）：失败要告诉用户发生了什么以及接下来做什么；不允许静默吞错，也不允许直接暴露原始错误码。ux 技能补充了一条容易被漏掉的顺序规则：error 分支必须先于 empty 分支判断——读取 error 而不是把 data ?? [] 强转成空态；一个失败的请求绝不能渲染成"空"（列表页读 error 再落空态；详情页读 error 再落 NotFound，"加载失败 ≠ 被删除/404"）。
4. 异步反馈（Async feedback）：变更类操作（mutation）必须确认成功或失败（toast、内联状态）；长操作要显示进度。ux 技能的 Act 模块进一步要求：异步/批量/不可逆操作遵循 确认 → 进行中（锁定）→ 完成/错误 三段式；乐观创建/重命名/复制要"让失败可见"（调用方捕获并 toast），绝不静默回滚。
5. 破坏性/不可逆操作：必须由明确说出后果的确认流程把关。ux 技能细化为：不可恢复或影响面大的动作（清空全部、删除账号、wipe）需要显式手势（输入确认 / 勾选），而非一键危险操作；且要报告部分失败，不允许静默"完成一半"。
6. 按钮层级（Button hierarchy）：每个界面只有一个主操作；破坏性动作不得采用主按钮样式。ux 技能要求验证方式是"在渲染出的界面上看视觉权重"，而不是从代码 variant 属性推断——返回/取消/次级按钮的视觉权重永远不能压过主操作。
7. 大列表（Lists at scale）：必须考虑 1000 条数据时的行为（虚拟化、分页、搜索）。ux 技能把这条展开为"1 → 10k 行"的设计要求，并指出服务端搜索要覆盖完整集合而非已加载页——排序、分面筛选、计数徽标、"对筛选结果批量操作"同样要落到全量数据上，否则会产生假的"无结果"与跨页错序。
8. 文案（Copy）：面向用户的文本必须清晰、已国际化（i18n）、且与现有术语体系一致。这一条对应 DESIGN.md 的 Voice & Content 职责：确认 / 完成 / 空 / 错误状态的措辞有既定规范，新文案偏离时需给出理由。
9. 交互细节（Interaction details）：焦点管理、键盘路径（Enter/Escape）、"带理由的禁用"优于"静默无效"。ux 技能的 Grow 模块还收录了一个典型反例：借用键盘/CLI 惯用法的外观（数字 chip、⌘K 徽章、键帽提示）必须真的接好对应按键——只有键帽样式的 chip 而无 handler 是"虚假可供性"（false affordance）。

这 9 项清单的写法值得注意：每一项都是可判定的命题（"是/否"可检查），而非抽象原则。这正是 SKILL.md 核心原则 "Rules over model"（质量来自细粒度可执行的维度规则，而非更聪明的模型）的具体体现——子代理跑在平衡/快速档位上，靠的就是规则本身足够精确。

4. 三步检查流程：How to check

ux.md 的 How to check 一节给出深度模式下评审者的标准作业程序，共三步，每一步都针对一类典型的 UX 评审失误：

1. 枚举状态：识别 diff 引入或改动的每一个用户可见状态，并对每个状态逐一枚举 empty / loading / error / success。这对抗的是"只看了 happy path 就签字"的评审习惯——"确定性"价值观要求每个状态都被设计过，所以遗漏一个分支（如只处理了成功、没处理失败）本身就是发现。
2. 以新用户走查：以首次使用者的身份走一遍完整流程——数据到达之前看到什么？失败时看到什么？成功之后看到什么？这对抗的是"知道功能应该怎么用"的评审者偏差：第一次接触这个界面的人没有这份先验知识。
3. 与最近似的现有功能对比：把新流程的文案与交互模式和应用中最接近的既有功能对照，偏离必须有理由。这一步把"一致性"从口号变成可执行的检查：ux 技能中的交互原则 "Consistency is semantic, not mechanical" 对此作了精确限定——一致性指"同一用户意图在同一界面表现一致"，而非"同一组件到处必须一样"；复用组件跨界面时，交互策略应由父界面提供，让行为跟随意图而非实现便利。

值得强调的是，第三步与 ux.md 的 "Violations" 第 2 条形成闭环：违反既定交互模式的流程，评审时必须引用那个兄弟功能（cite the sibling feature）作为证据——"隔壁列表页的加载态是骨架屏，你这个新页面却是白屏"。

5. 违规与非违规边界：校准原则

UX 类维度最容易产生的问题不是漏报，而是误报——把口味分歧当缺陷。ux.md 用 Violations 与 Not violations 两节划出硬边界，配合 SKILL.md 的 "Calibrate to codebase and lifespan" 核心原则使用。

构成违规（Violations）

只有两类情况算违规：

1. 存在可达的用户状态却没有任何设计过的呈现——空白（blank）、卡死（stuck）、原因不明的失败（unexplained failure）。
2. 流程与某个设计价值观或应用内既定交互模式相矛盾——且必须引用那个兄弟功能作为证据。

不构成违规（Not violations）

三条"免罪"条款，逐条都对应一类常见误报：

1. 在设计系统内一致使用的外观选择：口味分歧不是发现（taste disagreements are not findings）。只要落在既定设计系统（DESIGN.md 的 token 体系）内且一致使用，圆角偏好、间距微调这类"我觉得那样更好看"不构成 finding。
2. 打磨缺位但达到代码库现有水平：ux 技能称之为 calibration principle——如果该流程的体验水位与代码库当前的整体水位持平，"这里少了点 delight/polish"最多记为 P2 级建议（advisory），不能升级成必须修复的问题。
3. 真实交互不可达的状态：在报告一个"缺失状态"之前，必须先验证其可达性（verify reachability before reporting）——一个用户实际到不了的状态缺了设计，不算缺陷。

这三条与 verify 子代理的裁决规则（见 verify-prompt.md）严格对齐：verify 流程要求先寻找反例（上游保证、提前返回、框架行为、既有校验），并把"广泛存在且本 diff 未使其变差"的发现直接判为 false_positive，理由以 over-scrutiny: 开头。从源码结构看，ux 维度没有声明 calibration_exempt: true（该豁免仅安全维度使用），因此它完整接受校准裁决——这正是"非违规"条款在流水线层面的执行机制。

6. 与 deep-review 流水线的协同：从候选发现到确认结论

理解了维度文件本身后，再看它如何嵌入 deep-review 的完整流水线。以 deep 模式为例，ux 维度经历四个阶段：

阶段一：剪枝判定。 主代理按 SKILL.md 剪枝表检查：diff 是否触及组件、样式、文案或交互流程？是则 ux 维度幸存，列入派发清单；否则剪掉并在报告头部注明"pruned: ux — no user-facing surface changed"。

阶段二：独立评审。 每个幸存维度由一个独立子代理评审（"Anti self-approval" 原则：刚写完代码的代理不能当自己的考官）。子代理接收由 review-prompt.md 实例化的自包含提示词，ux 维度下它需要：完整读取 ux.md，按路由读取 DESIGN.md 与 ux SKILL.md 的相关章节，然后以"独立第三方"姿态审查 diff。评审范围有硬规则：finding 位置默认必须落在 diff 的 + 行上；顺手撞见的无关旧问题一律不报（除非是显而易见的 P0 生产 bug，且要标记 exposure: "bystander"）。

阶段三：结构化输出。 每个候选发现必须是严格 JSON，必填字段包括 id（如 ux-1）、dimension、issue_type、nature（introduced / exposed_legacy）、severity（p0/p1/p2）、likelihood（high/medium/low）、location（file:line）、summary、core_problem、fix_cost、至少一条 fix_options 和 need_test。这份契约不是纸面约定——validate-output.ts 用 Zod schema 对其做运行时校验，并有配套测试 validate-output.test.ts。从源码结构看，schema 还带条件约束：exposed_legacy 的发现必须携带 exposure 与 scenario；likelihood: low 的发现必须写出前置条件链（scenario）——写不出具体触发链，说明评审者是在猜测触发条件，应当降级或如实说明。

阶段四：对抗性验证。 因为 verify: true，ux 的候选发现交给另一个独立子代理逐条证伪（"Anti-hallucination" 原则：只看 diff 片段的评审者会编造 bug）。verify 子代理读完整上下文，先找反例，再对每条发现给出三路裁决之一：confirmed / false_positive / need_more_context——设计文档明确说明"三路裁决优于置信度百分比：听起来校准过的分数不可靠"。ux 发现最常见的 false_positive 理由正是 over-scrutiny:（模式广泛存在且未被本 diff 恶化），这与 第 5 节 的校准原则首尾呼应。只有 confirmed 的发现进入最终报告（报告结构契约见 report-template.md），按 P0 → P1 → P2 分桶渲染，每条带 blocks release、likelihood、证据与修复选项。

7. 实战演练：评审一个真实的用户面 diff

把上述规则落到一次典型评审上。假设某 PR 给 LobeHub 新增了一个"连接器管理"设置页：新路由、一个加载中的列表、一个"创建连接器"按钮和一个删除操作。按 ux 维度完整走一遍：

第一步（剪枝）：diff 触及组件（新页面）、样式（新布局）与交互流程（创建/删除）——ux 维度幸存。

第二步（枚举状态）：对该页面枚举 four states——

• Empty：零连接器时是否有一个"真正的页面"（引导文案 + 主 CTA），而不是空白区域？若 Empty 组件带 search 变体而本页支持搜索，零结果时会不会误显示首次引导页？
• Loading：列表加载是骨架屏（结构锚点对齐最终布局：页头高度、首个分组标题位置）还是死帧？加载态是否有失败出口——失败后是带 Retry 的错误态，还是无限加载？
• Error：删除失败时用户看到什么？是静默吞掉、裸错误码，还是"发生了什么 + 下一步"的提示？error 分支是否先于 empty 分支判断，保证失败请求不会渲染成"空列表"？
• Success：创建成功后是否提供主操作"去查看结果"（forward momentum），还是只弹一个会消失的 toast？

第三步（新用户走查 + 兄弟功能对比）：以首次使用者视角走通创建流程；把该页的列表行、按钮层级、确认弹窗与设置区最接近的既有页面（例如同类"管理列表"界面）逐一对照。若兄弟页面列表行用规范组件组合而成而新页面手写了裸 <div> + 定制 CSS，导致 hover/active 高亮与内容框错位——ux 技能的 Read 清单明确将此类"手搓平行实现"列为发现（聚合起来读作"未打磨"，即使每一处差距都微小）。

第四步（边界裁决）：确认删除是否"说出后果"（列出将影响哪些内容）而非泛泛的"确定吗？"；删除按钮是否被错设为主按钮样式；禁用态的"创建"按钮（未登录等场景）是否给了禁用理由。同时校准：若该页体验水位与代码库现有同类页面持平，"缺个 loading 动画的 delight"记 P2 建议而非阻断项；若"零结果"状态实际不可达（页面根本没有搜索框），先验证可达性再决定是否报告。

第五步（输出）：每条候选发现以 ux-N 编号进入结构化 JSON，severity 只表达"发生时有多严重"、likelihood 独立回答"实际触发频率"——一个数据损坏级但极难触达的问题可以是 p0 + low。随后 verify 子代理逐条证伪，确认项进入报告：P1 级"删除失败静默回滚"（证据指向具体 file:line）会成为合并前置条件；P2 级打磨建议列入 follow-ups。

8. 小结

ux.md 这份维度文件的价值在于把"用户体验评审"从一个模糊的品味问题改造为一套可执行规则：

• 标尺明确：对照 Natural / Meaningful / Certainty / Growth 四个设计价值观（design-values.md）与两份规则源（DESIGN.md、ux SKILL.md）评审，而非通用审美；
• 清单可判定：9 项快速清单覆盖空/加载/错误/反馈/破坏性操作/按钮层级/大列表/文案/交互细节，每项都是可检查的命题；
• 流程可复现：枚举状态 → 新用户走查 → 兄弟功能对比的三步法，配合"必须引用兄弟功能"的证据要求；
• 边界防误报：两类违规 + 三类非违规的校准原则，与 verify 阶段的 over-scrutiny 裁决闭环，确保口味分歧不冒充缺陷。

对于维护该技能的开发者，SKILL.md 末尾的 "Keeping this skill sharp" 还规定了反馈回路：当一次评审暴露规则缺口或过时规则时，应在同一 PR 或后续 PR 中直接更新维度文件——ux 评审规则的"校准"本身就遵循它所倡导的成长性。