上下文引用

输入 @ 并后跟引用即可将内容直接注入到您的消息中。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	获取并注入网页内容

用法示例

审查 @file:src/main.py 并提出改进建议

哪些地方发生了变化？@diff

比较 @file:old_config.yaml 和 @file:new_config.yaml

@folder:src/components 中有什么？

总结这篇文章 @url:https://arxiv.org/abs/2301.00001

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

检查 @file:main.py，以及 @file:test.py。

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

命令行界面（CLI）自动补全

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

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

行范围

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

@file:src/main.py:42        # 单行 42
@file:src/main.py:10-25     # 第 10 行到第 25 行（包含）

行号从 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）仅注入相关部分。

常见模式

# 代码审查工作流
审查 @diff 并检查安全问题

# 带上下文调试
此测试失败了。这是测试 @file:tests/test_auth.py
和实现 @file:src/auth.py:50-80

# 项目探索
这个项目是做什么的？ @folder:src @file:README.md

# 研究
比较 @url:https://arxiv.org/abs/2301.00001
和 @url:https://arxiv.org/abs/2301.00002 中的方法

错误处理

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

条件	行为
文件未找到	警告：“文件未找到”
二进制文件	警告：“不支持二进制文件”
文件夹未找到	警告：“文件夹未找到”
Git 命令失败	带有 git stderr 的警告
URL 未返回内容	警告：“未提取内容”
敏感路径	警告：“路径是敏感凭证文件”
路径超出工作区	警告：“路径超出允许的工作区”