npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0 - Mend

better-dsh 0.2.5 → 0.3.0

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 (999) hide show

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

@@ -1,441 +0,0 @@
----
-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 DELETED Viewed

@@ -1,234 +0,0 @@
----
-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——社区贡献随时欢迎。*