dsh-pilot：基于 DSH 会话权限的浏览器自动化插件

前言¶

在 DSH 插件生态中，驱动浏览器的工具不少，大多通过读取页面的无障碍树来工作，这是行业惯例，而非特色。关键在于权限模型。现有的插件通常只在工具调用的入口点检查权限，这使得重定向、页面内的链接点击或历史导航轻易绕过检查。

dsh-pilot 修正了这一点。它不自己发明一套权限系统，而是直接读取 DSH 会话自身的批准立场，并在网络层通过请求拦截强制执行。这意味着无论页面如何跳转，只要会话没有授权，导航就会被阻断。

核心功能¶

该插件提供以下工具，用于在浏览器上下文中操作页面：

pilot_navigate：处理 goto、后退、前进、刷新和标签页操作。这是唯一受 origin 限制的入口，决策在网络层强制执行（包含重定向、链接跳转和历史移动）。
pilot_snapshot：返回页面的无障碍树，元素带有 [ref=eX] 标记。支持 Shadow DOM 和同源 iframe。
pilot_act：通过 ref 执行点击、输入、按键、悬停、选择、勾选、取消勾选和上传。会报告控制台错误及是否触发了导航。
pilot_wait：等待选择器、文本、URL 片段或网络空闲。返回 satisfied: false 而非盲目的重试循环。
pilot_screenshot：将视口或全页 PNG 截图保存到工作区，供人工查看。
pilot_close：在任务完成后关闭标签页。

安装与启用¶

安装该插件需要 Node.js 版本在 ^22.19 或 >=24 之间。

dsh plugin --profile web add dsh-pilot

插件会自动使用已安装的 Google Chrome 或 Microsoft Edge。若需使用 Chromium，需先运行 npx playwright install chromium 并在配置中设置 browserChannels: [chromium]。

权限模型¶

权限模型完全基于 DSH 会话，而非插件内部逻辑。

本地访问：localhost 总是可用，前端测试无需额外配置。
预授权来源：通过 allowedOrigins 预先授权已知的良好来源。
会话跟随：其余访问遵循 newOriginPolicy（默认为 auto）：
- 会话批准策略为 ask 时，对每个来源询问用户一次。
- 会话处于 danger-full-access（批准策略为 never）时，静默允许。
- 无批准通道（无人值守自动化）时，拒绝访问。
网络层边界：决策在浏览器上下文的请求拦截器中执行，因此重定向、页面内链接点击和后退/前进操作无法绕过此检查。弹窗（window.open）会在到达时被关闭。
凭证卫生：默认拒绝向密码字段输入内容，除非部署设置了 allowPasswordFields: true。上传限制在工作区文件，下载指定目录。

配置示例¶

在 DSH 的插件配置中，dsh-pilot 支持以下参数：

- id: pilot
  name: dsh-pilot
  config:
    headless: true
    browserChannels: [chrome, msedge, chromium]
    viewportWidth: 1280
    viewportHeight: 800
    navigationTimeoutMs: 15000
    actionTimeoutMs: 5000
    waitMaxMs: 60000
    snapshotMaxChars: 24000
    maxTabs: 8
    allowedOrigins: []
    newOriginPolicy: auto       # auto | ask | deny | allow
    allowPasswordFields: false
    profileDir: ''              # 留空表示每次运行使用隔离上下文
    screenshotDir: .dsh-pilot
    downloadDir: .dsh-pilot/downloads
    maxConsoleMessages: 100
    registerSkill: true

启用 profileDir 可让智能体在持久化的浏览器配置文件中操作，但需了解由此带来的安全风险（已登录状态可能被访问）。

已知限制¶

已批准来源的累积：已批准的 origin 会随插件实例生命周期累积，并在同一 DSH 进程的会话间共享（即共享一个浏览器上下文）。
Canvas 内容：Canvas 渲染的内容无无障碍语义，pilot_screenshot 仅能将其展示给人类，截图转视觉模型的路线尚在计划中。
无头渲染差异：无头模式下的渲染行为与桌面浏览器存在差异，包括指针锁定、部分 GPU 路径以及操作系统对话框。
Ref 机制维护成本：Ref 机制基于 Playwright 内部实现。虽然 ariaSnapshot({ mode: 'ai' }) 是公开的，但将 ref 转换为选择器的 aria-ref= 引擎未公开，且 Locator.ariaRef() 在 Playwright 1.60 中被移除。因此 playwright-core 被锁定在 ~1.62.0 版本，后续版本更新需重新验证 Shadow DOM 和 iframe 场景。
名称冲突：该名称并非唯一。guo6x/dsh-pilot 是一个较早的、不同的插件，安装时需注意区分。

生态背景¶

DSH 插件独立于 DeepSeek 或幻方官方应用商店，属于社区目录管理的插件生态。dsh-pilot 维护者 Viger1 还开发了 dsh-preview（视觉检查）、dsh-review（缺陷审查）和 dsh-design（设计约束）等插件，它们可独立安装共存。

插件目录：https://www.skillhub.cn/plugins/Viger1/dsh-pilot
源码仓库：https://github.com/Viger1/dsh-pilot