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

[![Tests](https://github.com/anyuer678/voiceconsole/actions/workflows/test.yml/badge.svg)](https://github.com/anyuer678/voiceconsole/actions/workflows/test.yml)

# 安全硬化说明（合并入 README 顶部或「安全」章节）

> **状态**：`local-tool` · 语音控制将执行本机命令 · **仅在可信 MCP 宿主使用**  
> **威胁模型**：[docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)

### Sprint1 硬化

| 项 | 默认 |
|---|---|
| `confirm_authority` | `local-ui` — MCP **不能** `confirm(confirm_id)` 自批 |
| `path_roots` | null → 默认用户主目录 + 当前工作目录；越界拒绝 |
| 审计 | `~/.voiceconsole/audit.jsonl`（可用 `audit_path` / `VOICECONSOLE_AUDIT_PATH`） |
| TTS | 默认 `system`；`edge` 需 `tts_engine=edge` **且** `tts_allow_network=true`（会出网） |

迁移：若你依赖 MCP 自批，需在 `config.json` 显式设 `"confirm_authority": "mcp"`（不推荐）。


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

[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-80%20passed-brightgreen)](tests/)
[![MCP](https://img.shields.io/badge/MCP-Server-000000)](voiceconsole/)

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

> **安全边界说明**：本工具可执行本机命令（`subprocess.run` + `shell=False`）。安全门包含 40+ 拒绝前缀、shell 元字符拦截、空白规范化。Web UI 绑定 `127.0.0.1:8765`，内置 CSRF/DNS-rebinding 防护。命令分类采用默认拒绝策略（未知命令需确认）。请勿在不受信任的环境中运行。

## 功能特性

| 能力 | 说明 |
|---|---|
| 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`，仅本机监听，不暴露密钥 |

## 快速开始

```bash
# 安装依赖（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 测试（80 例，含真实 stdio 子进程握手）
```

## 安全模型

1. 检查顺序：空命令/注入字符（`; && | > < $(` 等）→ 黑名单 → 白名单 → 其余需确认
2. 黑名单默认拒绝：`rm sudo curl wget dd mkfs mv del shutdown bash passwd net user` 等
3. 白名单默认放行：`ls cd cat pwd dir git status git log ping ps top` 等
4. **未知命令默认需确认**（fail-closed），不自动放行
5. 执行默认超时 10s 防挂起；密钥一律走环境变量，绝不硬编码
6. Web UI 绑定 `127.0.0.1`，Host/Origin 校验防 CSRF/DNS-rebinding

## 测试

```bash
python -m pytest tests/ -v
```

## 隐私与免责

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

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

**安全声明**：本工具通过 `subprocess.run`（`shell=False`）执行命令，安全门包含 40+ 拒绝前缀和 shell 元字符拦截。命令分类采用默认拒绝策略（未知命令需确认后执行）。Web UI 绑定 `127.0.0.1` 并内置 CSRF/DNS-rebinding 防护，但本地其他进程仍可访问。本工具可执行本机任意白名单命令，请在可信环境中使用。

## License

[MIT License](LICENSE) — Copyright (c) 2026 anyuer678