Pi Agent 全指南：极简 AI Agent 的使用与定制

一、基础特性

Pi 是一款极简设计的 AI Agent，核心特点：

• 仅保留四个基础工具：读文件、写文件、修改文件、运行命令，无冗余功能
• 启动速度快、内存占用低，适合通过容器（Docker）、虚拟机（WSL/hyper-v）批量部署
• 遵循「让工具适应工作流」的设计哲学，开放高度定制化能力

二、安装与配置

1. 安装

支持 Windows、Mac 系统，通过终端执行官方一键安装命令完成部署。

2. 模型配置

两种方式：API Key（如 DeepSeek、Kimi）或模型订阅（如 OpenAI） 支持多模型切换，可通过快捷键调整模型思考强度，适配不同任务复杂度

三、核心功能

1. 指令交互模式

• 常规模式：直接输入指令交互
• 非交互模式：通过-p参数传入指令，后台静默执行，适合作为 CLI 工具

指令追加方式：

• steering：实时引导，打断当前任务调整方向，基于内层循环注入上下文实现
• follow up：排队等待，当前任务完成后执行新指令，基于外层循环实现（Windows 需先修改 PowerShell 快捷键避免冲突）

2. 会话管理

Session：会话单元，记录对话历史，支持：

• /new：新建会话（清空上下文）
• pi -c：恢复最近会话
• pi -r：选择历史会话

对话树：通过/tree命令回退到指定对话节点，创建分支尝试不同操作；仅回退对话历史，需配合 Git 回退代码 辅助命令：/clone克隆会话、/fork基于节点新建会话、/compact手动压缩上下文

3. 项目协作

指定项目文件夹后，Pi 操作默认在该目录下执行 沟通方式：支持粘贴截图反馈需求、通过@指定文件针对性修改 命令执行：

• !执行命令（AI 可见过程）
• !!执行命令（AI 不可见）

四、扩展能力

1. 插件系统

支持全局 / 项目级安装，常见插件：

• Pi Web Access：零配置联网搜索
• Pi Sub Agents：并行运行多子代理
• Pi MCP Adapter：适配 MCP 服务（如高德地图）
• BTW：旁路对话，不打断主任务的同时提问
• Plan Mode：先输出任务计划，确认后执行
• Go Mode：多轮迭代完成复杂目标
• Dynamic Workflows：调度多子代理协同完成大规模任务
• Pi WeChat Assistant：微信端交互

2. Skills 体系

遵循标准 Agent Skills 协议，可部署在项目或全局目录：

• 技能示例：playwright-cli（浏览器自动化）、markdown-convert（格式转换）
• 安装渠道：GitHub、Skill Hub，可让 AI 辅助安装依赖

3. Web UI

第三方开发的 pi-ui（4.2k Star），提供可视化界面：

• 支持项目切换、模型配置、技能 / 插件管理
• 可开启 / 关闭技能 / 插件降低 Token 消耗，内置文本转语音等功能

五、跨会话记忆

通过agent.md文件实现：

• 项目级：放在项目根目录，AI 每次对话自动读取，可让 AI 自动生成
• 全局级：放在 Pi 全局配置目录
  • Windows：C:\Users\[用户名]\.pi\agent
  • Mac：~/.pi/agent 对所有项目生效；也可创建append_system.md追加系统提示词（优先级更高）

六、安全与定制

1. 安全机制

• 基础信任：陌生目录启动时询问是否加载插件 / 技能
• 无内置沙箱，可通过容器 / 虚拟机隔离环境，或安装权限插件（如 Pi Permission System）让敏感操作需用户审批

2. 定制化

开放大量接口，可让 AI 自行开发插件：

• 定制 UI：如在对话窗口显示天气信息
• 权限控制：禁止操作.env文件、删除命令需用户确认
• 插件可部署为项目级或全局级，通过/reload加载生效

七、源码架构与 SDK

1. 核心包

• agent：统一模型调用接口，适配数十家模型厂商
• agent：实现核心双层循环机制
• cody agent：定义基础工具、系统提示词、技能 / 插件机制
• tui：实现命令行界面功能

2. SDK

• Pi AI SDK：快速接入多模型，通过createModel方法调用
• Pi Coding Agent SDK：开箱即用的编程 Agent，支持创建会话、下发任务

需要我把这份文档精简成一页速查版，方便你快速查阅命令清单吗？