Dify 前端代码评审实战：frontend-code-review 技能中的代码质量规则包深度解析

本文基于 Dify 仓库中 code-quality.md 这份评审规则参考文档展开，完整覆盖其五大类代码质量规则（范围控制、TypeScript、样式、导入、文案与 i18n），并结合 cn() 工具实现、dify-ui 包导出声明 与 i18n 校验脚本 等真实源码，解释每条规则背后的工程约束。读完后你可以直接套用这套规则对 web/ 与 packages/dify-ui/ 下的代码变更做结构化评审，并理解 Dify 前端在类型边界、样式令牌和国际化方面的强制性约定。

一、规则包定位：frontend-code-review 技能中的"兜底规则包"

code-quality.md 并不是独立的规范文档，而是 Dify 仓库内 frontend-code-review 技能 的八个规则参考包之一。该技能专门用于对 web/ 或 packages/dify-ui/ 下的前端代码做评审（支持待提交变更、指定文件和粘贴 diff 三种评审模式），其 SKILL.md 定义了一套"按 diff 内容路由规则包"的机制：只加载与本次变更实际匹配的规则文件，而不是一次性通读全部规则。

路由表中的分工如下（引自 SKILL.md 的 Rule Routing 章节）：

变更涉及领域	对应规则包
DOM 语义、焦点、键盘、表单、禁用态等交互	accessibility-ui.md
Dify UI 导入、Base UI 封装、overlay、令牌	dify-ui.md
组件归属、props、状态、Effects、模块边界	component-architecture.md
生成的客户端、Query、mutation、SSR、URL 状态	data-query-contracts.md
测试文件或缺失回归测试	testing.md
Bundle、渲染瀑布、订阅成本	performance.md
命名路径上的 Dify 运行时不变量	dify-invariants.md
通用 TypeScript 或样式质量（未被上述规则包覆盖的部分）	code-quality.md

可以看到，code-quality.md 承担的是"兜底"职责：凡是 TypeScript 类型质量与样式代码质量、且不属于上面七个专项的问题，都由它管辖。技能的评审原则同样是"证据优先"（Evidence First）：先确立评审范围，阅读变更行及其行为所有者与最近的 AGENTS.md，只在影响正确性时才追踪公开消费者与运行时配置；只报告能绑定到可观测故障、被违反的契约、安全边界或可证明的维护风险的发现。评审结论按 P0（安全/隐私泄漏、数据丢失、生产崩溃）到 P3（轻微可执行清理）分级输出，并要求每个发现附带紧凑的文件与行号引用、失效的契约或复现路径、影响面与具体修复方向。

理解了这一定位，就能明白这份规则包为什么以"Flag / Prefer（Use）"清单而非完整代码示例来组织：它是评审时的判定标准，而非教学文档。下面逐节完整解读这四类规则，并补充仓库内的实现证据。

二、范围控制（Scope Control）：先盯住"评审范围之外"的变更

规则包的第一条不是代码风格，而是评审范围的守界。评审时必须标记（Flag）以下超出所请求功能或评审范围的变更：

• 把全仓库清理（repo-wide cleanup）混入一个定向修复（targeted fix）；
• 在没有明确迁移需求的情况下加入兼容性导出、别名、shim 或包装层（wrapper layers）；
• 在跨功能复用尚未稳定之前就提前创造共享抽象；
• 把业务组件在没有清晰所有权边界的情况下搬进通用共享位置。

这四条共同指向一个原则：每一次 PR 的 diff 应该恰好等于它声称要解决的问题。共享抽象、兼容层、组件搬家这三类"看起来是重构"的变更，恰恰是最容易让 diff 失去可评审性的来源——评审者无法区分哪些行是目标功能的实现、哪些行是顺手重构。Dify 仓库本身提供了很好的反例约束：其前端组件层有明确的归属划分（应用层代码在 web/，基础 UI 原语在 packages/dify-ui），业务组件是否"应该"下沉为共享原语，需要先在 dify-ui 的包边界文档 里找到依据，而不是在评审 diff 里临时决定。

三、TypeScript 规则：类型边界在哪里收口

文档对 TypeScript 的 Flag 清单有四条：

1. any 或宽泛的 Record<string, any>——前提是"已经存在生成/API 类型或本地领域类型"。Dify 的 web/ 中存在生成客户端与契约包（仓库根目录的 packages/contracts 即存放跨端共享契约），在已有强类型来源时仍写 any，等于主动放弃了编译期检查；
2. 重新声明 API 形状——应当导入生成类型或接口返回类型，而不是在组件文件里手写一份"看起来一样"的接口。手写副本与真实契约的漂移是 Dify 这类前后端分离项目中最常见的隐性 bug 来源；
3. 弱化的路由/查询参数类型——让 string | string[] | undefined 一路泄漏进组件深层。规则要求"在路由/API 边界做类型收窄"（type narrowing at route/API boundaries），即参数解析只发生在入口处，进入组件树之后拿到的是已经收窄过的具体类型；
4. 只为满足 TypeScript 而加的运行时包装——如果存在更窄的类型边界就能保留既有运行时形状，就不应该为此引入运行时对象转换。

与之对应的 Prefer（推荐做法）清单是：

• 使用与 API 契约匹配的、显式的领域命名；
• 在路由/API 边界做类型收窄；
• 小的转换辅助函数（conversion helpers）与需要它的组件同置（colocated），而不是塞进全局工具库。

这三条推荐合起来描述的是同一件事：类型问题应在最小边界内解决。转换逻辑就近放置，既避免"全局 utils 垃圾桶"，也避免为了类型正确性改变运行时数据形状。

四、样式规则：Dify 令牌体系与 cn() 的底层依据

这是规则包中最长的一节，完整继承了原文档的全部 Flag 与 Use 条款。

4.1 应当标记（Flag）的样式写法

• 当 Tailwind 工具类与 Dify 令牌已能覆盖需求时，仍新建 CSS modules 或临时 CSS（ad hoc CSS）；
• 组件级的裸 .css 文件，或通过 globals.css 导入组件 CSS；只有在 Tailwind 与组件变体确实无法表达该样式时，才使用作用域化的 *.module.css；
• 在 Dify 语义令牌已存在的地方使用通用颜色工具类；
• 颜色、间距、圆角、阴影、z-index、排版上使用硬编码的"魔法值"类——前提是 Dify 令牌、组件变体或已文档化的圆角映射本可以表达它；
• 没有狭窄且有文档说明的理由时使用 ! important 修饰符或 important CSS 覆写；
• 用手动字符串拼接、模板字符串、数组 .join(' ') 或自定义三元表达式来处理条件类名或多行类名；
• 对 Dify UI / Base UI 已经通过 data-* 选择器暴露的原始视觉状态，仍然写 JS 条件类名分支；
• 传入的 className 被放在 cn(...) 中默认类之前，导致调用方无法覆写；
• overlay 上使用任意 z-index 或一次性的层叠修复。

4.2 应当使用（Use）的写法

• 使用本地包或该文件已在用的 cn(...) 工具合并类名；
• 使用 Dify 语义令牌与 Tailwind v4 工具类；
• 优先使用既有组件变体，而不是分叉出一套一次性类名；
• 在为了样式引入 React state 或布尔 props 之前，先使用原语选择器：data-disabled:*、data-checked:*、data-highlighted:*、group-data-*、peer-data-*、has-[:focus-visible]；
• 先使用组件级变体、语义令牌与正常级联/顺序，再考虑 ! 覆写。! 仅用于"无法通过组件 API 或局部选择器结构表达、且有界"的兼容覆写。

这些条款在仓库源码中有直接落点，可以逐条验证：

cn() 的实现依据。 规则要求"用 cn(...) 合并类名"，其真实实现就在 packages/dify-ui/src/cn.ts：

import type { ClassValue } from 'clsx'
import { clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'

function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

export { cn }

两个依赖解释了规则的两处细节。clsx 负责把条件值、数组、对象语法收敛成类名字符串——这正对应 Flag 中"禁止手动模板字符串拼接与 .join(' ')"的原因：cn 的 ClassValue 参数已经天然支持条件与数组写法。而 tailwind-merge 负责按 CSS 特异性后写者优先的原则去重冲突的工具类，这正是"className 必须放在默认类之后才能覆写"的机制基础：twMerge 让后传入的类赢掉前面的冲突类，所以"传入的 className 放前面"的写法会被工具静默地"修正"掉，造成调用方误以为自己的覆写生效而实际没有（或反之，默认类意外生效）。cn 的对外入口是 dify-ui 的 ./cn 子路径导出，消费方应从这个官方子路径引入，而不是各自复制一份。

Tailwind v4 与语义令牌。 packages/dify-ui/package.json 的 peerDependencies 中列有 tailwindcss，devDependencies 中有 @tailwindcss/vite（Tailwind v4 的官方 Vite 集成），这与规则中"Tailwind v4 utilities"的表述一致；同时 class-variance-authority（CVA）也在依赖列表中，印证了"既有组件变体优先"这一条——Dify 的原语组件正是用 CVA 声明变体（variant）体系的。令牌的完整映射与圆角文档位于 packages/dify-ui/docs/styling.md，overlay 的层叠规则位于 packages/dify-ui/docs/overlays.md，评审"任意 z-index / 一次性层叠修复"这类发现时应以这两份文档为判定依据。

data-* 选择器优先于 JS 状态。 规则要求对"已暴露的原始视觉状态"先用 data-disabled:*、group-data-* 等选择器。这与 Dify UI 原语构建在 Base UI（@base-ui/react 出现在 dify-ui 的 peerDependencies 中）之上有关：Base UI 组件在 DOM 上输出结构化的 data-* 状态属性，样式可以直接消费这些属性，从而避免"为了一个视觉状态专门加一个 React 布尔 prop + state"的冗余链路。

4.3 导入（Imports）规则：子路径导出是强制边界

原文档的 Imports 节要求标记四类问题：

1. 从 @langgenius/dify-ui 的桶式导入（barrel imports）——消费者必须使用子路径导出；
2. 从旧版 @/app/components/base/modal、dialog、drawer 引入新的 overlay；
3. 绕过显式顶层公开文件的跨功能导入；
4. 当功能契约已暴露目标面时，直接导入生成/内部实现文件。

第 1 条在源码中有非常硬的证据：packages/dify-ui/package.json 的 exports 字段根本没有定义包根路径（"."）导出，只有 ./cn、./styles.css 以及 ./button、./dialog、./drawer、./combobox 等几十个显式子路径。也就是说，桶式导入 @langgenius/dify-ui 在当前包结构下直接不可解析——这不是风格偏好，而是由 exports map 物理强制的边界。子路径导出同时带来打包层面的收益：每个子路径指向独立的 index.tsx 入口，未使用的原语不会经由 barrel 被拖进 bundle。

第 2 条的旧版 overlay 路径（web/app/components/base/modal 等）在当前仓库中已不存在对应目录（web/app/components/base/ 下查无此三目录），可以确认这是一批被标记为 legacy 的旧组件位置：新增代码一律走 @langgenius/dify-ui/dialog、/drawer 等新子路径，而 dify-ui.md 路由文档 进一步要求 overlay 相关问题先读 docs/overlays.md 与包内实现。

五、文案与 i18n 规则：可校验的本地化契约

原文档 Copy And i18n 节的完整 Flag 清单：

• web/ 中用户可见的硬编码字符串；
• 新增或重命名的 i18n key 未出现在所触及命名空间的每一个受支持 locale 文件中；
• 翻译命名空间漂移——尤其是用无关模块的命名空间承载本地功能文案；
• 动作明确却使用 Continue 这类通用按钮标签；
• 只陈述失败、不给出下一步的错误消息。

对应的使用规则是：默认使用功能本地（feature-local）翻译 key，跨命名空间时才使用别名；并且任何被触及的翻译命名空间都必须能通过 pnpm i18n:check --file <name>。

仓库中这条规则是可执行、可校验的：

• 校验脚本入口声明在 web/package.json："i18n:check": "tsx ./scripts/check-i18n.js"，即规则文档中的命令直接对应 web/scripts/check-i18n.js 这一实现；
• web/i18n/ 目录下实际维护着 24 个 locale 目录（ar-TN、de-DE、en-US、es-ES、fr-FR、ja-JP、zh-CN 等，共 888 个 JSON 词条文件），这就是"每个受支持 locale 文件"的实体。评审时检查 key 是否全 locale 覆盖，本质上就是在跑这个脚本能跑出的同一套校验。

关于"翻译命名空间漂移"，其风险在于：把 A 功能的文案塞进 B 模块的命名空间后，任何一次 B 模块的词条整理都可能顺带破坏 A 功能的显示，且 grep 词条时会误导维护者去错误的模块下找定义。规则用"默认 feature-local，跨命名空间才 alias"给了一个明确的判定标准，使评审可以给出可执行结论而不是风格建议。

六、落地建议：如何把这份规则包用于一次评审

结合 SKILL.md 的评审流程，code-quality.md 的实际使用方式可以归纳为四步：

1. 先定范围再谈质量：按 Scope Control 四条先扫一遍 diff，剔除或单独列出越界变更——这一步决定后续评审是否还有意义；
2. 按领域路由：如果 diff 只涉及 overlay 层叠、按钮变体、dify-ui 导入形态，优先走 dify-ui.md 及其指向的包内 owner 文档（authoring.md、styling.md、overlays.md）；code-quality.md 处理剩余的通用类型与样式问题。两份规则对同一处代码同时命中时，以专项规则的契约描述为准，通用规则作为补充；
3. 每条发现要求可复现依据：标记 any、桶式导入、魔法值类名、!important 等发现时，必须给出文件行号、被违反的契约（如 exports map 的强制子路径、令牌映射文档）以及具体修复方向（如"改从 @langgenius/dify-ui/cn 导入并用 cn() 合并"），这与技能"只报告绑定到可观测故障的发现"的原则一致；
4. i18n 变更以脚本为准：任何触及翻译命名空间的 PR，直接运行 pnpm i18n:check --file <name>，脚本输出即评审结论，避免人工逐 locale 比对 24 个目录。

需要说明的适用前提：这份规则包描述的是 Dify 当前仓库的前端技术栈（Next.js + React 的 web/ 应用、packages/dify-ui 原语包、Tailwind v4、Base UI、CVA 变体、web/i18n 的 JSON 词条体系），其条目（如"旧版 overlay 路径"）与该仓库自身的演进状态绑定；把规则迁移到其他项目时，需以目标项目的实际包结构与令牌体系重新校准。