ARTICLE · 1081267
10分钟上手Pi Agent:终端里的AI编程助手,安装配置一学就会!
10分钟上手Pi Agent:终端里的AI编程助手,安装配置一学就会! 厌倦了在不同AI编程工具之间切换？一款“小而美”的开源终端编程智能体Pi Agent正成为开发者新宠。它不绑定任何模型厂商，核心极简，却功能强大——用自然语言描述需求，它就能自己读文件、写代码、改Bug、跑命令，直到任务完成。 🤔 一、Pi Agent 是什么？为什么值得关注？ Pi Agent 是一个运行在你电脑终端里的开源AI编程智能体（Coding Agent）。与传统的“你问我答”式AI助手不同，它是一个“你给目标、它自己跑”的自动执行引擎。 核心特点一览： 特性 说明 终端原生 不依赖任何IDE，在终端中直接运行，适合SSH远程开发、Docker容器内使用 模型自由 支持15+模型提供商（Anthropic、OpenAI、Google、DeepSeek、Ollama等），随时切换 极简工具集 默认只给模型read、write、edit、bash四个基础工具，系统提示词不到1000 token，响应速度极快 零成本入门 工具本身免费，只需自带API Key或复用现有Claude/ChatGPT/Copilot订阅 高度可扩展 TypeScript扩展系统，社区生态丰富，可以给它添加几乎任何能力 你可以把它想象成一个 “住在终端里的AI程序员” ——你用自然语言描述需求，它读取代码、修改文件、运行命令，全程透明可审计。 📦 二、安装Pi Agent：两种方式任你选 方式一：一键安装脚本（推荐） 在终端中运行以下命令即可完成安装： curl -fsSL https://pi.dev/install.sh | sh 安装完成后，验证是否成功： pi --version 💡 系统要求： • 操作系统：macOS 12+、Ubuntu 22.04+、Windows 11（需WSL2） • Node.js：22.0 或更高版本 • 网络：需要访问所选AI模型的API 方式二：通过npm安装 如果你更喜欢使用npm，可以运行： npm install -g --ignore-scripts @earendil-works/pi-coding-agent 🔐 三、配置模型：云模型与本地模型全覆盖 安装完成后，你需要配置一个AI模型来让Pi Agent工作。Pi Agent支持两种主要方式：云模型订阅/API Key 和 本地模型。 1. 登录云模型订阅或配置API Key 首次启动Pi Agent时，它会引导你完成配置。最直接的方式是使用/login命令： pi # 进入交互界面后 /login 你可以选择： • OAuth订阅登录：如Claude Pro/Max、ChatGPT Plus/Pro（Codex）等，直接使用你的现有订阅 • API Key方式：支持Anthropic、OpenAI、DeepSeek、Gemini、OpenRouter等多家提供方 2. 选择默认模型 配置好提供商后，使用/model命令选择默认模型： /model 你可以从支持列表中选择，如claude-sonnet-4-20250514、gpt-4o、gemini-2.5-pro等。 3. 配置本地模型（以Ollama为例） 如果你想在本地运行开源模型（如Llama、Qwen等），可以配置Ollama。首先，在~/.pi/agent/models.json文件中添加以下配置： { "providers": { "ollama": { "baseUrl": "http://localhost:11434/v1", "api": "openai-completions", "apiKey": "ollama", "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false }, "models": [ { "id": "qwen2.5-coder:7b" }, { "id": "llama3.1:8b" } ] } } } ⚠️ 注意：对于Ollama等本地模型，apiKey是必需的，但Ollama会忽略它，所以填任何值都可以。 配置完成后，在Pi Agent中使用/model命令，你就能看到并选择这些本地模型了。 🛠️ 四、基本操作方法：与Pi Agent协作 配置完成后，就可以开始使用Pi Agent了。以下是核心操作方法： 1. 启动与工作目录 进入你想要Pi Agent工作的项目目录，然后启动它： cd /path/to/your/project pi 工作文件夹帮助Pi发现相关文件、指令和配置。它也使用该文件夹来分组保存的会话。 2. 给Pi Agent下达任务 在交互界面中，直接用自然语言描述你的需求。Pi Agent会显示它执行的每个文件读取、搜索、命令和编辑操作。 任务示例： Summarize @meeting-notes.md and save the action items to action-items.md. Explain how this repository is structured and how to run its checks. Compare @previous.csv with @current.csv and summarize the important changes. 在编辑器中输入@可以搜索文件。 3. 常用命令与操作 命令/操作 功能 示例 /model 选择或切换模型 /model /login 登录或配置模型提供商 /login @filename 引用文件 @src/index.js !command 执行Shell命令 !ls -la Ctrl+L 快速切换模型 /tree 查看树状会话历史，可跳回任意节点重新提问或分叉试错 /export 导出会话为HTML /reload 重新加载扩展（修改扩展后生效） 4. 理解Pi Agent的工作流程 Pi Agent遵循感知-规划-行动-验证的循环： flowchart LR A[感知<br>扫描项目目录] --> B[规划<br>拆解任务] B --> C[行动<br>调用工具执行] C --> D[验证<br>检查结果] D --> E{是否满足要求?} E -- 否 --> A E -- 是 --> F[任务完成] 1. 感知：扫描当前仓库，读取相关文件，理解项目结构 2. 规划：根据用户目标和代码内容，决定先看哪些文件、写什么代码 3. 行动：调用read、write、edit、bash等工具执行操作 4. 验证：运行测试、执行命令，检查结果 5. 迭代：如果验证失败，它会读报错、定位原因、调整方案，再进入下一轮 ⚙️ 五、高级配置：设置文件与扩展 1. 设置文件 Pi Agent的设置分为全局设置和项目设置，优先级是项目覆盖全局： • 全局设置：~/.pi/agent/settings.json • 项目设置：.pi/settings.json 一个最小配置示例： { "defaultProvider": "anthropic", "defaultModel": "claude-sonnet-4-20250514", "defaultThinkingLevel": "medium", "defaultProjectTrust": "ask" } 2. 扩展与插件 Pi Agent支持通过扩展添加自定义工具、命令和功能。扩展文件可以放在： • ~/.pi/agent/extensions/（全局） • .pi/extensions/（项目） 修改扩展后，使用/reload命令即可热重载生效，无需重启。 你还可以通过pi install命令安装社区提供的包，例如： pi install npm:pi-lm-providers 🎯 六、核心总结与快速上手指南 快速上手步骤 1. 安装：使用一键脚本curl -fsSL https://pi.dev/install.sh | sh或npm安装 2. 启动：进入项目目录，运行pi 3. 配置模型：使用/login登录云模型或配置本地模型（如Ollama） 4. 下达任务：用自然语言描述你的需求，让Pi Agent自主执行 最佳实践建议 • 从简单任务开始：先让Pi Agent处理一些明确的小任务，如“给这个函数添加注释”、“修复这个语法错误” • 提供清晰上下文：使用@引用相关文件，让Pi Agent更快理解任务背景 • 重要任务先备份：虽然Pi Agent透明可审计，但对重要文件操作前建议先备份 • 逐步信任：随着对Pi Agent能力的了解，可以逐渐赋予它更复杂的任务 常见问题（FAQ） Q1: Pi Agent是免费的吗？ A: Pi Agent本身是开源免费的（MIT协议），但你使用的AI模型可能需要API Key或订阅费用。 Q2: 我的数据会泄露吗？ A: Pi Agent完全本地运行，代码不会上传到任何云端。模型调用走你自己的Key/订阅，数据安全可控。 Q3: 支持Windows吗？ A: 支持，但需要WSL2环境。 Q4: 如何卸载Pi Agent？ A: 根据你的安装方式反向处理。如果用npm安装，运行npm uninstall -g @earendil-works/pi-coding-agent。 👍 觉得有用，点个“在看”，转发给身边的朋友！ 👇 你在安装或使用Pi Agent过程中遇到了什么问题？或者有什么使用心得？评论区聊聊~ 延伸阅读： • Pi Agent官方文档 • GitHub仓库 • 自定义模型配置指南