PC Conductor

操作系统级别的鼠标和键盘控制库，使用 Rust 编写，支持 Windows、macOS 和 Linux。

特性

• 🖱️ 鼠标控制：移动、点击、拖拽、滚动
• ⌨️ 键盘控制：输入文本、按键、组合键
• 🌐 跨平台：支持 Windows、macOS、Linux
• 🚀 高性能：基于 Rust，零成本抽象
• 🔒 类型安全：编译时类型检查，避免运行时错误
• 🌐 HTTP API：提供 RESTful API，任何语言都可以调用
• 📝 配置文件驱动：通过 YAML/JSON 配置文件定义操作序列

安装

在 Cargo.toml 中添加依赖：

[dependencies]
pc-control = { path = "../pc-control" }

或者从本地路径使用：

[dependencies]
pc-control = { path = "./packages/pc-control" }

注意：本项目使用 rdev 库（而不是 enigo），因为它更稳定，特别是在 macOS 上不会出现段错误问题。

快速开始

方式 1: 独立可执行文件（推荐用于生产环境）

编译独立可执行文件

cd packages/pc-control

# Release 版本（优化，文件更小）
cargo build --release --bin pc-control

编译后的可执行文件位于：target/release/pc-control

使用方式

从本地文件运行：

./target/release/pc-control examples/user_example.yaml
./target/release/pc-control examples/script_example.json

从 URL 运行（支持 HTTP/HTTPS）：

# 从 GitHub 获取配置
./target/release/pc-control https://raw.githubusercontent.com/user/repo/main/script.yaml

# 从内部服务器获取配置
./target/release/pc-control http://config-server:8080/scripts/daily-task.yaml

# 从 HTTPS URL
./target/release/pc-control https://example.com/automation.json

程序会自动检测配置格式（YAML/JSON），支持从本地文件或远程 URL 加载。

打包和分发

详细打包指南请查看 BUILD.md

方式 2: 使用配置文件（开发环境）

通过 YAML 或 JSON 配置文件定义操作序列：

name: "My Script"
steps:
  - type: click
    x: 960
    y: 540
    button: left
  - type: input
    key: Q
  - type: input
    key: E
  - type: hold
    modifiers: [shift]
    key: W
    duration: 20000

运行脚本：

# 使用独立可执行文件
./target/release/pc-control examples/script_example.yaml

# 或开发模式
cargo run --bin pc-control -- examples/script_example.yaml

详细文档请查看 SCRIPT_GUIDE.md

方式 3: 编程方式

在 Rust 代码中直接使用：

use pc_control::{InputController, MouseButton, Key};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut controller = InputController::new()?;

    // 鼠标操作
    controller.mouse().move_to(500, 500)?;
    controller.mouse().click(MouseButton::Left)?;
    controller.mouse().double_click(100, 100, None)?;
    controller.mouse().drag(100, 100, 500, 500, MouseButton::Left)?;
    controller.mouse().scroll_vertical(3)?;

    // 键盘操作
    controller.keyboard().type_text("Hello, World!")?;
    controller.keyboard().press(Key::Enter)?;
    controller.keyboard().ctrl(Key::C)?; // Ctrl+C

    // 组合操作
    controller.click_and_type(100, 100, "Text")?;
    controller.copy()?;
    controller.paste()?;

    Ok(())
}

方式 4: HTTP API 服务器（可选）

启动 HTTP 服务器，提供 RESTful API：

# 启动服务器（默认端口 8080）
cargo run --bin pc-control-server --features server

# 或指定端口
cargo run --bin pc-control-server --features server -- 3000

然后从任何语言调用 API：

# 使用 curl
curl -X POST http://localhost:8080/api/v1/mouse/move \
  -H "Content-Type: application/json" \
  -d '{"x": 960, "y": 540, "duration": 1000}'

详细文档请查看 API_GUIDE.md 和 QUICK_START_API.md

API 文档

鼠标操作

MouseController

// 创建鼠标控制器
let mut mouse = MouseController::new();

// 移动鼠标
mouse.move_to(x: i32, y: i32)?;

// 点击
mouse.click(button: MouseButton)?;
mouse.click_at(x: i32, y: i32, button: MouseButton)?;

// 按下/释放
mouse.press(button: MouseButton)?;
mouse.release(button: MouseButton)?;

// 拖拽
mouse.drag(from_x: i32, from_y: i32, to_x: i32, to_y: i32, button: MouseButton)?;

// 滚动
mouse.scroll_vertical(amount: i32)?;  // 正数向下，负数向上
mouse.scroll_horizontal(amount: i32)?; // 正数向右，负数向左

// 双击
mouse.double_click(x: i32, y: i32, button: Option<MouseButton>)?;

MouseButton

• MouseButton::Left - 左键
• MouseButton::Right - 右键
• MouseButton::Middle - 中键

键盘操作

KeyboardController

// 创建键盘控制器
let mut keyboard = KeyboardController::new();

// 输入文本
keyboard.type_text("Hello, World!")?;

// 按键
keyboard.press(key: Key)?;
keyboard.press_down(key: Key)?;
keyboard.release(key: Key)?;

// 组合键
keyboard.ctrl(Key::C)?;           // Ctrl+C
keyboard.alt(Key::Tab)?;          // Alt+Tab
keyboard.shift(Key::A)?;          // Shift+A
keyboard.meta(Key::V)?;           // Cmd+V (macOS) 或 Win+V (Windows)
keyboard.ctrl_shift(Key::N)?;      // Ctrl+Shift+N
keyboard.ctrl_alt(Key::T)?;       // Ctrl+Alt+T

// 自定义组合键
keyboard.key_combination(&[KeyModifier::Control, KeyModifier::Shift], Key::N)?;

支持的按键

字母和数字：Key::A 到 Key::Z，Key::Num0 到 Key::Num9

功能键：Key::F1 到 Key::F12

修饰键：Key::Control、Key::Alt、Key::Shift、Key::Meta

导航键：Key::ArrowUp、Key::ArrowDown、Key::ArrowLeft、Key::ArrowRight、Key::Home、Key::End、Key::PageUp、Key::PageDown

编辑键：Key::Backspace、Key::Delete、Key::Insert、Key::Enter、Key::Tab、Key::Escape

特殊键：Key::Space、Key::CapsLock、Key::NumLock、Key::ScrollLock

组合操作

InputController

let mut controller = InputController::new()?;

// 点击并输入
controller.click_and_type(x: i32, y: i32, text: &str)?;

// 剪贴板操作（自动适配平台）
controller.select_all()?;  // Ctrl+A 或 Cmd+A
controller.copy()?;        // Ctrl+C 或 Cmd+C
controller.paste()?;       // Ctrl+V 或 Cmd+V
controller.cut()?;         // Ctrl+X 或 Cmd+X
controller.undo()?;        // Ctrl+Z 或 Cmd+Z
controller.redo()?;        // Ctrl+Y 或 Cmd+Shift+Z

运行示例

基本示例

cargo run --example basic

高级示例

cargo run --example advanced

平台特定说明

macOS

需要在"系统设置 > 隐私与安全性 > 辅助功能"中授予应用权限。

Linux

可能需要以下权限之一：

• X11 访问权限
• uinput 模块权限（需要 root 或用户组权限）

Windows

通常不需要特殊权限，但某些操作可能需要管理员权限。

错误处理

所有操作都返回 Result<T, InputError>，可以这样处理：

match controller.mouse().click(MouseButton::Left) {
    Ok(()) => println!("Click successful"),
    Err(e) => eprintln!("Error: {}", e),
}

性能考虑

• 默认操作之间有 10ms 的延迟，可以通过 set_default_delay() 调整
• 对于批量操作，考虑使用异步或并发
• 避免过于频繁的操作，可能导致系统响应问题

依赖

• rdev - 跨平台输入模拟库（比 enigo 更稳定）
• thiserror - 错误处理
• serde - 序列化支持
• serde_yaml - YAML 配置文件支持
• serde_json - JSON 配置文件支持
• minreq - 轻量级 HTTP 客户端（用于从 URL 加载配置）

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！