第3课：语音助手#

为什么需要这个#

想象一下：你去倒杯咖啡，你的AI代理正在电脑上工作。它请求编辑文件的权限。你不用掏出手机打字，只需说：“好的，批准”。或者用语音口述新任务。

HAPI的语音助手能让你通过ElevenLabs Conversational AI技术用语音控制AI代理。

语音助手能做什么#

🎤 与代理对话 ——用语音分配任务、提问
✅ 语音审批操作 ——说"是"或"否"代替按按钮
📢 播报结果 ——助手会告诉你任务完成或出错

准备工作#

在 ElevenLabs 上拥有API访问权限的账号
通过互联网可访问的Hub（例如使用 --relay）

ElevenLabs 是一家开发语音合成和识别技术的公司。他们的服务将你的语音转为文字，并将文字转为自然发音的语音。

API（Application Programming Interface）是程序之间通信的方式。API密钥就像密码，确认你有权访问该服务。

分步配置#

第1步：获取ElevenLabs API密钥#

访问 elevenlabs.io 注册（或登录）
前往设置：API Keys
点击 Create API Key（创建API密钥）
复制密钥——下一步需要用到

⚠️ 保管好API密钥！这就像密码——如果被他人知道，他们可以使用你的账号。

第2步：配置Hub#

启动Hub之前设置环境变量：

export ELEVENLABS_API_KEY="你的api密钥"
hapi hub --relay

环境变量 是启动前传递给程序的设置。export 命令将其保存在当前终端会话期间。

首次启动时Hub会自动创建“Hapi Voice Assistant"语音代理到你的ElevenLabs账号中。无需额外配置！

第3步：开始语音会话#

在Web App中打开一个会话（手机浏览器）
点击屏幕底部（消息输入区域）的麦克风按钮 🎤
浏览器请求时允许麦克风访问
开始说话！

语音命令#

你不需要记住特殊命令——自然说话即可：

说什么	会发生什么
“让Claude重构授权模块”	你的请求被传递给AI代理
“创建一个新的测试文件”	创建文件的请求
“是”/“批准”/“好的”	批准等待中的权限
“不”/“拒绝”/“取消”	拒绝权限
“代理现在在做什么？”	助手会自行回答（如果能）

内部工作原理#

语音通信经过几个阶段：

你的声音 → 麦克风 → 浏览器 → WebRTC → ElevenLabs → 文字
                                                          │
                                                     Hub → CLI → AI代理
                                                          │
代理回复 ← 语音 ← ElevenLabs ← 文字 ←──────────────────────┘

WebRTC（Web Real-Time Communication）是通过浏览器实时传输音频和视频的技术。这与视频通话使用的技术相同。

自动上下文同步#

语音助手自动"了解"正在发生的事情：

当你打开会话——整个历史会被加载
当代理发送消息——助手收到更新
当收到权限请求——助手可以告诉你
当任务完成——助手会通知

你不需要问"有什么新消息”——助手会主动告诉你重要的变化。

实用建议#

说话要具体 ——请求越精确，结果越好。不要说"对代码做点什么"，而要说"在login函数中添加错误处理"
等待完成 ——代理工作时，助手保持安静。任务完成后，它会主动告诉你结果
使用耳机 ——这会减少回声，提高语音识别质量
一次一个会话 ——为了最清晰的上下文，一次只操作一个会话

高级配置（可选）#

如果你想使用自定义ElevenLabs代理（例如不同的语音或设置）：

export ELEVENLABS_AGENT_ID="你的代理id"

如果你在ElevenLabs网站上配置了具有特殊语音或指令的代理，这会很有用。

问题排查#

问题	解决方案
“ElevenLabs API key not configured”	确保设置了 `ELEVENLABS_API_KEY` 变量并重启Hub
麦克风不工作	检查浏览器权限，确保麦克风未被其他程序占用
助手不回应	检查会话连接（状态栏中的绿点）
音质差	使用耳机，减少背景噪音
“Failed to create ElevenLabs agent”	检查API密钥和ElevenLabs账号配额

课程总结#

语音助手让你可以用语音控制AI代理——无需键盘
工作需要 ElevenLabs API密钥 和可通过互联网访问的Hub
配置只需5分钟：获取密钥→设置变量→启动Hub
用自然语言说话——没有特殊命令
助手自动跟踪更新并报告重要事件