使用技巧与最佳实践
一份快速见效的实用技巧合集，帮助你立即更高效地使用 Hermes Agent。每个部分聚焦不同方面——浏览标题并跳转到你关心的内容。
获得最佳结果
明确表达你的需求
模糊的提示会产生模糊的结果。不要说“修复代码”，而应具体说明：“修复 api/handlers.py 第 47 行的 TypeError —— process_request() 函数从 parse_body() 接收到 None。” 提供的上下文越多，所需迭代次数就越少。
提前提供上下文
在请求开头就加载相关细节：文件路径、错误信息、预期行为。一条精心设计的消息胜过三轮澄清。直接粘贴错误堆栈跟踪——代理可以解析它们。
使用上下文文件处理重复指令
如果你发现自己反复重复相同指令（如“使用制表符而非空格”、“我们使用 pytest”、“API 地址是 /api/v2”），请将这些内容放入 AGENTS.md 文件中。代理会在每次会话中自动读取该文件——设置完成后无需额外操作。
让代理使用其工具
不要试图手动引导每一步。说“查找并修复失败的测试”而不是“打开 tests/test_foo.py，查看第 42 行，然后……”。代理具备文件搜索、终端访问和代码执行能力——让它自主探索并迭代。
使用技能处理复杂工作流
在编写冗长提示说明如何完成某项任务之前，请先检查是否已有对应技能。输入 /skills 浏览可用技能，或直接调用某个技能，如 /axolotl 或 /github-pr-workflow。
CLI 高级用户技巧
多行输入
按 Alt+Enter（或 Ctrl+J）可插入换行而不发送消息。这让你能在按下 Enter 发送前，组合多行提示、粘贴代码块或构建复杂请求。
粘贴检测
CLI 会自动检测多行粘贴。直接粘贴代码块或错误堆栈跟踪即可——不会将每一行作为单独消息发送。粘贴内容会被缓冲，并作为一条消息整体发送。
中断与重定向
按一次 Ctrl+C 可中断代理的响应。之后你可以输入新消息来重定向它。在 2 秒内连续按两次 Ctrl+C 可强制退出。当代理开始走错方向时，此功能极为有用。
使用 -c 恢复会话
忘记上次会话的内容了？运行 hermes -c 可以恢复到你离开时的完全状态，完整会话历史将被还原。你也可以通过标题恢复：hermes -r "my research project"。
剪贴板图像粘贴
按 Ctrl+V 可直接将剪贴板中的图像粘贴到聊天中。代理通过视觉能力分析截图、图表、错误弹窗或 UI 原型——无需先保存为文件。
斜杠命令自动补全
输入 / 后按 Tab 可查看所有可用命令。这包括内置命令（如 /compress、/model、/title）以及所有已安装的技能。你无需记忆任何内容——Tab 补全已为你覆盖。
使用 /verbose 可循环切换工具输出显示模式：off → new → all → verbose。“all” 模式适合观察代理的操作过程；“off” 模式则最简洁，适用于简单问答。
上下文文件
AGENTS.md：你的项目的“大脑”
在项目根目录创建一个 AGENTS.md 文件，包含架构决策、编码规范和项目特定指令。该文件会在每次会话中自动注入，因此代理始终了解你的项目规则。
# 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 与 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 懒加载，并注入到工具结果中——它们不会提前加载到系统提示中。
保持上下文文件简洁聚焦。每个字符都会计入你的 token 预算，因为它们会被注入到每一条消息中。
记忆与技能
记忆 vs. 技能：该放哪里？
记忆用于存储事实：你的环境、偏好、项目位置，以及代理对你了解的各类信息。技能用于流程：多步骤工作流、工具特定指令和可复用的“配方”。用记忆记录“是什么”，用技能记录“怎么做”。
何时创建技能
如果你发现某个任务需要 5 步以上，并且你可能会再次执行，就让代理为它创建一个技能。例如，输入“将你刚才的操作保存为名为 deploy-staging 的技能”。下次只需输入 /deploy-staging，代理就会加载完整的操作流程。
管理内存容量
内存是故意受限的（MEMORY.md 约 2,200 字符，USER.md 约 1,375 字符）。当内存满时，代理会自动合并条目。你可以通过输入“清理你的记忆”或“替换旧的 Python 3.9 笔记——我们现在用的是 3.12”来协助。
让代理记住
在一次高效会话结束后，输入“记住这次的内容以便下次使用”，代理将保存关键收获。你也可以更具体地说明：“将我们的 CI 使用 GitHub Actions 和 deploy.yml 工作流的信息保存到记忆中。”
记忆是一个冻结的快照——会话期间所做的更改不会立即反映在系统提示中，直到下一次会话开始才会生效。代理会立即写入磁盘，但提示缓存不会在会话中被刷新。
性能与成本
不要破坏提示缓存
大多数大语言模型（LLM）提供商会缓存系统提示前缀。如果你保持系统提示稳定（相同的上下文文件、相同记忆），会话中的后续消息将获得缓存命中，成本显著降低。避免在会话中更改模型或系统提示。
在达到限制前使用 /compress
长时间会话会累积大量 token。当你注意到响应变慢或被截断时，运行 /compress。它会总结对话历史，在大幅减少 token 数量的同时保留关键上下文。使用 /usage 检查当前状态。
委托以实现并行工作
需要同时研究三个主题？让代理使用 delegate_task 并行执行子任务。每个子代理独立运行，拥有自己的上下文，最终只返回摘要——极大降低主对话的 token 使用量。
使用 execute_code 执行批量操作
不要逐个运行终端命令，而是让代理编写一个脚本一次性完成所有操作。“写一个 Python 脚本将所有 .jpeg 文件重命名为 .jpg 并运行它”比逐个重命名文件更高效且成本更低。
选择合适的模型
使用 /model 在会话中切换模型。对于复杂推理和架构决策，使用前沿模型（Claude Sonnet/Opus、GPT-4o）。对于简单任务（如格式化、重命名或样板生成），切换到更快的模型。
定期运行 /usage 查看你的 token 消耗情况。运行 /insights 获取过去 30 天使用模式的更全面视图。
消息提示
设置主频道
在你偏好的 Telegram 或 Discord 频道中使用 /sethome，将其设为主频道。定时任务和计划任务的输出将发送至此。若未设置，代理将无处发送主动消息。
使用 /title 组织会话
使用 /title auth-refactor 或 /title research-llm-quantization 为会话命名。命名会话可通过 hermes sessions list 轻松查找，并通过 hermes -r "auth-refactor" 恢复。未命名会话会堆积，难以区分。
私信配对实现团队访问
无需手动收集用户 ID 添加白名单，启用私信配对功能。当同事向机器人发送私信时，他们会收到一个一次性配对码。你通过 hermes pairing approve telegram XKGH5N7P 批准即可——简单且安全。
工具进度显示模式
使用 /verbose 控制你看到的工具活动程度。在消息平台中，通常越少越好——保持“new”模式，仅显示新的工具调用。在 CLI 中，“all” 模式可提供代理执行全过程的实时视图。
在消息平台中，会话会在空闲一段时间后自动重置（默认：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，以确保控制台和原生命令输出使用 UTF-8：
$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
这可使 PowerShell 及其子进程始终使用 UTF-8，有助于避免仅在 Windows 上出现的失败。
选择“始终”前仔细审查
当代理触发危险命令审批（如 rm -rf、DROP TABLE 等）时，你会看到四个选项：一次、会话、始终、拒绝。选择“始终”前务必仔细考虑——这将永久允许该模式。建议先使用“会话”模式，直到你感到安心。
命令审批是你的安全网
Hermes 在执行前会将每个命令与一个精心筛选的危险模式列表进行比对。这包括递归删除、SQL 删除操作、将 curl 的输出直接管道传递给 shell 等行为。请勿在生产环境中禁用此功能——它存在是有充分理由的。
当在容器后端（Docker、Singularity、Modal、Daytona）中运行时，危险命令检查将被跳过，因为容器本身是安全边界。请确保您的容器镜像已正确锁定。
为消息机器人使用白名单
切勿在具有终端访问权限的机器人上设置 GATEWAY_ALLOW_ALL_USERS=true。始终使用平台特定的白名单（如 TELEGRAM_ALLOWED_USERS、DISCORD_ALLOWED_USERS）或私信配对方式来控制谁可以与您的代理交互。
# 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——欢迎社区贡献。