better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/team-telegram-assistant.md

@@ -0,0 +1,441 @@
+---
+sidebar_position: 4
+title: "教程：团队 Telegram 助手"
+description: "逐步指南：为整个团队搭建一个 Telegram 机器人，用于代码帮助、研究、系统管理等"
+---
+
+# 搭建团队 Telegram 助手
+
+本教程将引导你搭建一个由 Hermes Agent 驱动的 Telegram 机器人，供多名团队成员使用。完成后，你的团队将拥有一个共享 AI 助手，可以向它发消息寻求代码、研究、系统管理等方面的帮助——并通过按用户授权保障安全。
+
+## 我们要构建什么
+
+一个 Telegram 机器人，具备以下能力：
+
+- **任何已授权的团队成员**都可以私信寻求帮助——代码审查、研究、Shell 命令、调试
+- **运行在你的服务器上**，拥有完整工具访问权限——终端、文件编辑、网络搜索、代码执行
+- **按用户会话隔离**——每个人拥有独立的对话上下文
+- **默认安全**——只有经过审批的用户才能交互，支持两种授权方式
+- **定时任务**——每日站会、健康检查和提醒推送到团队频道
+
+---
+
+## 前提条件
+
+开始前，请确保你已具备：
+
+- **已在服务器或 VPS 上安装 Hermes Agent**（不是你的笔记本——机器人需要持续运行）。如尚未安装，请参阅[安装指南](/getting-started/installation)。
+- **一个 Telegram 账号**（机器人所有者）
+- **已配置 LLM 提供商**——至少在 `~/.hermes/.env` 中配置了 OpenAI、Anthropic 或其他受支持提供商的 API 密钥
+
+:::tip
+一台 $5/月的 VPS 足以运行 gateway（网关）。Hermes 本身很轻量——花钱的是 LLM API 调用，而那些调用发生在远端。
+:::
+
+---
+
+## 第一步：创建 Telegram 机器人
+
+每个 Telegram 机器人都从 **@BotFather** 开始——这是 Telegram 官方用于创建机器人的机器人。
+
+1. **打开 Telegram**，搜索 `@BotFather`，或访问 [t.me/BotFather](https://t.me/BotFather)
+
+2. **发送 `/newbot`**——BotFather 会询问两件事：
+   - **显示名称**——用户看到的名字（例如 `Team Hermes Assistant`）
+   - **用户名**——必须以 `bot` 结尾（例如 `myteam_hermes_bot`）
+
+3. **复制机器人 token**——BotFather 会回复类似内容：
+   ```
+   Use this token to access the HTTP API:
+   7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
+   ```
+   保存此 token——下一步会用到。
+
+4. **设置描述**（可选，但推荐）：
+   ```
+   /setdescription
+   ```
+   选择你的机器人，然后输入类似内容：
+   ```
+   Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.
+   ```
+
+5. **设置机器人命令**（可选——为用户提供命令菜单）：
+   ```
+   /setcommands
+   ```
+   选择你的机器人，然后粘贴：
+   ```
+   new - Start a fresh conversation
+   model - Show or change the AI model
+   status - Show session info
+   help - Show available commands
+   stop - Stop the current task
+   ```
+
+:::warning
+请妥善保管你的机器人 token。任何持有该 token 的人都可以控制机器人。如果泄露，请在 BotFather 中使用 `/revoke` 生成新 token。
+:::
+
+---
+
+## 第二步：配置 Gateway
+
+你有两种选择：交互式设置向导（推荐）或手动配置。
+
+### 方式 A：交互式设置（推荐）
+
+```bash
+hermes gateway setup
+```
+
+通过方向键选择完成所有配置。选择 **Telegram**，粘贴你的机器人 token，并在提示时输入你的用户 ID。
+
+### 方式 B：手动配置
+
+在 `~/.hermes/.env` 中添加以下内容：
+
+```bash
+# Telegram bot token from BotFather
+TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
+
+# Your Telegram user ID (numeric)
+TELEGRAM_ALLOWED_USERS=123456789
+```
+
+### 查找你的用户 ID
+
+你的 Telegram 用户 ID 是一个数字值（不是你的用户名）。查找方式：
+
+1. 在 Telegram 上给 [@userinfobot](https://t.me/userinfobot) 发消息
+2. 它会立即回复你的数字用户 ID
+3. 将该数字填入 `TELEGRAM_ALLOWED_USERS`
+
+:::info
+Telegram 用户 ID 是永久性数字，例如 `123456789`。它与可以更改的 `@username` 不同。白名单中请始终使用数字 ID。
+:::
+
+---
+
+## 第三步：启动 Gateway
+
+### 快速测试
+
+先在前台运行 gateway，确认一切正常：
+
+```bash
+hermes gateway
+```
+
+你应该看到类似输出：
+
+```
+[Gateway] Starting Hermes Gateway...
+[Gateway] Telegram adapter connected
+[Gateway] Cron scheduler started (tick every 60s)
+```
+
+打开 Telegram，找到你的机器人，发送一条消息。如果它回复了，说明一切正常。按 `Ctrl+C` 停止。
+
+### 生产环境：安装为服务
+
+若要持久部署并在重启后自动恢复：
+
+```bash
+hermes gateway install
+sudo hermes gateway install --system   # 仅 Linux：开机启动的系统服务
+```
+
+这会创建一个后台服务：Linux 上默认为用户级 **systemd** 服务，macOS 上为 **launchd** 服务，传入 `--system` 则创建开机启动的 Linux 系统服务。
+
+```bash
+# Linux——管理默认用户服务
+hermes gateway start
+hermes gateway stop
+hermes gateway status
+
+# 查看实时日志
+journalctl --user -u hermes-gateway -f
+
+# SSH 退出后保持运行
+sudo loginctl enable-linger $USER
+
+# Linux 服务器——显式系统服务命令
+sudo hermes gateway start --system
+sudo hermes gateway status --system
+journalctl -u hermes-gateway -f
+```
+
+```bash
+# macOS——管理服务
+hermes gateway start
+hermes gateway stop
+tail -f ~/.hermes/logs/gateway.log
+```
+
+:::tip macOS PATH
+launchd plist 在安装时捕获你的 Shell PATH，以便 gateway 子进程能找到 Node.js 和 ffmpeg 等工具。如果之后安装了新工具，请重新运行 `hermes gateway install` 以更新 plist。
+:::
+
+### 验证运行状态
+
+```bash
+hermes gateway status
+```
+
+然后在 Telegram 上向你的机器人发送测试消息。几秒内应收到回复。
+
+---
+
+## 第四步：设置团队访问权限
+
+现在让你的队友获得访问权限。有两种方式。
+
+### 方式 A：静态白名单
+
+收集每位团队成员的 Telegram 用户 ID（让他们给 [@userinfobot](https://t.me/userinfobot) 发消息），然后以逗号分隔的列表形式添加：
+
+```bash
+# 在 ~/.hermes/.env 中
+TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555
+```
+
+修改后重启 gateway：
+
+```bash
+hermes gateway stop && hermes gateway start
+```
+
+### 方式 B：私信配对（推荐用于团队）
+
+私信配对更灵活——无需提前收集用户 ID。工作流程如下：
+
+1. **队友私信机器人**——由于不在白名单中，机器人会回复一次性配对码：
+   ```
+   🔐 Pairing code: XKGH5N7P
+   Send this code to the bot owner for approval.
+   ```
+
+2. **队友将配对码发给你**（通过任何渠道——Slack、邮件或当面）
+
+3. **你在服务器上审批**：
+   ```bash
+   hermes pairing approve telegram XKGH5N7P
+   ```
+
+4. **他们即可使用**——机器人立即开始响应他们的消息
+
+**管理已配对用户：**
+
+```bash
+# 查看所有待审批和已审批用户
+hermes pairing list
+
+# 撤销某人的访问权限
+hermes pairing revoke telegram 987654321
+
+# 清除已过期的待审批码
+hermes pairing clear-pending
+```
+
+:::tip
+私信配对非常适合团队使用，因为添加新用户时无需重启 gateway。审批立即生效。
+:::
+
+### 安全注意事项
+
+- **切勿在拥有终端访问权限的机器人上设置 `GATEWAY_ALLOW_ALL_USERS=true`**——任何找到你机器人的人都可能在你的服务器上执行命令
+- 配对码在 **1 小时**后过期，并使用密码学随机数生成
+- 速率限制防止暴力破解：每用户每 10 分钟 1 次请求，每平台最多 3 个待审批码
+- 5 次审批失败后，该平台进入 1 小时锁定状态
+- 所有配对数据以 `chmod 0600` 权限存储
+
+---
+
+## 第五步：配置机器人
+
+### 设置主频道
+
+**主频道**是机器人投递 cron 任务结果和主动消息的地方。没有主频道，定时任务将无处发送输出。
+
+**方式 1：** 在机器人所在的任意 Telegram 群组或聊天中使用 `/sethome` 命令。
+
+**方式 2：** 在 `~/.hermes/.env` 中手动设置：
+
+```bash
+TELEGRAM_HOME_CHANNEL=-1001234567890
+TELEGRAM_HOME_CHANNEL_NAME="Team Updates"
+```
+
+要查找频道 ID，可将 [@userinfobot](https://t.me/userinfobot) 添加到群组——它会报告该群组的聊天 ID。
+
+### 配置工具进度显示
+
+控制机器人在使用工具时显示的详细程度。在 `~/.hermes/config.yaml` 中：
+
+```yaml
+display:
+  tool_progress: new    # off | new | all | verbose
+```
+
+| 模式 | 显示内容 |
+|------|-------------|
+| `off` | 仅显示干净的回复——无工具活动 |
+| `new` | 每次新工具调用的简短状态（推荐用于消息场景） |
+| `all` | 每次工具调用及其详情 |
+| `verbose` | 完整工具输出，包括命令结果 |
+
+用户也可以在聊天中使用 `/verbose` 命令按会话更改此设置。
+
+### 使用 SOUL.md 设置个性
+
+通过编辑 `~/.hermes/SOUL.md` 自定义机器人的沟通方式：
+
+完整指南请参阅[在 Hermes 中使用 SOUL.md](/guides/use-soul-with-hermes)。
+
+```markdown
+# Soul
+You are a helpful team assistant. Be concise and technical.
+Use code blocks for any code. Skip pleasantries — the team
+values directness. When debugging, always ask for error logs
+before guessing at solutions.
+```
+
+### 添加项目上下文
+
+如果你的团队在特定项目上工作，可以创建上下文文件，让机器人了解你们的技术栈：
+
+```markdown
+<!-- ~/.hermes/AGENTS.md -->
+# Team Context
+- We use Python 3.12 with FastAPI and SQLAlchemy
+- Frontend is React with TypeScript
+- CI/CD runs on GitHub Actions
+- Production deploys to AWS ECS
+- Always suggest writing tests for new code
+```
+
+:::info
+上下文文件会注入到每个会话的系统 prompt（提示词）中。请保持简洁——每个字符都会占用你的 token 预算。
+:::
+
+---
+
+## 第六步：设置定时任务
+
+gateway 运行后，你可以安排定期任务，将结果投递到团队频道。
+
+### 每日站会摘要
+
+在 Telegram 上给机器人发消息：
+
+```
+Every weekday at 9am, check the GitHub repository at
+github.com/myorg/myproject for:
+1. Pull requests opened/merged in the last 24 hours
+2. Issues created or closed
+3. Any CI/CD failures on the main branch
+Format as a brief standup-style summary.
+```
+
+Agent 会自动创建一个 cron 任务，并将结果投递到你提问的聊天（或主频道）。
+
+### 服务器健康检查
+
+```
+Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
+and Docker container status with 'docker ps'. Report anything unusual —
+partitions above 80%, containers that have restarted, or high memory usage.
+```
+
+### 管理定时任务
+
+```bash
+# 通过 CLI
+hermes cron list          # 查看所有定时任务
+hermes cron status        # 检查调度器是否运行
+
+# 通过 Telegram 聊天
+/cron list                # 查看任务
+/cron remove <job_id>     # 删除任务
+```
+
+:::warning
+Cron 任务的 prompt 在完全全新的会话中运行，不保留任何先前对话的记忆。请确保每个 prompt 包含 agent 所需的**全部**上下文——文件路径、URL、服务器地址以及清晰的指令。
+:::
+
+---
+
+## 生产环境建议
+
+### 使用 Docker 保障安全
+
+在共享团队机器人上，使用 Docker 作为终端后端，让 agent 命令在容器中运行，而非直接在宿主机上运行：
+
+```bash
+# 在 ~/.hermes/.env 中
+TERMINAL_BACKEND=docker
+TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
+```
+
+或在 `~/.hermes/config.yaml` 中：
+
+```yaml
+terminal:
+  backend: docker
+  container_cpu: 1
+  container_memory: 5120
+  container_persistent: true
+```
+
+这样即使有人要求机器人执行破坏性操作，你的宿主系统也受到保护。
+
+### 监控 Gateway
+
+```bash
+# 检查 gateway 是否运行
+hermes gateway status
+
+# 查看实时日志（Linux）
+journalctl --user -u hermes-gateway -f
+
+# 查看实时日志（macOS）
+tail -f ~/.hermes/logs/gateway.log
+```
+
+### 保持 Hermes 更新
+
+在 Telegram 中向机器人发送 `/update`——它会拉取最新版本并重启。或在服务器上执行：
+
+```bash
+hermes update
+hermes gateway stop && hermes gateway start
+```
+
+### 日志位置
+
+| 内容 | 位置 |
+|------|----------|
+| Gateway 日志 | `journalctl --user -u hermes-gateway`（Linux）或 `~/.hermes/logs/gateway.log`（macOS） |
+| Cron 任务输出 | `~/.hermes/cron/output/{job_id}/{timestamp}.md` |
+| Cron 任务定义 | `~/.hermes/cron/jobs.json` |
+| 配对数据 | `~/.hermes/pairing/` |
+| 会话历史 | `~/.hermes/sessions/` |
+
+---
+
+## 进一步探索
+
+你已经拥有一个可用的团队 Telegram 助手。以下是一些后续步骤：
+
+- **[安全指南](/user-guide/security)**——深入了解授权、容器隔离和命令审批
+- **[消息 Gateway](/user-guide/messaging)**——gateway 架构、会话管理和聊天命令的完整参考
+- **[Telegram 设置](/user-guide/messaging/telegram)**——平台专属详情，包括语音消息和 TTS
+- **[定时任务](/user-guide/features/cron)**——高级 cron 调度，含投递选项和 cron 表达式
+- **[上下文文件](/user-guide/features/context-files)**——用于项目知识的 AGENTS.md、SOUL.md 和 .cursorrules
+- **[个性设置](/user-guide/features/personality)**——内置个性预设和自定义角色定义
+- **添加更多平台**——同一 gateway 可同时运行 [Discord](/user-guide/messaging/discord)、[Slack](/user-guide/messaging/slack) 和 [WhatsApp](/user-guide/messaging/whatsapp)
+
+---
+
+*有问题或遇到问题？请在 GitHub 上提 issue——欢迎贡献。*

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

@@ -0,0 +1,234 @@
+---
+sidebar_position: 1
+title: "技巧与最佳实践"
+description: "充分发挥 Hermes Agent 潜力的实用建议——prompt 技巧、CLI 快捷键、上下文文件、记忆、成本优化与安全"
+---
+
+# 技巧与最佳实践
+
+一份实用技巧速查集，帮助你立即提升使用 Hermes Agent 的效率。每个章节针对不同方面——扫描标题，直接跳到相关内容。
+
+---
+
+## 获得最佳结果
+
+### 明确说明你的需求
+
+模糊的 prompt（提示词）只会产生模糊的结果。不要说"修复代码"，而要说"修复 `api/handlers.py` 第 47 行的 TypeError——`process_request()` 函数从 `parse_body()` 收到了 `None`。"给出的上下文越多，所需的迭代次数就越少。
+
+### 预先提供上下文
+
+在请求开头就给出相关细节：文件路径、错误信息、预期行为。一条精心构造的消息胜过三轮来回确认。直接粘贴错误堆栈——agent 能够解析它们。
+
+### 使用上下文文件处理重复指令
+
+如果你发现自己在反复输入相同的指令（"用 tab 而非空格"、"我们用 pytest"、"API 地址是 `/api/v2`"），把它们放进 `AGENTS.md` 文件。agent 每次会话都会自动读取它——设置一次，永久生效。
+
+### 让 Agent 使用它的工具
+
+不要试图手把手指导每一步。说"找到并修复失败的测试"，而不是"打开 `tests/test_foo.py`，看第 42 行，然后……"。agent 拥有文件搜索、终端访问和代码执行能力——让它自行探索和迭代。
+
+### 对复杂工作流使用 Skill
+
+在写一大段 prompt 解释如何做某件事之前，先检查是否已有对应的 skill。输入 `/skills` 浏览可用的 skill，或直接调用，例如 `/axolotl` 或 `/github-pr-workflow`。
+
+## CLI 高级用户技巧
+
+### 多行输入
+
+按 **Alt+Enter**、**Ctrl+J** 或 **Shift+Enter** 可插入换行而不发送消息。`Shift+Enter` 仅在终端将其作为独立按键发送时有效（Kitty / foot / WezTerm / Ghostty 默认支持；iTerm2 / Alacritty / VS Code 终端需启用 Kitty 键盘协议）。另外两种方式在所有终端中均可使用。
+
+### 粘贴检测
+
+CLI 会自动检测多行粘贴。直接粘贴代码块或错误堆栈——不会将每行作为单独消息发送。粘贴内容会被缓冲后作为一条消息发送。
+
+### 中断与重定向
+
+按一次 **Ctrl+C** 可中断 agent 的响应过程，然后输入新消息重新引导它。在 2 秒内双击 Ctrl+C 可强制退出。当 agent 开始走错方向时，这个功能非常有用。
+
+### 使用 `-c` 恢复会话
+
+上次会话有遗漏？运行 `hermes -c` 可精确恢复到上次离开的位置，完整对话历史全部还原。也可以按标题恢复：`hermes -r "my research project"`。
+
+### 剪贴板图片粘贴
+
+按 **Ctrl+V** 可将剪贴板中的图片直接粘贴到对话中。agent 会使用视觉能力分析截图、图表、错误弹窗或 UI 原型——无需先保存为文件。
+
+### Slash 命令自动补全
+
+输入 `/` 后按 **Tab** 可查看所有可用命令，包括内置命令（`/compress`、`/model`、`/title`）和所有已安装的 skill。无需记忆任何内容——Tab 补全全部搞定。
+
+:::tip
+使用 `/verbose` 循环切换工具输出显示模式：**off → new → all → verbose**。"all" 模式非常适合观察 agent 的操作过程；"off" 模式在简单问答时最为简洁。
+:::
+
+## 上下文文件
+
+### AGENTS.md：你的项目大脑
+
+在项目根目录创建 `AGENTS.md`，写入架构决策、编码规范和项目专属指令。该文件会自动注入每次会话，让 agent 始终了解你的项目规则。
+
+```markdown
+# Project Context
+- This is a FastAPI backend with SQLAlchemy ORM
+- Always use async/await for database operations
+- Tests go in tests/ and use pytest-asyncio
+- Never commit .env files
+```
+
+### SOUL.md：自定义个性
+
+想让 Hermes 拥有稳定的默认风格？编辑 `~/.hermes/SOUL.md`（如果使用自定义 Hermes home，则为 `$HERMES_HOME/SOUL.md`）。Hermes 现在会自动生成一个初始 SOUL 文件，并将该全局文件作为实例级个性来源。
+
+完整说明请参阅 [在 Hermes 中使用 SOUL.md](/guides/use-soul-with-hermes)。
+
+```markdown
+# Soul
+You are a senior backend engineer. Be terse and direct.
+Skip explanations unless asked. Prefer one-liners over verbose solutions.
+Always consider error handling and edge cases.
+```
+
+使用 `SOUL.md` 设置持久个性，使用 `AGENTS.md` 设置项目专属指令。
+
+### .cursorrules 兼容性
+
+已有 `.cursorrules` 或 `.cursor/rules/*.mdc` 文件？Hermes 同样会读取它们。无需重复编写编码规范——这些文件会从工作目录自动加载。
+
+### 发现机制
+
+Hermes 在会话启动时从当前工作目录加载顶层 `AGENTS.md`。子目录中的 `AGENTS.md` 文件在工具调用期间通过 `subdirectory_hints.py` 延迟发现，并注入工具结果——不会在启动时预先加载到系统 prompt 中。
+
+:::tip
+保持上下文文件简洁聚焦。每个字符都会消耗 token 配额，因为它们会注入到每一条消息中。
+:::
+
+## 记忆与 Skill
+
+### 记忆 vs. Skill：各司其职
+
+**记忆（Memory）** 用于存储事实：你的环境、偏好、项目位置，以及 agent 了解到的关于你的信息。**Skill** 用于存储流程：多步骤工作流、特定工具的操作指南和可复用的操作方案。记忆存"是什么"，skill 存"怎么做"。
+
+### 何时创建 Skill
+
+如果某个任务需要 5 步以上且你会重复执行，就让 agent 为它创建一个 skill。说"把你刚才做的保存为名为 `deploy-staging` 的 skill"。下次只需输入 `/deploy-staging`，agent 就会加载完整流程。
+
+### 管理记忆容量
+
+记忆容量是有意限制的（`MEMORY.md` 约 2,200 字符，`USER.md` 约 1,375 字符）。当记忆填满时，agent 会自动整合条目。你也可以主动说"清理你的记忆"或"替换旧的 Python 3.9 备注——我们现在用 3.12 了"。
+
+### 让 Agent 记住内容
+
+在一次高效的会话结束后，说"记住这些以备下次使用"，agent 会保存关键要点。也可以具体指定："保存到记忆中，我们的 CI 使用 GitHub Actions 的 `deploy.yml` 工作流。"
+
+:::warning
+记忆是一个冻结的快照——会话期间的修改不会出现在系统 prompt 中，直到下一次会话开始。agent 会立即写入磁盘，但 prompt 缓存在会话中途不会失效。
+:::
+
+## 性能与成本
+
+### 不要破坏 Prompt 缓存
+
+大多数 LLM 提供商会缓存系统 prompt 前缀。如果你保持系统 prompt 稳定（相同的上下文文件、相同的记忆），同一会话中的后续消息会命中**缓存**，成本显著降低。避免在会话中途切换模型或修改系统 prompt。
+
+### 在达到限制前使用 /compress
+
+长会话会积累大量 token。当你发现响应变慢或被截断时，运行 `/compress`。这会对对话历史进行摘要，在大幅减少 token 数量的同时保留关键上下文。使用 `/usage` 查看当前用量。
+
+### 使用委托实现并行工作
+
+需要同时研究三个主题？让 agent 使用 `delegate_task` 并行分配子任务。每个子 agent 独立运行，拥有各自的上下文，最终只有摘要结果返回——大幅减少主对话的 token 消耗。
+
+### 使用 execute_code 进行批量操作
+
+不要逐条运行终端命令，而是让 agent 编写一个脚本一次性完成所有操作。"写一个 Python 脚本把所有 `.jpeg` 文件重命名为 `.jpg` 并运行它"比逐个重命名文件更省钱、更快速。
+
+### 选择合适的模型
+
+使用 `/model` 在会话中途切换模型。对于复杂推理和架构决策，使用前沿模型（Claude Sonnet/Opus、GPT-4o）；对于格式化、重命名或样板代码生成等简单任务，切换到更快的模型。
+
+:::tip
+定期运行 `/usage` 查看 token 消耗情况。运行 `/insights` 可查看过去 30 天的用量模式概览。
+:::
+
+## 消息技巧
+
+### 设置主频道
+
+在你偏好的 Telegram 或 Discord 聊天中使用 `/sethome`，将其指定为主频道。定时任务结果和计划任务输出会发送到这里。没有主频道，agent 就没有地方发送主动消息。
+
+### 使用 /title 整理会话
+
+用 `/title auth-refactor` 或 `/title research-llm-quantization` 为会话命名。命名后的会话可通过 `hermes sessions list` 轻松找到，并用 `hermes -r "auth-refactor"` 恢复。未命名的会话会堆积起来，难以区分。
+
+### DM 配对实现团队访问
+
+不要手动收集用户 ID 来维护白名单，而是启用 DM 配对。当团队成员向 bot 发送私信时，他们会收到一次性配对码。你用 `hermes pairing approve telegram XKGH5N7P` 批准即可——简单且安全。
+
+### 工具进度显示模式
+
+使用 `/verbose` 控制工具活动的显示详细程度。在消息平台上，通常越简洁越好——保持"new"模式只查看新的工具调用。在 CLI 中，"all" 模式可以实时查看 agent 的所有操作。
+
+:::tip
+消息平台的会话不会因空闲或每日时间边界重置。使用 `/new` 或 `/reset` 开始新对话；长对话仍由上下文压缩管理。
+:::
+
+## 安全
+
+### 对不可信代码使用 Docker
+
+在处理不可信仓库或运行陌生代码时，使用 Docker 或 Daytona 作为终端后端。在 `.env` 中设置 `TERMINAL_BACKEND=docker`。容器内的破坏性命令不会影响宿主系统。
+
+```bash
+# In your .env:
+TERMINAL_BACKEND=docker
+TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest
+```
+
+### 避免 Windows 编码陷阱
+
+在 Windows 上，某些默认编码（如 `cp125x`）无法表示所有 Unicode 字符，在测试或脚本中写入文件时可能导致 `UnicodeEncodeError`。
+
+- 建议在打开文件时显式指定 UTF-8 编码：
+
+```python
+with open("results.txt", "w", encoding="utf-8") as f:
+    f.write("✓ All good\n")
+```
+
+- 在 PowerShell 中，也可以将当前会话的控制台和原生命令输出切换为 UTF-8：
+
+```powershell
+$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+```
+
+这样可以让 PowerShell 和子进程统一使用 UTF-8，避免仅在 Windows 上出现的失败。
+
+### 谨慎选择"始终允许"
+
+当 agent 触发危险命令审批（`rm -rf`、`DROP TABLE` 等）时，你有四个选项：**once（仅此一次）**、**session（本次会话）**、**always（始终允许）**、**deny（拒绝）**。选择"always"前请仔细考虑——它会永久将该模式加入白名单。在熟悉之前，先用"session"。
+
+### 命令审批是你的安全防线
+
+Hermes 在执行每条命令前都会与一份精心维护的危险模式列表进行比对，包括递归删除、SQL DROP、curl 管道到 shell 等。不要在生产环境中禁用此功能——它的存在有充分的理由。
+
+:::warning
+在容器后端（Docker、Singularity、Modal、Daytona）中运行时，危险命令检查会被**跳过**，因为容器本身就是安全边界。请确保你的容器镜像已妥善加固。
+:::
+
+### 为消息 Bot 使用白名单
+
+永远不要在拥有终端访问权限的 bot 上设置 `GATEWAY_ALLOW_ALL_USERS=true`。始终使用平台专属白名单（`TELEGRAM_ALLOWED_USERS`、`DISCORD_ALLOWED_USERS`）或 DM 配对来控制谁可以与你的 agent 交互。
+
+```bash
+# Recommended: explicit allowlists per platform
+TELEGRAM_ALLOWED_USERS=123456789,987654321
+DISCORD_ALLOWED_USERS=123456789012345678
+
+# Or use cross-platform allowlist
+GATEWAY_ALLOWED_USERS=123456789,987654321
+```
+
+---
+
+*有值得收录的技巧？欢迎提交 issue 或 PR——社区贡献随时欢迎。*