最近翻开发者群聊Pi Agent 相关的讨论明显从“这是什么”变成了“你们的工作流怎么配”这其实是个好信号说明已经有不少人用起来了。但反过来我也看到不少人卡在最前面的安装环节问的问题基本都是版本、依赖、连不上模型这几类。这个系列的第一篇聊了它的整体思路这篇就接着往下走把“五分钟装好并用起来”这件事讲透。先说这篇的适用对象你想找一个能直接参与项目开发的 AI 编程助手愿意在终端里操作又不想折腾太复杂的环境那这篇正合适。不用懂太多底层原理跟着操作就行但我也会把关键步骤背后的逻辑讲清楚免得你装好了不知道怎么用。我的目标是让你看完之后从零开始跑通第一个对话再让它帮你实际改一个小代码问题全程控制在半小时以内。1. 动手安装前先把这三件事想明白1.1 Pi Agent 解决的是“人肉搬运代码”的问题Pi Agent 这类工具本质上是一个coding agent不只是聊天窗口。它的核心能力是“进到你的项目里干活”能看目录结构、读文件、搜索关键词、执行命令、改代码然后把改动以 diff 的方式呈现给你审查。你可以把它理解成一个“带工具访问权限的对话式机器人”而不是一个只能生成代码片段给你复制的网页窗口。所以它解决的痛点很直接以前你要把 AI 给的代码复制进编辑器再手动定位项目位置、手动跑测试、手动查报错所有衔接工作都是人肉完成的。用了 Pi Agent 之后这些环节大部分被压缩了。你只需在终端里描述目标它自己会去项目里找相关文件、分析现状、动手修改全程每一步都摊开给你看。这种“看着它干活”的体验和传统“复制粘贴代码”是两码事。这个系列的第一篇已经聊了 Pi Agent 的整体设计这一篇就不重复原理了直接进入安装实战。不过有两件事我得提前打预防针第一它本身不提供“大脑”你需要准备一个大模型接口第二五分钟指的是装好并跑通一个基础对话不是五分钟调出一个完美工作流后者需要你用几次之后慢慢磨合。1.2 模型从哪来决定了你能不能跑起来装之前先想清楚一个问题Pi Agent 的推理能力从哪来它自己不带模型推理你需要给它配置一个模型来源常见就两种方案。方案 A接在线大模型 API。你注册一个服务商的 API 密钥把接口地址填进配置Pi Agent 就通过这个接口完成推理。好处是效果通常最好响应也快不需要消耗本地计算资源坏处是每一步推理都会产生费用而且隐私数据会发送到第三方服务。方案 B接本地模型。用 Ollama 这类工具在本地起一个模型服务Pi Agent 直接连 127.0.0.1 上的接口。好处是数据不出机器、免费、可离线用坏处是速度和效果取决于你的硬件配置尤其是内存和显卡小模型跑复杂逻辑时会明显“不够聪明”。我自己推荐的判断标准是这样如果你只是想尝鲜和测试流程先接一个本地中等规模模型成本最低如果你准备在日常开发里正经用直接选一个效果更好的在线 API省心。两者可以在配置里随时切换不用太纠结。对比维度在线 API本地模型接入成本注册、拿密钥、可能涉及付费装 Ollama 并在本地拉取模型响应速度快依赖网络状况看显卡和内存波动大代码理解效果通常更好小模型容易出错数据隐私数据会交给第三方服务不出本机隐私可控离线可用不行可以断网也能跑费用按 token 计费基本只花电费1.3 三分钟环境预检装到一半再返工就晚了很多人安装失败不是因为工具本身难装而是环境前设没确认。我建议动手之前先花三分钟在终端里做一次快速预检Python 版本推荐 3.10 及以上低于 3.9 的话依赖很容易冲突建议先升级或装一个版本管理工具。包管理器如果你之前直接用系统自带的 pip建议这次改用uv原因下面会专门说。命令行基础工具确认有 git如果没有有的功能会受限。网络连接能正常访问公共软件仓库就行。在终端里依次敲这三条命令基本就能排查完python3 --version git --version curl --version只要三条命令都有返回没有报“command not found”环境就过关了。如果 Python 版本偏低也别急着练手先把它处理掉。不少人在这一步偷懒最后依赖装到一半发现各种不兼容那是真的难受。2. 五分钟安装实操从零到能对话2.1 用 uv 而不是裸 pip是我踩坑后的选择第一次装 Pi Agent 的时候我直接用了系统里的 pip结果因为年份久远的 Python 环境和一堆历史依赖装到一半就开始报错最后花了半个多小时清理现场。后来换了uv整个过程干净利落所以你现在让我推荐我会毫不犹豫让你用 uv。uv 是一个用 Rust 写的 Python 包管理工具对开发者友好的点在于一是安装非常快依赖解析和下载比传统 pip 快一个量级二是它默认做环境隔离不会把包装进系统 Python 里也就不会污染你机器上其他项目。你可能会觉得“多学一个工具成本很高”但实际上它就是把很多操作简化了后面你装别的 Python 工具也会用到。如果你机器上还没有 uv一条命令就能装好但不同系统命令不一样我建议直接去它的官方 GitHub 仓库看 README那里永远是最新的。装好之后你会看到一个uv命令后面所有操作都围绕它展开。2.2 安装命令与启动配置这里我以当时装的 0.6.x 版本为例命令行和参数在后续版本可能微调但整体逻辑是一样的最终以官方 README 为准。安装只需要一条命令uv tool install pi-agentuv tool install的意思是把这个 CLI 工具作为一个独立的应用装在隔离环境里之后系统里会多出一个pi-agent命令。装完先验证一下pi-agent --version能输出版本号说明安装成功了。这个过程正常也就一两分钟如果网络状况不太好会慢一些但可以换镜像源来解决我在后面的常见问题环节里专门写。接下来是初始化配置。运行pi-agent init它会以交互式问答的方式引导你完成配置主要问三件事选模型后端我们前面说过可以是某个在线 API也可以是本地 Ollama 服务。填模型名称和接口地址如果走在线 API还要把密钥准备好。问你是否允许自动执行命令这个我建议首次都选“先询问”熟悉之后再放开权限。这些配置会写进用户目录下的一个配置文件中后续随时可以改。填完这些初始化就结束了整个流程不长关键是把模型接口的地址和密钥填准确。2.3 第一个对话测试验证它真的“通”了安装配置都完成之后进到一个空目录或者一个简单的测试项目输入pi-agent看到提示符出现后给它一个非常轻量的任务比如请告诉我当前目录的结构并简单介绍每个文件和文件夹的作用。如果它能正确读取目录、输出项目结构说明那恭喜你五分钟的目标已经达成了说明模型接口、目录权限、基础会话链路全部打通。这一步最关键的不是让它在复杂问题上表现多好而是确认整条链路是通的。链路一通后面所有配置都只是加分项。3. 第一次实战让 Agent 修一段真实代码3.1 准备一个能快速验证的小项目装好之后别急着让它干大活先拿一个小规模项目练手。我建议你用自己平时写的任意一个小脚本或者干脆新建一个项目来测试。这里拿一个极简的示例来说demo/ ├── main.py └── calculator.pycalculator.py里有一个计算函数但缺了除零校验main.py调用它并把结果打印出来。我们让 Pi Agent 去给calculator.py加上异常处理。这个任务足够典型有明确的文件位置、有具体的改动目标、还能验证它的代码修改能力。3.2 给 coding agent 下任务的话术跟给人下任务不一样我发现很多初学者把 Pi Agent 当成网页版聊天框来用直接一句“帮我加个异常处理”就发过去了。结果它改了半天改的不是你要的地方然后就开始互相拉扯。这不能全怪它问题出在任务描述太模糊哪个文件哪个函数什么异常希望的输出形态是什么如果你想让 Agent 第一次就干对我给你一个可以套用的 prompt 结构明确指定文件路径和函数名说清楚改动目标给出具体的约束条件和验收标准要求它先输出计划再动手改这是我实际用下来比较顺手的写法请修改 src/calculator.py 里的 divide 函数 - 当除数为 0 时抛出 ValueError错误信息为“除数不能为 0” - 不改动其他函数不改变对外接口 - 先给我一份改动计划确认之后再做最后输出 diff这个 prompt 里包含的四个要素各有用处指定文件名是为了缩小搜索范围写清目标是为了让改动方向不跑偏约束条件是为了防止它“顺手重构”你的代码要求先给计划则给了你一个叫停机会。这套话术同样适用你之后所有 coding agent 场景基本可以复用。3.3 从它的工作流里学配置思路当你把任务发给 Pi Agent 之后留意它整个执行过程通常会分这么几个阶段第一步它先读取目标文件和相关依赖文件搞清楚现状期间会打印它读了哪些文件。第二步它会给出改动计划有时候还会临时把计划写成一个文档。第三步执行改动并且展示出 diff。你确认之后它才会应用改动、跑测试验证结果。我在第一次用的时候最大的感受是“原来它每一次动代码之前都会在心里先过一遍计划”。这个特性非常有价值因为你可以随时打断它在它还没动手之前纠正方向。很多 coding agent 用不好其实不是因为工具笨而是用户自己没用好这个“先计划后执行”阶段直接跳到最后让人家自己搞出一个东西来。从这里引申出一个配置思路你可以把“先计划后执行”设成默认策略这能有效防止它在复杂任务里乱改代码。具体怎么配置我在下一节里会展开讲。4. 把配置固化下来形成自己的 coding workflow4.1 权限边界让它大胆干但不是什么都敢干我第一次用的时候什么权限都不敢给每次让它执行命令都在那弹确认效率低到崩溃。后来学聪明了把安全命令放开把危险命令留着询问。具体来说你可以按命令类型设置不同级别允许执行但不修改状态的git status、find、ls、cat这些不会造成破坏建议全放开。允许执行但有副作用的跑测试、格式化代码、安装依赖、git commit这些视情况决定建议先询问。一律必须询问的删除文件、强制推送、改 git 配置、直接改权限这些必须保留人工确认步骤。这块如果配得好你就能做到“让它大胆干活但危险动作必须经过你点头”。这也是 coding workflow 里比较核心的一块很多人前期忽略它后面容易出事故。4.2 项目级配置文件让 Agent 一眼看懂项目背景除了全局配置Pi Agent 还支持在项目根目录下放一个配置文件比如pi-agent.yaml。这个文件的作用相当于“项目入职培训手册”Agent 每次进入这个目录都会先读到里面的项目背景、编码规范、禁用操作等信息。以下是我一个项目里实际用的简化模板你可以复制改改# pi-agent.yaml project: name: demo-checkout description: 一个用于电商订单校验的 Python 项目 language: python rules: - 所有函数必须带类型注解 - 禁止修改 migrations 目录下的文件 - 测试代码统一用 pytest不引入 unittest permissions: read_files: allow edit_files: ask run_commands: allow: - git status - pytest - python -m * ask: - *这个配置的价值在于它把“项目背景”从你嘴里转移到文件里省去了每次对话都要重新解释一遍的麻烦。团队里如果有新人加入只要你共享这个文件大家跑出来的 Agent 行为就很接近这比口头培训要靠谱得多。4.3 把工作流沉淀成团队模板用过几次之后你会发现这些配置其实是可以沉淀成一套团队级的模板的。我现在的做法是把pi-agent.yaml连同基础提示词模板一起放进项目仓库的.pi-agent/目录并通过.gitignore把密钥文件过滤掉。这样新成员 clone 项目后只要运行一次初始化命令填自己的密钥就能立刻获得和你接近的 Agent 行为。这个做法看起来很简单实际收益很大。它相当于把“AI 助手使用规范”做成了能跟着项目走的文档比在 Wiki 写一篇文章更实用。因为配置文件是活的它会随着项目变化不断演进而 Wiki 很容易忘记维护。5. 常见问题与排查技巧实录5.1 装到一半报错十有八九是环境问题很多人卡在安装这一步报错信息五花八门但根因就那么几种。我这里整理成一张速查表方便你对照。症状常见原因解决方案安装时提示 Python 版本过低系统默认 Python 是 2.x 或 3.8 以下安装 Python 3.10或用 uv 自带 Python 管理依赖冲突一长串报错当前环境装了太多全局包改用 uv tool install隔离干净环境下载速度很慢或直接超时网络路径不佳把包管理器的源改为镜像源速度能明显改善命令装好但pi-agent找不到PATH 没配好确认安装输出信息的目录并把它加进 PATH关于国内网络环境我多说一句安装时如果感觉很卡不要硬等直接把源切成镜像源。pip 和 uv 都支持指定索引源改成镜像地址之后速度差距非常大这是很多人装完 Pip 类工具之后驾驭的第一道门槛。这不是什么复杂操作只是很多人不知道可以这么做。5.2 模型响应慢、超时不一定是网络问题在使用过程中最让人恼火的是对话到一半就卡住不回了。大家第一反应肯定是网络问题但其实还有几个常见原因。第一接口地址或模型名填得不对。有时候你填的在线模型 ID 已下线或者自定义的接口路径拼错了表现就是请求一直挂着。这种情况你把配置里的 base_url 和 model 字段拉出来对一遍基本能解决。第二模型上下文过长。如果项目比较大Agent 读了一堆文件进上下文单次请求的 token 数会非常惊人在线 API 响应变慢或者直接超时。解决方案是给请求设置一个合理的 max_tokens 上限同时提醒自己在任务描述里明确范围别让它漫无目的地读整个项目。第三本地模型显存不够。如果你选的是本地模型跑大一点的项目时很容易内存溢出或响应极慢。建议先用小模型验证流程确认真有必要再上更大的模型。5.3 Agent 乱改代码问题多半出在任务描述“我就让它加个日志它把我整个文件格式化了一遍”这种抱怨我见得太多了。说实话这锅主要不在 Agent而在任务描述没说清楚约束条件。你没告诉它“只改指定函数、不动其他区域”它就很可能根据自己的理解发挥。解决办法也不复杂在 prompt 里像我们前面说的那样写清楚边界尤其在多文件项目里一定要点名要动的文件。如果你发现它总是忽略你的约束检查一下项目配置文件里的规则是否有冲突比如你写的是“允许自动修改文件”但任务里又没有说明白范围那它大展拳脚也正常。5.4 密钥管理别忽视Pi Agent 的配置里会存放你的 API 密钥这个文件默认就在用户主目录或项目目录底下。有几个安全习惯我建议一上来就养成千万不要把带密钥的配置文件提交进 git 仓库哪怕私有仓库也要小心。密钥通过环境变量引用而不是直接硬编码到配置文件里这样万一文件泄漏密钥不会被带走。如果发现密钥疑似泄漏第一时间去后台吊销并重新生成而不是自欺欺人。密钥这块看着不起眼但一旦出了问题是最麻烦的我在文章里重复提醒很多次也值得。最后再补一个我实际使用的习惯每次装完 Pi Agent我都会把初始化好的项目配置模板存到一个专门的目录里以后开新项目直接复制过去改几行就能用。不用每次从零开始配置这省了很多重复劳动。希望你也能在下一个项目里把这条流程跑通然后用顺手了再回头来调工作流效率会比一上来就追求复杂配置高得多。