better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/use-soul-with-hermes.md

@@ -0,0 +1,264 @@
+---
+sidebar_position: 7
+title: "在 Hermes 中使用 SOUL.md"
+description: "如何使用 SOUL.md 塑造 Hermes Agent 的默认风格，哪些内容应放在其中，以及它与 AGENTS.md 和 /personality 的区别"
+---
+
+# 在 Hermes 中使用 SOUL.md
+
+`SOUL.md` 是你的 Hermes 实例的**主要身份标识**。它是系统提示词（system prompt）中的第一项内容——定义了 Agent 是谁、如何表达，以及应避免什么。
+
+如果你希望每次与 Hermes 交谈时都感受到一致的助手风格，或者想用自己的角色完全替换 Hermes 的默认人设，这就是你需要编辑的文件。
+
+## SOUL.md 的用途
+
+`SOUL.md` 适用于：
+- 语气
+- 个性
+- 沟通风格
+- Hermes 应有多直接或多温和
+- Hermes 在风格上应避免什么
+- Hermes 如何应对不确定性、分歧和模糊情况
+
+简而言之：
+- `SOUL.md` 关注的是 Hermes 是谁，以及 Hermes 如何表达
+
+## SOUL.md 不适用的内容
+
+不要在其中放置：
+- 特定代码仓库的编码规范
+- 文件路径
+- 命令
+- 服务端口
+- 架构说明
+- 项目工作流指令
+
+这些内容属于 `AGENTS.md`。
+
+一个简单的判断原则：
+- 如果某项内容应在所有地方生效，放入 `SOUL.md`
+- 如果某项内容只属于某个项目，放入 `AGENTS.md`
+
+## 文件位置
+
+Hermes 目前仅使用当前实例的全局 SOUL 文件：
+
+```text
+~/.hermes/SOUL.md
+```
+
+如果你使用自定义主目录运行 Hermes，路径变为：
+
+```text
+$HERMES_HOME/SOUL.md
+```
+
+## 首次运行行为
+
+如果 `SOUL.md` 尚不存在，Hermes 会自动为你生成一个初始文件。
+
+这意味着大多数用户一开始就有一个可以立即阅读和编辑的真实文件。
+
+注意：
+- 如果你已有 `SOUL.md`，Hermes 不会覆盖它
+- 如果文件存在但为空，Hermes 不会从中向提示词添加任何内容
+
+## Hermes 如何使用它
+
+Hermes 启动会话时，会从 `HERMES_HOME` 读取 `SOUL.md`，扫描其中的提示词注入（prompt-injection）模式，必要时进行截断，并将其作为 **Agent 身份标识**——系统提示词中的第 1 个槽位。这意味着 `SOUL.md` 会完全替换内置的默认身份文本。
+
+如果 `SOUL.md` 缺失、为空或无法加载，Hermes 将回退到内置的默认身份。
+
+文件内容不会被任何包装语言包裹。内容本身才是关键——按照你希望 Agent 思考和表达的方式来写。
+
+## 第一次编辑建议
+
+如果你只做一件事，打开文件并修改几行，让它感觉像你自己的风格。
+
+例如：
+
+```markdown
+You are direct, calm, and technically precise.
+Prefer substance over politeness theater.
+Push back clearly when an idea is weak.
+Keep answers compact unless deeper detail is useful.
+```
+
+仅此一项就能明显改变 Hermes 的感觉。
+
+## 示例风格
+
+### 1. 务实工程师
+
+```markdown
+You are a pragmatic senior engineer.
+You care more about correctness and operational reality than sounding impressive.
+
+## Style
+- Be direct
+- Be concise unless complexity requires depth
+- Say when something is a bad idea
+- Prefer practical tradeoffs over idealized abstractions
+
+## Avoid
+- Sycophancy
+- Hype language
+- Overexplaining obvious things
+```
+
+### 2. 研究伙伴
+
+```markdown
+You are a thoughtful research collaborator.
+You are curious, honest about uncertainty, and excited by unusual ideas.
+
+## Style
+- Explore possibilities without pretending certainty
+- Distinguish speculation from evidence
+- Ask clarifying questions when the idea space is underspecified
+- Prefer conceptual depth over shallow completeness
+```
+
+### 3. 教师／讲解者
+
+```markdown
+You are a patient technical teacher.
+You care about understanding, not performance.
+
+## Style
+- Explain clearly
+- Use examples when they help
+- Do not assume prior knowledge unless the user signals it
+- Build from intuition to details
+```
+
+### 4. 严格审阅者
+
+```markdown
+You are a rigorous reviewer.
+You are fair, but you do not soften important criticism.
+
+## Style
+- Point out weak assumptions directly
+- Prioritize correctness over harmony
+- Be explicit about risks and tradeoffs
+- Prefer blunt clarity to vague diplomacy
+```
+
+## 什么是优质的 SOUL.md？
+
+优质的 `SOUL.md` 具备以下特点：
+- 稳定
+- 广泛适用
+- 风格具体
+- 不堆砌临时指令
+
+劣质的 `SOUL.md` 则是：
+- 充斥项目细节
+- 自相矛盾
+- 试图微观管理每一个回复的形式
+- 大量泛泛之词，如"要有帮助"和"要清晰"
+
+Hermes 本身已经尽力做到有帮助且清晰。`SOUL.md` 应当赋予真实的个性和风格，而不是重申显而易见的默认行为。
+
+## 建议结构
+
+不需要标题，但标题有助于组织内容。
+
+一个实用的简单结构：
+
+```markdown
+# Identity
+Who Hermes is.
+
+# Style
+How Hermes should sound.
+
+# Avoid
+What Hermes should not do.
+
+# Defaults
+How Hermes should behave when ambiguity appears.
+```
+
+## SOUL.md 与 /personality 的区别
+
+两者互为补充。
+
+使用 `SOUL.md` 作为持久的基础设定。
+使用 `/personality` 进行临时的模式切换。
+
+示例：
+- 你的默认 SOUL 是务实且直接的
+- 某次会话中你使用 `/personality teacher`
+- 之后切换回来，无需修改基础风格文件
+
+## SOUL.md 与 AGENTS.md 的区别
+
+这是最常见的误用。
+
+### 放入 SOUL.md 的内容
+- "Be direct."
+- "Avoid hype language."
+- "Prefer short answers unless depth helps."
+- "Push back when the user is wrong."
+
+### 放入 AGENTS.md 的内容
+- "Use pytest, not unittest."
+- "Frontend lives in `frontend/`."
+- "Never edit migrations directly."
+- "The API runs on port 8000."
+
+## 如何编辑
+
+```bash
+nano ~/.hermes/SOUL.md
+```
+
+或
+
+```bash
+vim ~/.hermes/SOUL.md
+```
+
+然后重启 Hermes 或开启新会话。
+
+## 实用工作流
+
+1. 从自动生成的默认文件开始
+2. 删除不符合你期望风格的内容
+3. 添加 4–8 行清晰定义语气和默认行为的文字
+4. 与 Hermes 交谈一段时间
+5. 根据仍感觉不对的地方进行调整
+
+这种迭代方式比一次性设计完美人设更有效。
+
+## 故障排查
+
+### 我编辑了 SOUL.md，但 Hermes 听起来还是一样
+
+检查：
+- 你编辑的是 `~/.hermes/SOUL.md` 或 `$HERMES_HOME/SOUL.md`
+- 而不是某个仓库本地的 `SOUL.md`
+- 文件不为空
+- 编辑后已重启会话
+- 没有 `/personality` 覆盖层主导了结果
+
+### Hermes 忽略了我 SOUL.md 中的部分内容
+
+可能原因：
+- 更高优先级的指令覆盖了它
+- 文件中包含相互冲突的指导内容
+- 文件过长被截断
+- 部分文本类似提示词注入内容，可能被扫描器拦截或修改
+
+### 我的 SOUL.md 变得过于项目化
+
+将项目指令移入 `AGENTS.md`，保持 `SOUL.md` 专注于身份标识和风格。
+
+## 相关文档
+
+- [个性与 SOUL.md](/user-guide/features/personality)
+- [上下文文件](/user-guide/features/context-files)
+- [配置](/user-guide/configuration)
+- [技巧与最佳实践](/guides/tips)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/use-voice-mode-with-hermes.md

@@ -0,0 +1,469 @@
+---
+sidebar_position: 8
+title: "在 Hermes 中使用语音模式"
+description: "在 CLI、Telegram、Discord 及 Discord 语音频道中设置和使用 Hermes 语音模式的实用指南"
+---
+
+# 在 Hermes 中使用语音模式
+
+本指南是[语音模式功能参考](/user-guide/features/voice-mode)的实用配套文档。
+
+功能页面介绍语音模式能做什么，本指南则说明如何真正用好它。
+
+## 语音模式适合哪些场景
+
+语音模式在以下情况特别有用：
+- 需要免手持的 CLI 工作流
+- 希望在 Telegram 或 Discord 中获得语音回复
+- 希望 Hermes 加入 Discord 语音频道进行实时对话
+- 边走动边快速记录想法、调试问题或来回交流，而不是打字
+
+## 选择你的语音模式方案
+
+Hermes 中实际上有三种不同的语音体验。
+
+| 模式 | 最适合 | 平台 |
+|---|---|---|
+| 交互式麦克风循环 | 编码或研究时的个人免手持使用 | CLI |
+| 聊天中的语音回复 | 在正常消息旁附带语音回复 | Telegram、Discord |
+| 实时语音频道机器人 | 在语音频道中进行群组或个人实时对话 | Discord 语音频道 |
+
+推荐路径：
+1. 先让文本模式正常工作
+2. 再启用语音回复
+3. 最后如需完整体验，再切换到 Discord 语音频道
+
+## 第一步：确保普通 Hermes 先正常运行
+
+在接触语音模式之前，请确认：
+- Hermes 能正常启动
+- 已配置好 provider（提供商）
+- Agent 能正常回答文本 prompt（提示词）
+
+```bash
+hermes
+```
+
+问一个简单的问题：
+
+```text
+What tools do you have available?
+```
+
+如果文本模式还不稳定，请先修复它。
+
+## 第二步：安装所需的额外依赖
+
+### CLI 麦克风 + 播放
+
+```bash
+cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"
+```
+
+### 消息平台
+
+```bash
+cd ~/.hermes/hermes-agent && uv pip install -e ".[messaging]"
+```
+
+### 高级 ElevenLabs TTS
+
+```bash
+cd ~/.hermes/hermes-agent && uv pip install -e ".[tts-premium]"
+```
+
+### 本地 NeuTTS（可选）
+
+```bash
+python -m pip install -U neutts[all]
+```
+
+### 全部安装
+
+```bash
+cd ~/.hermes/hermes-agent && uv pip install -e ".[all]"
+```
+
+## 第三步：安装系统依赖
+
+### macOS
+
+```bash
+brew install portaudio ffmpeg opus
+brew install espeak-ng
+```
+
+### Ubuntu / Debian
+
+```bash
+sudo apt install portaudio19-dev ffmpeg libopus0
+sudo apt install espeak-ng
+```
+
+各依赖的作用：
+- `portaudio` → CLI 语音模式的麦克风输入与播放
+- `ffmpeg` → TTS 和消息传递的音频转换
+- `opus` → Discord 语音编解码器支持
+- `espeak-ng` → NeuTTS 的 phonemizer 后端
+
+## 第四步：选择 STT 和 TTS 提供商
+
+Hermes 同时支持本地和云端语音处理方案。
+
+### 最简单 / 最低成本的方案
+
+使用本地 STT 和免费的 Edge TTS：
+- STT provider：`local`
+- TTS provider：`edge`
+
+这通常是最好的起点。
+
+### 环境变量文件示例
+
+添加到 `~/.hermes/.env`：
+
+```bash
+# 云端 STT 选项（本地无需密钥）
+GROQ_API_KEY=***
+VOICE_TOOLS_OPENAI_KEY=***
+
+# 高级 TTS（可选）
+ELEVENLABS_API_KEY=***
+```
+
+### Provider 推荐
+
+#### 语音转文字（STT）
+
+- `local` → 隐私保护和零成本使用的最佳默认选项
+- `groq` → 极快的云端转录
+- `openai` → 良好的付费备选
+
+#### 文字转语音（TTS）
+
+- `edge` → 免费，对大多数用户已足够
+- `neutts` → 免费的本地/设备端 TTS
+- `elevenlabs` → 最佳质量
+- `openai` → 良好的中间选项
+- `mistral` → 多语言，原生 Opus
+
+### 如果使用 `hermes setup`
+
+如果你在设置向导中选择了 NeuTTS，Hermes 会检查 `neutts` 是否已安装。如果缺失，向导会告知你 NeuTTS 需要 Python 包 `neutts` 和系统包 `espeak-ng`，并提供自动安装，使用平台包管理器安装 `espeak-ng`，然后运行：
+
+```bash
+python -m pip install -U neutts[all]
+```
+
+如果跳过安装或安装失败，向导会回退到 Edge TTS。
+
+## 第五步：推荐配置
+
+```yaml
+voice:
+  record_key: "ctrl+b"
+  submit_mode: "direct"  # TUI：direct | draft
+  max_recording_seconds: 120
+  auto_tts: false
+  beep_enabled: true
+  silence_threshold: 200
+  silence_duration: 3.0
+
+stt:
+  provider: "local"
+  local:
+    model: "base"
+
+tts:
+  provider: "edge"
+  edge:
+    voice: "en-US-AriaNeural"
+```
+
+这是适合大多数人的保守默认配置。
+
+在 TUI 中，`voice.submit_mode` 控制转写完成后的行为：
+
+- `direct`（默认）会立即提交转写文本。
+- `draft` 会把转写文本放入输入框，供你编辑或取消，按 Enter 后才发送。
+
+如需可编辑的语音草稿，请设置：
+
+```yaml
+voice:
+  submit_mode: "draft"
+```
+
+如果想改用本地 TTS，将 `tts` 块替换为：
+
+```yaml
+tts:
+  provider: "neutts"
+  neutts:
+    ref_audio: ''
+    ref_text: ''
+    model: neuphonic/neutts-air-q4-gguf
+    device: cpu
+```
+
+## 使用场景一：CLI 语音模式
+
+## 开启方式
+
+启动 Hermes：
+
+```bash
+hermes
+```
+
+在 CLI 内执行：
+
+```text
+/voice on
+```
+
+### 录音流程
+
+默认按键：
+- `Ctrl+B`
+
+工作流程：
+1. 按下 `Ctrl+B`
+2. 说话
+3. 等待静音检测自动停止录音
+4. Hermes 转录并回复
+5. 如果开启了 TTS，它会朗读答案
+6. 循环可自动重启以持续使用
+
+### 常用命令
+
+```text
+/voice
+/voice on
+/voice off
+/voice tts
+/voice status
+```
+
+### 推荐的 CLI 工作流
+
+#### 随走随调试
+
+说：
+
+```text
+I keep getting a docker permission error. Help me debug it.
+```
+
+然后继续免手持操作：
+- "再读一遍最后的错误"
+- "用更简单的语言解释根本原因"
+- "现在给我精确的修复方案"
+
+#### 研究 / 头脑风暴
+
+非常适合：
+- 边走动边思考
+- 口述半成形的想法
+- 让 Hermes 实时整理你的思路
+
+#### 无障碍 / 少打字场景
+
+如果打字不方便，语音模式是保持完整 Hermes 工作流的最快方式之一。
+
+## 调整 CLI 行为
+
+### 静音阈值
+
+如果 Hermes 开始/停止过于激进，调整：
+
+```yaml
+voice:
+  silence_threshold: 250
+```
+
+阈值越高 = 灵敏度越低。
+
+### 静音时长
+
+如果你在句子之间经常停顿，增大该值：
+
+```yaml
+voice:
+  silence_duration: 4.0
+```
+
+### 录音按键
+
+如果 `Ctrl+B` 与你的终端或 tmux 习惯冲突：
+
+```yaml
+voice:
+  record_key: "ctrl+space"
+```
+
+## 使用场景二：Telegram 或 Discord 中的语音回复
+
+此模式比完整语音频道更简单。
+
+Hermes 仍作为普通聊天机器人运行，但可以朗读回复。
+
+### 启动 gateway
+
+```bash
+hermes gateway
+```
+
+### 开启语音回复
+
+在 Telegram 或 Discord 中：
+
+```text
+/voice on
+```
+
+或
+
+```text
+/voice tts
+```
+
+### 模式说明
+
+| 模式 | 含义 |
+|---|---|
+| `off` | 仅文本 |
+| `voice_only` | 仅当用户发送语音时才朗读 |
+| `all` | 朗读每条回复 |
+
+### 何时使用哪种模式
+
+- `/voice on`：仅对语音来源的消息给出语音回复
+- `/voice tts`：始终作为完整语音助手运行
+
+### 推荐的消息平台工作流
+
+#### 手机上的 Telegram 助手
+
+适用于：
+- 离开电脑时
+- 发送语音备忘并获取快速语音回复
+- 希望 Hermes 充当便携式研究或运维助手
+
+#### Discord 私信中的语音输出
+
+适用于希望私密交互、避免服务器频道 @mention 行为的场景。
+
+## 使用场景三：Discord 语音频道
+
+这是最高级的模式。
+
+Hermes 加入 Discord 语音频道（VC），监听用户语音，转录后运行正常的 agent 流水线，并将回复朗读回频道。
+
+## 所需的 Discord 权限
+
+除了普通文本机器人设置外，请确保机器人拥有：
+- Connect（连接）
+- Speak（发言）
+- 最好还有 Use Voice Activity（使用语音活动）
+
+同时在开发者门户中启用特权 intent（意图）：
+- Presence Intent
+- Server Members Intent
+- Message Content Intent
+
+## 加入与离开
+
+在机器人所在的 Discord 文本频道中：
+
+```text
+/voice join
+/voice leave
+/voice status
+```
+
+### 加入后的行为
+
+- 用户在语音频道中说话
+- Hermes 检测语音边界
+- 转录内容发布到关联的文本频道
+- Hermes 以文字和音频形式回复
+- 文本频道为执行 `/voice join` 的那个频道
+
+### Discord 语音频道使用最佳实践
+
+- 严格限制 `DISCORD_ALLOWED_USERS`
+- 先使用专用的机器人/测试频道
+- 在尝试语音频道模式之前，先确认 STT 和 TTS 在普通文本聊天语音模式下正常工作
+
+## 语音质量建议
+
+### 最佳质量方案
+
+- STT：本地 `large-v3` 或 Groq `whisper-large-v3`
+- TTS：ElevenLabs
+
+### 最佳速度 / 便利性方案
+
+- STT：本地 `base` 或 Groq
+- TTS：Edge
+
+### 最佳零成本方案
+
+- STT：本地
+- TTS：Edge
+
+## 常见故障模式
+
+### "No audio device found"
+
+安装 `portaudio`。
+
+### "机器人加入但听不到声音"
+
+检查：
+- 你的 Discord 用户 ID 是否在 `DISCORD_ALLOWED_USERS` 中
+- 你是否处于静音状态
+- 特权 intent 是否已启用
+- 机器人是否拥有 Connect/Speak 权限
+
+### "能转录但不说话"
+
+检查：
+- TTS provider 配置
+- ElevenLabs 或 OpenAI 的 API 密钥 / 配额
+- Edge 转换路径的 `ffmpeg` 安装情况
+
+### "Whisper 输出乱码"
+
+尝试：
+- 更安静的环境
+- 提高 `silence_threshold`
+- 更换 STT provider/模型
+- 更短、更清晰的表达
+
+### "在私信中正常但在服务器频道中不工作"
+
+这通常是 mention（提及）策略问题。
+
+默认情况下，除非另行配置，机器人在 Discord 服务器文本频道中需要被 `@mention` 才会响应。
+
+## 建议的第一周方案
+
+如果你想走最短的成功路径：
+
+1. 让文本 Hermes 正常工作
+2. 运行 `hermes setup voice` 以启用语音支持
+3. 使用本地 STT + Edge TTS 的 CLI 语音模式
+4. 然后在 Telegram 或 Discord 中启用 `/voice on`
+5. 只有在此之后，再尝试 Discord 语音频道模式
+
+这种递进方式可以将调试范围控制到最小。
+
+## 下一步阅读
+
+- [语音模式功能参考](/user-guide/features/voice-mode)
+- [消息 Gateway](/user-guide/messaging)
+- [Discord 设置](/user-guide/messaging/discord)
+- [Telegram 设置](/user-guide/messaging/telegram)
+- [配置](/user-guide/configuration)