uxlint

uxlint

像熟悉设计的评审者一样审查任意网站的 UX：对比度、点击区域、字体比例、色彩规范、扫描模式、页面地标。每条发现都附有明确的修复建议，Agent（或人工）可直接采用。它专为融入编码 Agent 的工作流（MCP）而设计，并可反复迭代，直至全部通过。

一次真实运行，从开始到结束：audit_url → 评分 B，发现 2.39:1 的对比度错误，以及三个 CTA 使用了三种不同的强调色 → 修复 → verify_fix → 评分 A。其中每个数字都来自工具；只删去了等待时间。

这是 CLI：一个小巧的静态 Rust 二进制文件。它通过 DevTools 协议驱动你已安装的 Chrome/Chromium（无需 Node、Playwright 或下载无头浏览器），捕获页面的视觉和文本表现，并将其发送给 uxlint 的托管服务，由该服务进行实际评分。规则引擎、校准后的阈值和 LLM 评审器都在服务端，因此规则变更时无需更新客户端。

┌──────────────────────────┐        POST /v1/audit {snapshots}        ┌──────────────────────────┐
│ uxlint (this binary)     │ ───────────────────────────────────────▶ │ uxlint-server (hosted)    │
│ drives YOUR Chrome (CDP) │ ◀─────────────────────────────────────── │ rules engine + LLM judge  │
└──────────────────────────┘        report {findings + fixes}         └──────────────────────────┘

安装

curl -fsSL https://uxlint.net/install.sh | sh    # detects OS/arch, verifies checksum

也可以使用 mise——它的 github 后端会从 GitHub Releases 下载匹配的构建版本、验证该版本，并在运行 mise up 时更新：

mise use -g "github:uxlint-net/uxlint-cli[rename_exe=uxlint]@latest"

或者在项目的 mise.toml 中固定版本：

[tools]
"github:uxlint-net/uxlint-cli" = { version = "latest", rename_exe = "uxlint" }

也可以从源代码构建（需要较新的稳定版 Rust 工具链，以及 PATH 中的 Chrome/Chromium）：

git clone https://github.com/uxlint-net/uxlint-cli && cd uxlint-cli
cargo build --release
./target/release/uxlint --version

快速开始

uxlint auth login                                        # opens your browser, saves a token
uxlint audit --base https://your-site.com --routes /,/pricing

首次审查自己的项目？uxlint init 会选择（或创建）一个用于关联报告的网站，并写入 uxlint.toml，这样今后在此目录中进行的每次审查都会直接生效：

uxlint init
uxlint audit --base http://localhost:5173 --routes /,/pricing

发现项超过配置的严重性等级时，退出代码为 1 → 可直接用于 CI（模板见 .github/workflows/，也可使用 GitHub Action uxlint-net/uxlint-action）。

在审查中隐藏元素（uxlint-hide）

有些页面上的界面元素并非产品 UI，不应纳入评审：开发/暂存环境横幅、“DEV”标记、调试工具栏、Storybook/预览入口。给这类元素添加 uxlint-hide 类，审查时就会将其移除——它从首次绘制开始就是 display:none，因此不会出现在截图中，也不会被采集器看到（不会产生任何发现）：

<div class="env-banner uxlint-hide">STAGING</div>

该类在实际网站上不起作用——只有在运行审查时才会生效，因为隐藏它的样式表（.uxlint-hide { display: none !important; }）仅由 uxlint 的浏览器注入，且会在页面自身脚本运行前注入。其他时候，你可以随意设置该元素的样式。它适用于所有捕获路径——爬取、目标遍历测试和修复预览。

有什么变化？（--allow-mutation）

交互审计会导航、读取并点击候选菜单、展开控件和对话框控件。 发现阶段会跳过可访问名称中包含已识别动作动词的控件：delete、remove、accept、 leave、revoke、cancel、transfer、pay、publish、submit、add、create、save 及其变体；只要这些词作为完整单词出现在标签的任意位置，就会匹配。标签无法证明点击处理程序实际会做什么，因此请在你能控制且使用一次性数据的环境中运行交互 审计。

有两个探测会写入数据，而且除 --states 外，两者都需要 --allow-mutation：

• action-feedback 探测会点击一个建设性操作（Add / Create / Save），检查页面 是否提示操作已完成；
• destructive 探测会点击 Delete / Remove，并在确认对话框中继续点击，检查 其约定：破坏性操作要么先要求确认，要么提供撤销选项。

它们会触发 action-no-feedback、destructive-no-confirm 和 undo-missing，这三条规则 在未启用该标记时不会触发。**仅限一次性环境。**以有权删除某一行的用户身份登录，并不等于你已授权我们删除；这个标记就是让你明确授权的方式。

uxlint mcp 从不设置该标记，也无法要求它设置。

审计会写入数据的另一种情况，是你自己编写的测试：声明的 [[tests]] 流程会以某个 角色登录并执行真实流程，而这正是测试的做法。

MCP（在编码 Agent 中使用）

Claude Code，一条命令：

/plugin marketplace add uxlint-net/uxlint-cli
/plugin install uxlint@uxlint

这会安装 uxlint MCP 服务；如果 CLI 尚未在你的 PATH 中，还会使用与上文相同的校验和验证安装程序获取匹配版本，并且只获取一次——因此 /plugin update 也会同时更新其底层 CLI。不需要 Node：它会下载一个静态二进制文件（并根据已发布的校验和进行验证），然后驱动你已有的 Chrome。

其他 Agent——一行命令（npm 包会为你的平台获取二进制文件，验证其旁边发布的校验和，然后交由客户端使用）。这是唯一需要 Node 18+ 的方式，因为要运行 npx 本身；如果你不想使用 Node，请用顶部的命令安装二进制文件并注册它：

claude mcp add uxlint -- npx -y @uxlint-net/uxlint mcp

或者，对于读取 JSON 配置的客户端：

{ "mcpServers": { "uxlint": { "command": "npx", "args": ["-y", "@uxlint-net/uxlint", "mcp"] } } }

uxlint 也已加入 MCP 注册表，名称为 io.github.uxlint-net/uxlint，供可浏览注册表的客户端使用。已经安装 CLI？uxlint mcp install 可直接注册，无需 npx 包装器。

无需预先设置令牌：让 Agent 在退出登录的状态下审计某项内容，它会提供一个登录链接，为你生成并保存令牌（UXLINT_API_KEY 供 CI 使用，因为 CI 没有 浏览器）。

五种工具：audit_url（完整审计，提供评级结论和行动计划）、verify_fix（编辑后重新检查某个页面上的一条规则）、get_shot（获取某项发现的标注截图）、 ux_guidance（构建 UI 之前阅读的最佳实践指南）以及 lint_feedback——默认关闭、需主动启用（§ 隐私）——一个工具，收集三类反馈：某项发现是否有用、uxlint 缺少的 lint 规则，或它未识别的组件库。Agent 会执行审计、阅读修复建议、编辑并再次审计，直到结果全部通过。

验证与设计记忆

verify_fix 返回 passed、failed、not_evaluated 或 inconclusive。仅凭发现数为零 绝不表示修复已通过。目前，通过验证涵盖 page-title-missing、 html-lang-missing 和 horizontal-overflow，并且针对所请求的路由和 两种视口提供了明确证据。其他检查可以报告失败，但需要完整审计和证据审查； 未知规则、跳过的检查和旧版服务无法通过。检查项解除后绝不会自动提交接受投票。

将已批准的项目决策保存在 uxlint.toml 旁边的 uxlint.design.json 中。每次调用 ux_guidance 时都会重新读取该文件，包括在新的 Agent 会话中。先创建草稿：

{"version":1,"revision":1,"status":"draft","site":"example.test",
 "tokens":{"accent":"var(--color-brand)"},
 "components":{"primary_action":"Reuse PrimaryButton"},
 "pages":{"/":"Explain the product and offer a clear starting action"},
 "journeys":["Start the main task from the homepage"],
 "references":["/styleguide"],"exceptions":[]}

将 site 设置为项目配置的网站。将 status 设为 approved 并提交文件之前， 请与负责人一起审查这些决策。后续获批的更改应递增 revision。该工具不会批准或写入 契约；草稿不会成为指导。参考资料不会自动获取，例外不会抑制 lint 检查，而且这份 初始本地记忆目前既不会强制执行令牌，也不会比较截图。无效的契约会产生醒目警告。 文件应小于 32 KiB，且不要在其中放入凭据或客户私人数据。

隐私与信任

此 CLI 在你的机器上运行，并通过真实浏览器访问真实页面，因此你理应想知道它具体会 捕获什么，以及数据会被发送到哪里。以下说明均基于本仓库中的实际代码：

• 采集器内置于二进制文件中，且可读。 它通过 include_str! 编译进此 二进制文件（assets/collector.js），因此 uxlint --version 可确定具体使用的捕获 代码，服务器无法在运行时注入任何内容。它捕获的内容仅包括页面几何信息、可见文本、 计算样式和截图。对于嵌入的 <iframe>，它只记录 src 的 主机名，绝不记录完整嵌入 URL，因为其查询字符串可能包含会话 ID 和令牌。它不会读取 你的源代码，也不会读取 uxlint.toml 以外的文件系统内容。它确实会读取少量项目来源 信息，并随报告发送： 你当前的 git commit sha 和分支名称（git rev-parse）、机器的主机名，以及在 GitHub Actions 中的仓库/PR/提交链接。设置 UXLINT_RUNNER 可覆盖主机名。
• 密钥和 PII 脱敏尽力而为，并非保证。 上传任何内容之前， 采集器会遮蔽捕获页面文本中看起来像令牌、API 密钥、密码或电子邮件地址的内容，并 从控制台日志和原生对话框消息中脱敏相同模式的内容。所有渠道共用一个模式列表 （assets/redact.js），因此不会出现规则不一致。截图会在捕获前额外处理一次：遮蔽每个 表单字段的值（密码字段清空，其他输入替换为圆点），并清除页面文本中符合模式的密钥， 以免输入的数据和显示的密钥出现在图像中。此处理会深入 Shadow DOM（包括通过 attachShadow 拦截器访问的封闭根节点）和同源 iframe；对于跨域 iframe，则会覆盖一个 不透明方框，因为无法对其像素进行脱敏。但脱敏基于模式，截图终究还是像素：任何未被 模式捕获的任意显示内容（例如页面上的客户姓名、订单数据）、拆分显示的值，以及绘制在 图像或 <canvas> 中的内容，仍可能泄露。通过 --header/--storage/--login-* 传入的凭据仅用于驱动你自己的浏览器，绝不会发送到 uxlint 服务器。

  由于报告会捕获页面 HTML、文本和截图，因此无法完全防止敏感内容泄露到报告中。请使用测试账号，而非真实账号或生产环境账号。 在本地开发时，只要数据仅用于本地开发，风险就很低。当你审计的网站需要身份验证，且其中包含真实机密或个人数据时，请在发送前检查将要发送的内容：使用 --dry-run 将准确的负载（页面文本、来源信息和截图）写入本地文件夹，并检查内容，而不上传。脱敏可以减少意外暴露，但不能构成安全边界；你仍需对指定给 uxlint 的内容负责。

• 仅出于必要，对导航文本中的机密进行清理。 控件标签、菜单和 <select> 选项，以及工作区／组织切换器名称，都会经过同一套机密匹配规则处理，但不会针对名称或其他任意内容进行脱敏。原因在于目标遍历：审计会通过大模型驱动页面，而大模型会准确读取这些文本，以找到正确的控件、操作控件，并将所选内容与 DOM 匹配。对这些文本进行屏蔽会妨碍遍历，因为判定器将无法区分不同选项，也无法点击它选中的选项。因此，审计导航所需的标签会保持可读；其中包含的真实姓名，则由上述测试账号规则而非脱敏措施来保护。这是一种有意的权衡：与屏蔽测试账号规则已经保护的文本相比，确保目标遍历正常运行更重要。
• 不进行遥测。 此二进制文件只会向你指定的主机发起出站请求：uxlint API 服务器（--server／UXLINT_SERVER，或默认的托管源站）、你要求它审计的网站，以及仅在你明确选择加入时发送的匿名规则反馈信号。它没有内置其他分析、崩溃报告或回传数据的目的地。
• 反馈需主动选择加入，默认关闭。 uxlint init 会询问一次；只有你同意时，它才会将 feedback = true 写入 uxlint.toml，你也可以随时将其关闭。
• 审计浏览器使用临时配置文件。 每次审计都会启动 Chrome，并使用全新的临时用户数据目录，因此日常浏览中的 Cookie、历史记录或扩展程序不会加载到受审计的会话中，进程退出后也不会保留任何内容。
• 登录凭据保留在本地。 uxlint auth login 会将令牌存储在 ~/.config/uxlint/credentials，权限为 0600。令牌绝不会被记录或打印（只有一个有意为之的例外：uxlint signup 会打印新生成的密钥，供你导出），也绝不会打包进报告。

这不能替代阅读源代码。源代码很简短，这正是发布它的原因。如果你发现实际情况与此说明不符，请提交一个 issue。

这个 CLI 不是什么

它的设计有意保持简单：导航、运行内置收集器、上传快照、打印报告。规则、阈值和判定模型不在此代码仓库中，也永远不会放在这里。它们才是真正的产品，并且只存在于服务器端。没有 uxlint 服务器可供连接时，此 CLI 的构建版本毫无用处（默认连接 https://uxlint.net 上的托管服务器，或你自己的服务器）。

许可证

Apache License 2.0（见 LICENSE）。阅读、审计、分叉、从源代码构建，或将其集成到自己的工具中——除常见的署名和专利条款外，不附加任何条件。

本项目此前采用 Business Source License，并将在 2030 年的变更日期转为 Apache-2.0；我们只是提前完成了这一转换。该许可证的限制——禁止基于此代码构建与之竞争的托管式“审计我的网站”服务——保护错了对象：真正有价值的是规则、经过校准的阈值和评判器，而它们都在服务端，不在这个代码库中。这里真正提供的是一个客户端；没有 uxlint 服务，它几乎毫无用处，而客户端恰恰应该易于安装、阅读和引入项目。

截至 v0.1.30（含）的版本均以 BUSL-1.1 发布；v0.1.31 及之后的版本均以 Apache-2.0 发布。