📘 第 10 课：Context management（上下文管理）

官方课程名：Context management（Curriculum 第二段「Teaching your Agent」之后、进入「Extending your Agent」收官） 官方地址：https://anthropic.skilljar.com/claude-platform-101 归档路径：Claudeexams/20-课程/课程003 the AI Platform 101/ 针对认证：CCAR-P（架构师 Professional） 归档日期：2026-10-14 ⚠️ 语料来源：官方 Skilljar 课程正文（用户提供，需登录）。CC BY-NC-SA 4.0，仅供个人学习。

⭐⭐ 本课权重提示：领域 2（13%）的「另一半正名课」。考纲领域 2 原文两句——「优化上下文窗口与管理 token 消耗」＋「实现提示复用策略（caching、模块化提示、Skills）」——本课一次讲齐：Skills（第 8 课）＋ caching（本课模式 3）＋ 上下文管理四模式。同时命中领域 4（16%）（caching 成本数学）与领域 1（17%）（memory tool 的状态设计）。官方那句 "the goal is to fit the right things in" 是本课总纲。 🔗 注意一个反差点：前两课（Skills / MCP）走 beta 端点，本课的 context_management 用的是标准端点 client.messages.create（无 .beta.、无 betas）——官方明说四个模式里三个是 first-class API features。

🎯 本课学习目标

⚠️ 本课官方未提供 What you'll learn 区块。以下按文稿结构反推：

1. 能列全 context 五要素（system prompt / message history / tool definitions ＆ results / attached files ＆ skills / thinking blocks）。
2. 能背出本课总纲：fit the right things in（不是 fit everything in）。
3. ⭐⭐ 能区分四个模式的性质：三个 first-class API 特性 ＋ 一个 design pattern（just-in-time）。
4. ⭐⭐ 能写出 context_management ＋ edits: [{"type": "compact"}] 并讲清 trigger threshold 机制。
5. ⭐⭐ 能算 caching 成本账（4,000 token × 100 次/小时的官方例）。
6. ⭐⭐ 能讲清 memory tool 三方分工：AI 读写 memory directory，你实现 storage backend，平台 auto-inject 系统指令。

📖 一、什么是上下文（What counts as context）

官方原句： Every request you send the AI has a context window. A million tokens sounds like a lot, but it runs out faster than you think once you're shipping a real agent. That's where context management comes in: it's how you stay inside the window without losing what matters.

精译：你发给 the AI 的每个请求都有一个上下文窗口。一百万 token 听起来很多，可一旦你在交付真实的 agent，它耗尽的速度超乎想象。上下文管理由此登场：它让你留在窗口之内，又不丢掉要紧的东西。

⭐⭐ context 五要素（必背清单）

官方原句： Context is everything the AI sees on a given turn: - The system prompt - The message history - Tool definitions and tool results - Attached files and skills - Thinking blocks

精译：上下文是 AI 在某一轮看到的全部：系统提示词、消息历史、工具定义与工具结果、附件与 Skills、思考块。

官方原句： It's the input to every single API call.* You pay for it on the way in, and you pay for it on the way out. And once the window is full, the request fails*.

精译：它是每一次 API 调用的输入。进来收费，出去也收费。而窗口一旦装满，请求直接失败。

⭐⭐ 本课总纲（必背句）

So the goal isn't to fit everything in. The goal is to fit the right things in. 「目标不是把所有东西都塞进去，而是把对的东西塞进去。」 * 考点：判断题题眼。选项若写「尽量把更多上下文装进窗口」即为反向干扰——官方立场是选择性装载。

📖 二、四个模式总览（官方分类）

官方原句： the AI provider publishes four patterns for managing context in long-running agents. Three are first-class API features, and one is a design pattern.**

精译：官方为长时运行 agent 发布了四个上下文管理模式。三个是一等 API 特性，一个是设计模式。

📖 三、模式 1：Just-in-time context（按需即时装载）

官方原句： Don't load everything upfront.* Load what the agent needs now, and let it pull more in via tools when it asks*.

精译：别把所有东西预先装好。装载 agent 现在需要的，它开口要更多时，让工具去拉。

官方原句： Think of a compliance review agent. It doesn't get the entire building code book stuffed into its system prompt — it calls a lookup_building_code tool when it needs a specific section. This is the design pattern of the four: nothing special in the API, just a deliberate choice about what you load and when.**

精译：想一个合规审查 agent。它不会把整本建筑规范塞进系统提示词 —— 需要某一节时，它调用 lookup_building_code 工具去取。这是四模式中唯一的纯设计模式：API 里没有任何特殊开关，只是对「装什么、何时装」的一次有意选择。

⭐⭐ 考点：四模式里唯一不动 API 的就是它（对照：第 7 课 lookup 类只读工具即 JIT 的载体）。考题问「哪个模式不需要 API 特性」选 just-in-time；问「agent 该怎么处理大文档」也选它——不塞 prompt，做成检索工具。

📖 四、模式 2：Server-side compaction（服务端压缩）

官方原句： When a conversation runs long, the AI provider's server-side compaction summarizes old turns into a single block. You opt in by adding a context_management key to your request, holding an edit with a type.

精译：对话跑长了，官方服务端的压缩功能把旧的轮次摘要成一个块。主动加入的方式：给请求加一个 context_management 键，里面放一条带类型的 edit。

response = client.messages.create(
    model="current-model-fast",
    max_tokens=1024,
    context_management={
        "edits": [
            {"type": "compact"}
        ]
    },
    messages=messages,
)

官方原句： The API auto-summarizes when the input crosses the trigger threshold. You don't have to track conversation length yourself.**

精译：输入越过触发阈值时，API 自动摘要。你自己不用盯着对话长度。

⭐⭐ 考点：机制题三连——开关在哪（context_management）、类型是什么（compact）、什么时候压缩（越过 trigger threshold 自动）。干扰项：让你自己统计对话长度、或把压缩写成 beta 特性。

📖 五、模式 3：Prompt caching（提示缓存）

官方原句： Prompt caching lets you mark the stable parts of a request — the system prompt, the tool definitions, a long document — and reuse them across calls at a fraction of the cost.

精译：提示缓存让你把请求中稳定的部分做标记 —— 系统提示词、工具定义、长文档 —— 然后跨调用复用，只花零头的价钱。

官方原句： The math matters more than it looks.* If your system prompt is 4,000 tokens and you call it 100 times an hour, caching is the difference between a usable bill and a phone call from finance*.

精译：这笔账比看上去重要。如果你的系统提示词 4,000 token、每小时调用 100 次，缓存就是「一张能用的账单」和「财务找你谈话」之间的差别。

⭐⭐ 考点：caching 与 Skills 同属考纲「提示复用策略」清单（caching、模块化提示、Skills 三件套已集齐两件）；判别题「什么适合做缓存标记」→ 稳定不变的部分，频繁变化的内容标记缓存反而浪费。

📖 六、模式 4：The memory tool（记忆工具）

官方原句： Some context needs to survive across sessions: user preferences, the agent's running notes, what was decided last week. The recommended primitive for this is the memory tool.

精译：有些上下文要跨会话存续：用户偏好、agent 的运行笔记、上周定了什么。官方推荐的原语级构件就是记忆工具。

⭐⭐ 三方分工（必背）

官方原句： - the AI reads and writes to a memory directory via tool calls. *- You implement the storage backend client-side — a file system, a database, an encrypted store, whatever you want. - the AI provider auto-injects a system instruction* telling the AI to check the memory directory before starting work.

精译：① the AI 经工具调用读写一个记忆目录。② 存储后端由你在客户端实现 —— 文件系统、数据库、加密存储，随你。③ 官方平台自动注入一条系统指令，让 AI 开工前先查记忆目录。

⭐⭐ 考点：责任题——「谁来持久化记忆？」→ 你（storage backend client-side）；「AI 怎么知道要查记忆？」→ 平台自动注入的系统指令。干扰项：说平台替你托管存储、或说 AI 需要你每次提醒。

📖 七、分层组合与失效模式（Layering the patterns）

官方原句： In a production app, you'll usually layer all four at once. The compliance review agent caches its system prompt and tool definitions, and pulls building code sections in just in time via lookup_building_code.

精译：在生产应用里，你通常会把四个模式同时叠上。那个合规审查 agent 缓存了系统提示词与工具定义，再按需即时经 lookup_building_code 拉取建筑规范各节。

官方原句： Each pattern handles a different failure mode: cost, window size, statelessness.* Pick the ones that match what's breaking for you*.

精译：每个模式对症一种失效模式：成本、窗口大小、无状态。哪个在坏，就用对症的那几个。

🔗 layer（叠加，动词）在第 8 课精讲 033 已收——从「叠 Skill」到「叠模式」，同一个动词贯穿。failure mode（精讲 017）在本课完成三分类闭环。

📌 八、Recap（官方六条要点）

🧠 本课 → CCAR-P 考点映射

⭐ 战略结论：本课与第 8 课合起来恰好拼出考纲领域 2 复用策略的全句（caching ＋ 模块化提示 ＋ Skills）；四模式×三失效模式的对症矩阵是判断题高频结构。另外记住那个反差点：本课机制全部走标准端点，与前两课的 beta 三件套形成对照题。

🔤 本课新生词（已回灌 30-单词表/03，2026-10-14）

✅ 本课进度

• [x] 全文精译与架构师级拆解（2026-10-14）
• [x] ⭐⭐ 记录 context 五要素、四模式性质分类（3 API ＋ 1 design pattern）与三失效模式对症矩阵
• [x] 记录 context_management ＋ compact 代码与标准端点反差点（vs 第 8/9 课 beta）
• [x] 生词回灌 30-单词表/03-考试核心生词与术语表.md（2026-10-14：新增速查 43 条 → 全表 427 条（与表内重复 3 词追加「第 10 课复现」）；新升级精讲 6 条 041–046）
• [x] 保存本课英文原文（25-English-10-Context-management.md）
• [ ] 跑通本课 runnable demo（需 Console 账号 + API key + 预付费额度）
• [ ] 官方未提供 What you'll learn 与练习区块 —— 若后续页面补全，需回填

🔗 关联

• 本课英文原文：25-English-10-Context-management.md ✅ 已存（2026-10-14）
• 上一课对照：第 9 课 MCP（beta 端点 → 本课标准端点反差）
• 复用策略拼图：第 8 课 Skills（Skills）＋ 本课（caching）＝ 考纲领域 2 复用策略全句
• 课程大纲：01-课程导读与大纲全景
• 考纲：00-CCAR-P备考蓝图
• 生词表：30-单词表/03-
• 下一课预告：What are managed agents?（Curriculum 第三段「Managed Agents」开篇）

⚠️ 语料说明：英文原文中的 model="current-model-fast" 等为抓取/去品牌化残留；其余英文引句均为官方原句，未作改动。