LobeHub ux-audit 技能系列（一）：Layer 1 静态代码审计（L1）——不跑界面、只看代码的 UX 基线检查法

LobeHub ux-audit 技能系列一Layer 1 静态代码审计L1——不跑界面、只看代码的 UX 基线检查法【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub导读本文详解 LobeHub 仓库内.agents/skills/ux-audit技能三阶段审计模型中的Layer 1 — Static auditL1 静态审计。它以src/routes路由与src/features特性组件为输入通过读代码判定一个界面该有的状态与交互模式是否存在于代码中缺 empty/error 分支、无 retry、草稿未持久化、模式缺失等是每次审计都执行的最廉价基线。读完本文你将掌握 L1 的适用范围与边界、四步标准流程、状态缺口清单式检查法以及如何把它与ux技能清单、pattern-catalog模式目录、L2/L3 层衔接成闭环。本文面向的是 LobeHub 仓库中以技能化、可重复、证据驱动方式进行单界面 UX 审查的方法论文档。原文档位于.agents/skills/ux-audit/references/layer-1-static.md是ux-audit技能的 L1 层流程文件。以下内容以该文档为主体骨架结合其兄弟文件SKILL.md、pattern-catalog.md、layer-2-visual.md、layer-3-dynamic.md以及.agents/skills/ux/SKILL.md及其分模块清单展开。L1 在整个审计体系中的定位LobeHub 的ux-audit技能见.agents/skills/ux-audit/SKILL.md把一次界面审计拆成三个独立层级每一层只对它能看见的东西下结论层级流程文件做什么能抓住的问题成本L1 Staticlayer-1-static.md读代码缺失的状态/分支empty/error/retry、草稿未持久化、模式缺失、结构性问题便宜、离线、每次审计必跑L2 Visuallayer-2-visual.md渲染截屏评审真实视觉层级与主导控件、间距/对比/对齐、截断/溢出、空/加载/错误态的实际观感、响应式、深浅色中需要一次渲染L3 Dynamiclayer-3-dynamic.md用 acceptance 框架驱动真实用户旅程并打点in-progress/locked 状态、强制错误/空状态、步骤 N 是否通向 N1、焦点/键盘、量化 CLS/LCP/INP/long-tasks高需要运行环境 登录态L1 被称为 fast, offline baseline理由很直接读代码不需要渲染环境、不需要账号、不需要截图只要仓库在本地即可全量覆盖一个界面的所有代码路径因此它在每次审计中都是必跑项成本最低却给出完整的结构性覆盖。L3 动态审计假设acceptance技能的 Step 0环境 认证已就绪且所有 CDP 驱动命令agent-browser --cdp 9222 snapshot/screenshot/eval在云端xvfb-run下也可无头运行——这些是 L1 无需承担的运行前提。层间衔接遵循一条铁律一条结论必须来自能看见它的那一层。这正是覆盖矩阵的意义——你可以在 L1 断言没有 error 分支代码里能看见但绝不能从代码断言页面上主导按钮是主操作那是 L2 在渲染上的事。一、L1 能下结论与不能下结论的边界能代码里看得见的从源码结构看L1 能直接判定的是某个状态机或模式在代码里是否存在例如某个数据分支缺失没有error分支初始化标志只在成功时翻转失败即永久骨架屏草稿只存在于内存 store 而没有任何persist持久化某个界面模式完全缺席fetch 没有 retry动作没有 in-progress 中间态。这些都是结构性问题读取file:line即可命中无需渲染。不能推迟给 L2/L3L1 读不到渲染后的观感类结论包括屏幕上的主导控件是否真的是主操作、空态是否读起来像一个真实的页面、间距/对比度/截断、响应式行为以及一切带数字的指标CLS/LCP。原文档特别强调一条纪律永远不要根据variant之类的 prop 去勾选视觉结论——比如在代码里看到variantghost或isPrimary就认定这是次按钮/这是主按钮这种判断必须标记为pending L2。不能需要 surface-class 基准见 SKILL.md这是 L1 结构性盲区中最隐蔽的一种某个界面按领域惯例本该具备、但完全没做出来的能力在代码里不留下任何file:line、死分支或半接线的按钮L1 根本无从 grep。原文档给出了一个真实失误案例❌OAuth consent 界面没有 switch-account 能力——按 GitHub / Google / Okta 这类同类产品的类规范class normsconsent 屏应展示正在以哪个身份授权并允许切换账号/重新认证、点名请求方应用、列出 scope、允许/拒绝、并可跳转后续撤销而 LobeHub 首次审计仅对照内部状态清单报出了按钮层级、retry 等次优问题却漏掉了最大的那个consent 屏把用户锁死在当前身份上没有切换账号的入口。competitor-norms 一遍过能在第一分钟抓住它纯代码审计永远抓不到。因此正确做法是把 surface-class / 竞品对照得到的期望能力清单带进 L1逐项勾存在 / 缺失否则 L1 永远只在给已经存在的路径打分。不能声明的意图 ≠ 交付的结果代码注释或 prop 命名表达的设计意图是一句主张不是结论。例如// reads as one more choice、isPrimary、variantghost——支撑它的实现机制可能根本不存在L1 看不到二者之间的鸿沟。意图性注释只能作为L2 待确认项绝不能照着注释打 ✅。原文档的教训❌ 某 ask-user 自定义输入的行内注释声称它读起来像一个额外选项但那行其实没有任何真实选项携带的编号 chips——注释描述的意图渲染层从未交付。代码自述 ≠ 代码行为。二、L1 标准流程四步步骤 1 — 圈定范围并映射界面Scope map the surface先钉死界面委派到的两层代码路由层src/routes/**本仓库实际路径为src/routes包含 800 个.tsx/.ts路由文件特性组件层路由委派去的src/features/**这是 LobeHub 最大的源码目录3500 文件一个路由往往只做数据装配真正的界面块都在这里。然后自上而下枚举用户看到的所有 block外加 chrome导航、头部、侧边栏。原文档建议用一个Explore agent做广度扫描让它返回组件树并对每个 block 标注其数据获取机制、以及 empty / loading / error / retry 哪些存在、哪些缺失全部带file:line。对于你最想深挖的 2~3 个发现自己动手重读它们背后的源文件——广度靠 agent深度靠自己。以仓库中的实际审计样例example/task-detail.md为例/task/:taskId与/agent/:aid/task/:taskId两条路由树router config 中分别指向同一组件最终都渲染TaskDetailPage即src/features/AgentTasks/AgentTaskDetail/TaskDetailPage.tsx整个详情面由useActiveTaskDetail.ts、TaskActivities.tsx、CommentInput.tsx、TaskDetailRunPauseAction.tsx、TopicCard.tsx等一组文件支撑——这就是先定路由再定委派组件再逐 block 读代码的落地形态。步骤 2 — 清点使用中的模式Inventory patterns in use逐家族family走一遍pattern-catalog.md——它把 Jenifer Tidwell《Designing Interfaces》的模式语言按 7 大族组织Navigation导航Clear Entry Points、Global Navigation、Hub Spoke、Fat Menus/Sitemap Footer、Sequence Map/Breadcrumbs、Escape Hatch、Modal Panel、Deep-linkingLayout布局Visual Framework、Center Stage、Titled Sections、Card/Card Stack、Grid of Equals、Accordion/Collapsible/Movable Panels、Right/Left Alignment、Responsive DisclosureInput输入Input Prompt/Input Hints⚠️ 陷阱placeholder 必须静态、不可夹带可点击/可检索内容、Good/Smart Defaults、Forgiving/Structured Format、Autocompletion、Dropdown Chooser/List Builder/Illustrated Choices、Same-Page/Inline ErrorCommands actions命令与动作Prominent Done Button、Button Groups、Smart Menu Items、Preview、Progress Indicator/Cancelability、Multi-Level Undo、Action Panel/Overflow MenuShowing complex data复杂数据展示Overview Detail、Sortable Table、News Stream/Activity Stream⚠️ 期望配 Update Indicator 手动刷新 用户操作下不重排、Dynamic Queries、Data SpotlightFeedback system response反馈Loading Indicator/Spinner/SkeletonLobeHub 规范骨架屏或NeuralNetworkLoading绝不用 antdSpin、Progress Indicator、Update Indicator、Failure Retry、Cancelability/Deferred ChoicesGetting started上手与成长Welcome/Sign-on、Guided Tour、Empty-state as onboarding首启空态既教学又带 CTA⚠️ 陷阱promo/onboarding 槽位要可预期不能随机轮换。模式目录的用法不是背规范而是按意图匹配、不抠名称跨版本/跨库命名有差异某模式缺失不一定是 bug但这个界面明显该有而缺失如数据流没有新消息提示就是 finding。对每个 block给每个模式打三档标签✅solid扎实⚠️partial-or-misused部分或误用—absent-but-expected缺失但应有然后输出一张表Pattern | Where (block file) | rating | note。这张表同时会把缺失的模式暴露出来比如没有 Update Indicator 的 feed。仓库实测提示pattern-catalog.md末尾总结了本代码库的高发弱点区——**Feedback 族failure/retry 缺失和 Input 族草稿安全、placeholder 误用**最常出问题检查时优先扫这两族。步骤 3 — 对照 ux 检查清单审计状态Audit states against the ux checklists对每个 block走一遍ux技能相关的模块Read/Edit/Act/Feedback/Grow 五个分模块把每个缺口记为present / missing / misleading并附file:line。原文档按投入产出比最高优先排了高频检查项① Loading can failFeedback §4.2——每次 fetch 都要有终态失败 retry重点盯只在成功时置位的 init 标志→ 出错时永久骨架屏。相关规则全貌在feedback.md的 §4.2加载态必须有终态失败路径init/ready 标志不能只在成功时置位error 分支不能排在isLoading !map[id]数据在场闸门之后首次加载失败时不可达只有 revalidation 失败才渲染errorMap/isXErrorselector 若零调用点就是建好但孤儿的错误路径与缺失无异。② Empty vs failed vs not-loadedRead §1.1——区分了空 / 失败 / 未加载吗失败的加载会不会伪装成这里啥也没有规则在read.md§1.1先读error再判空失败绝不允许渲染成空态详情页读error后再落到 NotFound加载失败 ≠ 被删除/404。③ Draft safetyEdit §2.1——用户输入的草稿跨刷新持久化了吗还是只在内存里规则在edit.md§2.1编辑器要把进行中的输入备份到 durable storage刷新/崩溃/保存失败后能恢复。④ Forward momentum action statesAct §3.1——confirm → in-progresslocked→ done/error 的完整状态链在代码里存在吗规则在act.md§3.1异步/批量/不可逆动作必须 confirm → in-progress(locked) → done/error长耗时操作要提供运行中 Cancel乐观更新必须把失败面给用户catch toast绝不静默回滚。⑤ Live / polling streamsRead §1.7——有新条目信号、有手动刷新、且不在用户操作下重排吗规则在read.md§1.7轮询 feed 要信号新条目 手动刷新 不重排 刷新失败要有独立呈现不能伪装成空。⑥ Closed-loop / cross-surface entry pointsGrow §5.3——该界面是否把用户引向它配置的那个功能的数据/管理区而不是死胡同规则在grow.md§5.3给某功能做配置的界面要在上下文中链到它的数据/管理区闭环config → manage。这是 L1最容易漏的一类缺口纯配置面板一个开关、没有任何链向它管辖对象的链接或只在文案里承诺目的地——因为本该存在的链接没有 file:line。必须对每个界面都主动问这一条包括那些不起眼的只是个小表单——缺口往往藏在那里。⑦ 其他按界面酌定——Pinned actions、draft scope 等视界面类型决定是否检查。步骤 4 — 分级并记录Rank record按共享的严重度分级标准定义在 SKILL.md排定优先级然后把步骤 2 的模式表和步骤 3 的缺口清单灌进共享的输出模板见example/home.md与example/task-detail.md的产物形态。凡是无法仅凭代码得出结论的判定标记pending L2/L3让下一层知道该去确认什么。共享严重度分级SKILL.md为Breaks trust——数据/输入丢失、卡死/永久状态、用误导性的空掩盖失败、静默发送失败Dead-ends or misleads——没有前进路径、状态含混、缺少 in-progress 反馈、不像真实页面的空态Friction / inconsistency / missed delight——可预期性、冗余控件、渐进式披露缺口、CLS 抖动。这一档最容易被低估只盯着正确性跑的审计会偏重 /掠过微一致性兄弟元素样式不一、有 affordance 没 label。界面整体扎实时要刻意切换进界面细节镜片再扫一遍。三、落地形态与共享输出审计报告要报好而不只报缺SKILL.md 有一整节在纠正只列缺陷 bug 报告的偏移职责是**用到的模式 用得好不好所以亮点是头等 finding。一个精良的状态机、一个保存失败仍存活的草稿、一个 open-redirect 防护、一个聪明的默认值都该点名、附file:line、标为 ✅ 亮点**。理由有三它们教学好案例是回灌回灌/闭环循环的 ✅ 半边会成为ux清单项引用的正面例子——审计若从不报告好案例就只能在清单的 ❌ 半边打磨它们防退化别把这个改回退了本身就是一条 finding下一次重构必须知道哪些行为是承重的它们校准严重度缺口要放到这个界面整体很强还是处处都弱的基准上去读。task-detail.md是这条纪律的范本它把读/监控主脊骨的每一条亮点都带file:line写出——useActiveTaskDetail.ts以 resolving!hasTaskDetail !isNotFound为闸而不是dataundefined、副依赖闸门锁的是 in-flight 标志agentConfigLoading从而让解析为null的 assignee放行闸门而非死锁✅ 已回灌成 Feedback §4.210 秒轮询只在hasInFlightActivity期间进行✅ 已回灌成 Read §1.7run-all 的 preview → locked confirm →partialFailure/kickedOfftoast✅ 已回灌成 Act §3.1评论草稿只在await成功后才清空失败保留草稿。而它列的缺口也逐条挂到ux清单与严重度run/pause 失败静默、详情 fetch 失败伪装成 404、配置 autosave 状态枚举只有idle|saving|saved没有failed、无任务级 abort、评论提交失败无提示、artifacts 为零即整节消失。审计没写完不算完必须落地Land the findingsSKILL.md 明确审计写完 finding 不算完成落地才算。三步缺一不可具体 bug→ 修掉最顶上的 或按页建 Linear 子议题归档per-page 容器议题 → 每条 finding 一个子议题可泛化的缺口 → 回灌ux强制每条超出本界面的 finding 都要反哺ux清单——加/强化某条规则规则 ✅/❌ 例子 镜像一行到 Quick review以被审界面为 ❌ 实例。一轮跑完清单应该比跑之前更锋利若真没有任何可泛化缺口要在 Skill-feedback 部分明说沉默不是可接受的收尾示范性好案例 → 回灌ux并细化规则好案例只有教会规则新东西才值得落地——问这条模式做到的、现有规则还没要求的技巧是什么把那个区别提炼回来例如 Fleet 从滚入视野中提炼出re-run 触发有两种风味——异步到达 vs 命令式 add-then-paint、滚动轴跟随列表方向 → Read §1.3skeleton 提炼出按文本宽度比例匹配不只匹配高度 → Feedback §4.1本次审计本身→ 存为references/example/page.md供下次审计当模板。审计与ux技能因此是一个闭环ux是审计所对照的基准审计是让ux保持诚实的机制——跳过回灌就等于断环审计退化为一次性评审。为什么 L1 也要有状态强迫清单L2/L3 层的存在意义是让 L1 的推断有机会被证实或推翻。对照layer-3-dynamic.md的状态强迫食谱state-forcing cookbook可以看到 L1 盲区如何被覆盖离线/错误用 CDPNetwork.emulateNetworkConditions {offline:true}触发并观察 failureretry UI慢/卡加载用 slow 3G 冻结骨架屏空态用全新空账号能力门控则选一个缺能力的模型看软警告是否出现。CLS 这类数字则靠先注入PerformanceObserver再读累积值。L1 里标记的每个pending L2/L3项最终都会落到这些可执行验证上——这正是task-detail.md末尾§5 Pending一节的做法把详情 fetch 打 500 → 证实 D② 显示 Task not found 且无 reload等写成一串明确的 L3 验证项。四、跑 L1 时的操作要点速记每次审计都跑 L1不需要任何环境前置只有问题涉及布局/层级/渲染态/响应式时才加 L2需要走旅程/强制 L1/L2 到不了的状态/量化 CLS 时才加 L3。CLI 可用--l1 / --l2 / --l3把一次运行限定到某一层默认 L1若附了截图则加跑 L2。证据不是感觉evidence, not vibes每条 finding 都要带证据——L1 是file:lineL2 是用 Read 工具验证过的截图L3 是捕获到的值/快照。任何承重断言都要先在拥有它的那一层确认——一个错误的它缺失了比没有 finding 更糟。对照界面类打基准不只是对照自家产物读自家代码只能暴露我们做了的东西里的瑕疵结构上对我们压根没做过的能力是瞎的。先在代码前写下这个界面所属类OAuth consent、file picker、checkout、share dialog…的期望能力清单再对着它审计缺口否则审计永远只是在给已有路径抛光还会悄悄放走一个缺失项。冗余控件先想组合层再谈删减L1 发现两个控件看似做同一件事时条件反射是删/藏/合并。先问意图相同、scope 不同——scope 更宽的应该提升为可见的平级兄弟Titled Sections 一类的组合层动作而不是删除。务必先走完 pattern-catalog 再对任何冗余/重叠发现开药方。结语L1 静态审计是整个 LobeHub 三阶段 UX 审计的基石它以近乎零成本换得对一个界面全部代码路径的结构性覆盖把缺分支、缺 retry、缺持久化、缺模式这类代码级缺口一次性扫清并把视觉观感类结论诚实地上交 L2、把运行时/量化类结论上交 L3。对照本仓库的实操样例task-detail.md、home.md等可以把它当作可直接复制的报告模板而每一轮 L1 产出经回灌ux后都会让下一轮审计所对照的基准更锋利——这就是 LobeHub 把 UX 审查做成可重复、证据驱动、且持续进化的闭环机制的关键所在。下一篇可继续深入 L2 视觉审计截图如何取证、如何从渲染上确认主导控件与 L3 动态审计CDP 驱动旅程 Core Web Vitals 打点三篇合起来即构成完整的界面审计方法论。【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考