Hermes Agent 中文文档
GitHub

技巧与最佳实践

一份实用技巧的快速集锦，让你立即提升使用 Hermes Agent 的效率。每个部分针对不同方面——浏览标题，跳到你感兴趣的内容。

获得最佳结果

明确表达需求

模糊的提示词产生模糊的结果。与其写"修复代码"，不如说"修复 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 拥有文件搜索、终端访问和代码执行能力——让它自己探索和迭代。

对复杂工作流使用技能

在写长提示词解释如何做某事之前，先检查是否已有对应的技能。输入 /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 始终了解你项目的规则。

# 项目上下文
- 这是一个使用 SQLAlchemy ORM 的 FastAPI 后端
- 数据库操作始终使用 async/await
- 测试放在 tests/ 目录，使用 pytest-asyncio
- 绝不提交 .env 文件

SOUL.md：自定义人格

想让 Hermes 拥有稳定的默认口吻？编辑 ~/.hermes/SOUL.md（或使用自定义 Hermes home 时的 $HERMES_HOME/SOUL.md）。Hermes 现在会自动生成初始 SOUL，并将该全局文件作为实例级人格来源。

完整操作指南请参阅将 SOUL.md 与 Hermes 配合使用。

# Soul
你是一名资深后端工程师。说话简洁直接。
除非被问，否则跳过解释。偏好一行代码胜过冗长方案。
始终考虑错误处理和边界情况。

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 将其指定为主频道。Cron 任务结果和定时任务输出会投递到这里。没有主频道，Agent 就没有地方发送主动消息。

使用 /title 组织会话

用 /title auth-refactor 或 /title research-llm-quantization 命名你的会话。命名会话易于通过 hermes sessions list 查找，并用 hermes -r "auth-refactor" 恢复。未命名会话会堆积起来，变得无法区分。

DM 配对管理团队访问

无需手动收集用户 ID 加入白名单，启用 DM 配对即可。当队友私信机器人时，他们会获得一次性配对码。你用 hermes pairing approve telegram XKGH5N7P 批准即可——简单且安全。

工具进度显示模式

使用 /verbose 控制你看到多少工具活动。在消息平台上，通常越少越好——保持 "new" 模式，只看新工具调用。在 CLI 中，"all" 模式能让你实时观看 Agent 做的每一件事。

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

安全

对不可信代码使用 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 特有的失败。

选择"始终"前仔细考虑

当 Agent 触发危险命令审批（rm -rf、DROP TABLE 等）时，你有四个选项：一次、会话、始终、拒绝。选择"始终"前要三思——它会永久将该模式加入白名单。在熟悉之前先用"会话"。

命令审批是你的安全网

Hermes 在执行前会检查每条命令是否符合精心策划的危险模式列表。包括递归删除、SQL drop、curl 管道到 shell 等。不要在生产环境中禁用此功能——它的存在是有充分理由的。

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

对消息机器人使用白名单

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

# 推荐：每个平台显式白名单
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678

# 或使用跨平台白名单
GATEWAY_ALLOWED_USERS=123456789,987654321

觉得某条技巧应该出现在本页？提交 issue 或 PR——欢迎社区贡献。