内容
<div align="center">
# Tell Proof
### 独立的视觉验证，适用于 AI 生成的界面
**Tell Proof 捕获用户实际看到的 UI，识别使其感觉通用或不一致的视觉特征，起草基于源代码的修复方案，并在任何更改触及您的应用程序之前，在一次性检查环境中验证结果。**
[演示](#demo) · [为什么是 Tell](#why-tell) · [功能](#features) · [快速入门](#quick-start) · [Cursor MCP](#cursor-mcp) · [架构](#architecture) · [部署](#deploy)
[](./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 流生成。
Tell 可以直接扫描公共 URL，也可以本地克隆 GitHub 仓库，安装依赖，启动应用在空闲端口，并自动捕获 localhost。
---
## 为什么是 Tell
AI 代理可以快速生成可用的界面。但更难的问题是，结果是否有品位：独特的层次结构，一致的令牌，可达的状态，清晰的对比度，以及不会崩溃为相同的渐变卡片模板的视觉语言。
Tell Proof 是针对这一刻的独立评审者。它不会要求作者代理为自己的输出评分。它在真实的浏览器中打开页面，测量渲染的表面，识别特定的通用性和漂移模式，并将批评转化为可审查的方向。
作者代理提出建议。Tell 测量，批评，修复，并验证。
---
## 功能
| 功能 | 当前版本 |
|---|---|
| **渲染捕获** | Playwright 打开路由并记录截图证据，DOM 摘要，计算样式，CSS 变量，对比度样本和交互状态探针。 |
| **14 个确定性检测器** | 8 个通用性检测和 6 个一致性漂移检测器捕获系统字体，渐变支撑，阴影过度使用，半径单调，灰色模糊，令牌绕过，间距混乱，状态间隙，焦点不一致等。 |
| **品位引擎** | 发现结果转化为纯英文判决：`generic`，`drift`，`intentional` 或 `uncertain`，具有置信度和理由。Gemini 可以丰富判断；确定性回退在没有密钥的情况下保持流程可用。 |
| **语音和文本艺术指导** | 说出或输入方向，如“更温暖，更具编辑性，更少阴影”。Tell 将意图映射到预设和具体行动项目，然后进行模型改进。 |
| **前后对比** | 捕获的页面与确定性协调进行比较，以保留内容，同时改善层次结构，对比度，深度，半径和焦点处理。 |
| **基于源代码的重新设计差异** | 当有仓库可用时，Tell 按渲染证据对真实的 TSX/JSX/CSS 文件进行排名，并起草统一的差异，而不是从截图中猜测。 |
| **视觉工作树证明** | 候选补丁在一次性检查环境中运行。Tell 应用，等待 HMR，重新捕获，比较分数/焦点/结构，并自动恢复失败的尝试。 |
| **GitHub 设置运行器** | 粘贴 `github.com/owner/repo`；本地 Tell 克隆它，读取 `README` 和 `package.json`，安装依赖，启动开发服务器，并捕获可达的 URL。 |
| **多页面扫描** | 从快照中发现的路由可以单独扫描，暴露在定价，文档，引导或次要页面上才出现的漂移。 |
| **Cursor MCP** | `tell_capture`，`tell_diagnose`，`tell_redesign` 和 `tell_apply` 在 Cursor Agent 聊天中暴露相同的引擎。 |
Tell 不是功能性，响应性，可访问性或安全测试的替代品。它是一个专注的视觉证据层，适用于一次渲染的路由。
---
## 工作原理
```mermaid
flowchart LR
url["公共 URL 或本地应用"] --> capture["浏览器捕获"]
capture --> fingerprint["设计指纹"]
fingerprint --> detectors["通用性和漂移检测器"]
detectors --> taste["品位判决"]
taste --> report["Tell 报告"]
report --> direction["语音/文本艺术指导"]
direction --> diff["基于源代码的差异"]
diff --> proof["一次性验证检查环境"]
proof --> recapture["重新捕获 + 测量比较"]
recapture --> cursor["在 Cursor 中审查和应用"]
```
**确定性优先：** 捕获，指纹识别，检测器输出，基准协调和分数比较不依赖于模型。仅在判断或起草需要语言时才使用模型。
**设计为人工审查：** Tell 可以准备补丁并在隔离环境中证明，但最终更改仍通过开发者的正常审查工作流落地。
---
## 快速入门
您需要 **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
```
可选环境变量位于 `.env.example` 中：
```bash
GEMINI_API_KEY= # 更丰富的品位和语音解析
CURSOR_API_KEY= # Cursor-SDK 支持的重新设计草案
CURSOR_MODEL=composer-2.5
CURSOR_AGENT_TIMEOUT_MS=75000
TELL_CAPTURE_API_URL= # 用于托管 UI 的远程 Playwright 后端
```
---
## Cursor MCP
Tell 通过 `.cursor/mcp.json` 注册为本地 MCP 服务器。在 Cursor 中打开此仓库，并要求 Agent 聊天直接运行工具。
```text
在 http://localhost:3001 上运行 tell_diagnose 并起草编辑性重新设计。
```
| 工具 | 目的 |
|---|---|
| `tell_capture` | 捕获 URL 的截图和计算样式证据。 |
| `tell_diagnose` | 返回完整的 Tell 报告，发现结果，判决和分数。 |
| `tell_redesign` | 为发现结果或整个报告起草重新设计提案。 |
| `tell_apply` | 返回补丁文本和说明；它永远不会为您写入文件。 |
---
## 架构
Tell 是一个 pnpm 多模块仓库，具有一个共享引擎，支持 Web 应用和 MCP 服务器。
```text
tell/
├── apps/web/ # Next.js 产品 UI 和 API 路由
├── packages/schema/ # 跨边界共享的 Zod 契约
├── packages/core/ # 捕获，指纹识别，检测器，诊断
├── packages/taste/ # 判决，方向预设，语音/文本解析
├── packages/redesign/ # 调和，源代码补丁，证明测量
├── packages/mcp/ # Cursor MCP stdio 服务器
├── fixtures/ # 通用输入应用和已提交报告工件
└── docs/ # 产品，部署和设计说明
```
关键 API 路由：
| 路由 | 责任 |
|---|---|
| `POST /api/diagnose` | 捕获和诊断 URL，使用远程捕获后端时配置。 |
| `POST /api/redesign` | 使用确定性回退生成基于源代码的重新设计提案。 |
| `POST /api/voice` | 将转录/文本转换为方向预设和行动项目。 |
| `POST /api/setup/start` | 本地唯一的 GitHub 克隆/安装/运行/捕获工作流。 |
| `POST /api/proof/apply` | 在一次性检查环境中应用候选补丁并验证。 |
| `POST /api/proof/revert` | 恢复检查环境。 |
| `GET /api/health/capture` | 检查 Playwright 捕获准备情况。 |
---
## 部署
最可靠的生产环境是托管 UI 加上独立的 Playwright 捕获后端。
| 层 | 平台 | 角色 |
|---|---|---|
| UI | Vercel | 快速的 Next.js 应用，报告，揭示，语音方向，重新设计草案 |
| 捕获 | Vultr，Render 或 Docker 主机 | Playwright + Chromium，用于实时 URL 诊断 |
| MCP | 本地 Cursor | 用于编辑器原生诊断和补丁交接的 Stdio 工具 |
在 Vercel 应用上设置 `TELL_CAPTURE_API_URL` 以指向捕获后端。GitHub 克隆和运行在公共主机上应保持禁用，并使用 `TELL_DISABLE_REPO_SETUP=1`。
部署指南：
- [混合和单平台部署](./docs/DEPLOY.md)
- [Vultr 捕获后端](./docs/DEPLOY-VULTR.md)
---
## 产品状态
已发布：
- 确定性捕获，指纹识别和 14 个检测器
- 具有安全回退的品位判决
- 具有前后对比的 Tell 报告
- 语音/文本艺术指导
- Cursor MCP 工具
- 公共 URL 捕获，带有离线报告回退
- 本地 GitHub 仓库设置运行器
- 基于源代码的重新设计提案
- 基于对比度的协调
- 多页面路由发现和每页扫描
- 候选补丁的离散视觉证明循环
接下来：
- 每个状态的证据缩略图，用于悬停，焦点和错误状态
- 可共享的托管报告链接
- 跨更多产品类别的更广泛的检测器黄金集合
---
## 贡献
欢迎贡献。最高影响力的新增功能是新的检测器，更好的证据视图和更强的源代码映射。
```bash
pnpm typecheck && pnpm test
```
`fixtures/generic-app/` 下的示例应用是故意作为输入数据，而不是产品本身。参见 [CONTRIBUTIONS.md](./CONTRIBUTIONS.md) 获取归属分解。
---
## 许可证
在 [MIT 许可证](./LICENSE) 下发布。
