Voice Console：本地语音指令控制台 MCP 安全硬化说明

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

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

状态：local-tool · 语音控制将执行本机命令 · 仅在可信 MCP 宿主使用
威胁模型：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 加一层本地语音入口。

本地语音控制台：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`，仅本机监听，不暴露密钥

快速开始

# 安装依赖（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 退出。

工具	输入	说明
`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 子进程握手）

安全模型

检查顺序：空命令/注入字符（; && | > < $( 等）→ 黑名单 → 白名单 → 其余需确认
黑名单默认拒绝：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 等
未知命令默认需确认（fail-closed），不自动放行
执行默认超时 10s 防挂起；密钥一律走环境变量，绝不硬编码
Web UI 绑定 127.0.0.1，Host/Origin 校验防 CSRF/DNS-rebinding

测试

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 防护，但本地其他进程仍可访问。本工具可执行本机任意白名单命令，请在可信环境中使用。

生态

voiceconsole 是标准 MCP server（mcp>=2.0，stdio 传输），可作为 lumen（24/7 Agent Runtime，内置 MCP 注册与 L2 人工确认）的语音入口插件。相关：keyvault（LLM Key 本地加密管理）· 体系地图：https://anyuer678.github.io/yuer.dev/map