🤖 HoloJarvis

你电脑上的中文语音管家 —— 喊一声「贾维斯」，动口就办事。

本地语音识别 · 任意大模型（中转站/DeepSeek/GPT…）· 工具调用 · 克隆音发声 · 钢铁侠风格全息桌宠

简体中文 · English

演示：喊「贾维斯」→ 聆听 → 思考 → 用克隆音回答，HUD 反应堆随状态变色

✨ 这是什么

HoloJarvis 是一个跑在 macOS / Windows 上的中文语音助手，灵感来自电影里钢铁侠的 AI 管家。 你对着电脑喊「贾维斯」，它就醒来听你说话、理解意图、调用工具把事办了，再用语音回答你—— 桌面上还浮着一块青色的全息控制台桌宠，实时显示时间、系统状态和对话字幕。

🪟 项目最初为 macOS 而生（原名 jarvis-mac），现已同一套代码跨平台支持 Windows： 底层差异（语音合成、截屏、剪贴板、媒体/音量、回收站、系统遥测等）按系统自动切换，集中在 jarvis/winops.py。

它的大脑接的是 OpenAI 兼容接口，所以你可以用自己的中转站接入任意模型 （DeepSeek、GPT、Claude……），按需切换；嗓音可选接入 GPT-SoVITS 克隆音，让它用你想要的声音说话。

💡 这是一个个人项目，面向喜欢折腾、想要一个「本地可控、越用越懂你」的桌面语音助手的玩家。

🌟 特性

• 🎙️ 本地语音识别 —— 用 faster-whisper 在本地转写，不上传你的声音。
• 🔑 拼音模糊唤醒 —— 喊「贾维斯」即可唤醒，识别成「家维斯/贾卫师」等同音也能命中；并做了噪音幻听过滤，防止电视声误唤醒。
• 🧠 任意大模型 —— 通过你的中转站（OpenAI 兼容）接入 DeepSeek / GPT / Claude 等，改一行配置即可换模型。
• 🧰 17 个内置工具 + MCP 扩展 —— 开应用、查天气、控制音乐、读屏幕、发微信、整理文件、设倒计时…… 还能通过 MCP 接入更多能力。
• 🗣️ 克隆音发声 —— 可选接入 GPT-SoVITS，用克隆嗓音朗读；服务没开时自动回退到系统 say。
• 🧬 长期记忆 —— 说「记住…」它就跨重启记住你的名字、偏好、习惯，越用越懂你。
• 🪟 全息桌宠 HUD —— 钢铁侠风格的青色控制台：弧形反应堆随状态变色、时钟天气、磁盘/电量/CPU 遥测、对话字幕、笔记栏。点反应堆即可说话。
• 🌀 3D 全息粒子控制台（--holo） —— 用 ./run.sh --holo 启动浏览器版形象：Three.js 万级粒子核心，摄像头手势控制（张手放大扩散、握拳聚拢、捏合切形态，球体/环体/DNA/星系/立方/头像六种形态），语音状态实时联动变色脉动、对话字幕、系统遥测。识别用 MediaPipe 本地模型，运行不依赖外网。
• 🔒 本地可控 —— 识别、桌宠、记忆都在本地；大模型走你自己的中转站，密钥配置全部留在本机、不进仓库。

🧱 架构

flowchart LR
    Mic[🎙️ 麦克风] --> VAD[分句/静音检测]
    VAD --> ASR[faster-whisper 本地识别]
    ASR --> Wake{拼音唤醒?}
    Wake -- 否 --> Mic
    Wake -- 是 --> Brain[🧠 大脑]
    Brain <--> LLM[(中转站<br/>OpenAI 兼容)]
    Brain <--> Tools[🧰 本地工具 + MCP]
    Brain --> Mem[(长期记忆)]
    Brain --> TTS[🗣️ GPT-SoVITS / 系统嗓音]
    TTS --> Speaker[🔊 朗读]
    Brain -.状态/字幕.-> Pet[🪟 桌宠 HUD]

🚀 快速开始

需要 Python 3.12（macOS 或 Windows 均可）。首次运行会下载 Whisper 模型，请耐心等待。

# 1) 克隆
git clone https://github.com/wqq64842-commits/holojarvis.git
cd holojarvis

# 2) 建虚拟环境并装依赖
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3) 配置中转站（OpenAI 兼容网关）
cp base_url.txt.example base_url.txt   # 填你的中转站地址，如 https://xxx/v1
cp api_key.txt.example  api_key.txt    # 填你的 API Key
cp model.txt.example    model.txt      # 选模型，如 deepseek-chat

# 4) 启动（带桌宠）
./run.sh
# 或纯命令行：./run.sh --no-pet

⚠️ 首次运行 macOS 会弹窗申请麦克风权限；部分工具（截屏/读屏/发微信）还需要在 「系统设置 → 隐私与安全性」里授予屏幕录制、辅助功能权限。

支持 Windows 10/11 64 位。首次安装依赖和首次下载 Whisper 模型都需要联网。

1. 安装 Python 3.12

1. 打开 Python Windows 下载页面，下载 Python 3.12 的 Windows installer (64-bit)。
2. 运行安装程序，务必勾选 Add python.exe to PATH，然后点击 Install Now。
3. 安装完成后打开 PowerShell，检查版本：

py -3.12 --version

正常情况下会显示 Python 3.12.x。如果提示找不到 py，请重新安装 Python 3.12，并确认勾选了 Add python.exe to PATH。

2. 下载 HoloJarvis

不熟悉 Git 的用户：

1. 点击仓库页面右上方绿色的 Code 按钮；
2. 选择 Download ZIP；
3. 解压到简单路径，例如 C:\HoloJarvis。

熟悉 Git 的用户也可以执行：

git clone https://github.com/wqq64842-commits/holojarvis.git
cd holojarvis

3. 在项目目录打开 PowerShell

进入解压后的 HoloJarvis 文件夹，在文件夹空白处点击鼠标右键，选择 在终端中打开。也可以手动进入目录：

cd C:\HoloJarvis

4. 创建独立环境并安装依赖

下面的命令不需要激活虚拟环境，因此不会遇到 PowerShell 脚本执行策略问题：

# 创建 Python 虚拟环境
py -3.12 -m venv .venv

# 更新 pip
.\.venv\Scripts\python.exe -m pip install --upgrade pip setuptools wheel

# 安装 HoloJarvis 依赖（可能需要几分钟）
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

5. 创建并填写模型配置

复制示例配置：

Copy-Item base_url.txt.example base_url.txt
Copy-Item api_key.txt.example api_key.txt
Copy-Item model.txt.example model.txt

用记事本逐个打开：

notepad base_url.txt
notepad api_key.txt
notepad model.txt

每个文件只填写一行，不要加引号：

🔒 API Key 属于私密信息。不要截图、发给别人或提交到 GitHub；这些本地配置已经加入 .gitignore。

6. 测试模型连接

.\.venv\Scripts\python.exe test_llm.py

如果终端显示模型回复，说明地址、API Key 和模型名称配置正确。如果出现 401，通常是 API Key 错误； 如果出现 404，请检查接口地址是否需要 /v1，以及模型名称是否正确。

7. 启动 HoloJarvis

# 桌面 HUD 模式
.\run.bat

# 3D 全息浏览器模式
.\run.bat --holo

# 纯命令行模式
.\run.bat --no-pet

首次启动会自动下载 Whisper 语音识别模型，可能需要几分钟。下载期间请保持网络连接，不要关闭窗口。

8. 开启麦克风权限

打开 Windows 设置 → 隐私和安全性 → 麦克风，确保以下开关已经开启：

• 麦克风访问权限；
• 允许应用访问麦克风；
• 允许桌面应用访问麦克风。

系统朗读使用 Windows 内置 SAPI。如果能识别你的声音但没有语音回复，请检查系统扬声器是否静音， 并前往 设置 → 时间和语言 → 语音 安装中文语音。

常见问题

依赖安装失败

先重新升级安装工具，再安装依赖：

.\.venv\Scripts\python.exe -m pip install --upgrade pip setuptools wheel
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Whisper 模型下载失败

• 检查网络连接后重新运行，已经下载的缓存通常可以继续使用；
• 如果使用代理，请检查代理地址和端口是否合法；
• 下载阶段不要关闭 PowerShell 窗口。

更新 HoloJarvis

Git 用户可以执行：

git pull
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

使用 ZIP 的用户可以下载新版 ZIP，并把自己的 base_url.txt、api_key.txt、model.txt、 memory.json 和 notes.txt 复制到新目录。发微信功能依赖已登录的微信客户端，并通过界面自动化完成操作。

启动后喊一声「贾维斯」，或用鼠标点一下桌宠中央的反应堆，就能开始对话。

🗣️（可选）接入克隆音

默认用系统中文音 say 发声，零配置即可用。想要克隆嗓音：

1. 按 GPT-SoVITS 文档部署，启动它的 api_v2，监听 127.0.0.1:9880；
2. 准备一段参考音频（几秒你想要的嗓音），设置环境变量：

   export JARVIS_TTS=gptsovits
   export GPTSOVITS_REF=/绝对路径/你的参考音频.wav
   export GPTSOVITS_PROMPT="参考音频里说的那句话"
   

3. 重新 ./run.sh。连不上 9880 时会自动回退到 say，不影响使用。

💡 Apple 芯片可把 GPT-SoVITS 的 device 设为 mps 用 GPU 加速，合成快 2~3 倍。

⚙️ 配置说明

所有敏感配置都放在项目根目录的几个文本文件里（已被 .gitignore 排除，不会进仓库）：

也支持用环境变量覆盖（优先级更高）：JARVIS_BASE_URL、JARVIS_API_KEY、JARVIS_MODEL、 JARVIS_TTS、JARVIS_VOICE、JARVIS_WHISPER 等，详见 jarvis/config.py。

🔧 换模型：改 model.txt 一行，重启即可。建议选支持工具调用的模型， 否则开应用/读屏幕/记忆等能力会失效。

🧰 内置工具

🔌 MCP 扩展

编辑 mcp.json 即可接入 MCP 服务器（文件系统、浏览器自动化、网页抓取等）， 仓库内已带文件系统示例。MCP 工具会和内置工具一起交给大模型自由调用。

🗺️ 路线图

• Windows 支持（同一套代码跨平台）
• 开机自启（macOS launchd / Windows 计划任务）
• 桌宠点击穿透 / 可调透明度
• 更多内置工具（日历、提醒事项、邮件）
• 真实麦克风电平驱动波形

欢迎 Issue / PR 一起折腾，详见 贡献指南。

🙏 致谢

• GPT-SoVITS —— 少样本克隆音
• faster-whisper —— 本地语音识别
• Model Context Protocol —— 工具扩展协议
• skyfireitdiy/Jarvis —— 同名项目，README 形态参考

📄 License

MIT © 2026 wang64862