$ pi –explain-yourself

Pi 刻意保持了一个小而锋利的内核。理解少数几个概念——智能体循环、工具、上下文文件、模型与会话——几乎就能解释 CLI 的全部行为。其余能力（权限、计划模式、子智能体、MCP）都被有意留给扩展实现。

智能体循环

运行时，Pi 是 @earendil-works/pi-agent-core 的一个实例：一个带工具执行与事件流的有状态智能体，构建于 @earendil-works/pi-ai（统一的多提供商 LLM API，覆盖 OpenAI、Anthropic、Google 等）之上。

当你发送一条提示，循环开始运转：

你的消息被追加到会话状态中。
组装上下文——系统提示词、上下文文件、对话历史——并发送给模型。
模型流式返回响应。它可能直接输出文本结束回合，也可能请求工具调用。
每个工具调用被执行（读文件、跑命令），其结果追加到对话中。
第 2–4 步重复——即一个“turn”的循环——直到模型不再调用工具为止。

内部，智能体发出一条类型化事件流（agent_start、turn_start、message_start、message_update、tool_execution_start、tool_result、turn_end、agent_end 等）。TUI 渲染这些事件；扩展订阅同一条事件流来拦截或增强行为。

内部还区分 AgentMessage（可携带纯 UI 或自定义消息类型）与 LLM 能理解的普通 user / assistant / toolResult 消息。每次调用模型前，convertToLlm 步骤会对历史进行过滤与转换。

内置工具

默认情况下，模型拥有四个工具：

read —— 读取文件
write —— 创建或覆写文件
edit —— 对文件打补丁
bash —— 执行 shell 命令

额外的只读工具——grep、find、ls——可通过工具选项启用。你可以从 CLI 控制工具面：

pi --tools read,grep,find,ls -p "Review the code"   # 只读运行
pi --exclude-tools bash                              # 除 bash 外全部启用
pi --no-builtin-tools                                # 仅扩展/自定义工具
pi --no-tools                                        # 纯聊天

扩展可以注册自己的工具，甚至通过注册同名工具来覆盖内置工具。

上下文文件（AGENTS.md）

Pi 在启动时加载上下文文件，以了解如何在你的项目中工作：

~/.pi/agent/AGENTS.md —— 全局指令，始终加载
AGENTS.md 或 CLAUDE.md —— 从父目录（自 cwd 向上逐级查找）与当前目录加载

一个典型的项目文件：

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

用 --no-context-files（-nc）禁用加载。修改上下文文件后，重启 Pi 或运行 /reload。

你还可以用 .pi/SYSTEM.md（项目级）或 ~/.pi/agent/SYSTEM.md（全局）整体替换系统提示词，或在任一位置用 APPEND_SYSTEM.md 追加内容。

@-文件引用与 shell 转义

两个编辑器特性打通了文件系统与对话：

输入 @ 模糊搜索项目文件并附加到消息中。命令行用法：pi @src/app.ts @src/app.test.ts "Review these together"。图片同样支持：pi -p @screenshot.png "What's in this image?"。
!command 执行 shell 命令并将输出注入模型上下文；!!command 执行但不污染上下文。

模型与提供商

Pi 内置提供商模型目录（缓存在 ~/.pi/agent/models-store.json 供离线使用）。凭据来源包括 OAuth 订阅（/login）、环境变量或 ~/.pi/agent/auth.json——Anthropic、OpenAI、Google Gemini、DeepSeek、Groq、xAI、OpenRouter、Mistral、Cerebras 等数十家；云提供商（Bedrock、Azure、Vertex）以及通过 llama.cpp 的本地模型也受支持。扩展还可以通过 pi.registerProvider() 注册完全自定义的提供商。

切换模型是一等操作：

/model 或 Ctrl+L —— 打开模型选择器
Ctrl+P / Shift+Ctrl+P —— 在你的限定范围（scoped）模型间循环（用 /scoped-models 或 --models "claude-*,gpt-4o" 配置）
Shift+Tab —— 循环思考等级（off、minimal、low、medium、high、xhigh、max）

命令行用法：

pi --model openai/gpt-4o "Help me refactor"
pi --model sonnet:high "Solve this complex problem"
pi --list-models anthropic

在 ~/.pi/agent/settings.json 中用 defaultProvider、defaultModel、defaultThinkingLevel 设置默认值。

会话

会话自动保存到 ~/.pi/agent/sessions/，按工作目录组织。每个会话是一个 JSONL 文件，结构为树：每条记录有 id 和 parentId，当前位置是活动叶子节点。这支持分支式工作流：

/tree —— 跳转到此前任意节点并从此继续；被放弃的分支可以被总结
/fork —— 从某个历史用户消息创建新的会话文件
/clone —— 将当前活动分支复制为新会话
/compact [prompt] —— 总结较早的消息以释放上下文（自动压缩默认开启；通过 compaction.reserveTokens 与 compaction.keepRecentTokens 调节）

Shell 侧：pi -c 继续最近的会话，pi -r 打开会话选择器（支持重命名、删除、搜索），--no-session 以临时模式运行，--name 为会话命名以便日后检索。/export 将会话导出为 HTML；/share 上传为私有 GitHub gist。

界面：TUI 及其他

默认界面是基于 @earendil-works/pi-tui（一个带差分渲染的终端 UI 库）构建的 TUI，分为四个区域：启动头部（快捷键、已加载的上下文文件、技能、扩展）、消息流、编辑器（边框颜色表示思考等级）与底部状态栏（cwd、会话名、token/缓存用量、费用、上下文占用、当前模型）。

但 TUI 只是同一智能体内核的消费方之一：

pi -p "..." —— print 模式：一次性、非交互
--mode json —— 每个事件输出为一行 JSON，便于脚本处理
--mode rpc —— 通过 stdin/stdout 的 RPC，用于把 Pi 嵌入其他进程
@earendil-works/pi-agent-core —— 以 npm 库形式提供的运行时，用于构建你自己的智能体应用

Pi 刻意不包含的东西

没有内置 MCP、子智能体、权限弹窗、计划模式、待办列表或后台 bash。设计哲学是最小内核加扩展系统；完整 rationale 见作者的博客文章。

核心概念