# ZCode Computer Use MCP Windows（Windows提取版）

从 `C:\Program Files\ZCode` 提取的内置 Computer Use MCP，不依赖 ZCode/Electron 宿主，可接入任意 MCP 客户端。

提取版本：`0.5.14`（对应 `@zcode/zcode-cua-plugin` / `@zcode/zcode-cua-helper-runtime`）
原版文件保持不动，本目录是副本。

## 目录

```
zcode-cua-standalone\
  launcher.mjs              # 一键启动器：拉起 helper + MCP server(stdio)
  test-client.mjs           # 最小 MCP 客户端，用于自检
  plugin\                   # MCP server 侧（原 resources\glm\packages\zcode-cua-plugin）
    dist\mcp\server.js      #   30 个工具 + 帧/坐标投影 + broker 客户端
    node_modules\           #   未提交，需 npm install 还原（sharp/koffi）
  helper\                   # Windows 平台 helper（原 resources\tools\cua-helper）
    dist\windows-helper.js  #   broker server + 平台逻辑
    build\Release\ax_native.node  # 原生插件：UIA / WGC / SendInput / 剪贴板 / DPI
    node_modules\           #   未提交，需 npm install 还原（sharp）
    runtime-manifest.json
  skill\computer-use\SKILL.md   # 从 MCP 剥离出的行为指南（宿主侧内容，非 MCP 提供）
  mcp-config.example.json   # MCP 客户端配置示例
  run-mcp.cmd               # 便捷入口（等价于 node launcher.mjs）
```

## 运行要求

- Windows 10/11 x64，交互式桌面会话（不能跑在服务/无桌面会话）
- Node.js（实测 v24.14.1；`ax_native.node` 是 N-API 插件，ABI 稳定）
- 无需 ZCode.exe；无需管理员权限（但也因此无法操作以管理员身份运行的窗口，UIPI 限制）

## 安装（首次使用）

仓库**不包含 `node_modules`**，克隆后先在两个子目录还原运行时依赖：

```powershell
git clone https://github.com/A8Cl233395/zcode-computer-use-mcp-windows.git
cd zcode-computer-use-mcp-windows\helper
npm install --omit=dev

cd ..\plugin
npm install --omit=dev
```

- 版本固定为提取时的 `sharp@0.34.5`、`koffi@2.15.6`，npm 会自动拉取 win32-x64 预编译二进制。
- `helper\build\Release\ax_native.node` 已随仓库提供，无需本地编译。
- 原 `plugin\package.json` 里指向 pnpm workspace 的 `catalog:` 依赖已改为上述精确版本，因此可以脱离原 monorepo 独立安装。

## 使用

### 1. 自检

```powershell
node C:\path\to\zcode-cua-standalone\test-client.mjs
```

> 路径替换为实际克隆目录，下同。

预期：打印 `30 tools: ...` 和一段 `list_apps` 的应用列表。

### 2. 接入 MCP 客户端

配置示例（Claude Desktop / Claude Code / 其它支持 stdio 的宿主）：

```json
{
  "mcpServers": {
    "computer-use": {
      "command": "node",
      "args": ["C:\\path\\to\\zcode-cua-standalone\\launcher.mjs"]
    }
  }
}
```

`launcher.mjs` 的职责：

1. 生成随机命名管道 `\\.\pipe\zcode-cua-helper-<hex>` 与随机 token；
2. 以 `--socket <pipe> --parent-pid <自己>` 启动 helper，token 经环境变量 `ZCODE_CUA_PERMISSION_BROKER_TOKEN` 传入；
3. 收到 helper 的 `ready`（原生插件加载完成）后设置 `ZCODE_CUA_PERMISSION_BROKER_SOCKET/TOKEN` 并调用 MCP server 的 `main()`；
4. 客户端断开 / 进程退出时通知 helper 关闭；helper 自身也有 parent-pid 看门狗，且 90 秒内无人认领（首个 `broker_info`）会自杀，避免孤儿进程。

## Skill 是怎么提供的（不是 MCP）

原版 `plugin.json` 里的 `"skills": "skills"` 是 **ZCode 插件宿主的功能**：宿主扫描 `skills/**/SKILL.md`，把 frontmatter 的 `name/description` 注册成"技能"，在需要时把正文注入模型上下文（与 Claude Skills 同类的机制）。MCP 本身不提供 skill——`tools/list` 里只有 30 个工具，没有 resources/prompts。MCP 工具描述里原来只有一句指向 `SKILL.md "Choose the target"` 的提示（`SKILL_REF`），本提取版已把这两处置空，因此 MCP 工具 schema 里不再出现 SKILL.md 引用。

剥离后的技能文件在：

```
skill\computer-use\SKILL.md   # 完整行为指南：a11y 优先、元素/坐标目标选择、重试安全等
```

接入方式（任选其一，取决于宿主）：

- **Claude Code / Codex / opencode 等读 AGENTS/CLAUDE 的宿主**：把 `SKILL.md` 放到技能目录，或在 `AGENTS.md`/`CLAUDE.md` 里 `@`/引用该文件；
- **任意 MCP 宿主**：把 `SKILL.md` 正文作为 system prompt 或项目指令注入（内容本身与工具 schema 无关）；
- **想让 MCP 自己提供**：需改 `plugin/dist/mcp/server.js` 注册 `prompts`（MCP 的 prompt 机制），多数客户端目前不会自动使用，不推荐。

## 实现要点（为什么能独立跑）

- MCP server 与 helper 之间是**命名管道上的 NDJSON JSON-RPC**（`\\.\pipe\zcode-cua-helper-*`），token 认证，不依赖 Electron IPC。
- ZCode 宿主只做三件事：传 socket/token、显示权限面板、PiP 窗口；这些都不参与操控链路，缺失只影响对应 UI 功能。
- 观测：`get_app_state` → UIA 元素树（`CoCreateInstance(CUIAutomation)`）；截图走 **Windows Graphics Capture**（D3D11），PNG 再由 MCP 侧 sharp 压到最长边 1568 / JPEG。
- 动作：元素目标 → UIA 模式（Invoke/Value/Toggle/...，后台可点）；坐标目标 → 模型给栅格像素，MCP 用帧投影换成屏幕坐标，helper 校验前台后调用 **SendInput**（Windows 下坐标原始输入要求目标窗口前台）。

## 已知限制

- 只提取了 Windows helper；macOS（`ZCode Computer Use.app`）与 Linux 需要各自的 helper 与 `.node`。
- 原宿主提供的权限引导面板、PiP 实时画面、`prevent_activation` 宿主策略等不再存在；`request_access` 只返回状态快照。
- 键盘/鼠标高层 API 行为受原版策略约束：`strategy=event` 的原始输入要求目标应用在最前；不要用它操作管理员窗口。
- 本目录中的二进制与代码版权归原项目（ZCode/Z.ai）所有，仅供本地研究/集成使用，请遵守原始许可。