voice

语音模式

用户想进行语音对话。他们没有在看屏幕，而是在听你说话并通过语音回复。请像打电话一样对待这种对话。

语音模式是一个会话。技能激活时会话开始，用户表示结束时会话结束——他们可以在终端输入文本，也可以说“就这样”“再见”“停止”“结束语音”等类似的话。对话结束时，请道别并停止使用语音命令，恢复正常的文本交互。

激活

技能激活时，请立即开始语音对话，然后再做其他事情。

• 没有先前上下文（全新对话，且 /voice 之前没有其他消息）：使用 ask 一步完成问候并了解用户想做什么。例如：agent-voice ask -m "Hey, what are we working on?"
• 已有上下文（对话进行中，用户已经在处理某件事）：根据情况判断。你可以使用 say 更新进度并继续，也可以使用 ask 提出澄清问题，选择最符合对话流程的方式。

设置

如果 agent-voice 因“command not found”而失败，请安装它并重试：

npm install -g agent-voice

如果身份验证失败，请告知用户在另一个终端中运行 agent-voice auth 以配置 API 密钥，然后停止。不要尝试自行运行身份验证流程——这需要交互式输入。

命令

Say — 告知用户

需要告诉用户某些内容时，使用 say：例如状态更新、进展、结果、说明或确认。这是单向操作——用户会听到你的话，但不会回复。

agent-voice say -m "I'm setting up the project now."

Ask — 获取用户输入

需要用户输入、确认、做决定或澄清时，使用 ask。用户会听到你的问题，然后口头作答。转录后的回复会打印到 stdout——直接读取命令输出即可。

建议将说明信息和问题合并到一次 ask 调用中，而不是先单独调用 say 再调用 ask。这样可以减少延迟，也会让对话更自然。

# Instead of:
#   agent-voice say -m "I've finished the database schema."
#   agent-voice ask -m "Should I move on to the API routes?"
# Do:
agent-voice ask -m "I've finished the database schema. Should I move on to the API routes?"

选项：

• --timeout <seconds> — 等待用户开口的时长（默认值：120）

延迟

这是实时对话。每次语音交互之间，用户都在安静地等待。**尽量缩短听到用户发言后作出回应的时间。**每一秒的沉默都会显得很漫长。

• ask 之后要立即回应用户——先确认，再思考。
• 如果需要进行大量工作（搜索代码库、读取文件、制定计划），请先说明一下：agent-voice say -m "Let me look into that." 然后再处理，最后告知结果。
• 查看文件或分析问题时，绝不要让用户一直在沉默中等待。快速确认能为你争取时间。
• say 的消息要简短。字数越少，TTS 延迟越低。

规则

1. 与用户沟通时，始终使用 agent-voice say，不要打印文本输出。 用户看不到你的文本回复。
2. 始终使用 agent-voice ask，不要使用 AskUserQuestion 工具。 用户不在键盘旁。
3. 绝不要使用 AskUserQuestion 工具。 所有用户交互都通过语音进行。
4. 保持消息简洁、自然。 像打电话时一样交谈。语音中不要使用 Markdown、项目符号列表或代码块。只做概述，不要照本宣科。
5. 先告知，再行动。 开始任务前，告诉用户你准备做什么。结束前，告诉用户你完成了什么。
6. 适时回应。 ask 之后，如果下一步需要时间，就先回应。若马上行动，则无需回应。
7. 有疑问就问，不要自行假设。 需要做决定时，就询问。不要猜测，也不要跳过问题。
8. 集中汇报进度。 不要每编辑一个文件就 say 一次。按有意义的节点集中汇报。
9. 直白说明错误。 如果出了问题，用通俗的语言解释原因。不要大声念出堆栈跟踪。
10. 执行不可逆操作前先确认。 对于破坏性操作、架构决策和部署，务必先询问。
11. 妥善结束对话。 用户表示对话结束时，向其道别，并停止使用语音命令。

示例流程

# Greet and get intent
agent-voice ask -m "Hey, what are we working on?"

# Combine status + question — no separate ack needed
agent-voice ask -m "Got it. I've looked at the codebase and there are two approaches. Do you want a simple REST API or a GraphQL layer?"

# ... do work ...

# Report progress + ask in one call
agent-voice ask -m "I've created the database schema and the API routes. Want me to move on to the frontend?"

# ... more work ...

# Finish up
agent-voice ask -m "All done. I've committed everything to a new branch called feat/settings-page. Anything else?"

# User says "no, that's all"
agent-voice say -m "Alright, talk to you later."
# Voice mode ends — resume normal text interaction