上下文管理：pi 能看到什么

token 是什么，为什么它很重要

跟 pi 聊天和跟人聊天有个本质区别：pi 有”记忆容量”。这个容量不是按对话条数算的，而是按 token（词元）算的。

token 是语言模型处理文本的最小单位。一个英文单词大概是 1-3 个 token，一个中文字通常是 1-2 个 token。你发给 pi 的每条消息、pi 给你的回复、它读到的文件内容——全部在消耗 token。

每个模型都有一个”上下文窗口”（context window），也就是它一次最多能”装下”多少 token。比如 Claude Sonnet 4 的窗口是 200K token，GPT-4o 是 128K。

如果你一次塞的东西超过了这个上限，模型就会报错或者返回截断的结果。 这也是为什么我们要理解 pi 的上下文管理机制。

pi 启动时会自动读哪些文件

pi 在进入交互模式时，不会把你的整个项目文件夹一股脑全读进去。它有一套自动加载规则：

AGENTS.md / CLAUDE.md

这是 pi 最核心的上下文文件。pi 会按以下顺序加载：

1. ~/.pi/agent/AGENTS.md——全局指令，影响你的所有项目
2. 从当前目录往上一级一级找，读取各层父目录中的 AGENTS.md 或 CLAUDE.md
3. 当前工作目录下的 AGENTS.md 或 CLAUDE.md

如果你两个文件都有（AGENTS.md 和 CLAUDE.md），pi 优先加载 AGENTS.md。之前用过 Claude Code 的同学可以直接复用 CLAUDE.md，不用改名。

一个典型的 AGENTS.md 长这样：

# 项目指令

## 代码规范
- 所有代码使用 TypeScript 严格模式
- 函数必须有返回值类型注解

## 工作流程
- 修改代码后运行 `npm run check`
- 不要直接对生产数据库执行迁移

## 回复风格
- 回复保持简洁，不要过度解释

更新了 AGENTS.md 之后，用 /reload 就能热重载，不用重启 pi。

如果你不想让 pi 自动加载这些文件

加个参数就行：

pi --no-context-files
pi -nc   # 短形式，效果一样

SYSTEM.md / APPEND_SYSTEM.md

AGENTS.md 是”附加指令”，pi 默认的系统提示词仍然有效。如果你需要更深度的定制，可以用这两个文件：

文件	位置	作用
SYSTEM.md	~/.pi/agent/SYSTEM.md 或 .pi/SYSTEM.md	替换默认系统提示词
APPEND_SYSTEM.md	~/.pi/agent/APPEND_SYSTEM.md 或 .pi/APPEND_SYSTEM.md	追加到默认系统提示词后面

项目文件：pi 会主动读什么

pi 不会提前把你的代码全读一遍。它是按需读取的——

• 当你提到某个文件时，pi 会用 read 工具去读那个文件
• 当你让它改代码时，pi 会读相关文件、了解上下文再下手
• 当你让它执行命令时，pi 能看到命令的输出结果

所以 pi 的视野是动态扩展的：它从 AGENTS.md 获得项目规范，然后根据你的指令去读具体的代码文件。

上下文窗口：pi 能同时”记住”多少

窗口不是无底洞

前面说过，模型有上下文窗口上限。pi 的对话也一样：随着聊天越来越长，早期对话会被”挤出去”。

怎么看当前占了多少 token？底部状态栏会实时显示用量。也可以用命令看详细情况：

/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

窗口里具体装着什么

pi 每次发送给模型的内容包括：

1. 系统提示词（定义 pi 的角色和行为）
2. AGENTS.md 等上下文文件的内容
3. 对话历史（你和 pi 之间的所有消息）
4. 工具调用结果（比如 read 读回来的文件内容、bash 的输出）
5. 预留给模型响应的空间（需留出足够的 token 让 pi 生成回复）

其中第 4 项——工具调用结果——往往是最大头。读一个几百行的文件，内容全塞进上下文里，token 消耗蹭蹭涨。

自动压缩：当对话太长时

pi 有一个叫 compaction（上下文压缩）的机制。当上下文快满的时候，pi 会自动把早期的对话总结成一段摘要，释放空间给新内容。

如果你想调整压缩策略，在 settings.json 里改：

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

配置项	含义
enabled	开/关自动压缩
reserveTokens	留给模型生成回复的 token 数
keepRecentTokens	保留不被压缩的最近 token 数

如果想手动压缩：

/compact

还能加自定义指令，告诉 pi 总结时重点关注什么：

/compact 重点关注错误修复和 API 变更

怎么控制 pi 的视野

指定要读的文件

有时候你需要 pi 关注特定文件，但它自己不会主动去读。你可以直接在对话里提：

帮我看看 src/utils/auth.ts 里的 login 函数

pi 就会去读这个文件。

也可以用 @ 语法把文件贴在消息里：

@src/utils/auth.ts 帮我分析这个文件的设计问题

限制 pi 不要读某些文件

如果你不想让 pi 碰某些文件（比如密钥文件、大日志），有两个办法：

1. 不在 .pi/ 目录之外做额外配置——pi 只读你让它读的东西
2. 如果你装了 skills 或 extensions，确保它们的配置没有开放不该开放的目录

pi 没有”自动扫描整个项目并全部读入”的行为。它只在你明确要求时读文件。这一点和 IDE 插件式的 AI 助手（比如 Copilot）不一样。

临时会话：不保留任何上下文

如果你只是想快速问一个问题，不希望之前的对话污染上下文：

pi --no-session

这个模式不会保存会话记录。用完即走，不留痕迹。

用 /reload 刷新配置

改了 AGENTS.md 或 skill 配置后，不需要重启：

/reload

这个命令会重新加载上下文文件、extension、skill、提示词模板和主题。但改了 settings.json 还是需要重启。

推理过程：给不给看

推理型模型（比如 Claude Sonnet）在回答前有一段”思考过程”。你可以控制要不要在终端里显示它：

设置项	说明
hideThinkingBlock	设为 true 隐藏推理过程，只看最终回答
showCacheMissNotices	设为 true 看缓存命不命中的提示

在交互模式里按 Ctrl+T 也能随时切换显示/隐藏推理过程。

小结

掌握三个要点，上下文管理就够用了：

• 自动加载的文件：AGENTS.md（全局 → 父目录 → 当前目录），pi 不会主动扫全项目
• token 预算：对话 + 工具结果 + 预留空间，加起来不能超过模型窗口上限
• 控制手段：/compact 手动压缩、--no-session 临时会话、/reload 热重载配置

更深层的 compaction 内部机制和 branch summarization 留到第 24 章再聊。现在你知道怎么管好 pi 的”记忆力”就够了。