SoulBrowser Docs

Appearance

运行时模型 ​

本页把旧 docs/ARCHITECTURE.md、docs/ARCHITECTURE_DETAIL.md、docs/MODULE_DEEP_DIVE.md 中最影响开发联调的部分收敛成一张运行时地图。

目标 ​

回答四个问题：

  • 用户请求如何进入系统
  • 浏览器执行如何被组织
  • session 和 task 如何关联
  • 哪些模块是“事实源”

高层模型 ​

text
User / UI / API
  -> SoulBrowser Kernel
  -> Agent / Tool / Perception
  -> Browser Runtime (CDP / Local Bridge / Chrome)
  -> Session Snapshot / Task Status / Observations / Timeline

关键实体 ​

Session ​

Session 是浏览器运行态的载体，负责关联：

  • 当前浏览器上下文
  • 最后一次绑定的 task
  • 最近一帧截图
  • overlay 历史
  • SSE / snapshot 出口

对前端来说，session 通常是最稳定的实时状态入口。

Task ​

Task 是一次任务执行单元，负责承载：

  • 用户 prompt
  • 计划或循环执行结果
  • 步骤计数和状态
  • recent evidence / observations
  • 完成或失败结论

Page / Frame ​

浏览器侧的 page/frame 由 CDP 层管理，但前端通常不直接依赖它们，而是通过 session snapshot 间接消费。

推荐的数据事实源 ​

实际开发里，建议按下面优先级理解运行态：

  1. session snapshot
  2. task status
  3. task observations
  4. session live SSE

原因：

  • snapshot 最稳定，适合作为 UI 主状态源
  • task status 最适合作为步骤进度补链
  • observations 适合作为截图 fallback
  • SSE 适合提升实时性，但不适合作为唯一真相源

典型请求链路 ​

聊天任务 ​

text
POST /api/chat
  -> resolve session
  -> create task
  -> bind task to session
  -> invoke agent loop / planner
  -> emit task status, overlays, observations
  -> update session snapshot

前端右侧运行态 ​

text
selected or auto session
  -> /api/sessions or /api/sessions/:id
  -> derive session_status / last_task_id / frame / overlays
  -> /api/tasks/:task_id/status
  -> optional /api/tasks/:task_id/observations

为什么 session 和 task 要分开 ​

因为它们解决的是两种不同的问题：

  • session 关注“浏览器现在是什么状态”
  • task 关注“这次任务执行到哪里了”

一旦前端把这两者混成一个模糊对象，就很容易出现：

  • 页面有 session，但 task 没绑上
  • task 已成功，但右侧还空白
  • Auto 模式下不知道该跟踪哪个会话

模块层级 ​

更完整的 crate 分层见 分层架构，但从运行时角度可以粗略理解成：

  • Kernel：HTTP、路由、服务聚合
  • Agent：计划、循环、重试
  • Tools：动作原语和编排
  • Perception：结构/视觉/语义感知
  • Browser：CDP、local bridge、stealth
  • Infra：event store、policy、state、timeline

开发时的判断原则 ​

  • 如果问题表现为“右侧空白”，先看 session snapshot。
  • 如果问题表现为“步骤不对”，再看 task status 和 overlays。
  • 如果问题表现为“画面没更新”，再看 frame 和 observations。
  • 不要一上来就先怀疑 SSE。

相关页面 ​

SoulBrowser Documentation

Docs in monorepo