上下文引用

輸入 @ 後跟一個引用，即可將內容直接注入到您的消息中。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        # 單線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 中，@ 會觸發自動補全，引用在消息發送給 Agent 前被展開。

在 消息平臺（Telegram、Discord 等）中，@ 語法不會被網關展開——消息會原樣傳遞。但 Agent 本身仍可通過 read_file、search_files 和 web_extract 工具引用文件。

與上下文壓縮的交互

當對話上下文被壓縮時，展開後的引用內容會包含在壓縮摘要中。這意味著：

通過 @file: 注入的大文件內容會計入上下文使用量
若後續對話被壓縮，文件內容將被總結（而非原樣保留）
對於非常大的文件，建議使用行範圍（如 @file:main.py:100-200）僅注入相關部分

常見模式

# 代碼審查工作流程
Review @diff and check for security issues

# 使用 context 進行調試
This test is failing. Here's the test @file:tests/test_auth.py
and the implementation @file:src/auth.py:50-80

# 項目探索
What does this project do? @folder:src @file:README.md

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

錯誤處理

無效引用會產生內聯警告而非失敗：

條件	行為
文件未找到	警告：“文件未找到”
二進制文件	警告：“不支持二進制文件”
目錄未找到	警告：“目錄未找到”
Git 命令失敗	附帶 git stderr 的警告
URL 無內容返回	警告：“未提取到內容”
敏感路徑	警告：“路徑為敏感憑據文件”
路徑超出工作區	警告：“路徑在允許的工作區之外”

支持的引用​

使用示例​

CLI 自動補全​

行範圍​

大小限制​

安全性​

敏感路徑攔截​

路徑遍歷防護​

二進制文件檢測​

平臺可用性​

與上下文壓縮的交互​

常見模式​

錯誤處理​