项目概述

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

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

技术架构

核心技术栈

资料来源：README.md:50-56LAUNCHGUIDE.md:45-48

通信协议

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

// 请求格式
{"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

核心功能

屏幕操作

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

鼠标操作

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

键盘操作

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

OCR 文本检测

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

{"method":"detect_elements"}

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

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

配置与控制

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

认证机制

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

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

资料来源：README.md:150-154

运行时配置参数

时间参数

显示参数

资料来源：LAUNCHGUIDE.md:155-176

版本信息

资料来源：package.json:4server.json:12

已知问题与限制

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

根据社区反馈 (issue #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:

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 文件：

{
  "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

使用场景

资料来源：LAUNCHGUIDE.md:14-21

相关链接

概述

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

系统的主要职责包括：

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

资料来源：LAUNCHGUIDE.md:1-15

架构分层

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

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 实现，主要依赖以下组件：

工具定义

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

资料来源：tools/index.js:1-50

Daemon 生命周期管理

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

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 认证方式：

当检测到 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":"screenshot","params":{},"id":1}

响应：

{"result":{"format":"png","width":1280,"height":717,"data":"<base64>"},"id":1}

检测元素示例

请求：

{"method":"detect_elements","params":{}}

响应：

{
  "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)

缩放参数

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

资料来源：README.md:177-185

运行时配置

可配置参数

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

配置操作示例

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

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

重置为默认值：

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

查询当前配置：

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

资料来源：README_TR.md:95-130

命令行参数

Daemon 参数

环境变量

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

资料来源：server.json:25-60

已知限制

VNC 连接稳定性

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

相关 Issue：#8 VNC connection drops during long-running test sessions

平台限制

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

资料来源：LAUNCHGUIDE.md:25-30

组件交互流程

典型操作流程

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

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 个操作，适用于复杂的多步骤工作流：

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

发布与分发

发布版本

当前最新版本：

分发方式

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. 运行时配置 — 支持动态调整时序参数，无需重启连接

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

概述

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

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 代理层采用清晰的两层架构设计：

资料来源：README.md:1-50

MCP 代理职责

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

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

// 核心代理启动流程
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

请求-响应流程

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 操作分类为以下动作组：

资料来源：tools/index.js:10-35

输入 Schema

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

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 代理层通过环境变量进行配置：

资料来源：server.json:20-35

配置读取实现

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() 启动原生守护进程：

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

参数说明：

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

生命周期管理

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

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

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 层错误处理

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

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

致命错误处理

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

依赖项

运行时依赖

资料来源：package.json:20-30

开发依赖

坐标系统

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

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

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

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

认证机制

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

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

概述

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

守护进程通过标准输入/输出与 Node.js MCP 代理层通信，使用 NDJSON 格式的 PC（Procedure Call）协议交换命令和响应，实现了高效的双工通信机制。 资料来源：README.md

架构设计

系统分层

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

资料来源：README.md

组件架构图

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

守护进程子组件

资料来源：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

支持的方法

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

资料来源：tools/index.js:19-35

核心功能详解

屏幕捕获

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

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

典型工作流程：

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

输入注入

#### 鼠标操作

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

#### 键盘操作

Apple Vision OCR

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

{
  "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

安装与配置

安装方式

VNC 守护进程通过 Homebrew 安装：

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

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

claude-kvm-daemon --version

资料来源：LAUNCHGUIDE.md

命令行参数

资料来源：LAUNCHGUIDE.md

环境变量配置

资料来源：server.json:25-46

MCP 配置

在项目目录创建 .mcp.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

已知问题

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

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

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

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

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

临时解决方案：

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

资料来源：GitHub Issue #8

版本历史

资料来源：GitHub Releases

技术栈

资料来源：README.md

工作流程示例

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

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
• Homebrew Tap: homebrew-tap
• 问题反馈: GitHub Issues
• Mac M1 配置技巧: VNC 加固与 SSH 隧道指南

架构概览

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

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

资料来源：README.md:55-65

vnc_command 工具概述

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

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 模式进行操作：

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

屏幕操作

screenshot

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

{"action": "screenshot"}

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

cursor_crop

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

{"action": "cursor_crop"}

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

diff_check

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

{"action": "diff_check"}

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

鼠标操作

坐标系统

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

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

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

资料来源：README.md:70-75

mouse_click

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

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

mouse_drag

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

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

scroll

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

键盘操作

key_tap

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

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

key_combo

修饰符组合键示例：

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

或数组格式：

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

key_type

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

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

paste

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

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

元素检测

detect_elements

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

{"action": "detect_elements"}

响应示例：

{
  "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
  }
}

返回字段说明：

资料来源：README.md:88-105

配置管理

configure

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

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

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

完整配置参数表

资料来源：README.md:180-200

重置为默认值

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

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

系统控制

health

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

{"action": "health"}

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

shutdown

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

{"action": "shutdown"}

操作队列

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

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

资料来源：tools/index.js:1-30

认证方式

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

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 获取 VNC 安全和会话稳定性建议。

资料来源：community_context

完整操作索引

相关链接

• 最新守护进程版本： daemon-v1.0.1
• 安装指南： 参见 README.md
• 持续集成测试： GitHub Actions

概述

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

资料来源：README.md:认证机制部分

支持的认证方法

VNC Auth（标准口令认证）

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

认证流程：

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

资料来源：README.md:Authentication部分

ARD Auth（Apple Remote Desktop）

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

资料来源：README_TR.md:Kimlik Doğrulama部分

认证检测与自动协商

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

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 代理：

MCP Server 配置示例

{
  "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 协议通信：

// 连接请求（隐含认证）
{"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 通信部分

安全考量

传输安全

已知限制

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

问题：扩展测试会话期间 VNC 连接断开，daemon 无响应。SSH 远程 Mac 连接保持活跃，确认问题在 VNC/ARD 服务器端——非 daemon 或网络层问题。

资料来源：Issue #8

SSH 隧道建议

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

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

资料来源：README.md:Mac M1 Preparation Tricks 引用

配置命令

运行时认证参数

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

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

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

故障排查

技术栈总结

系统要求

硬件与平台要求

[!NOTE]

如果在裸机 Mac 上运行，请参阅 Mac M1 Preparation Tricks 以获取 VNC 安全、SSH 隧道和会话稳定性的配置建议。资料来源：README.md

网络要求

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

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

[!TIP]

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

组件安装

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

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 之间的代理层：

npm install -g claude-kvm

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

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

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

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

第二阶段：安装 Daemon

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

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 发布版本

环境变量配置

必需的环境变量

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

示例配置

.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

MCP 客户端配置

Claude Desktop 配置

在项目根目录创建 .mcp.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 传递额外参数：

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

资料来源：README_TR.md

VNC 服务器配置

标准 VNC Auth

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

Apple Remote Desktop (ARD)

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

VNC_USERNAME=admin
VNC_PASSWORD=your_ard_password

[!NOTE]

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

已知问题与限制

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

社区问题 #8 报告了在长时间测试会话（约 50 轮）期间 VNC 连接断开的问题。

问题表现：

• VNC 连接在扩展测试会话中丢失
• daemon 无响应
• SSH 远程连接 Mac 保持活跃

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

可能的解决方向：

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

验证安装

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

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

1. 检查 daemon 版本：

在 Claude 对话中调用 vnc_command 工具： ``json {"method":"health"} ``

1. 使用 MCP 健康检查工具：

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

1. 获取当前配置：

预期响应示例：

{
  "result": {
    "timing": {
      "click_hold_ms": 50,
      "key_hold_ms": 30,
      "hover_settle_ms": 400
    },
    "scaledWidth": 1280,
    "scaledHeight": 779
  }
}

故障排除

概述

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

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

资料来源：index.js:1-30

环境变量配置

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

核心连接参数

Daemon 路径配置

资料来源：server.json:25-40

配置示例

{
  "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 方法查询当前所有配置参数值：

{"method":"get_timing"}

参数设置

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

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

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

重置为默认值

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

资料来源：README.md:85-95

时序参数详解

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

鼠标操作参数

拖拽操作参数

键盘操作参数

滚动操作参数

资料来源：README_TR.md:95-130

显示配置参数

坐标缩放系统

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

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

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

配置显示缩放：

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

返回确认信息：

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

资料来源：README.md:65-75

Daemon 命令行参数

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

资料来源：README_TR.md:55-65

配置系统架构

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

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 认证方法：

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

完整配置参数速查表

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

概述

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

诊断工具

health 命令

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

{"method":"health"}

响应示例：

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

资料来源：tools/index.js:23

日志级别

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

npx -y claude-kvm --verbose

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

常见问题与解决方案

连接问题

#### VNC 连接断开

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

社区反馈：此问题已在 Issue #8 中报告，表明问题根源在 VNC/ARD 服务器端，而非守护进程或网络层。

排查步骤：

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

自动重连配置：

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

claude-kvm-daemon --no-reconnect

资料来源：README.md - 命令行参数

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

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

排查步骤：

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

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

资料来源：index.js:48-62

认证问题

#### VNC 认证失败

Claude KVM 支持两种认证方式：

排查步骤：

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

环境变量配置：

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

资料来源：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 命令调整最大尺寸：

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

响应示例：

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

#### OCR 检测位置偏差

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

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

返回数据结构：

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

资料来源：tools/index.js:28

性能与时序问题

#### 动作执行过快

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

排查步骤：

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

{"method":"get_timing"}

1. 调整关键时序参数：

配置示例：

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

响应：

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

#### 拖拽操作失败

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

资料来源：README.md - 时序参数表

守护进程无响应

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

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

排查步骤：

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

{"method":"health"}

1. 尝试优雅关闭：

{"method":"shutdown"}

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

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

资料来源：index.js:64-73

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

代码逻辑：

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

环境变量配置参考

调试工作流

建议的调试工作流：

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

命令行参数参考

资料来源：package.json

联系与反馈

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

• GitHub Issues
• 项目主页

概述

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       │                │   │
│  │                   └─────────────────┘                │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

组件交互流程

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[生成测试报告]

测试类型

集成测试矩阵

资料来源：README.md:1-30

工具行为测试

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

// 工具动作覆盖范围
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 执行流程

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 测试运行记录，可用于观察系统实际表现：

资料来源：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 或网络层。

问题特征：

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

资料来源：社区上下文 - Issue #8

缓解建议

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

配置参数

测试相关配置

运行时调优

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

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

关键时序参数：

资料来源：README.md:50-80

性能基准

操作响应时间

资料来源：README_TR.md:15-25

扩展测试

自定义测试场景

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

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

测试工具清单

// 完整的测试工具列表
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

相关资源

Pitfall Log / 踩坑日志

项目：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