guo6x/dsh-pilot

🛩️ dsh-pilot — 给你的 DSH agent 一双会开车的手

Awesome DSH Plugin dsh-recommend dsh score ci English · DeepSeek Harness 插件

让 agent 在 DSH 对话里操控真实浏览器：打开网页、把页面当结构化文本读（带编号元素列表）、按编号点击输入（不用猜 CSS）、按键、后退/刷新/等待、执行 JS、截图——你在 Web GUI 的可拖拽驾驶舱面板里实时围观，随时接管。

- 🚀 一条命令安装 —— dsh plugin --profile web add github:guo6x/dsh-pilot
- ⚡ 零运行时依赖 —— 走 Node ≥ 22 原生 WebSocket 直连 CDP，用你机器上已有的 Edge/Chrome
- 🔑 无需 API key —— 什么都不出本机，不需要视觉模型
- 📖 文本优先设计 —— agent 读的是 DOM 快照（标题/URL/正文/链接 + 编号元素），纯文本模型照样上网，不烧视觉 token
- 🎯 按编号交互 —— 点击/输入全部指向快照编号，过期编号报错并提示重取快照
- 📝 表单更懂人话 —— 可按 label、aria-label、placeholder、name 或 id 一次填写多个字段，也能按编号上传文件
- 🧭 完整导航套件 —— 后退、刷新、等待工具 + 内置页面落定等待，真实上网流程全覆盖
- 👀 人在环中 —— 驾驶舱实时截图、地址栏、操作日志、会话切换器，agent 的一举一动都看得见
- 🧩 按会话隔离 —— 每个 agent 会话独立浏览器，并行会话互不抢页面

先看它怎么工作

打开 ✈️ 驾驶舱、启动隔离浏览器，页面变化全程可见。多个 agent 同时上网时，录屏还演示了锁定某个会话，再切回自动跟随。

dsh-pilot 驾驶舱演示：浏览器操控与会话切换

安装——复制、粘贴、验收

从 GitHub 直装——当前唯一受支持的发布渠道：
dsh plugin --profile web add github:guo6x/dsh-pilot

如果 dsh web 正在运行，重启它再刷新页面。当侧边栏底部出现 ✈️ 按钮时，安装就完成了。点开即是驾驶舱。

要求：DSH web profile、Node ≥ 22、装了 Edge 或 Chrome。插件不需要额外账号、API key 或下载浏览器。

从本地 checkout 开发？在仓库目录执行 dsh plugin --profile web add .。仓库已提交 lib/ 构建产物，所以 GitHub 安装不会跑构建脚本。

第一条安全任务

新开一个对话，直接粘贴：

打开 https://example.com，告诉我页面写了什么，并确认 “Learn more” 链接可见。

你会看到带页面标题和编号链接的结构化回答，同时驾驶舱会显示同一页面。这个任务只读取公开网页。

如果看不到 ✈️ 按钮

- 确认插件安装在 web profile：dsh plugin --profile web list dsh-pilot。
- 安装后必须重启 dsh web；仅刷新浏览器不会加载新的宿主代码。
- 确认 Node 为 22 或更新版本，且 Edge/Chrome 至少装了一个；两者都没有时驾驶舱会报告启动错误。

60 秒看到它工作

要验证真实的预发布表单，可以给 agent 一个有边界的任务：

打开我们的 staging 报名表。填写联系信息，上传已授权的简历 C:\\path\\to\\resume.pdf，核对已填内容，在最终提交前停下。

agent 拿到的是页面的结构化证据，用 label 和快照编号交互，不会盲猜；驾驶舱则让你随时围观或一键停止浏览器。

它和普通浏览器自动化有什么不同

| 常见翻车点 | dsh-pilot 的做法 |
|---|---|
| agent 猜 CSS 选择器，悄悄点错元素 | 返回可见元素的编号快照；动作按编号执行，过期编号会明确报错 |
| 填一张表要反复逐字段调用 | pilot_fill 按人类字段名匹配，一次填写文本框、文本域和下拉框 |
| 浏览器自动化像黑箱，人在外面看不见 | 驾驶舱实时显示页面、URL、状态和最近操作 |
| 加浏览器能力要带框架和云端账号 | 直接使用 Node 22 原生 WebSocket + 本机 Edge/Chrome：零运行时依赖、零 API key |

agent 得到的工具

| 工具 | 作用 |
|---|---|
| pilot_open | 打开网址（首次自动拉起浏览器），返回标题/URL/正文快照 |
| pilot_snapshot | 把当前页面读成文本：标题、URL、可见文本（8k 字符）、链接、编号元素列表（refs），以及相对上次快照的变化摘要 |
| pilot_diff | 只报告相对上次快照的变化（URL/标题/文本增量、新增/消失的元素）——不重读整页就能判断动作是否生效 |
| pilot_click | 按快照编号（或 CSS 选择器）点击元素，先滚动到可视区 |
| pilot_type | 按快照编号（或选择器）往输入框打字（原生 value setter，React/Vue 表单能感知） |
| pilot_fill | 按字段 label/aria-label/placeholder/name/id 批量填写文本框、文本域和下拉框 |
| pilot_upload | 按快照编号（或选择器）向文件输入上传 1–10 个绝对路径文件（总计上限 100 MB） |
| pilot_press | 按键（Enter/Tab/Escape/方向键/单个字符） |
| pilot_back | 后退一页，等页面落定后返回 URL/标题 |
| pilot_reload | 刷新当前页，等页面落定 |
| pilot_wait | 等待 N 毫秒（1–30000），让异步内容加载完再动手 |
| pilot_wait_for | 等待页面文本、可见元素或 URL 条件满足，替代盲等 |
| pilot_assert | 立即验证页面文本、可见元素或 URL 条件是否满足 |
| pilot_screenshot | 存 PNG 并返回路径（给有视觉的模型或人看） |
| pilot_download | 下载资源（默认当前页），走页面自己的 fetch——继承会话 Cookie；上限 20 MB |
| pilot_eval | 页面里执行 JS，拿 JSON 结果 |
| pilot_close | 关掉浏览器；下次调用自动重启 |

agent 直接用大白话说需求即可："打开登录页，填表，点提交，读出结果" —— 工具动词和这句话一一对应。

人得到什么

可拖拽驾驶舱浮窗：实时截图（2 秒刷新）、当前 URL + 标题、启动/关闭按钮、地址栏、最近操作日志。多个会话同时开车时，可手动查看任意一个，或选择最近活跃继续自动跟随 agent。不想让它开了，一键关掉；想自己上手，随时接管。

已知限制

- 每会话单标签：ref 编号绑定当前页面，切标签会让编号失效。需要第二个上下文？开个子代理——每个 agent 会话自带独立浏览器。
- 仅 headless：驾驶舱显示的是 headless 画面，没有有头模式（人和 agent 同开一个浏览器是另一个产品）。
- 面板默认显示最近活跃会话的浏览器：每个会话仍是独立实例；会话多时可手动锁定任意一个，选择最近活跃即可恢复自动跟随。

原理

DSH 对话 ──pilot_* 工具──▶ 宿主插件 ──CDP(原生 WebSocket)──▶ headless Edge/Chrome
▲                             │
└── 结构化文本快照 ◀───────────┘
GUI 驾驶舱 ◀──/dsh-pilot/state + /dsh-pilot/shot.png（仅回环）──┘

- 以 headless 模式启动 msedge/chrome，独立 --user-data-dir（OS 临时目录），调试端口 9222 起动态选；停止时整棵进程树杀掉、临时 profile 删除，删除失败会重试并上报而不是被吞掉。每次启动还会清扫临时目录里被上一次强杀留下的旧 profile。
- 宿主注册 17 个工具 + 仅回环的 HTTP API（/dsh-pilot/*，非回环客户端一律 403）。
- 客户端是注册在 sidebar.footer.action + shell.overlay 的小浮窗。

安全说明

- 浏览器以 headless + 独立 profile 运行，绝不碰你真实浏览器会话。
- HTTP API 只挂在 DSH 服务（默认回环地址），并显式拒绝非回环客户端。
- pilot_open 只收 http(s) URL；pilot_eval 在页面上下文执行 JS（相当于你自己开 DevTools——别让 agent 去你不信任的页面）。
- pilot_upload 只接收现有的绝对路径普通文件；仅把用户已授权的文件上传到当前站点。
- 无遥测、无第三方网络调用、无 API key。

开发

pnpm install
pnpm test             # 构建、真 headless Edge 流程、发布包内容检查

MIT 协议。发现问题或有好点子，直接提 issue。

相关资源

- 中文实录（掘金）：我给我的 agent 装了双手：零依赖浏览器操控插件开发记