Voice Console —— 语音指令控制台 MCP

对着电脑说一句「打开桌面」或「执行 dir」，它就执行并播报结果——给 MCP / CLI 加一层本地语音入口。

Python License: GPL v3 Tests MCP

本地语音控制台：STT 识别 → 意图解析 → 安全门 → 工具执行 → TTS 播报。以 MCP Server 形态提供 5 个工具，可被任意 MCP 客户端调用。

功能特性

能力	说明
MCP Server	标准 stdio 传输，5 个工具（`run_cli` / `find_file` / `open_folder` / `speak` / `confirm`）
本地语音链路	faster-whisper 本地 STT（无 key 可用）+ edge-tts 播报（自动降级系统 TTS）
安全门	黑/白名单 + 注入字符拦截 + 二阶段语音确认（30s 超时自动拒绝）
三种入口	热键语音循环 / `--text` 文本模式 / Web 控制台
零依赖 Web UI	标准库 `http.server`，仅本机监听，不暴露密钥

快速开始

# 安装依赖（mcp / faster-whisper / edge-tts / keyboard / sounddevice ...）
pip install -r requirements.txt

# 方式 1：作为 MCP Server（任意 MCP 客户端 stdio 调用）
python -m voiceconsole

# 方式 2：本地热键语音循环（Windows 需管理员运行）
python main.py

# 方式 3：免麦克风/免管理员：交互文本模式
python main.py --text

# 方式 4：本地 Web 控制台（浏览器打开 http://127.0.0.1:8765）
python -m voiceconsole.webui --port 8765

热键：Ctrl+Shift+Space 开始/停止录音 · Ctrl+Shift+Q 退出。

MCP 工具清单

工具	输入	说明
`run_cli`	`command`, `cwd?`	白名单执行；危险命令抛错，其余需语音确认
`find_file`	`pattern`, `directory="."`	按文件名模糊搜索
`open_folder`	`path`	系统文件管理器打开
`speak`	`text`	TTS 播报
`confirm`	`prompt`	发起并等待语音确认，超时默认拒绝

项目结构

main.py               热键监听 + 全局循环
voiceconsole/
  __init__.py         MCP server 入口（register + run）
  __main__.py         python -m voiceconsole（stdio）
  mcp_server.py       MCP SDK 工具注册与执行编排
  safety.py           安全门：黑白名单 + 确认状态机（线程安全）
  actions.py          真实执行体（全项目唯一 subprocess 处）
  intent.py           规则意图解析 + 工具映射
  stt.py / tts.py     STT / TTS 引擎封装（含降级）
  webui.py            本地 Web 控制台（零依赖）
tests/                pytest 测试（71 例，含真实 stdio 子进程握手）

安全模型

检查顺序：空命令/注入字符（; && | > < $( 等）→ 黑名单 → 白名单 → 其余需确认
黑名单默认拒绝：rm sudo curl wget dd mkfs mv del shutdown bash passwd net user 等
白名单默认放行：ls cd cat pwd dir git status git log ping ps top 等
执行默认超时 10s 防挂起；密钥一律走环境变量，绝不硬编码

测试

python -m pytest tests/ -v

隐私与免责

语音与控制指令仅在本机处理；STT 使用本地模型或你配置的在线 API，TTS 使用本地/在线引擎。
工具可执行本机命令，请自行评估风险；确认门默认开启，危险操作需语音二次确认。
演示请运行 python demo.py（免麦克风，覆盖打开桌面/找文件/危险命令拒绝/退出全链路）。

本项目仅供学习交流与演示用途，不构成任何形式的商业服务或技术承诺。软件按「现状」提供，不作任何明示或暗示的保证，包括但不限于适销性、特定用途适用性与非侵权性。您理解并同意：使用本项目即表示您自行承担全部风险。如您在使用过程中发现缺陷或问题，欢迎通过 GitHub Issues 反馈，但作者不因使用本软件所直接或间接产生的任何损失（包括但不限于数据丢失、业务中断、第三方索赔）承担责任。本项目以功能演示与学习交流为主要目的，其架构设计、安全基线、容错机制与性能表现均未按生产级标准进行验证与加固，不适用于实际生产环境或关键业务场景。任何将本项目部署于生产系统、对外提供服务、或将其接入真实业务工作流的做法，均属使用者的自主决策行为；由此产生的任何直接或间接不良后果，包括但不限于服务中断、数据损坏或泄露、业务损失、合规风险、以及因依赖本软件而引发的第三方纠纷，开发者均不承担任何责任。若您确有生产级使用需求，请在充分评估与自行加固（包括但不限于安全审计、压力测试、代码审查）后，自行承担相应风险。