上下文引用

输入 @ 再跟上一个引用，就可以把内容直接附加到你的消息里。Hermes 会在发送前展开这些引用，并把对应内容附加到 --- Attached Context --- 区块中。

支持的引用类型

语法	描述
`@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 自动补全​

行范围​

大小限制​

安全性​

敏感路径拦截​

路径遍历防护​

二进制文件检测​

平台可用性​

与上下文压缩的交互​

常见使用模式​

错误处理​