context-engineering

name	context-engineering
description	当你在设计或调试 Agent 的上下文（系统提示词、工具定义、消息历史、状态注入、上下文压缩）时使用；当出现 KV Cache 命中率低、首 token 延迟高、Agent 决策随上下文变长而下降（上下文腐化）时使用。不适用于纯提示词措辞优化（见 prompt-engineering）或知识库检索调优（见 memory-rag）。

上下文工程（Context Engineering）

子 Skill 索引（渐进式披露：目录常驻，正文按需加载）

子 Skill	目录	何时深入加载
KV Cache 友好设计	context-kv-cache-friendly	设计系统提示词/工具定义布局、排查缓存命中率低/首 token 延迟高
Agent 状态栏	context-status-bar	让模型感知任务进度/工具计数/环境状态、解决循环/遗忘/目标偏离
上下文压缩	context-compression	上下文膨胀接近上限、决策质量下降（上下文腐化）时为上下文做减法

角色与读者

面向构建生产级 Agent 的开发者。本 Skill 服务的目标是：让 Agent 在每个决策点以最低成本获得信息充分的上下文，并让上下文布局对 KV Cache 友好。核心公式：上下文 = 静态前缀 + 轨迹。

核心原则（配正例/反例）

1. 静态前缀与轨迹严格分离

   • 系统提示词 + 核心工具定义构成静态前缀，一旦确定就不要改（哪怕多一个空格都可能改变 token 序列）。
   • 动态信息（时间戳、用户状态、新工具 schema）一律追加到末尾，作为轨迹的一部分。
   • 正例：当前时间作为新 user 消息追加到末尾，或需要时用工具获取。
   • 反例：在 system prompt 里加 Current time: {{now}}，导致每次请求前缀从时间戳位置起失效，首 token 延迟从 0.5s 涨到 3-5s、月度成本近乎翻倍。

2. 使用标准 API 格式，绝不自行拼接消息

   • 结构化消息（system/user/assistant/tool）会被 Chat Template 翻译成模型训练时见过的固定 token 序列。
   • 正例：工具结果用 role: "tool" + tool_call_id 回传。
   • 反例：把工具结果混入 user 消息 → 触发思维链清理机制（模型正算到一半"草稿纸被收走"）；自行拼 "USER: ... ASSISTANT: ..." 纯文本 → 偏离训练格式，重复执行、忽略工具结果、该调工具时生成文本。

3. 动态元信息用"Agent 状态栏"注入末尾，且用代码维护

   • 状态栏内容：工具调用计数、TODO 列表、当前时间/工作目录/环境状态、详细错误信息。
   • 位置：作为一条 user 角色的消息追加到上下文末尾（紧邻生成位置，获得最高注意力权重），用 <agent_status> 标签包裹。
   • 反例：用 LLM 一次性批量统计"打了多少次电话"——模型几乎无条件相信状态栏且数量统计易错，错误元信息会被当成事实。

4. 压缩要"上下文感知"，批量压缩而非每轮压

   • 压缩动机不只是省 token，更是提升思考质量 + 缓解"上下文焦虑"（模型怕窗口耗尽提前收尾）。
   • 压缩时把查询意图和已有信息纳入决策（Given the search query: {query} + Current context: {context}），压缩率可比无感知压缩高一个量级（实验：40K vs 277K token）。
   • 保留四类信息：决策、约束、失败、来源（引用）。
   • 正例：接近预算阈值（如 80%）时一次性批量压缩旧工具结果，加 [COMPRESSED] 标记防重复处理。
   • 反例：每轮都压缩 → 频繁破坏缓存；无感知压缩 → 信息碎片化或截断丢末尾关键信息。

5. 隔离优于压缩

   • 大体积中间信息（代码库大范围搜索、海量搜索结果）委派给子 Agent，只回传几百 token 的结论摘要，噪声从一开始就不进主上下文。
   • 代价：子 Agent 看不到主上下文，任务描述必须自包含、目标明确。

执行流程（SOP 检查清单）

1. 确定静态前缀：系统提示词 + 核心工具定义，写死、固定字节级稳定。
2. 确定动态信息注入点：时间戳、环境状态、状态栏 → 全部追加到轨迹末尾。
3. 设计状态栏：任务规划（TODO）、工具调用计数、环境状态、详细错误信息，由代码确定性维护。
4. 设计压缩策略：分层的（工具结果预算控制 → 噪声直接删除 → API 层微压缩 → 归档式摘要 → 全量压缩），接近阈值时批量触发。
5. 设计隔离边界：哪些任务委派子 Agent，哪些信息只回传摘要。

禁止清单（写清合法例外）

• 禁止修改已确定的 system prompt / 核心工具定义。例外：需要新增工具时，把完整 schema 追加到轨迹末尾（工具被发现那一轮），而非插回前缀；后续轮次它固定在原位置继续命中缓存。
• 禁止滑动窗口直接丢弃历史（破坏前缀一致性 + 丢失关键工具结果）。例外：接近预算时对旧工具结果做"上下文感知压缩"后再替换。
• 禁止静默截断（模型会误以为看到全部内容）。例外：截断必须注明"已显示第 1-200 行，共 5000 行，可用 offset 继续读取"。
• 禁止工具定义动态排序（改变顺序使缓存从首个变动工具起失效，对选择能力几乎无增益）。
• 禁止让 LLM 一次性批量统计状态（状态栏尽量代码维护，实在用 LLM 也要逐条抽取再由代码汇总）。

参考资料

• 本书第 2 章《上下文工程》：KV Cache 三条核心结论、Chat Template、Agent 状态栏、上下文压缩六策略对比。
• 笔记 02-上下文工程.md（本仓库 /Users/gongfan/ai-agent-notes/）。
• Anthropic "Contextual Retrieval" / "How Claude Code uses prompt caching"。