difflens (Byzkhan)

DiffLens

MCP服务器，为AI编码代理提供UI工作的“眼睛”。它在代码更改前后对本地主机页面进行截图，直观地进行比较，并返回带有叠加图像的结构化差异报告。

快速开始

npm install -g difflens-cli
cd your-project
difflens setup
# Restart Claude Code — DiffLens is now active

DiffLens自动工作——只需正常发出UI请求。Claude将在更改前进行快照，并在更改后进行验证，无需您询问。

无需安装即可使用

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "difflens": {
      "command": "npx",
      "args": ["-y", "difflens-cli"]
    }
  }
}

运作原理

1. 快照 保存基线屏幕截图的页面
2. 对代码进行更改
3. 检查 该页面--DiffLens获取一个新的屏幕截图，根据基线运行像素级差异，对更改的区域进行聚类，并返回一个带有注释的覆盖图像的报告

覆盖会使未更改的区域变暗，用红色突出显示更改的像素，在检测到的区域周围绘制边框，并包含一个带有更改百分比的图例栏。

从源代码安装

git clone https://github.com/byzkhan/difflens.git
cd difflens
npm install
npm run build

工具

快照

截取屏幕截图并将其保存为基线。

检查

拍摄一张新的屏幕截图，并将其与最新基线（或特定快照）进行比较。返回结构化报告和叠加图像。

报告包括：

• 状态: no_changes, minor (\10%)
• 百分比已更改：精确的像素变化百分比
• 区域：带有位置描述和像素数的更改区域列表
• 覆盖图像：带注释的复合显示了更改的内容

检查响应

在多个视口宽度下运行视觉差异，以捕捉响应式设计回归。

快照元素

通过CSS选择器对特定DOM元素进行截图。内联返回图像。

list_snapshots

列出具有可选筛选功能的存储快照。

清理

按年龄或计数删除旧快照。

自动工作流

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检测到差异中的意外变化，它会自动修复这些变化并重新检查，直到结果干净为止。

引擎盖下的工作原理

1. CLAUDE.md 指示Claude始终在UI编辑之前进行快照，并在编辑之后进行检查
2. 克劳德代码挂钩 每次文件编辑时触发——如果文件是UI文件（.html、.css、.jsx、.tsx、.vue、.svelte、.scs），它们会提醒Claude进行快照/检查
3. 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协议消息。

技术栈

• 模型上下文协议SDK --MCP服务器框架
• 剧作家 --无头浏览器自动化
• 像素匹配 --像素级图像比较
• 锋利 --叠加图像合成
• pngjs --PNG编码/解码
• 黄道带 --工具模式的输入验证

许可证

麻省理工学院