上下文引用

键入 @ 符号后跟引用标识符，可将内容直接注入到您的消息中。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 开始计数。无效的范围将被静默忽略（返回完整文件内容）。

大小限制

上下文引用受到限制，以防止超出模型的上下文窗口：

阈值项目	数值	行为
软限制 (Soft limit)	上下文长度的 25%	附加警告，但继续展开
硬限制 (Hard limit)	上下文长度的 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 类型和空字节（null-byte）扫描来检测二进制文件。已知的文本扩展名（如 .py、.md、.json、.yaml、.toml、.js、.ts 等）会跳过基于 MIME 的检测。二进制文件将被拒绝并触发警告。

平台可用性

上下文引用主要是一项 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

错误处理

无效的引用会产生行内警告，而不会导致任务失败：

状况	行为
文件未找到	警告：“file not found”
二进制文件	警告：“binary files are not supported”
文件夹未找到	警告：“folder not found”
Git 命令失败	显示带有 git 标准错误（stderr）的警告
URL 未返回内容	警告：“no content extracted”
敏感路径	警告：“path is a sensitive credential file”
路径超出工作区	警告：“path is outside the allowed workspace”