Pi Agent实战：终端极简AI编程助手完整使用指南

为什么Pi Agent值得关注

AI编程工具层出不穷，每天都有新产品在社交媒体上引发热议。但大多数工具要么功能臃肿，要么依赖复杂的配置流程。Pi Agent（pi.dev）走了一条完全不同的路——它是一个开源的极简AI代理，直接运行在终端中，没有MCP设置、没有子代理、没有权限弹窗，只使用最基本的CLI命令来完成工作。

关于MCP：MCP（Model Context Protocol）是Anthropic于2024年底推出的开放协议，旨在标准化AI模型与外部工具、数据源之间的连接方式，类似于AI世界的"USB接口"。然而MCP的配置往往需要JSON服务器定义、权限声明和进程管理，对于追求快速迭代的工程师来说增加了不少摩擦成本。Pi Agent选择绕过这一层抽象，直接用shell命令完成同等任务，体现了Unix哲学中"做一件事并做好"的传统。

这种"少即是多"的设计哲学，让Pi Agent成为了一位资深DevOps工程师日常唯一使用的AI工具，覆盖了代码开发、脚本编写、Ansible/Terraform基础设施即代码、服务器运维、容器编排等所有家庭实验室场景。

Pi Agent的核心设计理念

极简但不简陋

Pi Agent的开发者刻意避免了功能堆砌。与Cloud Code、OpenAI Codex等大平台工具不同，Pi专注于几个核心能力：

• agents.md上下文：类似README但面向AI的项目说明文件
• Skills（技能）：可复用的能力定义
• Prompts（提示词）：自定义斜杠命令
• 多种输入模式：直接命令执行与对话式交互

没有规划模式，没有反复确认，就是直接执行CLI命令。这种设计也让它特别适合搭配本地LLM使用——本地运行的开源模型（如通过Ollama部署的Llama 3、Mistral等）受硬件内存限制，通常只有4K到32K tokens的上下文容量，而Pi Agent"所需上下文极少"的特点，使其与本地LLM的兼容性远优于需要注入大量工具描述和系统提示的MCP架构工具。对于在家庭实验室中用消费级GPU运行本地模型的用户，这意味着更快的推理速度和更低的显存压力。

广泛的模型支持

Pi支持超过15种不同的AI提供商，包括：

• 订阅服务：ChatGPT Plus、Claude Pro/Max、GitHub Copilot
• API密钥：Amazon、Cloudflare、DeepSeek、Google Gemini、Groq、Hugging Face等
• 本地模型：通过models.json配置Ollama、LM Studio等OpenAI兼容的LLM

实战：在家庭实验室中使用Pi Agent

基础操作与思维模式配置

安装Pi后，通过pi命令启动代理，使用/model选择模型（推荐GPT 5.5）。Pi提供了不同的思维模式（thinking mode）设置：

• Minimal/Low：适合简单任务，响应快速
• Medium/High：适合复杂编码和推理任务

一个实用技巧：在对话中输入感叹号!前缀，可以直接在shell中执行命令而不发送给AI。比如!ls或!docker ps，无需退出Pi会话。

agents.md配置：让AI真正理解你的项目

agents.md是Pi Agent最核心的概念，其设计理念源于"上下文工程"（Context Engineering）这一新兴实践——即系统性地设计AI所能获取的信息，以最大化其任务完成质量。这与提示词工程（Prompt Engineering）的区别在于：提示词工程关注单次对话的措辞优化，而上下文工程关注持久化的、结构化的背景知识注入。

agents.md本质上是一份"AI操作手册"，将原本散落在工程师脑海中的隐性知识显式化。类似的概念在其他工具中也有体现：Cursor的.cursorrules文件、GitHub Copilot的copilot-instructions.md，以及Claude项目中的"项目说明"功能，都是同一思路的不同实现。Pi Agent将这一机制作为核心设计而非可选功能，反映了其对"AI理解项目"重要性的深刻认识。

就像README帮助人类理解项目一样，agents.md帮助AI理解项目上下文。一个典型的agents.md包含：

• 仓库地图：解释目录结构，如"Docker Compose部署文件在此目录"
• 部署信息：服务器地址、FQDN、运行位置
• 操作规范：如"创建资源前先检查现有文件，遵循相同的命名和缩进模式"
• 工作流约束：如"不要本地执行Terraform apply，只做验证后推送到Git"

正是因为agents.md中定义了"GitLab生产环境运行在server-production-1上"，当用户说"检查我的远程服务器上容器是否运行"时，Pi能自动SSH到正确的服务器执行docker ps。

用Pi Agent实现Terraform基础设施自动化

这是一个令人印象深刻的实际用例：用Pi Agent通过Terraform管理GitLab仓库。

IaC工具链背景：Ansible和Terraform/OpenTofu是现代DevOps工具链的两大支柱。Ansible专注于配置管理和应用部署，采用声明式YAML剧本（Playbook）通过SSH推送变更，无需在目标机器安装代理；Terraform（及其开源分支OpenTofu）则专注于云基础设施的声明式供给，通过状态文件追踪资源生命周期。两者的共同点是"代码即文档"——基础设施的期望状态完全由版本控制的文本文件描述。这正是Pi Agent能发挥巨大价值的场景：AI可以阅读现有IaC文件，理解命名规范和模块结构，然后生成风格一致的新配置，而不是凭空创造可能与团队规范冲突的代码。

当输入"create a new test repo for my user"时，Pi Agent会：

1. 读取agents.md中的指令，理解需要使用IaC方式
2. 检查现有Terraform文件的结构和模式
3. 按照相同的命名规范创建新的Terraform文件
4. 执行验证（而非本地apply）
5. 将变更推送到Git仓库，由CI/CD完成实际部署

这里的工作流遵循了GitOps模式——将Git仓库作为基础设施配置的唯一可信来源，工程师不直接在服务器上执行变更，而是通过提交代码触发自动化流水线（如GitLab CI、GitHub Actions）来完成实际操作。这种方式带来了完整的变更审计追踪和可回滚性。Pi Agent在agents.md中配置"不要本地执行Terraform apply