verbalcoding 0.2.6 → 0.2.8

package/docs/i18n/USAGE.ko.md

@@ -1,45 +1,37 @@
 # VerbalCoding 사용 가이드
 
-이 문서는 README에 다 넣기에는 긴 실제 운영 방법을 모아 둔 사용 설명서입니다.
+이 페이지에는 README를 너무 길게 만들던 운영 세부 정보가 담겨 있습니다.
 
 ## CLI 명령
 
 ```bash
-vc setup --yes                # npm 설치 후 의존성 부트스트랩과 설정 마법사 실행
-vc start                      # 기본 Discord 음성 브릿지 시작
-vc status                     # STT 언어, 진행 언어, TTS 음성 상태 보기
-vc language en                # 영어 STT + 영어 진행/TTS 음성
-vc language ko                # 한국어 STT + 한국어 진행/TTS 음성
-vc language auto              # Whisper 자동 언어 감지 + 진행/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 프로필 생성
-vc instance start NAME        # ./run.sh instances/NAME.env를 백그라운드로 시작
-vc instance stop NAME         # 백그라운드 인스턴스 중지 및 pid 파일 제거
-vc doctor                     # 비밀값을 숨긴 상태 점검 실행
-npm run mcp                   # stdio MCP 서버 실행
+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`를 수정합니다. 적용하려면 `vc start`, `./run.sh`, 또는 사용 중인 프로세스 매니저로 브릿지를 재시작하세요.
+언어 변경은 `.env`를 업데이트합니다. 적용하려면 `./run.sh` 또는 사용 중인 프로세스 관리자로 브리지를 다시 시작하세요.
 
 ## 실행 모드
 
-npm으로 설치한 기본 브릿지:
-
-```bash
-vc start
-```
-
-GitHub 클론에서 직접 실행:
+단일 인스턴스 브리지:
 
 ```bash
 ./run.sh
 ```
 
-프로젝트별 인스턴스 env로 실행:
+로컬 override env를 사용하는 인스턴스별 브리지:
 
 ```bash
 ./run.sh instances/my-project.env
@@ -47,40 +39,40 @@ GitHub 클론에서 직접 실행:
 VERBALCODING_INSTANCE_ENV=instances/my-project.env ./run.sh
 ```
 
-봇은 설정된 음성 채널 이름 중 첫 번째로 자동 입장합니다. 기본값은 `일반,General,general`입니다.
+봇은 설정된 첫 번째 채널 이름에 자동 참가하며 기본값은 `일반,General,general`입니다.
 
 ## Discord 명령
 
-명령을 연결하기 전에 먼저 상위 문서대로 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을 만들 수 있습니다.
+그런 다음 `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>` | 음성과 같은 선택된 CLI 어댑터로 텍스트 요청 보내기 |
-| `!session status` | 현재 프로젝트/default 에이전트 세션 보기 |
-| `!session new <name> <workdir> [context] --voice <voice-channel>` | 프로젝트 단위 Hermes 세션 생성 |
-| `!session attach-voice [sessionName] --voice <voice-channel>` | 현재 텍스트 채널/스레드를 음성 채널에 연결 |
-| `!session list` | 설정된 프로젝트 세션 목록 보기 |
-| `!session reset` / `!reset-session` | 현재 프로젝트/default 세션 파일 초기화 |
-| `!verbose on/off` | 자세한 진행 업데이트 켜기/끄기 |
-| `!latency` / `!metrics` | 최근 지연 시간 요약 보기 |
+| `!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` | 끼어들기 감도 전환 |
 
-음성으로도 “외부 모드”, “보수 모드”, “실내”, “기본 감도” 같은 감도 전환과 “잠깐”, “멈춰”, “그만” 같은 명확한 중단 표현을 처리합니다. “상세 진행 켜” / “상세 진행 꺼”처럼 말해서 verbose progress도 바꿀 수 있습니다.
+“외부 모드”, “보수 모드”, “실내”, “기본 감도” 같은 음성 표현과 “잠깐”, “멈춰”, “그만” 같은 명확한 중지 문구는 브리지가 처리합니다. “상세 진행 켜” / “상세 진행 꺼”라고 말해 음성으로 자세한 진행을 전환할 수도 있습니다.
 
-## 목소리 변경
+## 음성 변경
 
-`vc language ko|en|auto`는 STT 언어, 진행 언어, 기본 TTS 목소리를 함께 바꿉니다. 언어 전체가 아니라 말하는 사람/목소리만 바꾸고 싶다면 Discord 음성에서 이렇게 말하면 됩니다.
+`vc language ko|en|auto`는 STT 언어, 진행 언어, 해당 기본 TTS 음성을 함께 변경합니다. 브리지가 실행 중일 때 화자/음성만 바꾸고 싶다면 Discord 음성으로 말하세요:
 
 ```text
 남자 한국어 목소리로 바꿔
@@ -89,11 +81,11 @@ change voice to Korean female
 switch speaker to English
 ```
 
-실행 중인 브릿지는 이 발화를 제어 명령으로 인식해 `config/tts-voices.json`을 갱신하고, 현재 프로세스의 TTS 설정도 바로 바꾼 뒤 “목소리를 Korean male로 바꿨어.” 같은 짧은 확인을 말합니다. 바꾼 직후에는 `!voice-test <text>`로 현재 백엔드와 목소리를 바로 들어볼 수 있습니다.
+실행 중인 브리지는 이를 음성 제어 명령으로 인식하고 `config/tts-voices.json`을 업데이트하며, 실행 중 프로세스의 유효 TTS env를 업데이트하고 “목소리를 Korean male로 바꿨어.” 같은 짧은 확인으로 응답합니다. 변경 직후 `!voice-test <text>`로 현재 백엔드와 음성을 들어보세요.
 
-기본 Edge 목소리 타입:
+내장 Edge 음성 유형:
 
-| 목소리 타입 | Edge voice |
+| 음성 유형 | Edge 음성 |
 |---|---|
 | `korean_male` | `ko-KR-InJoonNeural` |
 | `korean_female` | `ko-KR-SunHiNeural` |
@@ -101,24 +93,24 @@ switch speaker to English
 | `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`에서 관리할 수 있습니다.
+수동 영구 설정은 `.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 voice |
-| Supertonic | `SUPERTONIC_VOICE` | `M1`–`M5`, `F1`–`F5`; `SUPERTONIC_LANGUAGE=ko|en|es|pt|fr` |
-| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE` | 사용 허가가 있는 reference WAV와 `default` 같은 style |
-| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER` | CosyVoice reference WAV 또는 백엔드가 지원하는 speaker/model 값 |
+| 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과 로컬 clone 백엔드는 위 env를 바꾼 뒤 `!voice-test <text>`로 바로 들어보세요. 현재 음성 명령 기반 전환은 기본 Edge-style voice type에 매핑되어 있고, 더 풍부한 백엔드 카탈로그는 `config/tts-voices.json`에 추가할 수 있습니다.
+Supertonic 및 로컬 복제 백엔드에서는 위 백엔드 env 변수와 `!voice-test <text>`를 사용해 변경 사항을 청음하세요. 음성 명령 전환은 현재 내장 Edge 스타일 음성 유형에 매핑됩니다. 더 풍부한 백엔드 카탈로그는 `config/tts-voices.json`에 추가할 수 있습니다.
 
-## 긴 발화와 중간 멈춤
+## 긴 받아쓰기와 멈춤
 
-VerbalCoding은 말을 STT로 보내기 전에 idle window를 기다립니다. 기본값 `UTTERANCE_IDLE_MS=4500`은 일부러 조금 여유 있게 잡혀 있습니다. 긴 지시 중 자연스러운 멈춤을 문장 끝으로 오해해 앞부분만 에이전트에 보내고, 뒷부분을 processing 중 끼어들기로 처리하는 문제를 줄이기 위해서입니다.
+VerbalCoding은 음성을 STT로 보내기 전에 유휴 구간을 기다립니다. 기본 `UTTERANCE_IDLE_MS=4500`은 일부러 약간 여유 있게 잡혀 있어, 긴 지시 중 자연스러운 멈춤 때문에 문장이 나뉘거나 에이전트 턴이 너무 일찍 시작되고 나머지가 처리 중 끼어들기로 취급되는 일을 방지합니다.
 
-짧은 명령 반응을 더 빠르게 하고 싶다면 `.env`에서 낮추고, 긴 한국어 dictation이 여전히 잘리면 더 올리세요.
+짧은 명령을 더 빠르게 처리하고 싶다면 `.env`에서 낮추세요. 긴 한국어 받아쓰기가 여전히 나뉜다면 높이세요:
 
 ```bash
 UTTERANCE_IDLE_MS="6000"
@@ -126,29 +118,27 @@ UTTERANCE_IDLE_MS="6000"
 
 ## 자세한 진행 모드
 
-자세한 진행은 기본적으로 꺼져 있습니다. `.env`에 `AGENT_VERBOSE_PROGRESS=1`을 설정하거나 Discord에서 `!verbose on`, 또는 음성으로 “상세 진행 켜”라고 말해 켤 수 있습니다.
-
-켜져 있으면 긴 작업 중 이런 짧은 진행 줄을 텍스트로 보냅니다.
+`AGENT_VERBOSE_PROGRESS=1`이 설정되지 않은 한 자세한 진행은 기본적으로 꺼져 있습니다. `!verbose on` 또는 “상세 진행 켜” 같은 음성 명령으로 활성화하세요. 다음과 같은 짧은 진행 줄을 내보낼 수 있습니다:
 
 ```text
-🤖 에이전트 호출 시작
+🤖 Hermes Agent 호출 시작
 📖 파일 읽기 app-node/main.mjs
 🔎 웹 검색 실행
 ⌨️ 터미널 명령 실행
-🤖 에이전트 응답 수신
+🤖 Hermes Agent 응답 수신
 ```
 
-이 모드는 선택된 CLI 하네스에 `VERBALCODING_PROGRESS: ...` 줄을 내보내도록 요청하고, 가능하면 stdout/stderr의 일반적인 도구 사용 흔적도 요약합니다. 비밀값처럼 보이는 필드는 숨기고, 진행 줄은 최종 음성 답변에서 제거합니다.
+이 모드는 선택된 CLI 하네스에 `VERBALCODING_PROGRESS: ...` 줄을 내보내도록 요청하고, 가능한 경우 스트리밍 stdout/stderr에서 일반적인 도구 표시자를 요약합니다. 비밀처럼 보이는 필드는 가려지고 진행 줄은 최종 음성 답변에서 제거됩니다.
 
 ## 지연 시간 지표
 
-VerbalCoding은 각 턴의 지연 시간 기록을 JSONL로 저장합니다. 기본 경로:
+VerbalCoding은 턴별 지연 시간 기록을 JSONL로 작성합니다. 기본 경로:
 
 ```text
 ./.logs/latency.jsonl
 ```
 
-각 기록에는 상태, 전체 시간, 음성 캡처 시간, 발화 idle 대기, STT 시간, 에이전트 시간, TTS 합성/재생 시간, 청크 수, 발화 길이, 답변 길이, 가능한 경우 오디오 레벨이 포함됩니다.
+각 기록에는 상태, 총 시간, 음성 캡처 시간, 발화 유휴 대기, STT 시간, 에이전트 시간, TTS 합성/재생 시간, 청크 수, 전사 길이, 답변 길이, 가능한 경우 오디오 레벨이 포함됩니다.
 
 Discord에서:
 
@@ -157,7 +147,7 @@ Discord에서:
 !metrics
 ```
 
-요약은 최근 200개 기록 기준으로 count, average, p95, max, non-OK 상태를 보여줍니다.
+요약은 최신 200개 기록을 사용합니다: 개수, 평균, p95, 최대값, OK가 아닌 상태.
 
 ## 테스트
 
@@ -165,8 +155,7 @@ Discord에서:
 node --check app-node/main.mjs
 npm test
 bash -n run.sh scripts/install.sh
-npm pack --dry-run
 vc doctor
 ```
 
-`vc doctor`는 비밀값을 출력하지 않고 필수 값이 설정됐는지만 확인합니다. 또한 `instances/*.env`에서 중복 토큰 지문과 충돌하는 런타임 경로를 검사합니다.
+`vc doctor`는 의도적으로 비밀 정보를 가리고 필수 값이 설정되었는지만 보고합니다. 또한 중복 토큰 지문과 충돌하는 런타임 경로가 있는지 `instances/*.env`를 확인합니다.

package/docs/i18n/USAGE.ru.md

@@ -0,0 +1,161 @@
+# Руководство по использованию VerbalCoding
+
+Эта страница содержит эксплуатационные подробности, которые раньше делали README слишком длинным.
+
+## 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
+```
+
+Изменения языка обновляют `.env`; перезапустите bridge через `./run.sh` или ваш менеджер процессов, чтобы они вступили в силу.
+
+## Режимы запуска
+
+Bridge с одним экземпляром:
+
+```bash
+./run.sh
+```
+
+Bridge для отдельного экземпляра с локальным override env:
+
+```bash
+./run.sh instances/my-project.env
+# or
+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`, чтобы сгенерировать URL приглашения VerbalCoding с текстовыми и голосовыми разрешениями.
+
+| Команда | Назначение |
+|---|---|
+| `!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` | Переключить чувствительность перебивания |
+
+Голосовые эквиваленты вроде “외부 모드”, “보수 모드”, “실내”, “기본 감도” и ясные стоп-фразы вроде “잠깐”, “멈춰”, “그만” обрабатываются bridge. Также можно сказать “상세 진행 켜” / “상세 진행 꺼”, чтобы переключить подробный прогресс голосом.
+
+## Изменение голоса
+
+`vc language ko|en|auto` одновременно меняет язык STT, язык прогресса и соответствующий голос TTS по умолчанию. Если нужно изменить только диктора/голос во время работы bridge, скажите это голосом в Discord:
+
+```text
+남자 한국어 목소리로 바꿔
+여자 한국어 목소리로 바꿔
+change voice to Korean female
+switch speaker to English
+```
+
+Работающий bridge распознаёт это как команды управления голосом, обновляет `config/tts-voices.json`, обновляет эффективное TTS-окружение для текущего процесса и отвечает коротким подтверждением вроде “목소리를 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` |
+
+Для постоянной ручной конфигурации задайте `TTS_BACKEND=edge`, `TTS_VOICE_TYPE=<voice-type>` и, при необходимости, `TTS_VOICE=<edge-voice>` в `.env` либо отредактируйте `config/tts-voices.json` для пользовательских каталогов голосов.
+
+Параметры голоса для конкретных бэкендов:
+
+| Бэкенд | Настройка голоса | Распространённые варианты |
+|---|---|---|
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | `korean_male`, `korean_female`, `korean_multilingual_male`, `english_male`, `english_female`; любой голос Edge из `edge-tts --list-voices` |
+| 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` | референсный WAV для CosyVoice или поддерживаемые бэкендом значения диктора/модели |
+
+Для Supertonic и локальных бэкендов клонирования используйте переменные окружения бэкенда выше плюс `!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` на повторяющиеся отпечатки токенов и конфликтующие runtime-пути.

package/docs/i18n/USAGE.zh.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>` | 将文本频道/thread 绑定到语音频道 |
+| `!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 vars 加 `!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` 中是否存在重复令牌指纹和冲突的运行时路径。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verbalcoding",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Discord voice bridge for CLI coding agents.",
   "license": "MIT",
   "repository": {

package/scripts/bootstrap_prereqs.sh

@@ -79,13 +79,25 @@ install_system_linux_packages() {
   if has_cmd apt-get; then
     log 'Installing Linux packages with apt-get'
     run_sudo apt-get update
-    run_sudo apt-get install -y curl ca-certificates git python3 python3-venv python3-pip build-essential cmake pkg-config ffmpeg nodejs npm
+    local packages=(curl ca-certificates git python3 python3-venv python3-pip build-essential cmake pkg-config ffmpeg)
+    # npm installs often run under NodeSource Node.js, whose `nodejs` package conflicts
+    # with Ubuntu's separate `npm` package. Do not request nodejs/npm again when the
+    # current npm-based installer is already running with working node and npm.
+    has_cmd node || packages+=(nodejs)
+    has_cmd npm || packages+=(npm)
+    run_sudo apt-get install -y "${packages[@]}"
   elif has_cmd dnf; then
     log 'Installing Linux packages with dnf'
-    run_sudo dnf install -y curl ca-certificates git python3 python3-pip gcc gcc-c++ make cmake pkgconf-pkg-config ffmpeg nodejs npm
+    local packages=(curl ca-certificates git python3 python3-pip gcc gcc-c++ make cmake pkgconf-pkg-config ffmpeg)
+    has_cmd node || packages+=(nodejs)
+    has_cmd npm || packages+=(npm)
+    run_sudo dnf install -y "${packages[@]}"
   elif has_cmd pacman; then
     log 'Installing Linux packages with pacman'
-    run_sudo pacman -Sy --needed --noconfirm curl ca-certificates git python python-pip base-devel cmake pkgconf ffmpeg nodejs npm
+    local packages=(curl ca-certificates git python python-pip base-devel cmake pkgconf ffmpeg)
+    has_cmd node || packages+=(nodejs)
+    has_cmd npm || packages+=(npm)
+    run_sudo pacman -Sy --needed --noconfirm "${packages[@]}"
   else
     warn 'No supported Linux package manager found. Install node/npm, ffmpeg, python3, git, cmake, and a C++ toolchain manually.'
     return 1

package/scripts/cli.mjs

@@ -292,7 +292,7 @@ async function main(argv = process.argv.slice(2)) {
   }
   if (command === 'doctor') {
     const { spawnSync } = await import('node:child_process');
-    const result = spawnSync(process.execPath, [path.join(ROOT, 'scripts', 'doctor.mjs')], { stdio: 'inherit', cwd: ROOT });
+    const result = spawnSync(process.execPath, [path.join(ROOT, 'scripts', 'doctor.mjs'), ...argv.slice(1)], { stdio: 'inherit', cwd: ROOT });
     process.exitCode = result.status ?? 1;
     return;
   }