# macOS 远程桌面客户端设计文档

## 1. 概述

### 1.1 目标

在不影响现有 Windows/Linux 功能的基础上，为 YAMA 项目添加 macOS 客户端支持，前期实现远程桌面控制功能。

### 1.2 功能范围（Phase 1）

| 功能 | 优先级 | 状态 | 说明 |
|-----|--------|------|------|
| 连接服务器 | P0 | ⏳ Stub | 复用现有网络协议 |
| 屏幕捕获 | P0 | ✅ 完成 | CGDisplayCreateImage 实现 |
| 鼠标控制 | P0 | ✅ 完成 | CGEvent 实现 |
| 键盘控制 | P0 | ✅ 完成 | CGEvent + VK映射 |
| 光标同步 | P1 | ⏳ 待实现 | 显示当前光标类型 |
| 多显示器 | P2 | ⏳ 待实现 | 支持多屏幕选择 |

### 1.3 参考实现

- **Linux 客户端** (`linux/`): 架构相似，协议兼容
- **RustDesk**: 成熟的跨平台远程桌面开源项目
- **Sunshine**: 高性能游戏串流项目

---

## 2. 架构设计

### 2.1 目录结构（已实现）

```
YAMA/
├── common/              # 跨平台共享（已有）
│   ├── commands.h       # 协议定义
│   └── ...
├── client/              # Windows 客户端（不动）
├── linux/               # Linux 客户端（不动）
└── macos/               # macOS 客户端（Phase 1 完成）
    ├── CMakeLists.txt   # 构建配置
    ├── build.sh         # 一键编译脚本
    ├── README.txt       # 使用说明
    ├── IOCPClient.h     # 网络客户端 stub
    ├── main.mm          # 入口点 + 系统信息
    ├── Permissions.h    # 权限检查声明
    ├── Permissions.mm   # 权限检查实现
    ├── ScreenHandler.h  # 屏幕捕获声明
    ├── ScreenHandler.mm # 屏幕捕获实现
    ├── InputHandler.h   # 输入模拟声明
    ├── InputHandler.mm  # 输入模拟实现
    ├── SystemManager.h  # 进程管理声明
    └── SystemManager.mm # 进程管理实现
```

### 2.2 模块依赖关系

```
┌─────────────────────────────────────────────────┐
│                   main.mm                        │
│         (入口、权限检查、系统信息收集)             │
└─────────────┬───────────────────────────────────┘
              │
    ┌─────────┼─────────┬─────────────┐
    ▼         ▼         ▼             ▼
┌───────┐ ┌───────┐ ┌───────┐ ┌────────────┐
│Screen │ │Input  │ │System │ │IOCPClient  │
│Handler│ │Handler│ │Manager│ │(网络 stub) │
└───┬───┘ └───┬───┘ └───────┘ └────────────┘
    │         │
    ▼         ▼
┌─────────────────────────────────┐
│     macOS 系统框架               │
│  CoreGraphics (截屏)            │
│  Carbon (键码定义)              │
│  ApplicationServices (权限)     │
└─────────────────────────────────┘
```

---

## 3. 技术选型

### 3.1 屏幕捕获方案（已选定）

| 方案 | 最低版本 | 性能 | 复杂度 | 选择 |
|-----|---------|------|--------|-----|
| `CGDisplayCreateImage` | 10.5 | 中 | 低 | **✅ 已采用** |
| `CGDisplayStream` | 10.8 | 中 | 中 | 备选 |
| `ScreenCaptureKit` | 12.3 | 高 | 高 | 未来考虑 |

**选择 CGDisplayCreateImage**：
- 实现简单，兼容性好
- 与 Linux 端 `XGetImage` 方案一致
- 足以支持 10-30 FPS 传输

### 3.2 输入模拟方案（已实现）

| 功能 | API | 实现状态 |
|-----|-----|---------|
| 鼠标移动 | `CGEventCreateMouseEvent` | ✅ 完成 |
| 鼠标点击 | `CGEventCreateMouseEvent` | ✅ 完成 |
| 鼠标拖动 | `kCGEventLeftMouseDragged` | ✅ 完成 |
| 鼠标滚轮 | `CGEventCreateScrollWheelEvent` | ✅ 完成 |
| 键盘输入 | `CGEventCreateKeyboardEvent` | ✅ 完成 |
| 事件发送 | `CGEventPost(kCGHIDEventTap)` | ✅ 完成 |

### 3.3 VK 键码映射（已实现）

Windows VK 码到 macOS CGKeyCode 的完整映射：

| 按键类型 | VK 范围 | macOS 映射 |
|---------|---------|-----------|
| 字母 A-Z | 0x41-0x5A | kVK_ANSI_A - kVK_ANSI_Z |
| 数字 0-9 | 0x30-0x39 | kVK_ANSI_0 - kVK_ANSI_9 |
| 小键盘 | 0x60-0x69 | kVK_ANSI_Keypad0 - 9 |
| F1-F12 | 0x70-0x7B | kVK_F1 - kVK_F12 |
| 方向键 | 0x25-0x28 | kVK_LeftArrow 等 |
| 修饰键 | 0x10-0x12 | kVK_Shift/Control/Option |
| Win 键 | 0x5B-0x5C | kVK_Command |

### 3.4 差分算法（与 Linux 一致）

| 算法 | ID | 说明 |
|-----|-----|------|
| ALGORITHM_GRAY | 0 | 灰度压缩 |
| ALGORITHM_DIFF | 1 | BGRA 差分 |
| ALGORITHM_H264 | 2 | 硬件编码（未实现）|
| ALGORITHM_RGB565 | 3 | RGB565 压缩 |

### 3.5 macOS 版本支持

| 版本 | 代号 | 发布年份 | 支持状态 |
|-----|------|---------|---------|
| 10.13 | High Sierra | 2017 | ✅ 目标最低版本 |
| 10.14 | Mojave | 2018 | ✅ 支持 |
| 10.15 | Catalina | 2019 | ✅ 支持（需权限） |
| 11.x | Big Sur | 2020 | ✅ 支持 |
| 12.x | Monterey | 2021 | ✅ 支持 |
| 13.x | Ventura | 2022 | ✅ 支持 |
| 14.x | Sonoma | 2023 | ✅ 支持 |

**注意**：macOS 10.15+ 需要用户授予屏幕录制权限。

---

## 4. 权限处理

### 4.1 所需权限

| 权限 | 用途 | 最低要求版本 | 授权方式 |
|-----|------|------------|---------|
| **屏幕录制** | 捕获屏幕内容 | 10.15 | 系统偏好设置 > 隐私 > 屏幕录制 |
| **辅助功能** | 模拟键盘/鼠标输入 | 所有版本 | 系统偏好设置 > 隐私 > 辅助功能 |

### 4.2 权限检查实现（Permissions.mm）

```objc
// 检查屏幕录制权限
bool Permissions::checkScreenCapture() {
    if (@available(macOS 10.15, *)) {
        CGImageRef image = CGWindowListCreateImage(
            CGRectMake(0, 0, 1, 1),
            kCGWindowListOptionOnScreenOnly,
            kCGNullWindowID,
            kCGWindowImageDefault
        );
        if (image == nil) return false;
        CGImageRelease(image);
        return true;
    }
    return true;  // 10.15 之前不需要权限
}

// 检查辅助功能权限
bool Permissions::checkAccessibility() {
    return AXIsProcessTrusted();
}

// 请求辅助功能权限（弹出系统对话框）
void Permissions::requestAccessibility() {
    NSDictionary *options = @{
        (__bridge id)kAXTrustedCheckOptionPrompt: @YES
    };
    AXIsProcessTrustedWithOptions((__bridge CFDictionaryRef)options);
}
```

### 4.3 权限引导流程

```
程序启动
    │
    ▼
检查屏幕录制权限 ──否──▶ 打开系统偏好设置
    │
    是
    │
    ▼
检查辅助功能权限 ──否──▶ 弹出授权对话框
    │
    是
    │
    ▼
正常运行
```

---

## 5. 核心代码实现

### 5.1 ScreenHandler（已实现）

```objc
// ScreenHandler.h
class ScreenHandler {
public:
    ScreenHandler();
    ~ScreenHandler();

    bool init();                                    // 初始化
    void start(IOCPClient* client, uint64_t id);   // 开始捕获
    void stop();                                    // 停止捕获

    int getWidth() const;
    int getHeight() const;

    void sendBitmapInfo();                         // 发送屏幕信息
    void onReceive(const uint8_t* data, size_t size);
    void applyQualityLevel(int8_t level, bool persist);

private:
    bool captureScreen(std::vector<uint8_t>& buffer);  // 截屏
    void sendFirstScreen();                            // 发送首帧
    void sendDiffFrame();                              // 发送差分帧
    uint32_t compareBitmap(...);                       // 差分计算
    void convertBGRAtoGray(...);                       // 灰度转换
    void convertBGRAtoRGB565(...);                     // RGB565转换
    void captureLoop();                                // 捕获循环

    // 成员变量
    IOCPClient* m_client;
    CGDirectDisplayID m_displayID;
    BITMAPINFOHEADER_MAC m_bmpHeader;
    std::vector<uint8_t> m_prevFrame, m_currFrame;
    std::atomic<bool> m_running;
    std::atomic<uint8_t> m_algorithm;
    std::atomic<int> m_maxFPS;
};
```

### 5.2 InputHandler（已实现）

```objc
// InputHandler.h
class InputHandler {
public:
    InputHandler();
    ~InputHandler();

    bool init();                                    // 初始化（检查权限）
    void handleInputEvent(const MSG64_MAC* msg);   // 处理输入事件
    bool hasAccessibilityPermission() const;

private:
    void handleMouseMove(int x, int y);
    void handleMouseButton(CGMouseButton button, bool down, int x, int y);
    void handleMouseDoubleClick(CGMouseButton button, int x, int y);
    void handleMouseWheel(int delta);
    void handleKeyEvent(uint32_t vkCode, bool down);

    static CGKeyCode vkToMacKeyCode(uint32_t vk);  // VK 到 macOS 键码映射

    bool m_hasPermission;
    CGPoint m_lastMousePos;
    bool m_leftButtonDown, m_rightButtonDown, m_middleButtonDown;
};
```

### 5.3 SystemManager（已实现）

```objc
// SystemManager.h
class SystemManager {
public:
    SystemManager(IOCPClient* client, uint64_t clientID);
    ~SystemManager();

    void onReceive(const uint8_t* data, size_t size);

private:
    void sendProcessList();                        // 进程列表
    void killProcesses(const uint8_t* data, size_t size);
    void sendWindowsList();                        // 窗口列表

    static std::vector<pid_t> getAllPids();        // 枚举进程
    static std::string getProcessName(pid_t pid);
    static std::string getProcessPath(pid_t pid);
};
```

### 5.4 main.mm（已实现）

主要功能：
- 命令行参数解析
- 权限检查和引导
- 系统信息收集（主机名、OS版本、CPU、内存等）
- 初始化各处理器
- 主事件循环

```objc
int main(int argc, const char* argv[]) {
    @autoreleasepool {
        // 1. 解析命令行参数
        // 2. 检查权限
        // 3. 收集系统信息
        // 4. 初始化 ScreenHandler, InputHandler
        // 5. 主循环
    }
    return 0;
}
```

---

## 6. 构建配置

### 6.1 CMakeLists.txt

```cmake
cmake_minimum_required(VERSION 3.15)
project(ghost_macos)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_OSX_DEPLOYMENT_TARGET "10.13")
set(CMAKE_OSX_ARCHITECTURES "x86_64;arm64")  # Universal Binary

set(SOURCES
    main.mm
    ScreenHandler.mm
    InputHandler.mm
    SystemManager.mm
    Permissions.mm
)

add_executable(ghost ${SOURCES})

target_include_directories(ghost PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

# 链接 macOS 框架
find_library(COCOA_FRAMEWORK Cocoa REQUIRED)
find_library(COREGRAPHICS_FRAMEWORK CoreGraphics REQUIRED)
find_library(IOKIT_FRAMEWORK IOKit REQUIRED)
find_library(IOSURFACE_FRAMEWORK IOSurface REQUIRED)
find_library(APPLICATIONSERVICES_FRAMEWORK ApplicationServices REQUIRED)
find_library(SECURITY_FRAMEWORK Security REQUIRED)
find_library(CARBON_FRAMEWORK Carbon REQUIRED)

target_link_libraries(ghost PRIVATE
    ${COCOA_FRAMEWORK}
    ${COREGRAPHICS_FRAMEWORK}
    ${IOKIT_FRAMEWORK}
    ${IOSURFACE_FRAMEWORK}
    ${APPLICATIONSERVICES_FRAMEWORK}
    ${SECURITY_FRAMEWORK}
    ${CARBON_FRAMEWORK}
)

target_compile_options(ghost PRIVATE -Wall -Wextra -fobjc-arc)
```

### 6.2 编译命令

```bash
# 方式 1: 使用脚本
chmod +x build.sh
./build.sh

# 方式 2: 手动编译
mkdir build && cd build
cmake ..
make -j$(sysctl -n hw.ncpu)

# 输出: build/bin/ghost
```

---

## 7. 实现进度

### Phase 1: 基础框架 ✅ 完成

| 任务 | 状态 | 产出 |
|-----|------|------|
| 创建目录结构 | ✅ | `macos/` 目录 |
| CMakeLists.txt | ✅ | 构建配置 |
| Permissions.h/mm | ✅ | 权限检查 |
| ScreenHandler.h/mm | ✅ | 屏幕捕获 |
| InputHandler.h/mm | ✅ | 输入模拟 |
| SystemManager.h/mm | ✅ | 进程管理 |
| main.mm | ✅ | 入口点 |
| IOCPClient.h | ✅ | 网络 stub |

### Phase 2: 网络集成 ⏳ 待实现

| 任务 | 状态 | 说明 |
|-----|------|------|
| IOCPClient 实现 | ⏳ | 复用 client/IOCPClient |
| 登录信息发送 | ⏳ | LOGIN_INFOR 结构 |
| 心跳保活 | ⏳ | Heartbeat 机制 |
| 命令分发 | ⏳ | DataProcess 回调 |

### Phase 3: 功能完善 ⏳ 待实现

| 任务 | 状态 |
|-----|------|
| 光标类型同步 | ⏳ |
| 多显示器支持 | ⏳ |
| 文件传输 | ⏳ |
| 剪贴板同步 | ⏳ |

### Phase 4: 代码保护 ⏳ 待实现

| 任务 | 状态 |
|-----|------|
| 服务端密钥对生成 | ⏳ |
| 服务端签名逻辑 | ⏳ |
| 闭源库 libYamaCore | ⏳ |
| 客户端绑定验证 | ⏳ |

---

## 8. 测试指南

### 8.1 编译前准备

```bash
# 安装 Xcode Command Line Tools
xcode-select --install

# 安装 CMake (通过 Homebrew)
brew install cmake
```

### 8.2 编译运行

```bash
# 获取代码
git clone <repo-url>
cd YAMA/macos

# 编译
./build.sh

# 运行
./build/bin/ghost [server_ip] [port]
```

### 8.3 首次运行权限授予

1. **屏幕录制权限**：
   - 系统偏好设置 > 隐私与安全性 > 屏幕录制
   - 添加 `ghost` 可执行文件

2. **辅助功能权限**：
   - 系统偏好设置 > 隐私与安全性 > 辅助功能
   - 添加 `ghost` 可执行文件

### 8.4 预期输出

```
=== macOS Ghost Client (Phase 1) ===
Server: 192.168.0.55:6543
Checking permissions...
Collecting system information...
Hostname: MacBook-Pro.local
OS: macOS 14.0.0
CPU: Apple M1 (0 MHz, 8 cores)
Memory: 16.0 GB
User: username
Resolution: 1:2560x1600
Executable: /path/to/ghost
Start Time: 2024-04-29 12:00:00
Initializing handlers...
Screen handler initialized: 2560x1600
Input handler initialized
=== Phase 1 Status ===
Screen Capture: READY
Input Control:  READY
Network:        STUB (Phase 2)
======================
Starting main loop (Ctrl+C to exit)...
```

---

## 9. 常见问题

### 9.1 编译问题

| 问题 | 原因 | 解决方案 |
|-----|------|---------|
| 找不到 Foundation.h | 缺少 Xcode CLT | `xcode-select --install` |
| CMake 找不到 | 未安装 CMake | `brew install cmake` |
| 架构不匹配 | Universal Binary 问题 | 检查 CMAKE_OSX_ARCHITECTURES |

### 9.2 运行时问题

| 问题 | 原因 | 解决方案 |
|-----|------|---------|
| 程序无法打开 | 未签名 | `xattr -d com.apple.quarantine ghost` |
| Screen Capture: NEED PERMISSION | 无录屏权限 | 系统偏好设置授权 |
| Input Control: NEED PERMISSION | 无辅助功能权限 | 系统偏好设置授权 |

### 9.3 权限重置

```bash
# 如果权限状态混乱，可重置
tccutil reset ScreenCapture
tccutil reset Accessibility
```

---

## 10. 代码保护机制（待实现）

### 10.1 保护策略

核心思路：客户端内嵌服务端公钥，连接时验证服务端身份。

```
┌─────────────────────┐                    ┌─────────────────────┐
│   macOS Client      │                    │   Your Server       │
│                     │    1. 挑战请求     │                     │
│ ┌─────────────────┐ │ ─────────────────▶ │ ┌─────────────────┐ │
│ │ libYamaCore.a   │ │                    │ │  服务端私钥     │ │
│ │ (闭源)          │ │ ◀───────────────── │ │                 │ │
│ │ 内嵌服务端公钥  │ │    2. 签名响应     │ └─────────────────┘ │
│ │                 │ │                    │                     │
│ │ 验证签名 ─────▶ 匹配 ──▶ 正常工作                           │
│ │         ─────▶ 不匹配 ──▶ 拒绝连接                          │
│ └─────────────────┘ │                    │                     │
└─────────────────────┘                    └─────────────────────┘
```

### 10.2 实施步骤

1. 生成服务端密钥对
2. 服务端添加签名逻辑
3. 创建闭源库 libYamaCore
4. 嵌入公钥编译
5. 客户端集成验证

---

## 11. 参考资料

### 11.1 官方文档

- [CGDisplayCreateImage](https://developer.apple.com/documentation/coregraphics/1454434-cgdisplaycreateimage)
- [CGEvent Reference](https://developer.apple.com/documentation/coregraphics/cgevent)
- [Carbon Events.h](https://developer.apple.com/documentation/carbon/events_h)
- [Accessibility API](https://developer.apple.com/documentation/applicationservices/axuielement_h)

### 11.2 开源项目参考

- [RustDesk macOS](https://github.com/rustdesk/rustdesk/tree/master/src/platform/macos)
- [Sunshine Screen Capture](https://github.com/LizardByte/Sunshine/tree/master/src/platform/macos)

---

## 12. 修订历史

| 日期 | 版本 | 修改内容 |
|-----|------|---------|
| 2026-04-28 | 1.0 | 初始版本（设计文档） |
| 2026-04-29 | 1.1 | 更新为实现文档，Phase 1 完成 |