Pi Agent 核心概念速览
在正式使用 Pi Agent 之前，先了解它的核心概念和工作方式，能帮助你更快上手。
一句话理解 Pi Agent
Pi Agent 是一个运行在终端里的 AI 编程助手。
启动后你会看到类似聊天软件的界面，输入自然语言需求，AI 就能读取你的代码、执行命令、修改文件。
四种运行模式
Pi Agent 支持四种运行模式，适应不同场景：
| 模式 | 命令 | 说明 | 适用场景 |
|---|---|---|---|
| 交互模式 | pi（默认） | 终端 TUI 界面，实时对话，支持所有功能 | 日常开发、交互式编程 |
| Print 模式 | pi -p "提示词" | 一次性问答，输出结果后退出 | 脚本集成、快速查询 |
| JSON 模式 | pi --mode json | 所有事件以 JSON 行输出，适合程序解析 | 工具链集成、数据分析 |
| RPC 模式 | pi --mode rpc | 通过 stdin/stdout 的 JSONL 协议集成 | 进程间通信、编辑器插件 |
作为初学者，你大部分时间都在交互模式下工作。
当你熟练后，Print 模式可以用于脚本自动化。
内置工具
Pi Agent 启动后会默认给予 AI 下面四种内置工具：
| 工具名 | 功能 | 示例 |
|---|---|---|
| read | 读取文件内容 | AI 读取 src/main.ts 理解代码逻辑 |
| write | 创建或覆盖文件 | AI 创建新文件或重写整个文件 |
| edit | 精确替换文件中的内容 | AI 修改函数中的某几行代码 |
| bash | 执行 shell 命令 | AI 运行测试、安装依赖、执行 lint |
此外还有三个只读工具，默认不启用但可以通过 --tools 参数手动开启：
- grep - 在文件中搜索文本
- find - 按名称搜索文件
- ls - 列出目录内容
扩展体系
Pi Agent 通过以下五种方式扩展功能：
| 扩展方式 | 文件格式 | 用途 | 难度 |
|---|---|---|---|
| Extensions（扩展） | TypeScript（.ts） | 注册自定义工具、事件监听、命令、UI 组件 | 需要编程 |
| Skills（技能） | Markdown（SKILL.md） | 提供专业领域的工作流指令和脚本 | 会写 Markdown 即可 |
| Prompt Templates（提示词模板） | Markdown（.md） | 可复用的提示词，支持参数 | 最简单 |
| Themes（主题） | JSON（.json） | 自定义终端界面配色 | 简单 |
| Packages（包） | npm/git 项目 | 打包和分享以上四种资源 | 按需 |
作为初学者，你不需要立即理解所有扩展方式。先从基础使用开始，随着需求增长再逐步探索扩展系统。
文件加载顺序
Pi Agent 启动时会自动加载项目指令文件，让你可以约定 AI 的行为规范：
- 全局配置：~/.pi/agent/AGENTS.md - 对所有项目生效的通用指令
- 项目配置：项目目录及父目录中的 AGENTS.md 或 CLAUDE.md
项目级的配置会从父目录向上遍历加载，最终和当前目录的配置合并。
如果你之前使用 Claude Code，可以直接复用已有的 CLAUDE.md 文件，Pi Agent 会自动识别加载。
会话与分支
Pi Agent 的会话系统是其最独特的特性之一。
每次对话会自动保存为一个会话文件，存放在 ~/.pi/agent/sessions/ 中。
会话内部是树状结构：你可以在任意历史节点「分叉」出新的探索方向，而不会丢失之前的对话。
这在你需要试验不同的实现方案时非常有用——每条思路都可以独立保留、随时回溯。