在正式使用 Pi Agent 之前先了解它的核心概念和工作方式能帮助你更快上手。一句话理解 Pi AgentPi 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技能MarkdownSKILL.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/ 中。会话内部是树状结构你可以在任意历史节点「分叉」出新的探索方向而不会丢失之前的对话。这在你需要试验不同的实现方案时非常有用——每条思路都可以独立保留、随时回溯。