Reticle

一个以 MCP 工具形式交给编码 agent 调用的验证工具。开发期，应用里嵌一个很小的 SDK，它通过本地 WebSocket 上报 DOM、网络、控制台、路由与框架状态；agent 先看、再操作、再观察，最后断言「应该成立的事」，拿回来的判词是 yes、no 或 unknown，附带证据，以及该改的源文件与行号。它不靠截图评分：读的是无障碍树、网络日志、控制台和 store，那些「到不了像素」的故障正落在那里。它提供 CLI、MCP 服务器、Vite／Next／Babel 构建插件，以及 Electron、Tauri 和命令行这几类被验证对象的适配器；一条流程录一次之后可以不再经过模型重放，CI 门禁则不允许一个被流程覆盖的文件在没有通过判词的情况下过关。

谁做的账号 divshekhar 写了仓库 2,602 次提交中的 2,226 次，占全部的 86%；人类贡献者里排在第二的有 56 次。README 请读者去「book a call with the founders」，用的是复数；路线图里说话用的是「we」。1,890 次提交带共同作者尾注，其中 934 条写的是带一百万 token 上下文的 Claude Opus 5，其次是 Claude Opus 4.8 的 661 条，Cursor 只有 32 条。

1. 01

   仓库建于 2026-06-11，三天后 bridge 就能跑通一个来回

   仓库建于 2026-06-11，第一次提交在 2026-06-13，信息是「M0: project scaffold + working bridge round-trip」——一次就把脚手架和一个能应答的 socket 落了下来。到 2026-09-30 已有 2,602 次提交，最后一次的标题是「a daemon skew is told to the connection that announced it」（issue #1136）。按月看：建仓那个月 395 次，7 月 466 次，8 月 1,252 次，9 月 489 次。列出的二十个 release 从 2026-07-18 的 v2.1.0 到 2026-09-30 的 v3.4.0，大约四天一个，其中四个在最后十二天里；标签列表里还有一个 release 列表没有的 v3.0.0，所以从 2.14.0 跳到 3.1.0 时跳过了一个号。最后一天值得按顺序读：18:16 到 18:20 之间，作者提了三十个 issue，每个都点名一个文件、附一条「Done when」验收条件；18:25 打了 v3.4.0 的标签；提交一直持续到 18:42。其中两个在一小时内被外部的人认领——仓库本身也备好了这套流量：issue 模板、code owners、DCO 检查、治理文档、行为准则，以及 hacktoberfest 标签。706,454 字节的 changelog 由脚本拼装，测试则保证发布包与 Rust crate 的版本同步，同时不把「新增字段」当成版本偏差。

2. 02

   传感器放在页面里面，而不是站在旁边看

   定调的是一个 README 里的对照表：Playwright、DevTools 和浏览器类 agent 都站在浏览器外面往里看，这对你不拥有的站点是对的，对你自己在做的应用是错的，因为真正要命的 bug 根本到不了像素。所以应用自己带着传感器。开发期它调用 connect，默认连到 ws://localhost:4400/reticle 的 WebSocket，发送一条 HELLO，带上会话 id、协议版本，以及（如果配了）配对令牌；每个标签页各自生成 id，所以两个标签页不会撞车。SDK 随后装上 MutationObserver 看 DOM 变化、包住 fetch 与 XMLHttpRequest 看网络、挂上 console 钩子和 history 钩子看路由，再加上应用按名字主动注册的那几样——registerStore、registerCapabilities 与 signal——全部推进一个有界环形缓冲区：最近的历史随时可查，内存有上限。agent 调一个 MCP 工具，服务器把它变成一条走这条 socket 的命令，SDK 在真实页面里执行，再把结构化事件流回来。整条链上没有任何一处执行任意 JavaScript：固定的命令集只有看、操作、读状态和跳转，没有「执行这段 JS」这种工具。两个运行时的接缝是一个包而不是一句约定——凡是跨浏览器、bridge 和 agent 的字符串与结构，都只在 @reticlehq/core 里定义一次——而服务器会用这套 schema 校验每一条进来的消息，格式不对就断开连接，而不是让它流进逻辑里。

3. 03

   同一套协议也架在 Electron、Tauri 和命令行上

   桌面这一块是这个仓库不再是纯浏览器工具的地方。Electron 拿到一个住在主进程里的适配器：IPC 观察器加主进程截图，预加载脚本约 11 KB——渲染进程与特权进程之间那道边界就是这样变成证据的，README 也把这道边界点名为「只做浏览器的工具看不到」的东西。Tauri 拿到一套 Rust 截图后端：一个在所有 JavaScript 门禁之外的 crate，由专门的 CI job 编译，按操作系统各一个 capture 模块；另有一份由脚本生成的桌面契约文件，由测试守着。第三类 realm 处理命令行对象：它把进程拉起来并盯着它，不往里面塞任何代码，还自渲染一个终端 HUD。三者都听同一个协议包的话，而这个协议包的「对象」词汇表是刻意开放的——web、desktop、mobile、service、game、device，或者别的什么——理由是：一个必须改协议才能容纳一类新计算机的协议，是有保质期的。为这份通用性付出的代价就写在旁边：当被命名的那件事物被替换时，instance 必须变化；导航会整体作废证据，热更新只作废一部分；而两者都必须可上报。

4. 04

   文件与行号来自构建期，而 SDK 绝不会进生产包

   一句点名 src/checkout/PayButton.tsx 加行号的判词，价值不会超过那张映射表，而这张表是构建期盖上去的，不是运行时猜出来的：三个插件把 data-reticle-source 印进标记里——一个 Babel 插件、一个保留 SWC 并包住配置的 Next 适配器，以及 Vite 插件；Vite 这个还负责注入 connect 调用、探出开发服务器端口、写入配对令牌。@reticlehq/react 则把 DOM 节点映射到组件、再到源码位置，而它是刻意的可选项：项目自己写明，核心部分在没有源码映射那一半时也能工作。也正是同一个构建步骤让 SDK 永远不会随包发布——它只在开发服务器上生效，生产构建会把它换成一个惰性桩，运行时还有一道守卫，构建报告 NODE_ENV=production 时拒绝连接。这道守卫还顺带产出了一条维护者自己提给自己的错误建议：issue #1267 记录说，把 lease 指向一个已部署的 URL，会得到 sdk_never_dialled 以及「在那个目录里跑 reticle init」的提示，而这帮不上任何忙，因为那个桩是故意的。其余边界是以性质而非承诺写下的：bridge 只绑 127.0.0.1，应用用一个仅属主的令牌 ~/.reticle/pairing-token 与它配对，不带该令牌就拒绝绑到非回环地址，凡是能关掉某项安全控制的环节变量都只有一个具名常量，所以打错字不会静默地关掉鉴权；密码、令牌、API key 和卡号在到达 agent 之前就被换成 [REDACTED]。

5. 05

   yes、no、unknown——而看不见的地方也一并公开

   判词有三个值，重点在第三个：unknown 的意思是证据不足以判定，README 明确写着判词绝不是「悄悄地算通过」。证据本身分档——应用自己发出的 signal 最强，因为错误的元素伪造不出来；网络加路由加状态次之，在多数单页应用上不需要任何准备；DOM 或文本的存在感是最弱的那一档，工具会把人往别处推——而回答会说明它用的是哪一档。协议包把这种直觉变成了带编号的要求：证明某个后果的证据，不得来自执行该动作的那条通道；只有两条通道里至少有一条是独立的，才允许把不一致报告为故障；实现必须在连接时声明自己的通道；而读取未声明通道的断言必须是 unknown 而不是失败，因为「没人在看」和「事情没发生」会产出完全相同的空证据，意思却相反。它举的例子是 MCAS：三取二的传感器表决是一套正确的原则，却被实现成了只架在一个迎角叶片上；于是「一个只用散文写出规则、却不允许实现去声明独立性的协议，造出的是同一架飞机」。同一种反射也生出了那些小字：标签页在后台时，每个响应都会警告定时器、rAF 和指针手势可能静默失效；事件缓冲区发生淘汰时，会返回保留数、丢弃数，并注明此时一个否定结果可能是假否定；能力边界与强项并列公开——IndexedDB、Web Worker、closed shadow root 和跨域 iframe 目前看不见，而围绕单次动作的竞态被明确标为「部分支持」。支撑这套分档的测量也是同样写法：在一个确定性语料上，一个解析到错误元素的定位器能满足「存在」检查，却满足不了「后果」检查，而这个差别就是「88 个里有 1 个假绿」与 29 个的距离。

6. 06

   对外只挂九个工具，表里却有四十五个

   对外的工具面是一个预算决定，不是剩下的东西：MCP 会在每一轮把每个工具定义重新发给模型，所以工具列表是租金，不是买断的菜单。表里 45 个工具，agent 看得到九个，而其中只有两个能产出判词——一次驱动如果没有 reticle_act_and_wait 或 reticle_assert 收尾，就没有结果。其余大多数是被合并而不是被删掉，调用一个退休名字会得到替代它的那个调用。2026-09-16 从一个全新 daemon 上量到的数据是：默认工具面九个工具、17,663 字节；把全部工具都挂出去则是三十个工具、126,954 字节。有两个工具是被一次量出来的错误推回台前的：它们原本只能通过一个通用的 invoke 工具够到，于是一个登录表单被一次一个调用地驱动，因为「一个 agent 必须先知道它存在才会去调的工具，就是永远不会被调用的工具」。再往下削有地板：砍到八个工具时，真实 agent 的准确率可测量地掉了下去，而那条附注说这份读数已经旧到只能算「有日期的证据」而不是证明。预算是另一半，门禁则压在它上面：录下来的流程重放时不经过模型，47 个 token，而重新用模型驱动大约是 120,000 个；门禁要求每一次被改动波及的流程都有通过的产物覆盖，否则以非零退出——README 说这是唯一一个没人能靠「自己推理自己的 diff」满足的检查。