兰 亭 墨 苑

期货 · 量化 · AI · 终身学习

《看得见的 Agent 浏览器——dsh-ego-browser 与 DSH 生

2026年9月30日
69 分钟阅读
#202610

《看得见的 Agent 浏览器——dsh-ego-browser 与 DSH 生态深度手册》

目录

第一编 原理篇

  • 第1章 缘起：DSH 生态里的那块空白
  • 第2章 DSH 生态全景：一切皆插件（★重点章）
  • 第3章 三个 ego：ego-lite / ego-browser / dsh-ego-browser
  • 第4章 引擎原理：Space 隔离与登录态复用
  • 第5章 眼睛原理：页面快照 Snapshot
  • 第6章 手原理：CDP 直连与 JS 工具链
  • 第7章 大脑原理：learnings 与经验积累
  • 第8章 看得见的原理：观察窗与 self-observation
  • 第9章 可靠的原理：自愈、守卫与兜底

第二编 工程篇

  • 第10章 安装与首次运行
  • 第11章 ego_* 工具全景
  • 第12章 登录态：导入、持久化与接管
  • 第13章 观察窗工程：双后端与侧边栏集成
  • 第14章 实战三例：文献抓取 / 表单登录 / QA 冒烟
  • 第15章 架构走读：worker、cast-server 与 client
  • 第16章 二次开发：在 DSH 生态里扩展 ego
  • 第17章 生态坐标与选型

序言：这本书想讲清楚的一件事

DeepSeek Harness（DSH）发布时喊出一句口号：一切皆插件。模型、工具、会话、界面、Agent Loop 本身都可以被插件替换和重组。可当你真的把一个 agent 放进 DSH 跑起来，会发现最日常的一个需求——“去网页上干点活”——恰恰是插件体系里最难的一块拼图。

原因不在 DSH，而在浏览器本身。通用浏览器不是为 agent 设计的，而 Web 上大量有价值的交互——登录态、验证码、动态渲染、需要真人会话的站点——只有真浏览器能面对。纯文本工具（爬虫、API）绕不开这些墙，通用自动化框架（Puppeteer 系）又把人挡在外面：它要抢你的窗口、复不进来你的登录，还会把你的标签页弄得一团糟。

本书主线是一条清晰的解决路径：ego-lite（给 AI 和真人共用的 Chromium 引擎）→ ego-browser（开源的连接层）→ dsh-ego-browser（把前两者变成 DSH 生态一等公民的插件）。三者合起来回答一个问题：怎么让 agent 用你已登录的浏览器干活，而你不被打扰、还随时看得见、随时接得了手。

这本书只讲一件事：看得见，才谈得上放心；放心，agent 才敢真正替你上工。

第一编 原理篇

第1章 缘起：DSH 生态里的那块空白

DSH 的插件生态爆发得惊人：2026 年 8 月 13 日开源，三天内社区索引就列出 616 个插件；此后规模一路膨胀——从“必装清单”时代的 900 多个，到内置插件市场收录 2300+、2466 款，再到 Plugin Hub 挂出 4800+ 条目的阶段，社区统计口径甚至出现过“插件仓库破万”的说法。增长曲线像是一场持续的补课——官方底座只给骨架，能力全靠社区插件长出来。

但补课清单里，浏览器自动化一直是最特殊的一门。别的缺口（界面、视觉、记忆、通知）是“官方没做、社区补上”；浏览器这门的难点是模型先天看不见网页。

一个 agent 要“打开知网、翻页、下载 PDF”，摆在他面前的无非三条路：

  1. 爬虫与 API——能拿到静态 HTML，但撞上登录墙、验证码、动态渲染就死；你的账号 Cookie 它用不上，站点的反爬逻辑它扛不住。
  2. 无头浏览器框架——技术上行，但它是“通往浏览器的桥，而不是浏览器本身”：需要单独驱动一个实例，你的登录数据很少能原样带过去，连接不稳定，人和 agent 还得抢同一个浏览器的控制权。
  3. 让 agent 用“你的”浏览器——真正的登录态、真正的 Cookie、真的能过验证码，但代价是：你正在用的浏览器被占走、窗口被抢、内存被吃，人机互相踩踏。

这正是 ego 系（CitroLabs 的 ego-lite）切入的原始位置。它把问题从“给 agent 开个浏览器”换成“人机共用一个浏览器，但各占一个隔间”：agent 在独立的 Space（隔离工作区）里跑任务，你照常用你的标签页，你的鼠标留在原地；同时它继承了 Chrome 的登录态、Cookie、书签与扩展。这也正是 DSH 生态里后来冒出两条浏览器路线的分野——我们在第2章展开。

这一章可以浓缩成一个判断：agent 要真正接手网页世界，缺的不是更强的爬虫，而是一个能共用、能看见、能接手的浏览器。 ego 系选的就是这条路。

第2章 DSH 生态全景：一切皆插件（★重点章）

要理解 dsh-ego-browser，先理解它生长的土壤。DSH 不只开源了一个工具，它开源了一套可组合的 Agent 运行系统：Cordis 运行层负责安全地加载、卸载、重组插件，模型之外的上下文、工具、安全与恢复骨架全部被公开成可重组的插件树。

四个概念先分清（这是全书反复要用到的坐标）：

  • Plugin（插件）：最小能力单元，连 Agent Loop 本身也只是插件。
  • Bundle（功能包）：一组插件的装配，官方提供 Base、Web、Headless 三个官方 Bundle。
  • Profile（档案）：社区插件按 Profile 安装——Profile 是最小实验舱，装坏了一个不影响其他档案。
  • Preset（预设）：决定一次会话以什么 Agent 配置进入。

官方仓库体量：238 个工作区、219 个功能包，Host 平面与 Agent 平面分层。官方插件包统一 @deepseek-ai/dsh-* 前缀；凡不在这个前缀下、不随 dsh 安装分发的，都属于社区插件。

去哪里找插件，2026 年夏天大致有四条路：

入口 性质 规模
dsh-market DSH 内置可视化插件市场，浏览/搜索/一键安装，热更新、零遥测 2466 款
DSH Plugin Hub / dsh-plugin.org 官方渠道之外的集中市场 4800+
dshfind / DSHPlugin registry 带安装命令、兼容性证据与安全信号的注册表 数千级
awesome-dsh-plugin 社区精选列表，20+ 品类，只收可 dsh plugin add 安装的 200+ 起步

安全边界要记得：dsh plugin add 安装社区插件，等同于在你机器上以你的权限运行第三方代码，收录 ≠ 安全审查通过；白皮书也强调“工具沙箱不能自动覆盖宿主插件”——第三方插件运行在宿主里，审查清单是装任何插件前的必修课。

浏览器自动化在这片生态里的两条路线，恰好是理解本书主线的最好入口：

  • 路线A：操作你正在登录的 Chrome——代表插件是 Lum1104/dsh-browser：直接克隆仓库、跑安装脚本、把扩展装进你日常的 Chrome，让 agent 在你的真实登录态下干活。优点是零额外浏览器；缺点是它占用的就是你的浏览器——你浏览，它操作，同一个窗口里人机共舞，摩擦在所难免。
  • 路线B：给 agent 一个独立的浏览器——代表插件就是 Fisfzy/dsh-ego-browser：把 ego-lite（人机共用的 Chromium）接入 DSH，agent 有自己的 Space，不碰你的窗口，但同样复用你导入的登录态。

两条路线的取舍，本质是“共享同一个浏览器进程”还是“共享登录态、隔离工作空间”。本书选择路线B，因为它在“不打扰你”这一点上走得更彻底，且自带观察窗——下一章我们把这条路上的三个 ego 拆开看。

第3章 三个 ego：引擎、连接层、插件

ego 系是三层结构，很多人把它们当成一个东西，其实各司其职、缺一不可。

第一层：ego-lite（引擎层，CitroLabs 出品）

这是“给 AI Agent 用的 Chromium”浏览器本体。核心设计：

  • Space 隔离：每个 agent 一个完全隔离的工作区，人在前台浏览、agent 后台干活，互不干扰；同一个浏览器里可并行跑多个 Space（Claude Code 填 10 个客户线索、Codex 爬 5 个竞品站，互不冲突）。
  • 复用登录态：首次启动问一句“是否迁移 Chrome 数据”，同意后 agent 直接继承你的登录、Cookie、扩展、书签——登录摩擦归零。
  • Code-based 而非 CLI：暴露给 agent 的能力是可直接调用的 JavaScript 函数，agent 用“写代码”的方式一次组合多步任务，而不是“调两条命令→看结果→再调两条命令”的循环，复杂工作流更快、token 更省。
  • 最强快照：引擎级定制产出的页面快照，能把深层嵌套 iframe 也结构化成文本——文本模型“看见”网页就靠它。

代价与边界：目前仅原生支持 macOS，Windows 在内测，Linux 在路线图上。

第二层：ego-browser（连接层，开源 harness）

开源（MIT）的 Node.js CDP 浏览器自动化运行时，通过 globalThis.ego 绑定驱动 ego-lite，暴露一套 compact 的 snapshot/ref 工作流，并叠加“按站点整理的学习经验（learnings）”。技术要点：直接通过 Chrome DevTools Protocol（CDP）控制浏览器，不依赖 Puppeteer 或 Playwright，解析只用 acorn；核心源码按能力拆分模块（指针、键盘、导航、快照、等待、文件上传），学习子系统把按站点整理的经验存为可复用工具。

它还有一个画饼成真的功能：经验积累——每次成功的浏览器操作被提炼成可复用工具与工作流，同类任务后续最快快 5 倍。

第三层：dsh-ego-browser（宿主层，Fisfzy 维护）

这是本书主线。它把 ego-lite 的浏览器能力变成 DSH 里一组可确定性调用的 ego_* 工具（README 时代从 13 个工具起步，当前源码注册 32 个，最新 README 写作 33 个），并配一套实时观察前端口：SSE 推流、标签条、历史抽屉、缩放拖拽、监控窗鼠标直接接管真实浏览器。

它的三个不可替代的价值：

  1. 开箱即用：插件包内置 ego 运行时，无需克隆官方仓库、无需手动构建，--no-sandbox wrapper 随包自带，root / Docker / 无显示器环境一键跑。
  2. 看得见、控得住：同类插件把 ego-lite 接进 DSH 只做了 3 个工具（run/help/status），浏览器仍是后台黑盒；dsh-ego-browser 把黑盒打开，观察窗实时推流、且能直接驱动 agent 正在用的那个浏览器。
  3. self-observation：agent 用的就是这一个 Chromium——连它操作 DSH 自身界面（管理会话、调设置、看任务板）时，观察窗也全程可见、可接手。

一句话总结三层关系：ego-lite 是发动机，ego-browser 是变速箱，dsh-ego-browser 是把它装进 DSH 这台车、并给驾驶员装上仪表盘和副驾刹车的那一层。 这也是全书以它为主线的理由——前两层在别处也能跑，但只有第三层让“DSH 生态”和“看得见的 agent 浏览器”真正合体。

第4章 引擎原理：Space 隔离与登录态复用

上一章说 ego-lite 是发动机。这一章拆发动机的两个核心部件：Space 隔离和登录态复用。它们合起来回答了全书最关键的一个产品判断——agent 浏览器应该以什么方式和“你的浏览器”共存。

4.1 三种共存的姿势

想让 agent 用真浏览器干活，业界有三种姿势：

  1. 接管：agent 直接驱动你正在用的浏览器。你最熟悉，也最痛——窗口被抢、标签页被乱开、鼠标被挪走、内存被吃，人机互相踩踏。
  2. 桥接：browser-use、agent-browser（Vercel）这类框架的路数。它们本质是“通往浏览器的桥，而不是浏览器本身”：需要单独驱动一个浏览器实例，你的登录数据很少能原样带过去，连接不稳定，最后人还是和 agent 争夺同一个浏览器的控制权。用桥接方案的人几乎都经历过“重登一遍”的摩擦。
  3. 共享隔离：一个浏览器进程，人机各占一个隔间——这正是 ego-lite 的选择。人在前台浏览，agent 在后台的独立工作区干活，互不打扰、互不偷标签页。

前两种姿势的共同缺陷是：它们把“浏览器”当成了一个要抢的资源。第三种姿势的洞见在于——浏览器本身不该是稀缺品，稀缺的是“信任”：登录态、Cookie、扩展这些你攒了多年的身份资产。 于是 ego-lite 的解法变成了：浏览器一人一份空间，身份资产大家共享。

4.2 Space：一个浏览器里的隔离工作区

Space 是 ego-lite 的核心抽象：每个 agent 拥有一个完全隔离的工作区，agent 在属于自己的 Space 里执行任务。三个特性值得展开：

  • 互不干扰：你在前台浏览，agent 在后台跑，鼠标留在你最后放下的位置，标签页各自归各自。
  • 并行：同一个浏览器里可以同时跑多个 Space——Claude Code 在 10 个并行 Space 里补客户线索，Codex 在另外 5 个 Space 里爬竞品站，互不碰撞。这是桥接方案做不到的：它只有一个浏览器实例，人一用 agent 就得等。
  • 可见可控：随时能看出哪个 Space 有 agent 在运行，想接管就接管、想停就停。

引擎层的 Space 是浏览器进程内的原生能力；到了 dsh-ego-browser 插件层，还叠加了一层任务空间的沙盒隔离（isolateSpaces，默认关闭），用于把不同 DSH 任务的空间进一步隔开。两层隔离的粒度不同：引擎层管“人 vs agent”，插件层管“这个任务 vs 那个任务”。

4.3 登录态复用：身份资产的一次性迁移

Space 解决了“不抢浏览器”，登录态复用解决“不用再登录一遍”。ego-lite 首次启动时只问一个问题——是否迁移 Chrome 数据；同意后，agent 直接继承你已有的登录、Cookie、扩展和书签。之后 agent 打开任何站点，都是“你的身份”在访问：知网是已登录的，后台是已登录的，需要真人的会话也是可过的。

落到 dsh-ego-browser 这一层，登录态还有两条更工程化的路径：

  • 导入：v0.8.5 起，插件提供 ego_login_import，把日常 Chrome/Edge/Brave 里的登录 Cookie 按域名复制进 agent 浏览器，配合默认的磁盘持久化 Profile，导入的登录态跨重启永久保留。源浏览器运行中可选择优雅关闭后导入，导入前自动备份源 Cookie 库，异常清空自动还原。
  • 落盘：ego_auth_flush 负责把运行中的登录态落盘持久化，避免 agent 辛苦登录一遍、浏览器一重启就清零。

4.4 数据与隐私：窄收集、本地存储

共享身份资产会让人本能地警惕数据外流。ego-lite 的立场是：你的浏览数据、Cookie、一切浏览器持有的东西，都留在你的设备上；数据收集刻意收窄——只采集“是否把 ego lite 设为默认浏览器”这类简单产品信号。也就是说，它要的是“身份资产的复用权”，不是“身份数据的观测权”。

4.5 性能证据与它的边界

社区报道给出的性能数字相当亮眼：复杂任务相对 CLI 式驱动快约 2.5 倍、Token 消耗更低（不同文章口径从“减半”到“降低近 4 倍”不等）。但必须冷静看待：这些数字主要来自官方口径与社区转述，未经第三方严格验证。把它当“该方案的合理性证明”可以，当“可以写进汇报的实测基准”不行——第14章实战部分我们会给出一套可复现的测试方法。

本章小结：Space 把“抢浏览器”变成“分空间”，登录态复用把“重登一遍”变成“继承一次”。这两个机制合起来，才是 ego 系区别于桥接方案的根本——它不跟你要一个浏览器，它跟你要一次信任。

第5章 眼睛原理：页面快照 Snapshot

浏览器有了，agent 怎么“看见”网页？这个问题比听起来难得多：模型没有眼睛，只有 token。喂给它一张页面截图，它看不清；喂给它整段 HTML，它读不动。快照（Snapshot）就是夹在两者之间的答案：把页面变成结构化文本，让文本模型“看见”并据此操作网页。

5.1 快照是什么：压缩语义输入

ego-lite 暴露给 agent 的核心原语之一是快照——每次操作前，agent 先对当前页面拍一张“文本快照”，读懂了再决定点哪里、填什么。快照不是 HTML 的搬运，而是语义化压缩：把页面的结构、控件、可交互元素提取成紧凑的结构化文本，这就是模型赖以行动的“视界”。

这对应到 DSH 的上下文纪律上，恰好是同一门功课：白皮书总结省 Token 的关键不在某个开关，而在稳定前缀、结果裁剪与整链压缩——让模型看到更少但更有信息量的内容。快照就是浏览器世界的“结果裁剪”：页面有几 MB 的 DOM，模型只需要那几 KB 的语义。

5.2 为什么“引擎级”快照更强

市面上并不缺“把网页转成文本”的工具，为什么 ego-lite 敢说自己的快照是“市场上最强的”？答案在它 README 里那句不起眼的话：“Thanks to customization inside the browser engine”——快照能力是在浏览器引擎内部定制的，而不是在引擎外面做 DOM 解析。

这个差别在两类页面上是生死线：

  • 深层嵌套的 iframe：第三方组件、后台管理页、嵌入式工具，页面里套页面。引擎外部的解析方案在这一层反复崩坏，而引擎内定制意味着快照能进入每一层 iframe 的内部结构——这正是同类方案普遍翻车的重灾区，也是 agent 浏览器值得单独立项的价值点。
  • 动态渲染：SPA 应用、需要等待异步加载的内容。引擎级快照在渲染完成后的真实 DOM 上工作，而不是在初始 HTML 上猜。

5.3 快照之上：语义定位

快照让 agent“看见”，但光看见不够，还得“点得准”。快照之后接的是语义定位：dsh-ego-browser 的 ego_* 工具族里，文本语义快照与语义定位点击是配套出现的——模型基于快照理解页面上“登录按钮在哪儿”之后，不是按像素坐标去点（那会随布局变化失效），而是按语义找到目标元素再点击。这也是“结构化工具”与“脚本化操作”的分水岭：脚本写死选择器，页面一改就崩；语义定位面向“元素是什么”而不是“元素在哪”。

5.4 快照与 Token：一本书的两条省钱路径

把 DSH 的 Token 纪律和快照放一起看，会发现 ego 系和 DSH 在同一个方向上使劲：让模型消费更少、更高质量的 token。DSH 在会话层做稳定前缀与自动压缩，ego 在页面层做语义快照与压缩输入。前者省的是“对话记忆”的钱，后者省的是“理解网页”的钱——两条路径最终汇合在同一本账上。

本章小结：快照的本质，是把“网页”从像素世界翻译进 token 世界。引擎级定制让它读得懂最深层的页面，语义定位让它点得准最易变的页面。眼睛的问题解决了，“手”才有资格上场。

第6章 手原理：CDP 直连与 JS 工具链

眼睛解决了“看见”，接下来是“动手”。agent 操作浏览器的技术选型，ego 系做了一个教科书级的减法：不要框架，直连协议。

6.1 两种驱动哲学：CLI 循环 vs 代码组合

给 agent 浏览器能力，有两种完全不同的驱动方式：

  • CLI 式：把浏览器封装成一条条命令，agent 的每一小步都是“调用命令 → 看结果 → 再调命令”。缺点显而易见：一个多步任务会陷入“调两条命令、看结果、再调两条命令”的长循环，慢、费 token、容易断。
  • Code-based 式：把浏览器能力暴露成 JavaScript 函数，agent 直接写代码、一次组合多步任务成一个调用。这正是 ego-lite 的选择——它声称相比传统 CLI 方式，复杂工作流完成得更快、任务成功率更高、每次任务的工具调用数和成本都大幅下降。

这个选择与 DSH 白皮书反复强调的省 Token 逻辑同频：省 Token 的关键在减少无效往返——上下文稳定、结果裁剪、压缩整链，而不是靠某个单一开关。CLI 循环是“无效往返”的重灾区，代码组合正是对症下药。

6.2 CDP 直连：不套 Puppeteer，不套 Playwright

ego-browser（开源连接层）的技术栈极其克制：Node.js 运行时，通过 Chrome DevTools Protocol（CDP）直接控制浏览器，不依赖 Puppeteer 或 Playwright，解析只用了 acorn。

这个选择在工程上是三层考量：

  1. 依赖最小化：Puppeteer/Playwright 是重量级依赖，自带浏览器分发和庞大的 API 面；而 ego-lite 的浏览器本体是引擎内定制过的 Chromium，套通用框架反而隔了一层、丢了定制能力。
  2. 控制直达：CDP 是 Chrome 的原生调试协议，直连意味着拿到的是浏览器的原始能力，任何引擎级定制（快照、Space）都能无缝衔接，中间没有框架的“翻译损耗”。
  3. 解析够用即可：代码解析只用 acorn——一个轻量 JavaScript 解析器，而不是全套编译工具链。这符合 ego 系“少而精”的工程气质：每一层只解决它该解决的问题。

6.3 globalThis.ego：能力即函数

在浏览器这一侧，ego-lite 通过 globalThis.ego 绑定把能力暴露给 agent：快照（snapshot）、填充（fill）、点击（click）、等待（wait）、导航（navigate）、捕获（capture）——浏览器被抽象成一组“页内 JavaScript 工具”。agent 写一段 JavaScript 片段调用这些工具，ego-browser 在页面上一遍跑完。

开源 harness 的核心工作流是 snapshot/ref：先拍快照，拿到页面的结构化文本和元素引用（ref），再基于引用执行点击、填充等动作。这个“先读后写”的模式保证了确定性——模型不是凭记忆操作，而是基于刚读到的页面状态行动。

源码的组织也按能力拆分：驱动模块分成指针、键盘、导航、快照、等待、文件上传几个独立模块。职责单一，正是这套系统能持续演进的骨架。

6.4 从函数到工具：dsh-ego-browser 的结构化

ego-browser 的函数是给“会写代码的 agent”用的；而 DSH 里的模型是通过工具调用（tool calling）与系统交互的。dsh-ego-browser 做的，就是把前者翻译成后者：注册 32 个结构化 ego_* 工具（早期 README 描述为 13 个起步，当前源码注册 32 个），覆盖文本语义快照、语义定位点击、表单填充、截图、CDP 控制、任务空间隔离等。

这组工具的设计原则，恰好呼应 DSH 白皮书里的工具设计四条实用原则（第10.7节）：职责单一、可并行安全、提交顺序不乱、取消时补齐结果。ego 系自己也明确宣称：这 32 个工具“职责单一、可确定性调用”。

一个值得注意的工程细节：ego_script 工具负责跑自定义脚本，它的每次运行超时 timeoutMs 从 v0.7.0 起真正生效——之前是声明了不执行，之后是每跑必守。这种“把承诺落实成行为”的版本演进，是全书反复出现的主题：ego 系的价值不在口号，在可核对的代码行为。

本章小结：CDP 直连省掉框架层，globalThis.ego 把能力变成函数，snapshot/ref 保证操作的确定性，32 个 ego_* 工具把函数翻译成 DSH 模型可调用的语言。手的问题解决了，“脑子”才有地方长。

第7章 大脑原理：learnings 与经验积累

模型每次操作网页都是“从零开始”的——不知道这个站点的登录按钮在哪、表单怎么填、下一页怎么翻。试错是 agent 在浏览器任务上最贵的成本。 ego 系的第三层设计，就是给这套系统装上记忆：learnings。

7.1 learnings：按站点整理的经验包

ego-browser 的学习子系统（learnings）把经验按站点整理成经验包：每次成功操作后，站点相关的操作知识沉淀下来——这个站怎么登录、这个表单怎么填、这个列表怎么翻页。下次再访问同一站点，agent 不是白纸一张，而是带着上次的作业本进场。

这个设计与 DSH 的 Skills 机制在思路上同构：DSH 官方底座里的 Skills 是“目录先进入上下文、正文按需读取”——上下文里先有“我知道你会什么”，需要时才加载详细内容，而不是把所有知识一次性灌进模型。learnings 的按站点组织，正是浏览器世界里的 Skills：按需、分域、可复用。

7.2 经验积累：成功提炼成工具，同类任务快 5 倍

learnings 是“被动记忆”，ego 系还有一步“主动提炼”——经验积累：每次成功的浏览器操作被提取成可复用的工具和工作流，类似的后续任务最快可以快 5 倍。

机制不难理解：试错成本只付一次。第一次跑通“谷歌学术翻页收集文献”，这个流程被提炼成一个工具；第二次、第十次遇到同类任务，agent 直接调用提炼好的工具，而不是重新摸索。这也解释了 ego-lite 官方 Skill 宣称的“用得越多越快”——不是模型变聪明了，是工具库变厚了。

7.3 记忆的边界：什么该记、什么不该记

经验积累的背面是记忆卫生。ego 系的处理有几个克制点：

  • 按站点隔离：经验包按站点整理，站 A 的经验不会污染站 B 的操作。
  • 从成功中学习：提炼的对象是“成功的操作”，而不是所有操作——避免把试错的路径也固化进经验库。
  • 数据本地：浏览数据、经验包都留在本机，ego-lite 的数据收集刻意收窄，只保留简单产品信号。

这与 DSH 的安全边界哲学一致：白皮书强调第三方插件运行在宿主里、工具沙箱不能自动覆盖宿主插件——记忆能力越强，越要管住“记忆给了谁”。

7.4 在 dsh-ego-browser 里的落点

到插件这一层，learnings 的完整形态（成功提炼工具）更多属于 ego-lite 官方 Skill 的路线图；dsh-ego-browser 目前落地的是“可确定性调用的结构化工具”这一层——ego_script 跑自定义脚本、ego_captcha 探测人机验证、ego_download 捕获下载、ego_page_info 读取页面信息、ego_doctor 体检环境。未来当 learnings 正式上线，插件层大概率会把这些经验包同样接入 DSH 的工具注册体系——那将是“大脑”真正长出来的时刻。

本章小结：learnings 解决“同一件事反复从零开始”，经验积累把成功操作固化成工具。引擎给身体，CDP 给手，快照给眼睛，learnings 给记忆——原理篇的四块拼图到这里拼齐了。

第8章 看得见的原理：观察窗与 self-observation

原理篇走到这里，“能干活”的问题已经解决：引擎给身体，CDP 给手，快照给眼睛，learnings 给记忆。但还差最后一块拼图——你敢不敢让它放手去干。这正是 dsh-ego-browser 区别于同类插件的立身之本。

8.1 黑盒的代价

市面上把 ego-lite 接进 DSH 的同类插件只做了 3 个工具（run/help/status），浏览器仍是后台黑盒：agent 在里面翻了多少页、卡在哪个验证码、走没走岔，你一概不知，只能等它“跑完告诉你结果”。黑盒模式在两步以内的任务上没问题；任务一长，风险就变成成本——等 agent 跑完才发现它在第 3 步就走偏了，这趟工白干。

ego-browser 走的另一条路：把黑盒打开，一上来就把“看”和“控”做到位。

8.2 观察窗的四件套

dsh-ego-browser 的观察窗由四组能力组成，README 用几个 emoji 讲得很形象：

  • 🌐 小球一点看直播：右下角观察球，点开就是 agent 正在浏览的页面实时画面（SSE 推流）。
  • 🟦 标签条切换/关闭：agent 开了哪些标签，一目了然，随时切换、随时关。
  • 🕘 历史抽屉回看：agent 走过哪些页面，回放它刚才的操作轨迹，出了问题能溯源。
  • 🔍 缩放拖拽 + 🖱️ 监控窗直接接管：不只是看，还能在监控窗里亲手操作 agent 正在用的真实浏览器——点击、拖拽、滚动通过 CDP 回传，人机交接不用打断 agent 重来。

一句话概括：让 agent 在浏览器里干活，你在旁边既看得见、又随时能接手。

8.3 两种形态：侧边栏 Tab 与浮动观察球

观察窗前端口有两种部署形态，自动切换：

  • 侧边栏 Tab（v0.8.0 起）：当宿主装了 dsh-better-sidebar（推荐 ≥ v0.12.2），观察窗注册为侧边栏原生 Tab——“Agent 浏览器”出现在侧边栏“+”菜单里，随抽屉固定展示；agent 首次调用 ego_* 工具时自动打开该 Tab（v0.8.5 起按会话作用域打开，多会话不再弹错位置）。
  • 浮动观察球（回退形态）：未装 dsh-better-sidebar 时自动回退为右下角浮动球（#dsh-ego-fab）。

关键工程约束：两种形态共用同一套 SSE 实时推流 / 点击 / 输入 / 下载捕获能力，前端形态可以换，能力管道不重复造。

8.4 双后端：CDP 与 FFmpeg

观察窗的“直播”有两种采集后端，设置项 captureBackend 可选 auto | cdp | ffmpeg（默认 auto，当前解析为 CDP）：

  • CDP 后端：通过 DevTools Protocol 直接抓帧，JPEG 质量、FPS、最大宽度可调。
  • FFmpeg 后端：H.264 编码推流，FPS、最大宽度、码率（500–20000 kbps，低/平衡/高档默认 2000/4000/8000）、编码器、自定义路径均可配置；插件先探测自定义路径、系统 PATH 与托管缓存，检测到兼容 FFmpeg 前禁止选 FFmpeg，并提供固定版本一键下载（GitHub 下载可用 githubMirror 换源）。

两条后端的存在，意味着“看得见”是有成本的、需要按环境取舍的：CDP 简单但帧率与体积受限，FFmpeg 流畅但依赖外部二进制。默认 auto 的语义是：能省则省，必要才上重家伙。

8.5 self-observation：agent 操作 DSH 自身

dsh-ego-browser 最私藏的一点独特之处：agent 用的就是这一个 Chromium——连它操作 DSH 自身（管理会话、任务看板、调设置）时，观察窗也实时显示、你能随时接手。不止“看得见 agent 在网页上干活”，连 agent 操作 DSH 界面本身都全程可见、可掌控。

这个特性在同类方案里几乎看不到：大多数 agent 浏览器只关注“agent 在外面干了什么”，没人关心“agent 在系统里干了什么”。self-observation 把监控的边界从“网页世界”扩展到“宿主世界”——agent 的任何动作都在你的视野内，这是“放心”的最终形态。

8.6 接管的实战价值

观察窗的“看”最终服务于“控”。几个典型场景（README 原话场景）：

  • 表单与登录：agent 填表到一半，观察窗弹出验证码——你直接接管把验证码点了，再交还给 agent 继续。
  • 文献/数据抓取：agent 在知网/谷歌学术翻页收集，你看着它滚动、点下一页、下载 PDF，中途卡住立刻发现。
  • QA/冒烟测试：让 agent 在自己产品上点一圈，观察窗等于一台“会说话的录屏”，顺手回看历史轨迹。
  • 无头转有头：观察窗提供“弹出窗口”按钮——headless 运行的 agent 浏览器可一键替换为同 Profile 的有头窗口（标签页保留），手动接管无头环境里的任务。

观察窗还有一堆体验层细节：状态灯“干活常绿、空闲呼吸”（v0.7.0）；观察窗主动跟随 agent 正在操作的页面，不再被后台重绘页抢占视图（v0.6.1）；前端 frameCache/pageMeta 按标签清理，杜绝长会话内存增长（v0.7.0）。看得到是能力，看得对、看得不卡是工程。

本章小结：观察窗的四件套回答了“放心”的两个问题——看得见（SSE 推流、标签条、历史抽屉、双后端），接得住（鼠标直操、验证码接管、无头转有头、self-observation）。把黑盒打开，agent 才敢真正替你上工。

第9章 可靠的原理：自愈、守卫与兜底

观察窗让 agent 的行动可见，但可见不等于可靠。agent 浏览器是个长跑选手：长会话、无头环境、远程宿主机、随时可能崩溃的 Chromium 进程。dsh-ego-browser 在这件事上的投入，从版本历史里能看得很清楚——几乎每个版本都在加固“摔倒了能自己爬起来”的能力。

9.1 可靠性问题从哪来

agent 浏览器的可靠性压力，与普通浏览器完全不同：

  • 长会话：一个任务可能跑几十分钟甚至几小时，任何瞬时故障都会被放大成整场失败；
  • 无头与远程：Docker、root、无显示器环境（xvfb）下，没有“人眼盯着”兜底，进程死了没人知道；
  • 多任务并发：多个 DSH 会话共享观察窗 worker，一个 stale 状态可能污染所有会话。

于是插件的可靠性设计分了三层：进程层（不死）、状态层（不乱）、资源层（不涨）。

9.2 进程层：worker 单实例守卫 + 崩溃自愈

观察窗的推流 worker 有单实例守卫：一个宿主只允许一个 worker，重复拉起会被挡住，stale 状态会被清理（v0.6.1）。配合崩溃自动重启机制，worker 挂了能自愈，而不是把整个 DSH Web 拖下水。

冷启动重试也做了精细化：启动时只重试 CDP 瞬态错误，不吞真错——重试的是“环境还没准备好”，不是“环境根本不可用”。这个区分很关键：盲目重试会把真故障伪装成瞬态，让用户对着一个永远起不来的浏览器干等；只重试瞬态，才能既抗抖动、又不掩盖真相。

9.3 状态层：卸载不阻塞宿主 + 会话级清理

插件的卸载采用 fire-and-forget 策略：卸载不再阻塞宿主退出，自愈链路稳定（v0.6.1）。别小看这个细节——插件系统里最常见的“卸载死锁”，就是卸载流程等待一个正在被宿主关闭的进程，两个退出流程互相等。

v0.8.3 还修复了“无 dsh-better-sidebar 宿主 client 启动失败”和 Windows 冷启动回归（v0.8.2 引入的 Xvfb 误判）——这些修的都是“特定环境下根本起不来”的硬故障，属于可靠性的地基。

9.4 资源层：帧缓存上限与按标签清理

长会话最隐蔽的杀手是内存增长：推流帧、页面元数据如果不清理，跑一小时和跑十小时的内存是两个数量级。v0.7.0 做了两件事：前端 frameCache/pageMeta 按标签清理 + 上限兜底，杜绝长会话内存增长。v0.7.0 还让 ego_script 的超时 timeoutMs 真正生效——每次运行必守超时，不再是一句声明。

另有 idleTimeoutMin 开关：空闲 N 分钟后自动回收（观察窗）资源。资源层哲学很简单：无界的运行时间，必须配上有界的资源占用。

9.5 平台兜底：--no-sandbox 与开箱即用

ego-lite 本体是“先装一个 GUI 宿主”的模式；dsh-ego-browser 则自带平台兜底层：resolveEgoEnv 自动探测 Chrome/Edge/Brave，内置 --no-sandbox wrapper，root / Docker / 无显示器环境免配置直接跑。插件包内置 ego 运行时，无需克隆官方仓库、无需手动构建。平台自适应覆盖 Linux/macOS/Windows 自动探测（v0.4.0 起支持 Windows，v0.8.2 起合并 root/xvfb/macOS headless 适配）。

9.6 层层兜底：这套系统的工程气质

把第9章的机制排成一列，能看出 dsh-ego-browser 的可靠性不是单点方案，而是三层兜底：进程死了有自愈，状态乱了有守卫，资源涨了有上限；再往外，平台不对有 wrapper，环境不对有重试，宿主不对有回退形态（侧边栏 ↔ 观察球）。每一层只兜住自己那一层的故障，不越界、不重叠。

这种“层层递进、各管一段”的工程结构，是全书想强调的最后一个原理：可靠的系统不是“不会坏”的系统，而是“坏了知道自己在哪一层、由哪一层来兜”的系统。 看得见的观察窗让你放心，看不见的兜底层让你安心。

本章小结：进程层不死、状态层不乱、资源层不涨、平台层不挑——四层兜底把“能跑”变成“能一直跑”。原理篇到此收束：身体、手、眼睛、记忆、信任、韧性，六块拼图齐了。

第二编 工程篇

第10章 安装与首次运行

原理篇把六块拼图讲齐了，但从“知道”到“用起来”还有最后一段路。这一章解决最朴素的两个问题：怎么装，装完第一次跑起来是什么样。

10.1 这条路的优势：开箱即用

先把 ego-lite 的“先装 GUI 宿主”模式拎出来对比。ego-lite 本身是一个 Chromium 引擎，原生只支持 macOS，Windows 在内测、Linux 在路线图上。如果直接用它，你得先装一个 GUI 宿主、再手动克隆官方仓库、再手动构建——这一串门槛，是大多数人在第一道墙就折返的原因。

dsh-ego-browser 把这段路搬平了：

  • 插件包内置 ego 运行时，无需克隆官方仓库、无需手动构建；
  • 自带 --no-sandbox wrapper，root / Docker / 无显示器环境（xvfb）免配置直接跑；
  • 平台自适应覆盖 Linux / macOS / Windows 自动探测（v0.4.0 起支持 Windows，v0.8.2 起合并 root / xvfb / macOS headless 适配）。

一句话：原理篇里那套引擎级能力，装进 DSH 之后不再需要你手工伺候环境。

10.2 首次运行会发生什么

装完插件、第一次启动 agent，你会依次看到几件事：

  1. 身份迁移：engine 层首次启动只问一个问题——是否迁移已有的浏览器数据。同意后，agent 继承你已有的登录、Cookie、扩展、书签，此后打开任何站点都是“你的身份”在访问。
  2. 观察窗出现：如果你装了 dsh-better-sidebar（推荐 ≥ v0.12.2），“Agent 浏览器”会注册为侧边栏原生 Tab；agent 首次调用 ego_* 工具时，该 Tab 自动打开。没装则回退为右下角浮动观察球（#dsh-ego-fab）。
  3. 环境自检：ego_doctor 工具负责体检环境，确认 CDP 连接、平台适配、后端探测是否就绪。

10.3 环境依赖的最小化

resolveEgoEnv 会自动探测本机 Chrome / Edge / Brave，找到就调它控制的浏览器。这里有个值得记住的工程气质：插件不另起炉灶，而是复用你机器上已有的浏览器，只做协议连接层的适配。

阶段小结：工程层的第一课是“环境不对有兜底”。装了就能跑，跑了就能看见——这是从原理篇到工程篇的第一步跨越。

第11章 ego_* 工具全景

工具是 agent 与浏览器之间的语言。dsh-ego-browser 把引擎能力翻译成一组结构化工具（README 时代从 13 个起步，当前源码注册 32 个，最新 README 写作 33 个）。本章按类目讲透这些工具都用什么、怎么用。

11.1 先理解设计原则

这组工具不是随手攒的。它呼应 DSH 白皮书里的工具设计四条原则：职责单一、可并行安全、提交顺序不乱、取消时补齐结果。ego 系自己也明确宣称：这 32 个工具“职责单一、可确定性调用”。

核心工作流是 snapshot/ref：先拍快照拿到页面的结构化文本与元素引用（ref），再基于引用执行点击、填充等动作。这个“先读后写”的模式保证了确定性——模型不是凭记忆操作，而是基于刚读到的页面状态行动。

11.2 按类目看工具族

我把 33 个工具按功能归类（源码注册 32 个，README 口径 33 个，差异在迭代中）：

能力域 代表工具 干什么
语义快照 ego_snapshot 等 拍文本快照，让模型“看见”页面
语义定位点击 点击类工具 按语义找元素再点，不靠像素坐标
表单填充 fill 类 填表、处理表单控件
常规操作 navigate/wait 导航、等待、滚动
脚本执行 ego_script 跑自定义 JS 片段，自带 timeoutMs
验证码 ego_captcha 探测人机验证
下载 ego_download 捕获文件下载
页面信息 ego_page_info 读取页面信息
登录态 ego_login_import / ego_auth_flush 导入 / 落盘持久化登录态
环境体检 ego_doctor 体检插件与浏览器环境
任务隔离 isolate 类 不同 DSH 任务的沙盒空间（默认关）
CDP 控制 CDP 类 直接控制浏览器底层

其中 ego_script 的 timeoutMs 从 v0.7.0 起真正生效——每次运行必守超时，不再是声明了不执行。这就是这套工具的可信度来源：承诺都以可核对的代码行为落地。

11.3 一个重点：ego_login_import 与 ego_auth_flush

这两个工具暴露了“登录态”这条工程主线（第12章会展开）：

  • ego_login_import（v0.8.5 起）：把日常浏览器里的登录 Cookie 按域名复制进 agent 浏览器，配合默认磁盘持久化 Profile，跨重启永久保留；源浏览器运行中可优雅关闭后导入，导入前自动备份、异常自动还原。
  • ego_auth_flush：把运行中的登录态落盘持久化，避免 agent 辛苦登录、浏览器一重启就清零。

11.4 怎么查全貌

README 对各工具都有说明，源码的 src/utils 里有完整的注册映射。你在 DSH 里可以直接对 ego_* 声明的工具列表展开查看，不必背全——重点是理解“职责单一、可确定性调用”这条主线。

第12章 登录态：导入、持久化与接管

登录态是 ego 系区别于一切桥接方案的根本资产。这一章把“登录态”这条工程主线完整展开——从导入、到持久化、再到最终的人机接管。

12.1 为什么登录态是核心资产

回顾原理篇第4章的判断：浏览器本身不该是稀缺品，稀缺的是“信任”——登录态、Cookie、扩展这些你攒了多年的身份资产。ego-lite 首次启动只问一个问题：是否迁移 Chrome 数据。同意后，agent 直接继承你的登录、Cookie、扩展、书签，打开任何站点都是“你的身份”在访问。

这套机制的价值要放到真实场景里才看得见：知网的已登录态、后台管理页的会话、需要真人验证的站点——这些“只有真浏览器能过”的墙，全因登录态复用而变成 agent 直接就能走的路。

12.2 导入：ego_login_import

到 dsh-ego-browser 这一层，登录态复用被工程化成两条路径。第一条是导入。

ego_login_import（v0.8.5 起）把日常 Chrome / Edge / Brave 里的登录 Cookie 按域名复制进 agent 浏览器，配合默认的磁盘持久化 Profile，导入的登录态跨重启永久保留。

工程细节上有几个防护值得记住：

  • 源浏览器运行中可优雅关闭后导入——避免边用边拷导致的一致性问题；
  • 导入前自动备份源 Cookie 库——出问题能还原；
  • 异常清空自动还原——导入失败不会留下半截状态。

12.3 持久化：ego_auth_flush

第二条路径是落盘。ego_auth_flush 负责把运行中的登录态落盘持久化，避免 agent 辛苦登录一遍、浏览器一重启就清零。

为什么需要这一步？因为导入解决的是“继承已有身份”，落盘解决的是“保住新建立的身份”——比如 agent 在某个站点上完成了登录、过了验证码、填了资料，这套新会话如果不落盘，重启即丢。ego_auth_flush 让“在跑的过程中新攒的登录态”也能跨重启保留。

12.4 接管的最后一环

登录态工程到“接管”才算闭环。观察窗的监控窗可以直接驱动 agent 正在用的真实浏览器——表单填到一半弹出验证码，你直接接管点掉，再交还给 agent 继续。登录态 + 人机接管合起来，才真正兑现“身份资产共享、控制权随时可还”。

12.5 安全边界

身份资产越值钱，越要管住它给了谁。ego-lite 的立场是：浏览数据、Cookie 都留在你的设备上，数据收集刻意收窄，只采集“是否设为默认浏览器”这类简单产品信号——它要的是“身份资产的复用权”，不是“身份数据的观测权”。

到 DSH 生态还要叠加一层：插件运行在宿主里，第三方插件以你的权限运行，安装前要过审查清单。

本章小结：导入继承已有身份，落盘保住新建身份，接管让你在关键时刻亲手把关，窄收集守住身份资产的边界。登录态这条线走完，agent 才真正是“用你的身份替你干活”。

第13章 观察窗工程：双后端与侧边栏集成

原理篇第8章讲了观察窗“是什么、为什么”，这一章落到工程：双采集后端怎么选、侧边栏怎么集成、能力管道怎么复用。

13.1 双后端：CDP 与 FFmpeg

观察窗的“直播”有两种采集后端，设置项 captureBackend 可选 auto | cdp | ffmpeg（默认 auto，当前解析为 CDP）。

  • CDP 后端：通过 DevTools Protocol 直接抓帧，JPEG 质量、FPS、最大宽度可调。简单、无外部依赖，但帧率与体积受限。
  • FFmpeg 后端：H.264 编码推流，FPS、最大宽度、码率（500–20000 kbps，低/平衡/高档默认 2000/4000/8000）、编码器、自定义路径均可配置。流畅但依赖外部二进制——插件先探测自定义路径、系统 PATH 与托管缓存，检测到兼容 FFmpeg 前禁止选 FFmpeg，并提供固定版本一键下载（GitHub 下载可用 githubMirror 换源）。

auto 的语义很清楚：能省则省，必要才上重家伙。这是“看得见是有成本的、要按环境取舍”的工程表述。

13.2 侧边栏集成：两种形态自动切换

观察窗前端口有两种部署形态：

  • 侧边栏 Tab（v0.8.0 起）：装了 dsh-better-sidebar（推荐 ≥ v0.12.2），观察窗注册为侧边栏原生 Tab——“Agent 浏览器”出现在侧边栏“+”菜单，随抽屉固定展示；agent 首次调用 ego_* 工具时自动打开该 Tab（v0.8.5 起按会话作用域打开，多会话不再弹错位置）。
  • 浮动观察球（回退形态）：未装 dsh-better-sidebar 时，自动回退为右下角浮动球（#dsh-ego-fab）。

关键工程约束：两种形态共用同一套 SSE 实时推流 / 点击 / 输入 / 下载捕获能力。前端形态可以换，能力管道不重复造。

13.3 体验层的工程细节

观察窗的可靠不止在采集，还在前端：

  • 状态灯“干活常绿、空闲呼吸”（v0.7.0）——一眼看出 agent 忙不忙；
  • 主动跟随 agent 正在操作的页面，不再被后台重绘页抢占视图（v0.6.1）；
  • frameCache / pageMeta 按标签清理，杜绝长会话内存增长（v0.7.0）。

“看得到是能力，看得对、看得不卡是工程。”

本章小结：双后端让直播按环境取舍，侧边栏与浮动球自动切换且共用能力管道，体验层把“看得对、看得不卡”落到版本里。观察窗从“能看”走向“好用”。

第14章 实战三例

原理和工程都讲完了，这一章用三个真实场景把整本书串起来。每个例子都走同一套流程：装好 → 快照 → 行动 → 观察 → 接管。

14.1 例一：文献抓取（知网 / 谷歌学术）

需求：让 agent 翻页收集文献、下载 PDF。

流程与要点：

  1. 导入登录态（ego_login_import）——知网已登录，不走“重登一遍”的摩擦；
  2. 拍快照（ego_snapshot）——拿到当前页面的结构化文本和元素引用，agent 据此决定翻哪一页；
  3. 翻页 + 下载——agent 滚动、点下一页、触发 ego_download 捕获 PDF；
  4. 观察——观察窗实时显示它翻到第几页、下载了哪些 PDF，中途卡住立刻发现；
  5. 接管（兜底）——如果某篇需要人工过验证码，直接在监控窗点掉，再交还 agent。

这套流程最值钱的地方在于：试错成本只付一次。第一次跑通“谷歌学术翻页收集”被提炼成工具，第二次、第十次遇到同类任务，agent 直接调用提炼好的工具，而不是重新摸索。

14.2 例二：表单登录

需求：agent 帮你在某个站点填表登录。

流程与要点：

  1. 导航到登录页（navigate）→ 拍快照，读懂表单结构；
  2. 填表（fill 类工具）——基于快照的语义定位填字段，不靠像素坐标；
  3. 提交 + 过验证码——如果弹出人机验证，ego_captcha 探测到后，观察窗接管——你直接点掉验证码，再交还给 agent；
  4. 落盘（ego_auth_flush）——登录成功后落盘，浏览器一重启也不清零。

语义定位在这类场景里是生死线：脚本写死选择器，页面一改就崩；语义定位面向“元素是什么”而不是“元素在哪”。

14.3 例三：QA 冒烟测试

需求：让 agent 在自己产品上点一圈，检查关键流程是否正常。

流程与要点：

  1. 让 agent 在观察窗可见地跑——观察窗等于一台“会说话的录屏”，顺手回看历史轨迹；
  2. 无头转有头——headless 环境下跑，需要人工介入时点“弹出窗口”按钮，一键替换为同 Profile 的有头窗口（标签页保留），手动接管；
  3. 回看历史抽屉——出问题能溯源，定位是哪一步走岔。

14.4 一个诚实的边界

社区报道给出的性能数字（复杂任务快约 2.5 倍、Token 消耗降低）主要来自官方口径与社区转述，未经第三方严格验证。把它当“该方案的合理性证明”可以，当“可以写进汇报的实测基准”不行——要真验证，按上面的三例自建一套可复现测试：同样的任务、同样的站点、计时 + 数 token，跑三遍取中位。

本章小结：三个场景共享同一套“快照 → 行动 → 观察 → 接管”的流程骨架。区别只在细节：文献抓取靠导入与提炼，表单登录靠语义定位与落盘，QA 冒烟靠可见回放与无头转有头。而它们的共同底座，是前两编讲透的那六块拼图。

第15章 架构走读：worker、cast-server 与 client

把 dsh-ego-browser 拆开，它是三块拼在一起的：worker（采集与推流）、cast-server（媒体传输）、client（观察窗前端）。这一章走读它们的职责边界与协作方式。

15.1 三层架构的总览

层 职责 关键机制
worker 采集浏览器画面、捕获点击/输入/下载 单实例守卫、崩溃自愈、冷启动瞬态重试
cast-server 媒体传输（SSE 实时推流） 会话级清理、卸载不阻塞宿主
client 观察窗前端（侧边栏 Tab / 浮动球） frameCache 按标签清理、主动跟随

15.2 worker：单实例守卫 + 崩溃自愈

观察窗的推流 worker 有单实例守卫：一个宿主只允许一个 worker，重复拉起会被挡住，stale 状态会被清理（v0.6.1）。配合崩溃自动重启，worker 挂了能自愈，不把整个 DSH Web 拖下水。

冷启动重试做了精细化：只重试 CDP 瞬态错误，不吞真错——重试的是“环境还没准备好”，不是“环境根本不可用”。盲目重试会把真故障伪装成瞬态；只重试瞬态，才能既抗抖动、又不掩盖真相。

15.3 cast-server：SSE 推流与卸载策略

直播推流走 SSE（Server-Sent Events）。cast-server 负责把 worker 采到的帧实时推给前端观察窗。

它的卸载采用 fire-and-forget 策略：卸载不再阻塞宿主退出，自愈链路稳定（v0.6.1）。这个细节在插件系统里很关键——最常见的“卸载死锁”，就是卸载流程等待一个正在被宿主关闭的进程，两个退出流程互相等。fire-and-forget 把这个死锁从根上拆掉。

15.4 client：观察窗前端与内存纪律

client 侧（观察窗前端）的工程重点在内存与跟随：

  • frameCache / pageMeta 按标签清理 + 上限兜底（v0.7.0），杜绝长会话内存增长；
  • 主动跟随 agent 正在操作的页面，不被后台重绘页抢占视图（v0.6.1）。

15.5 两个形态共用一条管道

侧边栏 Tab 与浮动观察球共用同一套 SSE 推流 / 点击 / 输入 / 下载捕获能力——前端形态可以换，能力管道不重复造。架构上“一套能力、多种壳”的分层，是这套系统能同时服务轻量回退与深度集成的原因。

本章小结：worker 管采集与自愈，cast-server 管推流与卸载，client 管展示与内存。三层各管一段、职责单一——这正是原理篇第9章“层层兜底、各管一段”工程气质的架构落地。

第16章 二次开发：在 DSH 生态里扩展 ego

dsh-ego-browser 不是终点，而是起点。这一章讲怎么在 DSH 生态里基于它做二次开发。

16.1 先理解扩展的落点

DSH 的哲学是“一切皆插件”——模型、工具、会话、界面、Agent Loop 本身都可以被插件替换和重组。在这片土壤里扩展 ego，通常有三个落点：

  1. 扩展工具：新增 ego_* 工具，把新的浏览器能力暴露给模型；
  2. 扩展观察窗：在前端口上叠加新的可视化或交互能力；
  3. 接入自己的登录态 / 工作流：把 ego 的能力嵌进你自己的 agent 任务。

16.2 工具扩展：照着“职责单一”做

ego 系自己宣称那 32 个工具“职责单一、可确定性调用”，源码的组织也按能力拆分（指针、键盘、导航、快照、等待、文件上传各一个独立模块）。做二次开发时，这个骨架就是最好的模板：

  • 新增工具前，先想清楚它属于哪个能力域；
  • 遵循 snapshot/ref 的“先读后写”模式，保证确定性；
  • 遵守 DSH 工具设计的四条原则：职责单一、可并行安全、提交顺序不乱、取消时补齐结果。

16.3 观察窗扩展：复用能力管道

观察窗“两种形态共用同一套能力管道”的约束，对你做扩展是个好消息——你在 SSE 推流 / 点击 / 输入 / 下载捕获这条管道上做的任何增强，侧边栏 Tab 和浮动球都自动受益，不用各写一遍。

16.4 未来：learnings 落进插件层

目前 learnings 的完整形态（成功提炼工具）更多属于 ego-lite 官方 Skill 的路线图；dsh-ego-browser 落地的是“可确定性调用的结构化工具”这一层。将来 learnings 正式上线时，插件层大概率会把经验包接入 DSH 的工具注册体系——那将是“大脑真正长出来”的时刻。对想做二次开发的人，这是个值得提前布局的接口点。

本章小结：DSH 的插件化土壤 + ego 的职责单一骨架，给了二次开发清晰的落点。扩展工具照 snapshot/ref 做，扩展观察窗复用能力管道，未来扩展 learnings 提前占位。生态的价值，正在于“官方只给骨架，能力由长出来的人补齐”。

第17章 生态坐标与选型

最后一章，把 dsh-ego-browser 放回整个生态里，回答选型问题：它和同类方案比在哪儿，什么时候该选它。

17.1 它在生态里的坐标

回顾第2章的生态全景：DSH 插件生态爆发式增长（2026 年 8 月 13 日开源，三天内 616 个插件，到 Plugin Hub 4800+ 条目的阶段）。浏览器自动化在这片生态里走出两条路线：

  • 路线A：操作你正在登录的 Chrome（代表 Lum1104/dsh-browser）——占用你的浏览器，人机共舞；
  • 路线B：给 agent 一个独立浏览器（代表 Fisfzy/dsh-ego-browser）——有自己的 Space，不碰你的窗口，但复用导入的登录态。

本书主线选的是路线B，因为它在“不打扰你”这一点上走得更彻底，且自带观察窗。

17.2 三条路线的取舍

  • 桥接方案（browser-use / agent-browser）：本质是“通往浏览器的桥，而不是浏览器本身”，登录数据很难原样带过去，人和 agent 还抢同一个浏览器。
  • ego-lite 原生（引擎层）：能力强，但要先装 GUI 宿主、手动克隆构建，门槛高，且仅原生支持 macOS。
  • dsh-ego-browser（宿主层）：开箱即用、看得见、控得住、self-observation，三者合一。

选型的本质判断在原理篇第4章就说清了：它不跟你要一个浏览器，它跟你要一次信任。当你愿意把登录态这份信任交给 agent，又希望全程看得见、随时接得住，dsh-ego-browser 就是那条路。

17.3 边界与未来

也要诚实说边界：性能数字主要来自官方口径与社区转述，未经验证；learnings 完整形态还在 ego-lite 官方路线图上；Windows 内测、Linux 在路线图上。生态还在快速补课，这本书讲的机制会持续演进，但“身体、手、眼睛、记忆、信任、韧性”这六块拼图的结构判断，会一直成立。

全书收束

这本书讲了一件事：看得见，才谈得上放心；放心，agent 才敢真正替你上工。

原理篇六块拼图——引擎给身体，CDP 给手，快照给眼睛，learnings 给记忆，观察窗给信任，兜底层给韧性。工程篇把它们落成可用的东西：装起来、工具全景、登录态、观察窗工程、实战三例、架构走读、二次开发、生态选型。

全书主线是一条清晰的路径：ego-lite（引擎）→ ego-browser（连接层）→ dsh-ego-browser（DSH 宿主层），三者合起来回答一个问题：怎么让 agent 用你已登录的浏览器干活，而你不被打扰、还随时看得见、随时接得了手。