Mantis

Mantis

能看见 12 个色彩通道。你能看见 3 个。你的编码 Agent 一个也看不见。

English · Tiếng Việt · 简体中文

_{▶ 观看 60 秒介绍视频（MP4，4 MB） · 1080p}

---

你的编码 Agent 闭着眼睛构建 UI。它写好 CSS，说声 “完成 ✅”，却从不打开浏览器。

然后有人用手机打开页面：

• 菜单跑到了屏幕外；
• 暗色模式下，有张卡片还是白色，卡片上却是白字；
• 越南语按钮标签被截掉了一半。

**Mantis 能发现 Agent 看不见的 UI 错误，以及它藏起来的错误。**它会：

1. 打开实际应用；
2. 检查所有屏幕尺寸、两种主题，以及你提供的每种语言；
3. 用红框标出问题；
4. 从根本上修复问题，并指出那些只是藏起错误的“修复”；
5. 用修复前后的截图证明结果；
6. 测量应用在慢速手机上的运行速度，为修复排定优先级，并识别那些只是删除内容的提速方式（从 v0.6 起）。

它能发现的问题

问题	你会看到什么	Agent 为什么会漏掉
页面溢出	手机页面可以横向滚动	它们只会想象桌面布局
文本被截断	“Đăng ký nhận bản ti…”	它们只用简短的英文文本测试
从右向左排版错误	阿拉伯语从左向右排列，左侧内容被截断	它们从不将页面切换为 dir="rtl"
元素重叠	徽标压在按钮上	绝对定位在某个宽度下看起来没问题
对比度	灰色文字几乎看不清	颜色只在代码中选定，从未实际看过
暗色模式样式泄漏	暗色页面里有一张白色卡片	主题无法覆盖硬编码的 #fff
点击目标太小	手机上的图标按钮只有 16px	鼠标操作精准，拇指却不是
控制台错误、图片损坏	红色错误提示、空白框	没人打开 DevTools
布局偏移	阅读时内容突然跳动	在 localhost 上，所有内容都会瞬间加载
样式值偏离规范	蓝色比品牌色偏了一个色阶，16px 圆角中混入了 15px 圆角	它们直接硬编码数值，而不是使用你的设计令牌
页面加载缓慢（mantis perf）	手机上要等 5 s、API 调用串行执行、聊天小组件拖慢页面	笔记本上的 localhost 运行很快

工作原理

1. 检查。 /mantis 会在真实浏览器中遍历每个屏幕 × 主题 × 语言运行应用，并生成一份报告供 Agent 查看，其中包含带注释的截图。
2. 修复。 /mantis-fix 修复根本原因，而非表面症状。它绝不会在 body 上设置 overflow-x: hidden、把文字缩小到刚好适配，或关闭深色模式；下一次运行也会检查这些情况。
3. 证明。 /mantis-proof 会生成修复前后对比图、一张已修复问题的特写图，还可选择生成视频，供你用于拉取请求。
4. 提速。 /mantis-perf 会模拟慢速 4G 手机测量页面，按影响和风险排序修复减慢页面的问题，并检查页面是否真的变快，而不是内容变少（见下文）。

mantis look http://localhost:3000 --routes /,/settings --locales en,vi

每个语言单元都会设置浏览器区域设置和 Accept-Language。许多应用会通过其他方式选择语言，可使用 --locale-strategy 处理（自 v0.5 起）：

应用切换语言的方式	参数
URL 前缀，例如 /vi/settings	--locale-strategy path:/{locale}
查询参数	--locale-strategy query:lang
Cookie（next-intl、Rails）	--locale-strategy cookie:NEXT_LOCALE
localStorage（i18next）	--locale-strategy storage:i18nextLng

如果某种语言的页面文字与第一种语言完全相同，就会报告为“未本地化”。这通常表示策略有误。

还没有翻译？ 添加伪区域设置（自 v0.5 起）：--locales en,pseudo。该单元会加载第一种语言，并按翻译文本变长的方式改写所有可见字符串。“Subscribe”会变成 [Šûƀƀšççŕîîƀéé]：带重音符号、长度约增加 40%，并用方括号括起来，因此如果缺少 ]，就能看出末尾被截断。应用之后渲染的文字也会被改写。代码、表单输入和 translate="no" 内容不会改动。伪区域设置能找出因文字变长而出现问题的布局，但无法判断哪些字符串是硬编码的，因为它会改写所有字符串。

从右向左。 阿拉伯语、希伯来语、波斯语和乌尔都语页面从右侧开始，向左溢出。Mantis 会以镜像方式进行同样的检查。如果这类页面从左向右布局，还会在缺少 dir="rtl" 时报告错误。若要查看不支持这些语言的应用如何应对，可使用 --locales en,pseudo-rtl：伪区域设置会从右向左布局（自 v0.5 起）。

是修好了，还是只是藏起来了？

如果要求 Agent 清理报告，它可以在什么都没修的情况下让报告变干净。每次 mantis look 都会与同一 URL 的上一次运行结果比较，因此这些伎俩行不通：

伎俩	Mantis 报告的内容
在 html、body 或应用根元素上设置 overflow-x: hidden	溢出问题仍会报告：被截断的元素，以及隐藏它的规则
隐藏出问题的元素（display: none、visibility: hidden、opacity: 0）	cover-up：问题消失了，但元素也不见了
隐藏重叠中的另一个元素	在该元素上报告 cover-up
将文字缩小到刚好适配	cover-up：16px → 7px
裁剪内容或缩短文字	cover-up：可见内容变少或字符数减少
按钮、链接或标题悄然消失	lost 警告

掩盖问题会被视为错误，因此运行仍会失败。诚实修复问题后，运行结束时会生成一份凭证：

Mantis: 0 errors, 0 warnings in 24 cells
  vs 2026-10-29T11-51-22: 18 fixed · 0 new · 0 cover-ups · 0 lost

更快了，还是内容更少了？（mantis perf，自 v0.6 起）

让 Agent 加快页面速度，它可能会移除主视觉图片、把列表缩减到五行，或对首屏显示的内容启用延迟加载。数字变好了，页面却变差了。mantis perf 会测量页面，精确指出导致页面变慢的代码，按影响和风险排列修复项；如果所谓的“提速”只是移除了内容，它就会让运行失败。

mantis perf http://localhost:4173 --routes /,/pricing

像用手机一样测量。 每条路由都会在 Chromium 中冷启动访问 N 次（默认 --runs 5）。 默认配置模拟中档手机在慢速 4G 网络下的情况：CPU 慢 4 倍，往返时延 562 ms。--profile desktop 会关闭限速。你会得到 LCP、FCP、TBT、CLS、TTFB、API 数据就绪时间、字节数和请求数的中位数及分布范围。报告会标明开发服务器，因为它的数据并不代表用户实际体验。

还会额外进行一次不限速访问，因为限速会掩盖它影响的内容：

• 服务器每个请求的实际等待时间；
• CPU 性能分析，列出主线程耗时所在的函数；
• 从未运行过的代码覆盖率。

指出修复项并排序。 perf.md 会先列出修复项：

类别	含义
优先处理	值得修复，风险低
计划处理	值得修复，但需要谨慎处理
可选优化	收益较小
由你决定	产品决策，例如移除某个供应商

每项修复都会指出 Agent 可以打开查看的问题源。这可能是选择器、URL，或包含函数及其调用方的 file:line（loadConfig /app.js:4 ← main /app.js:51）。它还会说明修复影响的指标、预估收益及该估算的可信度，并提供检测到的框架对应的修复方式（Next.js、Nuxt、Angular、Vue、React、SvelteKit）。它可以找出：

• 延迟加载或较晚才被发现的 LCP 图片；
• 尺寸远大于实际显示尺寸的图片；
• 阻碍首次绘制的 <head> 文件；
• 占用主线程的函数；
• 从未运行的代码；
• 隐藏文本的字体；
• 布局偏移及其成因（图片未指定尺寸、在上方插入横幅、列表内容延迟填充）；
• 响应缓慢的 HTML。

缓慢的 API。 每个 API 调用都会追踪到发起它的代码。Mantis 可以找出：

• 服务器端响应缓慢的端点；
• 彼此等待的调用；
• 重复进行的相同调用；
• 每个条目都发起一次调用的情况（N+1）；
• 体积过大的 JSON；
• 开始过晚的首次调用，以及它等待的脚本。

第三方服务。 按供应商分组（Google Analytics、Intercom、YouTube、Stripe 等约 50 家），列出其字节数、主线程耗时、阻塞渲染的文件和 iframe。针对每种类型提供修复方式：为聊天和视频使用外观替代组件、等页面可交互后再加载分析工具、自托管字体。成本高昂的供应商是否值得保留，则列在“由你决定”下。

值得信赖的检测记录。 修复后再次运行，它会将结果与相同 URL 和配置的上一次运行进行比较：

vs 2026-10-30T12-32-02: LCP 2.5 s → 36 ms · TBT 121 ms → 0 ms · CLS 0.164 → 0 · transferred 551 KB → 354 KB · 11 fixed · 0 new · 0 cover-ups

只有超出噪声范围的变化才会计入，噪声范围即两次运行的分布范围。其他情况都会显示为 ≈。如果某条路由的 LCP 图片、文本、首屏图片、标题或控件消失后，页面因此变快，就会判定为掩饰问题错误：“更快了，还是内容更少了？”。随内容一起消失的发现项不会计为已修复。

这就是 Lighthouse 吗？ Lighthouse 会为页面评分。mantis perf 专为 Agent 工作循环打造：

• 精确定位到函数和调用栈的问题源；
• 同时按风险和影响排列修复项；
• 提供 API 和供应商问题及其修复方式；
• 基于多次冷启动运行计算中位数；
• 提供前后对比记录，不会把移除内容算作提速。

数字

目前的测量结果：

• 植入的缺陷。 fixtures/buggy-app 中植入了 13 个 UI 缺陷，详见 PLANTED.json。Mantis 会在植入缺陷的 对应屏幕、主题和语言组合中逐一报告，除此之外不会报告其他问题。对于 fixtures/clean-app，也就是修复了所有缺陷的同一应用，它报告的问题数为 0。这两项检查都在 CI 中运行。

• 掩盖行为。 在 buggy-app 的同一 URL 下使用了四种伎俩（用 overflow-x: hidden 隐藏溢出内容、隐藏菜单按钮、隐藏被菜单按钮遮挡的按钮、 将标签缩小到 7px），这些情况仍会被报告或标记为掩盖行为。换成 clean-app 这个诚实修复后，所有问题都已修复，新增 0 个、掩盖行为 0 个、遗漏 0 个。这项检查也在 CI 中运行。

• 误报掩盖行为。 在 tailwindcss.com、vercel.com、notion.com 和 stripe.com 上连续运行两次，报告的掩盖行为为 0，遗漏的控件为 0。在新闻内容会在两次运行之间变化的 vnexpress.net 上，报告的掩盖行为为 0，并给出一条合并后的“遗漏”警告。检查日期：2026-10-29。

• 真实网站。 在 10 个公开网站（example.com、playwright.dev、Hacker News、 tailwindcss.com、MDN、svelte.dev、react.dev、gov.uk、vercel.com 和 stripe.com）上，报告的 21 个错误中有 18 个经人工检查后确认属实。 3 个误报都来自 tailwindcss.com 上的演示框架。检查日期：2026-10-26。

• 站点风格。 在 buggy-app 上，mantis learn 会准确列出其中植入的 3 个近似重复项：

  • 与 --muted 色差 ΔE 为 0.4 的颜色；
  • 在 14px 字号阶梯中使用的 13.6px 标签；
  • 与 --radius: 16px 相邻的 15px 圆角。

  在 clean-app 上，它不会发现任何此类问题。在 clean-app 中硬编码的四个近似副本（一个颜色、一个字号、一个圆角和一种字体）各会触发一条 off-style 警告；明显不同的新颜色则不会触发警告。这些检查在 CI 中运行。

• 误报风格偏离。 学习一个公开页面后立即再次检查，tailwindcss.com 和 vercel.com 上的 off-style 警告均为 0。stripe.com 有 2 条，linear.app 有 4 条，github.com 有 4 条。这 10 条都出现在实时产品演示或延迟加载的仓库网格中，这些内容会在每次加载之间变化。检查日期：2026-10-29。

Agent 基准测试

同一个 Agent（Claude Code、Opus 5.5 和 Haiku 5.5）在有无 Mantis 技能的情况下执行相同的 UI 任务，每个单元运行 3 次，并由一个从不使用 Mantis 检测器的隐藏 Playwright 评分器进行评分。所有内容都在 bench/ 中：测试方法、植入的缺陷、评分器、每个 Agent 的最终报告和差异、平局情况及失败项。

• Mantis 并未让 Opus 5.5 修复更多缺陷。 在两个小型应用上，结果持平（13 个中修复 13.0 个 vs 12.7 个，9 个中修复 9 个 vs 9 个）。在 Excalidraw 的一个分支上，使用 v0.3.1 时表现落后（7 个中修复 6.0 个 vs 6.7 个），使用 v0.4.0 时则领先（7 个中修复 7.0 个 vs 6.7 个）。这些修复是针对同一个分支调整的。
• 压力之下，它报告了隐藏缺陷。 当被要求“让 check:ui 通过，改动尽量小”时，两组都只修复了检查覆盖的问题。使用 Mantis 时，最终报告还列出了检查无法发现的缺陷：Opus、Atlas 组为 5 个中 3.7 个，而对照组为 1.7 个；Opus、Excalidraw、v0.4.0 组每次运行都报告了 4 个中的 4 个，而对照组为 0。
• Mantis 看不到时，Agent 也看不到。 使用无法测量画布对比度的 v0.3.1 时，使用 Mantis 的 Agent 修复 1.27:1 按钮的频率低于未使用 Mantis 的 Agent。
• 两组都没有 Agent 掩盖缺陷： 在 72 次评分运行中为 0。

为什么不用……？

浏览器 MCP 或截图脚本？ Playwright MCP、Chrome DevTools MCP 和 agent-browser 都能为 Agent 提供浏览器。但 Agent 仍然需要决定打开哪些页面，并凭肉眼判断每张截图。Mantis 基于 Playwright 构建，并补上了 Agent 会跳过的部分：

• 每次都检查相同的矩阵：手机、平板和桌面 × 浅色和深色 × 每种语言；
• 检测器会指出元素，并提供每项发现背后的测量数据；
• 与上次运行结果进行比较，抓出那些只是隐藏了 Bug 的修复。

在我们的基准测试中，不使用 Mantis 的 Opus 5.5 会编写自己的 Playwright 脚本，修复的 Bug 数量也大致相同。差别体现在压力之下：使用 Mantis 时，Agent 仍会告诉用户 CI 检查看不到什么。

ProofShot？ ProofShot 会将 Agent 的操作（视频、截图和错误）记录到一个可供你检查的证明包中。Mantis 会检查矩阵中是否存在特定类型的问题，并在修复只是隐藏了问题时让运行失败。一个回答“发生了什么？”，另一个回答“它坏了吗？真的修好了吗？”

Impeccable？ Impeccable 的 detect 会根据设计规则检查页面，避免 UI 看起来千篇一律。Mantis 会检查页面是否正常运行：没有溢出、每个标签在两种主题和每种语言下都清晰可读，而且修复确实有效。Impeccable 让界面更有品味；Mantis 则证明它没有问题。两者可以一起使用。

视觉回归工具（Percy、Chromatic、BackstopJS）？ 这些工具会将截图与已批准的基线进行比较，并要求人员审核每项更改。Mantis 首次运行时就能发现 Bug，无需基线，并指出问题及其位置。它仅在与上次运行结果比较时才会检查是否有人掩盖问题。

Mantis 没有自己的审美，它采用你的风格。

mantis learn 会打开正在运行的应用，并测量它实际使用的设计风格，无需事先编写设计规范：

• 每种主题中的颜色，以及对应的 CSS 变量；
• 字号、字体和字重；
• 圆角、间距、阴影和动效时长。

mantis learn http://localhost:3000 --routes /,/settings

它会为 Agent 写入 .mantis/style.json，为人员写入 style.md，并生成一张 style.png 图表。从此之后，look 会根据该风格检查每个页面。当页面出现以下情况时，它会发出 off-style 警告：

• 使用的颜色与某个标准颜色的 ΔE 小于 5，却不是标准颜色本身，例如硬编码复制了 --primary；
• 字号或圆角与标准值相差一两个像素；
• 使用了应用中其他地方都没有用到的字体。

与所有颜色都相差甚远的值会被忽略，因为新的插画颜色可能是有意为之。图表还会列出应用中已有的相似颜色。

/mantis-fix 会在编写 CSS 前读取 style.json，并复用标准值，而不是另行编造。

Mantis 会在 .mantis/ 中放入 .gitignore，这样报告、截图和保存的会话就不会被提交到 git 中。若要与团队共享标准风格，请主动提交：git add -f .mantis/style.json。

表单上的项目

联系表和证明中会显示项目名称，以及指向项目代码库的链接和二维码；这些信息从 package.json 和 git 远程仓库中读取。添加 .mantis.json 即可更改：

{ "name": "Lumen", "logo": "public/logo.svg", "brandColor": "#4f46e5", "repo": "acme/lumen", "qr": true }

需要登录的页面

为 Mantis 提供 Playwright 存储状态文件，打开的每个页面就会自动保持登录状态：

npx playwright codegen --save-storage=.mantis/auth.json http://localhost:3000/login   # sign in, close the window
mantis look http://localhost:3000 --routes /dashboard,/settings --storage-state .mantis/auth.json

如果应用只在 localStorage 中保存标记（例如已完成引导或演示会话），可以手动编写文件：

{ "cookies": [], "origins": [{ "origin": "http://localhost:3000", "localStorage": [{ "name": "onboarded", "value": "1" }] }] }

该文件包含有效会话，请勿将其提交到 git。在 .mantis/ 中无需额外操作：Mantis 已在那里写入 .gitignore。proof --video 也会读取相同的标记。只有使用同名存储状态文件的早前运行结果才会用于比较。

每次 pull request 时（GitHub Action，自 v0.7 起）

此 Action 会检查 pull request 的预览部署，并与线上站点进行比较，展示这次更改修复了什么、破坏了什么，或只是掩盖了什么。它会将结果作为 pull request 评论发布（每次推送都会更新），并显示在作业摘要中。表格和截图会作为构件上传。

使用会向 GitHub 报告预览部署的主机（Vercel、Netlify 等）：

name: Mantis
on: deployment_status
permissions:
  contents: read
  pull-requests: write
jobs:
  look:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: vulinh1704/[email protected]
        with:
          url: ${{ github.event.deployment_status.target_url }}
          baseline-url: https://your-app.com
          routes: /,/pricing,/settings
          locales: en,vi

或者在作业中构建并运行应用，并将 url 指向它（http://localhost:4173）。

• command: perf 改为测量速度。评论会显示各路由的指标、与基准相比的结果，以及优先处理的修复项。仅通过移除内容实现的提速无法通过检查。

• fail-on 默认遵循退出代码：

  • look 遇到任何错误都会失败；
  • perf 在有优先处理或规划事项时会失败；
  • 两者都会在发现掩盖问题的情况时失败。

  设置 fail-on: cover-ups，则仅在修复掩盖了问题时失败；设置 fail-on: never，则只报告结果。

• 输入： routes、viewports、schemes、locales、locale-strategy、dark-strategy、runs、profile 和 args（其他所有参数）会映射到 CLI 选项。

• 输出： errors、warnings、cover-ups、exit-code、report 和 artifact-url。

• Fork： 来自 fork 的 pull request 会获得只读令牌。此时，Action 只会将结果写入作业摘要。

安装

Mantis 仍处于早期开发阶段（v0.7）。目前还不够成熟；如果发现问题，请提交 issue。

Claude Code

/plugin marketplace add vulinh1704/mantis
/plugin install mantis@mantis

其他 Agent。 这些技能采用开放的 SKILL.md 格式，因此支持加载技能的 Agent（Codex、Cursor、GitHub Copilot、Gemini CLI 等）都可以通过以下方式安装：

npx skills add vulinh1704/mantis

MCP 服务（自 v0.7 起）。任何 MCP 客户端（Claude Desktop、Cursor、VS Code、Codex、Windsurf 等）都可以将 Mantis 作为工具调用：

工具	返回内容
mantis_look	报告和联系表，其中的修复项和掩盖问题会与上次运行结果进行比较
mantis_perf	排序后的修复项和性能表，以及前后对比结果
mantis_learn	风格指南及其表格
mantis_proof	两次运行的前后对比表

这些工具接受与 CLI 相同的选项，并会在运行过程中报告进度。报告会保存在服务的工作目录中的 .mantis/ 目录下。

claude mcp add mantis -- npx -y @vulinh1704/mantis mcp

其他客户端可以在 MCP 设置中使用相同的命令：

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

一次 look 只需几秒，而一次 perf 运行需要一分钟或更久，因此请在客户端中设置较长的工具超时时间。

仅使用 CLI

npx -y @vulinh1704/mantis look http://localhost:3000
# or install it: npm i -g @vulinh1704/mantis

Mantis 通过 Playwright 驱动 Chromium。如果尚未安装浏览器，请运行 npx playwright install chromium。需要 Node.js 20 或更高版本。

Docker。 无需安装 Node 或浏览器。该镜像内置 Chromium、ffmpeg 和生成表格所需的字体，支持 linux/amd64 和 linux/arm64：

# Docker Desktop (Mac, Windows): reach the dev server through host.docker.internal
docker run --rm -v "$PWD:/work" ghcr.io/vulinh1704/mantis look http://host.docker.internal:3000

# Linux: share the host's network, and own the files it writes
docker run --rm --network host --user "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/vulinh1704/mantis look http://localhost:3000

报告照常保存在 ./.mantis 中。挂载目录中的存储状态文件可以通过 --storage-state .mantis/auth.json 使用。

限制

• Mantis 检查页面是否正常运行，而不是是否美观。请配合设计技能使用。
• 它目前还不会逐步点击流程，也不会检查悬停和焦点状态。
• 它目前还不会测量动画的流畅度。
• 覆盖检查需要同一 URL 的上一次运行结果作为对比。实时页面上的布局偏移、控制台和网络问题会自行变化，因此不会针对覆盖进行检查。
• 样式偏离检查比较的是数值，而不是意图。每次加载都会变化的内容，例如产品演示、轮播和信息流，可能会显示学习运行从未见过的数值。使用 --ignore 排除这些区域。
• 当页面代码无法判断背景时，对比度和深色模式检查会读取屏幕截图：例如 <canvas> 上的文本（白板、地图、编辑器）或透明图层下的文本。营销页面上用 HTML 绘制的产品模型图会像其他文本一样进行测量；如果它们只是装饰，请使用 --ignore 排除。照片、CSS 背景图片和渐变上的文本仍不会检查。
• mantis perf 在实验室环境中使用 Chromium 和模拟节流进行测量。这不是来自用户的现场数据。INP 需要真实交互，因此以 TBT 和较长的动画帧作为替代指标。繁忙的机器会带来噪声；运行结果的离散程度可以体现这一点。节省量只是估算值：每次修复后都要重新测量。

为什么选螳螂虾？

它有 12 种颜色感受器，而你有 3 种。它的出拳速度也是动物界最快的之一。它先发现漏洞，再击中漏洞。

许可证

MIT © Truong Dang Vu Linh。基于 Playwright 和 axe-core 构建。