技巧与最佳实践

> 📖 本文档翻译自 Hermes Agent 官方文档 > 最后更新：2026-04-16

---

技巧与最佳实践

一份实用技巧速查集合，让你立刻更高效地使用 Hermes Agent。每个部分针对不同的方面——浏览标题，跳转到你需要的内容。

---

获得最佳效果

明确说明你想要什么

模糊的提示产生模糊的结果。不要说"修复代码"，而要说"修复 api/handlers.py 第 47 行的 TypeError — process_request() 函数从 parse_body() 接收到了 None。"你给出的上下文越多，需要的迭代次数越少。

提前提供上下文

在请求的最前面放上相关细节：文件路径、错误信息、预期行为。一条精心编写的消息胜过三轮澄清。直接粘贴错误回溯信息——Agent 能解析它们。

使用上下文文件存放重复指令

如果你发现自己重复相同的指令（"使用制表符而非空格"、"我们使用 pytest"、"API 地址是 /api/v2"），把它们放到 AGENTS.md 文件中。Agent 每次会话都会自动读取它——设置之后零成本。

让 Agent 使用它的工具

不要试图手把手指导每一步。说"找到并修复失败的测试"，而不是"打开 tests/test_foo.py，看第 42 行，然后……"Agent 拥有文件搜索、终端访问和代码执行能力——让它自己探索和迭代。

使用技能处理复杂工作流

在编写一个长提示来解释如何做某事之前，先检查是否已有对应的技能。输入 /skills 浏览可用技能，或者直接调用，如 /axolotl 或 /github-pr-workflow。

CLI 高级技巧

多行输入

按 Alt+Enter（或 Ctrl+J）插入换行但不发送。这让你可以编写多行提示、粘贴代码块，或在按 Enter 发送前组织复杂的请求。

粘贴检测

CLI 会自动检测多行粘贴。直接粘贴代码块或错误回溯信息——它不会把每一行当作单独的消息发送。粘贴内容会被缓冲并作为一条消息发送。

中断和重定向

按 Ctrl+C 一次可中断 Agent 的当前响应。然后你可以输入新消息来重定向它。2 秒内双击 Ctrl+C 强制退出。当 Agent 开始走错方向时，这非常实用。

使用 -c 恢复会话

忘了上次会话中的某些内容？运行 hermes -c 即可恢复到你上次离开的位置，完整对话历史也会恢复。你也可以按标题恢复：hermes -r "my research project"。

剪贴板图片粘贴

按 Ctrl+V 可将剪贴板中的图片直接粘贴到聊天中。Agent 使用视觉能力分析截图、图表、错误弹窗或 UI 模型——无需先保存到文件。

斜杠命令自动补全

输入 / 然后按 Tab 查看所有可用命令。包括内置命令（/compress、/model、/title）和每个已安装的技能。你不需要记住任何东西——Tab 补全都帮你搞定了。

提示

使用 /verbose 循环切换工具输出显示模式：off → new → all → verbose。"all"模式非常适合观察 Agent 的操作；"off"模式最适合简单的问答。

上下文文件

AGENTS.md：你项目的大脑

在项目根目录创建一个 AGENTS.md，包含架构决策、编码规范和项目特定指令。这会在每次会话中自动注入，因此 Agent 始终知道你项目的规则。

# 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 主目录则为 $HERMES_HOME/SOUL.md）。Hermes 现在会自动生成一个入门 SOUL，并将该全局文件作为实例级的个性来源。

完整教程请参阅使用 SOUL.md。

# 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）并注入到工具结果中——它们不会预先加载到系统提示中。

提示

保持上下文文件聚焦且简洁。每个字符都计入你的 token 预算，因为它们会被注入到每条消息中。

记忆与技能

记忆 vs. 技能：什么放哪里

记忆用于存储事实：你的环境、偏好、项目位置以及 Agent 了解到的关于你的信息。技能用于流程：多步骤工作流、工具特定指令和可复用的方案。记忆用于"是什么"，技能用于"怎么做"。

何时创建技能

如果你发现一个任务需要 5 步以上，并且你会重复执行，就让 Agent 为它创建一个技能。说"把刚才做的事情保存为名为 deploy-staging 的技能。"下次只需输入 /deploy-staging，Agent 就会加载完整的流程。

管理记忆容量

记忆是有意限制的（MEMORY.md 约 2,200 字符，USER.md 约 1,375 字符）。当它满了，Agent 会合并条目。你可以说"清理你的记忆"或"替换旧的 Python 3.9 条目——我们现在用 3.12 了"来帮助它。

让 Agent 记住

在一次高效的会话后，说"记住这些以备下次使用"，Agent 会保存关键要点。你也可以具体指定："保存到记忆，我们的 CI 使用 GitHub Actions 和 deploy.yml 工作流。"

警告

记忆是一个冻结快照——会话期间所做的更改不会出现在系统提示中，直到下次会话开始。Agent 会立即写入磁盘，但提示缓存不会在会话中途失效。

性能与成本

不要破坏提示缓存

大多数 LLM 提供商会缓存系统提示前缀。如果你保持系统提示稳定（相同的上下文文件、相同的记忆），会话中的后续消息会获得缓存命中，显著降低成本。避免在会话中途更改模型或系统提示。

达到限制前使用 /compress

长会话会累积 token。当你注意到响应变慢或被截断时，运行 /compress。这会总结对话历史，保留关键上下文的同时大幅减少 token 数量。使用 /usage 查看当前状况。

委派以实现并行工作

需要同时研究三个主题？让 Agent 使用 delegate_task 处理并行子任务。每个子代理独立运行，拥有自己的上下文，只有最终的摘要返回——大幅减少主对话的 token 使用量。

使用 execute_code 进行批量操作

与其逐个运行终端命令，不如让 Agent 编写一个一次性完成所有任务的脚本。"编写一个 Python 脚本将所有 .jpeg 文件重命名为 .jpg 并运行它"比逐个重命名文件更便宜、更快速。

选择合适的模型

使用 /model 在会话中途切换模型。使用前沿模型（Claude Sonnet/Opus、GPT-4o）处理复杂推理和架构决策。切换到更快的模型处理简单任务，如格式化、重命名或样板代码生成。

提示

定期运行 /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 操作的实时视图。

提示

在消息平台上，会话在空闲时间后自动重置（默认：24 小时），或每天凌晨 4 点重置。如果需要更长的会话，可在 ~/.hermes/config.yaml 中按平台调整。

安全

对不受信任的代码使用 Docker

在处理不受信任的仓库或运行不熟悉的代码时，使用 Docker 或 Daytona 作为终端后端。在 .env 中设置 TERMINAL_BACKEND=docker。容器内的破坏性命令无法损害你的主机系统。

# In your .env:
TERMINAL_BACKEND=docker
TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest

避免 Windows 编码陷阱

在 Windows 上，某些默认编码（如 cp125x）无法表示所有 Unicode 字符，这可能导致在测试或脚本中写入文件时出现 UnicodeEncodeError。

• 建议使用显式 UTF-8 编码打开文件：

with open("results.txt", "w", encoding="utf-8") as f:
    f.write("✓ All good\n")

• 在 PowerShell 中，你还可以将当前会话切换为 UTF-8，用于控制台和原生命令输出：

$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)

这能让 PowerShell 和子进程都使用 UTF-8，有助于避免 Windows 特有的故障。

选择"始终"之前先审查

当 Agent 触发危险命令审批（rm -rf、DROP TABLE 等）时，你有四个选项：once（仅本次）、session（本次会话）、always（始终）、deny（拒绝）。在选择"始终"之前请仔细考虑——它会永久将该模式加入白名单。在你感到放心之前，先用"会话"。

命令审批是你的安全网

Hermes 在执行前会检查每个命令是否匹配精心策划的危险模式列表。这包括递归删除、SQL DROP、通过管道将 curl 输出传递给 shell 等。不要在生产环境中禁用此功能——它的存在是有原因的。

警告

当在容器后端（Docker、Singularity、Modal、Daytona）中运行时，危险命令检查会被跳过，因为容器本身就是安全边界。确保你的容器镜像被正确锁定。

消息 Bot 使用白名单

永远不要在具有终端访问权限的 Bot 上设置 GATEWAY_ALLOW_ALL_USERS=true。始终使用平台特定的白名单（TELEGRAM_ALLOWED_USERS、DISCORD_ALLOWED_USERS）或 DM 配对来控制谁可以与你的 Agent 交互。

# 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——欢迎社区贡献。