技巧与最佳实践

hermes agent 技巧与最佳实践

这是一组快速见效的实用技巧集合，可以让你立即更高效地使用 Hermes Agent。每个部分都针对不同方面 —— 浏览标题，并跳转到与你相关的内容。

获得最佳结果

明确说明你想要什么

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

提前提供上下文

在请求开头放入相关细节：文件路径、错误消息、预期行为。一条精心组织的消息胜过三轮澄清。直接粘贴错误 traceback —— Agent 可以解析它们。

为重复指令使用上下文文件

如果你发现自己一直在重复相同指令（“使用 tabs 而不是 spaces”、“我们使用 pytest”、“API 位于 /api/v2”），请把它们放到 AGENTS.md 文件中。Agent 会在每个会话中自动读取它 —— 设置后无需额外操作。

让 Agent 使用它的工具

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

为复杂工作流使用 Skills

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

CLI 高级用户技巧

多行输入

按 Alt+Enter、Ctrl+J 或 Shift+Enter 可插入换行而不发送。Shift+Enter 只有在终端将其作为独立按键发送时才有效（Kitty / foot / WezTerm / Ghostty 默认支持；iTerm2 / Alacritty / VS Code terminal 在启用 Kitty keyboard protocol 后支持）。另外两个在所有终端中都可用。

粘贴检测

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

中断并重定向

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

使用 `-c` 恢复会话

忘了上一个会话中的内容？运行 hermes -c，即可从上次离开的地方继续，并恢复完整对话历史。你也可以通过标题恢复：hermes -r "my research project"。

剪贴板图片粘贴

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

Slash 命令自动补全

输入 / 并按 Tab 可查看所有可用命令。这包括内置命令（/compress、/model、/title）和每个已安装的 skill。你不需要记住任何东西 —— Tab 补全会帮你。

上下文文件

`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 home，则编辑 $HERMES_HOME/SOUL.md）。Hermes 现在会自动初始化一个入门版 SOUL，并使用该全局文件作为整个实例范围内的个性来源。

完整演练请参阅 Use SOUL.md with Hermes。

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

记忆与 Skills

记忆 vs. Skills：什么内容放在哪里

记忆用于事实：你的环境、偏好、项目位置，以及 Agent 已经了解的关于你的事情。Skills 用于流程：多步骤工作流、工具特定说明和可复用方案。记忆用于“是什么”，skills 用于“怎么做”。

何时创建 Skills

如果你发现某个任务需要 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 工作流。”

警告

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

性能与成本

不要破坏 Prompt 缓存

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

在触及限制前使用 `/compress`

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

使用委托进行并行工作

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

使用 `execute_code` 进行批量操作

不要一次运行一个终端命令，而是让 Agent 写一个一次性完成所有操作的脚本。“写一个 Python 脚本，把所有 .jpeg 文件重命名为 .jpg 并运行它”，比逐个重命名文件更便宜也更快。

选择合适的模型

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

消息平台技巧

设置 Home Channel

在你偏好的 Telegram 或 Discord 聊天中使用 /sethome，将其指定为 home channel。Cron job 结果和计划任务输出会发送到这里。如果没有设置，Agent 就没有地方发送主动消息。

使用 `/title` 组织会话

使用 /title auth-refactor 或 /title research-llm-quantization 为你的会话命名。命名后的会话可以通过 hermes sessions list 轻松找到，并可使用 hermes -r "auth-refactor" 恢复。未命名的会话会不断堆积，最后变得难以区分。

用于团队访问的 DM 配对

不要手动收集用户 ID 来做 allowlists，而是启用 DM pairing。当队友私信 bot 时，他们会获得一次性配对码。你可以通过 hermes pairing approve telegram XKGH5N7P 批准它 —— 简单且安全。

工具进度显示模式

使用 /verbose 控制你看到多少工具活动。在消息平台中，通常越少越好 —— 保持在 "new"，只查看新的工具调用。在 CLI 中，"all" 可以让你获得令人满意的实时视图，看到 Agent 所做的一切。

安全

对不可信代码使用 Docker

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

# 在你的 .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 特有的失败。

在选择 “Always” 前先审查

当 Agent 触发危险命令审批（rm -rf、DROP TABLE 等）时，你会得到四个选项：once、session、always、deny。在选择 "always" 前要仔细考虑 —— 它会永久将该模式加入允许列表。先从 "session" 开始，直到你感到放心。

命令审批是你的安全网

Hermes 会在执行前根据一组精选的危险模式检查每个命令。这包括递归删除、SQL drop、将 curl 管道到 shell 等。不要在生产环境中禁用它 —— 它的存在是有充分理由的。

警告

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

为消息机器人使用允许列表

永远不要在拥有终端访问权限的 bot 上设置 GATEWAY_ALLOW_ALL_USERS=true。始终使用平台特定的允许列表（TELEGRAM_ALLOWED_USERS、DISCORD_ALLOWED_USERS）或 DM pairing 来控制谁可以与你的 Agent 交互。

# 推荐：按平台设置显式允许列表
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678

# 或使用跨平台允许列表
GATEWAY_ALLOWED_USERS=123456789,987654321

有应该加入此页面的技巧？欢迎提交 issue 或 PR —— 欢迎社区贡献。