HoRain云--Pi Agent 上下文管理
上下文管理是高效使用 Pi Agent 的核心技能。本章介绍如何通过环境文件控制 AI 的行为，以及如何管理对话上下文。
上下文文件概述
Pi Agent 在启动时会自动加载项目指令文件，让 AI 了解你的项目规范、命令和偏好。
这些文件告诉 AI「在这个项目中应该怎样工作」。
AGENTS.md / CLAUDE.md
这是 Pi Agent 最重要的上下文文件，加载顺序为：
- ~/.pi/agent/AGENTS.md - 全局指令，对所有项目生效
- 从当前目录向上遍历各级父目录中的 AGENTS.md 或 CLAUDE.md
- 当前目录下的 AGENTS.md 或 CLAUDE.md
以下是一个完整的 AGENTS.md 示例：
# 项目指令 ## 代码规范 - 所有代码使用 TypeScript 严格模式 - 函数必须有返回值类型注解 - 使用 ESLint 和 Prettier 保持代码风格一致 ## 工作流程 - 代码修改后运行 `npm run check` 验证 - 提交前运行 `npm test` 确保测试通过 - 不要在本地直接执行生产环境的数据库迁移 ## 安全提示 - 不要将 API Key 或密码写入代码 - 敏感配置使用环境变量 ## 回复风格 - 回复保持简洁，不要过度解释显而易见的代码 - 出现问题时先给出修复方案，再解释原因
更新 AGENTS.md 后，使用 /reload 命令即可热重载，无需重启 Pi Agent。
如果你同时有 AGENTS.md 和 CLAUDE.md，Pi Agent 会优先加载 AGENTS.md。如果你之前使用 Claude Code，可以直接复用已有的 CLAUDE.md。
如果想禁用上下文文件加载，使用命令行参数：
$ pi --no-context-files $ pi -nc # 短形式
SYSTEM.md
如果你需要完全替换 Pi Agent 的默认系统提示词，可以创建 SYSTEM.md 文件：
| 文件路径 | 作用 |
|---|---|
| ~/.pi/agent/SYSTEM.md | 全局替换默认系统提示词 |
| 项目根目录/.pi/SYSTEM.md | 项目级替换默认系统提示词 |
如果你只想追加内容而非替换，使用 APPEND_SYSTEM.md 替代 SYSTEM.md：
| 文件路径 | 作用 |
|---|---|
| ~/.pi/agent/APPEND_SYSTEM.md | 全局追加到默认系统提示词之后 |
| 项目根目录/.pi/APPEND_SYSTEM.md | 项目级追加 |
大多数情况下你不需要修改系统提示词。AGENTS.md 已经能覆盖绝大部分的定制需求。SYSTEM.md 适用于需要深度定制 AI 行为的场景，修改不当可能影响 AI 的工作效果。
上下文压缩（Compaction）
当对话变得很长时，AI 的上下文窗口（context window）会逐渐被占满。
Pi Agent 通过上下文压缩（Compaction）来解决这个问题——它会自动将较早的对话内容总结为简短的摘要，释放上下文空间。
自动压缩
默认情况下，Pi Agent 会在上下文接近模型限制时自动触发压缩。
你可以在设置中调整压缩行为：
{ "compaction": { "enabled": true, "reserveTokens": 16384, "keepRecentTokens": 20000 } }| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| compaction.enabled | boolean | true | 是否启用自动压缩 |
| compaction.reserveTokens | number | 16384 | 预留给 LLM 响应的 token 数 |
| compaction.keepRecentTokens | number | 20000 | 保留不压缩的最近 token 数 |
手动压缩
你也可以随时手动触发压缩：
/compact
压缩时可以添加自定义指令，告诉 AI 在总结时关注哪些内容：
/compact 重点关注错误修复和 API 变更
压缩是不可逆的操作。被压缩的对话内容会变成摘要，原始细节会丢失。如果你认为某些细节在未来可能有用，可以在压缩前使用 /fork 分叉出一个新会话保存完整历史。
推理过程显示
推理型模型（如 Claude Sonnet 系列）在回答之前会进行思考。
你可以通过以下方式控制推理过程的显示：
| 设置 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| hideThinkingBlock | boolean | false | 隐藏推理过程，仅显示最终回答 |
| showCacheMissNotices | boolean | false | 显示缓存未命中的提示 |
使用 Ctrl+T 可以在对话过程中随时切换推理过程的显示/隐藏。
热重载（/reload）
当你修改了以下内容时，使用 /reload 可以让变更立即生效，无需重启：
- AGENTS.md 或 CLAUDE.md（上下文文件）
- Extensions（扩展）
- Skills（技能）
- 提示词模板
- 主题文件
- 键盘快捷键配置
需要重启的情况：
- 修改了 ~/.pi/agent/settings.json 中的某些设置
- 安装了新的扩展包
- 修改了 auth.json 凭证
上下文使用量查看
底部状态栏会实时显示当前上下文的 token 用量和费用。
使用 /session 命令可以查看更详细的信息：
/session
输出示例：
Session file: ~/.pi/agent/sessions/my-project/abc123.jsonl Session ID: abc123-def456 Messages: 42 Tokens: 85,432 Cost: $0.52 Current model: claude-sonnet-4-20250514