企业官网建设流程全解析

先说明一点：后面要聊的 pi agent，全称是 pi coding agent，一个跑在终端里的开源 AI 编码代理。它干的事和 Claude Code、Goose、OpenHands 这类工具类似：读懂你的项目、调用命令行工具、改代码、跑测试、提交 commit，把“写代码”从“聊天生成片段”升级成“让 AI 负责一个完整任务”。

我把这个项目的落地过程，尤其是“国内环境从零到能干活”这段经历叫作毛坯房装修。为什么这么说？因为下载一个二进制只是毛坯，真正让 pi agent 跑起来，要铺的管线多着呢：Rust 工具链、cargo 源、模型 API 配置、MCP 扩展、工作目录权限……每一层都是水泥和电线，漏掉一根后面就得返工。这篇文章就把我装修过程中踩的坑、填的土、以及最后住进去的真实使用体验，全部分享出来，给也想把这套编码工作流跑起来的你省点时间。

1. 为什么要选 pi agent：一个“轻到可以塞进口袋”的编码代理

1.1 从 Claude Code 到 pi agent，我为什么换赛道

先说背景。我之前的日常是 VS Code + GitHub Copilot，偶尔用 Cursor 处理一些重构任务。Copilot 适合“补全下一行”，但对“帮我查一下为什么 pytest 挂了然后修掉”这种完整任务，它的表现基本是嘴强王者——给出建议，不会亲自干活。所以我开始转向“编码代理类”工具，也就是 agent 型的 AI 编程助手：它不只给你建议，还会真的执行命令、读取文件、修改代码。

Claude Code 很厉害，但它有几个问题让我一直没真正纳入日常工作流：第一，它对 Anthropic 官方 API 的依赖很重，国内调用要处理网络和计费；第二，它的配置和权限体系是围绕 Anthropic 生态设计的，我想要接入 DeepSeek、通义这类国产模型时，总觉得隔了一层。后来我翻 GitHub 时看到 savarin 的 pi-coding-agent，一下子被吸引住了。这项目最初是树莓派上跑出来的轻量编码代理，Rust 写的，支持 OpenAI 兼容 API，天然适合我这种“模型用国产、环境在国内、依赖越少越好”的人。

1.2 pi agent 到底解决了什么问题

pi agent 解决的问题非常精准：它把“用户坐在终端前手动敲命令、复制输出、再粘贴给 AI”的循环，压缩成“用户给一句任务描述，AI 自己用终端把活干了”。比如我以前定位一个 flaky 测试，流程是：跑 pytest —— 看失败的 case —— 打开对应测试文件 —— 翻实现代码 —— 猜原因 —— 加日志 —— 再跑。现在用 pi agent，我只要说“pytest 有 flaky 测试，先跑三遍找出失败规律，然后定位最可疑的时序问题，修复并补上回归测试”。

这背后是 agent 自己做上下文管理。它会先用ls、grep、rg这类 shell 命令探索目录结构，再读取相关文件，把内容塞进自己的上下文窗口，然后决定下一步执行什么命令。这种“shell-first”的设计，比那些只靠静态文件分析和 RAG 的工具要直接得多，因为它能看到测试运行的真实输出，而不是靠猜。

所以我的结论是：如果你想要一个能“真干活”的编码代理，且在意模型多样性、隐私和可控性，pi agent 是一个值得研究的起点。尤其适合那些已经会用终端、但不想被某个厂商生态绑死的开发者。

2. 毛坯房第一步：装环境前必须先看清的硬性条件

2.1 先检查你的“水电”：Rust、Git、网络源

我一开始犯的最大错误，就是拿到 GitHub 仓库地址就开始跑安装脚本，结果连 Rust 都没有，编译到一半直接报cargo: command not found。这就像毛坯房还没通水电，你已经开始贴瓷砖了。

装 pi agent 前，至少需要确认这几样东西：

• Rust 工具链（rustc + cargo，版本 1.74 以上）
• Git，并且能拉 GitHub 仓库
• 基础的构建工具链，Linux 上是build-essential，macOS 上通常是 Xcode Command Line Tools
• 一个 OpenAI 兼容的模型 API Key（DeepSeek、通义千问、Kimi、本地 Ollama 都行）

安装 Rust 本身也有一堆坑。如果你在官网看到curl https://sh.rustup.rs | sh，千万别直接用默认源跑，在国内这个速度会让你怀疑人生。我实测有效的做法是先配置环境变量指向国内镜像，再跑脚本：

export RUSTUP_DIST_SERVER=https://rsproxy.cn export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

跑完之后别忘了source "$HOME/.cargo/env"，否则当前 shell 里还是找不到 cargo。装完可以用rustc --version验证，能输出版本号才算水电供上了。

2.2 换 cargo 源：不等 20 分钟编译的基础操作

装好 Rust 之后，下一个坑就是 cargo 的依赖下载。pi agent 本体是 Rust 项目，依赖的 crate 数量相当多，如果你直接用官方 crates.io 源，下载速度可能就是几 KB/s，编译一个项目在那边转圈 20 分钟起步。

我的经验是用字节跳动的 rsproxy 镜像，或者中科大的镜像。配置文件放在~/.cargo/config.toml：

[source.crates-io] replace-with = 'rsproxy' [source.rsproxy] registry = "https://rsproxy.cn/crates.io-index" [registries.rsproxy] index = "https://rsproxy.cn/crates.io-index" [net] git-fetch-with-cli = true

配好之后编译速度会有质的提升，基本上几分钟内能把所有依赖拉完。注意这个文件不要放到项目目录里，放~/.cargo/config.toml是全局生效的，以后编译任何 Rust 项目都受益。

小提示：如果你拉 GitHub 仓库本身很慢，我见过有人直接硬等，有人用加速镜像。我的建议是尽量用 GitHub Releases 里的预编译包，能省掉本地编译这一步；没有预编译包再走源码编译路线。

3. 装修中段：安装 pi agent 的三种姿势与桌面端迷思

3.1 姿势一：官方脚本安装，最省事但也有坑

pi agent 的 README 里提供了安装脚本，我用的时候发现它做的事情比较粗暴：检测系统架构、下载对应 release 的二进制、放到用户目录下的 bin 文件夹里。这个方案的好处是快，缺点是你不知道它装到哪了，后面想升级或者卸载会有点稀里糊涂。

我用官方脚本时遇到的一个典型坑是：脚本默认写到~/.local/bin，但这个目录不一定在你的$PATH里，装完执行pi会提示command not found。解决办法是把export PATH="$HOME/.local/bin:$PATH"加进~/.bashrc或~/.zshrc，然后source一下。这一步踩完，基础才算通。

3.2 姿势二：源码编译，能看到更多细节但耗时

如果你跟我一样想看看这个项目内部怎么写的，或者想要最新主干的特性，源码编译是更可控的。步骤：

git clone https://github.com/savarin/pi-coding-agent.git cd pi-coding-agent cargo build --release ln -s "$(pwd)/target/release/pi" ~/.local/bin/pi

这里有一个编译性能的坑：release 编译很吃内存，我的机器 16G 内存跑起来风扇狂转。如果机器内存小于 8G，建议先cargo build（debug 模式）跑通功能，等真要长期用了再花时间编 release。另外源码编译时遇到编译错误不要慌，先检查 rustc 版本，很多莫名其妙的报错其实是不满足最低版本要求。

3.3 姿势三：用 cargo install 安装

如果你已经配好 rsproxy 源，也可以直接：

cargo install --git https://github.com/savarin/pi-coding-agent.git

它会自动把二进制放到~/.cargo/bin，这个目录一般已经在 PATH 里了。我实际用下来，这个方式最干净，卸载也简单（直接删二进制）。唯一要注意的是，Git 拉不下来时先解决镜像问题，不然会卡在 clone 阶段。

3.4 桌面端的迷思：其实你多半不需要它

热搜词里好多人搜“pi agent 桌面端”，我猜测是大家习惯了有图形界面的工具。但 pi agent 核心是一个 CLI 程序，设计哲学就是让你留在终端里干活。你真正需要的是三个东西：一个趁手的终端模拟器（我用的是 iTerm2，Windows 上建议用 Windows Terminal），一个大一点的分屏窗口（左边写代码右边跑 agent），以及一个能支持长文本输出的查看器。

如果你非要一个“看得见的界面”，方案是：在 VS Code 里开一个内置终端跑pi，然后利用 VS Code 的 diff 视图查看它改动的文件。这个体验非常接近图形化工具，但背后的核心还是 CLI。我不建议强行找“桌面客户端”，因为 pi agent 的输入输出都是文本流，套一层 UI 反而会让你失去对命令执行细节的掌控。

4. 最关键的水电改造：模型接入与配置文件

4.1 配置文件放哪、写什么

装完二进制只是毛坯墙体砌好，接下来是水电改造——让 pi agent 知道你用哪个模型、哪个 API 密钥。pi agent 默认会把配置放在用户目录下的一个隐藏文件夹里，我当时在~/.pi/config.yaml里写的，你可以根据自己的版本看 README 确认路径，但核心字段是一致的：

# pi agent 配置文件 model: "deepseek-chat" provider: "deepseek" api_key_env_var: "DEEPSEEK_API_KEY"

我的经验是：不要把 API Key 直接写进配置文件，用环境变量引用。原因很简单，你的配置文件可能会被放进 dotfiles 仓库同步到 GitHub，一旦泄露就是钱包灾难。我使用 DeepSeek 作为主力模型，因为它的价格和编码能力平衡得不错；如果你想换通义千问，那 provider 和模型名要做相应调整。

配置好之后，设置环境变量：

export DEEPSEEK_API_KEY="sk-你的密钥"

然后跑pi "你好，帮我看看当前目录下的项目结构"，如果它正确列出了文件结构，说明模型通路已经打通，水电都来了。

4.2 OpenAI 兼容 API 填坑指南

pi agent 之所以在国内好用，核心是它对“OpenAI 兼容 API”的支持。DeepSeek、通义、Kimi、甚至本地起的 Ollama，都提供 OpenAI 兼容的接口，这意味着 pi agent 不需要为每个模型厂商定制适配层。

但我踩过一个坑：某些厂商的 API，模型名和文档不一致。比如通义千问在官网显示的是qwen-plus，但 OpenAI 兼容端点里可能需要写成qwen-max或者带了版本后缀的模型名。如果你发现 agent 一直报 404 或者 model not found，先别怀疑 pi agent，去你模型厂商的 OpenAI 兼容文档里把准确的模型 ID 复制过来。

还有一点，上下文长度设置。pi agent 的提示词模板、工具定义会占掉一部分 token，如果你模型本身的上下文只有 32K，它能把文件和命令输出塞进上下文的空间其实不大。我在用某些本地模型时经常出现它“忘记”了前面读过的文件内容，换一个更大上下文的模型后问题立刻缓解。这个在配置里通常会有一个context_length或者直接在模型定义里给出的参数，建议设成模型真实上限的 80%，留点余量给输出。

5. 硬装落地：实操中我如何用它干活，以及三个必踩的坑

5.1 实际工作流演示：两分钟让 agent 修掉一个测试失败

用一个真实场景告诉你 pi agent 是怎么干活的。我有一个 Python 项目，其中一个测试最近开始随机失败，日志里没有明显错误。以前我手动修大概要 20 分钟到半小时，这次我把任务丢给 pi：

pi "跑三遍 pytest tests/test_worker.py 找出失败规律，分析一下失败原因，修复后提交 commit，并写清楚根因"

它会做这些事情：

1. 先执行pytest tests/test_worker.py三次，把输出拿回来分析；
2. 发现失败都与一个共享的queue对象有关，然后打开worker.py定位到 queue 的使用处；
3. 发现是queue.Empty异常没处理好，多线程竞争时会出现get_nowait()拿到空；
4. 修改代码、重跑测试、确认稳定通过、然后git add+git commit。

整个过程它会一条条执行命令，并且在执行前展示命令和预期后果，等你确认。我第一次用的时候还担心它会“自由发挥”改坏代码，但实际操作下来它每一步都会说清楚自己在干嘛，比如“我将修改第 45 行，把超时异常捕获加上”。这种透明感是用 agent 工具最重要的心理保障。

5.2 工作流中必踩的坑一：默认交互模式太碎

pi agent 默认是交互式审批模式，每一轮工具调用前都会问你Allow this? (y/n)。这种模式适合第一次试水，但如果你让它跑一个 10 步任务，你得按 10 次 y，体验有点像装修工人每钉一颗钉子都问你“要不要钉”。在可信项目里，我建议用自动审批模式跑分块任务：

pi --dangerously-bypass-approvals "执行整个重构流程，每一步完成后告诉我结果"

但注意这个 flag 的名字里带着 “dangerously”，它确实危险。我的折中方案是：只在 git 工作区干净、代码已经提交过的项目里用自动审批，并且全程盯着输出，一旦发现它要执行rm -rf、git push --force这类高危命令，立刻 Ctrl+C 中断。

这条真的重要：我在一台容器环境里测试时，让它帮我清理依赖缓存，结果它给我执行了整个项目的目录清理。幸好当时是在测试目录里，损失不大。从此之后我养成了习惯：永远不要在未提交代码的项目里放开自动审批权限。

5.3 工作流中必踩的坑二：上下文被撑爆

pi agent 读取文件、收集命令输出，目的是构建上下文。但如果你项目里有一个巨大的package-lock.json或者dist目录，agent 会傻乎乎地去读，结果上下文一下就被撑满，然后它开始“失忆”：一会儿说要改main.py，一会儿又去动utils.py，逻辑混乱。

解决办法是给 pi agent 设好忽略规则，让它不要碰不该碰的目录：

# .pi_ignore 文件 node_modules/ dist/ *.lock *.min.js __pycache__/

这个文件类似.gitignore，但只对 agent 的读取和探索行为生效。我加上之后，它探索项目的效率提升非常明显，不再动不动就去翻node_modules里几千个文件。

5.4 工作流中必踩的坑三：它不会自动保存你的工作习惯

pi agent 用完一次之后，下次是“失忆”的，不知道你 commit 风格是 conventional commit，也不知道你项目里测试命令是make test而不是pytest。如果你希望它每次都按你的习惯来，要在系统提示词或者每次任务描述里说清楚。

我在项目根目录放了一个AGENTS.md，里面写清楚：

• 测试命令是什么
• 代码风格要求
• commit 规范
• 哪些目录不要动

然后在第一次启动 pi agent 时，让它把AGENTS.md加载成项目的长期记忆。这个文件实际上比人还靠得住，即使隔了一个月重新回来做新需求，它也能立刻进入状态。

6. 验收测试：用一张速查表复盘我碰到的所有问题

6.1 常见问题与定位思路

装修到最后总要验收。我用一张表把这段时间遇到的问题整理出来，你遇到类似情况可以直接对照：

这个表不完整，但它覆盖了我在毛坯房装修阶段九成以上的问题。真正的秘诀不是记住所有可能性，而是会看日志：pi agent 的执行日志会详细打印每个请求的响应状态，报错了先翻日志，比瞎猜高效得多。

6.2 我最想提前知道的三条经验

如果让我对着刚下载好 pi agent 的自己说几句话，我会说：

第一，先读 README 再动手，官网和 GitHub 页面上的快速开始部分已经帮你扫平了九成的雷。我一开始图快跳过 README，结果在权限配置上多花了两个小时。

第二，第一次跑通“hello world”式任务之后，不要急着做复杂重构。先从“让它帮你跑测试、找出覆盖率最低的文件”这种只读任务开始，摸清楚它的执行习惯，再逐步放开修改权限。

第三，用一个专门的测试项目做实验，不要直接在公司的正式仓库里练手。这个工具的边界在于“它真的会动你的代码”，所以请在试验场里先建立信任。

7. 收尾的真心话：毛坯房住进来之后

整个 pi agent 的安装配置过程，就像一场毛坯房装修：一开始连水电都没有，装完 Rust 还要铺电线（cargo 源）、接水管（模型 API）、刷墙（项目忽略规则），最后装好家具（MCP 扩展）。过程里会有不少烦躁时刻，比如编译超时、模型 404、agent 在错误目录里打转，但一旦全部打通，它就变成一个平时很低调、出手很快的帮手。

我个人现在最舒服的工作流是：代码写到一个阶段性节点，丢给 pi agent 做一轮“自查 + 补测试 + commit”；遇到完全陌生的报错信息，直接粘贴给它分析，比开浏览器搜博客高效得多。它不完美，偶尔也会给你一个“看起来对但运行起来错”的改动，但只要你保留代码审查的习惯，它的价值就很明确——把大量重复的探索型工作从几十次手动操作压缩成几句对话。

最后再分享一个小技巧：不要只把它当“写代码工具”，试着让它做终端里的“运维专员”。我最近让它每天帮我在固定目录里整理日志、归档过期缓存、生成日报摘要，跑得非常稳。这些不一定算什么高阶玩法，但会逼你把项目目录、日志格式、命令输入都规范化。装修一次，后面长期受益，这就是我这次 pi agent 踩坑之旅最大的收获。