内容
<div align="center">
# 视觉验证工具
### 为 AI 生成的界面提供独立的视觉验证服务
**视觉验证工具会捕获用户实际看到的用户界面，识别出使其感觉通用或不一致的视觉线索，草拟基于源代码的修复方案，并在一次性checkout中验证结果，然后再对您的应用程序进行任何修改。**
[演示](#演示) · [为什么使用视觉验证工具](#为什么使用视觉验证工具) · [功能](#功能) · [快速入门](#快速入门) · [光标MCP](#光标MCP) · [架构](#架构) · [部署](#部署)
[](./LICENSE)
[](https://cursor.com)
[](https://www.typescriptlang.org/)
[](https://nextjs.org/)
[](https://modelcontextprotocol.io/)
<br/>
</div>
---
## 演示
- **在线应用：** [tell-five.vercel.app](https://tell-five.vercel.app)
- **默认扫描目标：** [superlearnai.com](https://superlearnai.com)
- **离线备用：** `fixtures/reports/tell-report.json`，因此即使实时捕获不可用，产品仍会打开并显示完整的报告。
- **展示GIF：** `docs/media/tell-superlearnai-demo.gif`，从当前UI流程生成。
视觉验证工具可以直接扫描公共URL，或本地克隆GitHub仓库，安装依赖项，在空闲端口启动应用程序，并自动捕获localhost。
---
## 为什么使用视觉验证工具
AI代理可以快速生成可用的界面。更难的问题是结果是否有品位：独特的层次结构，一致的令牌，可达的状态，可读的对比度，以及不会崩溃为相同的渐变卡片模板的视觉语言。
视觉验证工具是针对这一刻的独立审查员。它不要求作者代理对其自身输出进行评分。它在真正的浏览器中打开页面，测量渲染的表面，识别特定的通用性和漂移模式，并将批评转化为可审查的方向。
作者代理提出建议。视觉验证工具进行测量，批评，修复和验证。
---
## 功能
| 功能 | 今日发货 |
|---|---|
| **渲染捕获** | Playwright打开路由并记录截图证据，DOM摘要，计算样式，CSS变量，对比度样本和交互状态探针。 |
| **14个确定性检测器** | 8个通用性提示和6个一致性漂移检测器捕获系统字体，渐变支架，阴影过度使用，半径单调，灰色泥泞，令牌绕过，间距混乱，状态间隙，焦点不一致等。 |
| **品位引擎** | 发现变成纯英语判决：`generic`，`drift`，`intentional`或`uncertain`，具有信心和理由。Gemini可以丰富判断；确定性回退保留流程在无需密钥的情况下可用。 |
| **语音和文本艺术指导** | 说出或输入方向，如“更温暖，更具编辑性，更少的阴影”。视觉验证工具将意图映射到预设和具体的行动项目，然后进行模型改进。 |
| **前后显示** | 捕获的页面与确定性调和对比，保留内容同时改善层次结构，对比度，深度，半径和焦点处理。 |
| **基于源代码的重新设计差异** | 当存储库可用时，视觉验证工具对渲染证据进行排序，并草拟一个统一的差异，而不是从截图中猜测。 |
| **视觉工作树证明** | 候选补丁在一次性checkout中运行。视觉验证工具应用，等待HMR，重新捕获，比较得分/焦点/结构，并自动恢复失败的尝试。 |
| **GitHub设置运行器** | 粘贴`github.com/owner/repo`；本地视觉验证工具克隆它，读取`README`和`package.json`，安装依赖项，启动开发服务器，并捕获可达的URL。 |
| **多页面扫描** | 从快照中发现的路由可以单独扫描，暴露出仅在定价，文档，引导或次要页面上出现的漂移。 |
| **光标MCP** | `tell_capture`，`tell_diagnose`，`tell_redesign`，`tell_apply`，`tell_proof_verify`，`tell_proof_revert`和`tell_capture_matrix`在光标代理聊天中公开相同的引擎。 |
| **场景矩阵** | 实时Playwright捕获路由×视口×主题×交互×身份验证（storageState），具有CI烟雾测试和一个视觉验证工具报告面板。 |
视觉验证工具不是功能性，响应性，可访问性或安全性测试的替代品。它是一个专注的视觉证据层，适用于一次渲染的路由。
---
## 工作原理
```mermaid
flowchart LR
url["公共URL或本地应用"] --> capture["浏览器捕获"]
capture --> fingerprint["设计指纹"]
fingerprint --> detectors["通用性 + 漂移检测器"]
detectors --> taste["品位判决"]
taste --> report["视觉验证工具报告"]
report --> direction["语音/文本艺术指导"]
direction --> diff["基于源代码的差异"]
diff --> proof["一次性校验checkout"]
proof --> recapture["重新捕获 + 测量比较"]
recapture --> cursor["在光标中审查和应用"]
```
**确定性优先：** 捕获，指纹识别，检测器输出，基准调和和得分比较不依赖模型。仅在判断或起草时才使用模型。
**人为审查设计：** 视觉验证工具可以准备补丁并在隔离中证明，但最终更改仍然通过开发者的正常审查工作流程落地。
---
## 快速入门
您需要 **Node 20+** 和 **pnpm 9+**。
```bash
git clone <your-repo-url> tell
cd tell
pnpm install
pnpm dev
```
在 [http://localhost:3000](http://localhost:3000) 打开。应用程序以SuperlearnAI作为捕获目标启动，如果实时捕获无法运行，则回退到已提交的报告。
在第二个终端中使用已播种的示例应用程序：
```bash
pnpm dev:fixture # http://localhost:3001
```
有用的检查：
```bash
pnpm test
pnpm typecheck
pnpm capture:fixture
pnpm diagnose:fixture
pnpm auth:fixture # 为/account铸造Playwright storageState（fixture必须启动）
pnpm capture:matrix # 实时场景矩阵（设置TELL_MATRIX_URL）
pnpm verify:directions # 截图所有6个调和方向（需要Playwright）
```
可选环境变量位于 `.env.example` 中：
```bash
GEMINI_API_KEY= # 更丰富的品位和语音解析
CURSOR_API_KEY= # 光标SDK支持的重新设计草图
CURSOR_MODEL=composer-2.5
CURSOR_AGENT_TIMEOUT_MS=75000
TELL_CAPTURE_API_URL= # 用于托管UI的远程Playwright后端
```
---
## 光标MCP
视觉验证工具通过 `.cursor/mcp.json` 注册为本地MCP服务器。在光标中打开此存储库，并要求代理聊天直接运行工具。
```text
在 http://localhost:3001 上运行 tell_diagnose 并草拟编辑性重新设计。
```
| 工具 | 目的 |
|---|---|
| `tell_capture` | 捕获URL的截图和计算样式证据。 |
| `tell_diagnose` | 返回完整的视觉验证工具报告，发现，判决和得分。 |
| `tell_redesign` | 为发现或整个报告草拟重新设计提案。 |
| `tell_apply` | 返回补丁文本和说明；它永远不会为您写入文件。 |
| `tell_proof_verify` | 应用补丁，重新捕获URL，并返回通过/审查/失败并测量增量。 |
| `tell_proof_revert` | 恢复工作区中的上一个校验补丁。 |
| `tell_capture_matrix` | 实时Playwright场景矩阵（路由×视口×主题×交互×身份验证）。 |
---
## 架构
视觉验证工具是一个pnpm monorepo，具有一个共享引擎，支持Web应用程序和MCP服务器。
```text
tell/
├── apps/web/ # Next.js产品UI和API路由
├── packages/schema/ # 整个边界共享的Zod合约
├── packages/core/ # 捕获，指纹识别，检测器，诊断
├── packages/taste/ # 判决，方向预设，语音/文本解析
├── packages/redesign/ # 调和，源代码补丁，校验措施
├── packages/mcp/ # 光标MCP_stdio服务器
├── fixtures/ # 通用输入应用程序和已提交的报告工件
└── docs/ # 产品，部署和设计说明
```
关键API路由：
| 路由 | 责任 |
|---|---|
| `POST /api/diagnose` | 捕获并诊断URL，使用远程捕获后端时配置。 |
| `POST /api/redesign` | 使用确定性回退生成源感知重新设计提案。 |
| `POST /api/voice` | 将转录/文本转换为方向预设和行动项目。 |
| `POST /api/setup/start` | 仅限本地GitHub克隆/安装/运行/捕获工作流。 |
| `POST /api/proof/apply` | 在一次性checkout中应用候选补丁并验证它。 |
| `POST /api/proof/verify` | 托管校验沙盒 - 在Vercel上比较两个报告，或在捕获后端应用+重新捕获。 |
| `POST /api/proof/matrix` | 实时场景矩阵捕获（+可选的自我比较）。 |
| `POST /api/proof/revert` | 恢复校验checkout。 |
| `POST /api/reports/share` | 持久化视觉验证工具报告（Neon → Blob → 磁盘）并返回一个可共享的 `/report/[id]` 链接。 |
| `GET /api/reports/[id]` | 加载先前共享的报告JSON。 |
| `GET /api/health/capture` | 检查Playwright捕获准备情况。 |
---
## 部署
最可靠的生产环境是托管的UI和单独的Playwright捕获后端。
| 层 | 平台 | 角色 |
|---|---|---|
| UI | Vercel | 快速Next.js应用程序，报告，显示，语音方向，重新设计草图 |
| 捕获 | Vultr，Render或Docker主机 | Playwright + Chromium，用于实时URL诊断 |
| MCP | 本地光标 | 编辑器原生诊断和补丁交接的stdio工具 |
在Vercel应用程序上设置 `TELL_CAPTURE_API_URL` 以指向捕获后端。 GitHub克隆和运行在公共主机上应保持禁用，并使用 `TELL_DISABLE_REPO_SETUP=1` 。
对于Vercel上的持久链接，设置 `DATABASE_URL` 从Neon项目（首选）或链接Blob存储（参见 [DEPLOY.md](./docs/DEPLOY.md)）。对于PR预览诊断CI，设置GitHub存储库变量 `TELL_PREVIEW_URL` 为您的稳定Vercel URL。
部署指南：
- [混合和单平台部署](./docs/DEPLOY.md)
- [Vultr捕获后端](./docs/DEPLOY-VULTR.md)
---
## 产品状态
已发货：
- 确定性捕获，指纹识别和14个检测器
- 具有安全回退的品位判决
- 具有前后显示的视觉验证工具报告
- 语音/文本艺术指导
- 光标MCP工具
- 公共URL捕获，具有离线报告回退
- 本地GitHub存储库设置运行器
- 基于源代码的重新设计提案
- 基于对比度的调和
- 多页面路由发现和每页扫描
- 候选补丁的离散视觉证明循环
接下来：
- 可选拉伸 - 没有开放的PLAN阻塞。托管公共演示仍然需要用于Playwright支持的矩阵设置的 `TELL_CAPTURE_API_URL` 。
---
## 贡献
欢迎贡献。最高杠杆的增加是新的检测器，更好的证据视图和更强的源代码映射。
```bash
pnpm typecheck && pnpm test
```
`fixtures/generic-app/`下的示例应用程序是故意设计的朴素输入数据，而不是产品本身。有关属性分解，请参见 [CONTRIBUTIONS.md](./CONTRIBUTIONS.md)。
---
## 许可证
在 [MIT许可证](./LICENSE) 下发布。
