uisight

uisight

你的 AI 已经能看到屏幕，只是还无法测量屏幕上的内容。

截图会让 Agent 猜测：“那个标题看起来有点淡。”uisight 让它确切知道：

- from a screenshot:  "the heading looks a little washed out, maybe adjust the color?"
+ from uisight:       INVISIBLE TEXT 1.04:1 — span.bg-gradient-to-r "your headline"
+                     (text rgba(255,255,255,.5) / bg rgb(247,247,248))

一种只是印象。另一种则是附有选择器的测量结果——Agent 会修复那个元素，而不必到处寻找。

uisight 是一款面向网页和响应式 UI 的 MCP 服务（适用于 Claude Code、Cursor、Antigravity，以及任何支持 MCP 的工具）。它会并排运行实时移动端和桌面端会话，测量检测到的内容，并让你和 Agent 看到完全相同的屏幕。

由一位独立创始人打造，他受够了截取手机屏幕、粘贴到聊天中，再输入“这个按钮看起来坏了，你能看出来吗？”

实时面板：同一网站的桌面端和移动端会话，URL 同步。每个屏幕都会运行检查；检查结果按设备返回。AI 可通过 MCP 看到这个完全相同的视图。

有何不同

	多视口浏览器 （Polypane 等）	浏览器工具 / 计算机使用 （Playwright MCP、Agent 工具环境）	原生应用工具包 （Argent 等）	uisight
测量 UI（1.14:1，而非“看起来偏低”）	✅ 面向人类	—	—	✅ 以文本形式提供给 Agent
人类与 Agent 共享一个实时会话	—	—	—	✅
单次运行覆盖设备 × 主题矩阵	✅	—	—	✅
人类标记错误 → Agent 读取备注和画面	—	—	—	✅
原生 iOS/Android 应用	—	—	✅	—（仅限网页）

测量引擎是核心：它不再让 AI 消耗 Token 眯着眼看截图，而是由 inspect 返回如下检查结果：

[mobile · Pixel 7 · light] https://yourapp.com/
  INVISIBLE TEXT 1.04:1 — span.bg-gradient-to-r "your headline" (text rgba(255,255,255,.5) / bg rgb(247,247,248))
  BUTTON a.text-white "Get Started" → text/background contrast 3.35:1
  touch target below 44px 180x23 — "read the guide"

文本检查结果成本低、精确且可直接执行——AI 会修复确切的选择器，而不是靠猜。

“我的 Agent 已经能做这些了”

没错——而且有一部分确实如此。计算机操控、浏览器工具和大多数 Agent 驱动框架已经可以打开页面并截图。这不是 uisight 想要取代的部分。还有三件事尚未解决：

1. 看见不等于测量。 视觉模型读取截图时，无法告诉你对比度比值是多少。它分不清 4.6:1（合格）和 4.3:1（不符合 WCAG AA）——这两者看起来一模一样。它不会发现点击目标是 41px 而不是 44px，也不会注意到某个元素在浅色和深色模式下渲染完全相同，因为它的颜色是硬编码的。uisight 会从实时 DOM 中计算这些数据：包括 Alpha 合成背景、渐变文本、oklch() 颜色等。

2. 同样的代价，能获得更多信息。 以前有人声称，一张截图的成本是一次测量的好几倍。实际测量后发现并非如此：一张移动端画面的截图约为 460 个 token，而对应的 inspect 结果约为 570 个。inspect 并非更省的选项——它能明确告诉你 4.38:1 (threshold 4.5)，而图片只能让模型猜测。

真正节省成本的方式是另一种选择：uisight <url> 会生成一份模型只需读取一次的报告（约 800 个 token）；而逐屏操控 MCP 工具时，每一步都会重新发送完整对话。有人在发布帖下的评论中精准地说出了问题：“确实会消耗一些 token，但还能用。” 成本是多少中列出了完整表格，因为这样的说法值得核实。

3. 没有人和你一起观察。 在常见的设置中，Agent 独自查看页面，然后向你汇报。而在这里，你们会一起观察同一个实时会话——你能看到它的每一步操作；当你发现问题时，可以将其标记（📌）并附上备注，Agent 会读取你的备注和对应的确切画面。再也不必用文字描述 Bug。

范围说明：uisight 适用于Web 和响应式 UI。对于原生 iOS/Android 应用操控，Argent 非常出色，而且在这方面能做的远不止我们。

快速开始

# one-shot audit: PNGs + gallery + report for iPhone/Pixel/desktop, light+dark
npx uisight https://yourapp.com --theme both

# live panel: mobile + desktop side by side, you browse, AI watches (and vice versa)
npx -y -p uisight uisight-panel http://localhost:3000

首次运行。 Playwright 通过 npm 提供驱动程序，但浏览器需要单独下载，因此首次运行时还没有可供操控的浏览器。在终端中，uisight 会提示你下载所需内容（Chromium 一次约占 700 MB 磁盘空间），并显示下载过程。如果没有人可以响应——例如在 CI 中，或由编辑器或 Agent 主机启动的面板中——它绝不会提问或下载，而是明确显示所需的命令。UISIGHT_NO_INSTALL=1 可在所有环境中关闭此提示，你也可以随时手动安装：

npx playwright install chromium        # add webkit for the real iOS Safari engine

单次审计会生成按设备 × 主题排列的画廊卡片，并在每张卡片上显示发现的问题：

接入你的 AI（MCP）

# Claude Code
claude mcp add --scope user uisight -- npx -y -p uisight@latest uisight-mcp

对于 Cursor / Antigravity / 其他 MCP 主机，请在 MCP 配置中添加：

{ "mcpServers": { "uisight": { "command": "npx", "args": ["-y", "-p", "uisight@latest", "uisight-mcp"] } } }

然后只需告诉你的 Agent：“用 uisight 查看我的应用。” 需要时，面板服务会自动启动。

Claude Desktop（一键安装）

从最新版本下载 uisight-<version>.mcpb 并打开。Claude Desktop 会安装它，并询问三项内容：要打开的页面、工具集（all 或 core），以及是否在首次使用时下载浏览器。无需编辑 JSON。

该捆绑包包含服务及其依赖项（约 7 MB）。其中不包含浏览器，这正是第三个问题的原因：启用后，缺少的 Chromium 会在首次调用工具时由构建该捆绑包所用的 Playwright 版本下载一次。你也可以使用 node scripts/build-mcpb.mjs 自行构建捆绑包。

MCP 工具

工具	功能
see_screen	返回当前屏幕的图像——也就是人类在面板中看到的准确画面
inspect	运行对比度 / 触控目标 / 溢出 / 主题检查；以文本形式返回测量结果
goto	将所有会话导航到某个 URL（包括 localhost）
tap / type_text / scroll	操作页面——人类可以实时观看操作过程
set_device	切换设备配置（iphone-15、iphone-se、pixel、galaxy、ipad、desktop、laptop）或浅色 / 深色主题
status	查看打开的 URL、会话、近期控制台 / 网络错误——排查错误时的第一站
marks	读取人类在面板中固定的备注（📌 备注 + 当时的屏幕截图）

设置 UISIGHT_LANG=tr 后可使用土耳其语工具名称（ekrani_gor、denetle 等）。

面板（人类侧）

运行 npx -y -p uisight uisight-panel <url>，即可在 localhost:5055 打开浏览器页面：

• 移动端 + 桌面端并排显示，两边都实时更新，URL 同步
• 点击 = 在对应设备上轻触 · 滚轮 = 滚动 · 点击后输入文字
• 每个窗格都有设备切换器，浅色 / 深色切换器由两边共用
• Inspect 按钮会对每个屏幕运行测量引擎
• 📌 Pin：输入备注并固定后，你的 AI 就能通过 marks 读取备注 + 屏幕截图。不再需要“让我描述一下我看到的内容”。

可在 VS Code / Antigravity 中使用：选择 Simple Browser: Show → http://localhost:5055。

检查内容

能看清吗

• 不可见文本（对比度 < 1.6:1）和 WCAG AA 对比度不达标的问题——支持 alpha 合成背景、渐变文本、oklab() / oklch() 颜色
• 小于 12px 的文本、缺少 alt 的图像
• 被自身容器截断的文本（line-clamp 等不算“裁切”——这是有意设计）

能触达吗

• 小于 44px 的触控目标（仅限移动设备配置；根据 WCAG，行内文本链接不受宽度限制）
• 被其他内容遮挡的控件——通过 elementFromPoint 确认，而非根据几何位置判断；并从边到边采样，因此宽按钮的一端被悬浮按钮挡住也能发现
• 被固定栏或屏幕键盘压住的控件（keyboard-audit 会像手机一样打开键盘并重新测量）
• 被容器裁切且无法滚动到的内容——同一个框使用 overflow-x: auto 就没问题，因为内容可以触达
• 行内容不换行时，滑到控件后面的文本
• 水平溢出及造成溢出的元素
• 位于刘海或主屏幕指示条下方的固定栏——仅当页面请求全屏（viewport-fit=cover）却从未使用返回的内边距时才会检查；没有该标记时，iOS 会在页面周围加黑边，不会有内容被遮挡

逻辑合理吗

• 一排看起来完全相同的操作，因此无法区分哪一个是主要操作——对于标签页、菜单和筛选标签不会发出警告；只有误点会造成代价时（保存、删除、发送、付款）才会触发
• 深色模式中残留的亮色区域
• 同一屏幕中出现两种语言，以及非美国地区使用美国日期格式
• 转圈加载指示器仍在转动时显示“0 个结果”——把中间状态当成了事实
• 没有指出具体内容（“发生错误。”）且旁边没有退出方法的错误消息
• 可逆性不可恢复的操作——删除、移除、删除账户——所在页面完全没有确认步骤；不会点击按钮，因为点击真的会执行删除
• 页面加载期间就请求权限，此时用户还没有做过任何能说明请求缘由的操作
• 主题偏差：浅色和深色模式下都完全相同的元素 = 很可能使用了硬编码颜色
• 每台设备上的控制台 / JS 错误和失败的网络请求

每项检查的检测测试旁边都有一个误报测试。这不是出于礼貌：如果工具对每个底部导航栏都误报，人们就会忽略它，真正的检查结果也就无人查看。

坦诚地说，自动化检查无法发现设计错误——即使页眉相互重叠，测量结果也可能正常。这就是 see_screen 存在的原因，也是报告会提示“用肉眼检查 PNG”的原因。

无法通过查看渲染页面发现的行为（离线、返回）

有两项无法通过渲染后的页面测量：网络必须真的断开，返回按钮也必须真的按下。两者都作为面板操作运行，因此审计和 MCP 工具可以共用。

# through the panel
curl -X POST localhost:5055/action -H 'x-uisight-token: ...' \
     -d '{"type":"offline-audit","session":"mobile"}'

离线会断开连接、重新加载，然后检查用户看到的是什么：说明、重试按钮、永远不会结束的旋转图标，还是一片空白。为了确保判断可靠，关键在于服务工作线程——没有服务工作线程的页面无法离线响应，因此该结果会标记为 expected，并从审计结果中过滤掉。注册了工作线程却仍显示浏览器错误页面的页面，则是实际发现的问题。连接会在 finally 中恢复，因此即使失败，也不会让会话一直处于离线状态。

返回会打开一个站内链接并按下返回按钮，然后检查地址是否回到起点，以及屏幕是否为空白。返回后看到空白页面，会让“返回”变成“离开应用”。

登录后审计（uisight-audit）

公共页面只占应用的一半，而用户实际使用的部分并不只限于此。有人手动发现了 4 个真实问题并提交，其中 3 个藏在登录之后，另 1 个只会出现在某个特定角色下。

uisight-audit                        # every configured role, 10 pages each
uisight-audit --roles guide,agency   # only these
uisight-audit --pages 20 --port 5062

账号保存在 ~/.uisight/accounts.json 中。登录会尝试三种方式：固定的 code（类似商店审核账号的模式）、直接从应用自身的 OTP 响应中读取的 devCode（开发／演示模式——完全不需要存储密钥），或密码字段。离开登录页面才算登录成功，而不是 HTTP 200，因此错误验证码绝不会被报告为成功。如果应用拒绝登录，就会原样传递应用给出的提示：“HTTP 429 · 请求验证码过于频繁”，而不是猜测它是否处于演示模式。

如果应用提供了“查看为”端点，就通过该端点切换角色，这样一个管理员账号就能审计所有角色。尚未在任何角色下测量的页面会优先处理，让第二个角色把预算花在新页面上，而不是重复测量相同的公共页面。

编辑器扩展

extension/ 是一个 VS Code / Antigravity 扩展：侧边栏中的实时面板，以及用于设备、主题、地址、检查和“将屏幕发送给你的 AI”的命令。

在 Antigravity、Cursor 或 VSCodium 的扩展面板中搜索 uisight — open-vsx.org/extension/sololabstr/uisight。唯一的依赖是 Node.js：该扩展通过 npx uisight@latest 运行已发布的软件包，因此引擎会自行更新，安装一次后即可持续获得新的检查项。

要从此仓库构建扩展：

cd extension && npx @vscode/vsce package
code --install-extension uisight-*.vsix

扩展通过 HTTP 与面板通信，而这段交互没有任何类型检查，因此 test/extension.test.mjs 会比对两端：扩展发送的每个操作都必须由服务端处理，每个路由都必须存在，扩展渲染的每个结果字段都必须由引擎生成，清单中的每条命令都必须已注册。这个测试之所以存在，是因为两端曾经发生过一次偏离，而且失败得悄无声息——页面上明明到处都是问题，Inspect 却报告“未发现问题”。

费用

有人运行这个工具时耗尽了套餐，却无从得知费用花在了哪里。 因此，这里给出的是实测数据，而非估算——在真实网站上进行的一次 Pixel 7 会话， 图像费用按 Claude 的计价方式计算（宽度 x 高度 / 750）：

	tokens
uisight <url>，然后读取 REPORT.md	~800，一次
uisight-audit，然后读取 REPORT.md	~150-800，一次
MCP inspect	每次调用 ~570
MCP see_screen	每次调用 ~260（0.75 缩放比例，默认值）
MCP see_screen 搭配 full	每次调用 ~2,000（有上限；无上限时约 ~5,800）
工具定义	每次请求 ~1,065

这张表说明了三件事。

CLI 是最省钱的方式，而且优势非常明显。 uisight 和 uisight-audit 会写入一个文件；模型只需读取一次。逐屏调用 MCP 工具时，每一步都会 重新发送整个对话，所以三十次往返的费用远高于一份报告。需要对页面进行 操作 时才使用 MCP 工具——例如点击某项内容、更换设备、查看特定状态—— 而不是用来浏览应用。

图像不会只计费一次。 它会留在对话中，并在之后的每一轮重新发送。这就是 inspect 存在的原因，也是其输出采用文本的原因：同一页面的实测费用约为 570 tokens，而查看图像约为 460；测量结果会写明 4.38:1（阈值 4.5），而模型只能从图片中猜测。整页截图现在有上限 （UISIGHT_MAX_IMAGE_TOKENS，默认值为 2000），响应会告诉你费用和省略的内容， 而不是悄悄消耗 tokens。

截图无需使用原始尺寸。 在真实页面上实测：同一移动屏幕在缩放比例为 1.0、0.75 和 0.5 时，分别为 461、259 和 115 tokens；费用会随缩放比例的 平方下降。0.75 时几乎无法区分差异，包括小字；0.5 时布局和所有有意义的 标签仍然清晰可读，只有最小的法律文本会变模糊。因此默认值为 0.75，scale 是 see_screen 的一个参数；查看小字时传入 1，快速低成本扫描时传入 0.5。

工具定义是每次请求都要支付的固定费用。 无论是否调用，九个工具都会耗费约 1,065 tokens：

// only what a measuring session needs: goto, inspect, see_screen, status
{ "env": { "UISIGHT_TOOLS": "core" } }        // ~419 tokens
{ "env": { "UISIGHT_TOOLS": "goto,inspect" } } // ~211 tokens

遇到问题了吗？

请提交 issue——哪怕只写一句话也行。这是一个年轻的项目，让它最快取得进步的方式， 就是有人说“我在 X 上运行了它，得到了 Y”。面板截图或 REPORT.md 的内容会很有帮助。

以下是已知的不足，方便你区分错误和限制：

• 引擎无法发现设计问题。 与徽标重叠的页眉在测量中看起来完全正常。请使用 see_screen 亲自查看。
• 会跳过照片背景。 无法根据 CSS 计算背景图像上的对比度，因此引擎会略过这些元素，而不是进行猜测。
• 主题漂移检测会采样结构元素（body、header、nav、main、footer、button、a、input、cards/panels/modals/menus）——如果漂移只出现在正文文案中，就不会显示在浅色↔深色对比结果中。
• iPhone 配置使用的是 WebKit，而非 iOS Simulator——与 Safari 非常接近，但并不完全等同于真实设备。
• 内部内容仍为土耳其语。 面向用户的部分（工具、CLI 标志、报告）为英文；src/ 中的变量名目前仍未翻译。欢迎提交 PR，无论哪种都行。

开发

npm install
npx playwright install chromium
npm test          # runs the inspection engine against fixture pages in a real browser

测试是回归保护：test/inspect.test.mjs 中的每个用例，都对应引擎至少出错过一次的情况——错误地判定为“正常”、误报，或悄悄跳过某种颜色格式的测量。

修改测量引擎前，请先阅读 CONTRIBUTING.md——其中解释了为什么颜色计算无法提取到模块中，以及怎样才算一份好的 bug 报告。

注意事项与限制

• iPhone 配置文件运行在真实的 WebKit（Safari 的引擎）上——接近 iOS，但并非 iOS Simulator。
• Playwright 会在首次运行时下载浏览器（如需提前下载，可运行 npx playwright install chromium webkit）。
• 所有内容都在本地运行——无需云服务或账户，你的屏幕内容绝不会离开你的设备。
• 截至 v0.2，整个代码库均为英文——包括标识符、注释和面板的 HTTP 字段名称。如果你直接调用面板 API，CHANGELOG.md 中列有名称变更对照表。

许可证

MIT © SoloLabs