# Context Engineering 配套指南

本系列从原有九篇短文重写为十篇长文，以虚构售后任务解释上下文组装、预算、按需加载、状态、长期记忆、压缩、缓存、隔离、生产模块与贯穿实践。Python 为正文示例，Java 保留为框架接入参考。

本轮修订日期：2026-09-11。没有执行示例、测试、模型调用、安装、Astro 检查、构建或预览。下述命令供读者运行，不是本次运行记录。所有政策、订单、成本与预期输出均为教学材料。

## 阅读正文

1. [模型这次应该看到什么：理解上下文工程与上下文组装](/posts/agent_runtime/4.context_engineering/01-context-assembly/)
2. [上下文不是越长越好：Token 预算、信息选择与排列](/posts/agent_runtime/4.context_engineering/02-budget-and-selection/)
3. [需要时再加载：渐进式披露、工具发现与外部工作区](/posts/agent_runtime/4.context_engineering/03-progressive-loading/)
4. [一次任务怎样继续：会话历史、工作状态与 Checkpoint](/posts/agent_runtime/4.context_engineering/04-state-and-checkpoints/)
5. [哪些信息值得长期记住：记忆的提取、读取、纠正与遗忘](/posts/agent_runtime/4.context_engineering/05-memory-lifecycle/)
6. [长会话怎样压缩：从聊天摘要到可继续执行的任务快照](/posts/agent_runtime/4.context_engineering/06-compaction-and-recovery/)
7. [哪些上下文可以复用：缓存机制、命中条件与失效](/posts/agent_runtime/4.context_engineering/07-cache-and-invalidation/)
8. [谁可以看到什么：上下文隔离、可信边界与多 Agent 交接](/posts/agent_runtime/4.context_engineering/08-isolation-and-handoffs/)
9. [生产中的上下文工程：设计一个可追溯的上下文管理模块](/posts/agent_runtime/4.context_engineering/09-production-design/)
10. [把上下文工程串起来：实现组装流程，并定位回答失败](/posts/agent_runtime/4.context_engineering/10-context-in-practice/)

## 先选择运行哪一组

标准库示例需要 Python 3.10 或更高版本，不需要安装 LangGraph 或提供 API Key。源文件下载后要放在同一目录；下载一个入口文件不会自动下载它的同目录依赖。

| 文件 | 观察什么 | 依赖与边界 |
| --- | --- | --- |
| [budget_selection.py](python/budget_selection.py) | 必需项与完整政策包选择 | 人工成本；不是 Token 计数 |
| [progressive_loading.py](python/progressive_loading.py) | 目录发现、授权读取、版本匹配 | 内存资源；不访问文件或网络 |
| [state_transitions.py](python/state_transitions.py) | 用户改口与 revision 冲突 | 字典顺序模拟；不是数据库事务 |
| [memory_lifecycle.py](python/memory_lifecycle.py) | 显式偏好更新、重复事件与删除 | 预先按顺序提供候选；无模型提取、无外部索引 |
| [compaction_snapshot.py](python/compaction_snapshot.py) | 从状态生成快照及字段对照 | 同时下载 state_transitions.py；不是生成式摘要 |
| [cache_versions.py](python/cache_versions.py) | 版本、授权、TTL 改变读取结果 | 应用缓存；不是服务端前缀缓存 |
| [handoff_context.py](python/handoff_context.py) | 字段投影与引用范围检查 | 不包含真实子 Agent；引用存在不等于结论正确 |
| [context_pipeline.py](python/context_pipeline.py) | 授权、版本、必需依赖、预算与 trace | JSON 字符容量模拟；不计真实 Token |
| [context_walkthrough.py](python/context_walkthrough.py) | 两轮状态变化、快照与缓存 | 同时下载 pipeline、state、memory、compaction、cache 五个文件 |
| [langgraph_messages.py](python/langgraph_messages.py) | 同 ID 消息替换与移除 | 单独源码导读环境；无模型调用 |

```bash
# 切换到已经下载了同目录依赖文件的目录，再运行主线入口。
# 主线只依赖 Python 标准库，不需要 pip install。
python context_walkthrough.py
```

综合示例预期保留 state、order、condition、conclusion；拒绝其他主体资料与不匹配政策版本，排除超长可选历史。第二轮状态 revision 改变，旧组装缓存不能复用。删除条件片段或缩小预算会返回明确的失败原因。以上为按源码推导的行为，本轮未运行确认。

## 三个需要明确替换的接口

`fixture()` 是手工资料提供器，生产要替换成带授权过滤的数据查询，并返回来源版本。`Principal` 在示例里手工构造，生产应来自可信认证上下文。`demo_char_meter()` 计算序列化字符数，生产要替换成目标接口计数或估算，并校准服务端 usage。

`render()` 返回内部教学请求结构。真正发送前，适配器须处理模型支持的角色、工具字段、结构化约束与多模态格式；不要直接把含有空 tools 数组的内部结构发送到任意供应商接口。本轮未提供或执行真实模型客户端。

内存状态、记忆、缓存只展示算法。不提供跨进程原子性、持久化、完整自然语言理解、线上授权或副作用幂等。MemoryStore 只处理已按来源顺序到达的显式偏好，不将它描述成通用异步记忆系统。

## 原示例继续保留

[context_assembler.py](python/context_assembler.py) 保留最小的“租户过滤、排序、装入预算”演示；它没有必需依赖、最终结构计数与完整生产授权。原 50 单位示例中的 token_cost 是人工数字。

[memory_graph.py](python/memory_graph.py) 演示线程消息累积。reply 是本地统计函数，不是模型；InMemorySaver 不提供进程重启后的恢复。原 [requirements.txt](python/requirements.txt) 保留 LangChain 1.3.17、LangGraph 1.2.11 声明，不声称本轮已安装或验证其可用性。

## 固定版本源码导读

正文读取 [LangGraph 1.0.0 的消息归并实现](https://github.com/langchain-ai/langgraph/blob/1.0.0/libs/langgraph/langgraph/graph/message.py)，沿 MessagesState 与 add_messages 理解状态字段合并。不是当前最新版本推荐，也没有完成整个检查点后端的源码审计。

为导读单独提供 [source-requirements.txt](python/source-requirements.txt)，固定 langgraph 1.0.0 与 langchain-core 1.0.0；它不是包含所有传递依赖和哈希的完整锁文件。不要与原 requirements.txt 混装。

```bash
# 单独建立源码导读环境；这些命令未在本次修订中执行。
python3 -m venv .venv-context-source
source .venv-context-source/bin/activate
python -m pip install -r source-requirements.txt
python langgraph_messages.py
```

框架删除消息只改变对应状态视图，不会自动删除所有历史检查点、外部日志、索引和备份。数据删除需要完整生命周期设计。

## Java 框架入口

继续提供 [Java README](java/README.md)、[pom.xml](java/pom.xml) 与 [ContextHarnessDemo.java](java/src/main/java/dev/elaine/examples/ContextHarnessDemo.java)。此示例实际模型调用需要 JDK、Maven 和配置的供应商凭据；运行可能产生调用费用。本次未编译、未调用。

示例的 userId/sessionId 是本地演示值，工作区为固定相对路径。正式服务必须由认证身份生成作用域，并隔离文件、状态、缓存与日志。30 条触发、保留 10 条是已有示例配置，不是推荐给所有任务的压缩阈值。

## 来源与修订边界

- [上下文工程整体视角](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)：按调用循环维护输入。
- [Lost in the Middle](https://arxiv.org/abs/2307.03172)：所研究模型与任务中的长上下文位置影响，不推广为所有模型的定律。
- [LangGraph Persistence](https://docs.langchain.com/oss/python/langgraph/persistence)：线程与检查点。
- [LangChain Memory overview](https://docs.langchain.com/oss/python/concepts/memory)：记忆类型与维护。
- [Claude Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)：具体接入时核对缓存协议，不固定价格或容量声明。
- [AgentScope Workspace](https://java.agentscope.io/v2/en/docs/harness/workspace)、[Compaction](https://java.agentscope.io/v2/en/docs/harness/compaction)：保留 Java 接入入口。

## 旧文章迁移

旧路线与 Context Schema 合并到第一篇；预算、渐进加载分别进入第二、三篇；短期与长期记忆拆到第四、五篇，写入与淘汰并入第五篇；压缩、缓存、权限分别进入第六至八篇；第九、十篇为生产设计和贯穿实战。旧 URL 配置跳转到主要承接文章，详见 [迁移表](/examples/series-migration.json)。

重写保留分类 ID context-engineering，并使用 01—10 文件顺序。跳转是源码配置，未经本轮构建或发布，不能表述为已上线。