电脑控制 Anionex/dsh-computer-use

DSH Computer Use

为 DeepSeek Harness 提供原生 macOS 控制能力，默认不碰你的真实光标，也不因指针动作抢占前台；Bundle 可以在键盘输入前把目标应用带到前台，保证输入可靠。

DSH Computer Use 为 Agent 提供新鲜的 Accessibility observation、准确进程/窗口定向、stale state 拒绝、按应用限制的访问，以及动作后的可验证状态。语义化 Accessibility 始终优先；鼠标、拖拽、滚轮与键盘 fallback 会投递给选定进程，而不是全局桌面。

为什么它不同

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 动作会移动一个点击穿透、不会激活应用的软件光标，同时保持系统真实光标不变。它只在准确目标应用位于前台时显示，并沿速度/加速度塑造的轻微弧线移动。点击与滚动会等待到达后再输入；拖拽会先到达起点并显示按下，再让目标进程拖拽与光标向终点移动同步开始。
- 不盲目重放： 每个动作都绑定准确、未过期的 observation，并返回新鲜状态。

因此，这个原生动作层可以在用户继续使用当前前台应用时，操作许多后台应用。

它补充了什么

- 先观察再动作。 返回有界 Accessibility tree、带 index 的元素、准确 app/process/window metadata、权限状态和可选截图 Artifact。
- 把动作绑定到状态。 每个元素都带有 observation-local index 与 opaque targetHandle；准确 locator 继续兼容，而显式允许的重绑定只接受同一进程和窗口内唯一的 native 或 semantic 身份。
- 优先语义输入。 先使用 AXPress、可编辑 value、selected-text 赋值和元素声明的 Accessibility action，再考虑指针 fallback。
- 把 fallback 投递给目标。 键盘输入发给选定 pid；指针输入携带窗口本地坐标，发给选定 pid 和 CGWindowID，并通过点解析应用窗口，任意屏幕坐标都可以点击。
- 返回新鲜证据。 每个成功动作都会经过有界 settle，并返回新的完整或差分 observation。
- 按应用限制访问。 read/control lease 按 Agent、Session、turn 与准确 bundle id 分离；高影响动作另需一次性确认。
- 保持模型表面聚焦。 只有当前 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 一键安装 Web 与 Headless Bundle：

[!IMPORTANT]
已发布的包名为 @anionex/dsh-computer-use。旧名 @dsh-external/dsh-computer-use 从未发布到 npm，不可安装；安装前请先更新旧的 profile 或 manifest 引用。

dsh plugin --profile web add @anionex/dsh-computer-use
dsh plugin --profile headless add @anionex/dsh-computer-use

dsh --profile web --dump-config | grep computer-use
dsh --profile headless --dump-config | grep computer-use

本地开发时，把包名替换为 checkout 的绝对路径即可。

修改已安装插件后，需要重启正在运行的 dsh web host，再创建一个新 Session，让 host 重新载入 Bundle 与 Skill catalog。

在新 Session 中加载 Skill：

/dsh-computer-use

旧的 /computer-use Skill 仍供现有会话使用。如果已安装其他同名 Skill，请加载 /dsh-computer-use 来激活本插件。

然后可以尝试：

使用 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 target handle, index, 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"]

每个已观察元素都有 observation-local 兼容 index 和 opaque targetHandle。仅传 index 的动作保留准确 locator 行为。低风险元素动作可以传入 targetHandle 与 allowRebind: true；输入前，provider-independent resolver 会获取新鲜 Accessibility 状态，并依次检查原 locator、唯一 provider-native identifier（例如 macOS AXIdentifier），以及基于 role、accessible name、已声明 action 和稳定 ancestor fingerprint 的唯一 semantic match。Resolver 始终保留准确 bundle id、pid 与选定窗口身份；遇到歧义或低置信度时返回 COMPUTER_TARGET_AMBIGUOUS 或 COMPUTER_TARGET_LOW_CONFIDENCE，不会猜测。坐标动作仍要求引用窗口的完整状态保持当前。

成功的元素动作会报告 resolution.mode、confidence、candidateCount 与 targetChanged。敏感目标一旦需要 rebind，旧的一次性 confirmation 会失效，并返回 COMPUTER_TARGET_REBIND_REQUIRES_CONFIRMATION；调用方必须观察当前 UI，并对新选择的 handle 再次确认。视觉坐标不是 target handle，不能授权敏感 rebind。本基础版本不包含 provider-native visual hit-test，该能力留待后续实现。

默认 interaction policy 为：

interaction:
focusPolicy: preserve
keyboardPolicy: activate
pointerInputPolicy: targeted
cursorVisualization: visible
cursorSpeedPxPerSecond: 1600
cursorAccelerationPxPerSecondSquared: 6000
cursorClickDelayMs: 90
cursorAutoHideMs: 0

cursorVisualization: visible 会在选定应用位于前台时，为 click、scroll 与 drag 显示 Agent 自己的非交互光标；它不会替代或移动 macOS 系统光标。不需要视觉反馈时可设为 hidden。pointerInputPolicy: deny 会禁用坐标点击/fallback、滚动与拖拽。keyboardPolicy: activate（Bundle 默认）会先激活目标应用，让 type-text 键盘 fallback 与 press-key 可靠工作；focusPolicy: activate 是更宽的兼容模式，还会在指针光标移动和输入前激活目标应用，并重新观察、校验准确目标。

Agent 光标是 28x28 的透明整图光标（Cursor 箭头加 DeepSeek 鲸鱼，assets/cursor.png），热点位于图片左上角。它由独立进程运行，点击穿透、不激活应用，并绑定准确已观察的 pid、窗口、frame 与当前前台应用；任一条件不再匹配时就会隐藏。移动时间由距离、最大速度与加速度计算，默认采用带对称加减速的轻微弧线；把速度和加速度调高后仍保留少量可见动画帧。Native 到达目标并经过配置的停顿后，才会发出点击输入。拖拽则先按同一顺序到达起点，再让目标进程拖拽与 Agent 光标向终点移动同时开始。

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'
resolution?: {
mode: 'exact-locator' | 'native-identifier' | 'semantic-rebind'
confidence: number
candidateCount: number
targetChanged: boolean
}
agentCursor?: { visible: false; reason?: string }
effect: {
observedStateChanged: boolean
observedForMs: number
note?: string
}

effect.observedStateChanged 比较窗口 title、id、frame 与 Accessibility 元素树；它不证明变化由本次动作造成，也无法观察纯像素、瞬时、远端或其他外部效果。只有独立 Agent 光标本应显示却无法显示或验证时，结果才会出现 agentCursor。

模型不能通过 Tool 参数覆盖这些宿主策略。

模型 Tool

Bundle 初始只贡献 computer_use_activate。加载 Skill 后，才为当前 Agent 暴露聚焦的执行 vocabulary。

查看完整 Tool 列表

| Tool | 用途 |
| computer_list_apps | 列出有界用户应用及 bundle id、pid、前台状态和权限诊断 |
| computer_observe | 返回新鲜的 full/diff Accessibility observation 与可选截图 Artifact |
| computer_click | 优先使用 AXPress；接受准确 index 或 opaque target handle，并可在目标进程坐标 fallback 前执行安全 rebind |
| computer_set_value | 通过准确 index 或 opaque target handle 设置或清空可编辑 Accessibility value，不使用剪贴板 |
| computer_type_text | 通过 Accessibility 或目标进程键盘事件插入 Unicode；method: keyboard 跳过不可靠的 AX 写入，但不改变宿主焦点策略 |
| computer_press_key | 向选定进程发送有限词表中的按键，并支持可选 modifier |
| computer_scroll | 在已解析元素或窗口/屏幕坐标处向选定进程与窗口发送有界方向滚动 |
| computer_drag | 在引用 observation 的窗口/屏幕两点之间拖拽 |
| computer_perform_action | 执行准确或安全 rebind 后的选定元素所声明的 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、带 opaque target handle 的当前元素、可选截图 metadata 和权限状态。Target handle 不暴露 provider object reference 或 native identifier。Secure text value 以 [secure] 输出，不会进入 target descriptor、tree text、Tool result、截图 metadata 或 native error。截图仍可能包含应用中其他可见数据，应按敏感数据处理。

对于 Electron 应用，helper 通过 AXManualAccessibility 请求暴露文档，并在有限时间内等待 web 控件出现。仅当应用支持该可写属性、目标位于 web 区域且调用明确传入 allowCoordinateFallback=true 时，才在 AX press 之前选择一次指向元素中心的目标进程鼠标点击。其他应用（包括 WebKit web 区域）、原生控件和未显式允许降级的调用仍优先走语义 AX 路径。AX press 成功后不会因为树未变化而自动重试：动作效果可能延迟或发生在界面之外。宿主的指针和激活策略仍然生效。

坐标动作支持三种空间：window 与 screen 以 point 为单位（与 Accessibility frame 一致），screenshot 以 observation 截图的像素为单位。截图按窗口的 backing scale 捕获且不含窗口阴影，因此图像是窗口 frame 的直接渲染，screenshot.pixelScale 表示每个 point 对应的像素数（Retina 上通常为 2）。从截图图像上读出的坐标必须用 coordinateSpace: 'screenshot' 传入；若当作 window point 传入，点击会整体偏移一个像素倍率——在 2x 屏上，想点窗口中间的点击会落到两倍偏移处，可能完全错过控件。Service 会在发送任何输入之前把截图像素换算为窗口 point，并对「超出窗口 frame 但落在截图范围内」的 window 坐标报错并说明倍率。

技术访问模型包含两类准确 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、target handle 与 action；grant 不能绕过它。只要 resolution 不再使用原 locator，该 token 就会失效，必须重新观察并再次确认。

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。

配置

查看 Bundle 配置字段

| 字段 | 用途 |
| observationTtlMs | observation 允许复用的生命周期；默认 0 关闭过期，也可设为最大 86400000 ms（24 小时）内的任意值 |
| confirmationTtlMs | 一次性敏感动作 confirmation 的生命周期 |
| actionTimeoutMs | 1000 到 120000 ms 的 native action 硬超时 |
| settleMs | 0 到 10000 ms 的动作后状态检查间隔 |
| maxSettleMs | 100 到 60000 ms 的动作后 settle 最大预算 |
| maxNodes / maxDepth / maxTextBytes | Accessibility 遍历与模型可见文本上限 |
| maxScreenshotBytes | PNG Artifact 最大字节数 |
| artifactRoot | workspace 内的相对截图目录 |
| helper.path | 可选的显式外部 helper executable；省略、空字符串或仅含空白字符时使用随包提供的托管 helper |
| helper.allowSourceBuild | 提交 helper 缺失时允许显式托管源码重建；默认 false |
| interaction.focusPolicy | preserve（默认）避免激活目标应用；activate 显式允许激活，并要求重新观察/校验 |
| interaction.keyboardPolicy | preserve 不激活地把键盘事件定向投递；activate（Bundle 默认）在键盘 fallback 前激活目标应用 |
| interaction.pointerInputPolicy | targeted（默认）允许 pid/window 定向指针输入；deny 禁用 click fallback、scroll 和 drag |
| interaction.cursorVisualization | visible（默认）显示独立 Agent 光标；hidden 只关闭 overlay，不影响输入 |
| interaction.cursorSpeedPxPerSecond | Agent 光标期望最大速度；默认 1600，范围为每秒 100 至 50000 像素；极端距离/参数组合下优先遵守 48 至 2000 毫秒的移动安全边界 |
| interaction.cursorAccelerationPxPerSecondSquared | Agent 光标加速度与减速度；默认 6000，范围为每秒平方 100 至 500000 像素 |
| interaction.cursorClickDelayMs | 到达后、点击/拖拽按下反馈与原生输入前的停顿；默认 90，范围 0 至 1000 毫秒 |
| interaction.cursorAutoHideMs | Agent 光标空闲后隐藏时间；默认 0 表示在目标保持前台且绑定有效时持续显示，也可设为最大 30000 ms 内的有限值 |
| allowAllApps | 向所有运行中的应用授予 read 与 control；默认 false。开启后忽略精确 grants |
| grants | 准确、无通配符的 bundle-id read/control policy；control: true 隐含 read |

已弃用的 0.2.x interaction.cursorMotionMs 仍会被接受，确保旧 Settings 文档能够加载，但运行时会忽略它；下次通过 Web Settings 保存时会移除该字段。

Settings 更新只有在校验与健康检查通过后才替换当前 provider generation；替换会使已有 observation 与待用 confirmation 失效。

状态与限制

- 状态：早期 0.3.0；稳定版本发布前，模型可见和 provider 行为仍可能变化。
- 当前 provider 只支持 macOS；Windows UI Automation 和 Linux provider 尚未实现。
- 在非 macOS 主机上插件会优雅降级：DSH profile 正常启动，不会注册 Computer Use 工具与 Skill，Web Settings 会显示 COMPUTER_UNSUPPORTED_PLATFORM，而不是让启动失败。
- 目标进程指针投递使用动态解析的 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 包以 @anionex/dsh-computer-use 安装，可同时挂载到 Web 与 Headless Profile。

开发与发布验收

请把仓库放在 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 @anionex/dsh-computer-use
dsh plugin --profile headless remove @anionex/dsh-computer-use

移除或禁用 Bundle 会注销 Skill 与 Tool、取消 helper 工作、释放进程内 Agent observation、turn control grant 与 confirmation、关闭 storage-domain handle，并移除 Web contribution。已经生成的截图文件和插件自有的 computer_use_state sidecar 会保留，供用户显式清理。

安全、社区与支持

- 潜在漏洞按 SECURITY.md 私下报告。
- 修改代码或文档前请阅读 CONTRIBUTING.md。
- 安装、权限、配置和工作流问题见 SUPPORT.md。
- 在项目空间中遵守 Code of Conduct。
- 版本记录见 CHANGELOG.md。
- 维护支持方式见 FUNDING.md，赞助不购买 roadmap 控制权或私有支持。

关于

DSH Computer Use 由 anionex 维护。如果你想了解我后续的更多工作，欢迎在 X 或 GitHub 关注我。

许可证

MIT © 2026 anionex。