ironbee-express Vibe 项目

ironbee-express：把 LLM 从浏览器 agent 循环里拿掉的开源框架

ironbee-express 是一款基于 TypeSafe Jev 的目标驱动型浏览器 agent 框架，由 IronBee 团队开源。它的核心创新是默认情况下不把 LLM 放进执行循环：每一步决策由 Jev 模型在"页面已索引控件"中做一次选择（约 300ms），不生成文本、不发送截图，模型输出永远不会变成 selector、坐标或脚本——它只能指向"页面已经提供的"控件、选项或值。这从根本上避免了传统 Playwright/Selenium 类 agent 用 LLM 选坐标带来的脆弱性和幻觉。

在 IronBee 自家电商 demo 中，"登录、加入 12 件商品、移除 4 件"共 20 步，全程 12 秒。第二次重放该场景时无需任何模型决策，同样的 20 步只跑 4 秒——这是项目核心的"Record once, replay"机制。

核心功能

• Jev 决策模型：默认路径下每个步骤是一次控制级 Jev 选择，约 300ms，无需文本生成或截图。
• 结构化执行：动作只能命中页面已索引控件，避免坐标/选择器幻觉。
• Record once, replay：首跑记录场景后，重放无需模型决策；页面变化时从断点续跑并更新记录。
• 全链路验证：完成后审阅页面、API 响应、控制台错误、可选后端 span 与日志，输出 PASSED/FAILED 判定。
• 深度推理可选：遇到引擎卡壳时可挂载 Anthropic、OpenAI、OpenRouter 或 Claude Code / Codex CLI，让文本模型接管控制权。
• 人工接管：遇到社交登录、CAPTCHA、短信验证码时，UI 显示"Your turn"暂停，恢复后自动继续。
• 密钥隔离：密码与 token 通过引用键入，引擎与文本模型都不接收原值；模型视角下永远被遮罩。

技术实现

整个 agent 循环遵循 G → S → J → A → S → V → R 的状态机：

• G (Goal)：用户用一句话描述任务目标。
• S (Snapshot)：把页面 DOM 索引为"控件列表"。
• J (Jev decision)：一次请求从控件列表中挑出 operation + target。
• A (control_act)：guard → act → settle，由 IronBee DevTools 执行真实操作，返回下一个 snapshot。
• 循环直到 DONE，进入 V (Review)：同时检查页面最终态、API 响应、控制台日志、可选后端 trace。
• 输出 R (Verdict)：PASSED / FAILED + 证据链。

Jev 默认路径下完全无 LLM，单步约 300ms，20 步操作 12 秒。Demo 中"页面显示下单成功、但 API 返回 PAYMENT_FAILED"被判定为 FAILED，证据指向 GET /api/orders/131 → 200 但后端日志 notification-service 标记"Order #131 Could Not Be Processed"。挂载 IronBee 平台后还能把后端 span 与日志纳入审阅证据。

快速上手

git clone https://github.com/ironbee-ai/ironbee-express.git
cd ironbee-express
npm install
npm run build
echo 'TYPESAFE_API_KEY=…' > .env

# 启动 UI
npm run dev -- ui
# → http://127.0.0.1:15986

# 直接运行示例
npm run dev -- run --scenario eshop-add-to-cart --password password=demo123

# 自定义任务
npm run dev -- run 
  --url https://eshop.demo.ironbee.dev/ 
  --goal '登录，把 Sony WH-1000XM5 加购，使用收货地址 "..." 与卡号 4242... 下单，然后打开 My Orders' 
  --value email=demo@example.com --password password=demo123

适用人群

• 构建端到端 Web 测试或浏览器 agent 的工程师。
• 受 Playwright/Selenium 脆弱性困扰、希望引入验证层的团队。
• 对 LLM 幻觉与成本敏感的 AI 产品负责人。
• 研究 LLM-free agent 路径的学术团队。

出品方

IronBee 团队，TypeSafe AI 提供底层 Jev 模型。仓库采用 MIT 协议开源。配套的 IronBee 平台提供付费的"验证与情报层"，可把每次 agent 执行的视频、后端 trace、日志关联起来形成完整审计。

官方链接

• GitHub：https://github.com/ironbee-ai/ironbee-express
• IronBee 平台：https://ironbee.ai
• 文档：https://docs.typesafe.ai/introduction
• 许可证：MIT