verbalcoding 0.2.6 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/README.md +12 -22
  2. package/app-node/cli_install.test.mjs +15 -0
  3. package/docs/FRESH_INSTALL.md +8 -2
  4. package/docs/assets/figures/verbalcoding-flow.svg +45 -30
  5. package/docs/i18n/CONFIGURATION.es.md +239 -0
  6. package/docs/i18n/CONFIGURATION.fr.md +239 -0
  7. package/docs/i18n/CONFIGURATION.ja.md +239 -0
  8. package/docs/i18n/CONFIGURATION.ko.md +66 -74
  9. package/docs/i18n/CONFIGURATION.ru.md +239 -0
  10. package/docs/i18n/CONFIGURATION.zh.md +239 -0
  11. package/docs/i18n/FRESH_INSTALL.es.md +207 -0
  12. package/docs/i18n/FRESH_INSTALL.fr.md +207 -0
  13. package/docs/i18n/FRESH_INSTALL.ja.md +207 -0
  14. package/docs/i18n/FRESH_INSTALL.ko.md +60 -54
  15. package/docs/i18n/FRESH_INSTALL.ru.md +207 -0
  16. package/docs/i18n/FRESH_INSTALL.zh.md +207 -0
  17. package/docs/i18n/MULTI_INSTANCE.es.md +180 -0
  18. package/docs/i18n/MULTI_INSTANCE.fr.md +180 -0
  19. package/docs/i18n/MULTI_INSTANCE.ja.md +179 -0
  20. package/docs/i18n/MULTI_INSTANCE.ko.md +46 -46
  21. package/docs/i18n/MULTI_INSTANCE.ru.md +179 -0
  22. package/docs/i18n/MULTI_INSTANCE.zh.md +179 -0
  23. package/docs/i18n/README.es.md +83 -55
  24. package/docs/i18n/README.fr.md +85 -57
  25. package/docs/i18n/README.ja.md +83 -55
  26. package/docs/i18n/README.ko.md +47 -56
  27. package/docs/i18n/README.ru.md +86 -58
  28. package/docs/i18n/README.zh.md +83 -56
  29. package/docs/i18n/RELEASE.es.md +74 -0
  30. package/docs/i18n/RELEASE.fr.md +74 -0
  31. package/docs/i18n/RELEASE.ja.md +74 -0
  32. package/docs/i18n/RELEASE.ko.md +38 -36
  33. package/docs/i18n/RELEASE.ru.md +74 -0
  34. package/docs/i18n/RELEASE.zh.md +74 -0
  35. package/docs/i18n/USAGE.es.md +161 -0
  36. package/docs/i18n/USAGE.fr.md +161 -0
  37. package/docs/i18n/USAGE.ja.md +161 -0
  38. package/docs/i18n/USAGE.ko.md +61 -72
  39. package/docs/i18n/USAGE.ru.md +161 -0
  40. package/docs/i18n/USAGE.zh.md +161 -0
  41. package/package.json +1 -1
  42. package/scripts/bootstrap_prereqs.sh +15 -3
  43. package/scripts/cli.mjs +1 -1
  44. package/scripts/doctor.mjs +114 -8
@@ -0,0 +1,207 @@
1
+ # 全新安装
2
+
3
+ 本指南用于干净的公开安装。它避免依赖本地专用假设,并使用安装器尽可能完成引导。
4
+
5
+ ## 1. 安装 CLI
6
+
7
+ 推荐的 npm 路径:
8
+
9
+ ```bash
10
+ npm install -g verbalcoding
11
+ ```
12
+
13
+ 或者直接运行已发布的软件包:
14
+
15
+ ```bash
16
+ npx verbalcoding setup --yes
17
+ ```
18
+
19
+ 如果你使用了 `npm install -g`,继续运行:
20
+
21
+ ```bash
22
+ vc setup --yes
23
+ ```
24
+
25
+ 贡献者的 GitHub 克隆路径:
26
+
27
+ ```bash
28
+ git clone https://github.com/ca1773130n/VerbalCoding.git
29
+ cd VerbalCoding
30
+ ./scripts/install.sh --yes
31
+ ```
32
+
33
+ ## 2. 引导依赖并运行设置向导
34
+
35
+ 通过 npm 安装时,当前目录中没有仓库检出,因此不要直接运行 `./scripts/install.sh`。请改用打包好的 CLI 包装器:
36
+
37
+ ```bash
38
+ vc setup --yes
39
+ ```
40
+
41
+ `vc setup` 会运行已安装 npm 包内部的 `scripts/install.sh`。只有在 GitHub 克隆目录中时才使用 `./scripts/install.sh --yes`:
42
+
43
+ ```bash
44
+ ./scripts/install.sh --yes
45
+ ```
46
+
47
+ 它会执行以下操作:
48
+
49
+ - 当缺少 `node_modules/` 时安装 npm 依赖,
50
+ - 使用 `npm link` 安装简短的 `vc` shell 命令,
51
+ - 在 OS 包管理器支持时安装 `ffmpeg`、Node/npm 和 `whisper-cli`,
52
+ - 下载 `models/ggml-small-q5_1.bin`,
53
+ - 当 `PATH` 上尚无 `edge-tts` 时创建 `.venv-tts` 并安装 `edge-tts`,
54
+ - 运行交互式 `.env` 向导。
55
+
56
+ 支持的系统引导路径:
57
+
58
+ | OS | 系统依赖路径 |
59
+ |---|---|
60
+ | macOS | Homebrew:按需执行 `brew install node ffmpeg whisper-cpp` |
61
+ | Debian/Ubuntu | 使用 `apt-get` 安装 Node/npm、ffmpeg、Python、构建工具;本地 whisper.cpp 构建回退 |
62
+ | Fedora/RHEL | 使用 `dnf` 安装 Node/npm、ffmpeg、Python、构建工具;本地 whisper.cpp 构建回退 |
63
+ | Arch | 使用 `pacman` 安装 Node/npm、ffmpeg、Python、构建工具;本地 whisper.cpp 构建回退 |
64
+
65
+ 有用的安装器变体:
66
+
67
+ ```bash
68
+ vc setup --yes --no-wizard # 仅从 npm 安装进行依赖/引导
69
+ ./scripts/install.sh --yes --no-wizard # 仅从克隆仓库进行依赖/引导
70
+ ./scripts/install.sh --skip-system # 不安装 OS 软件包
71
+ ./scripts/install.sh --skip-model # 不下载默认 STT 模型
72
+ ./scripts/install.sh --skip-edge-tts # 不创建 .venv-tts
73
+ VERBALCODING_SKIP_CLI_LINK=1 ./scripts/install.sh --yes
74
+ ```
75
+
76
+ 如果你的 OS 不受支持,请先手动安装以下内容,再重新运行:
77
+
78
+ - Node.js 20+ 和 npm
79
+ - ffmpeg
80
+ - 带 venv/pip 的 Python 3
81
+ - whisper.cpp `whisper-cli`
82
+ - 一个已认证的 CLI 代理后端,默认是 Hermes Agent
83
+
84
+ ## 3. Discord 应用设置
85
+
86
+ 如果这是你的第一个机器人,请先阅读上游 Discord 机器人设置指南:
87
+
88
+ - Hermes Agent Discord 消息指南:<https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
89
+ - Discord 官方机器人概览:<https://docs.discord.com/developers/bots/overview>
90
+ - Discord 官方入门指南:<https://docs.discord.com/developers/quick-start/getting-started>
91
+
92
+ 这些页面展示如何创建 Discord 应用、添加机器人用户、启用特权 intents,并邀请它加入服务器。VerbalCoding 使用同样的 Discord 机器人设置,然后在其上增加语音接收、STT、CLI 代理执行和 TTS 播放。
93
+
94
+ 1. 在 Discord Developer Portal 中创建 Discord 应用和机器人。
95
+ 2. 启用 Message Content 特权 intent。
96
+ 3. 将机器人令牌复制到安装器提示或 `.env` 中的 `DISCORD_BOT_TOKEN`。
97
+ 4. 生成邀请 URL:
98
+
99
+ ```bash
100
+ vc bot invite <discord-client-id>
101
+ # 或将它固定到一个服务器:
102
+ vc bot invite <discord-client-id> --guild <guild-id>
103
+ ```
104
+
105
+ 该邀请包含 VerbalCoding 使用的 bot 和 slash-command scopes,以及文本/语音权限。
106
+
107
+ ## 4. 验证
108
+
109
+ ```bash
110
+ vc doctor
111
+ ```
112
+
113
+ `vc doctor` 会脱敏输出:它报告缺失的令牌/命令/模型,但不会打印密钥值。当可修复的本地前置依赖缺失(`ffmpeg`、`whisper-cli`、默认模型或 Edge TTS 辅助环境)时,它会先自动重新运行打包的引导程序。修复剩余的 `✗` 项,然后重新运行。
114
+
115
+ 预期成功输出包括:
116
+
117
+ ```text
118
+ ✓ Node.js
119
+ ✓ npm
120
+ ✓ ffmpeg
121
+ ✓ whisper-cli
122
+ ✓ whisper.cpp model
123
+ ✓ Discord bot token configured — [REDACTED]
124
+ ✓ edge-tts
125
+ ✓ hermes CLI
126
+ Doctor passed. Run vc start to start VerbalCoding.
127
+ ```
128
+
129
+ 如果安装器创建了本地 Edge TTS 辅助环境,`.env` 应包含指向 `.venv-tts/bin/edge-tts` 的 `EDGE_TTS_COMMAND` 路径。
130
+
131
+ ## 5. 运行单个默认机器人
132
+
133
+ ```bash
134
+ vc start
135
+ # 或者,从 GitHub 克隆仓库中:
136
+ ./run.sh
137
+ ```
138
+
139
+ 成功启动日志包括:
140
+
141
+ ```text
142
+ Logged in as <bot-name>
143
+ Listening in voice channel <server> / <channel>
144
+ ```
145
+
146
+ 在 Discord 中:
147
+
148
+ ```text
149
+ !ping
150
+ !join
151
+ !ask say hello briefly
152
+ !verbose on
153
+ ```
154
+
155
+ 然后在已配置的语音频道中说话。你应该会看到 STT 文本、详细模式开启时的进度文本、最终文本答案,并听到 TTS 播放。
156
+
157
+ ## 6. 每个项目一个房间的设置
158
+
159
+ 如果希望每个项目语音房间都有一个长期机器人,请为每个项目创建一个 Discord 应用,然后运行:
160
+
161
+ ```bash
162
+ vc instance setup my-project
163
+ vc bot invite <that-project-client-id>
164
+ vc instance start my-project
165
+ vc instance status my-project
166
+ ```
167
+
168
+ 每个实例都会写入一个被忽略的 `instances/<name>.env`,其中包含自己的令牌、语音频道、转写目标、日志路径、Hermes 会话文件和可选 Hermes profile。
169
+
170
+ ## 7. 可选 OpenVoice 设置
171
+
172
+ OpenVoice 语音克隆是可选的。全新公开安装请保留 `TTS_BACKEND=edge`。之后若要启用 OpenVoice:
173
+
174
+ ```bash
175
+ ./scripts/setup_openvoice.sh
176
+ # 将 OpenVoice V2 checkpoints 下载到 vendor/OpenVoice/checkpoints_v2/
177
+ # 在 voice-samples/user-reference.wav 放入一个获准使用的本地样本,
178
+ # 或运行机器人,说“목소리 샘플 녹음 시작해”,然后说话 10-30 秒。
179
+ python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-audio voice-samples/user-reference.wav --text '안녕하세요. 버벌코딩 목소리 복제 테스트입니다.' --output /tmp/verbalcoding-openvoice-smoke.wav
180
+ ```
181
+
182
+ 然后设置 `TTS_BACKEND=openvoice`,运行 `vc doctor`,并在 Discord 中测试 `!voice-test <text>`。
183
+
184
+ ## 8. 维护者的干净克隆冒烟测试
185
+
186
+ 快速的仅主机冒烟测试:
187
+
188
+ ```bash
189
+ TMPDIR=$(mktemp -d)
190
+ git clone https://github.com/ca1773130n/VerbalCoding.git "$TMPDIR/VerbalCoding"
191
+ cd "$TMPDIR/VerbalCoding"
192
+ ./scripts/install.sh --yes --no-wizard
193
+ npm pack --dry-run
194
+ cp .env.example .env
195
+ chmod 600 .env
196
+ vc doctor || true
197
+ ```
198
+
199
+ 此时预期失败应是缺少本地密钥或未认证的代理 CLI,而不是令牌泄漏或安装脚本缺失。
200
+
201
+ 基于 Docker 的 Ubuntu 干净安装冒烟测试:
202
+
203
+ ```bash
204
+ ./scripts/docker_ubuntu_smoke.sh
205
+ ```
206
+
207
+ 它会运行 `ubuntu:24.04`,将已跟踪的仓库树复制到干净容器中,执行 `./scripts/install.sh --yes --no-wizard`,写入无密钥的冒烟 `.env`,检查 `vc`,运行 Node 测试,并验证 `vc doctor`。它不会连接 Discord 语音;如果需要端到端语音频道测试,请在此之后使用真实 Ubuntu VM 或 WSL2。
@@ -0,0 +1,180 @@
1
+ # VerbalCoding multiinstancia
2
+
3
+ VerbalCoding puede ejecutar múltiples procesos independientes de puente de voz de Discord. Cada proceso sigue siendo el puente Node de instancia única existente, pero carga un archivo `instances/<name>.env` diferente y usa un token de bot de Discord diferente.
4
+
5
+ Usa esto cuando cada proyecto deba ocupar permanentemente su propio canal de voz de Discord y escribir en su propio canal/hilo de transcripción.
6
+
7
+ ## Por qué se requieren varios tokens de bot
8
+
9
+ La residencia de voz de Discord es efectivamente una conexión de voz activa por cuenta de bot y por guild. Si un token de bot se une a otro canal de voz en la misma guild, no puede permanecer también conectado de forma permanente al canal anterior. Para salas de proyecto simultáneas, crea una aplicación/bot de Discord por proyecto.
10
+
11
+ ## Diseño de archivos
12
+
13
+ ```text
14
+ instances/
15
+ README.md
16
+ example.env
17
+ llm-wiki.env # local only, ignored by git
18
+ verbalcoding.env # local only, ignored by git
19
+ .run/instances/
20
+ llm-wiki.pid # runtime only, ignored by git
21
+ ```
22
+
23
+ Los archivos reales `instances/*.env` se ignoran porque pueden contener tokens de Discord. `instances/example.env` es la plantilla versionada.
24
+
25
+ ## Asistente de configuración de instancia
26
+
27
+ Los usuarios no deberían copiar y editar manualmente archivos env para el uso normal. Ejecuta el asistente en su lugar:
28
+
29
+ ```bash
30
+ vc instance setup llm-wiki
31
+ # o mediante el script de configuración del proyecto:
32
+ ./scripts/install.sh --instance llm-wiki
33
+ ```
34
+
35
+ El asistente solicita el token del bot, ID de aplicación/cliente de Discord, canal de voz, destino de transcripción, workdir, contexto del proyecto y rutas de ejecución aisladas. Escribe `instances/<name>.env` con modo `0600`, hace una copia de seguridad del archivo existente antes de sobrescribirlo e imprime los siguientes comandos de inicio/estado.
36
+
37
+ Si introduces el ID de aplicación/cliente de Discord durante la configuración, el resumen también imprime la URL de invitación de ese bot. Puedes generar la misma URL en cualquier momento con:
38
+
39
+ ```bash
40
+ vc bot invite <client-id>
41
+ vc bot invite <client-id> --guild <guild-id>
42
+ ```
43
+
44
+ Discord sigue requiriendo una aplicación/bot del Developer Portal por sala de voz simultánea, pero esto evita construir manualmente URLs OAuth o enteros de permisos.
45
+
46
+ ### Aislamiento de perfiles de Hermes
47
+
48
+ Cada instancia obtiene su propio home de Hermes en `~/.hermes/profiles/<name>` para que memoria, MEMORY.md, SOUL.md y skills aprendidas no se filtren entre proyectos.
49
+
50
+ `vc instance setup <name>` automáticamente:
51
+
52
+ - ejecuta `hermes profile create <name> --clone-from default` (traslada claves API
53
+ y modelo desde tu `~/.hermes` actual; las sesiones y memoria empiezan limpias),
54
+ - define el `terminal.cwd` del nuevo perfil al workdir de la instancia,
55
+ - inicializa `<profile>/SOUL.md` desde la respuesta de contexto de proyecto del asistente,
56
+ - escribe `HERMES_HOME=...` en `instances/<name>.env`.
57
+
58
+ `vc instance start <name>` se autorepara: si el env apunta a un directorio de perfil de Hermes que ya no existe, el comando de inicio lo recrea antes de lanzar.
59
+
60
+ Los nombres de instancia deben coincidir con `^[a-z0-9][a-z0-9_-]{0,63}$` porque Hermes usa el nombre como directorio y clave de configuración.
61
+
62
+ ## Env mínimo generado para una instancia
63
+
64
+ ```env
65
+ INSTANCE_NAME=my-project
66
+ DISCORD_TOKEN=replac...oken
67
+ DISCORD_CLIENT_ID=123456789012345678
68
+ AUTO_JOIN_VOICE_CHANNELS=Project Room
69
+ TRANSCRIPT_CHANNEL_ID=123456789012345678
70
+ PROJECT_SESSIONS_FILE=config/project-sessions.my-project.json
71
+ BRIDGE_LOG_PATH=/tmp/verbalcoding-my-project.log
72
+ NODE_AUDIO_DEBUG_DIR=/tmp/verbalcoding-my-project-debug
73
+ HERMES_SESSION_FILE=.agent-sessions/hermes/my-project.session
74
+ HERMES_HOME=/home/you/.hermes/profiles/my-project
75
+ AGENT_LABEL=VerbalCoding · My Project
76
+ AGENT_CWD=/path/to/my-project
77
+ AGENT_PROJECT_CONTEXT=Project session: My Project
78
+ ```
79
+
80
+ Da a cada instancia valores únicos para archivos de registro/depuración/sesión. `HERMES_HOME` y el directorio correspondiente `~/.hermes/profiles/<name>` se crean automáticamente con `vc instance setup`. `vc doctor` comprueba tokens duplicados, rutas de ejecución en conflicto, directorios de perfil faltantes y discrepancias de `terminal.cwd` entre perfil e instancia, todo sin imprimir secretos.
81
+
82
+ ## Comandos
83
+
84
+ ```bash
85
+ vc instance list
86
+ vc instance status
87
+ vc instance status my-project
88
+ vc instance start my-project
89
+ vc instance stop my-project
90
+ vc instance restart my-project
91
+ ```
92
+
93
+ `start` ejecuta `./run.sh instances/<name>.env` desacoplado y escribe `.run/instances/<name>.pid`.
94
+
95
+ `stop` envía `SIGTERM`, espera hasta 10 segundos, luego recurre a `SIGKILL` y elimina el archivo pid.
96
+
97
+ ## Ejemplo: dos salas de voz permanentes
98
+
99
+ 1. Crea dos aplicaciones/bots de Discord:
100
+ - Bot VerbalCoding
101
+ - Bot LLM-Wiki
102
+
103
+ 2. Invita ambos al servidor con permisos de texto y voz:
104
+ - Ver canal
105
+ - Enviar mensajes
106
+ - Enviar mensajes en hilos
107
+ - Leer historial de mensajes
108
+ - Usar comandos de aplicación
109
+ - Conectar
110
+ - Hablar
111
+
112
+ Usa `vc bot invite <client-id>` después de crear cada aplicación de Discord para imprimir la URL de invitación exacta con esos permisos.
113
+
114
+ 3. Ejecuta el asistente de configuración para cada instancia local:
115
+
116
+ ```bash
117
+ vc instance setup verbalcoding
118
+ vc instance setup llm-wiki
119
+ ```
120
+
121
+ El asistente escribe los archivos ignorados `instances/verbalcoding.env` e `instances/llm-wiki.env` con modo `0600`; también hace copia de seguridad de un env de instancia existente antes de reemplazarlo. Cada ejecución también crea `~/.hermes/profiles/<name>` clonado desde tu home de Hermes predeterminado, de modo que las dos instancias empiezan con la misma autenticación/modelo, pero acumulan memoria y skills independientes a medida que aprenden cada proyecto.
122
+
123
+ 4. Comprueba la configuración:
124
+
125
+ ```bash
126
+ vc doctor
127
+ ```
128
+
129
+ 5. Inicia ambos:
130
+
131
+ ```bash
132
+ vc instance start verbalcoding
133
+ vc instance start llm-wiki
134
+ vc instance status
135
+ ```
136
+
137
+ 6. Verifica los registros:
138
+
139
+ ```bash
140
+ tail -n 50 /tmp/verbalcoding-verbalcoding.log
141
+ tail -n 50 /tmp/verbalcoding-llm-wiki.log
142
+ ```
143
+
144
+ Líneas de registro esperadas:
145
+
146
+ ```text
147
+ Listening in voice channel ... / VerbalCoding
148
+ Listening in voice channel ... / LLM-Wiki
149
+ ```
150
+
151
+ 7. Detén ambos:
152
+
153
+ ```bash
154
+ vc instance stop verbalcoding
155
+ vc instance stop llm-wiki
156
+ ```
157
+
158
+ ## Vinculación de texto/voz de corto plazo con un solo bot
159
+
160
+ Si solo tienes un token de bot, usa vinculación de voz de sesión de proyecto en lugar de residencia multicanal simultánea.
161
+
162
+ Ejecuta esto en el canal/hilo de texto objetivo:
163
+
164
+ ```text
165
+ !session attach-voice --voice "LLM-Wiki"
166
+ ```
167
+
168
+ Comportamiento:
169
+
170
+ - Vincula el canal de voz seleccionado al canal/hilo de texto actual.
171
+ - Si el canal de texto actual no tiene sesión de proyecto, crea una sesión aislada ad hoc.
172
+ - El texto de STT/resultado/progreso/respuesta final de voz se enruta al destino de transcripción de ese proyecto activo.
173
+
174
+ Para adjuntar una sesión de proyecto nombrada existente:
175
+
176
+ ```text
177
+ !session voice llm-wiki --voice "LLM-Wiki"
178
+ ```
179
+
180
+ Esto es conveniente para el enrutamiento, pero no hace que un bot permanezca en dos canales de voz al mismo tiempo. Usa varios tokens/procesos de bot para residencia permanente simultánea.
@@ -0,0 +1,180 @@
1
+ # VerbalCoding multi-instance
2
+
3
+ VerbalCoding peut exécuter plusieurs processus indépendants de passerelle vocale Discord. Chaque processus reste la passerelle Node à instance unique existante, mais il charge un fichier `instances/<name>.env` différent et utilise un jeton de bot Discord différent.
4
+
5
+ Utilisez ceci quand chaque projet doit occuper de façon permanente son propre salon vocal Discord et écrire dans son propre salon/fil de transcription.
6
+
7
+ ## Pourquoi plusieurs jetons de bot sont nécessaires
8
+
9
+ La résidence vocale Discord correspond en pratique à une connexion vocale active par compte bot et par guilde. Si un jeton de bot rejoint un autre salon vocal dans la même guilde, il ne peut pas aussi rester connecté en permanence au salon précédent. Pour des salons de projet simultanés, créez une application/un bot Discord par projet.
10
+
11
+ ## Organisation des fichiers
12
+
13
+ ```text
14
+ instances/
15
+ README.md
16
+ example.env
17
+ llm-wiki.env # local only, ignored by git
18
+ verbalcoding.env # local only, ignored by git
19
+ .run/instances/
20
+ llm-wiki.pid # runtime only, ignored by git
21
+ ```
22
+
23
+ Les vrais fichiers `instances/*.env` sont ignorés car ils peuvent contenir des jetons Discord. `instances/example.env` est le modèle commité.
24
+
25
+ ## Assistant de configuration d'instance
26
+
27
+ Les utilisateurs ne doivent pas copier et modifier manuellement les fichiers env pour un usage normal. Lancez plutôt l'assistant :
28
+
29
+ ```bash
30
+ vc instance setup llm-wiki
31
+ # or through the project setup script:
32
+ ./scripts/install.sh --instance llm-wiki
33
+ ```
34
+
35
+ L'assistant demande le jeton du bot, l'ID Application/Client Discord, le salon vocal, la cible de transcription, le workdir, le contexte de projet et les chemins d'exécution isolés. Il écrit `instances/<name>.env` avec le mode `0600`, sauvegarde un fichier existant avant de l'écraser et imprime les prochaines commandes de démarrage/statut.
36
+
37
+ Si vous saisissez l'ID Application/Client Discord pendant la configuration, le résumé imprime aussi l'URL d'invitation de ce bot. Vous pouvez générer la même URL à tout moment avec :
38
+
39
+ ```bash
40
+ vc bot invite <client-id>
41
+ vc bot invite <client-id> --guild <guild-id>
42
+ ```
43
+
44
+ Discord exige toujours une application/un bot Developer Portal par salon vocal simultané, mais cela évite de construire manuellement des URL OAuth ou des entiers de permissions.
45
+
46
+ ### Isolation des profils Hermes
47
+
48
+ Chaque instance reçoit son propre dossier Hermes à `~/.hermes/profiles/<name>` afin que la mémoire, MEMORY.md, SOUL.md et les skills appris ne fuient pas entre projets.
49
+
50
+ `vc instance setup <name>` automatiquement :
51
+
52
+ - exécute `hermes profile create <name> --clone-from default` (reprend les clés API
53
+ et le modèle de votre `~/.hermes` actuel ; les sessions et la mémoire repartent de zéro),
54
+ - définit le `terminal.cwd` du nouveau profil sur le workdir de l'instance,
55
+ - initialise `<profile>/SOUL.md` depuis la réponse de contexte de projet de l'assistant,
56
+ - écrit `HERMES_HOME=...` dans `instances/<name>.env`.
57
+
58
+ `vc instance start <name>` s'auto-répare : si l'env pointe vers un répertoire de profil Hermes qui n'existe plus, la commande start le recrée avant le lancement.
59
+
60
+ Les noms d'instance doivent correspondre à `^[a-z0-9][a-z0-9_-]{0,63}$`, car Hermes utilise le nom comme répertoire et clé de configuration.
61
+
62
+ ## Env minimal généré pour une instance
63
+
64
+ ```env
65
+ INSTANCE_NAME=my-project
66
+ DISCORD_TOKEN=replac...oken
67
+ DISCORD_CLIENT_ID=123456789012345678
68
+ AUTO_JOIN_VOICE_CHANNELS=Project Room
69
+ TRANSCRIPT_CHANNEL_ID=123456789012345678
70
+ PROJECT_SESSIONS_FILE=config/project-sessions.my-project.json
71
+ BRIDGE_LOG_PATH=/tmp/verbalcoding-my-project.log
72
+ NODE_AUDIO_DEBUG_DIR=/tmp/verbalcoding-my-project-debug
73
+ HERMES_SESSION_FILE=.agent-sessions/hermes/my-project.session
74
+ HERMES_HOME=/home/you/.hermes/profiles/my-project
75
+ AGENT_LABEL=VerbalCoding · My Project
76
+ AGENT_CWD=/path/to/my-project
77
+ AGENT_PROJECT_CONTEXT=Project session: My Project
78
+ ```
79
+
80
+ Donnez à chaque instance des valeurs uniques pour les fichiers de journal/debug/session. `HERMES_HOME` et le répertoire correspondant `~/.hermes/profiles/<name>` sont créés automatiquement par `vc instance setup`. `vc doctor` vérifie les jetons dupliqués, les chemins d'exécution en collision, les répertoires de profil manquants et les divergences de `terminal.cwd` entre profil et instance — le tout sans imprimer de secrets.
81
+
82
+ ## Commandes
83
+
84
+ ```bash
85
+ vc instance list
86
+ vc instance status
87
+ vc instance status my-project
88
+ vc instance start my-project
89
+ vc instance stop my-project
90
+ vc instance restart my-project
91
+ ```
92
+
93
+ `start` exécute `./run.sh instances/<name>.env` en mode détaché et écrit `.run/instances/<name>.pid`.
94
+
95
+ `stop` envoie `SIGTERM`, attend jusqu'à 10 secondes, puis bascule vers `SIGKILL` et supprime le fichier pid.
96
+
97
+ ## Exemple : deux salons vocaux permanents
98
+
99
+ 1. Créez deux applications/bots Discord :
100
+ - bot VerbalCoding
101
+ - bot LLM-Wiki
102
+
103
+ 2. Invitez les deux sur le serveur avec permissions texte et voix :
104
+ - Voir le salon
105
+ - Envoyer des messages
106
+ - Envoyer des messages dans les fils
107
+ - Lire l'historique des messages
108
+ - Utiliser les commandes d'application
109
+ - Se connecter
110
+ - Parler
111
+
112
+ Utilisez `vc bot invite <client-id>` après avoir créé chaque application Discord pour imprimer l'URL d'invitation exacte avec ces permissions.
113
+
114
+ 3. Lancez l'assistant de configuration pour chaque instance locale :
115
+
116
+ ```bash
117
+ vc instance setup verbalcoding
118
+ vc instance setup llm-wiki
119
+ ```
120
+
121
+ L'assistant écrit les fichiers ignorés `instances/verbalcoding.env` et `instances/llm-wiki.env` avec le mode `0600` ; il sauvegarde aussi l'env d'une instance existante avant de le remplacer. Chaque exécution crée également `~/.hermes/profiles/<name>` cloné depuis votre dossier Hermes par défaut, afin que les deux instances démarrent avec la même auth/le même modèle mais accumulent mémoire et skills indépendants à mesure qu'elles apprennent chaque projet.
122
+
123
+ 4. Vérifiez la configuration :
124
+
125
+ ```bash
126
+ vc doctor
127
+ ```
128
+
129
+ 5. Démarrez les deux :
130
+
131
+ ```bash
132
+ vc instance start verbalcoding
133
+ vc instance start llm-wiki
134
+ vc instance status
135
+ ```
136
+
137
+ 6. Vérifiez les journaux :
138
+
139
+ ```bash
140
+ tail -n 50 /tmp/verbalcoding-verbalcoding.log
141
+ tail -n 50 /tmp/verbalcoding-llm-wiki.log
142
+ ```
143
+
144
+ Lignes de journal attendues :
145
+
146
+ ```text
147
+ Listening in voice channel ... / VerbalCoding
148
+ Listening in voice channel ... / LLM-Wiki
149
+ ```
150
+
151
+ 7. Arrêtez les deux :
152
+
153
+ ```bash
154
+ vc instance stop verbalcoding
155
+ vc instance stop llm-wiki
156
+ ```
157
+
158
+ ## Liaison texte/voix de courte durée avec un seul bot
159
+
160
+ Si vous n'avez qu'un seul jeton de bot, utilisez plutôt la liaison vocale de session de projet au lieu d'une résidence multi-salons simultanée.
161
+
162
+ Exécutez ceci dans le salon/fil texte cible :
163
+
164
+ ```text
165
+ !session attach-voice --voice "LLM-Wiki"
166
+ ```
167
+
168
+ Comportement :
169
+
170
+ - Lie le salon vocal sélectionné au salon/fil texte actuel.
171
+ - Si le salon texte actuel n'a pas de session de projet, crée une session isolée ad hoc.
172
+ - Le texte STT/résultat/progression/réponse finale de la voix est routé vers cette cible de transcription de projet active.
173
+
174
+ Pour attacher une session de projet nommée existante :
175
+
176
+ ```text
177
+ !session voice llm-wiki --voice "LLM-Wiki"
178
+ ```
179
+
180
+ C'est pratique pour le routage, mais cela ne fait pas rester un même bot dans deux salons vocaux en même temps. Utilisez plusieurs jetons/processus de bots pour une résidence permanente simultanée.