# ofish

**Repository Path**: whillhill/ofish

## Basic Information

- **Project Name**: ofish
- **Description**: mini机器人
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-02-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

minibot
======

一个通过 CLI 交互启动的轻量转发层：

- 输入：文本；语音（WebRTC VAD 切句 + 官方 ASR HTTP）
- 处理：`POST /process-pipeline`（SSE 流式响应）
- 输出：控制台打印；可选 macOS `say` 或官方 TTS HTTP 播报
- 语音链路：麦克风 → WebRTC VAD 切句 → 官方 ASR HTTP → 文本 → `/process-pipeline` → TTS

目录结构（微服务风格骨架）
------------------------

```
minibot/
  cli/                  # CLI 入口与交互逻辑
  clients/              # 外部服务客户端（Pipeline/ASR）
  config/               # 配置读取
  core/                 # 领域基础能力（错误、SSE 解析等）
  tts/                  # 播报输出
  audio/                # 音频输入（预留）
config/
  .env.example          # 环境变量模板
.env                    # 本地开发环境变量（已加入 .gitignore）
```

快速开始
--------

1) 安装依赖（使用 uv）

```bash
uv sync
```

2) 运行交互模式（文本 / 语音）

```bash
uv run minibot run
```

3) 文本：在提示符输入内容，即发送 `type=text` 请求到 `MINIBOT_PIPELINE_URL` 并打印 SSE 输出。
4) 语音：启动时加 `--audio` 或交互命令 `/audio on`，使用 WebRTC VAD 自动分句并走同一处理链路。

可选：启用 macOS TTS

```bash
MINIBOT_TTS_ENGINE=say uv run minibot run
```

或：

```bash
uv run minibot run --tts say
```

拾音 / VAD
-----------
- 开启：`uv run minibot run --audio` 或在 CLI 输入 `/audio on`
- 关闭：`/audio off`
- VAD：WebRTC VAD，16k 单声道，20ms 帧，默认敏感度 2，句尾静音 600ms 触发分句。

配置
----

默认从项目根目录 `.env` 读取（变量前缀 `MINIBOT_`）：

- `MINIBOT_PIPELINE_URL`：例如 `http://115.190.220.103:8077/process-pipeline`
- `ASR_API_KEY`：官方 ASR Bearer Token
- `ASR_API_URL`：默认 `https://open.bigmodel.cn/api/paas/v4/audio/transcriptions`
- `TTS_API_KEY`：官方 TTS Bearer Token（不填则回退使用 ASR_API_KEY）
- `TTS_API_URL`：默认 `https://open.bigmodel.cn/api/paas/v4/audio/speech`
- `MINIBOT_TTS_ENGINE`：`none` | `say` | `official`（官方 TTS 推荐设置为 `official`）
- `MINIBOT_TTS_VOICE`：默认 `tongtong`
- `MINIBOT_TTS_SPEED` / `MINIBOT_TTS_VOLUME` / `MINIBOT_TTS_RESPONSE_FORMAT`
- `MINIBOT_TTS_SYNTH_WORKERS`：TTS 后台并行合成 worker 数量（默认 3）
- `MINIBOT_TTS_QUEUE_MAXSIZE`：TTS 播放队列最大长度（默认 20）
- `MINIBOT_TTS_QUEUE_OVERFLOW_STRATEGY`：队列满时策略，`drop_oldest` | `drop_newest`（默认 `drop_oldest`）
- `MINIBOT_TTS_EMIT_MODE`：`stream`（分段播报）| `end`（等待回复结束后整段播报，默认 `end`）
- `MINIBOT_TTS_KEEPALIVE_ENABLED`：是否开启静音保活流（默认 `true`）
- `MINIBOT_TTS_KEEPALIVE_INTERVAL_MS`：静音保活写入间隔毫秒（默认 `300`）
- `MINIBOT_TTS_KEEPALIVE_CHUNK_MS`：每次静音写入时长毫秒（默认 `40`）
- `MINIBOT_AUDIO_INPUT_DEVICE`：麦克风设备索引（None=系统默认，运行 `uv run python test_audio_devices.py` 查看）
- `MINIBOT_AUDIO_OUTPUT_DEVICE`：喇叭设备索引（None=系统默认）
- `MINIBOT_AUDIO_SAMPLE_RATE`：目标采样率（默认 16000 Hz，如设备不支持会自动重采样）
- `MINIBOT_AUDIO_MUTE_DURING_PLAYBACK`：是否在 TTS 播放时暂停拾音（默认 true，避免播报被 ASR 误识别）
- `MINIBOT_WAKE_ENABLED`：是否启用唤醒词门控
- `MINIBOT_WAKE_WORDS`：唤醒词列表（逗号分隔），默认 `小鱼小鱼`
- `MINIBOT_WAKE_MODEL_PATH`：Vosk 模型目录
- `MINIBOT_WAKE_SESSION_IDLE_TIMEOUT_MS`：唤醒会话静默超时（毫秒，默认 5000）
- `MINIBOT_WAKE_DEBUG`：唤醒词调试模式（默认 False，设置为 True 显示详细识别日志）
- `MINIBOT_WAKE_REPLY_TEXT`：唤醒后播放的文本（默认“我在”，设置为空则不播放）
- `MINIBOT_USER_ID` / `MINIBOT_SESSION_ID`

音频设备测试
--------

运行测试脚本查看可用设备：

```bash
uv run python test_audio_devices.py
```

选择选项 1 查看设备列表，记下设备 ID，然后在 `.env` 中配置：

```bash
MINIBOT_AUDIO_INPUT_DEVICE=2  # 例如使用 ID=2 的麦克风
MINIBOT_AUDIO_OUTPUT_DEVICE=3  # 例如使用 ID=3 的喇叭
MINIBOT_AUDIO_SAMPLE_RATE=48000  # 如果设备不支持 16000 Hz，设置为设备支持的采样率
```
注意：
- 如果设备不支持 16000 Hz，系统会自动从硬件采样率重采样到 16000 Hz
- Vosk 唤醒词和 ASR 需要 16000 Hz，不建议修改 `MINIBOT_AUDIO_SAMPLE_RATE`
- 如果遇到 "Invalid sample rate" 错误，请运行测试脚本查看设备支持的采样率
唤醒词排查
--------
如果唤醒词未命中，按以下步骤排查：
1. **开启调试模式**
   ```bash
   MINIBOT_WAKE_DEBUG=true uv run minibot run --audio
   ```
   会显示：
   - Vosk 识别的原始文本（Partial/Final）
   - 归一化后的文本
   - 匹配过程
2. **检查唤醒词设置**
   - 启动时会显示：`[WAKE] 唤醒词: xxx` 和 `[WAKE] 归一化后: xxx`
   - 确认归一化后的唤醒词是否正确
3. **常见问题**
   - **模型词汇表缺失**：如 `WARNING: Ignoring word missing in vocabulary`
     - 解决：更换为模型支持的唤醒词（如“你好”、“小鱼”）
     - 或下载完整版 Vosk 中文模型（vosk-model-cn-0.22，1.3GB）
   - **音量过低**：运行 `uv run python test_audio_devices.py` 选项 6 监控音量
   - **采样率不匹配**：确认 `MINIBOT_AUDIO_SAMPLE_RATE=16000`（系统会自动重采样）
注意：
- 如果设备不支持 16000 Hz，系统会自动从硬件采样率重采样到 16000 Hz
- Vosk 唤醒词和 ASR 需要 16000 Hz，不建议修改 `MINIBOT_AUDIO_SAMPLE_RATE`
- 如果遇到 "Invalid sample rate" 错误，请运行测试脚本查看设备支持的采样率
MINIBOT_AUDIO_INPUT_DEVICE=2  # 例如使用 ID=2 的麦克风
MINIBOT_AUDIO_OUTPUT_DEVICE=3  # 例如使用 ID=3 的喇叭
```