polish

polish 是一个自托管的 UI 代码审查 CLI 和 MCP 服务器。它从 0-100 分对可用性、设计工艺、可访问性和界面文案进行评分，并提供文件级发现和具体修复建议。在本地运行，接入你自己的 API 密钥，让审查循环留在你的工作流内。

专为审查真实 UI 代码的设计师和工程师打造。

在线体验：https://tomiabe.github.io/polish/

为什么

托管的设计审查工具很有用，但它们受配额和月度限制约束。polish 将审查循环保持在本地，使用你自己的 API 密钥和一个小型 Node CLI。把它指向你的 UI 文件，它会按照评分标准将文件发送给 LLM，然后返回一个分数以及带有严重程度、类别、file:line 和具体修复建议的发现。

Related MCP server: @gridwork/siteaudit

功能

• 按分层评分标准审查：可用性启发式、设计工艺、界面文案和可访问性。它检查标题、描述、标签和辅助文本，同时检查视觉和交互代码。评分标准是纯数据，因此可以替换为任何设计理念。

• Polish 加权评分。严重发现扣 22 分，重大发现扣 9 分，中等发现扣 3 分。没有严重程度上限。

• 支持 Groq、OpenAI、Anthropic、Gemini 和 OpenRouter 提供商，以及通过 baseUrl 支持任何兼容 OpenAI 的端点。

• 可选的提供商回退链，因此你可以按顺序尝试多个 API。

• 一个引擎同时驱动 CLI 和 MCP 服务器，因此终端用户和 AI 代理获得完全相同的结果。

• polish init-agent 写入一个安全的、仓库本地的 AGENTS.md，教导编码代理何时审查 UI 变更、如何识别回执，以及如何验证修复。

• 验证模式以远低于完整审查的成本重新检查先前发现与更新后的文件，并返回一个新的剩余问题分数。

• 当存在严重发现时以退出码 1 退出，因此它可以作为 pre-commit 或 CI 门禁使用。

安装

git clone https://github.com/tomiabe/polish.git
cd polish
npm link          # makes `polish` available in every project

在 shell 配置文件中设置一个 API 密钥：

export GROQ_API_KEY=...        # or:
export OPENAI_API_KEY=...      # or:
export ANTHROPIC_API_KEY=...   # or:
export GEMINI_API_KEY=...      # or:
export OPENROUTER_API_KEY=...

用法

polish                                   # audit files matched by config globs
polish src/components src/pages/*.tsx    # audit specific files or directories
polish --verify findings.json           # re-check that previous findings are fixed
polish --dry-run                        # preview what would be sent, no API call
polish --json                           # machine-readable receipt + findings, for CI or agents
polish init-agent                       # add the Polish workflow to AGENTS.md

配置

在项目根目录创建 .polish.json。所有内容都是可选的：

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "providers": ["gemini", "groq"],
  "include": ["src/**/*.{ts,tsx,css}"],
  "exclude": ["src/generated/**"],
  "rubric": ["usability", "craft", "accessibility"],
  "maxFiles": 20,
  "maxFileBytes": 100000
}

• provider - openai、anthropic、openrouter、groq 或 gemini。根据存在的环境变量密钥自动检测。

• providers - 有序的回退列表。如果设置，polish 会按顺序尝试每个提供商，直到一个成功。

• model - 默认值为 gpt-4o-mini、claude-sonnet-4-20250514、openai/gpt-4o-mini（OpenRouter）、llama-3.3-70b-versatile（Groq）和 gemini-2.5-flash。

• baseUrl - 覆盖 API 端点，用于代理或自托管网关。

• include / exclude - 使用 **、*、? 和 {a,b} 的 glob 模式。node_modules 和 .git 始终被跳过。

• rubric - 使用哪些评分标准层。usability（核心启发式）、craft（排版、颜色、间距、动效、组件、文案）、accessibility（对比度、键盘、语义、表单、触摸目标、减少动效）。默认全部开启；在大型审查中选择子集以降低 token 成本。

• maxFiles / maxFileBytes - 安全上限，防止大文件超出 token 预算。每次运行都会打印其估算的 token 数量。

评分标准及其定制

默认评分标准有三层：

• usability - 10 条核心启发式：系统状态可见性、与现实世界的匹配、用户控制与自由、一致性与标准、错误预防、识别而非回忆、灵活性与效率、美学与极简设计、错误诊断与恢复、帮助与文档。

• craft - 设计系统纪律：视觉工艺（同心圆角、光学对齐、无魔法数字、无通用 AI 默认样式）、颜色与 token、排版、间距与布局、动效、组件组合和文案。

• accessibility - 可检查的要求：对比度、键盘支持、语义元素、表单、触摸目标和减少动效。

评分标准是一个数据结构。要用你自己的理念替换它，在 .polish.json 中放入一个 principles 数组：

{
  "principles": [
    {
      "id": "D1",
      "name": "Your design principles",
      "rules": [
        "A concrete rule the model can verify in code",
        "Another concrete rule"
      ]
    }
  ]
}

规则最好表述为模型可以检查的事项（"按钮显示加载状态"），而不是美学感受。

评分

• 从 100 分开始。每个发现根据 Polish 权重扣分：严重 -22，重大 -9，中等 -3。

• 分数永远不会低于 0。

每次审查运行还会发出一个回执，包含 polishApplied: true、运行 id、分数和审查的文件。在人类可读模式下，polish 在分数之前打印该回执。在 --json 模式下，代理无需解析纯文本输出即可读取相同的回执。

验证模式

polish > findings.json
# fix the issues
polish --verify findings.json

验证模式仅针对当前文件内容重新运行被标记的发现，并为每个发现报告 FIXED 或 STILL PRESENT。 它还会根据剩余的发现发出一个新分数，以及与完整审查相同的回执结构。 添加 --json 以获取验证分数、回执和状态作为机器可读的 JSON。

MCP 服务器

polish 也可以作为基于 stdio 的 MCP 服务器运行，因此 AI 代理可以将其作为工具调用。它暴露：

• polish_review_files - 按内容审查 UI 文件，返回分数、回执和发现

• polish_verify_fixes - 根据更新后的内容重新检查发现，返回新分数、回执和状态

• polish_usage - 使用状态，始终无限制且自托管

在任何支持 MCP 的客户端中注册它。对于 opencode，在 ~/.config/opencode/opencode.json 中：

{
  "mcp": {
    "polish": {
      "type": "local",
      "command": ["node", "/absolute/path/to/polish/mcp-server.js"],
      "enabled": true,
      "environment": {
        "GROQ_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop 读取 ~/Library/Application Support/Claude/claude_desktop_config.json，Codex 读取 ~/.codex/config.toml。在这三个中，使用 node 的绝对路径（例如 /usr/local/bin/node），因为 GUI 应用不会继承你的 shell PATH，并在服务器的环境中传递 API 密钥，因为 GUI 应用不会加载你的 shell 配置。

代理说明

注册 MCP 服务器后，从项目根目录运行 polish init-agent。它会创建包含 UI 变更审查循环的 AGENTS.md。除非你传入 --force，否则该命令拒绝替换现有文件。

开发

npm test          # node --test: unit tests plus a mock-server end-to-end test
node scripts/demo.mjs            # before/after demo, no API key needed
node scripts/mcp-handshake.mjs   # manual MCP handshake test

演示

node scripts/demo.mjs 针对一个模拟的 OpenAI 兼容服务器运行完整流水线（配置、提示词、LLM 调用、评分、验证），因此无需 API 密钥。它审查 demo/ProfileCard.before.jsx（一个存在可访问性阻塞和设计系统泄漏的组件），然后审查其修复后的孪生组件 demo/ProfileCard.after.jsx（以及其样式表 demo/profile.css），最后验证 before 中的发现是否在 after 代码中得到解决。模拟是确定性的：预期从 39/100 到 97/100，且 8/8 个发现已修复。

设置 API 密钥后，相同的命令会针对实时模型运行，结论是真实的。在 Groq（llama-3.3-70b-versatile）上录制的实时运行将卡片演示评分为 before 62/100 和 after 78/100，表单演示为 before 43/100 和 after 66/100。结论因模型和运行而异，因此请使用实时运行来评判你自己的代码：

polish demo/ProfileCard.before.jsx
polish demo/ProfileCard.after.jsx demo/profile.css
polish demo/SettingsForm.before.jsx
polish demo/SettingsForm.after.jsx demo/settings-form.css

文件

bin/polish.js        CLI entry, output rendering, exit codes
mcp-server.js        MCP server (stdio) wrapping the review engine
lib/rubric.js        default rubric layers (usability, craft, accessibility), swap for your own
lib/config.js        config loading, glob expansion, defaults
lib/llm.js           LLM provider callers and JSON extraction
lib/prompt.js        review and verify prompt builders
lib/review.js        shared review and verify engine, used by CLI and MCP
lib/agent.js         repo-local instructions for coding agents
lib/scoring.js       weighted scoring and summaries
demo/                before/after demo components (ProfileCard, SettingsForm)
test/                unit and integration tests
scripts/             manual test scripts

关于 token 成本的说明

polish 将完整的、带行号的文件内容发送给模型。每次运行前都会打印估算的 token 数量。保持 maxFiles 和 maxFileBytes 紧凑，并审查变更中触及的界面，而不是整个仓库。