# https://github.com/ARAS-Workspace/claude-kvm 项目说明书

生成时间：2026-05-31 04:01:59 UTC

## 目录

- [项目首页](#home)
- [系统架构](#architecture)
- [MCP 代理层](#mcp-proxy)
- [VNC 守护进程](#vnc-daemon)
- [工具参考手册](#tools-reference)
- [认证机制](#authentication)
- [安装指南](#installation)
- [配置参数详解](#configuration)
- [故障排除](#troubleshooting)
- [实时测试与演示](#live-testing)

<a id='home'></a>

## 项目首页

### 相关页面

相关主题：[系统架构](#architecture), [安装指南](#installation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
- [server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)
- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [LAUNCHGUIDE.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/LAUNCHGUIDE.md)
</details>

# 项目首页

## 项目概述

Claude KVM 是一个基于 [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 的服务器项目，允许通过 VNC 协议远程控制桌面环境。该项目专为 macOS 设计，利用 Apple Silicon 的原生性能，集成了 Apple Vision 框架进行本地 OCR 文本检测。 资料来源：[package.json:3]()[server.json:3]()

```mermaid
graph TD
    subgraph Claude["Claude Desktop"]
        A[用户指令]
    end
    
    subgraph MCP_Proxy["MCP Proxy (JavaScript/Node.js)"]
        B[MCP SDK]
        C[VNC Daemon 生命周期管理]
        D[stdio JSON-RPC 通信]
    end
    
    subgraph VNC_Daemon["VNC Daemon (Swift/C)"]
        E[LibVNC 库]
        F[屏幕捕获]
        G[输入注入]
        H[Apple Vision OCR]
    end
    
    subgraph Remote_Desktop["远程桌面 (macOS)"]
        I[VNC Server]
        J[ARD Apple Remote Desktop]
    end
    
    A --> B
    B --> C
    C --> D
    D <--> E
    E --> F
    E --> G
    E --> H
    F --> I
    G --> I
    H --> I
```

## 技术架构

### 核心技术栈

| 层级 | 技术栈 | 职责 |
|------|--------|------|
| **MCP Proxy** | JavaScript (Node.js/ESNext) | 与 Claude Desktop 通信，管理 daemon 生命周期，通过 stdio JSON-RPC 进行进程间通信 |
| **VNC Daemon** | Swift/C (Apple Silicon) | VNC 连接管理、屏幕捕获、鼠标/键盘输入注入、设备端 OCR |
| **底层库** | LibVNC (静态链接) | VNC/RFB 协议实现 |
| **OCR 引擎** | Apple Vision Framework | 设备端文本检测，无需外部 API |

资料来源：[README.md:50-56]()[LAUNCHGUIDE.md:45-48]()

### 通信协议

MCP Proxy 与 VNC Daemon 之间采用 **PC (Procedure Call) 协议**，通过 **NDJSON** (换行分隔的 JSON-RPC) 进行通信：

```json
// 请求格式
{"method":"<method_name>","params":{...},"id":<number|string>}

// 成功响应
{"result":{...},"id":<number|string>}

// 错误响应
{"error":{"code":<number>,"message":"<string>"},"id":<number|string>}

// 通知消息
{"method":"<method_name>","params":{...}}
```

资料来源：[README.md:63-68]()

### 坐标缩放机制

VNC 服务器的原生分辨率会被自动缩放至 `--max-dimension` (默认 1280px) 以内，确保 Claude 在一致的坐标空间内操作：

```
原生分辨率: 4220 × 2568 (VNC 服务器帧缓冲)
缩放分辨率: 1280 × 779   (Claude 可见的目标空间)

mouse_click(640, 400) → VNC 接收 (2110, 1284)
```

资料来源：[README.md:71-75]()

## 核心功能

### 屏幕操作

| 功能 | 参数 | 描述 |
|------|------|------|
| `screenshot` | - | 全屏截图 (~200ms) |
| `cursor_crop` | - | 在光标位置周围裁剪带十字线的区域 |
| `diff_check` | - | 检测与基准图像的屏幕变化 |
| `set_baseline` | - | 将当前屏幕设为差异检测基准 |

资料来源：[tools/index.js:13-16]()[README.md:96-98]()

### 鼠标操作

| 功能 | 参数 | 描述 |
|------|------|------|
| `mouse_click` | `x, y, button?` | 单击 (left/right/middle) |
| `mouse_double_click` | `x, y` | 双击 |
| `mouse_move` | `x, y` | 移动光标 |
| `hover` | `x, y` | 移动 + 悬停等待 |
| `nudge` | `dx, dy` | 相对光标移动 |
| `mouse_drag` | `x, y, toX, toY` | 从起点拖拽到终点 |
| `scroll` | `amount, direction` | 滚动 (up/down/left/right) |

资料来源：[tools/index.js:17-20]()[README.md:100-105]()

### 键盘操作

| 功能 | 参数 | 描述 |
|------|------|------|
| `key_tap` | `key` | 单键按下 (enter/escape/tab/space...) |
| `key_combo` | `key` 或 `keys` | 修饰键组合 ("cmd+c" 或 ["cmd","shift","3"]) |
| `key_type` | `text` | 逐字符输入文本 |
| `paste` | `text` | 通过剪贴板粘贴文本 |

资料来源：[tools/index.js:21-23]()[README.md:107-110]()

### OCR 文本检测

`detect_elements` 使用 Apple Vision 框架进行设备端 OCR，返回缩放坐标空间中的文本内容和边界框：

```json
{"method":"detect_elements"}
```
```json
{"result":{"elements":[{"text":"Finder","w":32,"x":37,"y":6,"h":9,"confidence":1},...],
"scaledWidth":1280,"scaledHeight":779}}
```

资料来源：[tools/index.js:24]()[README.md:112-119]()

### 配置与控制

| 功能 | 参数 | 描述 |
|------|------|------|
| `configure` | `{<params>}` | 运行时设置时间/显示参数 |
| `configure` | `{reset: true}` | 重置所有参数至默认值 |
| `get_timing` | - | 获取当前时间和显示参数 |
| `wait` | `ms?` | 等待 (默认 500ms) |
| `health` | - | 连接状态和显示信息 |
| `shutdown` | - | 优雅关闭 daemon |

资料来源：[tools/index.js:25-29]()[README.md:133-137]()

## 认证机制

Claude KVM 支持多种 VNC 认证方式：

| 认证类型 | 加密方式 | 平台 |
|----------|----------|------|
| **VNC Auth** | DES Challenge-Response | 通用 |
| **ARD (Apple Remote Desktop)** | Diffie-Hellman + AES-128-ECB | macOS |

当检测到 ARD auth type 30 凭证请求时，系统会自动识别 macOS 目标，并将 Meta 键映射为 Super 键以确保 Command 键兼容性。

资料来源：[README.md:150-154]()

## 运行时配置参数

### 时间参数

| 参数 | 默认值 | 描述 |
|------|--------|------|
| `click_hold_ms` | 50 | 点击按住时长 |
| `double_click_gap_ms` | 50 | 双击间隔 |
| `hover_settle_ms` | 400 | 悬停稳定等待 |
| `drag_press_ms` | 50 | 拖拽按下阈值 |
| `drag_step_ms` | 5 | 插值点之间间隔 |
| `drag_settle_ms` | 30 | 释放前稳定等待 |
| `scroll_press_ms` | 10 | 滚动按下-释放间隔 |
| `key_hold_ms` | 30 | 按键按住时长 |
| `type_key_ms` | 20 | 输入时按键时长 |
| `type_inter_key_ms` | 20 | 字符间间隔 |

### 显示参数

| 参数 | 默认值 | 描述 |
|------|--------|------|
| `max_dimension` | 1280 | 最大屏幕尺寸 (px) |
| `cursor_crop_radius` | 150 | 光标裁剪半径 (px) |

资料来源：[LAUNCHGUIDE.md:155-176]()

## 版本信息

| 组件 | 当前版本 |
|------|----------|
| claude-kvm (MCP) | 2.0.11 |
| claude-kvm-daemon | 1.0.1 |

资料来源：[package.json:4]()[server.json:12]()

## 已知问题与限制

### VNC 连接在长时间测试中断开

根据社区反馈 ([issue #8](https://github.com/ARAS-Workspace/claude-kvm/issues/8))，在长时间运行测试会话（约 50 轮）期间，VNC 连接可能断开且 daemon 无响应。SSH 到远程 Mac 仍保持活跃，表明问题发生在 VNC/ARD 服务器端，而非 daemon 或网络层。

> [!NOTE]
> 这是一个社区报告的问题，可能与 VNC 服务器配置或 macOS ARD 服务稳定性相关。

资料来源：[community_context:issue_8]()

## 安装与配置

### 前置要求

- macOS (Apple Silicon / aarch64)
- Node.js (LTS)
- VNC 服务器运行在目标 Mac 上

### 安装步骤

**1. 安装 Daemon:**

```bash
brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon
```

> [!NOTE]
> claude-kvm-daemon 在 CI (GitHub Actions) 上编译和签名。编译产物以两种格式打包：Homebrew 发布的 `.tar.gz` 和用于公证的 `.dmg`。公证后的 DMG 可在 CI Artifacts 获取。

**2. 配置 MCP:**

在项目目录创建 `.mcp.json` 文件：

```json
{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass",
        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon"
      }
    }
  }
}
```

资料来源：[LAUNCHGUIDE.md:62-79]()

## 使用场景

| 场景 | 描述 |
|------|------|
| 远程桌面自动化 | 通过自然语言控制远程 macOS 桌面 |
| GUI 测试 | CI/CD 环境中的视觉测试 |
| 屏幕采集 | 设备端 OCR，无需外部 API |
| 辅助功能自动化 | 无障碍操作自动化 |
| 桌面 Agent 编排 | 多步骤工作流自动化 |

资料来源：[LAUNCHGUIDE.md:14-21]()

## 相关链接

| 资源 | 链接 |
|------|------|
| 项目主页 | https://github.com/ARAS-Workspace/claude-kvm |
| 文档 | https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md |
| 问题反馈 | https://github.com/ARAS-Workspace/claude-kvm/issues |
| Homebrew Tap | https://github.com/ARAS-Workspace/homebrew-tap |
| MCP 徽章 | https://lobehub.com/mcp/aras-workspace-claude-kvm |

---

<a id='architecture'></a>

## 系统架构

### 相关页面

相关主题：[MCP 代理层](#mcp-proxy), [VNC 守护进程](#vnc-daemon), [工具参考手册](#tools-reference)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- [index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/index.js)
- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
- [server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)
- [LAUNCHGUIDE.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/LAUNCHGUIDE.md)
</details>

# 系统架构

## 概述

Claude KVM 是一个基于 MCP (Model Context Protocol) 的远程桌面控制系统，通过 VNC 协议实现对远程 macOS 桌面的自动化控制。该系统采用双层架构设计，将协议通信与底层硬件操作分离，以实现跨平台兼容性与高性能的平衡。

系统的主要职责包括：

- 通过 VNC 协议捕获远程桌面屏幕
- 向远程桌面注入鼠标、键盘输入事件
- 使用 Apple Vision 框架进行本地 OCR 文本检测
- 处理坐标缩放与坐标系转换
- 支持 Apple Remote Desktop (ARD) 认证

资料来源：[LAUNCHGUIDE.md:1-15]()

## 架构分层

Claude KVM 采用两层架构设计，各层承担不同的职责，通过标准化的协议进行通信：

| 层级 | 语言/技术 | 职责 | 通信方式 |
|------|-----------|------|----------|
| **MCP Proxy** | JavaScript (Node.js) | 与 Claude 通信，管理 daemon 生命周期，处理工具调用 | stdio JSON-RPC |
| **VNC Daemon** | Swift/C (Apple Silicon) | VNC 连接、屏幕捕获、鼠标/键盘输入注入 | stdin/stdout NDJSON |

```mermaid
graph TD
    subgraph "MCP Proxy 层"
        A[Claude Desktop] <-->|stdio JSON-RPC| B[MCP SDK]
        B <--> C[Daemon 管理器]
    end
    
    subgraph "VNC Daemon 层"
        C -->|NDJSON| D[PC Protocol Parser]
        D --> E[VNC 连接管理器]
        E <-->|VNC RFB| F[远程 VNC 服务器]
        G[输入事件注入] --> E
        H[屏幕捕获] --> E
        I[Apple Vision OCR] --> H
    end
    
    style A fill:#e1f5fe
    style F fill:#fff3e0
    style I fill:#e8f5e9
```

资料来源：[README.md:145-160]()

## MCP Proxy 层

### 核心组件

MCP Proxy 层是系统的入口点，负责与 Claude Desktop 进行交互。该层使用 Node.js 实现，主要依赖以下组件：

| 组件 | 版本 | 用途 |
|------|------|------|
| `@modelcontextprotocol/sdk` | ^1.26.0 | MCP 协议实现，处理 JSON-RPC 通信 |
| `zod` | ^4.3.6 | 输入参数校验与 schema 定义 |

### 工具定义

所有 VNC 操作通过单一的 `vnc_command` 工具暴露给 Claude。该工具支持多种操作类型：

资料来源：[tools/index.js:1-50]()

| 操作类别 | 操作 | 说明 |
|----------|------|------|
| 屏幕 | `screenshot`, `cursor_crop`, `diff_check`, `set_baseline` | 屏幕捕获与差异检测 |
| 鼠标 | `mouse_click`, `mouse_double_click`, `mouse_move`, `hover`, `nudge`, `mouse_drag`, `scroll` | 鼠标操作与拖拽 |
| 键盘 | `key_tap`, `key_combo`, `key_type`, `paste` | 键盘输入与剪贴板 |
| 检测 | `detect_elements` | Apple Vision OCR 检测 |
| 配置 | `configure`, `get_timing` | 运行时参数配置 |
| 控制 | `wait`, `health`, `shutdown` | 系统状态与生命周期 |

### Daemon 生命周期管理

Daemon 管理器负责 VNC 进程的启动、监控和优雅关闭：

```mermaid
sequenceDiagram
    participant Claude
    participant Proxy as MCP Proxy
    participant Daemon as claude-kvm-daemon
    
    Note over Proxy: 启动 Daemon 进程
    Proxy->>Daemon: 初始化连接
    Claude->>Proxy: vnc_command 调用
    Proxy->>Daemon: NDJSON 请求
    Daemon->>Proxy: NDJSON 响应
    Proxy->>Claude: 结果返回
    Claude->>Proxy: shutdown
    Proxy->>Daemon: shutdown 命令
    Daemon->>Daemon: 清理资源
    Proxy->>Daemon: 发送 SIGTERM
```

资料来源：[index.js:80-120]()

## VNC Daemon 层

### 核心能力

VNC Daemon 是原生 Swift 实现，负责与 VNC 服务器建立连接并执行底层操作：

| 功能模块 | 技术实现 | 说明 |
|----------|----------|------|
| VNC 连接 | LibVNC (静态链接) | 处理 RFB 协议通信 |
| 屏幕捕获 | CoreGraphics/CGDirectDisplay | 获取帧缓冲区数据 |
| 输入注入 | IOKit HID 事件 | 模拟鼠标键盘操作 |
| OCR 检测 | Apple Vision Framework | 本地文本识别 |
| 认证 | VNC Auth + ARD Auth | 支持多种认证方式 |

### 认证机制

系统支持两种 VNC 认证方式：

| 认证类型 | 算法 | 适用场景 |
|----------|------|----------|
| **VNC Auth** | DES challenge-response | 标准 VNC 服务器 |
| **ARD Auth** | Diffie-Hellman + AES-128-ECB | Apple Remote Desktop |

当检测到 ARD auth type 30 凭证请求时，系统自动启用 macOS 目标检测，并将 Meta 键映射为 Super 键以保持 Command 键兼容性。

资料来源：[README.md:195-210]()

## 通信协议 (PC Protocol)

### 协议格式

MCP Proxy 与 VNC Daemon 之间使用自定义的 PC (Procedure Call) 协议，通过 NDJSON (Newline Delimited JSON) 进行通信：

| 消息类型 | 格式 | 说明 |
|----------|------|------|
| 请求 | `{"method":"<name>","params":{...},"id":<int>}` | 工具调用请求 |
| 响应 | `{"result":{...},"id":<int>}` | 成功响应 |
| 错误 | `{"error":{"code":<int>,"message":"..."},"id":<int>}` | 错误响应 |
| 通知 | `{"method":"<name>","params":{...}}` | 单向通知 |

### 请求-响应示例

以截图操作为例：

**请求：**
```json
{"method":"screenshot","params":{},"id":1}
```

**响应：**
```json
{"result":{"format":"png","width":1280,"height":717,"data":"<base64>"},"id":1}
```

### 检测元素示例

**请求：**
```json
{"method":"detect_elements","params":{}}
```

**响应：**
```json
{
  "result": {
    "scaledWidth": 1280,
    "scaledHeight": 717,
    "elements": [
      {"text":"Finder","x":37,"y":6,"w":32,"h":9,"confidence":1},
      {"text":"File","x":84,"y":6,"w":15,"h":9,"confidence":1}
    ]
  },
  "id": 2
}
```

资料来源：[README.md:165-175]()

## 坐标系与缩放

### 缩放机制

VNC 服务器的原生分辨率会被缩放至 `--max-dimension` (默认 1280px) 以内。这种设计使得 Claude 可以在统一的坐标空间内工作，简化了操作逻辑：

```
原生分辨率:  4220 × 2568  (VNC 服务器帧缓冲区)
缩放分辨率:  1280 × 779   (Claude 可见空间)

mouse_click(640, 400) → VNC 服务器收到 (2110, 1284)
```

### 缩放参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `max_dimension` | 1280 | 最大边像素数 |

缩放操作在 Daemon 层透明处理，Proxy 层无需关心具体转换细节。

资料来源：[README.md:177-185]()

## 运行时配置

### 可配置参数

所有时序和显示参数可在运行时通过 `configure` 方法调整，无需重新连接：

| 参数类别 | 参数名 | 默认值 | 说明 |
|----------|--------|--------|------|
| 点击 | `click_hold_ms` | 50 | 点击保持时间 |
| 双击 | `double_click_gap_ms` | 50 | 双击间隔 |
| 悬停 | `hover_settle_ms` | 400 | 悬停后稳定时间 |
| 拖拽 | `drag_press_ms` | 50 | 拖拽按下时间 |
| 拖拽 | `drag_position_ms` | 30 | 拖拽位置采样 |
| 拖拽 | `drag_step_ms` | 5 | 拖拽步骤间隔 |
| 拖拽 | `drag_settle_ms` | 30 | 拖拽后稳定 |
| 拖拽 | `drag_pixels_per_step` | 20 | 每步像素数 |
| 拖拽 | `drag_min_steps` | 10 | 最小步数 |
| 滚动 | `scroll_press_ms` | 10 | 滚动按下时间 |
| 滚动 | `scroll_tick_ms` | 20 | 滚动刻度间隔 |
| 键盘 | `key_hold_ms` | 30 | 按键保持时间 |
| 键盘 | `combo_mod_ms` | 10 | 修饰键稳定时间 |
| 键盘 | `type_key_ms` | 20 | 键入按下时间 |
| 键盘 | `type_inter_key_ms` | 20 | 键入间隔 |
| 键盘 | `type_shift_ms` | 10 | Shift 稳定时间 |
| 剪贴板 | `paste_settle_ms` | 30 | 粘贴后稳定时间 |

### 配置操作示例

设置点击保持时间为 80ms：

```json
{"method":"configure","params":{"click_hold_ms":80}}
```

重置为默认值：

```json
{"method":"configure","params":{"reset":true}}
```

查询当前配置：

```json
{"method":"get_timing","params":{}}
```

资料来源：[README_TR.md:95-130]()

## 命令行参数

### Daemon 参数

| 参数 | 说明 |
|------|------|
| `--host <地址>` | VNC 服务器地址 |
| `--port <端口>` | VNC 服务器端口 |
| `--password <密码>` | VNC 密码 |
| `--username <用户名>` | ARD 用户名 |
| `--scale <缩放比>` | 缩放比例 |
| `--max-dimension <像素>` | 最大边像素数 |
| `--bit-depth <位数>` | 每像素位数 |
| `--no-reconnect` | 禁用自动重连 |
| `-v, --verbose` | 详细日志输出 |

### 环境变量

MCP Proxy 支持通过环境变量配置连接参数：

| 变量 | 说明 |
|------|------|
| `VNC_HOST` | VNC 服务器主机名或 IP |
| `VNC_PORT` | VNC 服务器端口 |
| `VNC_USERNAME` | VNC/ARD 用户名 |
| `VNC_PASSWORD` | VNC/ARD 密码 |
| `CLAUDE_KVM_DAEMON_PATH` | Daemon 可执行文件路径 |

资料来源：[server.json:25-60]()

## 已知限制

### VNC 连接稳定性

社区反馈表明，在长时间运行的测试会话（约 50 轮交互）后，VNC 连接可能会断开，Daemon 变得无响应。经 SSH 确认远程 Mac 仍可连接，问题定位在 VNC/ARD 服务器端而非 Daemon 或网络层。

相关 Issue：[#8 VNC connection drops during long-running test sessions](https://github.com/ARAS-Workspace/claude-kvm/issues/8)

### 平台限制

- 仅支持 Apple Silicon (aarch64) 架构
- Daemon 必须在 macOS 目标机器上运行
- OCR 功能依赖 Apple Vision Framework，仅在 Apple Silicon 上可用

资料来源：[LAUNCHGUIDE.md:25-30]()

## 组件交互流程

### 典型操作流程

以"截图 → 分析 → 执行 → 验证"模式为例：

```mermaid
graph LR
    A[截图] -->|screenshot| B[获取 PNG]
    B --> C{分析内容}
    C -->|find element| D[detect_elements]
    D -->|OCR 结果| E{定位坐标}
    E -->|mouse_click| F[执行点击]
    F -->|screenshot| G[验证结果]
    G -->|diff_check| H{检查变化}
    H -->|变化检测| A
```

### 批量操作

系统支持在单次工具调用中批量执行最多 20 个操作，适用于复杂的多步骤工作流：

```javascript
{
  "action_queue": [
    {"action": "mouse_click", "x": 100, "y": 200},
    {"action": "wait", "ms": 200},
    {"action": "key_type", "text": "hello"},
    {"action": "key_tap", "key": "enter"}
  ]
}
```

## 发布与分发

### 发布版本

当前最新版本：

| 组件 | 版本 | 发布日期 |
|------|------|----------|
| claude-kvm (npm) | 2.0.11 | - |
| claude-kvm-daemon | 1.0.1 | - |

### 分发方式

| 方式 | 说明 |
|------|------|
| npm | `npx -y claude-kvm` |
| Homebrew | `brew install claude-kvm-daemon` |

Daemon 通过 GitHub Actions 在 CI 环境中编译、签名和公证，产出 `.tar.gz` (Homebrew) 和 `.dmg` (公证) 两种格式。

资料来源：[README_TR.md:50-70]()

## 总结

Claude KVM 的系统架构遵循清晰的分层设计原则：

1. **MCP Proxy 层** — 作为 Claude 与底层系统之间的桥梁，处理协议转换和工具暴露
2. **PC 协议** — 使用 NDJSON 格式实现轻量级的进程间通信
3. **VNC Daemon 层** — 封装所有底层操作，包括 VNC 通信、输入注入和 OCR
4. **坐标抽象** — 通过缩放机制提供统一的操作空间
5. **运行时配置** — 支持动态调整时序参数，无需重启连接

这种架构设计使得系统兼具灵活性与性能，同时保持了良好的可维护性和扩展性。

---

<a id='mcp-proxy'></a>

## MCP 代理层

### 相关页面

相关主题：[系统架构](#architecture), [VNC 守护进程](#vnc-daemon), [工具参考手册](#tools-reference)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/index.js)
- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
</details>

# MCP 代理层

## 概述

MCP 代理层是 claude-kvm 项目的核心通信中枢，负责在 Claude AI 与底层原生 VNC 守护进程之间建立桥梁。该层采用 JavaScript/Node.js 实现，通过 Model Context Protocol (MCP) 与 Claude 进行交互，同时使用 PC (Procedure Call) 协议通过 NDJSON 格式与本地守护进程通信 资料来源：[index.js:1-30]()。

```mermaid
graph TD
    subgraph "MCP 代理层 (JavaScript/Node.js)"
        A["Claude AI"] <--> B["MCP Server<br/>(StdioServerTransport)"]
        B <--> C["Tool Handler<br/>(vnc_command)"]
        C <--> D["Daemon Manager<br/>(child_process spawn)"]
    end
    
    subgraph "PC 协议层 (NDJSON)"
        D <--> E["stdin/stdout"]
    end
    
    subgraph "原生守护进程 (Swift/C)"
        E <--> F["VNC Daemon<br/>(LibVNC)"]
        F <--> G["Remote Desktop<br/>(VNC/ARD Server)"]
    end
```

## 架构分层

MCP 代理层采用清晰的两层架构设计：

| 层级 | 编程语言 | 职责 | 通信方式 |
|------|----------|------|----------|
| **MCP 代理** | JavaScript (Node.js) | 与 Claude 通信，管理守护进程生命周期 | stdio JSON-RPC |
| **VNC 守护进程** | Swift/C (Apple Silicon) | VNC 连接、屏幕捕获、输入注入 | stdin/stdout NDJSON |

资料来源：[README.md:1-50]()

### MCP 代理职责

MCP 代理层承担以下核心职责：

1. **协议转换** — 将 MCP JSON-RPC 请求转换为 PC 协议格式
2. **进程管理** — 启动、监控和终止原生守护进程
3. **工具暴露** — 通过单一 `vnc_command` 工具向 Claude 暴露所有功能
4. **生命周期处理** — 响应 SIGINT 信号，执行优雅关闭

```javascript
// 核心代理启动流程
const transport = new StdioServerTransport();
await mcpServer.connect(transport);
log('MCP server connected on stdio');
```

资料来源：[index.js:80-85]()

## PC 协议

PC (Procedure Call) 协议是代理层与守护进程之间的通信协议，基于 NDJSON 格式：

### 消息格式

```
请求:      {"method":"<name>","params":{...},"id":<int|string>}
响应:      {"result":{...},"id":<int|string>}
错误:      {"error":{"code":<int>,"message":"..."},"id":<int|string>}
通知:      {"method":"<name>","params":{...}}
```

资料来源：[README.md:45-50]()

### 请求-响应流程

```mermaid
sequenceDiagram
    participant C as Claude AI
    participant P as MCP Proxy
    participant D as VNC Daemon
    
    C->>P: MCP JSON-RPC (vnc_command)
    P->>P: 转换为 PC 协议
    P->>D: NDJSON Request
    D->>D: 执行 VNC 操作
    D->>P: NDJSON Response
    P->>P: 转换为 MCP 格式
    P->>C: MCP JSON-RPC Response
```

## 工具定义

MCP 代理层通过 `vncCommandTool()` 函数生成完整的工具定义，该工具封装了所有 VNC 操作 资料来源：[tools/index.js:1-60]()：

### 工具名称与描述

| 属性 | 值 |
|------|-----|
| 工具名称 | `vnc_command` |
| 描述模板 | `Control a remote desktop via VNC. Display: ${width}×${height}px.` |

### 支持的动作类别

代理层将 VNC 操作分类为以下动作组：

| 类别 | 动作列表 |
|------|----------|
| **屏幕操作** | `screenshot`, `cursor_crop`, `diff_check`, `set_baseline` |
| **鼠标操作** | `mouse_click`, `mouse_double_click`, `mouse_move`, `hover`, `nudge`, `mouse_drag`, `scroll` |
| **键盘操作** | `key_tap`, `key_combo`, `key_type`, `paste` |
| **元素检测** | `detect_elements` |
| **配置管理** | `configure`, `get_timing` |
| **系统控制** | `wait`, `health`, `shutdown` |

资料来源：[tools/index.js:10-35]()

### 输入 Schema

代理层使用 Zod 进行严格的输入验证：

```javascript
inputSchema: {
  action: z.enum([...]).describe('The action to perform'),
  x: z.number().int().min(0).max(width - 1).optional(),
  y: z.number().int().min(0).max(height - 1).optional(),
  toX: z.number().int().min(0)...
}
```

资料来源：[tools/index.js:55-75]()

## 配置管理

### 环境变量

MCP 代理层通过环境变量进行配置：

| 变量名 | 必需 | 说明 |
|--------|------|------|
| `VNC_HOST` | 是 | VNC 服务器主机名或 IP 地址 |
| `VNC_PORT` | 是 | VNC 服务器端口号 |
| `VNC_USERNAME` | 否 | VNC/ARD 用户名 |
| `VNC_PASSWORD` | 否 | VNC/ARD 密码 |
| `CLAUDE_KVM_DAEMON_PATH` | 否 | 守护进程可执行文件路径 |

资料来源：[server.json:20-35]()

### 配置读取实现

```javascript
const env = (key, fallback) => process.env[key] || fallback;

const config = {
  host: env('VNC_HOST', 'localhost'),
  port: parseInt(env('VNC_PORT', '5900')),
  username: env('VNC_USERNAME', ''),
  password: env('VNC_PASSWORD', ''),
  daemonPath: env('CLAUDE_KVM_DAEMON_PATH', 'claude-kvm-daemon'),
};
```

资料来源：[index.js:45-55]()

## 守护进程管理

### 进程启动

代理层通过 `child_process.spawn()` 启动原生守护进程：

```javascript
const daemon = spawn(config.daemonPath, ['--pc'], {
  stdio: ['pipe', 'pipe', 'pipe'],
});
```

参数说明：
- `--pc` 标志指示守护进程使用 PC 协议模式
- `stdio: ['pipe', 'pipe', 'pipe']` 建立完整的输入输出管道

### 生命周期管理

```mermaid
graph LR
    A[启动] --> B[守护进程运行中]
    B --> C[SIGINT 信号]
    C --> D{daemon 存在?}
    D -->|是| E[发送 shutdown 命令]
    E --> F[500ms 后强制终止]
    D -->|否| G[直接退出]
    F --> H[进程退出]
    G --> H
```

代理层实现优雅关闭机制：

```javascript
process.on('SIGINT', () => {
  log('Shutting down...');
  if (daemon) {
    daemon.stdin.write(JSON.stringify({ method: 'shutdown' }) + '\n');
    setTimeout(() => { daemon?.kill(); process.exit(0); }, 500);
  } else {
    process.exit(0);
  }
});
```

资料来源：[index.js:86-96]()

## 错误处理

### MCP 层错误处理

代理层为每个工具调用实现了统一的错误处理：

```javascript
return { content: [{ type: 'text', text: input.reason }], isError: true };
```

### 致命错误处理

```javascript
main().catch((err) => {
  log(`Fatal: ${err.message}`);
  process.exit(1);
});
```

## 依赖项

### 运行时依赖

| 包名 | 版本 | 用途 |
|------|------|------|
| `@modelcontextprotocol/sdk` | ^1.26.0 | MCP 协议实现 |
| `zod` | ^4.3.6 | 输入验证 |

资料来源：[package.json:20-30]()

### 开发依赖

| 包名 | 版本 | 用途 |
|------|------|------|
| `@anthropic-ai/sdk` | ^0.52.0 | Claude API 调用 |
| `@types/node` | ^25.2.3 | TypeScript 类型支持 |
| `dotenv` | ^17.3.1 | 环境变量管理 |

## 坐标系统

代理层与守护进程协同处理坐标缩放：

```
原生分辨率:  4220 × 2568  (VNC 服务器帧缓冲)
缩放分辨率:  1280 × 779   (Claude 可见和操作的坐标空间)

mouse_click(640, 400) → 守护进程转换 → VNC 接收 (2110, 1284)
```

缩放因子通过 `--max-dimension` 参数配置（默认 1280px） 资料来源：[README.md:55-65]()。

## 认证机制

代理层支持两种 VNC 认证方式：

| 认证方式 | 算法 | 说明 |
|----------|------|------|
| **VNC Auth** | 密码挑战-响应 (DES) | 标准 VNC 协议认证 |
| **ARD Auth** | Diffie-Hellman + AES-128-ECB | Apple Remote Desktop 认证 |

macOS 目标通过 ARD auth type 30 凭证请求自动检测，检测到后 Meta 键自动映射为 Super 键以确保 Command 键兼容性 资料来源：[README.md:100-110]()。

## 相关社区问题

### 长时间运行会话中的 VNC 连接断开

社区反馈 Issue #8 报告了长时间测试会话（约 50 轮）后 VNC 连接断开且守护进程无响应的问题。经调查，SSH 连接仍保持活跃，确认问题发生在 VNC/ARD 服务器端，而非代理层或网络层。

此问题可能与 MCP 代理层的连接保活机制无关，但用户可通过以下方式缓解：
- 定期调用 `health` 操作检查连接状态
- 在长时间任务中设置检查点
- 使用 `configure` 调整 `hover_settle_ms` 等时间参数以优化稳定性

详见：[Issue #8](https://github.com/ARAS-Workspace/claude-kvm/issues/8)

---

<a id='vnc-daemon'></a>

## VNC 守护进程

### 相关页面

相关主题：[系统架构](#architecture), [MCP 代理层](#mcp-proxy), [认证机制](#authentication)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
- [server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)
- [index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/index.js)
- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [LAUNCHGUIDE.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/LAUNCHGUIDE.md)
</details>

# VNC 守护进程

## 概述

VNC 守护进程（`claude-kvm-daemon`）是 claude-kvm 项目架构中的核心本地组件，采用 Swift/C 语言编写，专门针对 Apple Silicon 平台优化。该守护进程负责与 VNC 服务器建立连接、处理屏幕捕获、注入鼠标与键盘输入，并利用 Apple Vision 框架执行本地 OCR 文字检测。 资料来源：[LAUNCHGUIDE.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/LAUNCHGUIDE.md)

守护进程通过标准输入/输出与 Node.js MCP 代理层通信，使用 NDJSON 格式的 PC（Procedure Call）协议交换命令和响应，实现了高效的双工通信机制。 资料来源：[README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)

## 架构设计

### 系统分层

claude-kvm 采用三层架构设计，VNC 守护进程位于中间层：

| 层级 | 语言 | 职责 | 通信方式 |
|------|------|------|----------|
| **MCP 代理** | JavaScript (Node.js) | 与 Claude 通过 MCP 协议通信，管理守护进程生命周期 | stdio JSON-RPC |
| **VNC 守护进程** | Swift/C (Apple Silicon) | VNC 连接、屏幕捕获、鼠标/键盘输入注入 | stdin/stdout NDJSON |
| **目标机器** | - | VNC 服务器 (RFB 协议) | TCP :5900 |

资料来源：[README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)

### 组件架构图

```mermaid
graph TD
    subgraph Proxy["MCP 代理层"]
        Server["Server<br/>MCP Protocol"]
        Tools["Tools Proxy"]
    end

    subgraph Daemon["VNC 守护进程"]
        CMD["CMD<br/>PC Protocol Parser"]
        Scale["Scale<br/>Coordinate Transform"]
        VNC["VNC Bridge<br/>LibVNCClient 0.9.15"]
        Capture["Capture<br/>Screen Buffer"]
        Mouse["Mouse<br/>Pointer Events"]
        KB["KB<br/>Keyboard Events"]
    end

    subgraph Target["目标机器"]
        VNC_Server["VNC Server<br/>:5900"]
        Desktop["Desktop Environment"]
    end

    AI <-->|"stdio<br/>JSON-RPC"| Server
    Server <-->|"stdin/stdout<br/>PC (NDJSON)"| CMD
    CMD --> Scale
    Scale --> Capture
    Scale --> Mouse
    Scale --> KB
    Capture -.->|"framebuffer"| VNC
    Mouse -->|"pointer events"| VNC
    KB -->|"key events"| VNC
    VNC <-->|"RFB Protocol<br/>TCP :5900"| VNC_Server
    VNC_Server --> Desktop
```

### 守护进程子组件

| 组件 | 功能描述 |
|------|----------|
| **CMD** | PC 协议解析器，解析来自代理层的请求并路由到相应处理模块 |
| **Scale** | 坐标缩放模块，负责原生分辨率与缩放分辨率之间的坐标转换 |
| **VNC Bridge** | LibVNCClient 封装层，处理 RFB 协议通信 |
| **Capture** | 屏幕缓冲区管理，负责帧缓冲区数据提取 |
| **Mouse** | 鼠标事件生成，处理点击、移动、拖拽、滚动 |
| **KB** | 键盘事件生成，处理按键、组合键、文本输入 |

资料来源：[README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)

## PC 通信协议

### 协议格式

守护进程与代理层之间使用 PC（Procedure Call）协议，通过 NDJSON 格式进行通信：

```
请求:      {"method":"<name>","params":{...},"id":<int|string>}
响应:      {"result":{...},"id":<int|string>}
错误:      {"error":{"code":<int>,"message":"..."},"id":<int|string>}
通知:      {"method":"<name>","params":{...}}
```

资料来源：[README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)

### 支持的方法

守护进程暴露以下核心方法供代理层调用：

| 方法 | 描述 | 参数 |
|------|------|------|
| `screenshot` | 获取全屏 PNG 图像 | - |
| `cursor_crop` | 获取光标周围的裁剪图像 | - |
| `diff_check` | 检测自基准以来的屏幕变化 | - |
| `set_baseline` | 设置 diff 基准图像 | - |
| `mouse_click` | 鼠标点击 | `x, y, button?` |
| `mouse_double_click` | 鼠标双击 | `x, y` |
| `mouse_move` | 移动光标 | `x, y` |
| `hover` | 移动并等待稳定 | `x, y` |
| `nudge` | 相对移动 | `dx, dy` |
| `mouse_drag` | 拖拽操作 | `x, y, toX, toY` |
| `scroll` | 滚动 | `x, y, direction, amount?` |
| `key_tap` | 单键按下 | `key` |
| `key_combo` | 组合键 | `key` 或 `keys:[...]` |
| `key_type` | 逐字符输入文本 | `text` |
| `paste` | 剪贴板粘贴 | `text` |
| `detect_elements` | OCR 文字检测 | - |
| `configure` | 运行时配置 | `params` |
| `get_timing` | 获取当前参数 | - |
| `wait` | 等待 | `ms?` |
| `health` | 健康检查 | - |
| `shutdown` | 优雅退出 | - |

资料来源：[tools/index.js:19-35](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)

## 核心功能详解

### 屏幕捕获

守护进程通过 LibVNCClient 与 VNC 服务器通信，获取远程桌面的帧缓冲区数据。捕获的图像支持两种分辨率：

- **原生分辨率**：VNC 服务器的原始帧缓冲区大小
- **缩放分辨率**：根据 `--max-dimension` 参数自动缩放后的显示尺寸

典型工作流程：

```mermaid
graph LR
    A["VNC Server<br/>帧缓冲区"] --> B["LibVNCClient<br/>RFB 协议"]
    B --> C["Capture 模块<br/>数据缓冲"]
    C --> D["坐标 Scale 模块"]
    D --> E["缩放图像<br/>1280px 最大"]
```

### 坐标缩放

VNC 服务器的原生分辨率会被自动缩放至适合显示的大小（默认最大 1280px），Claude 在缩放空间中进行操作，守护进程负责坐标的双向转换：

```
原生分辨率:  4220 × 2568  (VNC 服务器帧缓冲区)
缩放分辨率:  1280 × 779   (Claude 可见和操作的空间)

示例转换:
mouse_click(640, 400) → VNC 接收 (2110, 1284)
```

资料来源：[README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)

### 输入注入

#### 鼠标操作

守护进程支持多种鼠标操作类型：

| 操作 | 参数 | 说明 |
|------|------|------|
| `mouse_click` | x, y, button? | 单击，默认左键 |
| `mouse_double_click` | x, y | 双击 |
| `mouse_move` | x, y | 移动光标 |
| `hover` | x, y | 移动后等待稳定 |
| `nudge` | dx, dy | 相对移动 |
| `mouse_drag` | x, y, toX, toY | 拖拽 |
| `scroll` | x, y, direction, amount? | 滚动 |

#### 键盘操作

| 操作 | 参数 | 说明 |
|------|------|------|
| `key_tap` | key | 单键按下（如 enter, escape, tab） |
| `key_combo` | key 或 keys[] | 组合键（如 "cmd+c"） |
| `key_type` | text | 逐字符输入 |
| `paste` | text | 剪贴板粘贴 |

### Apple Vision OCR

守护进程集成 Apple Vision 框架进行本地文字识别，无需外部 API：

```json
{
  "elements": [
    {"x":19,"y":6,"w":19,"h":9,"text":"Edit","confidence":1},
    {"x":143,"y":6,"w":22,"h":11,"text":"View","confidence":1},
    {"x":322,"y":477,"w":633,"h":93,"text":"PHANTOM","confidence":1}
  ],
  "scaledHeight":717,
  "scaledWidth":1280
}
```

返回结果包含文字边界框坐标、识别文本及置信度评分。 资料来源：[README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)

## 安装与配置

### 安装方式

VNC 守护进程通过 Homebrew 安装：

```bash
brew install ARAS-Workspace/tap/claude-kvm-daemon
```

安装后可通过以下命令验证：

```bash
claude-kvm-daemon --version
```

资料来源：[LAUNCHGUIDE.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/LAUNCHGUIDE.md)

### 命令行参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--max-dimension` | `1280` | 屏幕缩放最大尺寸（像素） |
| `--connect-timeout` | - | VNC 连接超时时间（秒） |
| `--bits-per-sample` | - | 像素位深度 |
| `--no-reconnect` | - | 禁用自动重连 |
| `-v, --verbose` | - | 启用详细日志输出 |

资料来源：[LAUNCHGUIDE.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/LAUNCHGUIDE.md)

### 环境变量配置

| 环境变量 | 必需 | 说明 |
|----------|------|------|
| `VNC_HOST` | 是 | VNC 服务器主机名或 IP |
| `VNC_PORT` | 是 | VNC 端口号（默认 5900） |
| `VNC_USERNAME` | 否 | ARD 认证用户名 |
| `VNC_PASSWORD` | 否 | VNC/ARD 密码 |
| `CLAUDE_KVM_DAEMON_PATH` | 是 | 守护进程二进制路径 |
| `CLAUDE_KVM_DAEMON_PARAMETERS` | 否 | 额外命令行参数 |

资料来源：[server.json:25-46](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)

### MCP 配置

在项目目录创建 `.mcp.json` 文件：

```json
{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass",
        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon",
        "CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"
      }
    }
  }
}
```

资料来源：[LAUNCHGUIDE.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/LAUNCHGUIDE.md)

## 已知问题

### VNC 连接在长时间测试中断开

**Issue #8**: VNC connection drops during long-running test sessions

**问题描述**：在长时间测试会话（约 50 轮交互）期间，VNC 连接会断开，守护进程变得无响应。SSH 连接到远程 Mac 保持正常，表明问题位于 VNC/ARD 服务器端，而非守护进程或网络层。

**影响范围**：长时间运行的自动化测试会话

**状态**：社区已知问题，正在调查 VNC 服务器端的连接稳定性

**临时解决方案**：

- 减少单次会话的交互轮数
- 在 VNC 服务器端启用连接保活机制
- 使用 SSH 隧道转发 VNC 连接以提高稳定性

资料来源：[GitHub Issue #8](https://github.com/ARAS-Workspace/claude-kvm/issues/8)

## 版本历史

| 版本 | 发布日期 | 主要变更 |
|------|----------|----------|
| **1.0.1** | 2026 | 最新稳定版本 |
| **1.0.0** | 2026 | 初始稳定版本 |

资料来源：[GitHub Releases](https://github.com/ARAS-Workspace/claude-kvm/releases)

## 技术栈

| 组件 | 技术选型 | 说明 |
|------|----------|------|
| **VNC 客户端库** | LibVNCClient 0.9.15 | RFB 协议实现 |
| **编程语言** | Swift / C | Apple Silicon 原生优化 |
| **OCR 引擎** | Apple Vision | 本地文字识别 |
| **构建系统** | - | 静态链接 LibVNC |
| **签名** | Apple notarization | macOS Gatekeeper 兼容 |

资料来源：[README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)

## 工作流程示例

守护进程的典型使用场景：

```mermaid
sequenceDiagram
    participant AI as Claude (AI)
    participant Proxy as MCP 代理
    participant Daemon as VNC 守护进程
    participant VNC as VNC 服务器

    AI->>Proxy: detect_elements
    Proxy->>Daemon: PC Request: {"method":"detect_elements"}
    Daemon->>VNC: rfbGetFramebuffer
    VNC-->>Daemon: 帧缓冲区数据
    Daemon->>Daemon: Apple Vision OCR
    Daemon-->>Proxy: PC Response: {"elements":[...]}
    Proxy-->>AI: 识别结果

    Note over AI,Daemon: 交互式操作流程

    AI->>Proxy: mouse_click + key_type
    Proxy->>Daemon: PC Request: {"method":"action_queue","actions":[...]}
    Daemon->>VNC: pointer events + key events
    VNC-->>Daemon: 状态更新
    Daemon-->>Proxy: PC Response
    Proxy-->>AI: 操作完成确认
```

## 相关资源

- **源码仓库**: [ARAS-Workspace/claude-kvm](https://github.com/ARAS-Workspace/claude-kvm)
- **Homebrew Tap**: [homebrew-tap](https://github.com/ARAS-Workspace/homebrew-tap)
- **问题反馈**: [GitHub Issues](https://github.com/ARAS-Workspace/claude-kvm/issues)
- **Mac M1 配置技巧**: [VNC 加固与 SSH 隧道指南](https://gist.github.com/remrearas/a3f300635b02f2587a134882a51f7114)

---

<a id='tools-reference'></a>

## 工具参考手册

### 相关页面

相关主题：[系统架构](#architecture), [配置参数详解](#configuration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- [README_TR.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README_TR.md)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
- [server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)
- [index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/index.js)
</details>

# 工具参考手册

本页面详细说明 `claude-kvm` 项目提供的所有远程桌面控制工具。工具通过 MCP (Model Context Protocol) 协议与 Claude 通信，由原生 Swift 编写的 VNC 守护进程执行实际控制操作。

## 架构概览

`claude-kvm` 采用双层架构设计：

```mermaid
graph TD
    A[Claude Desktop] <--> B[MCP Proxy<br/>Node.js]
    B <--> C[VNC Daemon<br/>Swift + LibVNC]
    C <--> D[VNC Server<br/>macOS 远程桌面]
    
    B -->|stdio JSON-RPC| A
    C -->|NDJSON PC Protocol| B
    C -->|VNC RFB| D
```

| 层级 | 语言 | 职责 | 通信方式 |
|------|------|------|----------|
| **MCP Proxy** | JavaScript (Node.js) | 与 Claude 通信，管理守护进程生命周期 | stdio JSON-RPC |
| **VNC Daemon** | Swift/C (Apple Silicon) | VNC 连接、屏幕捕获、输入注入 | stdin/stdout NDJSON |

资料来源：[README.md:55-65]()

## vnc_command 工具概述

`vnc_command` 是唯一的主工具，提供完整的远程桌面控制能力：

```javascript
export function vncCommandTool(width, height) {
  return {
    name: 'vnc_command',
    description: [
      `Control a remote desktop via VNC. Display: ${width}×${height}px.`,
      'All coordinates are in this scaled space.',
      // ...
    ],
    inputSchema: {
      action: z.enum([...]),
      x: z.number().int().min(0).max(width - 1).optional(),
      y: z.number().int().min(0).max(height - 1).optional(),
      // ...
    }
  }
}
```

资料来源：[tools/index.js:35-70]()

### 工具调用模式

建议使用 **screenshot → analyze → act → verify** 模式进行操作：

```
截图获取画面 → 分析识别元素 → 执行操作 → 验证结果
```

## 屏幕操作

| Action | 参数 | 说明 |
|--------|------|------|
| `screenshot` | 无 | 获取全屏 PNG 图像 |
| `cursor_crop` | 无 | 在光标位置裁剪带十字线的区域 |
| `diff_check` | 无 | 检测自 baseline 以来的屏幕变化 |
| `set_baseline` | 无 | 将当前屏幕设为 diff 参考 |

### screenshot

获取完整的远程桌面截图，返回 Base64 编码的 PNG 数据。

```json
{"action": "screenshot"}
```

```json
{"result": {"base64": "iVBORw0KGgoAAAANS..."}}
```

### cursor_crop

在鼠标光标位置裁剪图像，便于精确定位当前操作区域。裁剪半径可在配置中调整（默认 150px）。

```json
{"action": "cursor_crop"}
```

```json
{"result": {"base64": "...", "cursor": {"x": 640, "y": 400}}}
```

### diff_check

与 `set_baseline` 设置的参考画面进行对比，返回变化的区域。适用于检测操作效果或等待加载完成。

```json
{"action": "diff_check"}
```

```json
{"result": {"changed": true, "changedRegion": {"x": 100, "y": 200, "w": 50, "h": 30}}}
```

## 鼠标操作

| Action | 参数 | 说明 |
|--------|------|------|
| `mouse_click` | `x, y, button?` | 单击（left/right/middle） |
| `mouse_double_click` | `x, y` | 双击 |
| `mouse_move` | `x, y` | 移动光标 |
| `hover` | `x, y` | 移动后等待悬停稳定 |
| `nudge` | `dx, dy` | 相对位移 |
| `mouse_drag` | `x, y, toX, toY` | 从起点拖拽到终点 |
| `scroll` | `direction, amount?` | 滚动（up/down/left/right） |

### 坐标系统

所有坐标在**缩放空间**中指定。VNC 服务器原生分辨率自动缩放至 `--max-dimension`（默认 1280px）：

```
原生分辨率:  4220 × 2568 (VNC 服务器帧缓冲)
缩放分辨率:  1280 × 779  (Claude 操作的坐标空间)

mouse_click(640, 400) → VNC 接收 (2110, 1284)
```

资料来源：[README.md:70-75]()

### mouse_click

```json
{"action": "mouse_click", "x": 640, "y": 400}
```

可选参数 `button` 支持 `left`（默认）、`right`、`middle`。

### mouse_drag

执行平滑的拖拽操作，中间经过多个插值点：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `drag_position_ms` | 30 | 拖拽前位置确认等待 |
| `drag_press_ms` | 50 | 按下持续时间 |
| `drag_step_ms` | 5 | 插值点之间间隔 |
| `drag_settle_ms` | 30 | 释放后稳定时间 |
| `drag_pixels_per_step` | 20 | 每步像素密度 |
| `drag_min_steps` | 10 | 最小插值步数 |

```json
{"action": "mouse_drag", "x": 100, "y": 200, "toX": 500, "toY": 400}
```

### scroll

```json
{"action": "scroll", "direction": "down", "amount": 3}
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `scroll_press_ms` | 10 | 按下持续时间 |
| `scroll_tick_ms` | 20 | 每次 tick 间隔 |

## 键盘操作

| Action | 参数 | 说明 |
|--------|------|------|
| `key_tap` | `key` | 单键按下（enter/escape/tab/space 等） |
| `key_combo` | `keys` | 组合键（"cmd+c" 或 ["cmd","shift","3"]） |
| `key_type` | `text` | 逐字符输入文本 |
| `paste` | `text` | 通过剪贴板粘贴 |

### key_tap

支持的特殊键包括：`enter`、`escape`、`tab`、`space`、`delete`、`backspace`、`up`、`down`、`left`、`right` 等。

```json
{"action": "key_tap", "key": "enter"}
```

### key_combo

修饰符组合键示例：

```json
{"action": "key_combo", "keys": "cmd+c"}
```

或数组格式：

```json
{"action": "key_combo", "keys": ["cmd", "shift", "3"]}
```

### key_type

逐字符输入文本，包含内置延迟以模拟真实打字：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `key_hold_ms` | 30 | 按键保持时间 |
| `type_inter_key_ms` | 20 | 字符间延迟 |
| `type_shift_ms` | 10 | Shift 修饰符稳定时间 |

```json
{"action": "key_type", "text": "Hello, World!"}
```

### paste

通过剪贴板粘贴，适用于长文本输入：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `paste_settle_ms` | 30 | 粘贴后稳定时间 |

```json
{"action": "paste", "text": "这是一段很长的文本内容"}
```

## 元素检测

| Action | 参数 | 说明 |
|--------|------|------|
| `detect_elements` | 无 | OCR 文本检测，返回边界框 |

### detect_elements

使用 Apple Vision 框架进行设备端 OCR，无需 API 调用，响应时间约 50ms。返回所有检测到的文本元素及其边界框坐标（缩放空间）。

```json
{"action": "detect_elements"}
```

**响应示例：**

```json
{
  "result": {
    "detail": "13 elements",
    "elements": [
      {"confidence": 1, "h": 9, "text": "Finder", "w": 32, "x": 37, "y": 6},
      {"confidence": 1, "h": 9, "text": "File", "w": 15, "x": 84, "y": 6},
      {"confidence": 1, "h": 93, "text": "PHANTOM", "w": 633, "x": 322, "y": 477}
    ],
    "scaledHeight": 717,
    "scaledWidth": 1280
  }
}
```

**返回字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `text` | string | 检测到的文本内容 |
| `x, y` | number | 边界框左上角坐标 |
| `w, h` | number | 边界框宽高 |
| `confidence` | number | 置信度 (0-1) |

资料来源：[README.md:88-105]()

## 配置管理

| Action | 参数 | 说明 |
|--------|------|------|
| `configure` | `{<params>}` | 运行时设置参数 |
| `configure` | `{reset: true}` | 重置所有参数为默认值 |
| `get_timing` | 无 | 获取当前所有参数 |

### configure

在运行时调整时序和显示参数，无需断开重连：

```json
{"action": "configure", "params": {"click_hold_ms": 80, "key_hold_ms": 50}}
```

```json
{"result": {"detail": "OK — changed: click_hold_ms, key_hold_ms"}}
```

### 完整配置参数表

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `max_dimension` | 1280 | 最大显示尺寸 |
| `cursor_crop_radius` | 150 | 光标裁剪半径 (px) |
| `click_hold_ms` | 50 | 单击按下持续时间 |
| `double_click_gap_ms` | 50 | 双击间隔 |
| `hover_settle_ms` | 400 | 悬停稳定等待 |
| `drag_position_ms` | 30 | 拖拽前位置确认 |
| `drag_press_ms` | 50 | 拖拽按下持续 |
| `drag_step_ms` | 5 | 插值步间隔 |
| `drag_settle_ms` | 30 | 拖拽释放后稳定 |
| `drag_pixels_per_step` | 20 | 拖拽像素密度 |
| `drag_min_steps` | 10 | 最小插值步数 |
| `scroll_press_ms` | 10 | 滚动按下持续 |
| `scroll_tick_ms` | 20 | 滚动 tick 间隔 |
| `key_hold_ms` | 30 | 按键保持时间 |
| `combo_mod_ms` | 10 | 修饰符稳定时间 |
| `type_key_ms` | 20 | 打字按键持续 |
| `type_inter_key_ms` | 20 | 打字字符间隔 |
| `type_shift_ms` | 10 | Shift 修饰符延迟 |
| `paste_settle_ms` | 30 | 粘贴后稳定 |

资料来源：[README.md:180-200]()

### 重置为默认值

```json
{"action": "configure", "params": {"reset": true}}
```

```json
{"result": {"detail": "OK — reset to defaults", "timing": {...}, "scaledWidth": 1280, "scaledHeight": 779}}
```

## 系统控制

| Action | 参数 | 说明 |
|--------|------|------|
| `wait` | `ms?` | 暂停等待（默认 500ms） |
| `health` | 无 | 连接状态和显示信息 |
| `shutdown` | 无 | 优雅关闭守护进程 |

### health

检查 VNC 连接状态和显示信息：

```json
{"action": "health"}
```

```json
{
  "result": {
    "connected": true,
    "display": {
      "width": 1280,
      "height": 779,
      "scaledWidth": 1280,
      "scaledHeight": 779
    }
  }
}
```

### shutdown

优雅地关闭守护进程，完成当前请求后退出：

```json
{"action": "shutdown"}
```

## 操作队列

虽然 `vnc_command` 是主工具，但可以通过批量操作提高效率。单个请求可包含最多 20 个顺序操作：

```javascript
export const actionQueueTool = (maxActions = 20) => ({
  name: 'action_queue',
  description: `Batch up to ${maxActions} sequential actions...`
});
```

资料来源：[tools/index.js:1-30]()

## 认证方式

项目支持两种 VNC 认证方法：

| 认证方式 | 说明 |
|----------|------|
| **VNC Auth** | 基于 DES 的密码挑战-响应认证 |
| **ARD** | Apple Remote Desktop (DH 密钥交换 + AES-128-ECB) |

macOS 目标通过 ARD 认证类型 30 自动检测，Meta 键自动映射为 Super 以兼容 Command 键。

资料来源：[README.md:107-115]()

## 已知问题

### VNC 连接在长时间测试中断开

**问题来源：** GitHub Issue #8

在长时间测试会话（约 50 轮）后，VNC 连接会断开，守护进程无响应。SSH 到远程 Mac 仍保持活跃，确认问题在 VNC/ARD 服务器端，而非守护进程或网络层。

**社区状态：** 0 reactions, 2 comments

这是 VNC 服务器端的限制，与 `claude-kvm` 项目本身无直接关联。参见 [Mac M1 Preparation Tricks](https://gist.github.com/remrearas/a3f300635b02f2587a134882a51f7114) 获取 VNC 安全和会话稳定性建议。

资料来源：[community_context](#top-community-issues)

## 完整操作索引

| 分类 | Action | 必需参数 | 可选参数 |
|------|--------|----------|----------|
| 屏幕 | `screenshot` | - | - |
| 屏幕 | `cursor_crop` | - | - |
| 屏幕 | `diff_check` | - | - |
| 屏幕 | `set_baseline` | - | - |
| 鼠标 | `mouse_click` | x, y | button |
| 鼠标 | `mouse_double_click` | x, y | - |
| 鼠标 | `mouse_move` | x, y | - |
| 鼠标 | `hover` | x, y | - |
| 鼠标 | `nudge` | dx, dy | - |
| 鼠标 | `mouse_drag` | x, y, toX, toY | - |
| 鼠标 | `scroll` | direction | amount |
| 键盘 | `key_tap` | key | - |
| 键盘 | `key_combo` | keys | - |
| 键盘 | `key_type` | text | - |
| 键盘 | `paste` | text | - |
| 检测 | `detect_elements` | - | - |
| 配置 | `configure` | params | - |
| 配置 | `get_timing` | - | - |
| 控制 | `wait` | - | ms |
| 控制 | `health` | - | - |
| 控制 | `shutdown` | - | - |

## 相关链接

- **最新守护进程版本：** [daemon-v1.0.1](https://github.com/ARAS-Workspace/claude-kvm/releases/tag/daemon-v1.0.1)
- **安装指南：** 参见 [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- **持续集成测试：** [GitHub Actions](https://github.com/ARAS-Workspace/claude-kvm/actions)

---

<a id='authentication'></a>

## 认证机制

### 相关页面

相关主题：[VNC 守护进程](#vnc-daemon), [配置参数详解](#configuration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- [index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/index.js)
- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
- [server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)
- [README_TR.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README_TR.md)
</details>

# 认证机制

## 概述

Claude KVM 的认证机制负责在 MCP 代理（JavaScript/Node.js）与 VNC 目标服务器之间建立安全连接。该系统支持两种主流 VNC 认证协议：标准 VNC 口令认证和 Apple Remote Desktop (ARD) 专有认证。认证过程在 daemon 启动时自动协商完成，无需用户手动指定认证类型。

资料来源：[README.md:认证机制部分]()

## 支持的认证方法

### VNC Auth（标准口令认证）

VNC Auth 是 RFB 协议中最广泛使用的认证方式，采用基于 DES 的 Challenge-Response 机制：

| 属性 | 值 |
|------|-----|
| 协议 | RFB (Remote Framebuffer) |
| 加密方式 | DES 块密码 |
| 凭证 | VNC_PASSWORD |
| 安全性 | 中等（易受暴力破解） |

认证流程：
1. 客户端发送认证请求
2. 服务器生成 16 字节随机 Challenge
3. 客户端使用口令 DES 加密 Challenge
4. 服务器验证响应

资料来源：[README.md:Authentication部分]()

### ARD Auth（Apple Remote Desktop）

ARD 是 macOS 原生的远程桌面协议，使用更安全的密钥交换和加密：

| 属性 | 值 |
|------|-----|
| 协议 | ARD Type 30 |
| 密钥交换 | Diffie-Hellman |
| 加密方式 | AES-128-ECB |
| 凭证 | VNC_USERNAME + VNC_PASSWORD |
| 平台 | macOS 专有 |

资料来源：[README_TR.md:Kimlik Doğrulama部分]()

## 认证检测与自动协商

系统通过 RFB 协议握手阶段的认证类型标识自动检测目标服务器类型：

```mermaid
graph TD
    A[连接 VNC 服务器] --> B[RFB Handshake]
    B --> C{读取 Auth Type}
    C -->|Type 2| D[VNC Auth 检测]
    C -->|Type 30| E[ARD Auth 检测]
    D --> F[使用口令 DES 加密]
    E --> G[使用 DH + AES 加密]
    F --> H[认证成功]
    G --> H
    H --> I[建立 VNC 会话]
```

### macOS 自动识别

当检测到 ARD Auth Type 30 凭证请求时，系统自动判定目标为 macOS 设备。此时会执行 Meta 键（Command 键）到 Super 键的自动映射，确保 macOS 快捷键语义正确传递给 Claude。

资料来源：[README.md:Authentication部分]()

## 环境变量配置

认证凭证通过环境变量传递给 MCP 代理：

| 变量名 | 必需 | 说明 | 示例 |
|--------|------|------|------|
| VNC_HOST | 是 | VNC 服务器主机名或 IP | `192.168.1.100` |
| VNC_PORT | 是 | VNC 服务器端口 | `5900` |
| VNC_USERNAME | 否 | ARD 用户名（仅 ARD 认证需要） | `admin` |
| VNC_PASSWORD | 是 | VNC/ARD 密码 | `secretpass` |

### MCP Server 配置示例

```json
{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass"
      }
    }
  }
}
```

资料来源：[server.json:环境变量部分]()

## 认证流程架构

### 组件交互

```
┌─────────────┐     MCP stdio      ┌─────────────┐   PC Protocol   ┌─────────────┐
│   Claude    │◄──────────────────►│  MCP Proxy  │◄───────────────►│  Daemon     │
│   Desktop   │                    │  (index.js) │                 │ (Swift/C)   │
└─────────────┘                    └─────────────┘                 └──────┬──────┘
                                                                          │
                                                                          ▼
                                                                 ┌─────────────┐
                                                                 │ VNC Server  │
                                                                 │ (macOS)     │
                                                                 └─────────────┘
```

### PC 协议认证消息

Daemon 与 Proxy 之间的认证状态通过 NDJSON 协议通信：

```json
// 连接请求（隐含认证）
{"method":"screenshot","params":{},"id":1}

// 认证成功响应
{"result":{"detail":"Connected","scaledWidth":1280,"scaledHeight":717},"id":1}

// 认证失败响应
{"error":{"code":1,"message":"Authentication failed"},"id":1}
```

资料来源：[index.js:Daemon 通信部分]()

## 安全考量

### 传输安全

| 方面 | 说明 |
|------|------|
| 本地通信 | MCP Proxy 与 Daemon 通过 stdio 管道通信，进程隔离 |
| 远程通信 | VNC 流量建议通过 SSH 隧道传输，避免明文口令暴露 |
| 口令存储 | 环境变量方式避免硬编码，CI/CD 场景建议使用 secrets |

### 已知限制

根据社区反馈（Issue #8），长时间运行的测试会话（~50 轮）可能导致 VNC 连接断开。SSH 连接保持活跃表明问题位于 VNC/ARD 服务器端，与认证机制本身无直接关联。

> **问题**：扩展测试会话期间 VNC 连接断开，daemon 无响应。SSH 远程 Mac 连接保持活跃，确认问题在 VNC/ARD 服务器端——非 daemon 或网络层问题。
>
> 资料来源：[Issue #8](https://github.com/ARAS-Workspace/claude-kvm/issues/8)

### SSH 隧道建议

对于生产环境，建议使用 SSH 隧道保护 VNC 流量：

```bash
ssh -L 5900:localhost:5900 user@vnc-server
```

资料来源：[README.md:Mac M1 Preparation Tricks 引用]()

## 配置命令

### 运行时认证参数

虽然认证方法在连接时自动协商，但可通过 `configure` 动作调整连接参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `max_dimension` | 1280 | 最大显示尺寸 |
| `hover_settle_ms` | 400 | 悬停稳定时间 |

```json
{"method":"configure","params":{"max_dimension":960}}
```

资料来源：[README.md:Configuration 部分]()
资料来源：[tools/index.js:configure 动作定义]()

## 故障排查

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 认证失败 | 口令错误或 Auth Type 不匹配 | 检查 VNC_PASSWORD，确认服务器认证类型 |
| 连接超时 | 防火墙阻止或端口错误 | 验证 VNC_HOST:VNC_PORT 连通性 |
| ARD 认证失败 | 缺少 VNC_USERNAME | 对于 macOS ARD 服务器，设置 VNC_USERNAME |
| 长时间会话断开 | VNC 服务器超时 | 参考 Issue #8，考虑保活机制 |

## 技术栈总结

| 组件 | 语言 | 认证职责 |
|------|------|----------|
| MCP Proxy | JavaScript (Node.js) | 接收环境变量，传递给 Daemon |
| VNC Daemon | Swift/C | 执行 RFB 握手，处理 VNC/ARD 认证 |
| LibVNC | C (静态链接) | 底层 VNC 协议实现 |

---

<a id='installation'></a>

## 安装指南

### 相关页面

相关主题：[配置参数详解](#configuration), [故障排除](#troubleshooting)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- [README_TR.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README_TR.md)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [LAUNCHGUIDE.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/LAUNCHGUIDE.md)
</details>

# 安装指南

本指南详细说明如何在不同平台上安装和配置 Claude KVM。Claude KVM 由两个核心组件构成：基于 Node.js 的 MCP 代理层和运行在 macOS 上的原生 Swift VNC daemon。正确安装这两个组件是使用该工具的前提条件。

## 系统要求

### 硬件与平台要求

| 要求项 | 规格 | 说明 |
|--------|------|------|
| **操作系统** | macOS (Apple Silicon / aarch64) | daemon 仅支持 Apple Silicon 架构 |
| **运行时** | Node.js (LTS) | MCP 代理层依赖 Node.js 环境 |
| **VNC 服务器** | 任意支持 VNC 协议的服务器 | 支持标准 VNC Auth 和 Apple Remote Desktop |

> [!NOTE]
> 如果在裸机 Mac 上运行，请参阅 [Mac M1 Preparation Tricks](https://gist.github.com/remrearas/a3f300635b02f2587a134882a51f7114) 以获取 VNC 安全、SSH 隧道和会话稳定性的配置建议。资料来源：[README.md]()

### 网络要求

VNC 连接需要目标主机满足以下条件：

- VNC 服务器已启用并正常运行
- 网络可达（本地网络或通过 VPN/SSH 隧道）
- 防火墙允许 VNC 端口通信（默认 5900）

> [!TIP]
> **Phantom-WG** 可能是一个很好的替代方案。它可以在隔离 VNC 服务器的同时为您提供自托管 VPN 性能的隐私功能。资料来源：[README.md]()

## 组件安装

Claude KVM 的安装分为两个阶段：安装 MCP 包和安装 daemon。

```mermaid
graph TD
    A[开始安装] --> B[安装 Node.js 环境]
    B --> C[安装 claude-kvm npm 包]
    C --> D[添加 Homebrew Tap]
    D --> E[安装 claude-kvm-daemon]
    E --> F[配置环境变量]
    F --> G[配置 MCP 客户端]
    G --> H[验证安装]
```

### 第一阶段：安装 MCP 包

MCP 包通过 npm 安装，提供 Claude 与 daemon 之间的代理层：

```bash
npm install -g claude-kvm
```

或者使用 npx 直接运行（无需全局安装）：

```json
{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"]
    }
  }
}
```

当前版本信息：资料来源：[package.json:3]()

```json
{
  "name": "claude-kvm",
  "version": "2.0.11",
  "description": "MCP server — control remote desktops via VNC (MacOS)"
}
```

### 第二阶段：安装 Daemon

daemon 是 Claude KVM 的核心组件，负责 VNC 连接、屏幕捕获和输入注入。它通过 Homebrew 分发并经过代码签名和公证：

```bash
brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon
```

> [!NOTE]
> `claude-kvm-daemon` 在 CI（GitHub Actions）上编译并进行代码签名。编译输出以两种格式打包：用于 Homebrew 分发的 `.tar.gz` 存档和用于公证的 `.dmg` 磁盘镜像。DMG 包在同一流程中发送到 Apple 服务器进行公证。资料来源：[README_TR.md]()

#### Daemon 发布版本

| 版本 | 发布日期 | 说明 |
|------|----------|------|
| [v1.0.1](https://github.com/ARAS-Workspace/claude-kvm/releases/tag/daemon-v1.0.1) | 最新 | 当前稳定版本 |
| [v1.0.0](https://github.com/ARAS-Workspace/claude-kvm/releases/tag/daemon-v1.0.0) | 初始版本 | 首次正式发布 |

## 环境变量配置

### 必需的环境变量

在项目根目录创建 `.env` 文件或设置系统环境变量：

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `VNC_HOST` | — | VNC 服务器主机地址（必需） |
| `VNC_PORT` | `5900` | VNC 端口号 |
| `VNC_USERNAME` | — | 用户名（ARD 认证时必需） |
| `VNC_PASSWORD` | — | VNC 密码 |
| `CLAUDE_KVM_DAEMON_PATH` | `claude-kvm-daemon` | daemon 二进制路径（PATH 中存在时可选） |
| `CLAUDE_KVM_DAEMON_PARAMETERS` | — | 传递给 daemon 的额外 CLI 参数 |

### 示例配置

`.env` 文件示例：

```bash
VNC_HOST=192.168.1.100
VNC_PORT=5900
VNC_USERNAME=user
VNC_PASSWORD=pass
CLAUDE_KVM_DAEMON_PATH=/opt/homebrew/bin/claude-kvm-daemon
```

## MCP 客户端配置

### Claude Desktop 配置

在项目根目录创建 `.mcp.json` 文件：

```json
{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass",
        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon"
      }
    }
  }
}
```

### Daemon 参数配置

通过 `CLAUDE_KVM_DAEMON_PARAMETERS` 传递额外参数：

```json
{
  "env": {
    "CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"
  }
}
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--max-dimension` | `1280` | 屏幕缩放最大尺寸（像素） |
| `--connect-timeout` | — | VNC 连接超时时间（秒） |
| `--bits-per-sample` | — | 每像素位数 |
| `--no-reconnect` | — | 禁用自动重连 |
| `-v, --verbose` | — | 启用详细日志输出（stderr） |

资料来源：[README_TR.md]()

## VNC 服务器配置

### 标准 VNC Auth

大多数 VNC 服务器使用密码挑战-响应认证（DES 算法）。直接配置 `VNC_PASSWORD` 即可。

### Apple Remote Desktop (ARD)

macOS 系统通常使用 ARD 认证，需要配置 Diffie-Hellman 密钥交换和 AES-128-ECB 加密：

```bash
VNC_USERNAME=admin
VNC_PASSWORD=your_ard_password
```

> [!NOTE]
> macOS 通过 ARD auth type 30 凭证请求自动检测。当检测到 ARD 时，Meta 键会重新映射到 Super（Command 键兼容性）。资料来源：[README.md]()

## 已知问题与限制

### VNC 连接在长时间测试中断开

社区问题 [#8](https://github.com/ARAS-Workspace/claude-kvm/issues/8) 报告了在长时间测试会话（约 50 轮）期间 VNC 连接断开的问题。

**问题表现：**
- VNC 连接在扩展测试会话中丢失
- daemon 无响应
- SSH 远程连接 Mac 保持活跃

**影响范围：** 问题发生在 VNC/ARD 服务器端，而非 daemon 或网络层。资料来源：[community_context]()

**可能的解决方向：**
- 使用 `--no-reconnect` 参数禁用自动重连以测试稳定性
- 考虑使用 SSH 隧道来提高连接稳定性
- 检查 VNC 服务器的会话超时配置

## 验证安装

安装完成后，可通过以下方式验证：

1. **检查 daemon 版本：**
   ```bash
   claude-kvm-daemon --version
   ```

2. **使用 MCP 健康检查工具：**
   在 Claude 对话中调用 `vnc_command` 工具：
   ```json
   {"method":"health"}
   ```

3. **获取当前配置：**
   ```json
   {"method":"get_timing"}
   ```

预期响应示例：
```json
{
  "result": {
    "timing": {
      "click_hold_ms": 50,
      "key_hold_ms": 30,
      "hover_settle_ms": 400
    },
    "scaledWidth": 1280,
    "scaledHeight": 779
  }
}
```

## 故障排除

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| daemon 找不到 | PATH 配置错误 | 设置 `CLAUDE_KVM_DAEMON_PATH` 为完整路径 |
| 连接超时 | 防火墙或网络问题 | 检查 VNC 服务器状态和网络连通性 |
| 认证失败 | ARD 需要用户名 | 设置 `VNC_USERNAME` 环境变量 |
| 屏幕坐标不准确 | 分辨率不匹配 | 调整 `--max-dimension` 参数 |

---

<a id='configuration'></a>

## 配置参数详解

### 相关页面

相关主题：[安装指南](#installation), [工具参考手册](#tools-reference)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- [README_TR.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README_TR.md)
- [index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/index.js)
- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
- [server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)
</details>

# 配置参数详解

## 概述

Claude KVM 提供两套互补的配置系统，用于控制 VNC 连接行为和远程桌面操作时序。这两套系统共同决定了整个工具链的运行方式、性能表现和交互精度。

**环境变量配置**负责 daemon 的启动参数和连接目标，在进程启动时一次性设置；**运行时配置**则允许 Claude 在会话过程中动态调整操作时序和显示参数，无需重连即可改变行为。

资料来源：[index.js:1-30]()

## 环境变量配置

环境变量是 MCP Proxy 与 VNC Daemon 之间的桥梁，用于指定连接目标、认证信息和可执行文件路径。

### 核心连接参数

| 环境变量 | 必填 | 说明 |
|----------|------|------|
| `VNC_HOST` | 是 | VNC 服务器主机名或 IP 地址 |
| `VNC_PORT` | 是 | VNC 服务器端口号（默认 5900） |
| `VNC_USERNAME` | 否 | VNC/ARD 用户名，用于认证 |
| `VNC_PASSWORD` | 否 | VNC/ARD 密码，用于认证 |

### Daemon 路径配置

| 环境变量 | 说明 |
|----------|------|
| `CLAUDE_KVM_DAEMON_PATH` | claude-kvm-daemon 可执行文件路径，默认值为 `/opt/homebrew/bin/claude-kvm-daemon` |

资料来源：[server.json:25-40]()

### 配置示例

```json
{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass",
        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon"
      }
    }
  }
}
```

资料来源：[README_TR.md:15-25]()

## 运行时配置（configure）

运行时配置通过 `vnc_command` 工具的 `configure` 方法实现，支持动态修改操作时序和显示参数。所有修改立即生效，无需重启 daemon 或重新建立 VNC 连接。

### 配置查询

使用 `get_timing` 方法查询当前所有配置参数值：

```json
{"method":"get_timing"}
```

### 参数设置

```json
{"method":"configure","params":{"click_hold_ms":80,"key_hold_ms":50}}
```

返回结果确认已修改的参数：

```json
{"result":{"detail":"OK — changed: click_hold_ms, key_hold_ms"}}
```

### 重置为默认值

```json
{"method":"configure","params":{"reset":true}}
```

资料来源：[README.md:85-95]()

## 时序参数详解

时序参数控制鼠标、键盘、拖拽和滚动操作的精确时序，适配不同性能和负载的远程桌面环境。

### 鼠标操作参数

| 参数名 | 默认值 | 单位 | 说明 |
|--------|--------|------|------|
| `click_hold_ms` | 50 | 毫秒 | 单次点击的按下保持时间 |
| `double_click_gap_ms` | 50 | 毫秒 | 双击操作中两次点击的间隔 |
| `hover_settle_ms` | 400 | 毫秒 | hover 操作后等待元素稳定的时间 |
| `cursor_crop_radius` | 150 | 像素 | cursor_crop 裁剪区域的半径大小 |

### 拖拽操作参数

| 参数名 | 默认值 | 单位 | 说明 |
|--------|--------|------|------|
| `drag_press_ms` | 50 | 毫秒 | 拖拽开始时按键按下时间 |
| `drag_position_ms` | 30 | 毫秒 | 拖拽开始前鼠标定位等待时间 |
| `drag_step_ms` | 5 | 毫秒 | 拖拽步骤间延迟 |
| `drag_settle_ms` | 30 | 毫秒 | 拖拽释放前等待稳定的时间 |
| `drag_pixels_per_step` | 20 | 像素 | 每个拖拽步骤的像素距离 |
| `drag_min_steps` | 10 | 步数 | 最小拖拽插值步数 |

### 键盘操作参数

| 参数名 | 默认值 | 单位 | 说明 |
|--------|--------|------|------|
| `key_hold_ms` | 30 | 毫秒 | 普通按键按下保持时间 |
| `combo_mod_ms` | 10 | 毫秒 | 组合键中修饰键的响应延迟 |
| `type_key_ms` | 20 | 毫秒 | 逐字输入时按键按下时间 |
| `type_inter_key_ms` | 20 | 毫秒 | 字符间延迟 |
| `type_shift_ms` | 10 | 毫秒 | Shift 键切换延迟 |
| `paste_settle_ms` | 30 | 毫秒 | 粘贴操作后剪贴板稳定等待时间 |

### 滚动操作参数

| 参数名 | 默认值 | 单位 | 说明 |
|--------|--------|------|------|
| `scroll_press_ms` | 10 | 毫秒 | 滚动按键按下时间 |
| `scroll_tick_ms` | 20 | 毫秒 | 滚动 tick 之间的间隔 |

资料来源：[README_TR.md:95-130]()

## 显示配置参数

### 坐标缩放系统

VNC 服务器的原生分辨率会被缩放到 `max_dimension` 指定的范围内，Claude 在缩放后的坐标空间中工作，daemon 自动处理与原生帧缓冲区的坐标转换。

```
原生分辨率:  4220 × 2568  (VNC 服务器帧缓冲区)
缩放分辨率:  1280 × 779   (Claude 可见和操作的目标空间)

mouse_click(640, 400) → daemon 转换为 (2110, 1284)
```

| 参数名 | 说明 |
|--------|------|
| `max_dimension` | 缩放后显示的最大边长（默认 1280px） |
| `scaledWidth` | 当前缩放后的宽度 |
| `scaledHeight` | 当前缩放后的高度 |

配置显示缩放：

```json
{"method":"configure","params":{"max_dimension":960}}
```

返回确认信息：

```json
{"result":{"detail":"OK — changed: max_dimension","scaledWidth":960,"scaledHeight":584}}
```

资料来源：[README.md:65-75]()

## Daemon 命令行参数

claude-kvm-daemon 支持以下命令行选项：

| 参数 | 说明 |
|------|------|
| `--host <地址>` | VNC 服务器地址 |
| `--port <端口>` | VNC 服务器端口 |
| `--username <用户名>` | ARD 用户名 |
| `--password <密码>` | ARD 密码 |
| `--pixel-format <格式>` | 像素格式（如 rgb888） |
| `--max-dimension <像素>` | 缩放最大边长 |
| `--no-reconnect` | 禁用自动重连 |
| `-v, --verbose` | 详细日志输出到 stderr |

资料来源：[README_TR.md:55-65]()

## 配置系统架构

配置参数在三个层级中流动，从环境变量到运行时配置，形成完整的控制体系。

```mermaid
graph TD
    A[环境变量] --> B[MCP Proxy<br/>index.js]
    B --> C[Daemon 启动参数]
    C --> D[VNC Daemon<br/>claude-kvm-daemon]
    E[运行时 configure] --> D
    F[get_timing 查询] --> D
    D --> G[VNC 连接参数]
    D --> H[时序参数]
    D --> I[显示缩放]
    
    J[用户会话] --> K[vnc_command 工具]
    K --> E
    K --> F
```

## 认证配置

Claude KVM 支持两种 VNC 认证方法：

| 认证方式 | 协议 | 加密 |
|----------|------|------|
| VNC Auth | DES | 挑战-响应 |
| ARD | Diffie-Hellman + AES-128-ECB | 密钥交换 + 对称加密 |

macOS 目标通过 ARD auth type 30 凭证请求自动检测。检测到 macOS 后，Meta 键自动重映射为 Super 键，确保 Command 键兼容性。

资料来源：[README.md:140-150]()

## 社区已知问题与配置建议

根据社区反馈 Issue #8，在长时间测试会话（约 50 轮交互）后，VNC 连接可能断开，daemon 变得无响应。通过 SSH 仍可连接到远程 Mac，表明问题出在 VNC/ARD 服务器端，而非 daemon 或网络层。

**建议配置**：对于长时间运行的任务，可考虑：

1. 调整 `hover_settle_ms` 参数以减少不必要的等待
2. 使用 `diff_check` 替代频繁的 `screenshot` 操作以降低连接负载
3. 定期调用 `health` 检查连接状态

资料来源：[社区 Issue #8](https://github.com/ARAS-Workspace/claude-kvm/issues/8)

## 完整配置参数速查表

| 参数名 | 默认值 | 范围 | 适用操作 |
|--------|--------|------|----------|
| `click_hold_ms` | 50 | 10-500 | 鼠标点击 |
| `double_click_gap_ms` | 50 | 10-500 | 鼠标双击 |
| `hover_settle_ms` | 400 | 50-2000 | 悬停 |
| `cursor_crop_radius` | 150 | 50-500 | 截图裁剪 |
| `drag_press_ms` | 50 | 10-500 | 拖拽 |
| `drag_position_ms` | 30 | 10-500 | 拖拽 |
| `drag_step_ms` | 5 | 1-100 | 拖拽 |
| `drag_settle_ms` | 30 | 10-500 | 拖拽 |
| `drag_pixels_per_step` | 20 | 5-100 | 拖拽 |
| `drag_min_steps` | 10 | 3-50 | 拖拽 |
| `scroll_press_ms` | 10 | 5-200 | 滚动 |
| `scroll_tick_ms` | 20 | 5-200 | 滚动 |
| `key_hold_ms` | 30 | 10-200 | 键盘 |
| `combo_mod_ms` | 10 | 5-100 | 组合键 |
| `type_key_ms` | 20 | 10-200 | 打字 |
| `type_inter_key_ms` | 20 | 10-200 | 打字 |
| `type_shift_ms` | 10 | 5-100 | 打字 |
| `paste_settle_ms` | 30 | 10-200 | 粘贴 |
| `max_dimension` | 1280 | 480-3840 | 显示缩放 |

资料来源：[tools/index.js:1-50](), [README_TR.md:95-130]()

---

<a id='troubleshooting'></a>

## 故障排除

### 相关页面

相关主题：[安装指南](#installation), [实时测试与演示](#live-testing)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- [index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/index.js)
- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
</details>

# 故障排除

本文档提供 Claude KVM 使用过程中常见问题的诊断和解决方案。

## 概述

Claude KVM 是一个基于 VNC 协议的远程桌面控制工具，通过 MCP（Model Context Protocol）与 Claude 通信。故障排查主要涉及三个层面：MCP 代理层（JavaScript/Node.js）、PC 协议通信层（NDJSON）、以及 VNC 守护进程层（Swift/C）。

## 诊断工具

### health 命令

`health` 命令返回当前连接状态和显示信息，是排查连接问题的首选工具：

```json
{"method":"health"}
```

响应示例：

```json
{"result":{"status":"connected","scaledWidth":1280,"scaledHeight":779,"nativeWidth":4220,"nativeHeight":2568}}
```

资料来源：[tools/index.js:23]()

### 日志级别

使用 `--verbose` 参数启动 MCP 服务器以获取详细日志：

```bash
npx -y claude-kvm --verbose
```

日志输出到 stderr，包含 VNC 协议交互、守护进程通信等详细信息。

## 常见问题与解决方案

### 连接问题

#### VNC 连接断开

**问题描述**：长时间测试会话（约 50 轮）后 VNC 连接断开，守护进程无响应，但 SSH 仍可连接远程 Mac。

**社区反馈**：此问题已在 [Issue #8](https://github.com/ARAS-Workspace/claude-kvm/issues/8) 中报告，表明问题根源在 VNC/ARD 服务器端，而非守护进程或网络层。

**排查步骤**：

1. 验证网络层正常：通过 SSH 连接确认远程主机可达
2. 使用 `health` 命令检查连接状态
3. 检查 VNC 服务器日志（位于远程 Mac 的 `/var/log/`）
4. 考虑启用自动重连机制

**自动重连配置**：

默认情况下，守护进程会自动尝试重新连接。如需禁用，添加 `--no-reconnect` 参数：

```bash
claude-kvm-daemon --no-reconnect
```

资料来源：[README.md - 命令行参数]()

#### 守护进程启动失败

**问题描述**：守护进程无法启动或立即退出。

**排查步骤**：

1. 验证 VNC 服务器正在运行
2. 检查端口 5900（默认 VNC 端口）是否被占用
3. 确认 `claude-kvm-daemon` 已正确安装：

```bash
which claude-kvm-daemon
/opt/homebrew/bin/claude-kvm-daemon
```

资料来源：[index.js:48-62]()

### 认证问题

#### VNC 认证失败

Claude KVM 支持两种认证方式：

| 认证方式 | 协议 | 说明 |
|----------|------|------|
| VNC Auth | DES challenge-response | 标准 VNC 密码认证 |
| ARD | Diffie-Hellman + AES-128-ECB | Apple Remote Desktop |

**排查步骤**：

1. 确认环境变量中的密码正确
2. 检查 VNC 服务器的认证设置
3. 对于 macOS ARD，确保 `VNC_USERNAME` 和 `VNC_PASSWORD` 均已设置

**环境变量配置**：

```json
{
  "VNC_HOST": "192.168.1.100",
  "VNC_PORT": "5900",
  "VNC_USERNAME": "user",
  "VNC_PASSWORD": "pass"
}
```

资料来源：[server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)

### 显示与坐标问题

#### 坐标缩放错误

**问题描述**：鼠标点击位置与预期不符。

**原因**：VNC 服务器原生分辨率与 Claude 可见的缩放分辨率不同。

Claude KVM 自动将缩放坐标转换为原生坐标：

```
原生分辨率:  4220 × 2568 (VNC 服务器 framebuffer)
缩放分辨率:  1280 × 779   (Claude 操作的目标空间)

mouse_click(640, 400) → VNC 服务器收到 (2110, 1284)
```

资料来源：[README.md - Coordinate Scaling]()

**配置缩放参数**：

使用 `configure` 命令调整最大尺寸：

```json
{"method":"configure","params":{"max_dimension":960}}
```

响应示例：

```json
{"result":{"detail":"OK — changed: max_dimension","scaledWidth":960,"scaledHeight":584}}
```

#### OCR 检测位置偏差

**问题描述**：`detect_elements` 返回的坐标与实际截图不匹配。

**说明**：`detect_elements` 使用 Apple Vision framework 进行本地 OCR，返回的边界框坐标基于缩放空间，与截图分辨率一致。

返回数据结构：

```json
{
  "elements": [
    {"confidence": 1, "h": 9, "text": "Finder", "w": 32, "x": 37, "y": 6}
  ],
  "scaledHeight": 717,
  "scaledWidth": 1280
}
```

资料来源：[tools/index.js:28]()

### 性能与时序问题

#### 动作执行过快

**问题描述**：连续动作执行时出现遗漏或乱序。

**排查步骤**：

1. 使用 `get_timing` 查看当前时序参数：

```json
{"method":"get_timing"}
```

2. 调整关键时序参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `click_hold_ms` | 50 | 点击按住时长 |
| `key_hold_ms` | 30 | 键盘按住时长 |
| `hover_settle_ms` | 400 | 悬停后等待时长 |
| `type_inter_key_ms` | 20 | 打字时字符间隔 |

**配置示例**：

```json
{"method":"configure","params":{"click_hold_ms":80,"key_hold_ms":50}}
```

响应：

```json
{"result":{"detail":"OK — changed: click_hold_ms, key_hold_ms"}}
```

#### 拖拽操作失败

拖拽操作涉及多个阶段，任何阶段延迟不足都可能导致失败：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `drag_press_ms` | 50 | 按住起点时长 |
| `drag_step_ms` | 5 | 步骤间延迟 |
| `drag_position_ms` | 30 | 位置更新间隔 |
| `drag_settle_ms` | 30 | 释放前等待 |
| `drag_min_steps` | 10 | 最小插值步数 |

资料来源：[README.md - 时序参数表]()

### 守护进程无响应

#### 长时间运行后无响应

**问题描述**：守护进程在长时间运行后停止响应命令。

**排查步骤**：

1. 使用 `health` 命令确认状态：

```json
{"method":"health"}
```

2. 尝试优雅关闭：

```json
{"method":"shutdown"}
```

3. 如果无响应，强制终止并重启守护进程

4. 检查守护进程日志（`--verbose` 模式）

资料来源：[index.js:64-73]()

#### 发送 shutdown 后进程未退出

**代码逻辑**：

```javascript
process.on('SIGINT', () => {
  log('Shutting down...');
  if (daemon) {
    daemon.stdin.write(JSON.stringify({ method: 'shutdown' }) + '\n');
    setTimeout(() => { daemon?.kill(); process.exit(0); }, 500);
  } else {
    process.exit(0);
  }
});
```

守护进程发送 shutdown 命令后，MCP 服务器会在 500ms 后强制终止守护进程。

资料来源：[index.js:64-73]()

## 环境变量配置参考

| 变量名 | 必需 | 说明 |
|--------|------|------|
| `VNC_HOST` | 是 | VNC 服务器主机名或 IP |
| `VNC_PORT` | 是 | VNC 服务器端口 |
| `VNC_USERNAME` | 否 | VNC/ARD 用户名 |
| `VNC_PASSWORD` | 否 | VNC/ARD 密码 |
| `CLAUDE_KVM_DAEMON_PATH` | 否 | 守护进程自定义路径 |

## 调试工作流

建议的调试工作流：

```mermaid
graph TD
    A[发现异常行为] --> B{health 命令响应?}
    B -->|超时/错误| C[检查 VNC 服务器]
    B -->|connected| D[检查时序参数]
    C --> E[VNC 服务器日志]
    D --> F[get_timing]
    E --> G[重启 VNC 服务器]
    F --> H{参数合理?}
    H -->|否| I[configure 调整]
    H -->|是| J[考虑坐标缩放]
    I --> J
    J --> K[verify screenshot]
```

## 已知问题

### Issue #8: VNC 连接在长时间会话中断开

**问题状态**：社区已报告

**现象**：
- 扩展测试会话（约 50 轮）后 VNC 连接断开
- 守护进程变得无响应
- SSH 仍可连接远程 Mac

**结论**：问题根源在 VNC/ARD 服务器端，而非 Claude KVM 守护进程或网络层。

**临时解决方案**：
1. 定期重启 VNC 服务器
2. 配置自动重连（默认已启用）
3. 缩短单次会话时长

资料来源：[社区上下文 - Issue #8](https://github.com/ARAS-Workspace/claude-kvm/issues/8)

## 命令行参数参考

| 参数 | 说明 |
|------|------|
| `--max-dimension <px>` | 最大显示尺寸（默认 1280） |
| `--pixel-density <ratio>` | 像素密度（默认 2.0） |
| `--daemon-path <path>` | 守护进程路径 |
| `--no-reconnect` | 禁用自动重连 |
| `-v, --verbose` | 详细日志输出 |

资料来源：[package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)

## 联系与反馈

如遇到本文档未涵盖的问题，请通过以下方式获取帮助：

- [GitHub Issues](https://github.com/ARAS-Workspace/claude-kvm/issues)
- [项目主页](https://github.com/ARAS-Workspace/claude-kvm)

---

<a id='live-testing'></a>

## 实时测试与演示

### 相关页面

相关主题：[故障排除](#troubleshooting), [系统架构](#architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README.md)
- [README_TR.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/README_TR.md)
- [tools/index.js](https://github.com/ARAS-Workspace/claude-kvm/blob/main/tools/index.js)
- [package.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/package.json)
- [server.json](https://github.com/ARAS-Workspace/claude-kvm/blob/main/server.json)
- [LAUNCHGUIDE.md](https://github.com/ARAS-Workspace/claude-kvm/blob/main/LAUNCHGUIDE.md)
</details>

# 实时测试与演示

## 概述

Claude KVM 提供完整的端到端测试基础设施，用于验证远程桌面控制功能的正确性。测试系统基于 GitHub Actions 运行在真实 macOS 虚拟机上，覆盖 VNC 连接、屏幕捕获、鼠标键盘交互、OCR 检测等核心功能。

测试模块的主要职责包括：

- **功能验证**：确保所有 vnc_command 工具行为符合预期
- **回归测试**：每次提交后自动运行，防止引入破坏性变更
- **集成测试**：验证 MCP 协议层与 Swift Daemon 之间的通信正确性
- **性能基准**：测量屏幕捕获、OCR 检测等操作的响应时间

资料来源：[README.md:1-50]()

## 架构设计

### 测试执行层级

```
┌─────────────────────────────────────────────────────────────┐
│                    GitHub Actions Runner                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              macOS Virtual Machine                   │   │
│  │  ┌─────────────┐    ┌─────────────┐    ┌──────────┐ │   │
│  │  │   VNC Server │    │  Claude KVM  │    │  测试脚本 │ │   │
│  │  │  (目标桌面)   │◄──►│   MCP Proxy  │◄──►│ (e2e/)  │ │   │
│  │  └─────────────┘    └─────────────┘    └──────────┘ │   │
│  │         ▲                   │                       │   │
│  │         │                   ▼                       │   │
│  │         │         ┌─────────────────┐                │   │
│  │         └────────►│  claude-kvm-    │                │   │
│  │                   │     daemon       │                │   │
│  │                   └─────────────────┘                │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

### 组件交互流程

```mermaid
graph TD
    A[测试脚本] --> B[启动 Daemon]
    B --> C[建立 VNC 连接]
    C --> D{认证方式检测}
    D -->|VNC Auth| E[DES Challenge-Response]
    D -->|ARD Auth| F[DH Key Exchange + AES]
    E --> G[发送 vnc_command 请求]
    F --> G
    G --> H[接收 NDJSON 响应]
    H --> I{验证结果}
    I -->|通过| J[截图存档]
    I -->|失败| K[记录错误并退出]
    J --> L[生成测试报告]
```

## 测试类型

### 集成测试矩阵

| 测试名称 | 目标功能 | 验证点 | 预期耗时 |
|----------|----------|--------|----------|
| Integration Test | 基础连接与工具 | VNC 连接、截图、鼠标点击 | ~2分钟 |
| Mac Calculator Test | 计算器应用 | UI 元素检测、精确点击 | ~3分钟 |
| Mac Safari Browsing Test | 浏览器控制 | 导航、输入、页面交互 | ~5分钟 |
| Mac Drag & Drop Test | 拖拽操作 | 起点终点坐标、路径平滑度 | ~2分钟 |
| Mac Chess Test | 复杂交互 | 棋盘识别、棋子拖放 | ~4分钟 |
| Mac Scientific Calculator | 科学计算器 | 高级按键、结果显示 | ~3分钟 |

资料来源：[README.md:1-30]()

### 工具行为测试

每个测试场景都验证 `vnc_command` 工具的不同动作组合：

```javascript
// 工具动作覆盖范围
const toolActions = {
  screen: ['screenshot', 'cursor_crop', 'diff_check', 'set_baseline'],
  mouse: ['mouse_click', 'mouse_double_click', 'mouse_move', 'hover', 'nudge', 'mouse_drag', 'scroll'],
  keyboard: ['key_tap', 'key_combo', 'key_type', 'paste'],
  detection: ['detect_elements'],
  control: ['configure', 'get_timing', 'wait', 'health', 'shutdown']
};
```

资料来源：[tools/index.js:1-30]()

## 测试工作流

### CI/CD 执行流程

```mermaid
graph LR
    A[代码提交] --> B[触发 Workflow]
    B --> C[启动 macOS Runner]
    C --> D[安装依赖]
    D --> E[启动 VNC Server]
    E --> F[启动 claude-kvm-daemon]
    F --> G[运行 e2e 测试]
    G --> H{测试结果}
    H -->|成功| I[上传 Artifacts]
    H -->|失败| J[截图调试信息]
    J --> K[报告失败]
    I --> L[生成 Release]
```

### 端到端测试脚本结构

```
test/
├── README.md              # 测试文档
├── mac/
│   ├── test/
│   │   └── README_TR.md   # Mac 专用测试说明
│   ├── calculator/        # 计算器测试
│   ├── safari/            # 浏览器测试
│   └── chess/             # 棋类游戏测试
└── fixtures/              # 测试数据和配置
```

资料来源：[README.md:20-35]()

## 演示环境

### 实时测试运行

项目维护多个公开的 CI 测试运行记录，可用于观察系统实际表现：

| 测试名称 | 运行ID | 说明 |
|----------|--------|------|
| Integration Test | 22261661594 | 基础集成验证 |
| Mac Integration Test | 22261487249 | Mac 环境完整测试 |
| Mac Calculator Test | 22261139721 | 计算器功能测试 |
| Mac Scientific Calculator | 22261184519 | 科学计算器测试 |
| Mac Safari Browsing Test | 22261430282 | 浏览器导航测试 |
| Mac Drag & Drop Test | 22277460796 | 拖拽交互测试 |

资料来源：[README_TR.md:1-40]()

### 演示视频

项目仓库包含测试运行的实际录制：

- **Mac Demo 录制**：`assets/test/mac/demo-mac-run-22261487249.gif`
- 展示完整的 VNC 远程控制流程
- 包含屏幕捕获、鼠标移动、键盘输入等操作

## 已知问题

### 长时测试连接中断

**问题编号**：#8

**现象描述**：

在长时间运行的测试会话（约50次交互轮次）后，VNC 连接会意外断开，Daemon 进程变得无响应。通过 SSH 连接到远程 Mac 仍然正常，表明问题发生在 VNC/ARD 服务器端，而非 Daemon 或网络层。

**问题特征**：

| 指标 | 观察值 |
|------|--------|
| 触发条件 | 约 50 轮连续交互后 |
| 连接状态 | VNC 断开，Daemon 无响应 |
| SSH 连接 | 保持正常 |
| 问题定位 | VNC/ARD 服务器端 |

**社区讨论**：该问题已有 2 条评论，用户建议在长时间测试中加入定期重连机制。

资料来源：[社区上下文 - Issue #8]()

### 缓解建议

1. **增加健康检查频率**：在长测试会话中定期调用 `health` 方法验证连接状态
2. **实现自动重连**：使用 `--reconnect` 参数启用自动重连功能
3. **会话分割**：将大型测试拆分为多个较短会话
4. **日志监控**：使用 `--verbose` 参数记录详细日志便于问题诊断

## 配置参数

### 测试相关配置

| 参数 | 默认值 | 说明 | 测试场景 |
|------|--------|------|----------|
| `--max-dimension` | 1280 | 最大显示尺寸 | 确保测试截图一致性 |
| `--no-reconnect` | false | 禁用自动重连 | 验证重连机制 |
| `-v, --verbose` | false | 详细日志 | 调试测试失败 |

### 运行时调优

测试过程中可通过 `configure` 方法动态调整参数：

```json
{
  "method": "configure",
  "params": {
    "click_hold_ms": 80,
    "key_hold_ms": 50,
    "hover_settle_ms": 400
  }
}
```

关键时序参数：

| 参数 | 默认值 | 用途 |
|------|--------|------|
| `click_hold_ms` | 50 | 鼠标按下持续时间 |
| `hover_settle_ms` | 400 | 悬停后等待稳定 |
| `key_hold_ms` | 30 | 按键按下持续时间 |
| `type_inter_key_ms` | 20 | 字符输入间隔 |
| `drag_step_ms` | 5 | 拖拽步进间隔 |

资料来源：[README.md:50-80]()

## 性能基准

### 操作响应时间

| 操作 | 典型耗时 | 说明 |
|------|----------|------|
| `screenshot` | ~200ms | 完整屏幕捕获 |
| `cursor_crop` | ~150ms | 光标区域裁剪 |
| `detect_elements` | ~50ms | Apple Vision OCR |
| `mouse_click` | <50ms | 点击操作注入 |
| `key_type` | 20ms/字符 | 逐字符输入 |

资料来源：[README_TR.md:15-25]()

## 扩展测试

### 自定义测试场景

开发者可基于现有测试框架编写自定义测试：

1. **环境准备**：启动 VNC Server 和 claude-kvm-daemon
2. **初始化**：调用 `health` 确认连接正常
3. **执行步骤**：按序发送 `vnc_command` 请求
4. **验证结果**：对比截图或 OCR 结果
5. **清理**：调用 `shutdown` 正常关闭

### 测试工具清单

```javascript
// 完整的测试工具列表
const testTools = {
  // 屏幕操作
  screenshot: '获取当前屏幕PNG',
  cursor_crop: '获取光标周围区域',
  diff_check: '与基准对比检测变化',
  set_baseline: '设置差异检测基准',
  
  // 鼠标操作
  mouse_click: '单点击',
  mouse_double_click: '双击',
  mouse_move: '移动光标',
  hover: '悬停并等待稳定',
  nudge: '相对位移',
  mouse_drag: '拖拽操作',
  scroll: '滚动操作',
  
  // 键盘操作
  key_tap: '按键',
  key_combo: '组合键',
  key_type: '文本输入',
  paste: '剪贴板粘贴',
  
  // 检测与控制
  detect_elements: 'OCR元素检测',
  health: '健康检查',
  shutdown: '关闭连接'
};
```

资料来源：[tools/index.js:10-30]()

## 相关资源

| 资源 | 链接 |
|------|------|
| 最新 Daemon 版本 | [daemon-v1.0.1](https://github.com/ARAS-Workspace/claude-kvm/releases/tag/daemon-v1.0.1) |
| LibVNC 构建 | [Actions Run #22122975416](https://github.com/ARAS-Workspace/claude-kvm/actions/runs/22122975416) |
| Homebrew 安装 | [homebrew-tap](https://github.com/ARAS-Workspace/homebrew-tap) |
| Mac 配置技巧 | [Mac M1 Preparation Tricks](https://gist.github.com/remrearas/a3f300635b02f2587a134882a51f7114) |

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：aras-workspace/claude-kvm

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：VNC connection drops during long-running test sessions。

## 1. 安装坑 · 来源证据：VNC connection drops during long-running test sessions

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：VNC connection drops during long-running test sessions
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c5f8215134dd43ca8306d08dc0e808ac | https://github.com/ARAS-Workspace/claude-kvm/issues/8 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11 | host_targets=mcp_host, claude

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11 | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11 | last_activity_observed missing

## 5. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11 | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11 | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11 | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11 | release_recency=unknown

<!-- canonical_name: aras-workspace/claude-kvm; human_manual_source: deepwiki_human_wiki -->