# AI语音交互命令行工具

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

# Agent Voice

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

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

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

## Agent Skill

Agent Voice 以 [Agent Skill](https://skills.sh/adriancooney/agent-voice) 形式发布，适用于 AI 编程代理。

```bash
npx skills add adriancooney/agent-voice
```

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

## 安装

```bash
npm install -g agent-voice
```

## 配置

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

```bash
agent-voice auth
```

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

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

## CLI

### `say`

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

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

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

### `ask`

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

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

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

### `voices`

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

### `config`

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

### `daemon`

```bash
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 分钟后自动退出（可配置）
- 守护进程无法启动时回退为直接执行

## 调试日志

```bash
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 条命令，最旧的自动删除。

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

## Node.js API

```bash
npm install agent-voice
```

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

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

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

完整 [API 参考](./packages/agent-voice/README.md#nodejs-api) 包含音频回调和追踪事件等选项。

## 工作原理

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

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

## 软件包

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

## 许可证

MIT