企业官网建设流程全解析

GooeyPi 是一款为 Pi、OMP 和 Prime Agent 打造的桌面工作区，它的语音功能（Voice）让你无需打字即可与 AI Agent 协作：既可以用语音听写（Dictation）把说话内容转成文字提示词，也可以打开实时语音伙伴（Realtime Orb），直接与 Agent 进行口语对话、搜索资料，甚至口头下达任务。本指南带你从零完成配置。

两种语音功能：听写 vs 实时语音

GooeyPi 内置两条独立的语音通道，用途不同：

两者共用「设置 → Voice」页面配置，各自独立工作。

语音听写：三步完成配置

第 1 步：打开语音设置

进入Settings → Voice，页面顶部是 Connections（密钥管理），下方是 Dictation（听写）与 Realtime orb 两个配置区块，对应源码 VoiceSettings.tsx。

第 2 步：选择听写服务商

Dictation 区块提供 6 种服务（定义见 voice-options.ts）：

• OpenAI · Live（推荐）：边说边出字，延迟最低
• OpenAI · Recorded：先录音、停止后整段转录
• Groq：基于 Whisper 的高速录音转录
• Deepgram：Nova 系列模型，支持医疗、会议等场景
• Self-hosted：连接你自己的 Parakeet / Whisper 等 OpenAI 兼容转录服务，可点击「Connect & test」用 0.1 秒静音片段实测链路
• Local · whisper.cpp：完全在本机运行，无需 API Key，只需填写whisper-cli可执行文件和 GGML 模型文件路径

第 3 步：添加密钥并开始说话

若选择了托管服务，在 Connections 区域点击Add key粘贴 API Key。密钥会用操作系统的可信存储（macOS Keychain、Windows DPAPI、Linux 桌面密钥环）加密保存，绝不明文回读。

配置完成后，在任意会话输入框点击麦克风按钮即可开始听写：点击停止并转录，或直接用「转写完即发送」按钮。单次录音上限为 4 分钟，听写的完整状态机实现见 useDictation.ts，按钮在 Composer.tsx。

💡 小贴士：录音时自动启用了回声消除、降噪和自动增益，安静环境下直接说「帮我修复这个报错……」即可。

实时语音伙伴：和 Agent 开口对话

实时语音伙伴（Realtime Orb）是 GooeyPi 的核心亮点：它是一个可拖拽的语音球体，使用 OpenAI 的实时模型进行双向语音会话。

如何打开语音伙伴

1. 在Settings → Voice的 Realtime orb 区块选择实时模型（推荐 GPT Realtime 2.1）与说话声音（Marin、Cedar 等 10 种音色任选）
2. 确认 OpenAI 密钥已连接
3. 在会话页点击顶栏的音频波形图标（TitleToolbar.tsx），或从桌面宠物处直接唤起

打开后语音伙伴会显示连接状态，并随对话实时切换：Listening → Listening to you → Thinking → Speaking，实现逻辑见 VoiceOrb.tsx。你可以拖动它到窗口任意位置，位置会被自动记住。

语音伙伴能做什么

它不只是聊天，还内置了 5 个受控工具，可以在对话中直接触发：

• search_web：口头让它搜索资料
• list_projects / list_models：查询你的项目和可用模型
• start_task：口头下达任务，Agent 会在当前选中的 harness（Pi / OMP / Prime）中立即创建会话并开始工作，任务卡片会实时显示在语音球下方
• get_local_context：自动附带时区、地区等上下文，让回答更贴合你的环境

安全方面：每个实时会话都锁定在打开时选定的 harness 上，切换 harness 会自动关闭语音球；麦克风权限仅授予应用主渲染进程且只允许音频（校验见 voice-permissions.ts）。

桌面宠物：带语音控制的小伙伴

GooeyPi 还内置了桌面宠物，其中也包含语音能力：

• Orb：流体语音球，随 Agent 工作状态变色
• GooeyPi：官方紫色吉祥物，正是下面这只

在Settings → Pets中开启「Show desktop pet」后，宠物会悬浮在工作区上方，Agent 忙碌时做出对应动画；开启语音伙伴后，它还会显示麦克风静音按钮和语音状态，让你不必回到窗口也能随时接管语音会话。设置页实现见 PetsSettings.tsx。

常见问题（FAQ）

Q：本地 whisper.cpp 听写需要 API Key 吗？不需要。只要填对whisper-cli和模型文件路径，音频完全在本机处理。

Q：Linux 上提示「密钥只在本次会话有效」？说明系统没有可用的桌面密钥环（如 GNOME Keyring 或 KWallet）。此时密钥仅保存在内存中，退出应用即清除；安装密钥环后即可持久加密保存。

Q：打开语音设置提示「Restart GooeyPi to finish enabling Voice」？说明应用窗口连接的是旧版桌面进程，完全退出（Cmd/Ctrl+Q）后重新打开即可。

小结

GooeyPi 的语音能力把「说话」变成了与 AI Agent 协作的一等公民。更多安全细节可参阅 security.md，项目整体介绍见 README.md。