Appearance
Agent 与规划
本页整合旧 docs/AGENT_LLM_PLANNING.md 和 docs/CONVERSATION_CONTEXT.md 的高频结论，重点说明 Agent 是如何理解任务、如何规划、以及为什么需要上下文增强。
两种主要执行模式
SoulBrowser 当前主要支持两类 Agent 执行方式：
| 模式 | 说明 | 适用场景 |
|---|---|---|
| 计划-执行 | 先生成完整计划，再按步骤执行 | 结构化、确定性任务 |
| Agent Loop | 观察、思考、行动循环迭代 | 动态网页、需要适应环境变化的任务 |
Agent Loop 的实际意义
Agent Loop 更贴近真实网页环境，因为页面状态总在变化：
- 元素可能不存在
- 页面可能跳转
- 文案可能变化
- 某一步成功后，下一步上下文完全不同
所以它更像：
text
observe -> think -> act -> verify -> observe again核心组件
旧设计里比较稳定的几块包括：
AgentController- state formatter
- element tree builder
- LLM provider abstraction
- retry / recovery logic
这些组件共同解决的是：把浏览器当前状态转换成 LLM 能理解、又不会过于冗长的输入。
状态格式化
状态格式化的目标不是“把所有 DOM 都塞给 LLM”，而是：
- 给出当前页面最相关的信息
- 限制上下文长度
- 保持结构稳定
- 方便模型在失败后重试
这也是为什么 element tree、摘要信息、recent evidence 这些东西会同时存在。
对话上下文增强
旧 CONVERSATION_CONTEXT 文档要解决的问题是：
- 用户会说“继续上一步”
- 用户会省略主语或对象
- 用户期望系统记住之前任务结果
所以后续上下文增强的重点不是“保存所有历史”，而是：
- 注入必要的对话历史
- 缓存关键任务结果
- 做最基础的指代消解
- 明确区分历史上下文和当前指令
设计约束
- 历史上下文必须显式包裹，避免 prompt 间接注入。
- 失败恢复必须有上限，避免 Agent Loop 无休止重试。
- 页面状态摘要必须可观测，不要让模型输入变成黑盒。
开发时重点看什么
如果你在调 Agent 问题，优先看：
- prompt 组装逻辑
- state formatter 输出
- element tree 生成是否稳定
- 当前任务到底走的是 plan-execute 还是 agent loop
与前端运行态的关系
前端右侧显示的是 Agent 外显结果，而不是内部推理全文。
通常前端能看到的是：
- current step
- overlays
- task status
- screenshot / observation
所以如果 Agent 明明在跑但右侧没更新，问题常常不是 Agent 本身，而是 session/task 运行态链路。