Reticle

Reticle 快速入门

「你的 AI Agent 说『完成』，Reticle 验证它是不是真的完成」——Reticle（reticlehq/reticle）定位为编码 Agent 的验收层：不做代码生成，专管「验证」。它驱动真实运行的应用、读取实际发生的事（网络请求、应用自身状态、控制台），回传 pass / fail / couldn't tell 与可定位到文件行的证据。TypeScript，2026-09-26 核验：GitHub 878★ / 149 fork，最近 push 2026-09-25（持续活跃），官网称月安装 24k+。

这是什么？适合谁？

Agent 编码工具有一个系统性盲区：「说完成了」不等于「真的完成了」。修好一个 bug 顺手弄坏昨天还能跑的流程、用 mock 数据假装接口正常、把「回归验证」全留给人类手工点击——Reticle 的作者把这组问题归因为一句话：没有任何东西在检查 Agent 的工作，除了你。Reticle 补的就是这一层：Agent 第一次验证某个流程（比如结账）时它录制下来，此后每次代码变更后自动重放该录制并给出确定性判定（同一输入同一判定，0% flake），证据链包含网络 trace、应用状态快照和出错的具体文件行号，Agent 拿到就能自己修。

适合人群：

• 重度使用 Claude Code / Cursor / MCP Agent 的开发者：Agent 改完代码后想要自动化的「验收」而不是自己当人肉测试套件
• QA 团队：把 Playwright 发布门禁之外的内循环（每次编辑后的回归检查）自动化
• 关心 AI 账单的团队：官方基准称重放整套 4 流程仅约 47 token（Playwright 重跑约 120k、DevTools 约 129k），约 2,500 倍成本差

不适合谁：不拥有应用源码的场景（Reticle 活在代码内部）；非 React/Next 框架（官方明示适配器还在路线图上）；需要像素级视觉回归或跨浏览器渲染测试的团队（官方明确列出这些是它输的地方）；想要给人看的大屏看板的团队（Agent 才是它的用户）。

准备工作

• 运行环境：React / Next.js 项目（2026-09-26 核验的适配范围）；Node.js 工具链
• 账号要求：SDK 开源免费（Apache-2.0）无需账号；托管平台 app.reticle.sh 免费档可起步（无需信用卡），团队功能走付费
• 时间预算：安装与跑通第一个流程约 10-15 分钟
• 前置知识：会用 npm/pnpm 装包；理解「Agent + MCP」的基本用法（Reticle 通过 MCP 与 Claude Code/Cursor 等集成）
• 替代方案：Playwright E2E 测试（发布门禁定位，需手写 spec 与选择器）；让 LLM 自己反复跑验证（贵且有 flake）；人工手点

快速上手

第一步：把 Reticle 交给你的 Agent

官方推荐方式是把一行指令粘给 Agent，让它自己安装 in-source SDK 并完成配置：

安装 Reticle 并配置好验证流程：https://github.com/reticlehq/reticle

Agent 会读取仓库文档自行安装，之后它每完成一处修改就可以向 Reticle 索要 pass/fail 证明。

第二步：录制第一个流程

在开发环境里正常操作一遍你要守护的流程（例如「下单支付」）。Reticle 记录 DOM、网络请求、应用状态与控制台信号——这次录制就是之后所有自动回归的底稿。

第三步：让 Agent 改代码并自动验证

对 Agent 下达修改指令（如「修复购物车合计计算」）。Agent 改完后 Reticle 自动重放录制的流程并回传判定：

• pass：流程核心断言（订单已创建、卡片只扣款一次、store 已更新、控制台无错误）全部通过
• fail：附网络 trace + 状态快照 + 出错文件行号（形如 onPay.tsx line 46）的「修复包」，Agent 直接据此修
• couldn't tell：证据不足时如实说明，不硬编结论

预期产出：每次代码变更后得到一份确定性验收判定，而不是「Agent 说它测过了」。

第四步：把重放进 CI / 每次提交

录制可重放且结果确定（官方称 0% flake），整套重放约 47 token，成本低到可以挂在每次 commit 上跑。

常见踩坑

1. 把 Reticle 当 Playwright 的替代品：两者跑在不同时刻——Playwright 是你发布前的门禁（手写 spec、CI 运行），Reticle 是 Agent 每次编辑后的内循环验证（录制重放、无需维护选择器）。官方 FAQ 的建议是两者共存。
2. 非 React/Next 项目硬上：官方明确承认这是当前边界，适配器在路线图上；先确认技术栈再采用。
3. 以为它能测「不是你的站点」：Reticle 活在应用源码内部（in-source SDK），只能验证你有权改动代码的应用，不要拿去测第三方网站。
4. 混淆开源范围与商业模式：可嵌入 SDK 是 Apache-2.0；服务端/CLI/MCP 包是 FSL-1.1-ALv2（source-available，两年后转 Apache-2.0）；企业功能需要 key。引用许可时要分清组件。
5. 忽视遥测开关：CLI 默认发送匿名使用事件（跑了什么命令、判定结果），安全敏感团队应第一时间执行 reticle telemetry disable。
6. 拿它做像素回归：官方在对比页明示 pixel regression 是它输的地方，这类需求仍需视觉回归工具。

常见问题 FAQ

Q1：和 Playwright 到底什么关系？

A：互补而非替代。Playwright 在你上线前跑手写的 E2E spec；Reticle 在 Agent 每次编辑后重放录制流程并读取 DOM 之外的真实程序状态（网络、store、控制台、React commits）。官方基准称在其 88 个种子 bug 注册表中 Reticle 抓到 86 个而 Playwright 抓到 60 个，差距集中在静默 500、UI 与 store 不同步、死处理器、重复提交这类「屏幕上看不出来」的 bug。

Q2：会不会把我的代码传到云端？

A：免费开发环路的发送策略是「什么都不发」——代码、DOM、网络流量、控制台输出、文件路径都不上传；SDK 仅限 dev/preview 且会被 tree-shake 出生产构建，本地桥接绑定 127.0.0.1 并带 token。Team 档只共享你选择共享的判定与流程。

Q3：重放为什么这么便宜？

A：重放走的是录制直接回放，没有模型在环路里，所以每次结果一致（0% flake）且只要约 47 token 的管理开销，而让 LLM 重新驱动每个流程要付十多万 token。

Q4：License 检查会不会因为官方服务挂了而阻塞构建？

A：不会。Key 用 Ed25519 签名并在本地验证，授权检查不联网。

Q5：免费的托管平台有什么？

A：每次运行的历史记录（重启也不丢）、套件托管（不占你本机）、失败分组（二十个红 run 归并为一个 bug）、团队共享同一套判定。

权限、安全、成本与限制

• 许可：SDK Apache-2.0；server/CLI/MCP 包 FSL-1.1-ALv2（source-available，禁止转售 Reticle 本体，两年后自动转 Apache-2.0）；企业功能需生产 key。
• 安全：dev/preview-only SDK，tree-shake 出生产构建；桥接绑定 127.0.0.1 + token；许可离线校验；CLI 匿名遥测可用 reticle telemetry disable 关闭；运行产物写在本地 .reticle 目录（原子写、有界保留）。
• 成本：SDK 与验证引擎免费；托管平台免费档起步、团队/企业按需谈价；重放约 47 token/套，内循环成本可控。
• 限制：当前仅支持 React/Next；不支持像素回归、跨浏览器渲染与你不拥有源码的站点；本文基于官网、GitHub API 与仓库文档核验（2026-09-26），未在真实项目中做长周期实测。

小技巧

1. 先挑一条最怕回归的核心业务流程（支付/下单）录制，见效最快，再逐步扩展录制集。
2. fail 判定附带的「修复包」（trace + 状态 + 文件行）直接喂给 Agent，官方消融实验称这一改动让修复环路工具调用减少 45%。
3. 官方基准 harness 提交在仓库里（pnpm bench 可复现），采购评估时自己跑一遍，输赢都看得到。
4. 用 couldn't tell 判定梳理「证据不足」的灰区流程，针对性补充断言，验收覆盖会越用越密。
5. 团队采用时先过一遍安全审查材料（官方专门为安全评审人准备了 tree-shaking/绑定/许可校验的可审计说明）。

进阶学习方向

• Playwright MCP 集成：把 Reticle 与 Playwright MCP 组合，形成「录制重放内循环 + 发布门禁」的双层验收。
• 多流程录制集治理：为不同业务域（结账、登录、搜索）建立独立录制集，挂到对应目录的 commit hook 上。
• 判定信号扩展：研究它对 DOM、网络、state、console 四类信号的断言方式，学它「读程序而不是看截图」的验证思路，迁移到自研验收工具。

参考链接

• 官网
• 官方仓库
• 文档站
• 托管平台