Handy CLI

你是否想过，只需说话，就能生成代码、执行快捷键、获取 AI 建议？

Handy CLI 是一款面向开发者和高效能用户的本地化语音控制工具，它将语音识别、AI 辅助与键盘自动化结合，让你通过自然语言直接操控电脑操作。

无需鼠标，无需切换应用，按下一个组合键，说出指令，任务自动完成——这一切都在本地运行，数据不离设备。

核心功能一览

Handy CLI 不只是一个语音转文字工具，而是一个完整的语音驱动生产力系统。它的五大核心能力包括：

• 🎙️ 本地语音识别：基于 MLX Whisper 模型，在 Apple Silicon Mac 上实现低延迟、高精度的离线转录
• 🤖 AI 智能响应：通过 OpenRouter 接入 Claude 等模型，理解语义并返回智能建议
• 💻 代码生成：说出需求，自动生成结构清晰的代码片段
• ⌨️ 键盘命令自动化：用语音触发复制、粘贴、保存等常用快捷键
• 📝 上下文感知输入：结合剪贴板内容，实现更智能的 AI 交互与文本插入

所有功能均可通过预设的键盘快捷键一键激活，无缝融入日常编码或写作流程。

快捷键设计：精准区分使用场景

Handy CLI 采用多组合键机制，确保不同模式互不干扰。每个按键组合对应一种操作类型：

✅ 使用提示：所有操作均为“按住—说话—松开”模式，类似语音版快捷键，学习成本极低。

实际使用示例

✅ 场景一：语音生成代码

1. 按住 Ctrl + Alt + Cmd (左)
2. 说：“写一个 Python 函数，用来计算斐波那契数列前 n 项”
3. 松开按键
4. 生成的函数自动出现在编辑器中

def fibonacci(n):
    sequence = []
    a, b = 0, 1
    for _ in range(n):
        sequence.append(a)
        a, b = b, a + b
    return sequence

✅ 场景二：获取 AI 建议（带上下文）

1. 先选中一段出错的代码，复制到剪贴板（可选）
2. 按住 Shift + Alt (左)
3. 说：“这段代码报错了，提示 list index out of range，怎么修复？”
4. 松开后，AI 分析上下文并返回修复建议

✅ 场景三：快速文本输入

1. 按住 Ctrl + Cmd (右)
2. 说：“这个模块负责用户认证和权限校验”
3. 松开，文字立即输入到文档或聊天框中

✅ 场景四：语音控制快捷键

1. 按住 Ctrl + Shift (左)
2. 说：“save file”
3. 自动触发 Cmd + S 保存当前文件

支持常见命令映射：

• “copy” → Cmd + C
• “paste” → Cmd + V
• “undo” → Cmd + Z
• “select all” → Cmd + A

技术架构解析

Handy CLI 采用模块化设计，各组件职责明确，便于维护与扩展。

主要模块构成

🔍 注：目前 MLX Whisper 仅支持 Apple Silicon Mac，未来计划支持更多平台。

安装与配置指南

1. 克隆项目

git clone [repository-url]
cd handy-cli

2. 安装依赖

推荐使用 uv（Rust 编写的 Python 包管理器，速度快）：

uv pip install -r requirements.txt

所需依赖包：

openai              # 实际调用 OpenRouter 兼容接口
pynput              # 键盘/鼠标事件模拟
sounddevice         # 音频输入设备访问
mlx_whisper         # 苹果芯片上的 Whisper 推理
pyperclip           # 剪贴板读写
numpy               # 音频数据处理
python-dotenv       # 环境变量加载
pydantic            # 配置对象验证

3. 设置环境变量

创建 .env 文件，填入 OpenRouter API Key：

OPENROUTER_API_KEY=your_openrouter_api_key

💡 获取方式：前往 OpenRouter 官网 注册账号，生成 API 密钥

使用方法

启动主程序：

uv run handy.py

后台服务启动后，即可随时使用上述快捷键触发对应功能。

⚠️ 注意事项：

• 首次运行需授权麦克风权限
• macOS 用户需在“系统设置 > 隐私与安全性 > 辅助功能”中允许该脚本控制电脑
• 当前版本主要适配 macOS（Apple Silicon），其他平台正在适配中

当前限制与未来规划

已知限制

• 平台限制：MLX Whisper 目前仅支持 Apple Silicon Mac（M1/M2/M3）
• 网络依赖：AI 功能需联网调用 OpenRouter，无法完全离线
• 命令识别精度：部分口音或背景噪音可能影响识别效果

后续优化方向

• 支持本地大模型推理（如 Llama.cpp + whisper.cpp）
• 增加自定义命令配置文件（YAML 或 JSON）
• 引入语音唤醒词（如“Hey Handy”）
• 提供图形化设置界面

为什么选择 Handy CLI？

相比传统语音助手或商业工具，Handy CLI 的优势在于：

• 高度可定制：你可以修改命令映射、更换 AI 模型、调整识别逻辑
• 贴近开发者习惯：无需脱离键盘，即可完成复杂操作
• 隐私可控：语音识别本地完成，敏感上下文不会上传至第三方
• 轻量高效：无 GUI，资源占用低，常驻后台几乎无感

它不是替代 IDE 或终端，而是成为你手指的延伸——让想法更快落地。