浏览器与电脑控制 fegnze/dsh-browser-computer

浏览器与电脑控制（dsh-browser-computer）

把「让 DSH 驱动浏览器和电脑」变成插件，装一次就能接好线。
MCP 能力由 cordis.patch.yml 里的两行声明——playwright-mcp 和 peekaboo-mcp。这部分沿用官方「纯配置 bundle」的做法（templates/mcp + references/mcp-bundle.md）：只接 MCP 不需要 Host 或 Client 入口文件。本包额外提供 Host 和 Client 入口，用于健康检查、修复和状态 UI。激活步骤见下文。

激活后它会自动跑「检查环境 → 安装缺失依赖 → 检查权限 → 打开需要处理的权限面板」，UI 只有一行状态加一个 修复 按钮。它 从不写配置档配置（那是官方插件管理器的专属职责），也 从不改系统权限（只帮你打开对应的系统设置面板，由你点）。

接了什么

| 行 | 服务商 | 你能得到什么 |
| playwright-mcp | @playwright/mcp | 真实浏览器控制，靠无障碍快照和稳定 ref 驱动：导航、点击、填写、标签页、截图、网络、cookies/storage |
| peekaboo-mcp | @steipete/peekaboo | 读写 macOS 无障碍树、截图、真实鼠标和键盘输入（仅 macOS） |

command 在加载时通过 !!js 解析成 node 旁边那个绝对路径的 npx——没有硬编码任何机器相关路径，也不依赖 Finder/Dock 启动的应用拿到的那份精简 PATH （那里解析不出裸 npx，服务器会静默死掉）。

安装与激活

在 DSH 官方插件页添加下面任意一种 spec。允许命令行管理的配置档，用下面的命令。如果 Electron App 独占桌面配置档，就用它的插件管理器，别从命令行去管那个配置档。

1) from npm (recommended; specify @version for reproducible installs)
dsh plugin --profile <profile> add dsh-browser-computer

2) straight from GitHub
dsh plugin --profile <profile> add github:fegnze/dsh-browser-computer

3) local development (points at this directory; refresh/restart requirements still apply)
dsh plugin --profile <profile> add link:<absolute path to this repo>

安装后必须完全退出并重新打开 DSH App。 历史实测：

- 安装后两行 MCP 立刻出现在配置层（Config.listConfigs 能看到 playwright-mcp / peekaboo-mcp），但它们 不会 在运行中的会话里实体化成 mcp__playwright__ / mcp__peekaboo__ 工具，也不会拉起 MCP 子进程。
- Host 那半边的 JavaScript 被进程模块缓存扣着：不重启的话，激活仍然报上一版的错误。
- 官方 mcp-bundle 做法本身就以「安装，然后调用 mcp__<serverName>__<tool> 来验证」。

重启后，可以这样验证：让模型调用 browser_computer_repair，运行斜杠命令 /browser-computer repair，或者直接调用 MCP 工具（例如 mcp__playwright__browser_navigate）。

Client 那一半（插件页面上的那一节）还需要多做一步：刷新页面。只有 App 重启之后，启动图才会包含这个插件的 client 入口，所以已经打开的页面必须刷新一次才能加载到它。

它自己会做什么

插件激活时（安装，或 App 重启）会运行一次 repair，不需要你点任何东西：

1. 检查环境 —— Node / npx / 浏览器二进制文件 / 依赖包缓存
2. 安装缺失的依赖 —— npx -y <package> --version 会预热 playwright-mcp 和 peekaboo-mcp；已经缓存的包绝不会重新下载
3. 检查权限 —— 屏幕录制 / 辅助功能（--no-remote，所以状态归属于 DSH App 自己的进程链）
4. 引导权限 —— 如果有权限没授予，就打开对应的系统设置面板（它只负责打开面板，从不代为授予任何权限）

整个过程是幂等的，在后台运行；任何一步失败只会写一行日志，绝不会中断激活。把 autoRepairOnStart 设为 false 可以关掉它。

UI：一行状态和一个按钮

UI 位于这个插件自己的详情页（官方插槽 plugins.detail.section），不在宿主设置页里 —— 这是插件自己的健康检查，不是宿主偏好设置。Section 组件对其他插件的 subject 返回 null（只有当 subject.kind === 'bundle' && subject.pkg.name === <package name> 时才渲染），所以它绝不会跑到别的插件页面上。

只有两样东西：

- 一行状态加一张状态卡片（环境 / 三项权限 / MCP 连接），页面打开时自动读取一次（只读，不走网络）
- 一个「Repair」按钮 → POST /api/repair：安装缺失的依赖，打开需要授权的面板，最后验证连接

两个端点都要过两道关卡：自定义 intent 请求头（用来拦截跨站简单请求）和 connection.admit（Host/Origin 关卡加浏览器认证）。UI 不 require 任何 Harness Client 包；控件和样式都是它自己的，只引用 --dsw-alias- 主题 token。

在之前的开发环境里，改 Client 并不需要重启 App：编辑 src/client.js 会重建启动图，实时页面就能加载到（插件的入口会出现在 plugins.detail.section 的 occupants 里）。要做到免刷新更新，需要在同一个 checkout 里有一个活跃的 pnpm run dev:web watcher。如果没有验证过那个 watcher，就重新构建受影响的 Web 产物并刷新现有页面；不承诺自动更新。改 Host 需要完整重启。

两个操作

| 命令 | 工具 | 副作用 | 作用 |
| /browser-computer check | browser_computer_check | 无（不联网） | 本地依赖、macOS 权限状态、配置档接线冲突 |
| /browser-computer repair | browser_computer_repair | 安装包，可能打开面板 | 安装缺失依赖 → 检查并引导权限 → 验证 MCP 连接（verify: false 跳过这一步） |

不带参数时运行 repair。工具面刻意只保留这两个：工具 schema 是永久的上下文开销。

macOS 权限：能浪费你半小时的坑

TCC（系统设置 → 隐私与安全性）里没有「Event Synthesizing」开关。那是 Peekaboo 给它派生出的能力起的名字；它实际挂在辅助功能下面：

| 报告里的名称 | 系统设置里的位置 | 影响什么 |
| Screen Recording | 隐私与安全性 → 屏幕录制 | 截图、窗口枚举 |
| Accessibility | 隐私与安全性 → 辅助功能 | 读取/写入辅助功能树、后台点击 |
| Event Synthesizing | 同一位置；授予辅助功能后会自动打开 | 合成键盘、前台指针操作 |

有两件事你必须知道：

1. 授权对象是 DSH App，不是你的终端。插件用了 --no-remote，所以 Peekaboo 从本地执行环境报告权限，把状态归到 DSH App 的进程链上。改走 Peekaboo Bridge/daemon 是另一种授权，而且会拉起常驻进程。
2. 授权后重启 DSH App。 TCC 变更对已在运行的进程不一定生效。

安全边界（安装前先读）

- 插件的 computer 行传了 --allow-foreground：没有它，真实点击和输入都不可能。如果你只需要后台辅助功能操作，从 cordis.patch.yml 里删掉这一个参数就能降低权限。
- Playwright MCP 自带 browser_run_code_unsafe，厂商标注为「等同 RCE」。页面内容是不可信输入；别一上来就指向你日常用的浏览器配置档。
- 插件从不碰权限，所以上限完全取决于你的权限预设。
- 上下文开销：两个包加起来，会给每个系统提示词贡献大约 50 个工具 schema。如果觉得不值，从 cordis.patch.yml 里删掉对应行。

别接两次

如果你已经手动往 ~/.dsh/profiles/<profile>/cordis.patch.yml 里加了 serverName 相同的 MCP 行，它们会和插件声明的行冲突：两个 MCP 实例、工具名重复。check 阶段会报告这类冲突（wiring.conflicts），但不会改你的配置——删掉手动那行由你决定。

回滚

在官方 Plugins 页面移除插件，或者对命令行管理的配置档：

dsh plugin --profile <profile> remove dsh-browser-computer
删掉它，两行 MCP 都会一并移除。想保留能力、只去掉健康检查工具，就只删 browser-computer 那一行。

开发

cd dsh-browser-computer
node --test test/.test.mjs

测试从不运行真正的 npx：子进程、文件系统、环境全部注入。值得了解的几点：

- mcp-probe.test.mjs —— 在内存流上跑真正的换行分隔 JSON-RPC，覆盖成功 / RPC 错误 / 超时 / 启动失败
- doctor.test.mjs —— check / repair 的行为，包括「失败绝不粉饰成成功」
- http.test.mjs —— 路由的两道关卡（intent header + admit）、404、坏 JSON、错误透传
- client.test.mjs —— 真正执行 Client bundle 信封，在受控的全局环境里跑，能抓出信封 id 写错、导出形状不对、slot 注册不对、样式标签在插入前没打上归属标记，或者误 require 了另一个 Harness Client 包
- host.test.mjs —— commands / webServer 必须通过 ctx.inject 声明
- consistency.test.mjs —— 补丁里声明的参数必须和 src/packs.mjs 的 argv 一致，补丁里不能有写死的本地路径，图标必须满足 dsh-app-boot 的四条规则

我们踩过的三个坑（你就别再踩了）

1. apply 期间绝不要用 ctx.get('service')。 实测：插件正在 apply 时，ctx.get('webServer') 和 ctx.get('commands') 都返回 undefined，于是 if (svc?.register) 这道守卫会悄无声息地跳过注册 —— 安装时一切看着正常，只有你点下去才发现 404（或者斜杠命令根本不存在）。可选服务要用 ctx.inject([...], (c) => …) 声明；ctx.get 只在处理请求时安全，那时上下文已完整组装（比如读 connection）。
2. 图标填不满卡片不是你的问题。 Host 的 PackageArtwork 永远渲染 ，CARD_ARTWORK_SIZE = 36（组件行是 ROW_ARTWORK_SIZE = 30），外面套 48×48 的卡片，所以那圈留白是 Host 的布局。改图标文件改不动它。
3. 权限状态有三个值，不是两个。 Peekaboo 的 JSON 里，权限名在值的 name 字段
（{ data: { permissions: [ { name, isRequired, isGranted } ] } }），不在对象键上；
按键去查永远匹配不上，三个权限全报成 unknown。而且 unknown 绝不能报成「未授予」—— 早期版本就是这么干的。现在 missing 里只放 denied，unknown 单独出一份「读不到」的报告。另外，Event Synthesizing 是派生能力（TCC 没有对应开关，它跟随 Accessibility），所以它只报状态，绝不进 missing —— 否则会让人去找一个根本不存在的开关。

图标资源

- icon.png —— 插件实际使用的图标：透明背景，只有箭头主体本身，按图稿边界紧密裁剪，256×256，47 KB（dsh-app-boot 的上限是 256 KiB）。
- assets/icon-transparent.png —— 同一图稿的 768×768 母版，方便复用或重新导出。
- 两者都是 RGBA，四角 alpha 为 0，所以在深色或浅色背景上都不会出现白框。记住 Host 仍会把图片缩放到 36×36；那一圈是布局，不是文件里的白色边框。

已知限制

- computer 包只支持 macOS；在其他平台上，报告会标记为不支持，而不是假装它能用。
- repair 用 npx -y 拉取包，所以第一次运行可能很慢；超时会明确报出来，并提示「重试即可」。
- 权限读取依赖 Peekaboo 命令行的输出。如果那个格式变了，状态会降级为 unknown；报告从不猜测。
- 健康检查只验证「MCP 服务器能连上、工具都在」。它不验证某个具体操作能否成功 —— 那取决于页面内容和当前前台窗口，属于运行时事实。