LobeHub 代码评审实战：deep-review 的 Code Style 维度如何守护片段级可读性与约定

本文以 LobeHub 仓库中 deep-review 技能的核心规则文件 code-style 维度 为主体，完整拆解该维度定义的检查清单、检查方法与违规判定边界，并结合 typescript、react、i18n 三个规则源文档及仓库 ESLint 配置，讲清楚这条"片段级风格审查"流水线在实际代码库中如何落地。读完后，你将掌握一套可复用的 PR/Diff 风格审查方法论：查什么、怎么查、什么算违规、什么不算违规。

一、Code Style 维度在 deep-review 体系中的定位

deep-review 是 LobeHub 仓库为 AI 编码代理设计的一套多维度代码评审技能：评审广度来自多个并行维度，精准度来自对抗式验证与全局去重。其核心原则之一被概括为 "Rules over model"——评审质量来自细粒度、可执行的维度规则，而非更聪明的模型。每个维度对应 references/dimensions/ 目录下的一个规则文件，code-style.md 就是其中之一。

该文件的 frontmatter 声明了三个元信息：

id_prefix: style
verify: true
skip_when: docs/lockfile-only diff

• id_prefix: style：该维度产出的问题编号以 style 为前缀，在 SKILL.md 的维度表中可查（覆盖命名、可读性、死代码、注释、i18n 硬编码、UI 库与样式约定）；
• verify: true：该维度的候选发现必须经过独立 verify 子代理的三元裁决（confirmed / false_positive / need_more_context），通过后才进入报告——这是 deep-review"反幻觉"原则的体现，避免评审代理只看 diff 片段而臆造问题；
• skip_when: docs/lockfile-only diff：仅在纯文档/lockfile 变更时跳过。值得注意的是，deep-review 明确"docs-only 仅指人类可读散文"——.agents/skills/**、AGENTS.md 等承载控制流与契约的文件算作代码，触碰它们的 diff 永远不会被判定为 docs-only。

维度文件开篇界定了一个关键边界：Code Style 只看片段级可读性与约定遵循。审查者应孤立地看待每个变更 hunk（连同其所在文件）；跨文件复用与抽象问题属于 reuse-architecture 维度。这种职责切分保证了 14 个维度并行评审时互不越界。

二、Quick Checklist：11 条可执行检查项逐条解析

Quick checklist 是 light 模式评审者唯一读取的部分（deep 模式读取完整维度文件 + 规则源文档）。以下逐条继承原文档，并结合仓库源码扩充其落地依据。

2.1 残留的 console.log / console.debug

检查项：残留的 console.log / console.debug——应改用 debug 包或直接删除。

仓库的 ESLint 配置印证了这条规则的边界：在 eslint.config.mjs 中，no-console 仅在特定文件被放开（约 L479–L504），包括 e2e/测试文件（"allow console.log for debugging"）和 packages/model-runtime/src/utils/debugStream.ts（该文件以 console 输出为主要接口）。也就是说，除这些白名单外，生产代码中的 console 输出在 CI 层面即受约束，评审时若发现残留应标记为违规。typescript 技能的 Logging 章节还补充了更细的约定：不要直接 import { log } from 'debug'（它打到 console）；catch 块中用 console.error 而非 debug 包；.catch() 回调中必须记录错误，silent .catch(() => fallback) 会吞掉失败。

2.2 try/catch 中缺失的 return await

检查项：try/catch 内缺失 return await（拒绝会逃逸出 catch）——原文档引用了 typescript-eslint 的 return-await 规则。

这是一个典型的"看似无害"问题：return foo() 会把 Promise 的拒绝传递给外层，而不是被同一函数的 catch 捕获。deep-review 将其列为片段内即可见（visible within the fragment）的风格问题，因为它完全可以在单个 hunk 内识别，不需要跨文件上下文。

2.3 硬编码的用户可见字符串

检查项：硬编码的用户可见字符串——必须走 i18n key，key 位于 packages/locales/src/default/<namespace>.ts，命名模式为 {feature}.{context}.{action|status}。

仓库结构可直接验证这一约定：packages/locales/src/default/ 下按命名空间组织源文件（agent.ts、auth.ts、chat.ts、common.ts、setting.ts 等），各语言的生成 JSON 则位于根目录 locales/ 下。i18n 技能进一步细化了 key 规范：

• 使用点号平铺 key，禁止嵌套对象（'alert.cloud.action': '立即体验' 而非 alert: { cloud: { action } }）；
• 参数使用 {{variableName}} 插值语法；
• 避免 key 前缀冲突（如 clientDB.solve 与 clientDB.solve.backup.title 冲突，应改为 clientDB.solve.action）。

评审操作上也给出了明确方法：扫描新增的 JSX/文本字面量，凡是用户可见的都需要 key。仓库 AGENTS.md 的 i18n 章节还要求 en-US 与 zh-CN 在同一个 PR 中手写交付，其余语言交给每日 CI 工作流自动生成——评审时可以顺带检查新增 key 是否只改动了 packages/locales/src/default/ 而非生成目录。

2.4 UI 组件库导入优先级

检查项：当 @lobehub/ui（或 @lobehub/ui/base-ui）封装了同名组件时，不应再直接 import from 'antd'——优先级是 base-ui 优先，其次 @lobehub/ui，antd 最后。

react 技能 给出了完整的五级优先级：项目内 src/components → @lobehub/ui/base-ui（headless 原语，"组件在这里就用它"）→ @lobehub/ui（上层封装）→ antd → 自研（最后手段）。并特别点名了一个常见陷阱：import { Select } from '@lobehub/ui' 看似没问题，但它是 antd 底层的 Select，应改用 base-ui 的 Select。base-ui 中"永远优先"的组件清单包括 Alert、Select、Modal（命令式 API：createModal / confirmModal / useModalContext）、DropdownMenu、ContextMenu、Popover、ScrollArea、Switch、Toast、FloatingSheet、Drawer。

code-style 维度给出的核查命令也保留了可操作性：

rg "from 'antd'" <changed files>

然后逐个确认 @lobehub/ui 或 @lobehub/ui/base-ui 是否导出了同名组件（不确定时可查 node_modules/@lobehub/ui/es/index.mjs 与 node_modules/@lobehub/ui/es/base-ui/）。

2.5 硬编码颜色 / 原始 CSS 值

检查项：硬编码颜色或原始 CSS 值——应使用 antd-style token；除非样式需要运行时计算，否则优先 createStaticStyles + cssVar.* 而非 createStyles + token。

react 技能 的样式决策表与此完全对应：

场景	方案
大多数情况	createStaticStyles + cssVar.*（零运行时，模块级）
简单的一次性样式	内联 style 属性
真正动态（如 readableColor / chroma 等 JS 颜色函数）	createStyles + token（最后手段）

评审时这条规则的判定依据是"该 hunk 中的颜色值是否可用 token 表达"，而不是要求整个文件重写。

2.6 其余六项：死代码、注释、嵌套、冗余状态、类型松散、文件膨胀

• 死代码：本次 diff 引入或加剧的死代码、被注释掉的代码块、未使用的导出。"本次 diff 引入"是判定的关键词，存量问题不报。
• 注释：三种情况算违规——hacky/非显而易见逻辑缺失注释；签名变更后 JSDoc 过期（stale）；注释只是复述代码。核查方法是对比签名/行为变化与周围 JSDoc。
• 嵌套 ≥ 3 层：可以用 early return 或查找表拍平的深嵌套。
• 冗余/可推导状态：镜像 prop 的变量、或可由现有状态计算出的 state 字段——应改为 selector、useMemo 或纯表达式推导，避免第二份会漂移的拷贝。这一条与 react 技能 的 State 章节呼应：瞬时状态放在最小可用 owner，memo/useMemo/useCallback 是 opt-in 优化而非默认包装。
• 类型松散：any、被类型签名掩盖的运行时收窄、隐式契约。typescript 技能 给出了对应细则：避免隐式 any，必要时用 Record<PropertyKey, unknown> 替代 object/any；优先 @ts-expect-error > @ts-ignore > as any；对象形状用 interface，联合/交叉用 type。ESLint 侧也配置了 @typescript-eslint/consistent-type-imports（见 eslint.config.mjs 约 L410），强制 import type { ... } 独立语句。
• 文件膨胀超过 ~800 行：仓库 AGENTS.md 的 Code Style 章节给出了同一条硬约定——"单文件超过 ~800 行时考虑拆分为子组件、hooks、helpers 或类型"，理由是"更小、更聚焦的文件对人友好，对 agent 同样友好"。

三、How to Check：四步检查方法

原文档把检查流程压缩为四步，这也是 light 模式评审者的操作脚本：

1. 逐 hunk 阅读 diff：风格问题必须能在片段内（连同其所在文件）看见；
2. UI 导入核查：rg "from 'antd'" <changed files>，确认 @lobehub/ui 或 @lobehub/ui/base-ui 是否导出了同名组件；
3. 字符串核查：扫描新增的 JSX/文本字面量，用户可见的内容必须有 i18n key；
4. 注释核查：将签名/行为变化与周围 JSDoc 对比，标记过期文档。

这四步的共同特征是"片段内可裁决"——不依赖跨文件复用判断（那是 reuse-architecture 的事），因此可以由一个独立的、只读 diff 的 light 评审者执行。

四、规则源文档：deep 模式下的前置阅读

维度文件明确列出 deep 模式评审代理在评审前必须读取的规则源（rule sources）：

规则源	覆盖内容
.agents/skills/typescript/SKILL.md	TS 风格与类型安全：推断优先、interface vs type、async/await 与 IO 异步优先、独立 type import、named exports、packages/utils 复用
.agents/skills/react/SKILL.md	组件优先级（base-ui/@lobehub/ui/antd）、antd-style 样式决策表、状态局部性、渲染性能与 memoization 的 opt-in 原则
.agents/skills/i18n/SKILL.md	locale key 命名规范、哪些内容需要 key、packages/locales/src/default/ 工作流
根目录 AGENTS.md / CLAUDE.md	仓库级约定：800 行拆分阈值、i18n 交付要求、bun run check 质量检查流

这种"维度文件 + 路由规则源"的分层设计是 deep-review "Rules over model" 原则的具体实现：维度文件本身只写裁决标准（what counts / what does not），细则收敛在各技能文档的单一事实源（single source of truth）中，AGENTS.md 也明确规定"把详细实现规则放进 skills，让约定只有一个来源"。

五、违规判定边界：calibration 原则

code-style 维度最有工程价值的部分，是它对"什么算违规、什么不算"的精确划定。

算违规（Violations）：

• Quick checklist 中的任何一项——前提是由本次 diff 引入或使其恶化；
• 误导性命名（名字说 X，代码做 Y）——即使代码库中已存在其他弱命名，新引入的误导命名依然是违规。

不算违规（Not violations）：

• Prettier/ESLint 已强制的格式问题——CI 负责，不要报（仓库通过 bun run check 统一跑 lint + test，见 AGENTS.md Quality Check 章节）；
• 平淡但准确的命名——不要求命名富有诗意；
• 未触碰行上的存量风格债——校准原则（calibration principle）："这个 diff 没有让它变差"即不成立发现；
• 与文件既有规范一致的注释密度——不要求在一个疏于注释的文件里给每个函数补 JSDoc。

这套边界与 deep-review 的第四条核心原则一致：按代码库已达到的标准来衡量 diff，而不是理想化标准。它直接决定了评审报告的信噪比——把"CI 会管的"和"存量债"排除在外后，评审者只剩真正需要人（或 agent）处理的片段级问题。

六、落地路径：在 LobeHub 中如何触发这套评审

结合 SKILL.md 的流程，code-style 维度有两种进入方式：

• Light 模式（默认）：任何普通评审请求（"review this PR"、粘贴 diff 求查问题）都走 light——派发一个独立评审者，只读取各适用维度的 Quick checklist（含嵌套示例小节），无 verify 环节，主代理不亲自评审。code-style 的 skip_when 使它在 docs/lockfile-only diff 上被剪枝；
• Deep 模式（显式触发）：仅 /deep-review 等显式指令触发，完整编排为"维度评审代理 → 流水线式验证 → 全局去重 → 结构化报告 → 交互式修复"。code-style 因 verify: true，其每条发现都会经过独立 verify 子代理读取完整上下文后裁决。

一个值得注意的配套约束是 Deep 模式预算：同一逻辑需求（同一需求/PR/分支）默认最多运行一次 Deep，修复后的复核一律降级为 Light——这避免了"每次 fix commit 后都触发全量多代理评审"的成本失控。

小结

code-style 维度 把"代码风格评审"从一句空泛的要求压缩成了 11 条片段内可裁决的检查项、一条 rg 核查命令、四步操作流程和一份清晰的违规/非违规边界表；再由 typescript、react、i18n 三个规则源提供细则深度，与 eslint.config.mjs、packages/locales/src/default/、AGENTS.md 中的仓库实际约定互相印证。对于在多代理工作流中承担 PR 评审职责的团队，这套"规则文件 + 独立评审者 + verify 裁决 + 校准原则"的架构，是把风格约定从口头共识变成可执行、可验证工程约束的一个完整样例。