上下文引用

输入 @ 后跟一个引用，即可将内容直接注入到您的消息中。Hermes 会在行内展开引用，并在 --- 附加上下文 --- 部分追加内容。

支持的引用

语法	描述
`@file:path/to/file.py`	注入文件内容
`@file:path/to/file.py:10-25`	注入指定行范围（1索引，包含边界）
`@folder:path/to/dir`	注入目录树列表及文件元数据
`@diff`	注入 `git diff`（未暂存的工作区更改）
`@staged`	注入 `git diff --staged`（已暂存的更改）
`@git:5`	注入最近 N 次提交及其补丁（最多 10 次）
`@url:https://example.com`	获取并注入网页内容

使用示例

Review @file:src/main.py and suggest improvements

What changed? @diff

Compare @file:old_config.yaml and @file:new_config.yaml

What's in @folder:src/components?

Summarize this article @url:https://arxiv.org/abs/2301.00001

单条消息中可使用多个引用：

Check @file:main.py, and also @file:test.py.

引用值末尾的标点符号（,、.、;、!、?）会自动被移除。

CLI 自动补全

在交互式 CLI 中，输入 @ 会触发自动补全：

@ 显示所有引用类型（@diff、@staged、@file:、@folder:、@git:、@url:）
@file: 和 @folder: 触发文件系统路径补全，并显示文件大小元数据
仅输入 @ 后跟部分文本，会显示当前目录中匹配的文件和文件夹

行范围

@file: 引用支持行范围，用于精确注入内容：

@file:src/main.py:42        # Single line 42
@file:src/main.py:10-25     # Lines 10 through 25 (inclusive)

行号为 1 索引。无效范围将被静默忽略（返回完整文件内容）。

大小限制

为防止上下文窗口被过度占用，上下文引用设有上限：

限制类型	值	行为
软限制	上下文长度的 25%	附加警告，仍继续展开
硬限制	上下文长度的 50%	拒绝展开，原消息不变返回
目录条目	最多 200 个文件	超出条目替换为 `- ...`
Git 提交	最多 10 次	`@git:N` 被限制在 [1, 10] 范围内

安全性

敏感路径拦截

以下路径始终被 @file: 引用阻止，以防止凭据泄露：

SSH 密钥和配置：~/.ssh/id_rsa、~/.ssh/id_ed25519、~/.ssh/authorized_keys、~/.ssh/config
Shell 配置文件：~/.bashrc、~/.zshrc、~/.profile、~/.bash_profile、~/.zprofile
凭据文件：~/.netrc、~/.pgpass、~/.npmrc、~/.pypirc
Hermes 环境：$HERMES_HOME/.env

以下目录完全被阻止（其内部任意文件均不可访问）：

~/.ssh/、~/.aws/、~/.gnupg/、~/.kube/、$HERMES_HOME/skills/.hub/

路径遍历防护

所有路径均相对于工作目录解析。若引用路径解析至允许工作区根目录之外，则被拒绝。

二进制文件检测

通过 MIME 类型和空字节扫描检测二进制文件。已知文本扩展名（.py、.md、.json、.yaml、.toml、.js、.ts 等）会绕过 MIME 检测。二进制文件将被拒绝并发出警告。

平台可用性

上下文引用主要为 CLI 功能。在交互式 CLI 中，@ 会触发自动补全，引用在消息发送给代理前被展开。

在 消息平台（Telegram、Discord 等）中，@ 语法不会被网关展开——消息会原样传递。但代理本身仍可通过 read_file、search_files 和 web_extract 工具引用文件。

与上下文压缩的交互

当对话上下文被压缩时，展开后的引用内容会包含在压缩摘要中。这意味着：

通过 @file: 注入的大文件内容会计入上下文使用量
若后续对话被压缩，文件内容将被总结（而非原样保留）
对于非常大的文件，建议使用行范围（如 @file:main.py:100-200）仅注入相关部分

常见模式

# Code review workflow
Review @diff and check for security issues

# Debug with context
This test is failing. Here's the test @file:tests/test_auth.py
and the implementation @file:src/auth.py:50-80

# Project exploration
What does this project do? @folder:src @file:README.md

# Research
Compare the approaches in @url:https://arxiv.org/abs/2301.00001
and @url:https://arxiv.org/abs/2301.00002

错误处理

无效引用会产生内联警告而非失败：

条件	行为
文件未找到	警告：“文件未找到”
二进制文件	警告：“不支持二进制文件”
目录未找到	警告：“目录未找到”
Git 命令失败	附带 git stderr 的警告
URL 无内容返回	警告：“未提取到内容”
敏感路径	警告：“路径为敏感凭据文件”
路径超出工作区	警告：“路径在允许的工作区之外”

支持的引用​

使用示例​

CLI 自动补全​

行范围​

大小限制​

安全性​

敏感路径拦截​

路径遍历防护​

二进制文件检测​

平台可用性​

与上下文压缩的交互​

常见模式​

错误处理​