上下文管理是高效使用 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.mdPi 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.enabledbooleantrue是否启用自动压缩compaction.reserveTokensnumber16384预留给 LLM 响应的 token 数compaction.keepRecentTokensnumber20000保留不压缩的最近 token 数手动压缩你也可以随时手动触发压缩/compact压缩时可以添加自定义指令告诉 AI 在总结时关注哪些内容/compact 重点关注错误修复和 API 变更压缩是不可逆的操作。被压缩的对话内容会变成摘要原始细节会丢失。如果你认为某些细节在未来可能有用可以在压缩前使用 /fork 分叉出一个新会话保存完整历史。推理过程显示推理型模型如 Claude Sonnet 系列在回答之前会进行思考。你可以通过以下方式控制推理过程的显示设置类型默认值说明hideThinkingBlockbooleanfalse隐藏推理过程仅显示最终回答showCacheMissNoticesbooleanfalse显示缓存未命中的提示使用 CtrlT 可以在对话过程中随时切换推理过程的显示/隐藏。热重载/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