DSH Hub / 插件 / @dsh-external/dsh-computer-use Anionex/dsh-computer-use ↗ ★ 12
@dsh-external/dsh-computer-use Accessibility-first macOS Computer Use capability for DeepSeek Harness with stale-observation protection, app leases, confirmations, screenshots, and Web diagnostics
包名 @dsh-external/dsh-computer-use
版本 0.1.0
许可证 MIT
最近更新 2026年8月13日 GitHub ↗ 文档 ↗ 安装 $ npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Anionex/dsh-computer-use复制
DSH Computer Use
为 DeepSeek Harness 提供原生 macOS 控制能力,默认不碰你的真实光标,也不因指针动作抢占前台;Bundle 可以在键盘输入前把目标应用带到前台,保证输入可靠。
DSH Computer Use 为 Agent 提供新鲜的 Accessibility observation、准确进程/窗口定向、stale state 拒绝、按应用限制的访问,以及动作后的可验证状态。语义化 Accessibility 始终优先;鼠标、拖拽、滚轮与键盘 fallback 会投递给选定进程,而不是全局桌面。
English | 中文
为什么它不同
Accessibility 权限允许进程读取和操作 macOS UI 元素,但这个权限本身并不会自动防止抢焦点或移动光标。是否干扰用户,取决于输入事件走哪条路由。
DSH Computer Use 的默认路由有意避免干扰:
不移动系统光标: helper 中没有 cursor warp 路径。
不做全局指针注入: click、scroll 与 drag fallback 使用 pid/window 定向的 SkyLight 路由,不进入全局 HID 事件流。
指针动作不激活应用: 语义化 Accessibility、目标进程指针输入与 keyboardPolicy: preserve 都不激活;keyboardPolicy: activate(Bundle 默认)在键盘 fallback 前把目标应用带到前台,与 Codex Computer Use 对齐。
独立 Agent 光标: click、scroll 与 drag 动作会移动一个点击穿透、不会激活应用的软件光标,同时保持系统真实光标不变。默认显示,并停留在动作落点,直到绑定窗口变化或收到 hide 命令;cursorAutoHideMs 可开启定时自动隐藏。
不盲目重放: 每个动作都绑定准确、未过期的 observation,并返回新鲜状态。
因此,这个原生动作层可以在用户继续使用当前前台应用时,操作许多后台应用。
它补充了什么
先观察再动作。 返回有界 Accessibility tree、带 index 的元素、准确 app/process/window metadata、权限状态和可选截图 Artifact。
把动作绑定到状态。 每个元素 index 只属于一个 opaque observationId;进程、窗口、locator 或目标身份变化都会 fail closed。
优先语义输入。 先使用 AXPress、可编辑 value、selected-text 赋值和元素声明的 Accessibility action,再考虑指针 fallback。
把 fallback 投递给目标。 键盘输入发给选定 pid;指针输入携带窗口本地坐标,发给选定 pid 和 CGWindowID,并通过点解析应用窗口,任意屏幕坐标都可以点击。
返回新鲜证据。 每个成功动作都会经过有界 settle,并返回新的完整或差分 observation。
按应用限制访问。 read/control lease 按 Agent、Session、turn 与准确 bundle id 分离;高影响动作另需一次性确认。
@dsh-external/dsh-computer-use · DSH Hub
保持模型表面聚焦。 只有当前 Agent 加载 Computer Use Skill 后才暴露执行 Tool。
证据:从未激活的后台 fixture 仓库包含确定性 AppKit fixture 和 universal native helper。发布测试会通过 open -g 以后台模式启动 fixture,再通过 Agent 使用的同一协议完成操作。
observe exact bundle id + pid
-> element: "Targeted pointer probe", no AXPress action
-> computer_click with observationId + element index + allowCoordinateFallback
-> fresh observation
-> activation "not-requested"; pointerRouting "target-process"
-> status "Status: pointer click"
Fixture 会记录每次 applicationDidBecomeActive 回调。独立 native monitor 还会在 click、scroll 与 drag 整个动作期间每毫秒采样系统光标和前台 pid。默认发布路径不得增加 activationCount,并要求光标坐标不变、前台 pid 不变、click/scroll 精确计数,并且 drag 只有一组完整 down/up gesture。
范围 dsh-computer-use 是原生动作层 ,不会取代更窄的接口:
浏览器任务应继续使用 browser automation 和 DOM/CDP 状态;
有 API、CLI 或专用应用插件时仍应优先使用;
OCR、视觉 grounding 与像素理解应交给独立安装的 dsh-vision-toolkit:加载 vision-tools Skill,把准确的截图 Artifact 路径传给 vision_glance、vision_ground、vision_detect、vision_crop 或 vision_long_screenshot_ocr;不要用 shell 驱动的 tesseract、screencapture 或临时 Swift/Python OCR 取代这些工具;
dsh-design 等领域 Bundle 可以在工作流跨入原生应用时组合 Computer Use。
快速开始
前置条件
macOS 14 或更新版本。
已安装 Web 或 Headless Profile、并挂载 Skill Tool 的 DeepSeek Harness。
用于观察和原生动作的 macOS Accessibility 权限。
只有请求截图时才需要 macOS Screen Recording 权限。
构建本仓库时需要 Node.js ^22.19.0 或 >=24.0.0。
软件包当前尚未发布到 npm,请从 checkout 安装:
git clone https://github.com/dsh-external/dsh-computer-use.git
PLUGIN="$PWD/dsh-computer-use"
dsh plugin --profile web add "$PLUGIN"
dsh plugin --profile headless add "$PLUGIN"
dsh --profile web --dump-config | grep computer-use
dsh --profile headless --dump-config | grep computer-use
修改已安装插件后,需要重启正在运行的 dsh web host,再创建一个新 Session,让 host 重新载入 Bundle 与 Skill catalog。
使用 Computer Use 检查正在运行的 DSH Computer Use Fixture,启用 deterministic option,并根据动作后返回的新状态报告结果。优先使用 Accessibility 元素,不要复用旧 observation。
工作原理 flowchart LR
A["Select exact bundle id and pid"] --> B["Acquire scoped read access"]
B --> C["Observe AX tree and optional screenshot"]
C --> D["Choose indexed element or window-relative point"]
D --> E["Acquire control and optional one-use confirmation"]
E --> F["Re-observe and validate exact target"]
F --> G{"Input route"}
G -->|"Semantic"| H["Accessibility action or value"]
G -->|"Keyboard"| I["Post to target pid"]
G -->|"Pointer"| J["Post to target pid + window"]
H --> K["Wait for settlement"]
I --> K
J --> K
K --> L["Return fresh full or diff observation"]
每个元素 index 只在来源 observation 中有效。元素动作可以容忍无关 tree 变化,但会拒绝变化的进程、窗口、locator 或目标身份。坐标动作要求引用窗口的完整状态仍然新鲜。Stale 动作会返回 COMPUTER_STALE_OBSERVATION,不会搜索相似替代目标。
interaction:
focusPolicy: preserve
keyboardPolicy: activate
pointerInputPolicy: targeted
cursorVisualization: visible
cursorMotionMs: 180
cursorAutoHideMs: 0
cursorVisualization: visible 会在 click、scroll 与 drag 时显示 Agent 自己的非交互光标;它不会替代或移动 macOS 系统光标。不需要视觉反馈时可设为 hidden。pointerInputPolicy: deny 会禁用坐标点击/fallback、滚动与拖拽。keyboardPolicy: activate(Bundle 默认)会先激活目标应用,让 type-text 键盘 fallback 与 press-key 可靠工作;focusPolicy: activate 是更宽的兼容模式,还会在指针输入前激活。激活后 helper 会重新观察并校验准确目标,之后才发出输入。
Agent 光标是 28x28 的透明整图光标(Cursor 箭头加 DeepSeek 鲸鱼,assets/cursor.png),热点位于图片左上角。它由独立进程运行,点击穿透、不激活应用,并绑定准确已观察的 pid、窗口与 frame;目标窗口关闭、移动、缩放或最小化时会自动隐藏。
Helper executable 是 DSH 内部传输实现,不是公共授权 API。它要求独立进程组和父进程持有的标准传输,因此普通 shell 重定向会在解析命令前 fail closed。这个检查只属于纵深防御,不会认证同一 macOS 用户下运行的任意代码:专门构造的 detached 父进程仍能复现这类传输拓扑。应通过已注册 Tool 使用该能力,以保留应用 lease、敏感动作 confirmation 与宿主策略检查;不能把 danger-full-access 当作阻止直接 native 调用的保护。
activation: 'not-requested' | 'already-frontmost' | 'activated'
pointerInput: boolean
pointerRouting: 'none' | 'target-process'
模型 Tool Bundle 初始只贡献 computer_use_activate。加载 Skill 后,才为当前 Agent 暴露聚焦的执行 vocabulary。
Tool 用途 computer_list_apps列出有界用户应用及 bundle id、pid、前台状态和权限诊断 computer_observe返回新鲜的 full/diff Accessibility observation 与可选截图 Artifact computer_click优先使用 AXPress;也可通过目标进程指针输入点击已观察元素 frame 或窗口/屏幕坐标(coordinateSpace) computer_set_value不使用剪贴板,设置或清空可编辑 Accessibility value computer_type_text支持时通过 Accessibility 插入 Unicode,否则使用进程定向键盘 fallback computer_press_key向选定进程发送有限词表中的按键,并支持可选 modifier computer_scroll在窗口/屏幕坐标处向选定进程与窗口发送有界方向滚动 computer_drag在引用 observation 的窗口/屏幕两点之间拖拽 computer_perform_action执行选定元素声明的准确 Accessibility action computer_wait轮询一个有界 text/role/title 条件,不修改应用并返回新鲜状态 computer_confirm获取绑定准确敏感动作的一次性 token
任何 Tool 都不接受 AppleScript、JXA、shell、Swift、Objective-C、native selector、任意 Accessibility constant 或源码。
Observation、权限与敏感动作 Observation 包含 opaque id 与过期时间、准确 app 身份、frontmost/window metadata、有界 tree text、当前 indexed element、可选截图 metadata 和权限状态。Secure text value 以 [secure] 输出,不会进入 tree text、Tool result、截图 metadata 或 native error。截图仍可能包含应用中其他可见数据,应按敏感数据处理。
技术访问模型包含两类准确 bundle-id lease:
read:读取 Accessibility 状态和请求的截图;
control:向选定应用发送 UI 输入。
没有配置 grant 时,DSH 会请求 approval。Read approval 在 Session 内有效,control approval 只在当前 turn 有效。用户拒绝后,该 app/scope 在当前 Session 内保持最终结果。
Bundle 把 Session 级 read grant 和被拒绝的 app/scope 决定保存在自己拥有的 computer_use_state storage-domain sidecar 中,并用 Session header 的 createdAt 与 cwd 绑定准确生命周期;它不会向官方 Session 日志新增 Computer Use event,也不会修改 DSH Core。Web Profile 已经组合 @deepseek-ai/dsh-storage-domain;自定义 Profile 如果需要交互式 read grant 或持久拒绝状态,必须在本 Bundle 之前组合它。Settings 中配置的准确 grant 在没有 storage-domain 时仍可使用;获准的 control 决定只保存在当前进程的当前 turn。需要持久化的交互决定如果无法保存,操作会明确失败,不会静默缩短或削弱授权生命周期。
DSH danger-full-access preset 使用 approval/policy: never,因此未授权应用会在弹窗前被策略阻断。插件返回可操作的 COMPUTER_PERMISSION_REQUIRED 错误,并且不会把它记录成用户拒绝。请在 Computer Use Settings 中添加准确 bundle id,或改用 approval policy 为 ask 的 preset。
高影响外部通信、敏感数据传输、不可逆删除、账户/安全/隐私变更、未经请求的安装、法律条款接受,以及超出明确授权的财务完成动作,都需要在执行前立即调用 computer_confirm。Token 有短 TTL、只能使用一次,并绑定准确 app、process、observation 与 action;grant 不能绕过它。
macOS 权限与 native 完整性 Web Settings 分区展示 helper 完整性、Accessibility 与 Screen Recording 状态、当前 generation、interaction policy、限制和准确应用 grant。只有用户点击后,按钮才会打开相关 macOS 隐私页面;插件不能自行授予 TCC 权限。
Accessibility 与 Screen Recording 是 UI 权限,不是文件系统权限。正常使用保持在 DSH workspace-write 下:截图留在 Session workspace,临时文件使用 Session 私有临时目录,Bundle 不要求 danger-full-access。
仓库提交的 helper 是最低支持 macOS 14、ad-hoc 签名的 arm64 + x86_64 universal binary。native/macos/manifest.json 固定其 SHA-256、源码 digest、架构与 deployment target。pnpm run check:native 还会检查只有目标进程指针路由,并拒绝系统光标 warp 或全局指针 post symbol。
配置 字段 用途 observationTtlMsobservation 允许复用的生命周期;默认 0 关闭过期,也可设为最大 86400000 ms(24 小时)内的任意值 confirmationTtlMs一次性敏感动作 confirmation 的生命周期 actionTimeoutMs1000 到 120000 ms 的 native action 硬超时settleMs0 到 10000 ms 的动作后状态检查间隔maxSettleMs100 到 60000 ms 的动作后 settle 最大预算maxNodes / maxDepth / maxTextBytesAccessibility 遍历与模型可见文本上限 maxScreenshotBytesPNG Artifact 最大字节数 artifactRootworkspace 内的相对截图目录 helper.path可选的显式外部 helper executable helper.allowSourceBuild提交 helper 缺失时允许显式托管源码重建;默认 false interaction.focusPolicypreserve(默认)避免激活目标应用;activate 显式允许激活,并要求重新观察/校验interaction.keyboardPolicypreserve 不激活地把键盘事件定向投递;activate(Bundle 默认)在键盘 fallback 前激活目标应用interaction.pointerInputPolicytargeted(默认)允许 pid/window 定向指针输入;deny 禁用 click fallback、scroll 和 draginteraction.cursorVisualizationvisible(默认)显示独立 Agent 光标;hidden 只关闭 overlay,不影响输入interaction.cursorMotionMsAgent 光标移动动画时长,默认 180 毫秒 interaction.cursorAutoHideMsAgent 光标空闲后隐藏时间;默认 0 表示保持显示,直到绑定窗口变化或收到 hide 命令,也可设为最大 30000 ms 内的有限值 allowAllApps向所有运行中的应用授予 read 与 control;默认 false。开启后忽略精确 grants grants准确、无通配符的 bundle-id read/control policy;control: true 隐含 read
Settings 更新只有在校验与健康检查通过后才替换当前 provider generation;替换会使已有 observation 与待用 confirmation 失效。
状态与限制
状态:早期 0.1.0;稳定版本发布前,模型可见和 provider 行为仍可能变化。
当前 provider 只支持 macOS;Windows UI Automation 和 Linux provider 尚未实现。
目标进程指针投递使用动态解析的 SkyLight SPI。该路由不可用时,pointer fallback 会 fail closed,不会切换到全局输入。
点击点必须落在选定应用的某个屏幕内窗口中;helper 会解析该点下最上层的匹配窗口,frame/title 匹配有歧义不再阻塞坐标动作。最小化、隐藏或无窗口目标会 fail closed。
自定义 canvas、游戏、强化输入 surface 与未来 macOS 版本可能拒绝目标进程指针或键盘事件。应尽量优先使用语义化 Accessibility。
focusPolicy: activate 与 keyboardPolicy: activate 会有意打断前台工作,只作为操作方显式选择的兼容模式。
目标应用可能因接受动作而自行改变 activation 或 focus。
软件包按请求捕获离散 observation,不提供实时桌面流。
浏览器工作应继续使用 browser automation,因为 DOM/CDP 状态更窄、更精确。
npm 软件包名已写入 metadata,但尚未发布;请从 checkout 或本地 tarball 安装。
开发与发布验收 请把仓库放在 DeepSeek Harness checkout 旁边,让 TypeScript 与 Vitest 解析准确的 DSH peer declaration 和 runtime module:
workspace/
├── packages/
├── vendor/
└── dsh-computer-use/
pnpm install --frozen-lockfile
pnpm run build
DSH_COMPUTER_USE_REQUIRE_TCC=1 pnpm test
pnpm run check:native
pnpm pack --dry-run
pnpm run validate
pnpm run validate 会运行 keyless local lane 和干净 Web/Headless Profile lane。真实模型发布 lane 需要 DEEPSEEK_API_KEY,并支持可选的 DEEPSEEK_BASE_URL:
pnpm run validate:model
# or keyless validation followed by the real-model lane
pnpm run validate:release
移除 dsh plugin --profile web remove @dsh-external/dsh-computer-use
dsh plugin --profile headless remove @dsh-external/dsh-computer-use
移除或禁用 Bundle 会注销 Skill 与 Tool、取消 helper 工作、释放进程内 Agent observation、turn control grant 与 confirmation、关闭 storage-domain handle,并移除 Web contribution。已经生成的截图文件和插件自有的 computer_use_state sidecar 会保留,供用户显式清理。
安全、社区与支持
许可证