Pi Agent: 上下文管理
最后更新：2026-08-31
上下文就是 Agent 的"短期记忆"——管好它，Agent 才不会"说着说着就忘了"。
1. 什么是上下文
上下文（Context）是 Agent 在一次会话中积累的所有信息，包括：
- 系统提示词（System Prompt）
- 对话历史（Chat History）
- 工具调用记录（Tool Calls）
- 用户注入的额外信息（Injected Context）
TEXT
📖 仅展示
上下文结构
├── System Prompt → 固定指令（角色定义、行为约束）
├── Chat History → 动态积累（用户消息 + Agent 回复）
├── Tool Calls → 工具调用过程和结果
└── Injected Context → 额外注入（文件内容、API 数据等）
2. 上下文窗口
上下文窗口决定了 Agent 一次能"记住"多少内容：
(1) 设置窗口大小
PYTHON
from pi_agent import Agent
# 小窗口：节省 token，适合简单对话
agent = Agent(name="quick", context_window=2048)
# 大窗口：记住更多历史，适合长对话
agent = Agent(name="long", context_window=16384)
# 最大化：利用模型全部能力
agent = Agent(name="full", context_window=65536)
(2) 窗口与费用的关系
| 窗口大小 | 适合场景 | token 消耗 |
|---|---|---|
| 2K | 问答、简单指令 | 低 |
| 8K | 多轮对话、代码审查 | 中 |
| 32K | 长文档分析 | 高 |
| 64K | 大型项目分析 | 很高 |
Alice 发现："大窗口不代表一定要填满——实际消耗取决于你发送的内容量，窗口只是上限。"
3. 截断策略
当对话超出窗口时，Pi Agent 提供多种截断策略：
PYTHON
from pi_agent import Agent
# 默认：移除最早的消息
agent = Agent(truncation_strategy="remove_oldest")
# 摘要：用 AI 总结旧消息，保留要点
agent = Agent(truncation_strategy="summarize")
# 滑动窗口：保留最近 N 轮对话
agent = Agent(truncation_strategy="sliding_window", keep_recent=10)
| 策略 | 优点 | 缺点 |
|---|---|---|
| remove_oldest | 简单高效 | 丢失早期信息 |
| summarize | 保留要点 | 额外 token 消耗 |
| sliding_window | 可控 | 可能丢失重要上下文 |
4. 上下文注入
(1) 手动注入
PYTHON
from pi_agent import Agent
agent = Agent(name="coder")
# 注入文件内容作为上下文
with open("main.py") as f:
agent.inject_context("current_file", f.read())
# 注入项目信息
agent.inject_context("project_info", {
"name": "my_app",
"framework": "FastAPI",
"python_version": "3.11"
})
response = agent.chat("帮我添加一个健康检查接口")
# Agent 知道项目使用 FastAPI，会生成 FastAPI 风格的代码
(2) 自动注入
PYTHON
agent = Agent(
name="auto",
auto_context=True # 自动注入工作目录结构、git 信息等
)
▶ 示例 1：项目上下文助手（难度⭐⭐）
PYTHON
from pi_agent import Agent
import os
agent = Agent(
name="project_helper",
system_prompt="你是项目助手，根据项目上下文回答问题"
)
# 注入项目结构
tree = os.popen("find . -type f -name '*.py' | head -20").read()
agent.inject_context("project_tree", tree)
# 注入 requirements.txt
if os.path.exists("requirements.txt"):
with open("requirements.txt") as f:
agent.inject_context("dependencies", f.read())
response = agent.chat("这个项目用了哪些主要依赖？")
5. 上下文优化技巧
(1) 精简系统提示词
PYTHON
# 冗长
agent = Agent(system_prompt="你是一个非常优秀的编程助手，擅长Python，回答要详细...")
# 精简
agent = Agent(system_prompt="Python专家。回答简洁。")
(2) 清理无关历史
PYTHON
# 话题切换时清空历史
agent.clear_history()
# 只保留最近 N 轮
agent.keep_recent(5)
(3) 使用摘要压缩
PYTHON
# 手动触发上下文摘要
agent.summarize_context()
# 设置自动摘要阈值
agent = Agent(auto_summarize_threshold=3000)
❓ 常见问题
Q 上下文窗口和模型的上下文长度是什么关系？
A 上下文窗口是你设置的 Agent 级别上限，不能超过模型本身的最大上下文长度。比如 deepseek-chat 支持 64K，你设置 100K 也是无效的。
Q inject_context 和直接写在消息里有什么区别？
A inject_context 的内容会始终保留在上下文中（不会被截断策略删除），而消息里的内容可能被截断。适合放重要的项目信息。
Q 自动摘要消耗多少额外 token？
A 大约是被摘要内容的 10%-20%。比如摘要 4000 token 的历史，额外消耗约 400-800 token。
📖 小节
- 上下文 = 系统提示 + 对话历史 + 工具调用 + 注入内容
- 上下文窗口决定记忆上限，越大越强但也越贵
- 三种截断策略：remove_oldest、summarize、sliding_window
- inject_context 注入持久信息，不会被截断策略删除
- 精简提示词、清理历史、自动摘要三大优化技巧
📝 作业
- 基础题（难度⭐）：创建一个 Agent，设置不同的 context_window，观察多轮对话中何时开始"遗忘"。
- 进阶题（难度⭐⭐）：对比 remove_oldest 和 summarize 两种截断策略的效果差异。
- 挑战题（难度⭐⭐⭐）：实现一个"智能上下文管理器"，根据对话内容自动判断何时该清理历史、何时该摘要。
