后端开发

本页把旧 docs/QUICK_START.md、docs/TECHNICAL_DOCUMENTATION.md 和部分架构说明收敛成后端开发入口，目标是回答三个问题：

• 服务怎么启动
• 后端由哪些核心模块组成
• 开发时先看哪些文件

启动方式

本地开发最常见的是直接启动 soulbrowser 服务：

cargo run --bin soulbrowser -- serve

如果要关闭鉴权做联调：

SOUL_EXECUTION_MODE=local SOULBROWSER_AUTH_DISABLED=1 cargo run --bin soulbrowser -- serve --disable-auth

常见联调组合：

• 后端：cargo run --bin soulbrowser -- serve
• 新前端：cd web-console-dx && trunk serve
• 文档站：cd docs-site && npm run dev

核心运行时

当前后端主入口仍然以 soulbrowser-kernel 为核心，职责包括：

• HTTP 路由与中间件
• 会话管理
• 任务调度与执行绑定
• Chat API 和 Agent Loop 入口
• 运行态快照、实时流、任务状态输出

最常读的文件：

• crates/soulbrowser-kernel/src/kernel.rs
• crates/soulbrowser-kernel/src/server/router.rs
• crates/soulbrowser-kernel/src/server/router/chat.rs
• crates/soulbrowser-kernel/src/server/router/sessions.rs
• crates/soulbrowser-kernel/src/server/router/tasks.rs
• crates/soulbrowser-kernel/src/sessions/service.rs

工作区结构

项目是一个 Rust workspace，主要分成几类 crate：

类型	说明	典型模块
Runtime	直接承载服务进程和路由	soulbrowser-kernel
Agent	任务规划与循环执行	agent-core, soulbrowser-agent
Browser	浏览器连接、动作和桥接	cdp-adapter, local-bridge, soulbrowser-tools
Perception	结构、视觉、语义感知	perceiver-*
Infra	状态、事件、策略、存储	state-center, event-store, policy-center
Product services	认证、计费、记忆等	auth, billing, memory-center

后端请求主链路

最常见的请求流是：

HTTP Request
  -> Router / Middleware
  -> Auth / Billing / Validation
  -> Chat or Session/Task Handler
  -> Scheduler / Agent / Tool Execution
  -> Session Snapshot / Task Status / SSE

对聊天任务来说，核心链路通常是：

/api/chat
  -> create or reuse session
  -> create task
  -> bind task to session
  -> agent loop executes
  -> session snapshot / task status / observations update

开发时优先理解的对象

Session

会话是右侧运行态和浏览器上下文的锚点，负责承载：

• status
• last_task_id
• last_frame
• overlays
• live_path

Task

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

• prompt
• step_count
• success / failed
• status snapshot
• observations / evidence

Observation / Overlay

• observation 更偏证据和截图
• overlay 更偏步骤和 Agent 思考轨迹

这也是前端右侧实时面板最关键的两类数据。

推荐阅读顺序

1. 先读 快速开始
2. 再读 系统概览
3. 接着看 Agent 与规划
4. 需要排查会话或任务时看 Chat API、Sessions API、Tasks API

开发约束

• 新接口尽量保证 /api/chat、/api/sessions/:id、/api/tasks/:id/status 之间的契约稳定。
• 不要让前端靠多个模糊字段猜运行态，优先提供单一事实源。
• 增加运行态数据时，优先考虑是否能直接挂到 session snapshot，而不是再新开一条旁路接口。

相关页面

• 系统概览
• 分层架构
• 运行时模型
• 前端开发