📝 构建 Agent 实践指南 — 提示词工程

组装 · 缓存 · 注入防护 — 从 20 个 Agent 项目源码提炼的提示词工程方法论

1 系统提示词组装：从硬编码到声明式分层

系统提示词（system prompt）是 Agent 行为的灵魂。它决定了模型"是谁"、"能做什么"、"怎么做"。20 个 Agent 项目展示了从简单到复杂的四种组装范式：

1.1 硬编码方式（Level 1）

Smolagents Agno

最简单的方式——直接在代码中定义系统提示词字符串，作为类属性或常量。优点是简单直接，缺点是无法动态适配环境。

# Smolagents: smolagents/agent.py
SYSTEM_PROMPT = """You are a helpful agent that can use tools to answer questions."""
# 没有变量注入，没有分层，一个字符串到底

1.2 模板方式（Level 2）

Aider

Aider 的每个 Coder 子类（15 种 edit format）都有独立的 prompt 类，使用 Python .format() 模板注入运行时变量：

# Aider: coders/editblock_prompts.py
class EditBlockPrompts(CoderPrompts):
    main_system = """Act as an expert software developer.
Always use best practices when coding.
{final_reminders}
Take requests for changes to the supplied code.
{shell_cmd_prompt}
"""

变量在 fmt_system_prompt() 中注入——fence 类型、用户语言、平台信息、shell 命令提示等：

# Aider: coders/base_coder.py → fmt_system_prompt()
def fmt_system_prompt(self, prompt):
    final_reminders = []
    if self.main_model.lazy:
        final_reminders.append(self.gpt_prompts.lazy_prompt)
    if self.main_model.overeager:
        final_reminders.append(self.gpt_prompts.overeager_prompt)
    user_lang = self.get_user_language()
    if user_lang:
        final_reminders.append(f"Reply in {user_lang}.\n")
    # ... 注入 platform_text, shell_cmd_prompt, language 等
    prompt = prompt.format(
        fence=self.fence,
        final_reminders=final_reminders,
        platform=platform_text,
        shell_cmd_prompt=shell_cmd_prompt,
        language=language,
    )
    return prompt

2 三层架构：Stable / Context / Volatile 分离

Hermes 是唯一显式实现三层分离的项目，这是提示词缓存的前提条件：

2.1 关键设计决策

# prompt_builder.py → build_context_files_prompt()
project_context = (
    _load_hermes_md(cwd_path)      # 最高优先级：walk to git root
    or _load_agents_md(cwd_path)   # cwd only
    or _load_claude_md(cwd_path)   # cwd only
    or _load_cursorrules(cwd_path) # 最低：cwd only
)

2.2 OpenClaw 的 Context Engine 抽象

OpenClaw 将提示词组装抽象为 ContextEngine 接口，支持可插拔的上下文管理引擎：

// OpenClaw: context-engine/types.ts
export interface ContextEngine {
  assemble(params: {
    sessionId: string;
    messages: AgentMessage[];
    tokenBudget?: number;        // ← Token 预算驱动
    availableTools?: Set; // ← 工具感知
    model?: string;               // ← 模型感知
    prompt?: string;              // ← 当前用户输入
  }): Promise<AssembleResult>;

  compact(params: { ... }): Promise<CompactResult>;
  maintain?(params: { ... }): Promise<ContextEngineMaintenanceResult>;
  // ... bootstrap, ingest, afterTurn, subagent lifecycle
}

AssembleResult 返回有序消息列表、估计 token 数、可选的 systemPromptAddition 和 contextProjection 生命周期管理：

export type AssembleResult = {
  messages: AgentMessage[];
  estimatedTokens: number;
  promptAuthority?: "assembled" | "preassembly_may_overflow";
  systemPromptAddition?: string;
  contextProjection?: ContextEngineProjection; // "per_turn" | "thread_bootstrap"
};

3 提示词缓存：Cache Boundary 与 system_and_3 策略

提示词缓存是 Agent 系统中最容易被忽视、但影响最大的优化。20 个项目中只有 3 个有系统性的缓存策略：

3.1 Aider 的 ChatChunks + cache_control_headers

Aider 使用 Anthropic 的 cache_control API，在消息的特定位置标记缓存断点：

# Aider: coders/chat_chunks.py
@dataclass
class ChatChunks:
    system: List = field(default_factory=list)
    examples: List = field(default_factory=list)
    done: List = field(default_factory=list)
    repo: List = field(default_factory=list)      # ← RepoMap
    readonly_files: List = field(default_factory=list)
    chat_files: List = field(default_factory=list) # ← 当前编辑的文件
    cur: List = field(default_factory=list)
    reminder: List = field(default_factory=list)

    def add_cache_control_headers(self):
        # 断点1: examples（或 system）
        if self.examples:
            self.add_cache_control(self.examples)
        else:
            self.add_cache_control(self.system)
        # 断点2: repo（readonly_files + repomap）
        if self.repo:
            self.add_cache_control(self.repo)
        else:
            self.add_cache_control(self.readonly_files)
        # 断点3: chat_files
        self.add_cache_control(self.chat_files)

关键设计：done 消息（历史对话）没有被缓存——因为它们每轮都在变化（新消息加入）。而 repo（RepoMap）和 chat_files 在同一编辑会话中相对稳定，适合缓存。

3.2 Hermes 的 system_and_3 策略

Hermes 使用更简洁的 4 断点策略——system prompt + 最后 3 条非系统消息：

# Hermes: agent/prompt_caching.py
def apply_anthropic_cache_control(
    api_messages: List[Dict[str, Any]],
    cache_ttl: str = "5m",          # ← 支持 5m 和 1h 两种 TTL
    native_anthropic: bool = False,
) -> List[Dict[str, Any]]:
    """system_and_3 策略：system + 最后 3 条非系统消息"""
    messages = copy.deepcopy(api_messages)
    marker = _build_marker(cache_ttl)

    breakpoints_used = 0
    # 断点1: system prompt
    if messages[0].get("role") == "system":
        _apply_cache_marker(messages[0], marker, native_anthropic=native_anthropic)
        breakpoints_used += 1

    # 断点2-4: 最后 3 条非系统消息
    remaining = 4 - breakpoints_used
    non_sys = [i for i in range(len(messages))
               if messages[i].get("role") != "system"]
    for idx in non_sys[-remaining:]:
        _apply_cache_marker(messages[idx], marker, native_anthropic=native_anthropic)

    return messages

3.3 OpenClaw 的 Cache Boundary + 可观测性

OpenClaw 是唯一实现了 提示词缓存可观测性 的项目——不仅能设缓存，还能诊断缓存为什么失效：

// OpenClaw: prompt-cache-observability.ts
type PromptCacheSnapshot = {
  provider: string;
  modelId: string;
  cacheRetention?: "none" | "short" | "long";
  streamStrategy: string;
  transport?: string;
  systemPromptDigest: string;  // ← SHA-256 摘要
  toolDigest: string;           // ← 工具集摘要
  toolCount: number;
  toolNames: string[];
};

// 自动检测缓存断裂原因
function diffSnapshots(previous, next): PromptCacheChange[] {
  if (previous.systemPromptDigest !== next.systemPromptDigest)
    changes.push({ code: "systemPrompt", detail: "system prompt digest changed" });
  if (previous.toolDigest !== next.toolDigest)
    changes.push({ code: "tools", detail: "..." });
  if (previous.cacheRetention !== next.cacheRetention)
    changes.push({ code: "cacheRetention", detail: "..." });
  // 还检测 model、streamStrategy、transport 变化
}

此外，OpenClaw 还实现了 normalizeStructuredPromptSection()，在组装前对提示词进行规范化——统一换行符、去除行尾空格、trim 首尾空白。这确保微小格式差异不会导致缓存失效：

// OpenClaw: prompt-cache-stability.ts
export function normalizeStructuredPromptSection(text: string): string {
  return text
    .replace(/\r\n?/g, "\n")     // 统一换行
    .replace(/[ \t]+$/gm, "")    // 去行尾空白
    .trim();                       // 去首尾空白
}

4 上下文压缩：Condenser 管道与迭代摘要

当对话超过模型上下文窗口时，必须压缩。20 个项目中只有 5 个有成熟的压缩方案：

4.1 Hermes 的 ContextCompressor：结构化迭代摘要

Hermes 的压缩算法是所有项目中最精细的：

迭代摘要是关键创新——不是每次从头重新摘要，而是 在上一次摘要的基础上增量更新：

# context_compressor.py → compress()
summary_idx, summary_body = self._find_latest_context_summary(
    messages, summary_search_start, compress_end)
if summary_idx is not None:
    if summary_body and not self._previous_summary:
        self._previous_summary = summary_body  # ← 继承之前的摘要
    turns_to_summarize = messages[max(compress_start, summary_idx + 1):compress_end]

压缩后，system prompt 中追加一条通知：

"[Note: Some earlier conversation turns have been compacted into a
handoff summary to preserve context space. The current session state
may still reflect earlier work, so build on that summary and state
rather than re-doing work. Your persistent memory (MEMORY.md, USER.md)
remains fully authoritative regardless of compaction.]"

4.2 OpenClaw 的 ContextEngine.compact()

OpenClaw 将压缩也抽象为 ContextEngine 的一部分，支持：

• compactionTarget: "budget" | "threshold" — 压缩目标是预算还是阈值
• rewriteTranscriptEntries() — 安全的 transcript 重写（branch-and-reappend）
• ownsCompaction — 引擎可以接管自己的压缩生命周期
• turnMaintenanceMode: "foreground" | "background" — 前台或后台维护

// OpenClaw: context-engine/types.ts
export type CompactResult = {
  ok: boolean;
  compacted: boolean;
  reason?: string;
  result?: {
    summary?: string;
    firstKeptEntryId?: string;
    tokensBefore: number;
    tokensAfter?: number;
    sessionId?: string;        // ← 压缩后可能轮转 session
    sessionFile?: string;
  };
};

4.3 Aider 的 Summarizer

Aider 使用单独的弱模型（weak model）做摘要，不消耗主模型的上下文窗口：

# Aider: base_coder.py
# 初始化时选择摘要模型
self.summarizer = ChatSummary(
    [self.main_model.weak_model, self.main_model],  # ← 优先用 weak model
    self.main_model.max_chat_history_tokens,
)

关键：done_messages（已完成的消息）通过 summarizer 压缩后替换，保持总消息长度在 max_chat_history_tokens 以内。这与 ChatChunks 的缓存策略配合——压缩只影响 done 区块，不破坏 system/examples/repo 的缓存。