Context Assembly 与 Token Budget

1. 为什么这组知识要一起学

把 Context 当作有限的运行时工作集，学习如何组装、筛选、压缩、缓存，并在长任务中维持信息连续性。

这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。

2. Mental Model

Context 是每次推理的有限 working set，不是整个知识宇宙。目标是最大化“未来一步有用的信息 / token”。

Instructions + Task + History + Tool Catalog + Results + State + Memory + Retrieval → Selection → Budget → Compaction → Model Input

3. 核心机制

Context Assembly Pipeline

Context assembly 应成为显式 pipeline：从不同来源收集带 provenance 的 ContextItem，再做 selection、预算和 compaction，而不是各模块随意 append message。

Token Budget

预算层把总 context 分给 protected instructions、active state、tools、history、retrieval 和 output reserve；超过 soft limit 先清理可重建信息，再进入 compaction。

Context Selection

选择策略不能只按“最近”。任务依赖、重要约束和 unresolved state 可能比时间更重要；最好保留选择原因以便做 ablation。

4. 最小实现 / 伪代码

下面代码只表达边界和生命周期，不要求照抄到项目中：

class ContextManager:
    async def build(self, state, budget):
        items = await self.collect(state)
        selected = self.selector.select(items, budget)
        return self.renderer.render(selected)

真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。

5. 在 Shadow Harness 中怎么落地

独立 ContextManager、ContextItem、TokenEstimator、SelectionPolicy、ToolResultPolicy、Compactor；所有来源带 provenance 和可重建引用。

建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。

6. Production Engineering 检查项

• 保护目标/约束/未决问题
• tool schema 和 tool result 都计入预算
• 优先 deterministic projection 再 LLM summary
• 摘要不能成为唯一事实源

7. Failure Modes

7.1 全历史无脑塞入

当出现「全历史无脑塞入」时，用 context snapshot 检查来源、token 占比、protected state、selection reason，并对可疑项做 ablation。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.2 机械截断最旧消息

当出现「机械截断最旧消息」时，用 context snapshot 检查来源、token 占比、protected state、selection reason，并对可疑项做 ablation。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.3 summary-of-summary 漂移

当出现「summary-of-summary 漂移」时，用 context snapshot 检查来源、token 占比、protected state、selection reason，并对可疑项做 ablation。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.4 丢 provenance 后无法重新 grounding

当出现「丢 provenance 后无法重新 grounding」时，用 context snapshot 检查来源、token 占比、protected state、selection reason，并对可疑项做 ablation。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

8. Trade-offs

全量 context 信息完整但贵；选择式 context 成本低但依赖选择质量；JIT retrieval 增加调用但减少常驻 token。

设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。

9. Experiment / Evaluation

做 context ablation：full/selective/compacted/JIT，比较任务成功率、输入 token、约束遗失率与 latency。

实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。

10. 常见问题

基础：Context Assembly Pipeline 最容易被误解的点是什么？

Context assembly 应成为显式 pipeline：从不同来源收集带 provenance 的 ContextItem，再做 selection、预算和 compaction，而不是各模块随意 append message。

机制：这些能力在一次 Run 的哪个生命周期阶段生效？

沿着 Instructions + Task + History + Tool Catalog + Results + State + Memory + Retrieval → Selection → Budget → Compaction → Model Input 找位置，并明确它的输入、输出、持久化事实和失败传播。

工程：如果这一层失败，应该由谁恢复？

先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。

设计：规模扩大 10 倍后，哪个假设最先失效？

优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。

11. Sources

• Anthropic — Effective context engineering for AI agents
• Anthropic — Advanced tool use
• Anthropic — Effective harnesses for long-running agents

12. 本文结论

掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。