verbalcoding 0.2.6 → 0.2.8

package/docs/i18n/RELEASE.zh.md

@@ -0,0 +1,74 @@
+# VerbalCoding 发行说明
+
+## 当前候选版本
+
+VerbalCoding 是一个 Discord 语音桥接，用于通过语音控制基于 CLI 的编码代理。它面向公开发布，macOS / Apple Silicon 是测试最多的路径，并为常见包管理器提供尽力支持的 Linux 引导。
+
+### 已包含
+
+- 通过 Node `@discordjs/voice` 接收 Discord 语音。
+- 通过 `whisper.cpp` + Metal 进行本地韩语 STT。
+- 使用韩语默认声音进行 Edge TTS 播放。
+- 通用 CLI 驱动适配器层：
+  - Hermes Agent
+  - Claude Code
+  - Codex CLI
+  - Gemini CLI
+  - OpenCode
+  - OpenClaw
+  - 自定义命令
+- Hermes 后端的共享语音/文本会话支持。
+- 长答案 TTS 分块和响应式插话。
+- Diff/code/log 保护机制，避免大段技术输出被朗读。
+- 面向室内与嘈杂/户外使用的普通和保守灵敏度模式。
+- 设置向导、`.env.example`、`vc doctor` 前置条件检查器，以及用于 OS 软件包、npm 依赖、Edge TTS 辅助环境和默认 whisper.cpp 模型的 `./scripts/install.sh --yes` 引导。
+- npm 包安装路径：`npm install -g verbalcoding`、`vc setup --yes` 和 `vc start`。
+- 可选详细进度模式，在长时间代理工作期间提供仅文本的中间步骤更新。
+- 常开 JSONL 延迟指标，以及用于流水线优化的 `!latency` / `!metrics` 摘要。
+- 更耐心的发言空闲等待（`UTTERANCE_IDLE_MS=4500`），使带自然停顿的长口述指令不会被拆成部分提示加被忽略的处理期间语音。
+- 多实例 Hermes profile 隔离：`vc instance setup <name>` 会自动将 Hermes profile 克隆到 `~/.hermes/profiles/<name>`，设置实例 workdir，初始化 SOUL.md，并将 `HERMES_HOME` 写入实例 env，使每项目记忆和 skills 保持分离；`vc instance start` 会自愈缺失 profile，`vc doctor` 会检查 profile 目录存在性和 `terminal.cwd` 一致性。
+
+### 预发布检查清单
+
+从仓库根目录运行：
+
+```bash
+./scripts/install.sh --yes --no-wizard
+./scripts/docker_ubuntu_smoke.sh   # 需要 Docker；验证 ubuntu:24.04 干净安装
+node --check app-node/main.mjs app-node/agent_adapters.mjs app-node/install_config.mjs scripts/install.mjs
+npm test
+PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/ -q || [ $? -eq 5 ]  # 没有 Python 测试时也可以
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh scripts/docker_ubuntu_smoke.sh
+npm pack --dry-run
+vc doctor
+git diff --check
+```
+
+手动冒烟测试：
+
+1. 使用 `vc start` 或 `./run.sh` 启动桥接。
+2. 验证日志包含 `Logged in as <bot-name>`。
+3. 验证日志包含 `Listening in voice channel ... / 일반` 或已配置的默认频道。
+4. 在 Discord 中运行 `!ping`。
+5. 在 Discord 语音中说一个简短韩语请求。
+6. 验证 STT 转写、代理响应、TTS 播放和插话行为。
+
+### 已知要求
+
+- macOS + Homebrew，或带 `apt`、`dnf`、`pacman` 的 Linux（用于尽力支持的引导）。
+- `ffmpeg`；安装器会尝试安装它。
+- `whisper-cli`；安装器在 macOS 使用 Homebrew，在 Linux 上回退到本地 `vendor/whisper.cpp` 构建。
+- 默认模型位于 `models/ggml-small-q5_1.bin`；除非使用 `--skip-model`，安装器会下载它。
+- `PATH` 上的 Edge TTS CLI，或本地 `.venv-tts/bin/edge-tts`；安装器会在需要时创建本地辅助环境。
+- `.env`、`instances/<name>.env`、`~/.zshrc` 或运行时 env 中的 Discord 机器人令牌。
+- 已安装并认证的所选 CLI 驱动。
+
+### 尚不适合公开发布
+
+公开发布前，建议添加：
+
+- GitHub Actions CI。
+- 演示视频 / GIF。
+- Discord 机器人设置截图。
+- 在脚本级检查之外，对真实发行版进行更广泛的 Linux 验证。
+- 对所有日志路径进行安全审查。

package/docs/i18n/USAGE.es.md

@@ -0,0 +1,161 @@
+# Guía de uso de VerbalCoding
+
+Esta página contiene los detalles operativos que antes hacían que el README fuera demasiado largo.
+
+## Comandos CLI
+
+```bash
+vc status                    # show STT language, progress language, and TTS voice
+vc language en               # English STT + English progress/TTS voice
+vc language ko               # Korean STT + Korean progress/TTS voice
+vc language auto             # Whisper auto-detect STT + English progress/TTS voice
+vc restart auto status       # show commit-time voice-bot auto-restart setting
+vc restart auto on           # enable commit-time voice-bot auto-restart
+vc restart auto off          # disable it; this is the default
+vc bot invite CLIENT_ID      # print a Discord invite URL with required permissions
+vc instance status           # list per-instance bridge configs and process status
+vc instance setup NAME       # write instances/NAME.env and create ~/.hermes/profiles/NAME
+vc instance start NAME       # start ./run.sh instances/NAME.env detached
+vc instance stop NAME        # stop a detached instance and remove its pid file
+vc doctor                    # run the redacted doctor check
+npm run mcp                  # run the stdio MCP server
+```
+
+Los cambios de idioma actualizan `.env`; reinicia el puente con `./run.sh` o tu gestor de procesos para que surtan efecto.
+
+## Modos de ejecución
+
+Puente de instancia única:
+
+```bash
+./run.sh
+```
+
+Puente por instancia usando un entorno local de sobrescritura:
+
+```bash
+./run.sh instances/my-project.env
+# or
+VERBALCODING_INSTANCE_ENV=instances/my-project.env ./run.sh
+```
+
+El bot se une automáticamente al primer nombre de canal configurado, con valor predeterminado `일반,General,general`.
+
+## Comandos de Discord
+
+Antes de cablear comandos, configura la aplicación/bot de Discord usando las guías originales:
+
+- Guía de Discord de Hermes Agent: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Documentación oficial de bots de Discord: <https://docs.discord.com/developers/bots/overview>
+
+Luego usa `vc bot invite CLIENT_ID` para generar la URL de invitación específica de VerbalCoding con permisos de texto y voz.
+
+| Comando | Propósito |
+|---|---|
+| `!ping` | Comprobación básica del bot |
+| `!join` / `!leave` | Unirse a voz o salir de voz |
+| `!say <text>` | Decir texto directamente mediante TTS |
+| `!voice-test <text>` | Probar el backend/voz TTS activo |
+| `!voice-clone capture` | Guardar la siguiente emisión válida como muestra de referencia para OpenVoice |
+| `!voice-clone status` / `!voice-clone cancel` | Inspeccionar o cancelar la captura |
+| `!ask <prompt>` | Enviar texto mediante el mismo adaptador de arnés seleccionado que la voz |
+| `!session status` | Mostrar la sesión actual de proyecto/adaptador predeterminado |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | Crear una sesión Hermes con alcance de proyecto |
+| `!session attach-voice [sessionName] --voice <voice-channel>` | Vincular canal/hilo de texto a un canal de voz |
+| `!session list` | Listar sesiones de proyecto configuradas |
+| `!session reset` / `!reset-session` | Borrar el archivo de sesión actual del proyecto/adaptador predeterminado |
+| `!verbose on/off` | Alternar actualizaciones de progreso detalladas |
+| `!latency` / `!metrics` | Mostrar resumen de latencia reciente |
+| `!sensitivity normal/conservative` | Cambiar sensibilidad de interrupción |
+
+Equivalentes de voz como “외부 모드”, “보수 모드”, “실내”, “기본 감도” y frases claras de parada como “잠깐”, “멈춰”, “그만” son gestionados por el puente. También puedes decir “상세 진행 켜” / “상세 진행 꺼” para alternar el progreso detallado por voz.
+
+## Cambiar la voz
+
+`vc language ko|en|auto` cambia juntos el idioma STT, el idioma de progreso y la voz TTS predeterminada correspondiente. Si solo quieres cambiar el hablante/voz mientras el puente está en ejecución, dilo en la voz de Discord:
+
+```text
+남자 한국어 목소리로 바꿔
+여자 한국어 목소리로 바꿔
+change voice to Korean female
+switch speaker to English
+```
+
+El puente en vivo reconoce esto como comandos de control por voz, actualiza `config/tts-voices.json`, actualiza el entorno TTS efectivo del proceso en ejecución y responde con una confirmación corta como “목소리를 Korean male로 바꿨어.” Usa `!voice-test <text>` justo después de cambiarla para escuchar el backend y la voz actuales.
+
+Tipos de voz Edge integrados:
+
+| Tipo de voz | Voz Edge |
+|---|---|
+| `korean_male` | `ko-KR-InJoonNeural` |
+| `korean_female` | `ko-KR-SunHiNeural` |
+| `korean_multilingual_male` | `ko-KR-HyunsuMultilingualNeural` |
+| `english_male` | `en-US-GuyNeural` |
+| `english_female` | `en-US-AriaNeural` |
+
+Para configuración manual persistente, define `TTS_BACKEND=edge`, `TTS_VOICE_TYPE=<voice-type>` y opcionalmente `TTS_VOICE=<edge-voice>` en `.env`, o edita `config/tts-voices.json` para catálogos de voz personalizados.
+
+Controles de voz específicos de backend:
+
+| Backend | Ajuste de voz | Opciones comunes |
+|---|---|---|
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | `korean_male`, `korean_female`, `korean_multilingual_male`, `english_male`, `english_female`; cualquier voz Edge de `edge-tts --list-voices` |
+| Supertonic | `SUPERTONIC_VOICE` | `M1`–`M5`, `F1`–`F5`; define `SUPERTONIC_LANGUAGE=ko|en|es|pt|fr` |
+| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE` | una referencia WAV permitida más un estilo como `default` |
+| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER` | WAV de referencia para CosyVoice, o valores de hablante/modelo admitidos por el backend |
+
+Para Supertonic y backends locales de clonación, usa las variables de entorno del backend anteriores junto con `!voice-test <text>` para probar cambios. El cambio por comandos de voz actualmente asigna los tipos de voz integrados de estilo Edge; se pueden añadir catálogos de backend más completos en `config/tts-voices.json`.
+
+## Dictado largo y pausas
+
+VerbalCoding espera una ventana de inactividad antes de enviar el habla a STT. El valor predeterminado `UTTERANCE_IDLE_MS=4500` es deliberadamente un poco paciente para que una pausa natural en una instrucción larga no divida la oración, inicie un turno de agente demasiado pronto y luego trate el resto como una interrupción durante el procesamiento.
+
+Si prefieres comandos cortos más rápidos, bájalo en `.env`; si el dictado largo en coreano aún se divide, súbelo:
+
+```bash
+UTTERANCE_IDLE_MS="6000"
+```
+
+## Modo de progreso detallado
+
+El progreso detallado está desactivado por defecto salvo que `AGENT_VERBOSE_PROGRESS=1` esté definido. Habilítalo con `!verbose on` o con un comando de voz como “상세 진행 켜”. Puede emitir líneas cortas de progreso como:
+
+```text
+🤖 Hermes Agent 호출 시작
+📖 파일 읽기 app-node/main.mjs
+🔎 웹 검색 실행
+⌨️ 터미널 명령 실행
+🤖 Hermes Agent 응답 수신
+```
+
+Este modo pide al arnés CLI seleccionado que emita líneas `VERBALCODING_PROGRESS: ...` y resume marcadores comunes de herramientas desde stdout/stderr en streaming cuando están disponibles. Los campos con aspecto de secreto se redactan y las líneas de progreso se eliminan de la respuesta final hablada.
+
+## Métricas de latencia
+
+VerbalCoding escribe registros de latencia por turno como JSONL. Ruta predeterminada:
+
+```text
+./.logs/latency.jsonl
+```
+
+Cada registro incluye estado, tiempo total, tiempo de captura de voz, espera de inactividad de emisión, tiempo STT, tiempo del agente, tiempo de síntesis/reproducción TTS, conteos de fragmentos, longitud de transcripción, longitud de respuesta y niveles de audio cuando están disponibles.
+
+En Discord:
+
+```text
+!latency
+!metrics
+```
+
+El resumen usa los últimos 200 registros: conteo, promedio, p95, máximo y estados no OK.
+
+## Pruebas
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+vc doctor
+```
+
+`vc doctor` redacta secretos intencionadamente y solo informa si los valores requeridos están configurados. También comprueba `instances/*.env` en busca de huellas de token duplicadas y rutas de ejecución en conflicto.

package/docs/i18n/USAGE.fr.md

@@ -0,0 +1,161 @@
+# Guide d'utilisation de VerbalCoding
+
+Cette page contient les détails opérationnels qui rendaient auparavant le README trop long.
+
+## Commandes CLI
+
+```bash
+vc status                    # show STT language, progress language, and TTS voice
+vc language en               # English STT + English progress/TTS voice
+vc language ko               # Korean STT + Korean progress/TTS voice
+vc language auto             # Whisper auto-detect STT + English progress/TTS voice
+vc restart auto status       # show commit-time voice-bot auto-restart setting
+vc restart auto on           # enable commit-time voice-bot auto-restart
+vc restart auto off          # disable it; this is the default
+vc bot invite CLIENT_ID      # print a Discord invite URL with required permissions
+vc instance status           # list per-instance bridge configs and process status
+vc instance setup NAME       # write instances/NAME.env and create ~/.hermes/profiles/NAME
+vc instance start NAME       # start ./run.sh instances/NAME.env detached
+vc instance stop NAME        # stop a detached instance and remove its pid file
+vc doctor                    # run the redacted doctor check
+npm run mcp                  # run the stdio MCP server
+```
+
+Les changements de langue mettent à jour `.env` ; redémarrez la passerelle avec `./run.sh` ou votre gestionnaire de processus pour qu'ils prennent effet.
+
+## Modes d'exécution
+
+Passerelle à instance unique :
+
+```bash
+./run.sh
+```
+
+Passerelle par instance avec un env de surcharge local :
+
+```bash
+./run.sh instances/my-project.env
+# or
+VERBALCODING_INSTANCE_ENV=instances/my-project.env ./run.sh
+```
+
+Le bot rejoint automatiquement le premier nom de salon configuré, par défaut `일반,General,general`.
+
+## Commandes Discord
+
+Avant de câbler les commandes, configurez l'application/le bot Discord avec les guides amont :
+
+- Guide Discord de Hermes Agent : <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Documentation officielle des bots Discord : <https://docs.discord.com/developers/bots/overview>
+
+Utilisez ensuite `vc bot invite CLIENT_ID` pour générer l'URL d'invitation propre à VerbalCoding avec permissions texte et voix.
+
+| Commande | Objectif |
+|---|---|
+| `!ping` | Vérification de base du bot |
+| `!join` / `!leave` | Rejoindre ou quitter la voix |
+| `!say <text>` | Énoncer directement du texte via TTS |
+| `!voice-test <text>` | Tester le backend/la voix TTS actif |
+| `!voice-clone capture` | Enregistrer la prochaine énonciation valide comme échantillon de référence OpenVoice |
+| `!voice-clone status` / `!voice-clone cancel` | Inspecter ou annuler la capture |
+| `!ask <prompt>` | Envoyer du texte via le même adaptateur de harnais sélectionné que la voix |
+| `!session status` | Afficher la session de projet/par défaut actuelle de l'adaptateur |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | Créer une session Hermes limitée à un projet |
+| `!session attach-voice [sessionName] --voice <voice-channel>` | Lier un salon/fil texte à un salon vocal |
+| `!session list` | Lister les sessions de projet configurées |
+| `!session reset` / `!reset-session` | Effacer le fichier de session de projet/par défaut actuel de l'adaptateur |
+| `!verbose on/off` | Activer/désactiver les mises à jour détaillées de progression |
+| `!latency` / `!metrics` | Afficher un résumé récent de la latence |
+| `!sensitivity normal/conservative` | Changer la sensibilité d'interruption |
+
+Les équivalents vocaux comme “외부 모드”, “보수 모드”, “실내”, “기본 감도” et les phrases d'arrêt claires comme “잠깐”, “멈춰”, “그만” sont gérés par la passerelle. Vous pouvez aussi dire “상세 진행 켜” / “상세 진행 꺼” pour activer/désactiver la progression détaillée par la voix.
+
+## Changer la voix
+
+`vc language ko|en|auto` change ensemble la langue STT, la langue de progression et la voix TTS par défaut correspondante. Si vous voulez seulement changer le locuteur/la voix pendant que la passerelle tourne, dites-le dans le vocal Discord :
+
+```text
+남자 한국어 목소리로 바꿔
+여자 한국어 목소리로 바꿔
+change voice to Korean female
+switch speaker to English
+```
+
+La passerelle en cours d'exécution reconnaît ces phrases comme des commandes vocales, met à jour `config/tts-voices.json`, met à jour l'env TTS effectif du processus actif et répond par une courte confirmation comme “목소리를 Korean male로 바꿨어.” Utilisez `!voice-test <text>` juste après le changement pour entendre le backend et la voix actuels.
+
+Types de voix Edge intégrés :
+
+| Type de voix | Voix Edge |
+|---|---|
+| `korean_male` | `ko-KR-InJoonNeural` |
+| `korean_female` | `ko-KR-SunHiNeural` |
+| `korean_multilingual_male` | `ko-KR-HyunsuMultilingualNeural` |
+| `english_male` | `en-US-GuyNeural` |
+| `english_female` | `en-US-AriaNeural` |
+
+Pour une configuration manuelle persistante, définissez `TTS_BACKEND=edge`, `TTS_VOICE_TYPE=<voice-type>` et éventuellement `TTS_VOICE=<edge-voice>` dans `.env`, ou modifiez `config/tts-voices.json` pour des catalogues de voix personnalisés.
+
+Réglages vocaux propres au backend :
+
+| Backend | Paramètre de voix | Choix courants |
+|---|---|---|
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | `korean_male`, `korean_female`, `korean_multilingual_male`, `english_male`, `english_female` ; toute voix Edge de `edge-tts --list-voices` |
+| Supertonic | `SUPERTONIC_VOICE` | `M1`–`M5`, `F1`–`F5` ; définissez `SUPERTONIC_LANGUAGE=ko|en|es|pt|fr` |
+| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE` | un WAV de référence autorisé plus un style comme `default` |
+| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER` | WAV de référence pour CosyVoice, ou valeurs locuteur/modèle prises en charge par le backend |
+
+Pour Supertonic et les backends de clonage locaux, utilisez les variables d'env ci-dessus ainsi que `!voice-test <text>` pour écouter les changements. Le changement par commande vocale mappe actuellement les types de voix intégrés de style Edge ; des catalogues de backends plus riches peuvent être ajoutés dans `config/tts-voices.json`.
+
+## Dictée longue et pauses
+
+VerbalCoding attend une fenêtre d'inactivité avant d'envoyer la parole au STT. La valeur par défaut `UTTERANCE_IDLE_MS=4500` est volontairement un peu patiente afin qu'une pause naturelle dans une longue instruction ne coupe pas la phrase, ne démarre pas un tour d'agent trop tôt, puis ne traite pas la suite comme une interruption pendant le traitement.
+
+Si vous préférez des commandes courtes plus rapides, diminuez-la dans `.env` ; si une longue dictée coréenne est encore coupée, augmentez-la :
+
+```bash
+UTTERANCE_IDLE_MS="6000"
+```
+
+## Mode progression détaillée
+
+La progression détaillée est désactivée par défaut sauf si `AGENT_VERBOSE_PROGRESS=1` est défini. Activez-la avec `!verbose on` ou une commande vocale comme “상세 진행 켜”. Elle peut émettre de courtes lignes de progression comme :
+
+```text
+🤖 Hermes Agent 호출 시작
+📖 파일 읽기 app-node/main.mjs
+🔎 웹 검색 실행
+⌨️ 터미널 명령 실행
+🤖 Hermes Agent 응답 수신
+```
+
+Ce mode demande au harnais CLI sélectionné d'émettre des lignes `VERBALCODING_PROGRESS: ...` et résume les marqueurs d'outils courants depuis stdout/stderr en streaming quand ils sont disponibles. Les champs ressemblant à des secrets sont expurgés et les lignes de progression sont retirées de la réponse finale énoncée.
+
+## Métriques de latence
+
+VerbalCoding écrit des enregistrements de latence par tour en JSONL. Chemin par défaut :
+
+```text
+./.logs/latency.jsonl
+```
+
+Chaque enregistrement inclut le statut, le temps total, le temps de capture vocale, l'attente d'inactivité de l'énonciation, le temps STT, le temps agent, le temps de synthèse/lecture TTS, le nombre de morceaux, la longueur de transcription, la longueur de réponse et les niveaux audio quand disponibles.
+
+Dans Discord :
+
+```text
+!latency
+!metrics
+```
+
+Le résumé utilise les 200 derniers enregistrements : nombre, moyenne, p95, maximum et statuts non-OK.
+
+## Tests
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+vc doctor
+```
+
+`vc doctor` expurge intentionnellement les secrets et indique seulement si les valeurs requises sont configurées. Il vérifie aussi `instances/*.env` pour détecter les empreintes de jetons dupliquées et les chemins d'exécution en collision.

package/docs/i18n/USAGE.ja.md

@@ -0,0 +1,161 @@
+# VerbalCoding 使い方ガイド
+
+このページには、README を長くしすぎていた運用上の詳細をまとめています。
+
+## CLI コマンド
+
+```bash
+vc status                    # STT 言語、進捗言語、TTS 音声を表示
+vc language en               # 英語 STT + 英語の進捗/TTS 音声
+vc language ko               # 韓国語 STT + 韓国語の進捗/TTS 音声
+vc language auto             # Whisper 自動検出 STT + 英語の進捗/TTS 音声
+vc restart auto status       # コミット時の音声ボット自動再起動設定を表示
+vc restart auto on           # コミット時の音声ボット自動再起動を有効化
+vc restart auto off          # 無効化。これがデフォルト
+vc bot invite CLIENT_ID      # 必要な権限付きの Discord 招待 URL を出力
+vc instance status           # インスタンスごとのブリッジ設定とプロセス状態を一覧表示
+vc instance setup NAME       # instances/NAME.env を書き、~/.hermes/profiles/NAME を作成
+vc instance start NAME       # ./run.sh instances/NAME.env をデタッチして起動
+vc instance stop NAME        # デタッチされたインスタンスを停止し pid ファイルを削除
+vc doctor                    # 秘密情報を伏せた doctor チェックを実行
+npm run mcp                  # stdio MCP サーバーを実行
+```
+
+言語変更は `.env` を更新します。反映するには `./run.sh` または利用中のプロセスマネージャーでブリッジを再起動してください。
+
+## 実行モード
+
+単一インスタンスのブリッジ:
+
+```bash
+./run.sh
+```
+
+ローカルの上書き env を使うインスタンス別ブリッジ:
+
+```bash
+./run.sh instances/my-project.env
+# または
+VERBALCODING_INSTANCE_ENV=instances/my-project.env ./run.sh
+```
+
+ボットは最初に設定されたチャンネル名へ自動参加します。デフォルトは `일반,General,general` です。
+
+## Discord コマンド
+
+コマンドを接続する前に、上流ガイドに従って Discord アプリケーション/ボットをセットアップしてください:
+
+- Hermes Agent の Discord ガイド: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Discord 公式ボットドキュメント: <https://docs.discord.com/developers/bots/overview>
+
+その後、`vc bot invite CLIENT_ID` を使って、テキストおよび音声権限を持つ VerbalCoding 専用の招待 URL を生成します。
+
+| コマンド | 目的 |
+|---|---|
+| `!ping` | 基本的なボット確認 |
+| `!join` / `!leave` | 音声に参加または退出 |
+| `!say <text>` | TTS でテキストを直接読み上げ |
+| `!voice-test <text>` | 有効な TTS バックエンド/音声をテスト |
+| `!voice-clone capture` | 次の有効な発話を OpenVoice 参照サンプルとして保存 |
+| `!voice-clone status` / `!voice-clone cancel` | キャプチャ状態を確認またはキャンセル |
+| `!ask <prompt>` | 音声と同じ選択済みハーネスアダプター経由でテキストを送信 |
+| `!session status` | 現在のプロジェクト/デフォルトアダプターセッションを表示 |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | プロジェクトスコープの Hermes セッションを作成 |
+| `!session attach-voice [sessionName] --voice <voice-channel>` | テキストチャンネル/スレッドを音声チャンネルに紐付け |
+| `!session list` | 設定済みプロジェクトセッションを一覧表示 |
+| `!session reset` / `!reset-session` | 現在のプロジェクト/デフォルトアダプターセッションファイルを消去 |
+| `!verbose on/off` | 詳細な進捗更新を切り替え |
+| `!latency` / `!metrics` | 直近のレイテンシ要約を表示 |
+| `!sensitivity normal/conservative` | 割り込み感度を切り替え |
+
+「외부 모드」「보수 모드」「실내」「기본 감도」などの音声での同等表現や、「잠깐」「멈춰」「그만」のような明確な停止フレーズはブリッジが処理します。また、「상세 진행 켜」/「상세 진행 꺼」と言うことで、音声でも詳細進捗を切り替えられます。
+
+## 音声を変更する
+
+`vc language ko|en|auto` は、STT 言語、進捗言語、対応するデフォルト TTS 音声をまとめて変更します。ブリッジの実行中に話者/音声だけを変更したい場合は、Discord 音声で次のように話します:
+
+```text
+남자 한국어 목소리로 바꿔
+여자 한국어 목소리로 바꿔
+change voice to Korean female
+switch speaker to English
+```
+
+実行中のブリッジはこれらを音声制御コマンドとして認識し、`config/tts-voices.json` を更新し、実行中プロセスの有効な TTS env を更新して、「목소리를 Korean male로 바꿨어。」のような短い確認で応答します。変更直後に `!voice-test <text>` を使うと、現在のバックエンドと音声を聞けます。
+
+組み込み Edge 音声タイプ:
+
+| 音声タイプ | Edge 音声 |
+|---|---|
+| `korean_male` | `ko-KR-InJoonNeural` |
+| `korean_female` | `ko-KR-SunHiNeural` |
+| `korean_multilingual_male` | `ko-KR-HyunsuMultilingualNeural` |
+| `english_male` | `en-US-GuyNeural` |
+| `english_female` | `en-US-AriaNeural` |
+
+永続的な手動設定では、`.env` に `TTS_BACKEND=edge`、`TTS_VOICE_TYPE=<voice-type>`、必要に応じて `TTS_VOICE=<edge-voice>` を設定するか、カスタム音声カタログ用に `config/tts-voices.json` を編集します。
+
+バックエンド固有の音声ノブ:
+
+| バックエンド | 音声設定 | 一般的な選択肢 |
+|---|---|---|
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | `korean_male`、`korean_female`、`korean_multilingual_male`、`english_male`、`english_female`。`edge-tts --list-voices` が返す任意の Edge 音声 |
+| Supertonic | `SUPERTONIC_VOICE` | `M1`〜`M5`、`F1`〜`F5`。`SUPERTONIC_LANGUAGE=ko|en|es|pt|fr` を設定 |
+| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE` | 許可済み参照 WAV と、`default` などのスタイル |
+| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER` | CosyVoice 用の参照 WAV、またはバックエンド対応の話者/モデル値 |
+
+Supertonic とローカルクローンバックエンドでは、上記のバックエンド env 変数に加えて `!voice-test <text>` を使い、変更を試聴してください。音声コマンドによる切り替えは、現在は組み込みの Edge 風音声タイプにマッピングされます。より豊富なバックエンドカタログは `config/tts-voices.json` に追加できます。
+
+## 長いディクテーションとポーズ
+
+VerbalCoding は、音声を STT に送る前に無音ウィンドウを待ちます。デフォルトの `UTTERANCE_IDLE_MS=4500` は意図的に少し余裕を持たせています。長い指示の自然な間で文を分割したり、エージェントターンを早く始めすぎたり、その後の発話を処理中の割り込みとして扱ったりしないためです。
+
+短いコマンドをより速くしたい場合は `.env` で小さくしてください。長い韓国語ディクテーションがまだ分割される場合は大きくしてください:
+
+```bash
+UTTERANCE_IDLE_MS="6000"
+```
+
+## 詳細進捗モード
+
+`AGENT_VERBOSE_PROGRESS=1` が設定されていない限り、詳細進捗はデフォルトでオフです。`!verbose on` または「상세 진행 켜」のような音声コマンドで有効にします。次のような短い進捗行を出力できます:
+
+```text
+🤖 Hermes Agent 호출 시작
+📖 파일 읽기 app-node/main.mjs
+🔎 웹 검색 실행
+⌨️ 터미널 명령 실행
+🤖 Hermes Agent 응답 수신
+```
+
+このモードは、選択された CLI ハーネスに `VERBALCODING_PROGRESS: ...` 行の出力を求め、利用可能な場合はストリーミング stdout/stderr から一般的なツールマーカーを要約します。秘密情報に見えるフィールドは伏せられ、進捗行は最終的に読み上げられる回答から削除されます。
+
+## レイテンシ指標
+
+VerbalCoding はターンごとのレイテンシ記録を JSONL として書き込みます。デフォルトパス:
+
+```text
+./.logs/latency.jsonl
+```
+
+各レコードには、ステータス、合計時間、音声キャプチャ時間、発話アイドル待ち、STT 時間、エージェント時間、TTS 合成/再生時間、チャンク数、文字起こし長、回答長、利用可能な場合の音声レベルが含まれます。
+
+Discord 内:
+
+```text
+!latency
+!metrics
+```
+
+要約は最新 200 件のレコードを使い、件数、平均、p95、最大、OK 以外のステータスを表示します。
+
+## テスト
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+vc doctor
+```
+
+`vc doctor` は意図的に秘密情報を伏せ、必要な値が設定されているかだけを報告します。また、`instances/*.env` について、重複するトークンフィンガープリントや衝突するランタイムパスも確認します。