幽浮

Windows 桌面悬浮语音助手。按住说话，松开发送，听它回你。

中文 · English

截图 · 功能 · 快速开始 · 配置 · 音频输入 · 构建 · 诊断

Note

幽浮是本地 Windows 桌面应用，不是网页应用。web/ 只是保留的本地调试入口。

截图

功能

模块	说明
悬浮球	常驻桌面，支持拖拽、右键菜单、开机启动、透明度、边缘吸附和皮肤系统。
语音输入	按住快捷键录麦克风，松开发送；也可以取消当前录音。
桌面音频	可单独录制系统声音，适合让模型理解视频、会议或播放器内容。
多模态输入	Gemini 格式网关可以直接接收音频和截图；录音时也能附加桌面截图。
模型网关	支持 Gemini 和 OpenAI 兼容格式。
语音输出	可选 ElevenLabs 或 MiMo V2.5 TTS 生成回复语音，并在桌面播放。
对话气泡	漫画式对话框，支持流式文本、展开、滚动和用户转写展示。
人格约束	通过 prompts/persona.md 控制说话风格。
会话记忆	保留近期上下文，长上下文会自动摘要，避免无限增长。
诊断日志	可记录每轮音频、转写、模型回复和语音输出，方便排查误触和幻觉。

回到顶部

工作流

麦克风 / 桌面音频 / 截图
-> 模型网关理解输入
-> 人格约束 + 会话上下文
-> 结构化返回 user_text 和 assistant_text
-> TTS 服务生成语音
-> 悬浮球播放语音并显示流式文本

使用 Gemini 格式时，音频和图片会直接发给模型。模型会返回：

{
  "user_text": "用户说了什么，或 [no speech]",
  "assistant_text": "助手回复"
}

user_text 是模型根据音频理解出来的用户内容，用于展示、诊断和写入会话记忆。它不是固定的本地转写结果，所以如果短录音里只有噪声，可以通过诊断日志定位是录音问题还是模型幻觉。

回到顶部

音频输入兼容性

幽浮不是所有网关格式都用同一种音频协议。实际行为如下：

网关格式	音频处理方式	截图处理方式	当前状态
Gemini	以 inline_data 直接把音频发给模型。	以 inline_data 直接附加图片。	推荐使用，体验最完整。
OpenAI 兼容	以 Chat Completions 消息内容里的 input_audio 发送 base64 音频。	以 image_url 的 data URL 附加图片。	不是先转文字，但要求你的网关和模型真的支持 input_audio。

所以，OpenAI 兼容格式和 Gemini 一样都是“直接把音频交给模型理解”的设计，但协议字段不一样，兼容性取决于你接入的网关是否实现了这套 OpenAI 音频输入格式。

回到顶部

快速开始

安装依赖：

python -m pip install -r requirements.txt

启动桌面悬浮球：

.\run_desktop.ps1

也可以直接运行入口文件：

python .\desktop_orb.py

首次启动后，在悬浮球右键菜单里打开设置，填入模型网关和 TTS 配置。TTS 可选 ElevenLabs 或 MiMo V2.5。

快捷键

操作	默认按键
麦克风长按说话	鼠标侧键二
桌面音频输入	Ctrl+3
录音中附加截图	Alt
取消当前录音	鼠标中键

所有键鼠触发项都在 设置 -> 快捷键 里单独配置，可以录制单键，也可以录制组合键。

回到顶部

配置

大多数配置都可以在悬浮球右键菜单的 设置 里修改；同样的内容会保存到这些文件里。

文件	用途
gemini_config.json	模型、网关地址、网关密钥、格式类型。
tts_config.json	TTS 提供方、ElevenLabs 配置、MiMo V2.5 配置和输出格式。
.env.example	本地环境变量示例。
desktop_config.json	悬浮球名称、皮肤、大小、透明度、吸附、提示气泡、快捷键。
session_config.json	会话记忆、摘要阈值、上下文长度。
prompts/persona.md	语音人格和回复风格。
skins/	皮肤元数据。
assets/skins/	皮肤状态图。

Important

不要把真实 API Key 提交到公开仓库。建议使用环境变量或设置窗口保存本地配置。

网关格式

格式	适合场景	说明
Gemini	原生音频和截图输入	当前推荐格式。
OpenAI 兼容	支持 input_audio 的统一网关	可直接发送音频，但要求模型和网关支持。

相关文档：

• Google Gemini API 文档
• ElevenLabs API 文档
• MiMo V2.5 TTS 文档
• PyInstaller 文档
• sounddevice 文档
• soundcard 项目
• pynput 文档

回到顶部

命令行

文字对话：

python .\voice_turn.py --text "你好，帮我总结一下今天的计划"

音频对话：

python .\voice_turn.py --audio .\input.wav

音频加截图：

python .\voice_turn.py --audio .\input.wav --image .\screenshot.png

桌面音频：

python .\voice_turn.py --audio .\desktop.wav --audio-source desktop

新会话：

python .\voice_turn.py --new-session

只生成语音：

python .\tts.py "你好，这是一次语音合成测试。" --out outputs\test.mp3

构建

构建 Windows 可执行文件：

.\build_exe.ps1

构建产物会生成在本地 release\幽浮\幽浮.exe。release/ 是生成目录，不会提交到仓库。

回到顶部

诊断

启用诊断日志后，每轮对话会写入：

logs/voice-turns.jsonl

查看最近记录：

python .\inspect_diagnostics.py --last 12

适合排查这些问题：

• 短按误触是否只录到了噪声。
• 桌面音频是否来自预期来源。
• 模型是否把静音或噪声幻觉成文字。
• user_text 是否和保存的音频一致。
• 语音输出是否完整返回。

项目结构

路径	作用
desktop_orb.py	桌面悬浮球主界面、右键菜单、设置窗口和状态切换。
voice_turn.py	完整的一轮语音对话流程。
gemini_brain.py	模型网关请求逻辑。
gemini_audio.py	音频和图片载荷处理。
tts.py	ElevenLabs 和 MiMo V2.5 语音合成。
hotkey_listener.py	键盘和鼠标快捷键监听。
inspect_diagnostics.py	诊断日志查看工具。
build_exe.ps1	打包脚本。
docs/images/	README 截图。

本地调试入口

桌面悬浮球是主界面。本地网页调试入口仍然保留：

.\run_web.ps1

http://127.0.0.1:8765

回到顶部

---

为 Windows 桌面上的即时语音交流而做。