H繁中版
文件Flows社群 Repos開始使用
文件開發者指南prompt assembly
<!-- Source: https://hermesbible.com/docs/developer-guide/prompt-assembly -->

Hermes 刻意分離了：

  • 快取的系統提示狀態
  • 臨時的 API 呼叫時新增內容

這是專案中最重要的設計選擇之一，因為它影響：

  • token 使用量
  • 提示快取效果
  • 會話連續性
  • 記憶正確性

主要檔案：

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

快取的系統提示層級

快取的系統提示由三個有序層級組裝（參見 agent/system_prompt.py）：

  1. stable — 身分（SOUL.md 或回退）、工具/模型指引、技能提示、環境提示、平台提示
  2. context — 呼叫者提供的 system_message 加上專案上下文檔案（.hermes.md / AGENTS.md / CLAUDE.md / .cursorrules）
  3. volatile — 內建記憶快照（MEMORY.md）、使用者個人檔案快照（USER.md）、外部 memory-provider 區塊、時間戳/會話/模型/供應商行

最終系統提示的組裝順序為：stable → context → volatile。

此排序對優先順序討論很重要：

  • 技能屬於 stable 層級
  • 記憶/個人檔案快照屬於 volatile 層級
  • 兩者都在快取的系統提示中（它們不是作為臨時的中途覆蓋注入的）

當設定 skip_context_files 時（例如子代理委派），SOUL.md 不會被載入，而是使用硬編碼的 DEFAULT_AGENT_IDENTITY。

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

以下是當所有層級都存在時，最終系統提示的簡化視圖（註解顯示每個區塊的來源）：

# Layer 1: Agent Identity（來自 ~/.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.
...

# Layer 2: Tool-aware behavior guidance
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-use enforcement（僅限 GPT/Codex 模型）
You MUST use your tools to take action — do not describe what you
would do or plan to do without actually doing it.
...

# Layer 3: Honcho static block（啟用時）
[Honcho personality/context data]

# Layer 4: Optional system message（來自 config 或 API）
[使用者設定的 system message 覆寫]

# Layer 5: Frozen MEMORY snapshot
## Persistent Memory
- User prefers Python 3.12, uses pyproject.toml
- Default editor is nvim
- Working on project "atlas" in ~/code/atlas
- Timezone: US/Pacific

# Layer 6: Frozen USER profile snapshot
## User Profile
- Name: Alice
- GitHub: alice-dev

# Layer 7: Skills index
## Skills (mandatory)
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>

# Layer 8: Context files（來自專案目錄）
# Project 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.

# Layer 9: Timestamp + session
Current time: 2026-03-30T14:30:00-07:00
Session: abc123

# Layer 10: Platform hint
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 中的載入邏輯如下：

# 來自 agent/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。然後以 skip_soul=True 呼叫 build_context_files_prompt() 函數，防止 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() 使用優先順序系統——只載入一種專案上下文類型（第一個匹配者優先）：

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

    # 優先順序：第一個匹配者優先——只載入一種專案上下文
    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)

    # 來自 HERMES_HOME 的 SOUL.md（獨立於專案上下文）
    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.mdCWD 向上到 git 根目錄Hermes 原生專案設定
2AGENTS.md僅 CWD常見的 Agent 指令檔案
3CLAUDE.md僅 CWDClaude Code 相容性
4.cursorrules、.cursor/rules/*.mdc僅 CWDCursor 相容性

所有上下文檔案都：

  • 安全掃描 — 檢查提示注入模式（不可見 unicode、"ignore previous instructions"、憑證外洩嘗試）
  • 截斷 — 上限為 context_file_max_chars 字元（預設 20,000），使用 70/20 頭/尾比例並帶有截斷標記
  • YAML frontmatter 被移除 — .hermes.md 的 frontmatter 被移除（保留給未來的設定覆寫）

僅限 API 呼叫時的層級

以下內容刻意不作為快取系統提示的一部分被持久化：

  • ephemeral_system_prompt
  • 前填訊息
  • 閘道器衍生的會話上下文覆蓋
  • 後期輪次的 Honcho/外部回憶注入到當前輪次的使用者訊息中

pre_llm_call 外掛上下文也落入此 API 呼叫時路徑：它被附加到當前輪次的使用者訊息中，而非寫入快取的系統提示。當多個外掛回傳上下文時，Hermes 會串接這些上下文區塊（參見 Hooks → pre_llm_call）。

這種分離使穩定的前綴保持穩定以利快取。

記憶快照

本地記憶和使用者個人檔案資料在系統提示的 volatile 層級中被捕獲。中途寫入會更新磁碟狀態，但在重建路徑執行前不會修改已建構的快取系統提示（新會話，或明確的無效化/重建流程如壓縮觸發的重建）。

上下文檔案

agent/prompt_builder.py 使用優先順序系統掃描和清理專案上下文檔案——只載入一種類型（第一個匹配者優先）：

  1. .hermes.md / HERMES.md（向上走到 git 根目錄）
  2. AGENTS.md（啟動時的 CWD；子目錄在會話期間透過 agent/subdirectory_hints.py 逐步發現）
  3. CLAUDE.md（僅 CWD）
  4. .cursorrules / .cursor/rules/*.mdc（僅 CWD）

SOUL.md 透過 load_soul_md() 單獨載入用於身分槽位。成功載入時，build_context_files_prompt(skip_soul=True) 防止它出現兩次。

長檔案在注入前會被截斷。

技能索引

當技能工具可用時，技能系統會向提示貢獻一個簡潔的技能索引。

支援的提示自訂介面

大多數使用者應將 agent/prompt_builder.py 視為實作程式碼，而非設定介面。支援的自訂路徑是更改 Hermes 已經載入的提示輸入，而非直接編輯 Python 範本。

優先使用這些介面

  • ~/.hermes/SOUL.md — 用自己的 Agent 人格和持久行為替換內建的預設身分區塊。
  • ~/.hermes/MEMORY.md 和 ~/.hermes/USER.md — 提供應被快照到新會話中的持久跨會話事實和使用者個人檔案資料。
  • 專案上下文檔案如 .hermes.md、HERMES.md、AGENTS.md、CLAUDE.md 或 .cursorrules — 注入專屬儲存庫的工作規則。
  • 技能 — 打包可重用的工作流程和參考資料，無需編輯核心提示程式碼。
  • 選用的系統提示設定 / API 覆寫 — 新增部署特定的指令文字，無需分叉 Hermes。
  • 臨時覆蓋如 HERMES_EPHEMERAL_SYSTEM_PROMPT 或前填訊息 — 新增應不成為快取提示前綴一部分的輪次範圍指引。

何時改為編輯程式碼

僅在你刻意維護分叉或貢獻上游行為變更時編輯 agent/prompt_builder.py。該檔案組裝每個會話的提示管線、快取邊界和注入順序。直接編輯那裡是全域的產品變更，而非每個使用者的提示自訂。

換句話說：

  • 如果你想要不同的助手身分，編輯 SOUL.md
  • 如果你想要不同的儲存庫規則，編輯專案上下文檔案
  • 如果你想要可重用的操作流程，新增或修改技能
  • 如果你想要更改 Hermes 為所有人組裝提示的方式，更改 Python 並將其視為程式碼貢獻

為什麼提示組裝要這樣分離

此架構刻意優化以：

  • 保留供應商端的提示快取
  • 避免不必要地修改歷史
  • 保持記憶語義可理解
  • 讓閘道器/ACP/CLI 新增上下文而不毒化持久化的提示狀態

相關文件

上下文壓縮與快取

programmatic integrationprovider runtime