mc-skills/catalog

Fork 0

mc-skills 52efc07510 catalog: 更新 2026-04-07 11:44

2026-04-07 11:44:56 +08:00

4.7 KiB

Raw Blame History

AI语音交互命令行工具

AI代理 语音交互 CLI工具 OpenAI 实时API Node.js

Agent Voice

免提 AI 代理。agent-voice 是一个命令行工具，让 AI 代理能够通过 OpenAI Realtime API（或任何兼容提供商）与人类进行语音交互。

两个基本原语：say（向用户说话）和 ask（说话后等待回应）。就这么简单。

agent-voice say -m "正在部署到生产环境。"
agent-voice ask -m "应该用 Postgres 还是 SQLite？"
# → 用户说话 → "Postgres"

Agent Skill

Agent Voice 以 Agent Skill 形式发布，适用于 AI 编程代理。

npx skills add adriancooney/agent-voice

/voice 技能可启动免提语音对话。代理用 say 说话，用 ask 监听——无需屏幕。

安装

npm install -g agent-voice

配置

Agent Voice 需要一个兼容 OpenAI 的 Realtime API 密钥。运行认证向导：

agent-voice auth

凭据保存至 ~/.agent-voice/config.json（权限 0600）。也可设置 OPENAI_API_KEY 环境变量——CLI 同时检查两者，优先使用配置文件。

任何兼容 OpenAI 的 Realtime API 均可使用——在 agent-voice auth 时提供自定义 base URL 即可。

CLI

`say`

播放一条消息。无需麦克风，无需回应——即发即忘。

agent-voice say -m "构建完成，无错误。"

参数	默认值	说明
`-m, --message`	—	要播放的文本（或通过 stdin 传入）
`--voice`	`ash`	使用的语音
`--no-daemon`	—	跳过守护进程，直接运行

`ask`

播放一条消息，然后监听用户的语音回应。将转录结果输出到 stdout。

agent-voice ask -m "这个组件应该叫什么名字？"
# stdout: SearchBar

参数	默认值	说明
`-m, --message`	—	要播放的文本（或通过 stdin 传入）
`--voice`	`ash`	使用的语音
`--timeout`	`120`	等待语音的秒数
`--ack`	`false`	用户回应后播放简短确认语
`--no-daemon`	—	跳过守护进程，直接运行

`voices`

agent-voice voices           # 列出所有语音
agent-voice voices set coral # 设置默认语音

`config`

agent-voice config get              # 显示所有配置
agent-voice config set debug true   # 设置某个值
agent-voice config reset            # 重置为默认值（保留认证信息）

`daemon`

agent-voice daemon start    # 启动（已运行则无操作）
agent-voice daemon stop     # 优雅停止
agent-voice daemon restart  # 停止后重启
agent-voice daemon status   # 显示 PID、运行时长、命令数量
agent-voice daemon logs -f  # 实时跟踪事件日志

守护进程

后台进程，在命令之间保持音频引擎预热状态，降低启动延迟。首次执行 say/ask 时自动启动——无需手动配置。

监听 Unix socket：~/.agent-voice/daemon.sock
串行执行命令（音频硬件为单消费者模式）
空闲 30 分钟后自动退出（可配置）
守护进程无法启动时回退为直接执行

调试日志

agent-voice config set debug true        # NDJSON 事件追踪
agent-voice config set debug.audio true  # 同时捕获 WAV 文件

启用后，所有命令将结构化追踪写入 ~/.agent-voice/logs/events.ndjson，WAV 捕获（助手、麦克风、模型输入）写入 ~/.agent-voice/logs/audio/。音频文件使用环形缓冲区——保留最近 50 条命令，最旧的自动删除。

agent-voice daemon logs -f       # 实时跟踪
agent-voice daemon logs -n 100   # 最近 100 条

Node.js API

npm install agent-voice

import { say, ask } from "agent-voice";

await say("部署完成。");

const answer = await ask("应该用哪个数据库？");
// → "Postgres"

完整 API 参考包含音频回调和追踪事件等选项。

工作原理

Agent Voice 通过 WebSocket 连接到 OpenAI Realtime API。文本作为对话条目发送，由模型朗读。ask 模式下，消息播放完毕后麦克风打开，音频流式传输到 API，使用 gpt-4o-transcribe 结合语义 VAD 进行转录，判断用户何时停止说话。

音频格式为 24kHz 单声道 PCM16，通过内置声学回声消除（AEC）的 Rust 音频引擎处理，防止助手听到自身的播放声。

软件包

软件包	说明
`agent-voice`	CLI、Node.js API、守护进程、调试日志
`agent-voice-audio`	带 AEC 的 Rust 音频引擎

许可证

MIT

4.7 KiB Raw Blame History Unescape Escape