Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/context-references
在訊息中輸入 @ 加上參照，即可將內容直接注入訊息中。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 筆提交與 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 補全功能
在互動式 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 開始。無效的範圍會被靜默忽略（回傳完整檔案內容）。
大小限制
參照內容有大小限制，以避免超出模型的 context window：
| 閾值 | 數值 | 行為 |
|---|---|---|
| 軟性限制 | context 長度的 25% | 附加警告訊息，繼續展開 |
| 硬性限制 | context 長度的 50% | 拒絕展開，回傳原始訊息不變 |
| 資料夾項目 | 最多 200 個檔案 | 超出的項目以 - ... 取代 |
| Git 提交 | 最多 10 筆 | @git:N 的 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 功能。它們在互動式 CLI 中運作，@ 會觸發補全，參照在訊息傳送至 agent 之前展開。
在訊息平台（Telegram、Discord 等）中，@ 語法不會被 gateway 展開——訊息會原樣傳遞。不過 agent 本身仍可透過 read_file、search_files 和 web_extract 工具來參照檔案。
與 Context 壓縮的互動
當對話 context 被壓縮時，展開的參照內容會被包含在壓縮摘要中。這代表：
- 透過
@file:注入的大型檔案內容會佔用 context 用量 - 如果對話稍後被壓縮，檔案內容會被摘要（而非保留原始內容）
- 對於非常大的檔案，建議使用行數範圍（
@file:main.py:100-200）僅注入相關區段
常見用法
# 程式碼審查流程
Review @diff and check for security issues
# 帶上下文的除錯
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
錯誤處理
無效的參照會產生行內警告，而非中斷執行：
| 條件 | 行為 |
|---|---|
| 找不到檔案 | 警告：「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」 |