5分钟跑通Reticle:从安装到拿到第一个AI验证判定(yes/no/unknown)的零基础教程

原创2026-10-13 13:58:54216 阅读

5分钟跑通Reticle:从安装到拿到第一个AI验证判定(yes/no/unknown)的零基础教程

Reticle 是一个面向 AI 编程代理的运行时验证工具:它把一个小 SDK 装进你的应用内部,让 AI agent 能直接读到真实运行中的网络请求、应用状态和 console 日志,并给出带证据的 yes / no / unknown 验证判定。本教程带你 5 分钟从零完成 Reticle 安装、接入本地项目,并拿到第一个 AI 验证判定——全程只需两条命令和一句自然语言。

Reticle 解决什么问题?

AI agent 写完代码后通常会假设它成功了,然后继续往下做——它并不会真的打开你的应用看一眼。于是"按钮点击没反应""接口悄悄返回 500""状态和屏幕显示不一致"这类问题,往往要等你手动点一圈才发现。

Reticle 的思路是:验证必须来自运行中的应用本身。它从应用内部读出"程序真相",每次检查都以一个判定结尾——而且只有 yes 才算通过,判定不了就老老实实说 unknown,绝不假装变绿。

Reticle AI验证工具:页面看起来正常,底层的mock数据、死点击和隐藏的500错误被运行时验证捕获

判定失败时,它还会附上具体的 file:line(比如 src/checkout/PayButton.tsx:42),AI agent 能直接打开那个文件去修——而不是丢给你一张截图让你自己找。

准备工作:3样东西就够了

需要 说明
Node 20.11+ 用 node -v 检查版本,没有的话先装一个 Node
一个本地能跑的 Web 应用 自带 dev server 的即可(React/Vue/Next.js 等均可)
一个支持 MCP 的编程 agent Claude Code、Cursor、Windsurf、VS Code 等

📌 安装前先看一眼:Reticle 的 SDK 只在开发环境生效,生产构建中会被完全剥离,桥接服务也只监听 127.0.0.1,你的应用数据默认不出本机。

第一步:安装 Reticle CLI(每台机器一次)

在打开 AI agent 之前的终端里执行:

npm install -g @reticlehq/server
reticle setup mcp

这两条命令做了三件事:

  1. 把 reticle 命令装到全局 PATH 上;
  2. 把 Reticle 的 MCP 服务注册到你机器上的各个编程 agent(Claude Code、Cursor、VS Code 等);
  3. 自动生成并保存配对 token(存于 ~/.reticle/,仅本机可读)。

✅ 成功的标志:命令结束并提示"Reticle is installed on this machine. It is not in your app yet."——此时你的项目还没接入,这正是第二步要做的。

💡 不想全局安装?所有命令都可以 npx @reticlehq/server <command> 的形式运行,效果完全一样。

想先看看效果再接入?运行 reticle tutorial --run,Reticle 会驱动它自带的演示应用走完一轮完整验证,不碰你的任何项目(详见 docs/cli/tutorial.mdx)。

Reticle replay flow:LLM重放每次烧token,而flow记录一次后确定性地replay,零抖动直接产出verdict

第二步:接入你的应用(每个项目一次)

进入你应用的目录(有 package.json 的那层),运行:

reticle init

它会自动检测你的框架和包管理器,然后:

  • 安装两个 dev 依赖:框架适配器(如 @reticlehq/react)和构建插件(如 @reticlehq/vite-plugin);
  • 写入 .reticle.json(记录框架、项目 id 和本地桥接端口,默认 4400);
  • 往你的构建配置里加一行插件,开发模式下自动完成 SDK 连接;
  • 生成开发专用的 reticle-dev 文件,并给你的 agent 规则文件(CLAUDE.md/AGENTS.md)追加"用 Reticle 验证"的约定;
  • 启动你的 dev server、打开应用,并等待一次真实连接——这条连接就是接入成功的证明。

几个常用参数:

reticle init --dry-run     # 只打印改动计划,不写任何文件
reticle init --app apps/web   # monorepo:指定要接入哪个应用

✅ 成功的标志:init 逐条列出它改动的文件,并提示应用已连接。之后随时可以用 reticle status 复查。

⚠️ 最常见的一个坑:如果你的 dev server 在 init 之前就开着,它读到的是改动前的构建配置——重启 dev server 并刷新页面即可。

第三步:重启 AI agent,用一句话拿到第一个判定

Reticle 的工具是在 agent 启动时加载的,所以安装完成后记得重启一次 agent,然后在你的应用目录里打开它,用大白话说一个真实场景:

"用 Reticle 验证一下注册流程。"

agent 会自己调用 reticle_session 找到你的应用,点击、填写,并带着"预期结果"发起检查,最后返回类似这样的判定:

{
  "verified": "yes",
  "effect": {
    "action": "click",
    "name": "Sign up",
    "source": { "file": "src/SignUp.tsx", "line": 42 }
  },
  "verdict": {
    "pass": true,
    "evidence": { "method": "POST", "url": "http://localhost:5173/api/signup", "status": 201 }
  }
}

恭喜,这就是你的第一个 AI 验证判定——安装流程到此正式完成。注意它给的是一张"证据表",而不是一句"看起来没问题":请求发了几次、状态码多少、哪行代码负责这个按钮,全部附带。

Reticle act_and_wait 真实判定结果注解:verified、source定位、请求evidence、请求计数、状态diff与signal一次看懂

没有 agent 在场时,终端也能对"页面此刻的样子"做一次单点检查(只有通过时退出码才是 0):

reticle verify http://localhost:5173 --expect '{"kind":"element","query":{"role":"heading","name":"Welcome"},"state":"visible"}'

读懂判定:yes / no / unknown 到底是什么意思

判定 含义 该怎么处理
yes 你声明的预期确实发生了,证据已附上 ✅ 唯一的"通过"
no 没发生——这就是一次发现,附带要修的文件和行号 交给 agent 去修,再验证
unknown Reticle 驱动了应用但判断不了 ⚠️ 不是通过!按"无法确认"上报
no-fault 根本没声明要证明什么 给检查补一个预期条件(until)

这正是 Reticle 的设计哲学:只有 yes 是绿,其他状态都会明确告诉你"我还判断不了"。一个不敢承认不确定的验证层,只是一个很自信的答案生成器。

Reticle从应用内部捕获失败,把file:line定位证据作为repair packet交给coding agent修复

卡住了?三招快速排查

你看到的现象 原因 修复
agent 说找不到 reticle_* 工具 agent 在 Reticle 装好前就启动了 重启 agent 一次
"no browser session connected" dev server 在 init 前就开着,页面里没有 SDK 重启 dev server,硬刷新页面
浏览器报 websocket 连不上 应用和 Reticle 端口不一致 用 reticle({ port: 4400 }) 或 RETICLE_PORT 显式对齐
其他任何情况 — 一条命令体检:reticle doctor(检查浏览器、后台服务、端口)

完整排错清单见 docs/getting-started.md 的 Troubleshooting 一节。

下一步:把一次性检查变成 CI 里的回归闸门

你在 agent 里跑过的每一次带检查的驱动,都会自动保存为一个 flow(存在 .reticle/flows/,可提交进 git)。之后:

reticle verify http://localhost:5173     # 无模型重放所有已保存flow,全部通过才退出0
reticle gate --since HEAD~1             # CI:改动触及过的flow必须有一次通过的运行

重放时没有任何 AI 模型参与,确定性地跑完给你判定——今天的修复不可能悄悄弄坏上周的功能,成本也几乎可以忽略。

相关资源

5 分钟,两条命令,一句话——现在你的 AI agent 说"完成了"时,你可以要它拿证据来。

登录后查看全文
reticle