verbalcoding 0.2.12 → 0.2.13

package/.env.example

@@ -8,6 +8,7 @@ DISCORD_CLIENT_ID=""
 DISCORD_ALLOWED_USERS=""
 AUTO_JOIN_VOICE_CHANNELS="일반,General,general"
 TRANSCRIPT_CHANNEL_ID=""
+VOICE_CONNECT_TIMEOUT_MS="60000"
 
 # Agent harness: hermes, claude-code, claude, codex, gemini, opencode, openclaw, aider, cursor, custom
 # `vc setup` auto-detects which agents are installed and lets you pick.
@@ -20,9 +21,9 @@ AGENT_TASK_TIMEOUT_MS="0"
 AGENT_CHAT_TIMEOUT_MS="45000"
 AGENT_VERBOSE_PROGRESS="0"   # default off; toggle in Discord with !verbose on/off
 
-# Streaming TTS pipeline: enables sentence-by-sentence playback while the agent is still writing.
-# First audio plays before the agent finishes. Default off; opt in once you've validated TTS latency.
-STREAMING_TTS="0"
+# Streaming TTS pipeline: sentence-by-sentence playback while the agent is still writing.
+# First audio plays before the agent finishes. Set to "0" to fall back to whole-reply playback.
+STREAMING_TTS="1"
 
 # Smart progress summarization. When SMART_PROGRESS_API_KEY is set, raw progress events get
 # folded into a single human sentence via a small LLM (Groq OpenAI-compatible API by default).
@@ -50,7 +51,7 @@ VOICE_LANGUAGE="ko"        # ko | en | auto; controls progress/status language
 WHISPER_CPP_LANGUAGE="ko"  # ko | en | auto; auto omits forced whisper language
 STT_LANGUAGE="ko"
 
-TTS_BACKEND="edge"   # edge | openvoice | speechswift | supertonic
+TTS_BACKEND="edge"   # edge | openvoice | speechswift | supertonic | omnivoice | qwen3tts | mlxaudio | fireredtts2 | mossttsnano | neuttsair
 EDGE_TTS_COMMAND="edge-tts"
 TTS_VOICE_TYPE="korean_female"  # edge: korean_male | korean_female | korean_multilingual_male | english_male | english_female
 TTS_VOICE="ko-KR-SunHiNeural"
@@ -92,6 +93,33 @@ OPENVOICE_LANGUAGE="KR"
 OPENVOICE_STYLE="default"
 OPENVOICE_TIMEOUT_MS="90000"
 OPENVOICE_PROGRESS="0"   # keep progress prompts fast via Edge unless set to 1
+
+# Optional k2-fsa/OmniVoice TTS backend (600+ language zero-shot TTS / voice cloning).
+# Recommended: create a separate env, install torch/torchaudio/soundfile/omnivoice, and keep progress prompts on Edge.
+OMNIVOICE_PYTHON="./.venv-omnivoice/bin/python"
+OMNIVOICE_MODEL="k2-fsa/OmniVoice"
+OMNIVOICE_DEVICE="mps"       # mps on Apple Silicon, cuda:0 on NVIDIA, cpu as fallback
+OMNIVOICE_DTYPE="float16"
+OMNIVOICE_REF_AUDIO="./voice-samples/user-reference.wav"
+OMNIVOICE_REF_TEXT=""        # optional transcript of the reference sample
+OMNIVOICE_LANGUAGE="ko"
+OMNIVOICE_SPEAKER=""         # optional voice-design attributes when no ref sample is desired
+OMNIVOICE_TIMEOUT_MS="180000"
+OMNIVOICE_PROGRESS="0"       # keep progress prompts fast via Edge unless set to 1
+
+# Optional Qwen3-TTS CLI backend via speech-swift `audio speak`.
+# Install speech-swift/audio separately, then set TTS_BACKEND="qwen3tts" or "qwen3".
+QWEN3TTS_COMMAND="audio"
+QWEN3TTS_MODE="custom"       # custom | clone | design
+QWEN3TTS_MODEL="customVoice" # customVoice for preset speakers, base/base-8bit for cloning
+QWEN3TTS_LANGUAGE="korean"
+QWEN3TTS_SPEAKER="sohee"    # used in custom mode
+QWEN3TTS_INSTRUCT=""         # emotion/style instruction; used in custom/design modes
+QWEN3TTS_REF_AUDIO="./voice-samples/user-reference.wav"  # used in clone mode
+QWEN3TTS_REF_TEXT=""         # optional note for your reference sample
+QWEN3TTS_STREAM="1"
+QWEN3TTS_TIMEOUT_MS="120000"
+QWEN3TTS_PROGRESS="0"        # keep progress prompts fast via Edge unless set to 1
 REQUIRE_WAKE_WORD="0"
 MIN_UTTERANCE_SECONDS="1.0"
 # Wait for natural thinking pauses before STT. Lower for faster but more fragmented turns.
@@ -109,3 +137,45 @@ BARGE_IN_CONSERVATIVE_MIN_SECONDS="1.8"
 BARGE_IN_CONSERVATIVE_MIN_MEAN_VOLUME_DB="-27"
 BARGE_IN_CONSERVATIVE_MIN_MAX_VOLUME_DB="-12"
 MAX_DEFERRED_PROCESSING_UTTERANCES="0"
+
+
+# Optional local TTS backends (final answers only by default; progress falls back to Edge)
+# TTS_BACKEND=fireredtts2
+FIREREDTTS2_COMMAND=./.local/bin/fireredtts2
+FIREREDTTS2_PRETRAINED_DIR=pretrained_models/FireRedTTS2
+FIREREDTTS2_DEVICE=auto
+FIREREDTTS2_GEN_TYPE=monologue
+FIREREDTTS2_SPEAKER=S1
+FIREREDTTS2_PROMPT_AUDIO=voice-samples/user-reference.wav
+FIREREDTTS2_PROMPT_TEXT=
+FIREREDTTS2_BF16=0
+FIREREDTTS2_TIMEOUT_MS=180000
+FIREREDTTS2_PROGRESS=0
+
+# TTS_BACKEND=mossttsnano
+MOSSTTSNANO_COMMAND=python3
+MOSSTTSNANO_SCRIPT=vendor/MOSS-TTS-Nano/infer.py
+MOSSTTSNANO_CHECKPOINT=OpenMOSS-Team/MOSS-TTS-Nano
+MOSSTTSNANO_AUDIO_TOKENIZER=
+MOSSTTSNANO_MODE=continuation
+MOSSTTSNANO_DEVICE=auto
+MOSSTTSNANO_DTYPE=auto
+MOSSTTSNANO_PROMPT_AUDIO=voice-samples/user-reference.wav
+MOSSTTSNANO_PROMPT_TEXT=
+MOSSTTSNANO_MAX_NEW_FRAMES=375
+MOSSTTSNANO_TIMEOUT_MS=120000
+MOSSTTSNANO_PROGRESS=0
+
+# TTS_BACKEND=neuttsair  # NeuTTS Air is English-only; progress falls back to Edge by default.
+NEUTTSAIR_PYTHON=./.venv-neuttsair/bin/python
+NEUTTSAIR_SCRIPT=integrations/neuttsair/synth.py
+NEUTTSAIR_BACKBONE_REPO=neuphonic/neutts-air-q4-gguf
+NEUTTSAIR_BACKBONE_DEVICE=mps
+NEUTTSAIR_CODEC_REPO=neuphonic/neucodec
+NEUTTSAIR_CODEC_DEVICE=mps
+NEUTTSAIR_REF_AUDIO=voice-samples/user-reference.wav
+NEUTTSAIR_REF_TEXT=
+NEUTTSAIR_LANGUAGE=en
+NEUTTSAIR_SAMPLE_RATE=24000
+NEUTTSAIR_TIMEOUT_MS=120000
+NEUTTSAIR_PROGRESS=0

package/README.es.md

@@ -30,7 +30,8 @@ VerbalCoding convierte una sala de voz de Discord en una cabina manos libres par
 | Flujo tipo llamada | Habla, escucha, interrumpe y continúa en el mismo canal de voz de Discord. |
 | Configuración guiada | `vc setup` reúne prerequisites, Discord token/client ID, voice channel, transcript target, backend y TTS settings en un solo flujo. |
 | Bucle de voz local | Discord audio → local `whisper-cli` → selected CLI agent → TTS reply. |
-| Elección de agente | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw o custom command. |
+| Elección de agente | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI o custom command. `vc setup` autodetecta lo que tienes instalado. |
+| Enrutamiento de agente por voz | `"ask Codex what it thinks"` (un turno), `"switch to Aider"` (sticky), `"back to default"` para volver. Si el binario no está instalado, el puente ofrece fallback al agente por defecto. |
 | Más allá de la voz integrada de Hermes | Mantiene el mismo bucle de voz en VC y añade salas de proyecto, contexto compartido con `!ask`, interrupciones afinadas, voz de progreso/estado y control de backends multiagente. |
 | Operación real | Incluye doctor auto-fix, guía Docker UDP, latency metrics, multi-instance rooms y redacted config checks. |
 
@@ -90,6 +91,7 @@ vc instance start NAME                   # ejecutar ese bot en background
 | [Centro de documentación](docs/i18n/README.es.md) | Índice de guías localizadas. |
 | [Fresh Install](docs/i18n/FRESH_INSTALL.es.md) | npm/global setup, configuración de Discord y primera ejecución. |
 | [Usage](docs/i18n/USAGE.es.md) | Comandos CLI, comandos Discord, modos de ejecución y latency. |
+| [Uso por harness](docs/i18n/HARNESSES.es.md) | Instalación, configuración y enrutamiento por voz para Claude Code, Codex, Aider y demás. |
 | [Voz integrada de Hermes vs VerbalCoding](docs/i18n/HERMES_VOICE.es.md) | La voz Discord que Hermes ya ofrece y la diferencia de VerbalCoding. |
 | [Configuration](docs/i18n/CONFIGURATION.es.md) | .env, agent backends, MCP, TTS y operación. |
 | [Troubleshooting](docs/i18n/TROUBLESHOOTING.es.md) | Docker UDP y comprobaciones de token/channel. |

package/README.fr.md

@@ -30,7 +30,8 @@ VerbalCoding transforme un salon vocal Discord en poste de pilotage mains libres
 | Flux type appel | Parler, écouter, interrompre et continuer dans le même salon vocal Discord. |
 | Configuration guidée | `vc setup` couvre prerequisites, Discord token/client ID, voice channel, transcript target, backend et TTS settings en un seul flux. |
 | Boucle vocale locale | Discord audio → local `whisper-cli` → selected CLI agent → TTS reply. |
-| Choix de l’agent | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw ou custom command. |
+| Choix de l’agent | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI ou custom command. `vc setup` détecte automatiquement ce qui est installé. |
+| Routage d’agent par voix | `"ask Codex what it thinks"` pour un tour, `"switch to Aider"` en sticky, `"back to default"` pour revenir. Les binaires absents sont détectés et le pont propose un fallback vers l’agent par défaut. |
 | Au-delà de la voix intégrée de Hermes | Garde la même boucle vocale VC, puis ajoute salons de projet, contexte partagé `!ask`, interruptions réglées, annonces progression/état et contrôle de backends multiagents. |
 | Exploitation réelle | doctor auto-fix, guide Docker UDP, latency metrics, multi-instance rooms et redacted config checks inclus. |
 
@@ -90,6 +91,7 @@ vc instance start NAME                   # exécuter ce bot en background
 | [Centre de documentation](docs/i18n/README.fr.md) | Index des guides localisés. |
 | [Fresh Install](docs/i18n/FRESH_INSTALL.fr.md) | npm/global setup, configuration Discord, premier lancement. |
 | [Usage](docs/i18n/USAGE.fr.md) | Commandes CLI, commandes Discord, modes d’exécution, latency. |
+| [Usage par harness](docs/i18n/HARNESSES.fr.md) | Installation, configuration et routage vocal pour Claude Code, Codex, Aider et les autres. |
 | [Voix intégrée Hermes vs VerbalCoding](docs/i18n/HERMES_VOICE.fr.md) | La voix Discord déjà fournie par Hermes et la différence VerbalCoding. |
 | [Configuration](docs/i18n/CONFIGURATION.fr.md) | .env, agent backends, MCP, TTS, exploitation. |
 | [Troubleshooting](docs/i18n/TROUBLESHOOTING.fr.md) | Docker UDP et vérifications token/channel. |

package/README.ja.md

@@ -30,7 +30,8 @@ VerbalCoding は Discord の音声ルームを、コーディングエージェ
 | 電話のような流れ | 同じ Discord 音声チャンネルで話す、聞く、割り込む、続けるができます。 |
 | 人向けのガイド付き設定 | `vc setup` が prerequisites、Discord token/client ID、voice channel、transcript target、backend、TTS 設定を一連の流れで確認します。 |
 | ローカル音声ループ | Discord audio → local `whisper-cli` → selected CLI agent → TTS response。 |
-| エージェント選択 | Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、custom command に対応します。 |
+| エージェント選択 | Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Aider、Cursor CLI または custom command に対応します。`vc setup` がインストール済みのものを自動検出します。 |
+| 音声でエージェントを切替 | `"ask Codex what it thinks"` で 1 ターンのみ、`"switch to Aider"` で sticky、`"back to default"` で復帰。未インストールのバイナリを検出して既定エージェントへの fallback を提案します。 |
 | Hermes 標準音声の先 | 同じ VC 音声ループを土台に、プロジェクトルーム、`!ask` 共有コンテキスト、細かな割り込み処理、進捗/状態の音声案内、複数エージェントバックエンド制御を追加します。 |
 | 運用向け機能 | doctor auto-fix、Docker UDP ガイド、latency metrics、multi-instance rooms、redacted config checks を備えています。 |
 
@@ -90,6 +91,7 @@ vc instance start NAME                   # その bot を background で実行
 | [ドキュメントハブ](docs/i18n/README.ja.md) | ローカライズ済みガイドの索引。 |
 | [Fresh Install](docs/i18n/FRESH_INSTALL.ja.md) | npm/global setup、Discord 設定、初回起動。 |
 | [Usage](docs/i18n/USAGE.ja.md) | CLI コマンド、Discord コマンド、実行モード、latency。 |
+| [Harness 別の使い方](docs/i18n/HARNESSES.ja.md) | Claude Code、Codex、Aider などバックエンド別のインストール・設定・音声ルーティング。 |
 | [Hermes 標準音声 vs VerbalCoding](docs/i18n/HERMES_VOICE.ja.md) | Hermes がすでに提供する Discord 音声と VerbalCoding の違い。 |
 | [Configuration](docs/i18n/CONFIGURATION.ja.md) | .env、agent backends、MCP、TTS、運用。 |
 | [Troubleshooting](docs/i18n/TROUBLESHOOTING.ja.md) | Docker UDP、token/channel 不足チェック。 |

package/README.ko.md

@@ -30,7 +30,8 @@ VerbalCoding은 Discord 음성 방을 코딩 에이전트용 핸즈프리 조종
 | 통화 같은 작업 흐름 | 한 Discord 음성 채널에서 말하고, 듣고, 끼어들고, 이어서 작업합니다. |
 | 안내형 사람용 설정 | `vc setup`이 prerequisites, Discord token/client ID, voice channel, transcript target, backend, TTS 설정을 한 흐름으로 묻습니다. |
 | 로컬 음성 루프 | Discord audio → local `whisper-cli` → selected CLI agent → TTS 답변. |
-| 에이전트 선택 | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, custom command를 지원합니다. |
+| 에이전트 선택 | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI 또는 custom command를 지원합니다. `vc setup`이 설치된 것을 자동 감지해요. |
+| 음성으로 에이전트 라우팅 | `"코덱스한테 물어봐"`로 한 턴만 보내거나 `"aider로 전환"`으로 sticky 전환. `"기본으로 돌아가"`로 복귀. 없는 바이너리는 감지해서 기본 에이전트로 fallback할지 물어봐. |
 | Hermes 기본 음성 너머 | 같은 VC 음성 루프를 기반으로 프로젝트 방, `!ask` 공유 컨텍스트, 세밀한 끼어들기 처리, 진행/상태 음성 안내, 다중 에이전트 백엔드 제어를 더합니다. |
 | 운영 친화 기능 | doctor auto-fix, Docker UDP 안내, latency metrics, multi-instance rooms, redacted config checks가 포함됩니다. |
 
@@ -90,6 +91,7 @@ vc instance start NAME                   # 해당 bot을 background로 실행
 | [문서 허브](docs/i18n/README.ko.md) | 현지화된 가이드 색인. |
 | [Fresh Install](docs/i18n/FRESH_INSTALL.ko.md) | npm/global setup, Discord 설정, 첫 실행. |
 | [Usage](docs/i18n/USAGE.ko.md) | CLI 명령, Discord 명령, 실행 모드, latency. |
+| [하니스 사용법](docs/i18n/HARNESSES.ko.md) | Claude Code, Codex, Aider 등 백엔드별 설치·설정·음성 라우팅. |
 | [Hermes 기본 음성 vs VerbalCoding](docs/i18n/HERMES_VOICE.ko.md) | Hermes가 이미 지원하는 Discord 음성과 VerbalCoding의 차이. |
 | [Configuration](docs/i18n/CONFIGURATION.ko.md) | .env, agent backends, MCP, TTS, 운영. |
 | [Troubleshooting](docs/i18n/TROUBLESHOOTING.ko.md) | Docker UDP, token/channel 누락 점검. |
@@ -101,7 +103,7 @@ vc instance start NAME                   # 해당 bot을 background로 실행
 |---|---|
 | Runtime | Node.js 20+와 npm. |
 | Audio | `ffmpeg`와 local `whisper-cli`. |
-| TTS | 기본 Edge TTS, 선택 OpenVoice, SpeechSwift/CosyVoice, Supertonic. |
+| TTS | 기본 Edge TTS, 선택 OpenVoice, SpeechSwift/CosyVoice, Supertonic, OmniVoice, Qwen3 TTS CLI. |
 | Discord | Bot token, Message Content intent, voice permissions, 일치하는 channel names. |
 | Agent | 인증된 CLI harness 하나 이상, 기본은 Hermes Agent. |
 

package/README.md

@@ -34,6 +34,7 @@ VerbalCoding turns a Discord voice channel into a hands-free cockpit for **any**
 - **Streaming pipeline** — first sentence plays while the agent is still writing (Hermes lists this as a future Phase-4 item).
 - **Smart progress narration** — describes intent ("wiring the new login route"), not file lists.
 - **Voice plan mode** — say "plan it first", edit by voice ("skip step 3"), say "approve" to execute.
+- **Cross-agent routing by voice** — "ask Codex what it thinks" for a single turn, "switch to Aider" to make it sticky, "back to default" to restore. The plan can also emit a `which_agent` slot so the agent itself picks the next backend.
 - **Phone-down mode** — push notification with a voice summary when a long task completes and the room is empty.
 
 ## What feels different
@@ -41,8 +42,9 @@ VerbalCoding turns a Discord voice channel into a hands-free cockpit for **any**
 | Capability | Why it matters |
 |---|---|
 | Agent choice, first-class | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI, or any custom command. `vc setup` auto-detects what's installed. |
+| Cross-agent voice routing | Say "ask Codex …" (single turn), "switch to Aider" (sticky), or "back to default". Missing binaries are detected and the bridge offers to fall back to the default agent. Handoff prompts carry recent utterances + last plan decisions to the new agent. |
 | Real barge-in | VAD thresholds tuned for indoor and noisy rooms; cut in mid-utterance and resume the conversation. |
-| Streaming end-to-end | `STREAMING_TTS=1` plays sentences as the agent produces them; first audio in well under a second on a warm cache. |
+| Streaming end-to-end | Sentence-by-sentence playback while the agent is still writing; first audio in well under a second on a warm cache. On by default — set `STREAMING_TTS=0` to fall back to whole-reply playback. |
 | Smart progress | Optional LLM summarizer collapses raw events into one human sentence; falls back to the existing regex labels when no key is set. |
 | Plan-mode by voice | Narrated, editable, voice-driven plans without touching the keyboard. |
 | Phone-down handoff | Long task + empty VC = push notification (`ntfy`/`pushover`) with a redacted one-line summary and tap-to-rejoin link. |
@@ -156,7 +158,7 @@ The differentiation push is tracked in [docs/ROADMAP.md](./docs/ROADMAP.md). Fiv
 | Runtime | Node.js 20+ and npm; setup can install via Homebrew/apt/dnf/pacman where supported. |
 | Audio | `ffmpeg`; setup/doctor can install it on supported OSes. |
 | Speech recognition | Local `whisper-cli` from whisper.cpp plus `models/ggml-small-q5_1.bin`. |
-| TTS | Edge TTS by default; optional OpenVoice, SpeechSwift/CosyVoice, and Supertonic paths. |
+| TTS | Edge TTS by default; optional OpenVoice, SpeechSwift/CosyVoice, Supertonic, OmniVoice, and Qwen3 TTS CLI paths. |
 | Discord | Bot token, Message Content intent, voice permissions, matching auto-join channel names. |
 | Agent | At least one CLI harness installed; `vc setup` auto-detects Hermes, Claude Code, Codex, Gemini, OpenCode, OpenClaw, Aider, Cursor CLI. |
 | Platform focus | macOS / Apple Silicon most tested; Linux bootstrap is best-effort; Windows unsupported for now. |

package/README.ru.md

@@ -30,7 +30,8 @@ VerbalCoding превращает голосовую комнату Discord в h
 | Работа как звонок | Говорите, слушайте, перебивайте и продолжайте в одном голосовом канале Discord. |
 | Пошаговая настройка | `vc setup` проводит через prerequisites, Discord token/client ID, voice channel, transcript target, backend и TTS settings за один проход. |
 | Локальный голосовой цикл | Discord audio → local `whisper-cli` → selected CLI agent → TTS reply. |
-| Выбор агента | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw или custom command. |
+| Выбор агента | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI или custom command. `vc setup` автоматически находит установленные. |
+| Голосовая маршрутизация агента | `"ask Codex what it thinks"` — на один turn, `"switch to Aider"` — sticky, `"back to default"` — возврат. Отсутствующие бинарники определяются и мост предлагает fallback к агенту по умолчанию. |
 | Больше, чем встроенный голос Hermes | Сохраняет тот же VC-голосовой цикл и добавляет проектные комнаты, общий контекст `!ask`, тонкую обработку прерываний, голос прогресса/статуса и управление multi-agent бэкендами. |
 | Готовность к эксплуатации | doctor auto-fix, Docker UDP guide, latency metrics, multi-instance rooms и redacted config checks встроены. |
 
@@ -90,6 +91,7 @@ vc instance start NAME                   # запустить этот bot в ba
 | [Центр документации](docs/i18n/README.ru.md) | Индекс локализованных гайдов. |
 | [Fresh Install](docs/i18n/FRESH_INSTALL.ru.md) | npm/global setup, настройка Discord и первый запуск. |
 | [Usage](docs/i18n/USAGE.ru.md) | CLI-команды, Discord-команды, режимы запуска и latency. |
+| [Использование по harness](docs/i18n/HARNESSES.ru.md) | Установка, настройка и голосовая маршрутизация для Claude Code, Codex, Aider и других. |
 | [Встроенный голос Hermes vs VerbalCoding](docs/i18n/HERMES_VOICE.ru.md) | Что Hermes уже умеет в Discord voice и чем отличается VerbalCoding. |
 | [Configuration](docs/i18n/CONFIGURATION.ru.md) | .env, agent backends, MCP, TTS и эксплуатация. |
 | [Troubleshooting](docs/i18n/TROUBLESHOOTING.ru.md) | Docker UDP и проверки token/channel. |

package/README.zh.md

@@ -30,7 +30,8 @@ VerbalCoding 把 Discord 语音房间变成编码代理的免提驾驶舱。你
 | 电话式工作流 | 在同一个 Discord 语音频道里说话、收听、打断、继续。 |
 | 面向人的引导设置 | `vc setup` 一次引导 prerequisites、Discord token/client ID、voice channel、transcript target、backend 和 TTS 设置。 |
 | 本地语音闭环 | Discord audio → local `whisper-cli` → selected CLI agent → TTS reply。 |
-| 可选代理 | 支持 Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 或 custom command。 |
+| 可选代理 | 支持 Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Aider、Cursor CLI 或 custom command。`vc setup` 自动检测已安装项。 |
+| 语音切换代理 | `"ask Codex what it thinks"` 单 turn 路由,`"switch to Aider"` 粘性切换,`"back to default"` 回默认。未安装的二进制会被检测并询问是否回退到默认代理。 |
 | 超越 Hermes 内置语音 | 在同一个 VC 语音闭环上增加项目房间、`!ask` 共享上下文、细粒度打断处理、进度/状态语音和多代理后端控制。 |
 | 真实运维支持 | 内置 doctor auto-fix、Docker UDP 指南、latency metrics、multi-instance rooms 和 redacted config checks。 |
 
@@ -90,6 +91,7 @@ vc instance start NAME                   # 后台运行该 bot
 | [文档中心](docs/i18n/README.zh.md) | 本地化指南索引。 |
 | [Fresh Install](docs/i18n/FRESH_INSTALL.zh.md) | npm/global setup、Discord 设置、首次运行。 |
 | [Usage](docs/i18n/USAGE.zh.md) | CLI 命令、Discord 命令、运行模式、latency。 |
+| [Harness 使用](docs/i18n/HARNESSES.zh.md) | Claude Code、Codex、Aider 等各后端的安装、配置与语音路由。 |
 | [Configuration](docs/i18n/CONFIGURATION.zh.md) | .env、agent backends、MCP、TTS、运维。 |
 | [Troubleshooting](docs/i18n/TROUBLESHOOTING.zh.md) | Docker UDP、token/channel 缺失检查。 |
 | [Multi-Instance](docs/i18n/MULTI_INSTANCE.zh.md) | 每个项目一个固定语音房间。 |

package/app-node/agent_adapters.test.mjs

@@ -456,6 +456,20 @@ test('signal failure with patch-like output returns a concise interruption messa
   assert.doesNotMatch(answer, /@@|review diff|old|new/);
 });
 
+test('createAgentAdapter satisfies the agent adapter contract for every known backend', () => {
+  const backends = ['hermes', 'claude', 'codex', 'gemini', 'opencode', 'openclaw', 'aider', 'cursor'];
+  for (const backend of backends) {
+    const settings = buildAgentSettings({ ROOT: '/tmp/vc-test', env: { AGENT_BACKEND: backend } });
+    const adapter = createAgentAdapter(settings, {
+      execFileAsync: async () => ({ stdout: '', stderr: '' }),
+      log: () => {},
+      warn: () => {},
+    });
+    assert.doesNotThrow(() => assertAgentAdapterContract(adapter), `${backend} should satisfy contract`);
+    assert.equal(adapter.backend, backend);
+  }
+});
+
 test('hermes adapter spawn carries HERMES_HOME from instance env into child env', async () => {
   const { buildHermesSpawnOptions } = await import('./agent_adapters.mjs');
   const opts = buildHermesSpawnOptions({

package/app-node/agent_routing.mjs

@@ -0,0 +1,148 @@
+const BACKEND_ALIASES = {
+  hermes: ['hermes', '헤르메스'],
+  claude: ['claude code', 'claude-code', 'claude'],
+  codex: ['codex', '코덱스'],
+  gemini: ['gemini cli', 'gemini-cli', 'gemini', '제미나이'],
+  opencode: ['opencode', 'open code'],
+  openclaw: ['openclaw', 'open claw'],
+  aider: ['aider', '에이더'],
+  cursor: ['cursor cli', 'cursor-cli', 'cursor agent', 'cursor-agent', 'cursor'],
+};
+
+const BACKEND_LOOKUP = (() => {
+  const pairs = [];
+  for (const [backend, aliases] of Object.entries(BACKEND_ALIASES)) {
+    for (const alias of aliases) pairs.push([alias.toLowerCase(), backend]);
+  }
+  pairs.sort((a, b) => b[0].length - a[0].length);
+  return pairs;
+})();
+
+const BACKEND_LABELS = {
+  hermes: { en: 'Hermes', ko: '헤르메스' },
+  claude: { en: 'Claude Code', ko: 'Claude Code' },
+  codex: { en: 'Codex', ko: '코덱스' },
+  gemini: { en: 'Gemini', ko: 'Gemini' },
+  opencode: { en: 'OpenCode', ko: 'OpenCode' },
+  openclaw: { en: 'OpenClaw', ko: 'OpenClaw' },
+  aider: { en: 'Aider', ko: 'Aider' },
+  cursor: { en: 'Cursor CLI', ko: 'Cursor CLI' },
+};
+
+const ROUTING_SLOT_NAMES = new Set(['which_agent', 'agent', 'who_answers', 'router_agent']);
+
+const ASK_EN = /\bask\s+([a-z][a-z0-9 \-]{1,30}?)(?:\s+(?:to|what|if|whether)\b|[?,.]|$)/i;
+const SWITCH_EN = /\bswitch\s+to\s+([a-z][a-z0-9 \-]{1,30}?)(?:[?,.]|$)/i;
+const LET_FINISH_EN = /\blet\s+([a-z][a-z0-9 \-]{1,30}?)\s+(?:finish|handle|do)\b/i;
+const RESTORE_EN = /\b(back\s+to\s+default|use\s+the\s+default\s+agent|default\s+agent)\b/i;
+
+const ASK_KO = /([가-힣A-Za-z][가-힣A-Za-z0-9\-]{1,30})(?:한테|에게|에)\s*(물어|질문)/;
+const SWITCH_KO = /([가-힣A-Za-z][가-힣A-Za-z0-9\-]{1,30})(?:로|으로)\s*(전환|바꿔|바꿔줘)/;
+const RESTORE_KO = /(기본(?:으로)?\s*(?:돌아|복귀)|기본\s*에이전트)/;
+
+export function isRoutingOnlyUtterance(text) {
+  const t = String(text || '').trim();
+  if (!t) return false;
+  const normalized = t.toLowerCase().replace(/[.,!?]+$/u, '').trim();
+  if (/^(?:please\s+)?(?:back\s+to\s+default|use\s+the\s+default\s+agent|default\s+agent)$/i.test(normalized)) return true;
+  if (/^기본(?:으로)?\s*(?:돌아(?:가|가줘)?|복귀)$/.test(normalized)) return true;
+  const en = normalized.match(/^(?:please\s+)?(?:switch\s+to|use)\s+(.+)$/i);
+  if (en) return resolveBackendAlias(en[1], { strict: true }) !== null;
+  const ko = normalized.match(/^(.+?)(?:로|으로)\s*(?:전환|바꿔|바꿔줘)$/);
+  if (ko) return resolveBackendAlias(ko[1], { strict: true }) !== null;
+  return false;
+}
+
+export function resolveBackendAlias(rawName, { strict = false } = {}) {
+  const needle = String(rawName || '').toLowerCase().trim();
+  if (!needle) return null;
+  for (const [alias, backend] of BACKEND_LOOKUP) {
+    if (needle === alias) return backend;
+  }
+  if (strict) return null;
+  for (const [alias, backend] of BACKEND_LOOKUP) {
+    if (needle.includes(alias)) return backend;
+  }
+  return null;
+}
+
+export function parseAgentRoutingCommand(text, language = 'en') {
+  const t = String(text || '').trim();
+  if (!t) return { type: 'none' };
+  if (RESTORE_EN.test(t) || RESTORE_KO.test(t)) return { type: 'restore' };
+  const switchMatch = t.match(SWITCH_EN) || t.match(LET_FINISH_EN);
+  if (switchMatch) {
+    const backend = resolveBackendAlias(switchMatch[1]);
+    if (backend) return { type: 'route', backend, sticky: true };
+  }
+  const switchKo = t.match(SWITCH_KO);
+  if (switchKo) {
+    const backend = resolveBackendAlias(switchKo[1]);
+    if (backend) return { type: 'route', backend, sticky: true };
+  }
+  const askMatch = t.match(ASK_EN);
+  if (askMatch) {
+    const backend = resolveBackendAlias(askMatch[1]);
+    if (backend) return { type: 'route', backend, sticky: false };
+  }
+  const askKo = t.match(ASK_KO);
+  if (askKo) {
+    const backend = resolveBackendAlias(askKo[1]);
+    if (backend) return { type: 'route', backend, sticky: false };
+  }
+  return { type: 'none' };
+}
+
+export function isAgentRoutingDecision(decision) {
+  if (!decision || typeof decision !== 'object') return false;
+  const slot = String(decision.slot || '').toLowerCase();
+  return ROUTING_SLOT_NAMES.has(slot);
+}
+
+export function renderAgentPrefix(backend, language = 'en') {
+  const key = String(backend || '').toLowerCase();
+  if (!BACKEND_LABELS[key]) return '';
+  const en = /^en/i.test(String(language || ''));
+  const label = BACKEND_LABELS[key][en ? 'en' : 'ko'];
+  return en ? `${label} says: ` : `${label}: `;
+}
+
+function labelFor(backend, language) {
+  const key = String(backend || '').toLowerCase();
+  if (!BACKEND_LABELS[key]) return key || 'agent';
+  return BACKEND_LABELS[key][/^en/i.test(String(language || '')) ? 'en' : 'ko'];
+}
+
+export function buildCrossAgentPrompt({
+  prompt, fromBackend, toBackend,
+  resolvedDecisions = {}, priorUtterances = [], language = 'en',
+} = {}) {
+  const en = /^en/i.test(String(language || ''));
+  const fromLabel = labelFor(fromBackend, language);
+  const toLabel = labelFor(toBackend, language);
+  const lines = [];
+  lines.push(en
+    ? `[Cross-agent handoff from ${fromLabel} to ${toLabel}]`
+    : `[에이전트 핸드오프: ${fromLabel} → ${toLabel}]`);
+  const decKeys = Object.keys(resolvedDecisions || {});
+  if (decKeys.length) {
+    const parts = decKeys.map(k => `${k}=${resolvedDecisions[k] === null ? '(agent picks)' : resolvedDecisions[k]}`);
+    lines.push(en ? `Prior decisions: ${parts.join(', ')}` : `이전 결정: ${parts.join(', ')}`);
+  }
+  const utterances = (priorUtterances || []).filter(Boolean).slice(-4);
+  if (utterances.length) {
+    lines.push(en
+      ? `Recent user voice: ${utterances.join(' | ')}`
+      : `최근 사용자 음성: ${utterances.join(' | ')}`);
+  }
+  lines.push(en ? `User request: ${prompt}` : `사용자 요청: ${prompt}`);
+  return lines.join('\n');
+}
+
+export function buildFallbackDecision(missingBackend, fallbackLabel, language = 'en') {
+  const en = /^en/i.test(String(language || ''));
+  const question = en
+    ? `${missingBackend} is not installed. Use ${fallbackLabel} instead?`
+    : `${missingBackend}이(가) 설치되어 있지 않아. ${fallbackLabel}로 대신 진행할까?`;
+  return { slot: 'fallback', question, options: ['yes', 'no'] };
+}

package/app-node/agent_routing.test.mjs

@@ -0,0 +1,138 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  parseAgentRoutingCommand,
+  resolveBackendAlias,
+  isAgentRoutingDecision,
+  renderAgentPrefix,
+  buildCrossAgentPrompt,
+  buildFallbackDecision,
+  isRoutingOnlyUtterance,
+} from './agent_routing.mjs';
+
+test('parseAgentRoutingCommand recognizes "ask X" as single-turn', () => {
+  assert.deepEqual(parseAgentRoutingCommand('ask Codex what it thinks', 'en'),
+    { type: 'route', backend: 'codex', sticky: false });
+  assert.deepEqual(parseAgentRoutingCommand('ask aider to write the test', 'en'),
+    { type: 'route', backend: 'aider', sticky: false });
+});
+
+test('parseAgentRoutingCommand recognizes "switch to X" as sticky', () => {
+  assert.deepEqual(parseAgentRoutingCommand('switch to Aider', 'en'),
+    { type: 'route', backend: 'aider', sticky: true });
+  assert.deepEqual(parseAgentRoutingCommand('switch to claude code', 'en'),
+    { type: 'route', backend: 'claude', sticky: true });
+});
+
+test('parseAgentRoutingCommand recognizes Korean routing phrases', () => {
+  assert.deepEqual(parseAgentRoutingCommand('코덱스한테 물어봐', 'ko'),
+    { type: 'route', backend: 'codex', sticky: false });
+  assert.deepEqual(parseAgentRoutingCommand('aider로 전환해', 'ko'),
+    { type: 'route', backend: 'aider', sticky: true });
+});
+
+test('parseAgentRoutingCommand recognizes restore-default phrases', () => {
+  assert.deepEqual(parseAgentRoutingCommand('back to default', 'en'),
+    { type: 'restore' });
+  assert.deepEqual(parseAgentRoutingCommand('use the default agent', 'en'),
+    { type: 'restore' });
+  assert.deepEqual(parseAgentRoutingCommand('기본으로 돌아가', 'ko'),
+    { type: 'restore' });
+});
+
+test('parseAgentRoutingCommand returns none on unrelated input', () => {
+  assert.deepEqual(parseAgentRoutingCommand('just write the function', 'en'),
+    { type: 'none' });
+  assert.deepEqual(parseAgentRoutingCommand('plan it first', 'en'),
+    { type: 'none' });
+});
+
+test('resolveBackendAlias maps user-facing names to canonical backends', () => {
+  assert.equal(resolveBackendAlias('Claude Code'), 'claude');
+  assert.equal(resolveBackendAlias('claude'), 'claude');
+  assert.equal(resolveBackendAlias('cursor cli'), 'cursor');
+  assert.equal(resolveBackendAlias('gemini cli'), 'gemini');
+  assert.equal(resolveBackendAlias('코덱스'), 'codex');
+  assert.equal(resolveBackendAlias('unknown'), null);
+});
+
+test('isAgentRoutingDecision detects which_agent slot', () => {
+  assert.equal(isAgentRoutingDecision({ slot: 'which_agent', options: ['codex', 'aider'] }), true);
+  assert.equal(isAgentRoutingDecision({ slot: 'oauth_provider', options: ['google', 'github'] }), false);
+  assert.equal(isAgentRoutingDecision({ slot: 'agent', options: ['codex', 'aider'] }), true);
+  assert.equal(isAgentRoutingDecision(null), false);
+});
+
+test('renderAgentPrefix uses English label for en', () => {
+  assert.equal(renderAgentPrefix('codex', 'en'), 'Codex says: ');
+  assert.equal(renderAgentPrefix('claude', 'en'), 'Claude Code says: ');
+});
+
+test('renderAgentPrefix uses Korean label for ko', () => {
+  assert.equal(renderAgentPrefix('codex', 'ko'), '코덱스: ');
+  assert.equal(renderAgentPrefix('claude', 'ko'), 'Claude Code: ');
+});
+
+test('renderAgentPrefix returns empty when backend unknown', () => {
+  assert.equal(renderAgentPrefix('', 'en'), '');
+  assert.equal(renderAgentPrefix(null, 'en'), '');
+  assert.equal(renderAgentPrefix('unknownbackend', 'en'), '');
+});
+
+test('buildCrossAgentPrompt prepends handoff block in English', () => {
+  const out = buildCrossAgentPrompt({
+    prompt: 'Refactor the login route to use OAuth.',
+    fromBackend: 'claude', toBackend: 'codex',
+    resolvedDecisions: { oauth_provider: 'github' },
+    priorUtterances: ['plan it first', 'skip step 2'],
+    language: 'en',
+  });
+  assert.match(out, /Cross-agent handoff from Claude Code to Codex/);
+  assert.match(out, /Prior decisions: oauth_provider=github/);
+  assert.match(out, /Recent user voice: plan it first \| skip step 2/);
+  assert.match(out, /User request: Refactor the login route to use OAuth\./);
+});
+
+test('buildCrossAgentPrompt omits empty sections', () => {
+  const out = buildCrossAgentPrompt({
+    prompt: 'do it', fromBackend: 'claude', toBackend: 'codex',
+    resolvedDecisions: {}, priorUtterances: [], language: 'en',
+  });
+  assert.doesNotMatch(out, /Prior decisions:/);
+  assert.doesNotMatch(out, /Recent user voice:/);
+  assert.match(out, /User request: do it/);
+});
+
+test('buildCrossAgentPrompt renders Korean header for ko', () => {
+  const out = buildCrossAgentPrompt({
+    prompt: '로그인 라우트 리팩토링해줘',
+    fromBackend: 'claude', toBackend: 'codex',
+    resolvedDecisions: {}, priorUtterances: [], language: 'ko',
+  });
+  assert.match(out, /에이전트 핸드오프: Claude Code → 코덱스/);
+  assert.match(out, /사용자 요청: 로그인 라우트 리팩토링해줘/);
+});
+
+test('buildFallbackDecision yields a yes/no shape', () => {
+  const d = buildFallbackDecision('codex', 'Claude Code', 'en');
+  assert.equal(d.slot, 'fallback');
+  assert.deepEqual(d.options, ['yes', 'no']);
+  assert.match(d.question, /codex/);
+  assert.match(d.question, /Claude Code/);
+});
+
+test('buildFallbackDecision yields a Korean prompt for ko', () => {
+  const d = buildFallbackDecision('codex', 'Claude Code', 'ko');
+  assert.match(d.question, /codex/);
+  assert.match(d.question, /Claude Code/);
+});
+
+test('isRoutingOnlyUtterance detects command-only utterances', () => {
+  assert.equal(isRoutingOnlyUtterance('switch to codex'), true);
+  assert.equal(isRoutingOnlyUtterance('switch to Aider.'), true);
+  assert.equal(isRoutingOnlyUtterance('back to default'), true);
+  assert.equal(isRoutingOnlyUtterance('codex로 전환'), true);
+  assert.equal(isRoutingOnlyUtterance('기본으로 돌아가'), true);
+  assert.equal(isRoutingOnlyUtterance('switch to codex and write a test'), false);
+  assert.equal(isRoutingOnlyUtterance('ask codex what it thinks'), false);
+});