> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Qoder Voice

Qoder Voice 是内置于 Qoder 的实时语音对话伙伴。你可以像语音聊天一样说出想法，与它一起探索思路、梳理方案，并直接用对话推进任务、操作软件和电脑。语音层负责对话与判断，真正的查阅、编辑、执行由后台 Agent 在同一条任务时间线里完成，全过程可听、可看、可回溯。

Qoder Voice 运行在 Quest 窗口中，编辑器窗口的 Chat 面板不提供实时语音。

## ​开始与结束

* **三个入口**：Quest 新建页的语音按钮、语音任务底部的「开始语音」、以及可自定义的快捷键（应用失焦时也能随时呼出）。
* **开口即建任务**：启动时自动创建一个语音任务，并沿用新建页「Start in」选择的工作区（本地 / SSH / WSL / Dev Container），因此任务会归到对应工作区分组；只有显式选择"无工作区"才进入 Chats。
* **连接期不丢话**：连接过程中输入框保持原样但暂不可编辑，此时说出的第一句话会被缓存，连接就绪后按顺序补发。
* **三种结束方式**：悬浮球控制条的关闭按钮、任务底部的停止、或直接说"结束通话"。结束语音不会停止已经在跑的后台工作；当语音与任务同时运行时，第一次点击只停语音，第二次才停任务。

## ​悬浮球

悬浮球是一个独立的透明浮窗，不嵌在 IDE 里，因此可以浮在任何应用之上，跟随所有普通桌面空间。

* **状态可读**：连接中、聆听、你在说、AI 播报、思考、静默、错误、收起，共八种状态；声纹起伏来自真实麦克风包络，AI 播报态严格跟随实际播放队列。
* **三种外观**：经典声纹（默认）、呼吸光球、胶囊，右键切换，按本机记忆。
* **贴附与自由摆放**：默认贴在当前语音任务输入框上方；拖动超过 4px 后变为自由位置，切换任务、窗口或应用后再回来仍保留该位置；重新打开所属任务或单击球体时回贴。
* **悬停控制条**：静音播放、关闭麦克风、结束语音三个按钮。静音只让播放静默，麦克风继续采集；关闭麦克风表示"我说完了"，会补齐句尾静音再释放采集。
* **单击回到现场**：单击球体立即前置 Quest 并打开它所属的语音任务，不会改变采集或静音状态。
* **静音时看字幕**：静音期间球体上方显示当前 AI 回答的实时字幕（最多三行）；右上角标签显示「连接中 / 正在处理 / 深度思考」。

## ​像聊天一样推进

* **说话即任务**：闲聊或当前上下文已能回答时直接口头回复；需要看代码、查资料、跑命令、操作 Quest 任务时，语音层会把一份完整请求交给后台 Agent 执行。用户明确要求独立、持久的后台工作时，才会另建一个 Quest 任务。
* **转写与执行分层展示**：你和 AI 的转写实时进入会话流，视觉上与普通消息一致；工具调用、思考过程与执行报告默认折叠在「Worked」区，展开即可查看细节。
* **随时插话**：你一开口，当前播报立即停止。普通补充会排到当前工作之后，并明确告诉你"已排队"；只有明确改口或要求"立刻停下"才会打断当前一轮，再执行新目标。已排队但尚未开始的工作可被新请求取消。
* **只说有效信息**：任务结果默认一到两句口语；显式要求调研、排查、对比时给出覆盖结论与关键发现的多句摘要；后台没有实质进展时保持沉默，不播报等待。
* **需要授权时**：底部显示待确认卡片，语音只中性提醒一次"去批准或拒绝"，不读取工具敏感细节。
* **文字也能用**：语音进行中，纯文字输入进入语音会话；带附件或 Slash Command 的输入仍按普通追问发送。

## ​屏幕上下文（Appshot，仅 macOS）

当你说"这个"、"这一页"、"我的屏幕"时，Qoder 可以读取前台应用窗口的图像与文本作为上下文。首次触发时 macOS 会请求辅助功能与屏幕录制权限。

该开关默认开启，可随时在语音设置中关闭。关闭后语音会明确拒绝屏幕访问，截图也不会写入会话（硬门禁，不只依赖提示词）；非 macOS 平台一律视为关闭。普通非语音任务不受该开关影响。

## ​设置项

在 Quest 窗口的「设置 → 语音 → 实时语音」中：

* **快捷键**：编辑触发实时语音的键位。入口不可用时会自动释放，避免继续占用其他应用的键位。
* **音色**：Anna / Lily。运行中的连接不会中途换音色，下一次连接生效。
* **语速**：慢 / 正常 / 快，修改后立即生效，只改变说话节奏，不改变内容与语言。
* **声纹识别**（默认关闭）：录制约 10 秒 16 kHz 单声道语音，在多人或嘈杂环境中优先识别你的声音。开启前需明确确认存储用途；关闭只停止使用、不删除已保存声纹；可随时重新录制覆盖或删除。
* **Appshot**：见上一节。

## ​历史与恢复

* 语音转写与执行历史都会持久化，重开任务时原样恢复，不会重播上一段连接未送达的完成播报。
* 恢复任务时会建立一段新的语音连接，但沿用同一份语音历史。
* 从语音任务 Fork 出的任务是普通 Agent Quest，不继承语音会话与语音专属能力。

## ​注意事项

* **窗口范围**：仅 Quest 窗口提供实时语音，相关设置也只在 Quest 窗口显示。
* **单路连接**：整个应用同一时间只允许一路实时语音连接，新连接会替换旧连接，旧窗口按"连接被替换"正常收尾。
* **启动失败只提示一次**：麦克风被拒绝、无设备、被其他应用占用、环境不支持或额度不足，都会给出对应提示并回到原页面，不会留下半开的语音状态。
* **不自动重连**：连接中断或超时后不保留待重连态，需要从任务底部重新开始语音。
* **保持全双工**：回声消除只消除模型自己的播报，播放期间麦克风不会关闭，可随时插话。
* **Linux**：原生 Wayland 会话不支持全局指针查询与程序化窗口移动，悬浮球交互能力受限。