ruflo-browser 会话即技能Session-as-Skill浏览器自动化架构实战RVF 认知容器 ruvector 轨迹 AgentDB 记忆 AIDefence 门禁【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/rufloruflo-browser 是 ruflo 插件体系中面向开放网页的浏览器自动化插件其核心思想是把每一次浏览器会话从一次性副作用升级为一级公民的可寻址、可回放、可联邦化工件RVF 认知容器。本文以插件 README 与 ADR-0001 会话即技能架构决策 为主线结合 browser-session-tools.ts 等源码实现完整讲解安装方式、RVF 会话容器结构、7 个生命周期命令、8 项技能、AgentDB 记忆命名空间、AIDefence 三道强制门禁、235 MCP 工具面以及从结构性冒烟测试到回放尖峰Replay Spike的验证体系。读完你可以在自己的 ruflo 环境中把跑一次浏览器变成沉淀一份可复用、可回放、可审计的知识资产。一、架构总览为什么需要 Session-as-Skill1.1 旧版v0.1.0的扁平化问题旧版 ruflo-browser 只是一层围绕 23 个 Playwright MCP 工具的薄包装mcp__plugin_ruflo-core_ruflo__browser_*。表面上可用测试、截图、抓取、会话列表都有但存在四个结构性问题会话是短暂的浏览器会话结束后一切消失没有一级的会话工件选择器不沉淀每个试过能用的选择器只存在于自由格式的记忆字符串里换一次 DOM 就失效交互不可见运行结束后无法回溯任何交互凭据风险隐式存在cookie、token 泄漏风险没有显式边界。1.2 核心决策RVF 即会话容器ADR-0001状态Proposed2026-05-04提出把 ruflo-browser 重构为session-as-skill架构每个浏览器会话是一级的、可回放、可审计的 RVF 容器内含一条 ruvector 轨迹技能是稳定 Playwright 原语之上的薄组合市场形态镜像 Browserbase 的 skills 仓库。这一决策的支点性假设load-bearing assumption是选择器 动作轨迹在 DOM 漂移下可回放依赖browser-selectors的嵌入相似度恢复。因此 ADR 在验收前强制要求一次预接受尖峰pre-Accept spike在 10 个漂移特征各异的站点上回放成功率≥80%达标才能把 ADR 从Proposed翻转为Accepted详见 验证体系。1.3 基座对齐ADR-122插件本身是用户可感知的技能层底层原语Ed25519 RVF 签名轨迹、因果图自愈、AIDefence 认证的 cookie 保管库、联邦 MCTS、Session Capsules、Workflow Compiler在claude-flow/browsernpm 包中发布由 v3 源码的 browser-session-tools.ts 与 browser-tools.ts 承载。二、安装在 ruflo 的插件市场中通过两条命令完成安装/plugin marketplace add ruvnet/ruflo /plugin install ruflo-browserruflo安装后需要保证以下运行期依赖可用/ruflo-browser doctor会逐一探测agent-browserPlaywright 浏览器驱动器或通过npx --yes agent-browser按需获取ruvectorCLI轨迹钩子 RVF 容器文档与 ADR 记录钉住ruvector0.2.25AgentDB 控制器browser-sessions等四个命名空间AIDefence三道门禁工具。实现细节实际 MCP 实现browser-session-tools.ts已将 ruvector 的 npx 回退钉钉升级为ruvector0.2.27并采用本地优先解析策略——若 CLI 依赖树中已存在本地 ruvector 包则直接用node bin派生其 bin避免每次会话为下载第二个ruvector 版本付出 2–8 秒冷启动每会话 4 次 shell-out。这与 README/ADR 中 0.2.25 的记载属于版本演进命令形态rvf create/compact/status/derive/segments、hooks trajectory-begin/step/end在 0.2.25 与 0.2.27 上均经验证。三、会话如何工作RVF 容器结构一个浏览器会话在会话开始时分配 RVF 容器在会话结束时提交rvf-id/ ├── manifest.yaml # URL、viewport、profile、runner、lineage父会话谱系 ├── trajectory.ndjson # 每个动作一行由 ruvector hooks trajectory-step 写入 ├── screenshots/step.png ├── snapshots/step.json # 按导航边界索引的可访问性树 ├── dom/ # 可选当传入 --with-dom 时生成 ├── cookies.json # 经 AIDefence 清洗后的 cookie └── findings.md # 测试裁决、抓取输出、注入隔离记录各槽位的生产者与说明见 ADR-0001 §1槽位生产者说明manifest.yaml会话开始钩子URL、viewport、profile、runner本地 Playwright 或远程、父会话谱系trajectory.ndjsonruvectorhooks trajectory-step每个 click/nav/extract 一行含 selector、ref、截图路径、毫秒时间戳screenshots/browser_screenshot动作后文件名遵循step-id.png约定snapshots/browser_snapshot导航后按导航边界索引的可访问性树dom/可选导航后传入--with-dom时的 HTML 转储cookies.json会话结束写入前经 AIDefence PII 扫描清洗findings.mdreviewer 技能测试失败、抓取结果或轨迹裁决的 Markdown 摘要会话引用从此是 RVF id而不是 Playwright 句柄。这是关键转折会话可以重新打开rvf ingest id、派生rvf derive、联邦共享rvf export、归档而不会丢失轨迹或认证状态。ADR-0001 明确指出这是从 Browserbase.o11y/run-id/旁车布局借来的模式区别在于他们的布局是丢在磁盘上的旁车文件而我们让它本身就是会话本体用rvf query id可查询。四、命令/ruflo-browser动词分发器commands/ruflo-browser.md被重写为按子命令分发的动词分发器/ruflo-browser ls [--query text] # 列出会话AgentDB 索引 /ruflo-browser show session-id # 显示 manifest trajectory 裁决 /ruflo-browser replay session-id # 重新驱动轨迹 /ruflo-browser export session-id # rvf export → tar.zst /ruflo-browser fork session-id # rvf derive → 新的谱系追踪会话 /ruflo-browser purge session-id # 销毁保留脱敏 manifest /ruflo-browser doctor # 检查 Playwright、MCP、AgentDB、AIDefence各动词的关键调用来自 commands/ruflo-browser.md动词底层调用说明ls [--query text] [--host host] [--verdict pass\|fail\|partial]memory list --namespace browser-sessions/memory search --namespace browser-sessions --query QUERY语义过滤基于 AgentDB活动会话还会调browser_session-listshow session-idnpx -y ruvector0.2.25 rvf status id.rvfrvf segments打印 manifest 最近 20 条轨迹 裁决再读trajectory.ndjson尾部与findings.mdreplay session-id [--url new-url] [--mutate json]调用browser-replay技能browser_session_replayMCP 工具就绪后改走该工具用于回归测试export session-id [-o path] [--federate]rvf export id.rvf -o path--federate时经ruflo-federation推送联邦共享fork session-id [--name new-name]rvf derive id.rvf new.rvf谱系追踪cookie、选择器、模板全部继承purge session-id [--keep-manifest]销毁 RVF 容器默认保留browser-sessions中的脱敏 manifest 使后续搜索仍可发现--no-keep-manifest完全擦除doctorbash plugins/ruflo-browser/scripts/smoke.sh 依赖探测探测browser_openagainstabout:blank、agentdb_health、aidefence_stats、npx -y ruvector0.2.25 --version五、技能目录8 个新技能 1 个弃用 shim每个技能目录遵循既有约定kebab-case 目录 带 frontmattername、description、argument-hint、allowed-tools的SKILL.md。allowed-tools 必须逐技能显式枚举——没有任何技能获得全部 23 个 MCP 浏览器工具这是从 Browserbase 的Bash-only 原语原则继承而来的克制。技能用途说明browser-record打开一个命名的、被追踪的会话到 RVF 容器原语其余技能都在其上组合browser-replay回放存储的轨迹可换 URL 或注入变异输入v0.2.0 架构的支点性假设browser-extract运行存储的browser-templates配方或一次性抽取PII 扫描browser-login驱动一次认证流清洗并保管 cookie 供复用借用 Browserbasecookie-sync模式browser-form-fill表单交互字段名 → 值映射集成browser-templatesbrowser-screenshot-diff两个会话截图的像素 DOM 差异视觉回归browser-auth-flow探测认证流的重定向泄漏、缺 CSRF、弱会话 cookie对抗式审计browser-testUI 测试配方组合browser-recordbrowser-replaybrowser-scrape是弃用 shim委托给browser-extract在插件 v0.3.0 移除。5.1 browser-record一切的原语skills/browser-record/SKILL.md 是插件内所有浏览器技能组合的基座不调用这个技能或其包装就不要在插件里跑浏览器会话。核心步骤# 1. 分配会话 id 与 RVF 容器session id 格式固定YYYYMMDD-HHMMSS-task-slug SID$(date %Y%m%d-%H%M%S)-${TASK_SLUG:-record} npx -y ruvector0.2.25 rvf create $SID.rvf --dimension 384 npx -y ruvector0.2.25 hooks trajectory-begin --session-id $SID --task $1 # 2. browser_open 打开 URL3. browser_snapshot 初始可访问性树 browser_screenshot 基线图 # 4. 每个交互前后记录轨迹步骤 npx -y ruvector0.2.25 hooks trajectory-step \ --session-id $SID --action click --args {selector:#login} --result ok # 5. 干净收尾 npx -y ruvector0.2.25 hooks trajectory-end --session-id $SID --verdict pass npx -y ruvector0.2.25 rvf compact $SID.rvf # 6. 在 AgentDB browser-sessions 下建立索引 npx -y claude-flow/clilatest memory store --namespace browser-sessions \ --key $SID --value {rvf_id:$SID,host:...,task:...,verdict:pass}注意事项--with-dom昂贵每次导航全量 HTML 转储默认关闭AIDefence 门禁发生在抽取时而非导航时——browser-record是原语脱敏责任在读取内容的技能browser-extract、browser-test。5.2 browser-replay回放支点skills/browser-replay/SKILL.md 直接声明自己是v0.2.0 架构的支点性假设ADR-0001 Verification §4 要求跨 10 个漂移特征各异的站点回放成功率 ≥80%之后提案才能从Proposed→Accepted。若回放不可靠把失败模式记录进findings.md并上报 ADR。回放流程rvf status定位源会话 → 读trajectory.ndjson每行{ts, action, args, selector, result}→browser_open开新浏览器 → 逐步骤分派对应 MCP 工具 →选择器未命中时不要立刻失败先在browser-selectors命名空间查询嵌入相似选择器并重试一次npx -y claude-flow/clilatest memory search --namespace browser-selectors \ --query host intent --limit 5裁决方式matched-step / total-step 比率默认容差阈值0.85--tolerance可配置裁决写入findings.md。ADR 明确提示Browserbase 明确不提供回放rrweb 会话回放已被弃用我们押注的是选择器嵌入恢复如果单步恢复需要超过一次重试那说明该站点需要重新录制而非回放。5.3 browser-extract模板化抽取 强制门禁skills/browser-extract/SKILL.md 取代旧browser-scrape带来三条新保证会话是已记录的 RVF 容器成功的抽取持久化为browser-templates每条字符串在存入 AgentDB 和回流模型前都经过 AIDefence。支持模板路径--template name从browser-templates检索配方与一次性路径优先browser_snapshot可访问性树批量查询回退browser_evaldocument.querySelectorAll。模板是host 作用域的——news_article模板不能跨站直接复用分页抽取要把游标持久化进轨迹步骤参数保证仅凭轨迹就可回放。5.4 browser-login 与 cookie 保管库skills/browser-login/SKILL.md 驱动一次认证流然后把结果 cookie 保管进browser-cookies供后续复用npx -y claude-flow/clilatest memory store --namespace browser-cookies \ --key host \ --value {vault_handle:opaque, expiry:iso, aidefence_verdict:safe}三条纪律绝不把原始 cookie、token、密码写进日志或轨迹认证 POST 的轨迹步骤只记录字段名 redacted占位符凭据来自用户或环境不从.env读取、不粘贴进轨迹参数MFA 时只捕获重定向结果不捕获验证码本身。注意此技能不是凭据存储方案——vault-handle 模式防御的是 AgentDB 泄漏而非代理环境的整体沦陷。5.5 其余技能速览browser-form-fill结构化字段映射{first_name: Ada, ...}有browser-templates条目时自动解析字段名 → CSS 选择器否则走可访问性快照填写值必须脱敏——轨迹只记录字段名 重定向占位符browser_type模拟按键与browser_fill程序化赋值语义不同需在轨迹步骤里记录用的是哪个遇到 CAPTCHA 必须上抛给用户禁止绕过。browser-screenshot-diff按step-id配对两个会话的截图与可访问性快照支持--mode pixel|dom|both像素 diff 报告mse、psnr和最大差异簇边界框默认阈值 0.02即 2% 像素DOM diff 在 Playwright 可访问性树上做节点级比较比 HTML diff 更稳定。该技能不计划提供browser_screenshot_diffMCP 工具直接在本地 RVF 工件上运行diff 裁决也写进新的 RVF 容器使 diff 本身可回放。browser-auth-flow对抗式认证审计--probes csrf,redirect,cookie,oauth四类探针——csrf 检查同源 token 字段redirect 监视跨源重定向携带认证状态cookie 逐一检查Secure/HttpOnly/SameSite/过期/熵并把每条过aidefence_scanoauth 验证state/nonce高熵且redirect_uri匹配注册回调域。输出结构化的findings.md供人工审查禁止自动处置。典型审计轨迹 15–40 步。browser-testUI 测试配方由browser-record录制browser-replay验证组合每个测试产出可回放 RVF 工件而非短暂运行--against prior-session-id可对基线跑browser-screenshot-diff。browser-intent自然语言层通过browser_actpage-agentADR-175执行点击登录按钮这类意图式指令当目标元素难以用选择器表达时使用会引入 LLM 延迟与成本已知精确选择器时仍应直接用browser_click/browser_fill。六、记忆层四个 AgentDB 命名空间命名空间键值用途browser-sessionsrvf-idmanifest 摘要 裁决 标签/ruflo-browser ls的会话索引browser-selectorshost:intent{selector, ref, snapshot-hash, last-success}通过嵌入相似度扛 DOM 漂移browser-templatestemplate-name带选择器链 后处理的抓取配方取代即兴记忆字符串browser-cookieshost声明门控的 cookie blob 过期 AIDefence 裁决免重认证复用 cookie原始 cookie 与 token 永远不会裸入 AgentDB——见 ADR-0001 §3。该层不假设加密存储encryption-at-rest敏感 blob原始 cookie、token必须由应用层在插入前包装、取回时解包browser-cookies命名空间定义了这种包装契约。这也对应 Browserbase--context-id持久上下文的模式差异他们的上下文活在 Browserbase 服务器上我们的活在 AgentDB 里受声明门控并可通过联邦共享。browser-agent.md中给出了写入侧约定会话结束时写{rvf_id, host, task, verdict, tags, created_at}成功点击/填写后写选择器{host, intent, selector, ref, snapshot_hash, last_success}成功抓取管道后写模板成功认证流后写 cookie 条目。同时有一条硬性纪律造新选择器之前必须先搜browser-selectors——命名空间记忆的全部意义在于选择器知识跨会话累积并经嵌入相似度扛住 DOM 漂移。七、AIDefence 门禁强制不可跳过三道门禁全部强制且位于 MCP 表面之下——Agent 无法通过换工具跳过它们存储前扫描Pre-storage scan每条抓取字符串在 AgentDB store 前必须通过aidefence_has_pii。命中以占位符脱敏并在会话 manifest 记pii_redactions: [{path, kind, count}]。Cookie 清洗Cookie sanitizationcookies.json落入 RVF 容器前先跑aidefence_scan标记高熵原始密钥长、高熵、无过期提议将其保管进browser-cookies声明门控取回而非嵌入会话。提示注入检查Prompt-injection check任何回流到 LLM 的抽取文本先过aidefence_is_safe触发注入裁决的页面内容隔离到findings.md绝不未脱敏抵达模型。ADR-118 升级高杠杆配合aidefence2.3.0升级状态 Proposed2026-05-14aidefence_is_safe的检测面大幅扩展——提示注入正则从恰好一个修饰词放宽到0–4 个修饰词窗口从而首次匹配经典前缀ignore all previous instructions家族新增角色劫持模式you are now …/act as …/pretend to be …与越狱标记DAN mode/developer mode/god mode/root mode。对浏览器抓取页面而言这是高杠杆升级——被抓取的网页是这些模式的高泄漏源。该 ADR 同时声明无 MCP 工具签名变更、aidefence_stats的total_mitigations从硬编码 0 改为基于AtomicU64的热路径计数器观察者永远不会看到低于真值的计数。browser-agent.md的强制条款若 AIDefence 未初始化必须拒绝运行并给出 doctor 修复指引——不存储、不向模型返回任何内容。八、MCP 表面23 个交互原语 5 个会话生命周期工具18 个既有交互原语位于 browser-tools.tsopen/close/click/type/fill/select/check/uncheck/hover/press/scroll/screenshot/snapshot/eval/wait/reload/back/forward另加 v0.2.0 新增的 5 个browser_session_*生命周期工具共 23 个。新增工具实现在 browser-session-tools.ts418 行已在 mcp-client.ts 注册工具用途实现要点源码确认browser_session_recordRVF 分配 ruvectortrajectory-beginagent-browser open返回 session id rvf path必填url、task可选session自动生成格式YYYYMMDDHHMMSS-slug、rvf_dir默认.ruflo/browser-sessionsruvector 本地优先解析缺失时npx -y ruvector0.2.27兜底browser_session_endtrajectory-endrvf compact AgentDB 索引到browser-sessionsverdict枚举pass/fail/partial映射为 ruvector 的--quality1/0.5/0pass 加--success索引失败非致命——RVF 容器才是真值源browser_session_replayRVF derive 子容器 返回轨迹步骤供调用方分派刻意保持为原语不内联回放引擎返回rvfStatus/rvfSegments并在nextStep中要求调用方逐条读trajectory.ndjson、分派browser_*工具、选择器未命中时查browser-selectors重试、最后以聚合裁决调browser_session_endbrowser_template_apply从browser-templatesAgentDB 命名空间取配方经memory retrieve --namespace browser-templates --key name返回配方 nextStep提示调用方分派并持久化新选择器browser_cookie_use从browser-cookies取不透明保管句柄原始 cookie 值永不返回——只返回vault句柄 过期 AIDefence 裁决原始值仅在浏览器进程内物化设计要点源码注释确认优雅降级缺失依赖无 ruvector、无 agent-browser、无 AgentDB 控制器时返回结构化success: false错误而非崩溃钉钉与子命令面RUVECTOR_PIN ruvector0.2.27rvf create/compact/status/derive/segments与hooks trajectory-begin/step/end的旗标已对照--help验证——例如trajectory-begin接受的是-c/--context-a/--agent而非文档示例中的--session-id/--taskrvf create仅接受-d/--dimension必填-m/--metric--kind为未知选项issue #2015 修复维度 384与工具链其他部分ONNX embedder AgentDB 向量索引的 MiniLM-L6 默认对齐browser_session_record的工具描述明确区分了使用边界JS 密集 SPA 抓取、登录流 cookie 复用、DOM 漂移回放、内容进入 Claude 前的 AIDefence PII 门禁这些场景才需要真实浏览器自动化静态 HTML 页面用原生 WebFetch 更快更省。九、验证体系冒烟测试与回放尖峰两类互补检查README §Verification9.1 结构性冒烟快速、离线bash plugins/ruflo-browser/scripts/smoke.sh # 预期绿灯13 passed, 0 failedsmoke.sh13 步验证插件结构健全性plugin.json版本 0.2.1 与新关键词rvf/replay/trajectory/agentdb/aidefence8 个技能目录齐全每个技能 frontmatter 含 name/description/allowed-toolsbrowser-scrape是标注弃用的 shim/ruflo-browser命令覆盖全部 7 个动词agent 引用 4 个 AgentDB 命名空间与 3 个 AIDefence 门禁及 trajectory 钩子ADR-0001 存在且为 Proposed 且标注支点性回放风险README 枚举 8 技能 动词5 个browser_session_*工具在 CLI 源码注册且browserSessionTools导入于 mcp-client.ts无任何技能授予通配符工具权限。9.2 回放尖峰交互式、在线、pre-Accept 门槛bash plugins/ruflo-browser/scripts/replay-spike.shreplay-spike.sh 对 SITES.txt 中每个 URL默认 10 个站点覆盖静态 / SPA 密集 / 频繁部署 / 认证墙 / 反机器人等不同漂移特征执行录制基线会话 → 派生子容器回放 → 比对动作序列的完整循环输出spike-results/timestamp/STATUS.md含每站点裁决与聚合回放率。ADR 阈值≥80%达标即翻转 ADR-0001 为Accepted低于阈值则提案降级为会话即审计日志回放与截图 diff 变成尽力而为而非支点。该尖峰不属于冒烟测试——运行它是刻意的审计步骤需要agent-browser或npx --yes agent-browser、ruvector0.2.25npx 自动获取、5 个生命周期 MCP 工具已接线、以及网络访问。脚本内注释明确rvf create需要--dimension 384且不支持--kind#2015。十、架构决策与边界声明架构决策记录ADR-0001 —— Adopt session-as-skill architecture for ruflo-browser状态Proposed其验证契约7 项编号测试会话生命周期、AgentDB 索引、AIDefence 门禁、回放、cookie 保管库、联邦、doctor被scripts/smoke.sh物化为 13 项结构性检查 独立回放尖峰。负向后果ADR §ConsequencesAgentDB 与 AIDefence 成为硬依赖doctor与 init 流程必须强制RVF 压缩每会话加 100–500ms 开销短抓取场景可用--no-rvf逃生口跨机器复用需要联邦导出/导入Browserbase 的托管能力反机器人、住宅代理、CAPTCHA 解决不被复制——本插件保持本地 Playwright 定位需要这些特性的用户应继续直接用 Browserbase本提案关乎架构而非功能对等。十一、相关插件生态ruflo-ruvector—— 轨迹钩子、SONA 模式蒸馏、MCP 工具ruflo-agentdb—— 支撑browser-sessions/browser-selectors/browser-templates/browser-cookies的控制器ruflo-aidefence—— PII / 提示注入门禁3-gate 契约与 ADR-118 升级ruflo-federation—— 经 RVF 导出的跨安装会话共享。许可MIT。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考