@anionex/dsh-computer-use

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

DSH Computer Use



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

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

[English](README.md) | 中文

为什么它不同

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"

<p align="center">

<img src="assets/computer-use-fixture.png" width="760" alt="目标进程指针输入前、从未激活的确定性原生 fixture，显示专用 pointer probe 与 ready 状态。" />

</p>

Fixture 会记录每次 applicationDidBecomeActive 回调。独立 native monitor 还会在 click、scroll 与 drag 整个动作期间每毫秒采样系统光标和前台 pid。默认发布路径不得增加 activationCount，并要求光标坐标不变、前台 pid 不变、click/scroll 精确计数，并且 drag 只有一组完整 down/up gesture。

需求、架构、关键决策、验证证据和兼容性边界见[前台安全输入策略](docs/interaction-policy.md)。

范围

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
  cu

…(truncated)