SoulBrowser Docs

Appearance

浏览器工具系统 ​

本页整合旧 docs/BROWSER_TOOLS_IMPL.md 和 docs/TOOLS_REFERENCE.md，用于说明 SoulBrowser 的工具层是如何把高层任务转成可靠浏览器动作的。

分层结构 ​

工具系统可以概括成五层：

  1. Tool Registry
  2. Action Flow
  3. Action Gate
  4. Action Locator
  5. Action Primitives

最底层再往下就是 CDP Adapter 和实际 Chrome。

六大基础原语 ​

旧实现里最核心的是六个原语：

  • Navigate
  • Click
  • TypeText
  • Select
  • Scroll
  • Wait

这些原语的价值在于：高级流程再复杂，也最终应该落回有限、稳定、可验证的底层动作。

Locator 不是附属功能 ​

元素定位系统不是“找个 selector”这么简单，它要解决：

  • CSS 选择器不稳定
  • 文本变化
  • ARIA 信息不全
  • 页面重渲染后元素失效

所以定位通常需要多策略和自修复，而不能依赖单一规则。

Action Gate 的作用 ​

Action Gate 负责把动作执行前后的验证收进统一模型：

  • 执行前是否可见、可点击
  • 执行后页面是否真的变化
  • 是否收集到了足够证据
  • 是否需要等待稳定态

这层直接决定工具“看起来能跑”和“实际上可靠”之间的差异。

Wait 策略的重要性 ​

很多前端或执行问题，本质上都不是点击失败，而是等待策略错误：

  • 点得太早
  • 等得不够
  • 页面已经跳转但还没稳定
  • 验证发生在错误时机

所以 Wait 不是一个补丁动作，而是整套工具系统的可靠性基础。

高级工具的构建方式 ​

高级工具不应直接绕过原语层，而应：

text
high-level task
  -> flow orchestration
  -> locator + validation
  -> primitives
  -> CDP

这能保证：

  • 行为可观测
  • 错误更容易定位
  • 与前端任务状态输出更一致

参考的调试顺序 ​

排查工具执行问题时，优先顺序建议是：

  1. 参数有没有错
  2. locator 是否稳定
  3. action gate 前后验证是否合理
  4. wait tier 是否匹配页面节奏
  5. CDP 命令映射是否真的发出

相关页面 ​

SoulBrowser Documentation

Docs in monorepo