omdsh-dev/dsh-ego-browser ↗★ 557
dsh-ego-browser
Agent 浏览器:把浏览器自动化封装为 34 个 ego_* 结构化工具,内置 ego-lite 运行时;右侧栏实时观察窗(实时画面 + 鼠标交互 + 下载捕获 + 人机验证提醒),支持 Chrome 登录态导入与 TUI/无头环境。
同名包的其他仓库
安装
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:omdsh-dev/dsh-ego-browser说明文档
阅读完整 README ↗ego-browser — 看得见的 Agent 浏览器
= 0.1.2-rc.1">
= 0.12.2 (optional)">
仓库:
github.com/omdsh-dev/dsh-ego-browser|当前版本 v0.14.2|版本历史见 CHANGELOG.md|详情页:dshfind

右侧边栏实时显示 agent 正在操作的页面;可直接点击 / 滚动 / 输入,或点「弹出窗口」接管。
版本兼容矩阵
| 依赖 | 最低版本 | 推荐版本 | 说明 |
|---|---|---|---|
| DSH (DeepSeek Harness) | 0.1.2-rc.1 | ≥ 0.1.2-rc.1(v0.8.6 起适配 0.1.7 settings;v0.8.8 起支持 0.2.1 原生右侧边栏,截至 0.2.1 验证通过) | engines.dsh 声明地板;peer 依赖同步锁定 >=0.1.2-rc.1。0.1.0-rc.x / 0.1.1-rc.x 请使用 v0.8.0 及更早版本 |
| dsh-better-sidebar | 0.12.2(可选) | ≥ 0.17.1 | 官方右侧边栏不可用时的可选侧栏回退(v0.9.3 起不再回退浮动球); ⚠️ **Windows + Chrome/Edge ≥127 的 profile 复制路径会被拒绝**(ABE 导致 0 cookies,旧 junction 真实 profile 启动路径已在 0.9.4 删除)。请使用上面的扩展桥接;EGO_LINUX_LOGIN_IMPORT_FORCE=1` 仅作为老版本浏览器的调试开关。 |
常驻执行器(v0.8.8,可选,默认关闭):设置页「常驻执行进程」开启后,ego_* 调用复用同一个 ego-browser --serve 进程——首次调用支付启动开销,之后每次 ~1–2 ms(一次性 spawn 基准 ~340 ms)。浏览器被空闲回收或崩溃后,下一次调用自动回退到一次性 spawn 并重新拉起浏览器(带启动重试),随后恢复常驻;已经写出的请求不会重试,避免重复点击/填表。空闲停止时间可配(默认 30 分钟)。
把 CitroLabs/ego-lite(给 AI Agent 用的 Chromium)接入 DeepSeek Harness:以 35 个结构化 ego_* 工具驱动浏览器,并配一套实时观察前端口——agent 后台操作网页时,你能像看直播一样看到它正在浏览的每个页面,还能直接操作它。
一点私藏的独特之处(self-observation):agent 用的就是这一个 Chromium——连它操作 DSH 自身(管理会话、任务看板、调设置)时,观察窗也实时显示、你能随时接手。不只是"看得见 agent 在网页上干活",连 agent 操作 DSH 界面本身都是全程可见、可掌控的。
开箱即用:插件包内置 ego 运行时(runtime/,MIT,见 THIRD_PARTY_NOTICES.md)——无需克隆官方仓库、无需手动构建,--no-sandbox wrapper 随包自带,root / Docker / 无显示器一键跑。
🚀 快速启动
# 安装(任选一种;桌面端也可以走 插件 → 添加插件)
dsh plugin --profile desktop add dsh-ego-browser@0.14.2
- 在 DSH 会话里说一句让 agent 用浏览器的话,例如:
打开 https://example.com ,截图并告诉我页面标题
- agent 第一次调用
ego_*时,右侧边栏的「Agent 浏览器」标签会自动出现(没有原生侧边栏时回退到dsh-better-sidebar;两者都没有时不显示侧栏面板),实时显示它正在操作的页面。 - 想接手时,直接在观察窗里点击 / 输入 / 滚动;需要完整浏览器窗口就点面板上的「弹出窗口」。
宿主侧无需配置:Chrome/Edge/Brave 自动探测,root / 无头自动兜底。第一次启动约 2–4 秒。如果观察窗没出现,先跑一次
ego_doctor看环境;更换浏览器路径后需要让 agent 浏览器冷启动才生效(见「已知限制」)。
我们的真正优势(不是口号,是能对照代码和竞品核实的能力)
同样把 ego-lite 接进 DSH,市面上已有同类插件用它只做了 3 个工具——一个 run 脚本、一个 help 指南、一个 status 体检,浏览器仍是后台黑盒。ego-browser 走的是另一条路:把黑盒打开,并且一上来就把"看"和"控"的能力做到位。
| 能力 | ego-browser(本仓库) | 同类插件(Da1dr1em/dsh-ego-browser) |
|---|---|---|
| 结构化工具数 | 35 个,职责单一、可确定性调用 | 3 个(run/help/status) |
| 实时观察窗(CDP JPEG / FFmpeg H.264 双后端 + 标签条 + 历史抽屉) | ✅ 有 | ❌ 无 |
| 监控窗鼠标直接操作真实浏览器(点击/拖拽/滚动回传 CDP) | ✅ 有 | ❌ 无 |
| worker 单实例守卫 + 崩溃/重复自愈 | ✅ 有 | ❌ 无 |
下载捕获 ego_download / 人机验证检测 ego_captcha/ego_page_info | ✅ 有 | ❌ 无 |
平台自适应(Linux/Windows/macOS 自动探测 + root/无头/--no-sandbox 兜底) | ✅ 三平台开箱用(macOS 由社区真机验证) | 仅 Windows 预览宿主,需手动配 |
登录态落盘持久化 ego_auth_flush | ✅ 有 | ⚠️ 仅文档级说明 |
关键差异两条:
- 看得到:别家是"跑完告诉你结果"的黑盒;我们实时推流,你看着 agent 操作,卡在验证码/走岔立刻发现。
- 控得住:别家只读;我们监控窗直接驱动同一个 agent 浏览器,需要时你亲手接管(缩放/拖拽/点击),不必打断 agent 重来。
以上对比基于公开可见的可核实事实:本仓库代码(
bin/ego-cast-worker.mjs实时推流 + CDP 输入回传、lib/index.js35 个注册工具、src/cast-server.ts(构建进lib/index.js)host 桥接)与同类插件的源码/README。此文档不含对任何他人的贬低——我们只陈述自己多实现并验证了哪些能力。
相对 ego-lite 本体,我们多做了这些(都可对照本仓库代码核实):
| 能力 | 说明(对应代码) |
|---|---|
| 观察窗前端口 | ego-lite 本体是无头 CLI(只有 heredoc 脚本 + 文本输出);我们在其上加了 SSE 实时推流 + 标签条 + 历史抽屉 + 监控窗鼠标直操(bin/ego-cast-worker.mjs、src/cast-server.ts(构建进 lib/index.js)、lib/client.js),让"看"和"控"成为一等能力 |
| 开箱即用 + 跨平台自足 | resolveEgoEnv 自动探测 Chrome/Edge/Brave,内置 --no-sandbox wrapper,root / Docker / 无显示器免配置(lib/index.js);不必像官方那样先装一个 GUI 宿主 |
| 健壮性层 | 冷启动自动重试(只重试 CDP 瞬态,不吞真错)、worker 单实例守卫 + 崩溃自动重启、插件卸载 fire-and-forget 不阻塞宿主退出、前端帧缓存上限(withWarmupRetry / makeEnsureWorker / frameCache) |
| 运维型工具 | ego_doctor(环境体检)、ego_captcha(人机验证探测)、ego_auth_flush(登录落盘)、ego_login_import(系统浏览器登录态导入)、ego_http(浏览器上下文请求)等,是原生 CLI helper 没有的一层 |
| self-observation | agent 操作 DSH 自身界面时同样实时可见、可接手 |
我们不声称媲美官方 macOS App 的内核级快照或原生多窗口体验;本仓库解决的是"把同一套浏览器能力带进 DSH + Linux/WSL + 看得见"这件事。
它解决什么问题
通用浏览器不是为 agent 设计的,而 Web 上大量交互(登录态、验证码、动态渲染、表单、需真人会话的站点)只有真浏览器能面对——这正是 ego 系 "让 agent 用你已登录的浏览器,而不打扰你"(官网)的由来。
ego-browser 把它接进 DSH,并把最痛的一点——你看不见 agent 在干什么、也插不上手——用一套观察窗解决:
🌐 小球一点看直播;🟦 标签条切换/关闭;🕘 历史抽屉回看;🔍 缩放拖拽;🖱️ 监控窗直接接管真实浏览器。一句话:让 agent 在浏览器里干活,你在旁边既看得见、又随时能接手。
几个常见的上手场景
- 文献 / 数据抓取:让 agent 登录知网 / 谷歌学术翻页收集,你在观察窗看着它滚动、点下一页、下载 PDF,中途卡住立刻能发现。
- 表单与登录:agent 填表到一半,观察窗弹出验证码——你直接接管把验证码点了,再交还给 agent 继续。
- QA / 冒烟测试:让 agent 在自己产品上点一圈,观察窗等于一台"会说话的录屏",顺手还能回看历史轨迹。
- 看 agent 操作 DSH 自身(self-observation):agent 在管理会话 / 调设置时,观察窗同样全程可见、可接手。
✨ 近期亮点
- v0.14.2:spaces 快返回 + ego_scroll 正确性——无浏览器时
/api/ego/spaces不再拉起 worker,worker 退出时ensureWorker()立即中止;ego_scroll返回滚动前后偏移与moved/settled,不再报旧scrollY。 - v0.14.1:观察窗可用性兜底——Remote watch 不返回时 2 秒超时并回退到 host watch 路由;修复地址栏导航后侧栏停在
idle / 未接管的问题。 - v0.14.0:侧栏基础浏览器——标签栏最右侧
+直接新建独立 Chrome 窗口;新增常驻地址栏、前进/后退/刷新;地址栏可直接访问,用户操作会激活真实 Chrome,模型ego_*仍保持不抢前台。 - v0.13.1:观察窗稳定性修复——新窗口/后台 target 启用 focus emulation,避免 0 帧冻结;面板点击 tab 显式激活真实 Chrome(模型动作仍不抢前台);capture session 失效自动重建;agent profile 默认关闭 Chrome 密码管理器,避免原生保存密码气泡卡住 screencast。
- v0.13.0:回放与观察窗幽灵光标——新增
ego_replay:读取轨迹 JSONL,按顺序通过同一套 ego 构建器重新执行(脱敏文本跳过);观察窗 SSE 新增cursor事件,点击/悬停时在实时画面上显示渐隐光标。 - v0.12.0:轨迹记录 + 原生能力兜底——新增
trajectory/recordText设置,按会话写 JSONL 到~/.dsh/plugin-data/ego-browser/trajectories;默认脱敏ego_fill/ego_key文本。新增scripts/replay.mjs离线校验/回放计划;检测到cua_driver_native__*时ego_help增加native主题,系统弹窗改用桌面工具。 - v0.11.0:观察成本分级——
ego_snapshot新增subtreeRef子树裁剪、maxChars默认 24000 截断、continuation绑定 snapshotId 续读;大页面不再一次把整棵语义树塞进上下文。 - v0.10.0:CUA 启发 P0 能力——新增
ego_verify动作后置断言(satisfied / unsatisfied / unknown,unknown 永不等于成功);ego_snapshot返回snapshotId,ref 动作可传snapshotId,旧代次直接返回STALE_REF(actionSent:false)。 - v0.9.15:#99–#104 集中修复——Windows 有头模式不再隐式抬窗(#99);反向代理子路径下的观察窗 API/SSE 跟随 ``(#100);手机/窄面板实时画面等比填满(#101);
ego_screenshot默认不再生成空白交付卡(#102);新建 space 不再显示about:blank(#103);原生弹窗默认 dismiss、target=_blank新标签可列出/切换(#104)。ego_screenshot的deliver现为显式 opt-in。 - v0.9.12:macOS Cookie 落盘修复开关(#93 收尾)——社区实测确认 macOS 26/27 + Chrome 156 的 cookie 不落盘是登录 Keychain 层问题,
--use-mock-keychain可恢复;现把诊断开关升级为设置页正式选项 「macOS Cookie 落盘修复」(useMockKeychain,默认关闭,仅 macOS 生效,需浏览器冷启动)。同时写清落盘是延迟的(约 60 秒后才出现在Default/Cookies)——此前"flush 后立刻查仍 0 行"的记录正是查得太早。安全权衡与排查步骤见下方「macOS Cookie 落盘」。 - v0.9.11:cast worker 无限重启修复(#97)——自定义
EGO_LINUX_STATE_DIR时 worker 与插件对ego-cast.json路径解析不一致,导致每 8 秒重复 spawn;现在统一为/ego-cast.json,并加 in-flight 保护与指数退避。macOS Cookie 落盘诊断(#93 后续)——新增EGO_LINUX_USE_MOCK_KEYCHAIN=1/chromeArgs: "--use-mock-keychain"对照开关,默认关闭,仅诊断用。 - v0.9.10:标签页选择修复(#92)——不再把
chrome://newtab当真实页;ego_script/ego_cli支持space并同步 targetId pin。Windows 焦点修复(#96)——已 active 的标签不再重复switchTab,最小化窗口不会被每次调用弹出。截图更干净(#96)——ego_screenshot({ hideCursor })默认隐藏 agent 光标,浏览器窗口仍可见。面板增强(#94)——新增刷新、手动网址和尺寸预设右侧的「最大化」按钮。 - v0.9.9:修复扩展登录态导入恒 0 条(#90)——DSH 以 JSON 字符串传
type:"json"参数,旧Array.isArray静默失效;现在domains/ego_select.value/ego_drag.points/CDP/HTTP 参数统一归一化,空 domains 按文档读取全部 cookie,0 条结果会明确 warning。修复僵尸 X display(#91)——读.X-lock判 pid 存活,死 Xvfb 不再触发 20s 冷启动超时,display 号也不再漂移。 - v0.9.8:修复 0.9.7 的
ego_tabs全量回归(#88)——guard()重复插入const task声明导致list/switch/open/close在编译期报SyntaxError;现在 space 只声明一次,并把脚本生成抽成可单测的tabsScript(),新增 13 项编译级测试。其它工具不受影响。 - v0.9.7:运行时选型说明——内置
runtime/ego-linux(默认)与官方 ego lite 的定位、能力差异和桥接方式写清(#87);egoBin设置页字段(Node 脚本,不是.exe)+ 启动前校验,填 exe 直接给出可执行错误;ego_doctor显示 egoBin 类型/警告;ego_tabs能力降级(运行时缺createTab/closeTab/listTabs时返回明确错误,不再抛脚本异常);Windows 内置运行时排查与cpu-features噪音说明。 - v0.9.6:
ego_wait_for_response回放已完成的响应(includeBuffered默认 true,load 后再等文档响应不再空等超时;缓存命中会解释并建议 cache-busting);会话级 task space(sessionScopedSpaces默认开,每个 DSH session 独立 context/window/tab/cursor,不再互相抢标签;可关闭保持旧行为);截图/下载卡片(ego_screenshot/ego_download在 Web GUI 显示可点击卡片,deliver:false可关);新增ego_wait_for_human(CAPTCHA/登录/2FA 阻塞等待,超时返回提示而非报错);合并 PR #84/#85/#86。 - v0.9.5:侧栏滚轮/触控板滚动恢复(#81:wheel 改绑常驻 stage);双缓冲细节硬化(#82:冷 seed、失败帧不换层、切目标 generation guard);合并 PR #83(社区 @mecamangeg)——多标签跨调用固定 agent 当前 tab(per-space cursor +
@@EGO_TARGET@@)、ego_script/ego_cli支持tab、viewportWidth/Height/deviceScaleFactor覆盖、ego_select按 value → label → index 回退,新增 25 个测试。 - v0.9.4:Chrome 风格面板(
#f1f3f4工具区、Chrome 式标签、蓝色主按钮、移除登录提示条);一键复用 Chrome 登录态——标题栏「连接 Chrome 登录态」配对一次后,之后点「复用 Chrome 登录态」即可由扩展后台自动导出当前网站 cookie(无需每次开 Chrome UI/点 Export);ego_tabs(list / switch / open / close);#69 双安全路径:安全复制(源 profile 永不打开/写入)+ Chrome 扩展桥接(Windows/macOS/Linux 的 Chrome/Edge/Brave 均可),已用真实 Bilibili 21 条 cookie 验证。 - v0.9.3:侧栏画面不再黑闪(#81/#82,双缓冲:新帧解码完成才交换,旧帧始终保留)+ Retina 不再发虚(采集宽度跟随面板、
ResizeObserver防抖重启 watch);TUI 侧栏改为纯文字(不再请求/渲染截图,标签元数据与disableFrameRelay解耦,选中按targetId防错位);移除悬浮球回退(官方侧边栏优先,仅保留可选dsh-better-sidebar);统一 Agent 浏览器图标(浏览器窗口 + 光标,侧栏与面板头部一致);常驻执行器诊断(/api/ego/executor、面板状态、连续 3 次失败自动停用、ego_status.resident);登录导入安全范围扩至 Windows + Chrome/Edge ≥127(#69 fail-closed);另有 #78 Termux 文档、#79 headless UA 版本探测、#80ego_scriptpage 门面文档、macOS 27 / Chrome 156 复测记录。 - v0.9.2:macOS 开箱可用(#65/#68,社区 PR #72 由 @syjnzh918 提供并移植到当前主线)——自动探测
/Applications与~/Applications下 Chrome / Chromium / Edge / Brave 的.app内二进制,并像 Windows 一样注入EGO_LINUX_CHROME;headed 路径不再要求 Xvfb(macOS GUI 是 Aqua/Quartz、永不导出$DISPLAY,isHeadlessDetected继续排除 darwin 以保留 #16 的真实窗口能力)。社区真机复测(0.9.2):macOS 27.0.1 arm64 + Chrome 156.0.8078.47(此前另有一次 macOS arm64 + Chrome 154 验证),chromePath留空、无--headless,冷启动 → navigate → 截图 →ego_doctor全通。 - v0.9.1:观察窗尺寸同步真实窗口——面板「打开真实页 / 弹出窗口」行新增 🔒/🔓 尺寸同步 开关:解锁后拖动侧边栏宽度、或直接拖画面右侧/底部/右下角手柄,会按拖动增量 1:1 缩放 agent 浏览器真实窗口;尺寸预设(16:9 / 4:3 / 21:9 / 1:1 / 9:16)一键设定窗口比例;页面标题与 URL 移入实时状态栏。帧链路性能:按
cdpFps做源端抽帧、采集宽度跟随面板尺寸、窗口隐藏/最小化自动停流、TUI 设置新增「关闭实时画面传输」,实测总 CPU 约减半。输入与稳定性修复:窗口缩放后点击坐标不再偏移;拖动缩放不再卡顿;面板先于浏览器打开时 SSE 会自动重连接上。 - v0.9.0:dsh-TUI 支持——在 dsh-TUI 宿主中可选注册 Agent Browser 设置页、工具活动状态栏与有限通知;右侧栏面板展示浏览器状态、按任务空间分组的标签、人机验证提示与最近动作,并支持键盘操作(选标签、弹出真实窗口、关标签、落盘登录态、刷新);v0.9.3 起 TUI 面板改为纯文字(不再显示缩略图,也不请求任何截图/画面)。所有 TUI 服务缺席时静默降级,Web/桌面端行为不变。合并社区 PR #74/#75/#76(ccch1mneyyy)。
- v0.8.8:原生右侧边栏——观察窗优先注册进 DSH 自带的右侧边栏(
sidebar.right.pane.tab+ guide 入口 + 自绘图标),dsh-better-sidebar作为可选回退(v0.9.3 起移除浮动球回退);服务晚于插件就绪时用ctx.inject等待。常驻执行器(可选)——ego_*调用复用同一个ego-browser --serve进程,首次启动后每次 ~1–2 ms(一次性 spawn 约 340 ms);浏览器被停/崩溃后自动回退一次性 spawn 恢复,再回到常驻;已写出的请求不重试。稳定性——reconcile()清扫不属于任何 space 的孤儿标签(#67),冷启动不再堆积标签;Windows 上浏览器启动失败不再空等 Xvfb。登录导入——ego_login_import从"全禁"改为仅 Windows + Chrome ≥155 拒绝(#69;v0.9.3 起扩展到 Windows + Chrome/Edge ≥127,理由见下)。 - v0.8.7:工具语义修复——
ego_wait_for_url先比对当前 URL 再等未来导航(带matchedCurrent)、ego_wait_for_response超时不再抛错、ego_dialog失败时给出可执行提示、ego_script/ego_cli文档写明@@DSH_RESULT@@哨兵并支持最后一行 JSON 兜底。Windows 稳定性——clearProfileLock()在 win32 上真正清理孤儿 Chrome(此前是永久 no-op,一次非优雅退出会让 agent 浏览器再也打不开)。安全——ego_login_import默认禁用(fail-closed,EGO_LINUX_LOGIN_IMPORT_FORCE=1才放行)。回收器——--stop后清理Default/Sessions/,冷启动不再静默复活旧标签。观感——光标箭头与手形不再重叠;CDP 预览默认宽度 960 → 1280。合并 PR #63(--serve常驻传输,默认仍走 spawn 路径)。 - v0.8.6:登录态导入安全加固(#61 不再可能损坏源 cookie 库)、人机验证误报修复(#62,loopback 不探测、要求挑战短语)、DSH 0.1.7 设置页适配(插件页行配置 +
settings/document-updated订阅)。 - v0.8.0:侧边栏 Tab 集成——当
dsh-better-sidebar可用时,实时查看窗注册为侧边栏原生 Tab(而非浮动浮窗),ego_browser工具首次调用自动展开;内置EgoBrowserTabReact 组件 +LivePreviewController实时帧管道。dsh-better-sidebar不是 peer 依赖(ctx.get()机会性消费),没装就退回浮动浮窗,两种部署都干净。 - **v0.7.