5分钟跑通Reticle:从安装到拿到第一个AI验证判定(yes/no/unknown)的零基础教程
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,绝不假装变绿。
判定失败时,它还会附上具体的 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
这两条命令做了三件事:
- 把
reticle命令装到全局 PATH 上; - 把 Reticle 的 MCP 服务注册到你机器上的各个编程 agent(Claude Code、Cursor、VS Code 等);
- 自动生成并保存配对 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)。
第二步:接入你的应用(每个项目一次)
进入你应用的目录(有 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 验证判定——安装流程到此正式完成。注意它给的是一张"证据表",而不是一句"看起来没问题":请求发了几次、状态码多少、哪行代码负责这个按钮,全部附带。
没有 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 是绿,其他状态都会明确告诉你"我还判断不了"。一个不敢承认不确定的验证层,只是一个很自信的答案生成器。
卡住了?三招快速排查
| 你看到的现象 | 原因 | 修复 |
|---|---|---|
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 模型参与,确定性地跑完给你判定——今天的修复不可能悄悄弄坏上周的功能,成本也几乎可以忽略。
相关资源
- 官方快速上手(本教程的完整版):docs/quickstart.mdx
- 详细安装指南(逐文件讲解 init 改了什么):docs/getting-started.md
- 所有 MCP 工具说明:docs/tools/overview.mdx
verify命令完整参考:docs/cli/verify.mdx- 安装脚本(macOS/Linux 一条命令装好):install/install.sh
- AI agent 应遵守的接入规则:SKILL.md
- 项目总览与命令速查表:README.md
5 分钟,两条命令,一句话——现在你的 AI agent 说"完成了"时,你可以要它拿证据来。



