slop-eval

slop-eval

快速开始 • CLI 参考 • 库 API • MCP 服务 • 对比 • 常见问题

使用大模型评审器对 AI 生成的 UI 进行通用化程度评分，让 CI 检查能够捕捉到人类评审者一眼就会指出的同一个问题：“看起来和其他 AI 构建的应用都一样”。

npx slop-eval-cli score --screenshot ./preview.png --json

无需安装步骤：npx 会直接获取并运行已发布的 npm 包。更喜欢 Python？pip install slop-eval-cli 可获得相同的 CLI，它是对评分逻辑的真正独立移植版本。

两种发行版：npm 和 Python 均已上线

slop-eval-cli 已在 npm 和 PyPI（包名 slop_eval）上线。Python 版本是一个真正独立的实现，依据与 TypeScript 原版相同的评分标准和 Anthropic 评审提示词构建并测试（本次验证中测试通过率为 60/60）。Python 专属用法请参阅 python/README.md。

为什么要做这个工具，以及它不是什么

Nutlope 的 Hallmark 是一款热门的 AI 设计技能，拥有 21,000 多颗星；它有一个未解决的问题，一位用户直言：“全都是垃圾。”维护者将其关闭，标记为 NOT_PLANNED。此外，一位贡献者向 Hallmark 提交了一个标题为“为 Hallmark 输出添加评估驱动的质量测试框架”的 PR，截至本文撰写时，已开放约两个月但仍未合并。这两件事都确有其事，且截至本文撰写时均有记录。它们并不能证明需求很大，只能说明这一缺口确实存在，而且目前尚未得到解决。

slop-eval 并非这个领域的首款工具，也无意成为首款。附近已经有两款真正免费可用的工具：

• Impeccable（pbakaus/impeccable，拥有 54,000 多颗星，Apache 2.0）提供了一个 CLI，可识别 AI 生成 UI 的 59 种具体视觉特征（渐变色盘、玻璃拟态、侧边条纹边框、违反 WCAG 对比度要求等），默认全部启用且无需调用模型；单独的 impeccable critique 命令还可在此基础上增加可选的、基于大模型的评判。核心检测速度很快，因为默认检查都不需要模型。它早已超越了垃圾检测工具的范畴，发展成为适用于 Claude Code、Cursor 和 Codex 的完整设计语言技能，共有 23 条命令。
• aislop（MIT，拥有 500 多颗星）针对 AI 生成的代码（而非 UI），提供了确定性、基于规则的同类工具：覆盖 8 种语言的 50 多条正则表达式/AST 规则，运行时路径中不使用大模型，定位正是 CI 质量门禁。

两者都无法对 UI 进行全面、基于判断的评分，例如“这个布局是否有新意”“这个组件的选择是否经过深思熟虑”——这类判断很难用固定规则编码。这正是 slop-eval 所填补的缺口，它旨在与 Impeccable 等工具配合使用，而非取而代之。

特性

已直接根据此代码库中的代码进行验证：

• 三个评分维度，每项都必须有引用证据。 src/rubric/v1.json 对布局新颖性、视觉标识独特性和组件模式新颖性进行评分，每项 0–10 分。没有具体引用的发现会被视为错误，而非有效评分（参见 src/sources/RuleSource.ts）。
• 通过强制工具调用进行 LLM 评审，并返回结构化 JSON。 LLMJudgeSource 使用 tool_choice 锁定为 submit_slop_scores 架构，调用 Anthropic API；返回内容会可靠地保持为结构化 JSON，而不是需要用正则表达式拆解的聊天回复。
• 面向 CI 和 Agent 的 --json 模式。 每次运行都可以在 stdout 输出可解析的 { target, rubric, compositeScore, findings[], summary, disclaimer } 对象，无论成功还是出错，因此脚本或 Agent 无需检查不同的输出结构来查找错误字符串。
• 明确的退出码约定。 0 表示成功（未设置阈值，或分数达到或超过 --fail-below），1 表示成功但低于阈值，2 表示用法错误或不可恢复的失败。本次已直接通过构建后的 CLI 以及真实的 npm/PyPI 软件包进行验证；参见 CLI 参考。
• 基于内容哈希的缓存。 src/cache/judge-cache.ts 会对输入字节进行哈希；再次运行且输入未变时，会完全跳过 API 调用。这不仅能节省成本，也能保证正确性：未变更的 PR 不会因为 LLM 每次运行的结果有所差异而导致 CI 门禁反复变化。
• 可组合的 RuleSource 插件接口。 src/sources/RuleSource.ts 是每个评分来源都必须实现的接口。目前有一个实际来源（LLMJudgeSource）和一个文档化的占位实现（ScreenshotDiffSource；在存在真实标注语料前，会如实报告为 not_scored），因此未来可以添加规则目录或第二个 LLM 提供商，而无需改动综合评分器。
• 截图输入（真实视觉分析）或 --url 后备方案。 --screenshot 会将实际渲染的图像发送给评审器。--url 是文档所述的 v0.1 限制：未捆绑无头浏览器，因此它会获取原始 HTML/文本，由评审器根据标记和文案进行判断，而非根据布局进行判断。
• GitHub Action 优先展示具体标记，再展示分数。 action/action.yml 会发布一条 PR 评论，先列出最具体的单项标记发现，再列出综合分数，让评审者了解评分依据。
• 版本化的公开评分标准。 每个分数都会注明生成该分数的评分标准版本（当前为 v1）。评分标准变更会作为新文件发布，不会悄悄修改现有文件。
• 提供真实的、适用于 Agent 的 CLI 配套库 API。 两种发行版本都导出了编程入口（Python 中的 score_composite 及相关接口，TypeScript 中的 runScore/scoreComposite），因此 Agent 框架可以在进程内调用 slop-eval，而无需通过 shell 调用。参见 库 API。

快速入门

需要 Node.js 18+（npm）或 Python 3.9+（PyPI），以及 ANTHROPIC_API_KEY（自带密钥；可在 console.anthropic.com 获取）。

最快的方式是使用本 README 顶部的单行命令，无需本地克隆或构建：

npx slop-eval-cli score --screenshot ./preview.png --json

本次已使用真实 PNG ./preview.png，并在未设置 ANTHROPIC_API_KEY 的情况下，通过实际发布的 npm 软件包进行验证：

$ npx --yes slop-eval-cli@latest score --screenshot ./preview.png --json
{
  "error": "ANTHROPIC_API_KEY environment variable is not set.\nslop-eval calls the Anthropic API to run the LLM judge, and is BYO-key (bring your own key) -- there is no default or shared key baked into this tool. Set your key and try again:\n\n  export ANTHROPIC_API_KEY=\"sk-ant-...\"\n\nGet a key at https://console.anthropic.com/"
}
# exit code 2

若要改为从源代码构建：

git clone https://github.com/RudrenduPaul/slop-eval.git
cd slop-eval
npm install
npm run build

export ANTHROPIC_API_KEY="sk-ant-..."
./dist/cli.js score --screenshot ./test/fixtures/sample.png

供 CI 或 Agent 使用时，请添加 --json。--json 始终会在 stdout 输出有效的 JSON 对象，无论成功还是出错；--url/--screenshot 互斥检查就是一个真实用法错误示例，可确保其输出可解析：

./dist/cli.js score --screenshot ./test/fixtures/sample.png --json

{
  "target": "./test/fixtures/sample.png",
  "rubric": "v1",
  "compositeScore": 62,
  "findings": [
    {
      "ruleId": "llm-judge.layout-novelty",
      "category": "Layout novelty",
      "score": 4,
      "evidence": "Matches a common hero + 3-card grid + footer CTA pattern.",
      "status": "flag"
    }
  ],
  "summary": { "pass": 1, "flagged": 1, "notScored": 1 },
  "disclaimer": "This score is a heuristic quality signal from an LLM judge, not a certification..."
}

CLI 参考

本次会话从构建后的 CLI 中直接通过 ./dist/cli.js score --help 捕获，逐字如下：

Usage: slop-eval score [options]

Score a URL or screenshot for AI-UI genericness against a versioned rubric.

Note on --url mode (v0.1 limitation): this tool does not bundle a headless
browser. If --url is given, the raw HTML/text response is fetched and given to
the judge as a fallback input, instead of a rendered screenshot -- the judge
can reason about markup and copy, but not the actual visual layout. For the
stronger, layout-aware signal, render the page yourself and pass --screenshot.

Options:
  --url <url>          URL to score (fetched as raw HTML/text -- see
                        limitation note above)
  --screenshot <path>  path to a screenshot image to score (preferred over
                        --url)
  --rubric <name>       rubric version to use, reads src/rubric/<name>.json
                        (default: "v1")
  --json                output structured JSON instead of a human-readable
                        report (default: false)
  --fail-below <n>      exit code 1 if the composite score is below this
                        threshold (0-100); no threshold by default
  -h, --help             display help for command

退出码：0 表示成功（未设置阈值，或分数达到或高于 --fail-below）；1 表示成功但低于阈值；2 表示用法错误或不可恢复的故障（缺少 API 密钥、文件无法读取、评分标准格式错误、--url/--screenshot 互斥）。

--url 和 --screenshot 互斥；两者同时传入或都不传入，都会在任一输出模式下构成用法错误（退出码为 2）。本次会话已直接通过构建后的 CLI 验证这两种情况。

说明

--url 是 v0.1 的一项有意限制：不附带无头浏览器。它会获取原始 HTML/文本，并将其作为文本回退方案交给评判器，让评判器根据标记和文案进行推理，而非依据渲染后的布局。--screenshot 提供的信号更强；请自行渲染页面（使用 Playwright、Puppeteer 或 CI 中现有的预览截图步骤），然后传入图像。

Python CLI（通过 pip install slop-eval-cli 安装的控制台脚本 slop-eval）提供完全相同的标志集和退出码约定；本次会话已通过其自身的 --help 输出确认。

库 API

两个发行版本除了 CLI 外，都提供了真正且有文档说明的编程入口。Agent 框架或 CI 脚本可在进程内调用此接口，无需通过 shell 调用。

Python（slop_eval/__init__.py）：

from slop_eval import score_composite, ScoreInput, LLMJudgeSource, ScreenshotDiffSource

sources = [LLMJudgeSource("v1"), ScreenshotDiffSource()]
result = score_composite(sources, ScoreInput(screenshot_path="./preview.png"))
print(result.composite_score, result.findings)

score_composite(sources: List[RuleSource], score_input: ScoreInput) -> CompositeResult 会按列表顺序运行每个 RuleSource，合并其发现结果，并返回一个包含 composite_score: float（0-100）和 findings: List[RuleFinding] 的 CompositeResult。此外还导出了：RuleFinding、RuleFindingStatus、RuleSource、Rubric、RubricCategory、load_rubric、build_json_report、render_human_report、print_report、print_error、MissingApiKeyError、RubricLoadError。

TypeScript（src/cli.ts，从包的 main/types 入口导出）：runScore(options: ScoreOptions, buildSources?) => Promise<number> 和 buildProgram(): Command 是两个导出入口，同时还导出了 ScoreOptions 接口。scoreComposite（来自 src/scorer/composite.ts）是 CLI 在内部调用的同一个复合评分函数。提供这些接口主要是为了让测试套件能在进程内驱动 CLI；两个库中，Python 包的 __init__.py 才是更有意面向 Agent 的库接口。

MCP 服务

slop-eval 提供 Model Context Protocol 服务，因此兼容 MCP 的 Agent（Claude Desktop、Claude Code、Cursor、编排器）可以直接将 slop-eval 作为工具调用，而无需通过 shell 调用 CLI 并自行解析标准输出。

pip install "slop-eval-cli[mcp]"

Claude Desktop 配置：

{
  "mcpServers": {
    "slop-eval": {
      "command": "slop-eval-mcp",
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

该服务提供一个工具 run(args: list[str]) -> dict，作为 CLI 的通用封装：传入与命令行相同的 argv（不包含开头的 slop-eval），它会返回 CLI 解析后的 JSON 输出；如果退出码非零、发生超时或子进程故障，则会返回结构化的 {"error": ...} 字典——工具调用本身绝不会抛出异常。示例：

run(["score", "--screenshot", "./preview.png", "--json"])
# -> {"result": {"target": "./preview.png", "rubric": "v1", "compositeScore": 62.0, "findings": [...], ...}}

使用 slop-eval-mcp 直接启动（stdio 传输）。基础包需要 Python 3.9+；mcp 附加组件本身需要 mcp>=2.0.0。

GitHub Action

- uses: RudrenduPaul/slop-eval/action@main
  with:
    url: ${{ steps.deploy.outputs.preview_url }}
    fail-below: 50
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

它会发布 PR 评论，先列出最具体的标记发现，再列出复合分数。调用它的工作流需要设置 permissions: pull-requests: write。完整的输入/输出参考见 action/README.md。

坦诚对比

	slop-eval	Impeccable	aislop
目标	AI 生成的 UI	AI 生成的 UI	AI 生成的 代码
检测方式	LLM 评审（综合评估）	确定性规则，默认 59 项检查；单独的 critique 命令会额外添加可选的 LLM 评判	确定性规则（50 多项检查）
是否需要 API 密钥	是（自带 Anthropic 密钥）	默认的 59 项确定性检查不需要	不需要
速度	按设计较慢，实际模型调用处于关键路径中	确定性检查几乎即时完成	亚秒级，无网络调用
可组合的规则来源	是，提供 RuleSource 插件接口	否（规则集固定）	否（规则集固定）
GitHub 星标数	新项目（本仓库）	54,000+	500+
许可证	Apache 2.0	Apache 2.0	MIT
CI 门禁模式	GitHub Action，使用 --fail-below 阈值	主要定位并非 CI 产品	是，CI 质量门禁

想要快速、确定性、零成本地检查已知的 AI UI 特征？目前更适合的是 Impeccable 的工具；从星标数和覆盖范围来看，它也远比本项目成熟。若要综合判断布局和组件是否新颖，而这些很难通过固定规则集来编码，slop-eval 正是为此而生。你也可以在同一 CI 任务中同时运行两者。

关于速度： slop-eval 确实比 Impeccable 的核心检查和 aislop 慢，因为 LLM 调用处于关键路径中。以下是在本次会话中，从全新克隆和构建的项目实测得到的 CLI 开销数据（--help 和错误路径，不含评分调用）：

命令	实测耗时
slop-eval score --help	~0.05s
slop-eval score --screenshot <x>（没有 API 密钥，快速失败，仅读取本地文件）	~0.05s
slop-eval score --url <x>（没有 API 密钥，快速失败）	0.18s-0.91s，因该路径会在检查密钥前获取 URL，所以耗时随网络延迟而异

实际评分运行的延迟（真实 LLM 评审调用，区分首次运行和缓存命中）需要有效的 ANTHROPIC_API_KEY，但当前环境没有。因此，以下两个数字都是待实测的目标值：首次运行低于 10 秒；相同输入命中缓存时低于 1 秒。缓存命中的数字由 src/cache/judge-cache.ts 中的内容哈希缓存逻辑保证；首次运行的数字则是估算值。我们宁愿将目标如实标为目标，也不愿声称一个无法复现的数字。

分数意味着什么（以及不意味着什么）

slop-eval 的分数是一个启发式质量信号，来源于一个 LLM 根据明确的评分标准对你的 UI 进行评估。它并不能认证某个内容是否由 AI 生成；分数良好也不代表 UI 在各方面都很好，只能说明在当前版本下，这套评分标准没有标记它。

评分标准公开且有版本记录

每个分数都根据 src/rubric/v1.json 这个真实的版本化文件进行评定，你可以直接打开并阅读。阅读它、提出修改建议，或使用 --rubric 固定到特定版本。评分标准版本绝不会原地修改；每次变更都会以新文件的形式发布，因此历史分数始终记录了生成它时所用的评分标准版本。

路线图

• v0.1（本次发布）： LLM 评审评分、CLI、GitHub Action、内容哈希缓存、--json 模式，以及两个发行包中的库 API。
• v0.2： 有了真实的带标签语料库后，ScreenshotDiffSource 才会成为实际功能。添加 Impeccable 目录适配器，待完成许可证检查后发布。添加显式的 rescore --rubric v2 命令，确保评分标准升级绝不会悄无声息。

安全

ANTHROPIC_API_KEY 仅从环境变量中读取，绝不会记录到日志，也不会写入内容哈希缓存。完整政策和私下披露流程请参阅 SECURITY.md。

常见问题

slop-eval 是什么？它与 linter 有何不同？ 它是一个 CLI、GitHub Action 和库，用 Anthropic 大模型评审员依据有版本管理的评分标准（src/rubric/v1.json）为 AI 生成的 UI 评分，衡量其是否缺乏新意（“slop”），而不是使用一组固定的确定性模式检查。它旨在发现人类评审员一眼就能看出的“这看起来和其他 AI 构建的应用没什么两样”，并可与确定性 linter 一起在同一 CI 任务或 Agent 循环中运行。

我需要 API 密钥吗？ 需要。slop-eval 要求你自备 Anthropic API 密钥；它不提供共享密钥或托管密钥。除 Anthropic API 外，不会向任何地方发送数据。

如何安装？它支持哪些平台？ 有两种独立的发行版本，本次会话中均已验证可安装并运行。npm：使用 npx slop-eval-cli score ...（无需安装），或运行 npm install -g slop-eval-cli，要求 Node.js 18+（参见 package.json 中的 engines）。PyPI：运行 pip install slop-eval-cli，要求 Python 3.9-3.13（参见 python/pyproject.toml 中的分类器）。这两个包都没有原生二进制文件，也不需要针对特定平台的构建步骤，因此在 macOS、Linux 和 Windows 上的安装方式相同。

slop-eval 与 Impeccable 具体有何不同？ 完整对比请参见上方的客观对比表。简而言之：Impeccable 的核心是 59 项确定性检查，默认全部启用，无需 API 密钥且几乎瞬间完成；该项目本身也已发展为规模大得多的设计语言技能（54,000+ 星标、23 个命令），不再局限于检测 slop；另有一个独立的 critique 命令，在确定性检查之外增加大模型评审。slop-eval 则只调用一次大模型评审员，需要自备 Anthropic 密钥，而且按设计速度较慢，因为关键流程中包含实际的大模型调用；作为交换，它能对整体布局和组件进行判断，而这类判断很难用固定规则表达。两者的设计目标是在同一 CI 任务中协同运行。

我可以使用其他模型提供商（OpenAI、Gemini）吗？ v0.1 中还不可以。LLMJudgeSource 直接调用 Anthropic API；ANTHROPIC_MODEL 只能让你选择其他 Anthropic 模型。以后可通过 RuleSource 接口自然地接入可插拔的提供商，但目前尚未实现，因此不要把“可组合规则源”理解为现在就支持“多提供商”。

--url 会像浏览器一样渲染页面吗？如果评分失败怎么办？ v0.1 中不会。--url 会获取原始 HTML/文本响应，并将其作为备用内容交给评审员；若要进行真实的视觉评估，请自行渲染页面并传入 --screenshot。对于一般的失败情况：所有错误路径（包括缺少 ANTHROPIC_API_KEY）都会以代码 2 退出并打印清晰的消息（在 --json 模式下会输出 JSON {"error": ...} 对象），因此运行失败时总能明确告知你需要修复什么。

在同一个 PR 上重新运行 slop-eval，会导致 CI 检查结果反复变化吗？ 不会。相同输入（相同的截图字节，或相同的 URL 加获取到的内容）会命中 src/cache/judge-cache.ts 中的内容哈希缓存，不会再次调用 API，因此相同输入始终会返回相同的缓存结果。

screenshot-diff-vs-corpus 目前是真正的检查吗？ 不是。它在代码中确实是一个真正的 RuleSource 实现，但 v0.1 将其作为诚实的 not_scored 占位项发布，因为目前还没有标注过的对比语料库。手动塞入未经验证的语料库，不如直接报告“未评分”来得诚实。基于语料库的差异比较计划在 v0.2 推出。

我可以将 slop-eval 用于商业用途吗，包括用于闭源产品？ 可以。两个发行版本均采用 Apache 2.0 许可证（LICENSE、python/LICENSE）。该宽松许可证允许商业使用、修改和闭源再分发，并明确授予专利许可。从闭源项目中调用 CLI、Action 或库，不会要求你公开任何内容；再分发 slop-eval 自身代码副本时，只需附上许可证和版权声明。

贡献

欢迎提交 Issue 和 PR，请参阅 CONTRIBUTING.md（涵盖 npm 和 Python 包，以及各包的覆盖率要求）。新增 RuleSource 实现是最具价值的贡献：插件接口的设计目的，正是让新增检测方法时无需修改复合评分器。

许可证

Apache 2.0。请参阅 LICENSE。