DiffLens
MCP服务器，为AI编码代理提供UI工作的“眼睛”。它在代码更改前后对本地主机页面进行截图，直观地进行比较，并返回带有叠加图像的结构化差异报告。
快速开始
npm install -g difflens-cli
cd your-project
difflens setup
# Restart Claude Code — DiffLens is now activeDiffLens自动工作——只需正常发出UI请求。Claude将在更改前进行快照，并在更改后进行验证，无需您询问。
无需安装即可使用
添加到您的项目 .mcp.json:
{
"mcpServers": {
"difflens": {
"command": "npx",
"args": ["-y", "difflens-cli"]
}
}
}运作原理
- 快照 保存基线屏幕截图的页面
- 对代码进行更改
- 检查 该页面--DiffLens获取一个新的屏幕截图，根据基线运行像素级差异，对更改的区域进行聚类，并返回一个带有注释的覆盖图像的报告
覆盖会使未更改的区域变暗，用红色突出显示更改的像素，在检测到的区域周围绘制边框，并包含一个带有更改百分比的图例栏。
从源代码安装
git clone https://github.com/byzkhan/difflens.git
cd difflens
npm install
npm run build工具
快照
截取屏幕截图并将其保存为基线。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | string | 必填 | 截图URL |
width | 数字 | 1280 | 视口宽度 |
height | 数字 | 720 | 视口高度 |
fullPage | boolean | true | 捕获完整的可滚动页面 |
waitForSelector | string | -- | 捕获前要等待的CSS选择器 |
waitForTimeout | number | -- | 额外等待时间（毫秒） |
检查
拍摄一张新的屏幕截图，并将其与最新基线（或特定快照）进行比较。返回结构化报告和叠加图像。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | string | 必填 | 要检查的URL |
baselineId | string | latest | 要比较的特定快照ID |
width | 数字 | 1280 | 视口宽度 |
height | 数字 | 720 | 视口高度 |
fullPage | boolean | true | 捕获完整的可滚动页面 |
waitForSelector | string | -- | 要等待的CSS选择器 |
waitForTimeout | number | -- | 额外等待时间（毫秒） |
报告包括：
- 状态:
no_changes,minor(\10%) - 百分比已更改：精确的像素变化百分比
- 区域：带有位置描述和像素数的更改区域列表
- 覆盖图像：带注释的复合显示了更改的内容
检查响应
在多个视口宽度下运行视觉差异，以捕捉响应式设计回归。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | string | 必填 | 要检查的URL |
widths | number\[\] | \[375、768、1024、1440\] | 要测试的视口宽度 |
height | 数字 | 720 | 视口高度 |
fullPage | boolean | true | 捕获完整的可滚动页面 |
waitForSelector | string | -- | 要等待的CSS选择器 |
waitForTimeout | number | -- | 额外等待时间（毫秒） |
快照元素
通过CSS选择器对特定DOM元素进行截图。内联返回图像。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | string | 必填 | 包含元素的URL |
selector | string | 必需 | 要捕获的CSS选择器 |
width | 数字 | 1280 | 视口宽度 |
height | 数字 | 720 | 视口高度 |
waitForSelector | string | -- | 要等待的CSS选择器 |
waitForTimeout | number | -- | 额外等待时间（毫秒） |
list_snapshots
列出具有可选筛选功能的存储快照。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | string | -- | 按URL筛选 |
limit | number | 20 | 最大结果 |
清理
按年龄或计数删除旧快照。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
maxAgeHours | number | -- | 删除早于此的快照 |
maxCount | number | -- | 最多保留这么多（最新的优先） |
dryRun | boolean | false | 预览而不删除 |
自动工作流
DiffLens包括 CLAUDE.md 文件和Claude Code挂钩，使视觉验证完全自动化。你不需要提到DiffLens——Claude自己就这么做了：
You: Move the login button to the right side of the header
Agent: [calls snapshot on localhost:3000 — saves baseline]
[edits header CSS]
[calls check — compares before/after]
Done. Moved the login button to the right side of the header.
Visual check confirmed: only the button position changed,
no unintended layout shifts or regressions.如果Claude检测到差异中的意外变化，它会自动修复这些变化并重新检查，直到结果干净为止。
引擎盖下的工作原理
- CLAUDE.md 指示Claude始终在UI编辑之前进行快照，并在编辑之后进行检查
- 克劳德代码挂钩 每次文件编辑时触发——如果文件是UI文件（.html、.css、.jsx、.tsx、.vue、.svelte、.scs），它们会提醒Claude进行快照/检查
- Claude阅读差异报告，修复任何回归，只有在验证了视觉输出后才会做出响应
手动使用
您还可以明确地使用DiffLens：
You: Take a snapshot of http://localhost:3000
Agent: [calls snapshot] Saved baseline abc123
You: Check localhost:3000 for visual changes
Agent: [calls check] 4.2% pixels changed — 2 regions detected
[shows overlay image]存储
所有数据都存储在本地 .difflens/:
.difflens/snapshots/--PNG截图+JSON元数据.difflens/diffs/--差分图像和叠加合成
添加 .difflens/ 到你的 .gitignore.
实现细节
- 浏览器重用剧作家Chromium推出一次并保持活力。每个屏幕截图都会创建一个独立的
BrowserContext（约200毫秒，而新浏览器约3秒）。 - 确定性捕捉：在页面JS运行之前注入反动画CSS。动画、过渡和插入符号闪烁被禁用。时区锁定为UTC，区域设置为en-US。
- 区域聚类：更改的像素被分组到10x10px的网格中，然后在50px的范围内合并附近的单元格。这将原始像素噪声转化为有意义的“标题更改”区域。
- 原子写入：快照将写入
.tmp然后重命名文件，防止并发访问造成损坏。 - stdio安全：所有日志记录都会进入stderr。stdout保留用于MCP协议消息。
技术栈
许可证
麻省理工学院