内置浏览器（Desktop Browser）
自 v0.8.7 起，Windows 桌面应用提供侧栏 浏览器 视图：在应用内打开页面，并让 Agent 通过 browser_* 工具读页、点击与本地预览。
仅桌面。
zagens-tui/ CLI 没有 Browser 宿主；Agent 调用时会返回browser_host_missing，需先在桌面打开浏览器视图。
打开方式
| 入口 | 说明 |
|---|---|
| 图标栏 浏览器 | 打开 Browser 面板 |
| Ctrl+Shift+B | 快捷键打开并聚焦 |
| 聊天中的 http(s) 链接 | 默认在应用内打开；右键可「在系统浏览器打开」 |
地址栏支持前进 / 后退 / 刷新。形态可选：自动（优先嵌入） / 嵌入侧栏 / 独立窗口。
Agent 工具
| 工具 | 用途 |
|---|---|
browser_navigate |
导航到 URL（回环免审批；外站弹审批卡） |
browser_snapshot |
可见文本 + 无障碍树；稳定元素 ref（role:slug:nth）；可选截图 |
browser_get_text |
标题与可见文本（snapshot 子集） |
browser_console_tail |
页面控制台缓冲（导航时清空） |
browser_click / browser_type / browser_scroll |
按 snapshot ref 交互（默认需审批） |
browser_wait |
等待 text / ref / selector / load |
browser_start_preview |
读取工作区 .zagens/preview.json，起本地服务并导航 |
推荐流程：browser_navigate → browser_wait → browser_snapshot → 按 ref 点击/输入。
审批与 YOLO
- 外站
browser_navigate：默认审批卡；通过后可写入会话域名 allowlist（「允许当前域名」）。 - 回环（
localhost/127.0.0.1）与工作区内file://：通常免外站审批。 - 点击 / 输入 / 滚动：默认审批，与全局「自动批准工具」解耦。
browser_yolo：仅放宽 Browser 写入类操作；可在面板、~/.zagens/config.toml的[browser] yolo，或环境变量ZAGENS_BROWSER_YOLO开启。
偏好持久化在 ~/.zagens/browser/prefs.json（旧版 AppData 路径会自动迁移）。
本地 Preview（.zagens/preview.json）
工作区可放置：
{
"command": "npm run dev",
"cwd": ".",
"url": "http://127.0.0.1:5173",
"ready_pattern": "Local:"
}
面板按钮 起 preview.json，或让 Agent 调用 browser_start_preview：启动命令 → 等待 ready_pattern（可选 ready_regex）→ 导航到 url。
与「抓取网页」的区别
| 内置浏览器 | fetch_url / web.run |
|
|---|---|---|
| 宿主 | Desktop Browser 面板 | Runtime 网络请求 |
| 交互 | 可点击、输入、等 DOM | 无真实页面操控 |
| 本地 SPA | 适合 localhost 预览 | 不适合驱动前端 |
联网搜索仍用 网络工具；真页面操控用本页。
建议
- Agent 报
browser_host_missing时，先打开浏览器视图再重试。 - 外站自动化前确认审批策略；勿轻易开启
browser_yolo。 - HTML 静态预览见文件预览；完整交互站点用 Browser。