Skip to content
Back to search

dsh-zcode-cua

把 ZCode 的电脑控制(Computer Use)接进 DeepSeek Harness:点击、打字、读无障碍树与截图。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wkylnj--dsh-zcode-cua/badge.svg)](/listings/wkylnj--dsh-zcode-cua)

HTML

<a href="/listings/wkylnj--dsh-zcode-cua"><img src="/api/listings/wkylnj--dsh-zcode-cua/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

1. **Windows** 2. **ZCode installed and launched at least once** — this plugin reuses the native helper in ZCode's install directory and redistributes none of it. 3. **DeepSeek Harness** (this is a DSH bundle)

Into DSH

Option 1 (recommended): inside DSH, **Plugins → Add plugin**, then pick this directory. DSH links the checkout, so source edits take effect immediately.

Option 2: install from the checkout with the same command this was verified with:

cd "D:\path\to\dsh-zcode-cua"
dsh plugin --profile desktop add "link:$PWD"

Restart DSH afterwards. The tool appears as `mcp__zcode-cua__js`, and the plugin row reads **ZCode computer control**.

> **The package name must stay `dsh-zcode-cua`**, unscoped. The registration row points at the relative path `node_modules/dsh-zcode-cua/server/index.js`; that is what makes one file work on every machine, and it assumes the package is installed under the profile's `node_modules` under exactly that directory name.

Skill (optional, strongly recommended)

The tool works on its own, but the model will not know how to use it well. The skill lives at `skills/zcode-computer-use/SKILL.md` in this repository; install it into a DSH skill directory:

# user level (every project)
Copy-Item -Recurse .\skills\zcode-computer-use "$env:USERPROFILE\.dsh\skills\zcode-computer-use"

# or project level (only that project)
Copy-Item -Recurse .\skills\zcode-computer-use "D:\your-project\.dsh\skills\zcode-computer-use"

DSH does **not** load skills from a plugin directory — it scans `<project>/.dsh/skills`, `<project>/.agents/skills` and `~/.dsh/skills` only, so this step is manual. Restart DSH afterwards.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 196 lines
  1. # dsh-zcode-cua
  2. Brings [ZCode](https://zcode.ai)'s Computer Use into [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
  3. The model can click, type, read the accessibility tree and take screenshots of native desktop apps through a single `js` tool. DSH's own `dsh-cua-bundle` reports `unsupported-platform` on Windows, so this is the route that works there.
  4. [中文](README.zh.md) · [Changelog](CHANGELOG.md)
  5. ## What it adds
  6. One MCP tool, `mcp__zcode-cua__js`. Every call runs top-level `await` in a **fresh Node.js kernel**; the model drives the desktop with code:
  7. ```js
  8. const root =
  9. process.env.ZCODE_CUA_PLUGIN_ROOT ??
  10. process.env.ZCODE_PLUGIN_ROOT ??
  11. process.env.CLAUDE_PLUGIN_ROOT;
  12. const { join } = await import("node:path");
  13. const { pathToFileURL } = await import("node:url");
  14. const { setupComputerUseRuntime } = await import(
  15. pathToFileURL(join(root, "scripts", "computer-use-client.mjs")).href
  16. );
  17. await setupComputerUseRuntime({ globals: globalThis });
  18. const app = await agent.computerUse.getApp({ pid: 1234 });
  19. await app.getAXState(); // read the accessibility tree
  20. await app.click(12); // click by element index
  21. await app.typeText("hello");
  22. await app.getScreenshot();
  23. ```
  24. `agent.computerUse` exposes `getState` / `getApp` / `listApps` / `requestAccess` / `stop`, plus fourteen low-level `computer.*` tools. The ordered path is: `getAXState()` first, find the element by role and name, then act on its index. Coordinates are the last resort, for canvas and Electron content accessibility cannot see.
  25. The full API reference is `agent.documentation.get("computer-use")`, fetched on demand.
  26. ## The per-session switch
  27. **A new session cannot drive the desktop.** The `js` tool stays visible in the tool list, but every call is denied until the session opts in:
  28. > Computer control is off for this session. Ask the user to switch it on with the "Computer control" toggle under the message box, then call this tool again.
  29. The switch is a pill at the right end of the row under the message box — `电脑控制 · 已关闭` / `电脑控制 · 已开启`. One click flips it, and only for the session you are looking at.
  30. Why a switch rather than a setting: this tool clicks and types into whatever holds the keyboard. A profile-wide setting would mean one yes turns it on for every conversation, including the one that just asked a question and got an agent holding the mouse. Why a denial rather than hiding the tool: a tool missing from the schema reads as "the plugin is not installed", and the model would have no way to tell you which switch to flip.
  31. Three details worth knowing:
  32. - **The grant is per session and lives in memory.** Restarting DSH puts every session back to off. That is the safe direction for a capability that moves your mouse, so it is deliberate rather than a missing feature.
  33. - **A call with no session attached is denied**, even while another session is on. "No session" is not a session that said yes.
  34. - **Other tools are unaffected.** The guard only answers for `mcp__zcode-cua__js`; a guard that denied tools it does not own would quietly break unrelated plugins.
  35. The switch shows a third state — `电脑控制 · 状态未知` — when the host route cannot be reached. "Off" and "could not ask" must not look alike, or a broken switch reads as a working one.
  36. ## The on-screen indicator
  37. While a `js` call is running, a click-through overlay tells the user the computer is being driven: a blue glow around every screen edge, a banner, and a soft ring around the pointer. The banner's first line is always *DSH 正在控制电脑*; the second line is **what this call is doing**, taken from the `js` tool's required `title` argument — the same sentence the model already writes for the user.
  38. The point is that it is **invisible to the model**. Every window is marked `WDA_EXCLUDEFROMCAPTURE`, so Windows omits it from any screenshot — `PrintScreen`, `Graphics.CopyFromScreen`, and the GDI/DWM path the CUA helper itself uses. Verified on this machine: a full-screen capture taken mid-tool-call contains no trace of the overlay, while the same capture with the affinity cleared shows the full artwork.
  39. Nothing about it takes input or focus: the windows are `WS_EX_TRANSPARENT | WS_EX_NOACTIVATE | WS_EX_TOOLWINDOW`, so clicks pass straight through, focus is never stolen, and it never appears in the taskbar or Alt-Tab.
  40. Turn it off with `DSH_ZCODE_CUA_NO_OVERLAY=1`. The indicator is decoration — if PowerShell is missing, the C# fails to compile, or the host process dies, every path degrades to "no indicator" and tool calls keep working unchanged.
  41. The visual design is ported from [windows-mcp](https://github.com/CursorTouch/Windows-MCP)'s `control_overlay`; the implementation is a standalone Win32 layered window in C#, compiled at runtime by Windows PowerShell 5.1 so the plugin ships no binaries and needs no build step.
  42. ## How it is wired
  43. ```
  44. DSH ──MCP stdio──▶ this plugin's server/index.js
  45. ├─ injects ZCODE_CUA_PERMISSION_BROKER_SOCKET and friends
  46. └──▶ node-repl-host (ZCode's official MCP server, one `js` tool)
  47. └──▶ cua-helper (native Windows process, ax_native.node)
  48. └──▶ Win32 UI Automation / input injection
  49. ```
  50. This plugin does exactly two things: **resolve ZCode's installation layout**, and **translate between MCP 1.x and the modern protocol**. The CUA execution logic is ZCode's own runtime, unmodified, which is why behaviour matches ZCode.
  51. The upstream `js` tool is strict — anything beyond `code`, `timeout_ms` and `title` is refused — and this plugin passes it through untouched, adding no parameters.
  52. ## Install
  53. ### Prerequisites
  54. 1. **Windows**
  55. 2. **ZCode installed and launched at least once** — this plugin reuses the native helper in ZCode's install directory and redistributes none of it.
  56. 3. **DeepSeek Harness** (this is a DSH bundle)
  57. ### Into DSH
  58. Option 1 (recommended): inside DSH, **Plugins → Add plugin**, then pick this directory. DSH links the checkout, so source edits take effect immediately.
  59. Option 2: install from the checkout with the same command this was verified with:
  60. ```powershell
  61. cd "D:\path\to\dsh-zcode-cua"
  62. dsh plugin --profile desktop add "link:$PWD"
  63. ```
  64. Restart DSH afterwards. The tool appears as `mcp__zcode-cua__js`, and the plugin row reads **ZCode computer control**.
  65. > **The package name must stay `dsh-zcode-cua`**, unscoped. The registration row points at the relative path `node_modules/dsh-zcode-cua/server/index.js`; that is what makes one file work on every machine, and it assumes the package is installed under the profile's `node_modules` under exactly that directory name.
  66. ### Skill (optional, strongly recommended)
  67. The tool works on its own, but the model will not know how to use it well. The skill lives at `skills/zcode-computer-use/SKILL.md` in this repository; install it into a DSH skill directory:
  68. ```powershell
  69. # user level (every project)
  70. Copy-Item -Recurse .\skills\zcode-computer-use "$env:USERPROFILE\.dsh\skills\zcode-computer-use"
  71. # or project level (only that project)
  72. Copy-Item -Recurse .\skills\zcode-computer-use "D:\your-project\.dsh\skills\zcode-computer-use"
  73. ```
  74. DSH does **not** load skills from a plugin directory — it scans `<project>/.dsh/skills`, `<project>/.agents/skills` and `~/.dsh/skills` only, so this step is manual. Restart DSH afterwards.
  75. ## Configuration
  76. To change anything, find the `zcode-cua` row in the profile's `cordis.patch.yml`:
  77. ```yaml
  78. - id: zcode-cua
  79. name: '@deepseek-ai/dsh-mcp-client'
  80. config:
  81. serverName: zcode-cua
  82. transport: stdio
  83. command: 'node'
  84. args: ['node_modules/dsh-zcode-cua/server/index.js']
  85. toolCallTimeoutMs: 180000
  86. ```
  87. `command` defaults to `node`, which needs Node 18.17+ on PATH. The DSH desktop app ships its own Node; point `command` at it if you prefer an absolute path.
  88. ### Environment variables
  89. When layout resolution fails — ZCode installed somewhere unusual — override the three probes:
  90. | Variable | Points at |
  91. |---|---|
  92. | `ZCODE_BRIDGE_SERVER` | `node-repl-host`'s `dist/mcp/server.js` |
  93. | `ZCODE_CUA_PLUGIN_ROOT` | the `computer-use` plugin root (holds `scripts/computer-use-client.mjs`) |
  94. | `ZCODE_BRIDGE_HELPER_ROOT` | the `cua-helper` directory (holds `build/Release/ax_native.node`) |
  95. | `DSH_ZCODE_CUA_NO_OVERLAY` | set to `1` to disable the on-screen indicator entirely |
  96. | `DSH_ZCODE_CUA_KEEP_GHOST_CURSOR` | set to `1` to keep ZCode's own pointer overlay; by default it is suppressed so only the indicator above is on screen |
  97. Usually none are needed: the plugin looks for ZCode in the **uninstall registry** (`InstallLocation`), in `ZCODE_HOME`, and in the conventional install locations.
  98. ## Limitations
  99. - **Windows only.** It needs `resources/tools/cua-helper` from ZCode's install directory (the `ax_native.node` native module). ZCode currently has peer-identity verification disabled on Windows (`WINDOWS_PEER_IDENTITY_GATE_TEMPORARILY_OPEN = true` in `windows-helper.js`) — **this plugin did not open that gate**; the day ZCode closes it, this plugin stops working.
  100. - **No picture-in-picture.** `ax_native.node` exports no `pip*` functions at all and `pipSessionEnabled` is always false on Windows, so there is nothing to enable. The banner and screen glow described above stand in for the missing visual feedback, and unlike a cursor overlay they are guaranteed absent from screenshots.
  101. - **ZCode's own pointer overlay is suppressed on purpose.** The upstream launches the native helper with `--ghost-cursor-overlay` unconditionally — no setting or environment variable turns it off — so `server/helper-launcher.js` strips that flag before exec'ing the real helper. Two indicators disagreeing about what is happening is worse than one, and the ZCode overlay is a plain top-level window that any full-screen capture picks up. Set `DSH_ZCODE_CUA_KEEP_GHOST_CURSOR=1` to keep it. (Even when kept, it only paints inside a request scope that this path never supplies, for the reason recorded in 1.1.0.)
  102. - **No Browser Use.** Upstream `node-repl-host` implements a Browser Use bridge, but it needs a `browserBroker` from the host and this plugin only wires the Computer Use bridge. Use DSH's own Browser Use for web pages.
  103. - **Every `js` call is a fresh kernel.** Variables do not survive between calls, so bootstrap every time.
  104. - **Do not drive the desktop from two sessions at once.** There is only one helper in the whole chain: `@deepseek-ai/dsh-mcp-client` is a profile-level plugin, so DSH runs a single instance and a single child process. What actually keeps two sessions apart is the upstream serialisation lock — the bridge passes the same process-wide `session_id` (`dsh-<uuid>`, generated once at startup) for every DSH session, and upstream `server.js` wraps each `js` execution in `serialized(sessionKey, ...)` keyed on that id, so calls from different sessions queue behind one another. Two sessions therefore cannot click at the same time, but a long call in one session blocks every other session's `js` calls until it returns. Keep desktop work in a single session; run other sessions in a different DSH window without Computer Use, or wait for the first one to finish.
  105. - **The model really clicks and types on your desktop.** That is the capability, not a defect; disable the plugin row when you do not need it.
  106. ## Security notes
  107. - The helper's permission broker socket is created inside this plugin's own process under a random name (`\\.\pipe\zcode-cua-helper-<uuid>`) and disappears with the process.
  108. - This plugin reads, stores and forwards no ZCode or WorkBuddy credentials. It only drives a runtime already installed on the machine.
  109. - Tool calls are governed by DSH's tool permission system; use a DSH permission preset for tighter limits.
  110. ## Development
  111. ```
  112. server/paths.js resolves ZCode's three install locations
  113. index.js the Host half: the per-session tool guard and the switch's routes
  114. client.js the composer switch (browser module)
  115. server/index.js the MCP stdio server; spawns upstream and translates the protocol
  116. server/access.js the grant table and the guard body
  117. server/overlay.js owns the indicator's host process and brackets tool calls with it
  118. server/overlay/ Overlay.cs (the Win32 layered window) and host.ps1 (its resident driver)
  119. server/helper-launcher.js drops the upstream's forced --ghost-cursor-overlay, then execs the helper
  120. test/smoke.mjs end-to-end: handshake, tools/list, one real js call, cancellation
  121. test/overlay.mjs end-to-end: the indicator appears during a call and leaves afterwards
  122. test/access.mjs unit: the guard denies, allows, and scopes grants per session
  123. skills/ the skill (installed manually into a DSH skill directory)
  124. locale/ plugin display metadata
  125. docs/ detail page image
  126. cordis.patch.yml the two registration rows
  127. ```
  128. No build step, no runtime dependencies, pure ESM. Restart DSH after a change.
  129. ```sh
  130. node test/access.mjs # 13 checks
  131. node test/smoke.mjs # 5 checks
  132. node test/overlay.mjs # 9 checks
  133. ```
  134. ## License
  135. MIT. See [LICENSE](LICENSE).
  136. This plugin contains no ZCode binaries or source. It drives a ZCode installation already present on your machine; those rights belong to their respective owners.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.