第四章系统提示词工程

系统提示词是 AI Agent 行为的"灵魂"。Hermes Agent 的 prompt_builder.py 实现了一套**渐进式披露（Progressive Disclosure）**的提示词组装系统，从 10+ 个来源收集上下文信息，最终组装成完整的 system prompt。

4.1 组装架构

prompt_builder.py 的核心设计理念是层次化、可配置、安全过滤。提示词从多个来源逐层叠加，每层都有明确的责任边界。

提示词来源层次

各层详解

层次	来源	职责
身份层	`SOUL.md` / 默认身份	定义 Agent 的名称、性格、行为准则
平台提示	`platform` 参数	针对不同平台的格式和功能提示
项目上下文	`.hermes.md`	从 cwd 向上遍历到 git root 的所有 `.hermes.md`
Agent 配置	`AGENTS.md` / `CLAUDE.md` / `.cursorrules`	项目级别的 Agent 行为配置
技能索引	Skills Tier 1	可用技能的元数据摘要
记忆上下文	Memory Manager	用户偏好、历史经验等
模型适配	Model Metadata	针对不同模型的特定提示
环境提示	运行时环境	操作系统、Shell 类型、工作目录等
安全过滤	Scanner	检测并过滤注入攻击

4.2 身份层

SOUL.md

SOUL.md 是 Agent 的身份定义文件。如果用户没有自定义，Hermes Agent 会使用默认身份。

markdown

<!-- 示例 SOUL.md -->
# Hermes

You are Hermes, an AI assistant created by Nous Research.
You are helpful, harmless, and honest.
...

平台特定提示

不同平台有不同的消息格式和功能限制，Agent 会根据 platform 参数注入对应的提示：

平台	特殊提示
`telegram`	MarkdownV2 格式限制、inline keyboard 支持
`discord`	Discord embed 格式、线程回复
`slack`	Block Kit 格式、线程消息
`whatsapp`	纯文本限制、多设备注意事项
`cli`	完整终端能力、长输出支持

4.3 上下文注入

.hermes.md Walk

.hermes.md 文件的发现机制会从当前工作目录（cwd）开始，向上遍历到 git root，收集所有遇到的 .hermes.md 文件：

python

def _find_hermes_md_files(cwd: Path) -> list[Path]:
    """从 cwd 向上遍历到 git root，收集所有 .hermes.md"""
    files = []
    current = cwd.resolve()
    while True:
        hermes_md = current / ".hermes.md"
        if hermes_md.exists():
            files.append(hermes_md)
        if (current / ".git").exists():
            break  # 到达 git root
        parent = current.parent
        if parent == current:
            break
        current = parent
    return list(reversed(files))  # 从外到内的顺序

优先级顺序

.hermes.md (git root)     → 最低优先级
.hermes.md (project dir)  → 中等优先级
AGENTS.md                  → 项目 Agent 配置
CLAUDE.md                  → Claude Code 兼容配置
.cursorrules               → Cursor 编辑器兼容配置

4.4 技能索引

两层缓存

技能索引使用 LRU + Disk 两层缓存来避免重复扫描：

缓存层	存储	TTL	用途
LRU Cache	内存	会话内	快速读取已解析的技能列表
Disk Cache	`~/.hermes/skills/index-cache/`	文件修改时间	跨会话复用

渐进式披露策略

Tier 1：只包含技能名称和简短描述（~100 tokens/技能），注入到 system prompt
Tier 2/3：完整技能内容，仅在 Agent 主动调用技能时按需加载

这种策略的好处是显著减少 system prompt 的 token 开销，同时保持技能的可发现性。

平台过滤

python

# 只注入匹配当前平台的技能
skill_matches_platform(skill_metadata, platform="telegram")

4.5 模型适配

不同 LLM 提供商有不同的行为特性，Hermes Agent 会针对特定模型注入适配提示：

OpenAI 模型

Execution discipline: Complete each tool call fully before starting the next.
Do not batch independent tool calls unless explicitly asked.

Google Gemini 模型

Always use absolute file paths (not relative paths).
When using parallel tool calls, ensure results are independent.

Anthropic Claude 模型

Use the 'developer' role for system-level instructions.
Support extended thinking for complex reasoning tasks.

4.6 安全防线

prompt_builder.py 包含多层安全检测机制，防止通过上下文文件注入恶意指令。

注入检测模式

python

_CONTEXT_THREAT_PATTERNS = [
    (r'ignore\s+(previous|all|above|prior)\s+instructions', "prompt_injection"),
    (r'do\s+not\s+tell\s+the\s+user', "deception_hide"),
    (r'system\s+prompt\s+override', "sys_prompt_override"),
    (r'disregard\s+(your|all|any)\s+(instructions|rules|guidelines)', "disregard_rules"),
    (r'curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', "exfil_curl"),
    (r'cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass)', "read_secrets"),
    ...
]

不可见字符过滤

python

_CONTEXT_INVISIBLE_CHARS = {
    '\u200b', '\u200c', '\u200d', '\u2060', '\ufeff',
    # ... 更多零宽字符
}

Y-frontmatter 剥离

自动剥离 Markdown 文件中的 YAML frontmatter（--- 包围的部分），防止 frontmatter 中的恶意内容被注入。

20K 限制

所有注入来源的内容总量有 20,000 字符的软限制，防止单个来源占用过多上下文空间。

4.7 Prompt Caching

prompt_caching.py 实现了 Anthropic 的 system_and_3 缓存策略，可减少约 75% 的输入 token 成本。

缓存策略

使用 Anthropic 允许的最大 4 个 cache_control 断点：

System prompt — 跨所有会话稳定
倒数第 3 条消息 — 滚动窗口
倒数第 2 条消息 — 滚动窗口
倒数第 1 条消息 — 滚动窗口

python

def apply_anthropic_cache_control(
    api_messages: List[Dict[str, Any]],
    cache_ttl: str = "5m",
    native_anthropic: bool = False,
) -> List[Dict[str, Any]]:
    """Apply system_and_3 caching strategy"""
    messages = copy.deepcopy(api_messages)
    marker = {"type": "ephemeral"}
    if cache_ttl == "1h":
        marker["ttl"] = "1h"

    # 断点 1: System prompt
    # 断点 2-4: Last 3 non-system messages
    ...
    return messages

缓存断点图

缓存策略对比

策略	断点数	成本降低	适用场景
`system_and_3`	4	~75%	长对话，默认策略
`system_only`	1	~30%	短对话
无缓存	0	0%	非 Anthropic 模型

上一章：第三章工具系统下一章：第五章上下文管理

第四章 系统提示词工程 ​

4.1 组装架构 ​

提示词来源层次 ​

各层详解 ​

4.2 身份层 ​

SOUL.md ​

平台特定提示 ​

4.3 上下文注入 ​

.hermes.md Walk ​

优先级顺序 ​

4.4 技能索引 ​

两层缓存 ​

渐进式披露策略 ​

平台过滤 ​

4.5 模型适配 ​

OpenAI 模型 ​

Google Gemini 模型 ​

Anthropic Claude 模型 ​

4.6 安全防线 ​

注入检测模式 ​

不可见字符过滤 ​

Y-frontmatter 剥离 ​

20K 限制 ​

4.7 Prompt Caching ​

缓存策略 ​

缓存断点图 ​

缓存策略对比 ​

第四章系统提示词工程

4.1 组装架构

提示词来源层次

各层详解

4.2 身份层

SOUL.md

平台特定提示

4.3 上下文注入

.hermes.md Walk

优先级顺序

4.4 技能索引

两层缓存

渐进式披露策略

平台过滤

4.5 模型适配

OpenAI 模型

Google Gemini 模型

Anthropic Claude 模型

4.6 安全防线

注入检测模式

不可见字符过滤

Y-frontmatter 剥离

20K 限制

4.7 Prompt Caching

缓存策略

缓存断点图

缓存策略对比