dsh-operator

dsh plugin --profile web add dsh-operator

<p align="center">

<img src="assets/icon.png" width="104" alt="dsh-operator icon">

</p>

dsh-operator

给每个 DSH 会话一双手。





dsh-operator 是一个装一次、所有会话可用的 Computer Use 插件：安装进 DSH 的 desktop profile 后，无论你开「标准 / PTC / 极简 / 创造」哪种模式，会话里都会直接出现一套桌面 GUI 工具，支持看屏幕、点鼠标、敲键盘、开应用，也带一个后台 code_agent。不用建特殊会话，也不用切模式。

它不依赖任何外部账号、远程服务或运行时二进制：核心能力是纯 JavaScript + macOS 自带命令 + 一个编译好的小型 AX 助手。接入 cua-driver 只是可选增强，用来做「AI 在后台操作、你同时用电脑」的人机并行。

为什么值得装

• 装一次，全局可用：挂在 host 层工具栈里，所有当前和将来的会话自动继承，不需要每个会话单独配。
• 观察自带省 token 机制：Retina 截图先按长边 1280 + JPEG q80 编码再交给模型（约原图 1/4 的图片 token）；原生 App 额外附 AX 文本快照（通常约 1KB），比只给截图少猜很多。
• 动作有校验：每次动作后自动重采并比较，给出 actionEffect（confirmed / unverifiable / suspected_noop）；失败会附上可读提示，而不是让模型瞎猜。
• 后台人机并行（可选）：接入 cua-driver 后，cua_launch 后台启动 App、cua_observe 读窗口、cua_act 在后台点击/输入，不移动你的真实光标、不抢占焦点；你也可以选择不装，全部基础工具照常可用。
• 安全边界清楚：危险快捷键/「删除」类按压默认拦截（guard）；审计日志只记元数据、不存屏幕内容；失败样本自动脱敏；剪贴板用完还原。
• 代码可自持：MIT，全部能力代码在本仓库维护、无外部补丁链，490 项测试 + CI 全绿；欢迎自己改、自己发布。

3 分钟上手

# 1. 装进 desktop profile
dsh plugin --profile desktop add dsh-operator

# 2. 完全退出 DSH（⌘Q），再重新打开

首次使用 GUI 工具时 macOS 会弹「屏幕录制 / 辅助功能」授权，允许给 DeepSeek Harness（或你的 DSH 宿主 App）即可。打开任意会话，问它「截一张图看看我的屏幕」，能返回截图就说明通了。

升级：dsh plugin --profile desktop update dsh-operator（或再 add 一次），然后重启 App。

卸载：dsh plugin --profile desktop remove dsh-operator。

改动前想留后路：备份 ~/.dsh/profiles/desktop/ 下的 package.json、pnpm-lock.yaml、cordis.patch.yml 三件套即可回滚。

想跑仓库最新代码而不是发布版：git clone https://github.com/yffo/dsh-operator && dsh plugin --profile desktop add file:$PWD。

怎么跟它说话

装好之后不用记命令，用平时的说法讲清「目标 + 验收标准」就行：

你会说 · 它就去做

「打开系统设置，确认在「外观」页，截个图给我」 · 先看再开、最后给截图

「先看看现在前台是什么，别乱点」 · 只读观察

「这个流程存成技能，叫 archive-screenshots」 · 存成可回放的技能

「这是跨应用任务，先做计划再动手，每步校验」 · 生成计划并逐步执行

「写个交接」/ 新窗口只说 「接手」 · 交接与无缝续做

完整口语用法、出错时怎么问、它不会做什么，见 对话式使用指南。

只想让它看、不让它动：跟它说「只读模式」，或把 profile 的 guiTools 设为 false。

工具一览

会话里实际能用的工具（旧版名字默认保留，可用配置 legacyToolNames 关闭）：

类别 · 工具

观察 · screenshot（截图+前台信息）、wait / long_wait、cu_observe（按窗口读 AX/截图）、screenshot_window、list_windows、zoom_region（局部原生分辨率放大）、ocr（Vision 文本兜底：AX 拿不到时读截图，返回带坐标的文本行）

鼠标 / 键盘 · click、drag、scroll、input_text、hotkey、long_press、cu_act（后台动作）

AX 动作 · ax_press、ax_set_value、ax_scroll、ax_menu、ax_batch（2–12 个动作一批，可混跑桌面与浏览器动作）

窗口 / 应用 · list_apps、open_app（前台激活）、cua_launch（后台启动，不置顶）、open_in_browser、open_in_finder、window_move（含 left/right-half 等预设）

浏览器 DOM · browser_dom_snapshot、browser_dom_click、browser_dom_fill、browser_dom_probe（Chrome/Safari，AppleScript 优先，CDP 回退）

浏览器自动化 · browser_state、browser_prepare（可按 app 名找窗口）、browser_open、browser_click（ref 或文案）、browser_type、browser_pointer、browser_select、browser_key、browser_dialog、browser_download、browser_set_input_files（经 cua-driver：真实 profile、语义 ref、受信任输入）

浏览器 CDP · browser_wait、browser_read、browser_console、browser_network（需 browserCdpPort + Chrome --remote-debugging-port：等网络空闲/等元素、读页面可见文本、看控制台错误、看失败请求）

剪贴板 · clipboard_read、clipboard_write（文本/图片/文件；只读文本默认 4000 字符，硬顶 20000）

任务 / 技能 · task_profile、plan_create/list/update/run/delete、skill_save/list/show/run/delete

后台会话 · code_agent（另起标准会话执行代码/长任务）

查询 / 诊断 · verify_state（窗口标题/AX/前台等谓词轮询）、operator_status、failure_list（失败样本摘要）

可选：cua-driver 人机并行

基础工具用的是「真实键盘鼠标」语义；如果你希望 AI 操作的同时自己继续用电脑，接入 cua-driver：

# 1. 安装 cua-driver（见官方文档），确认：
cua-driver --version

# 2. 首次授权（Accessibility + Screen Recording 一次）
cua-driver permissions grant

# 3. 试试后台流程
#    cua_windows -> cua_observe -> cua_act / cua_launch

• cua_windows：列出窗口和 window_id（不需要前台）。
• cua_observe window_id=…：读该窗口的 AX 树（[N] 行 + element_token），可选截图附件。
• cua_act window_id=… action=click role=… name=…：后台点击/输入，默认 delivery_mode=background。
• cua_launch bundle_id=com.apple.Safari：后台启动 App 或打开文件/URL，不抢焦点。

环境变量：DSH_OPERATOR_CUA=0 关闭 cua 工具；DSH_OPERATOR_CUA_BIN 指定 cua-driver 路径；DSH_OPERATOR_CUA_SOCKET 指定 daemon socket。完整参数与已知限制见 docs/CUA-DRIVER.md。

浏览器自动化（真实 profile）

browser_* 走 cua-driver 的浏览器通道，直接操作你正在用的 Chrome/Edge/Brave（真实登录态、真实扩展、无自动化启动参数）：

# 1. 找到浏览器窗口
cua_windows app_contains="Chrome"
# 2. 绑定并拿语义快照（首次会要求授权；macOS Chrome 会弹一次它自己的调试确认）
browser_prepare pid=… window_id=… delivery_mode="foreground"
browser_state pid=… window_id=…        # 返回 target_id / tab_id / tabs / refs
# 3. 操作（ref 形如 p1:12，导航后失效）
browser_open url="https://example.com/"
browser_state target_id=… tab_id=…
browser_click ref="p1:2"
browser_type  ref="p1:5" text="hello" replace=true
browser_pointer action="scroll" delta_y=-600

• 输入默认走 Input.dispatchMouseEvent（受信任事件，不是 element.click()）；需要合成点击时才传 input_route:"dom_event"。
• 绑定用户浏览器需要显式授权；background_unavailable 时用 delivery_mode:"foreground"。
• 不读 Cookie/密码、不伪造指纹、不绕验证码；遇到挑战会停下并在提示里让你接管。
• DSH_OPERATOR_BROWSER=0 关闭这组工具；cua-driver < 0.38 时自动跳过。细节见 docs/BROWSER-AUTOMATION.md。

自带实例：独立窗口、用完即关

需要干净的登录环境（换个账号）或后台跑任务、不想动自己的浏览器时，让插件自己开一个实例——

独立 profile（独立 cookie）+ 独立调试端口，不碰你正在用的浏览器：

browser_launch headless=false            # 返回 pid / port / profileDir
browser_state  port=…                    # 后续 browser_* 都带这个 port
browser_close  port=…                    # 用完即关，临时 profile 自动删除

• 独立实例是按需的：不启动、不常驻，关掉就干净了，不会多一个窗口一直挂着。
• 传 user_data_dir 可以保留登录态，下次接着用；不传则用临时目录、关闭时删除。
• 与上面「真实 profile」的区别：那条复用的是你已有的登录态，这条是隔离出来的干净环境。

页面开发与调试

除了点击输入，还有四个页面开发用的工具（都走 CDP，读优先）：

browser_eval expression="document.querySelectorAll('.item').length"   # 跑一个表达

…(truncated)