提示詞組裝

Hermes 明確區分了：

• 緩存的系統提示狀態
• 僅在 API 調用時臨時添加的內容

這是該項目最重要的設計決策之一，因為它影響：

• token 使用量
• 提示詞緩存效率
• 會話連續性
• 記憶正確性

主要文件：

• run_agent.py
• agent/prompt_builder.py
• tools/memory_tool.py

緩存的系統提示層

緩存的系統提示按以下順序組裝：

1. Agent 身份 —— 若 HERMES_HOME 下存在 SOUL.md，則使用該文件；否則回退至 prompt_builder.py 中的 DEFAULT_AGENT_IDENTITY
2. 工具感知行為指導
3. Honcho 靜態塊（當啟用時）
4. 可選的系統消息
5. 凍結的 MEMORY 快照
6. 凍結的 USER 配置文件快照
7. 技能索引
8. 上下文文件（AGENTS.md、.cursorrules、.cursor/rules/*.mdc）—— 若第 1 步已加載 SOUL.md 作為身份，則此處不再包含 SOUL.md
9. 時間戳 / 可選會話 ID
10. 平臺提示

當設置 skip_context_files 時（例如子 Agent 委派），SOUL.md 不會被加載，而是直接使用硬編碼的 DEFAULT_AGENT_IDENTITY。

具體示例：組裝後的系統提示

以下是所有層均存在時最終系統提示的簡化視圖（註釋標明各部分來源）：

# 第 1 層：Agent 身份（來自 `~/.hermes/SOUL.md`）
You are Hermes, an AI assistant created by Nous Research.
You are an expert software engineer and researcher.
You value correctness, clarity, and efficiency.
...

# 第 2 層：Tool 感知行為指導
You have persistent memory across sessions. Save durable facts using
the memory tool: user preferences, environment details, tool quirks,
and stable conventions. Memory is injected into every turn, so keep
it compact and focused on facts that will still matter later.
...
When the user references something from a past conversation or you
suspect relevant cross-session context exists, use session_search
to recall it before asking them to repeat themselves.

# Tool-使用強制執行（僅適用於 GPT/Codex models）
You MUST use your tools to take action — do not describe what you
would do or plan to do without actually doing it.
...

# 第 3 層：Honcho 靜態塊（激活時）
[Honcho personality/context data]

# 第 4 層：可選系統消息（來自配置或 API）
[User-configured system message override]

# 第 5 層：凍結 MEMORY 快照
## 持久 Memory
- User prefers Python 3.12, uses pyproject.toml
- Default editor is nvim
- Working on project "atlas" in ~/code/atlas
- Timezone: US/Pacific

# 第 6 層：凍結 USER profile 快照
## 用戶 Profile
- Name: Alice
- GitHub: alice-dev

# 第 7 層：Skills 索引
## Skills（必填）
Before replying, scan the skills below. If one clearly matches
your task, load it with skill_view(name) and follow its instructions.
...
<available_skills>
  software-development:
    - code-review: Structured code review workflow
    - test-driven-development: TDD methodology
  research:
    - arxiv: Search and summarize arXiv papers
</available_skills>

# 第 8 層：Context 文件（來自項目目錄）
# 項目上下文
The following project context files have been loaded and should be followed:

## AGENTS.md
This is the atlas project. Use pytest for testing. The main
entry point is src/atlas/main.py. Always run `make lint` before
committing.

# 第9層：時間戳+session
Current time: 2026-03-30T14:30:00-07:00
Session: abc123

# 第10層：平臺提示
You are a CLI AI Agent. Try not to use markdown but simple text
renderable inside a terminal.

SOUL.md 在提示詞中的呈現方式

SOUL.md 位於 ~/.hermes/SOUL.md，作為 Agent 的身份標識 —— 系統提示的最開始部分。prompt_builder.py 中的加載邏輯如下：

# 來自代理/prompt_builder.py（簡體）
def load_soul_md() -> Optional[str]:
    soul_path = get_hermes_home() / "SOUL.md"
    if not soul_path.exists():
        return None
    content = soul_path.read_text(encoding="utf-8").strip()
    content = _scan_context_content(content, "SOUL.md")  # 安全掃描
    content = _truncate_content(content, "SOUL.md")       # 上限為 20k 字符
    return content

當 load_soul_md() 返回內容時，它將替換硬編碼的 DEFAULT_AGENT_IDENTITY。隨後調用 build_context_files_prompt() 並傳入 skip_soul=True，以防止 SOUL.md 被重複出現（一次作為身份，一次作為上下文文件）。

若 SOUL.md 不存在，則系統回退至：

You are Hermes Agent, an intelligent AI assistant created by Nous Research.
You are helpful, knowledgeable, and direct. You assist users with a wide
range of tasks including answering questions, writing and editing code,
analyzing information, creative work, and executing actions via your tools.
You communicate clearly, admit uncertainty when appropriate, and prioritize
being genuinely useful over being verbose unless otherwise directed below.
Be targeted and efficient in your exploration and investigations.

上下文文件的注入方式

build_context_files_prompt() 使用 優先級系統 —— 僅加載一種項目上下文類型（首個匹配項勝出）：

# 來自代理/prompt_builder.py（簡體）
def build_context_files_prompt(cwd=None, skip_soul=False):
    cwd_path = Path(cwd).resolve()

    # 優先級：第一場比賽獲勝 - 僅加載 ONE 項目 context
    project_context = (
        _load_hermes_md(cwd_path)       # 1. .hermes.md / HERMES.md（走到 git 根目錄）
        or _load_agents_md(cwd_path)    # 2. AGENTS.md（僅限 cwd）
        or _load_claude_md(cwd_path)    # 3. CLAUDE.md（僅限cwd）
        or _load_cursorrules(cwd_path)  # 4. .cursorrules / .cursor/rules/*.mdc
    )

    sections = []
    if project_context:
        sections.append(project_context)

    # `SOUL.md` 來自 `HERMES_HOME`（獨立於項目上下文）
    if not skip_soul:
        soul_content = load_soul_md()
        if soul_content:
            sections.append(soul_content)

    if not sections:
        return ""

    return (
        "# Project Context\n\n"
        "The following project context files have been loaded "
        "and should be followed:\n\n"
        + "\n".join(sections)
    )

上下文文件發現細節

優先級	文件	搜索範圍	說明
1	.hermes.md、HERMES.md	從當前工作目錄向上至 git 倉庫根目錄	Hermes 原生項目配置
2	AGENTS.md	僅當前工作目錄	常見的 Agent 指令文件
3	CLAUDE.md	僅當前工作目錄	Claude Code 兼容性
4	.cursorrules、.cursor/rules/*.mdc	僅當前工作目錄	Cursor 兼容性

所有上下文文件均經過：

• 安全掃描 —— 檢查提示注入模式（不可見 Unicode、"忽略先前指令"、憑證外洩嘗試）
• 截斷處理 —— 使用 70/20 頭尾比例，上限 20,000 字符，並添加截斷標記
• 移除 YAML 前置元數據 —— .hermes.md 的前置元數據將被移除（保留用於未來配置覆蓋）

僅在 API 調用時生效的層

這些內容不會作為緩存系統提示的一部分持久化：

• ephemeral_system_prompt
• 預填充消息
• 網關派生的會話上下文疊加層
• 後續輪次 Honcho 回憶注入到當前輪次用戶消息中

這種分離確保了穩定前綴的穩定性，便於緩存。

記憶快照

本地記憶和用戶配置文件數據在會話開始時作為凍結快照注入。會話中段的寫入會更新磁盤狀態，但不會修改已構建的系統提示，直到新會話或強制重建發生。

上下文文件

agent/prompt_builder.py 使用 優先級系統 掃描並淨化項目上下文文件 —— 僅加載一種類型（首個匹配項勝出）：

1. .hermes.md / HERMES.md（從當前目錄向上遍歷至 git 根目錄）
2. AGENTS.md（啟動時僅在當前工作目錄；會話期間通過 agent/subdirectory_hints.py 逐步發現子目錄）
3. CLAUDE.md（僅當前工作目錄）
4. .cursorrules / .cursor/rules/*.mdc（僅當前工作目錄）

SOUL.md 通過 load_soul_md() 單獨加載，用於身份槽位。若加載成功，則調用 build_context_files_prompt(skip_soul=True) 以防止其重複出現。

長文件在注入前會被截斷。

技能索引

當可用技能工具時，技能系統會向提示詞中添加一個緊湊的技能索引。

為何提示詞組裝採用此方式

該架構有意優化以實現：

• 保留提供商端的提示詞緩存
• 避免不必要的歷史變更
• 保持記憶語義清晰可理解
• 允許網關/ACP/CLI 添加上下文，而不汙染持久化提示狀態

相關文檔

• 上下文壓縮與提示詞緩存
• 會話存儲
• 網關內部機制