上下文引用

输入 @ 再跟上一个引用，就可以把内容直接注入到消息中。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 条 commit 及 patch（最多 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 Tab 补全

在交互式 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%	拒绝展开，返回原始消息
Folder entries	最多 200 个文件	超出的部分替换为 - ...
Git commits	最多 10 条	@git:N 会被限制在 [1, 10]

安全性

敏感路径拦截

为了防止凭据外泄，以下路径始终不能通过 @file: 引用：

• SSH key 与配置：~/.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

错误处理

无效引用不会导致失败，而是以内联警告的形式返回：

情况	行为
File not found	Warning: "file not found"
Binary file	Warning: "binary files are not supported"
Folder not found	Warning: "folder not found"
Git command fails	带 git stderr 的警告
URL returns no content	Warning: "no content extracted"
Sensitive path	Warning: "path is a sensitive credential file"
Path outside workspace	Warning: "path is outside the allowed workspace"