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 协议集成 | 进程间通信、编辑器插件 |
交互模式直接启动，进入 TUI 界面：
$ pi Pi Agent 0.1.x | ~/projects/runoob-demo claude-sonnet-4 | 上下文 2% | $0.0000 >
Print 模式回答完就退出，适合放进脚本：
$ pi -p "总结这个项目" 这是一个 TypeScript 命令行工具，核心逻辑位于 src/ 目录，包含会话管理、工具调度和扩展加载三个模块。 Tokens: 1.2k 输入 / 320 输出 | 费用 $0.0081
JSON 模式把每个事件输出为一行 JSON，方便程序解析：
$ pi --mode json -p "总结这个项目"
{"type":"session","id":"a1b2c3d4"}
{"type":"message_start","role":"assistant"}
{"type":"message_end","usage":{"input":1200,"output":320}}
RPC 模式通过 stdin/stdout 收发 JSONL 消息，供编辑器插件调用：
$ pi --mode rpc
{"id":1,"method":"prompt","params":{"message":"列出 src 目录"}}
{"id":1,"result":{"state":"idle","messages":2}}
作为初学者，你大部分时间都在交互模式下工作。
当你熟练后，Print 模式可以用于脚本自动化。
内置工具
Pi Agent 启动后会默认给予 AI 下面四种内置工具，另有 grep、find、ls 三个只读工具可选开启：
| 工具名 | 功能 | 示例 | 默认状态 |
|---|---|---|---|
| read | 读取文件内容 | AI 读取 src/main.ts 理解代码逻辑 | 默认启用 |
| write | 创建或覆盖文件 | AI 创建新文件或重写整个文件 | 默认启用 |
| edit | 精确替换文件中的内容 | AI 修改函数中的某几行代码 | 默认启用 |
| bash | 执行 shell 命令 | AI 运行测试、安装依赖、执行 lint | 默认启用 |
| grep | 在文件中搜索文本 | AI 搜索某个函数在哪些文件中被调用 | 可选开启 |
| find | 按名称搜索文件 | AI 找出所有名为 *.test.ts 的文件 | 可选开启 |
| ls | 列出目录内容 | AI 查看目录结构定位模块 | 可选开启 |
三个只读工具通过 --tools 参数手动开启，例如 pi --tools read,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/ 中。
会话内部是树状结构：你可以在任意历史节点「分叉」出新的探索方向，而不会丢失之前的对话。
这在你需要试验不同的实现方案时非常有用——每条思路都可以独立保留、随时回溯。