企业官网建设流程全解析

最近一周我把主力开发机上的 AI 编程工具全部换了一遍，最后停在了 oh-my-pi 这个开源项目上。先说清楚，这个 pi 既不是圆周率，也不是树莓派，而是一个能自己动手写代码、跑命令、改 Bug 的 AI 编程智能体，提供命令行和桌面端两套入口。我用它的第一天，就让这个 pi agent 完成了三件以前需要我手动折腾的小事：给老项目补测试、批量重构 utils 文件、把散落在仓库里的硬编码配置提取成环境变量。整个过程基本不用我把代码来回粘贴，它自己会读仓库、写文件、执行命令并把结果反馈出来——这种体验和传统聊天式编程助手完全是两个物种。

这篇文章我想把自己的实际使用过程完整记录下来，包括为什么选它、怎么安装配置、skills 机制怎么用、以及实战中如何让 agent 从一个空需求跑完整个开发循环。适合谁看？如果你日常要被代码格式化、重构、补测试、查日志这类重复劳动缠住，或者你想把 AI 从“只会聊天”升级成“能动手办事”，这篇文章的实操部分可以直接抄作业。下面所有内容都基于我自己的安装和使用记录，部分细节是通用实践，不同版本可能有差异，但核心思路不变。

1. 先搞清楚：pi 这个“AI 编程智能体”到底解决了什么问题

1.1 从“聊天助手”到“会动手的智能体”

大多数人用的 AI 编程工具还停留在“对话补全”阶段：你把代码粘进去，它给你一段建议，你再自己粘回去、自己跑测试、自己修报错。这个过程其实是断的——模型看到的上下文只有你手动贴进去的那一小段，既看不到仓库全貌，也无法主动验证它给的建议能不能跑通。

oh-my-pi 这类编程智能体最大的不同，是把“感知-决策-执行-验证”四个环节串成了一个闭环。我在实际使用中观察到的执行链路大概是这样：

• 感知：agent 会把当前项目目录的文件结构、关键源文件、依赖清单读入上下文，而不是等你手动粘贴；
• 决策：根据你给的任务目标，它自己规划先改哪个文件、后改哪个文件，需要执行什么命令；
• 执行：直接调用终端工具来改文件、运行命令、安装依赖、跑测试；
• 验证：看到命令报错后，它会自动读报错信息、定位问题、修改代码再重试，直到任务完成或明确向你求助。

以前我一提到“把代码交给 AI 自动改”就担心它乱来，实际用下来发现，只要给它圈定好项目范围、配置好命令白名单，它的自主空间其实完全可控。这就像你从“请了一个只出主意不动手的军师”，变成了“请了一个能把事落地并汇报的项目经理”。前者给的是建议，后者给的是结果。

1.2 为什么我最后选中了 oh-my-pi

市面上能做这件事的工具并不少，Cursor 里有 agent 模式，Claude Code 也能跑终端，Devin 这类产品更是在云端全自动干活。我最后在主开发机上留下 oh-my-pi，主要原因有四条：

• 开源可审计：核心代码在本地能看，不会把我的仓库内容传到一个完全黑盒的云端服务；
• 模型无关：它兼容 OpenAI 格式的接口，既能接云端大模型，也能接本地跑的模型，我甚至可以随时换模型厂商而不是被某个产品绑定；
• 桌面端和终端都有：在 IDE 里也能用，在纯命令行环境也能用，远程开发时不需要开一整套 IDE；
• skills 机制：这是我最喜欢的设计。可以把常用的操作步骤封装成“技能”，后续只要让 agent 调用技能，它就能按固定的高质量流程执行，不用每次重新描述需求。

当然它也不是没有缺点。在我用下来的版本里，它对超大仓库的上下文控制还不够聪明，偶尔会把不相关的文件也读进来，导致任务执行到一半上下文被塞满。这类问题我在第 5 部分会给出排查思路。

2. 环境准备与安装：把 pi agent 跑起来没那么玄

2.1 安装前先检查这三样东西

我建议在安装前先确认环境，避免后面踩坑。

• 操作系统：Windows 10/11、macOS 12+、主流 Linux 发行版基本都支持。我主力机是 macOS，副机是 Linux，Windows 上我也试过，原生支持没问题；
• 包管理器：如果你用命令行版本，Node.js 环境是必须的，推荐 Node 18 以上。桌面版安装包不需要手动装 Node，但我还是建议准备一个，因为很多 agent 子命令依赖系统终端环境；
• 模型 API：这个最关键。pi agent 本身不生产模型，它需要一个大模型来负责理解和规划。最常见的是准备一个 OpenAI 兼容接口的 API Key，本地模型（比如 Ollama）也可以，但是复杂代码推理任务建议用能力更强的模型，否则 agent 会显得很“笨”。

如果这三样都准备好了，安装过程基本顺畅。我第一次装的时候因为没看系统里 Python 版本，导致扩展技能跑不起来，后来发现是个别 skill 脚本依赖 Python 3.10+，和 oh-my-pi 本身关系不大。

2.2 三种安装方式，按场景选一个

oh-my-pi 提供了三种安装路径，分别适配不同使用场景，我逐一说明。

第一种是终端全局安装，适合习惯命令行工作流、日常在 SSH 或远程服务器上写代码的人。安装命令和执行入口长这样：

npm install -g oh-my-pi pi --version

如果网络条件一般，或者公司内网需要走私有 npm 源，可以换成：

npm config set registry https://registry.npmmirror.com npm install -g oh-my-pi

第二种是桌面端安装。桌面端是图形界面，适合想实时观察 agent 每一步做了什么的人。到 oh-my-pi 官网或 GitHub Releases 页面下载对应系统的安装包即可，macOS 下载 dmg，Windows 下载 exe，Linux 一般提供 AppImage 或 deb。安装包自带运行环境，装完不用额外配 Node。我第一次跑桌面端时其实心里有点打鼓，怕它只是壳子，实际打开后发现它把项目树、会话列表、文件 diff、命令执行面板都整合到一个界面里了，有种“给 agent 装了一个工作台”的感觉。

第三种是源码运行，适合想二次开发或者喜欢追新版的人。直接从仓库拉代码：

git clone https://github.com/oh-my-pi/oh-my-pi.git cd oh-my-pi npm install npm run dev

源码运行的好处是能改前端逻辑和 skill 运行机制，坏处是升级要手动 pull，不稳定版本也可能有 Bug。我不太建议普通用户上来就用源码，除非你确实想给项目提交 PR。

2.3 配置模型连接与 API 地址

装完后第一件事是让 agent 知道该调哪个模型。执行：

pi init

它会交互式地问你几个问题：默认模型供应商、API Key、接口地址（Base URL）、模型名称。如果用的服务完全兼容 OpenAI 格式，配置会写入本地~/.pi/config.json，大概长这样：

{ "provider": "openai-compatible", "baseUrl": "https://api.example.com/v1", "apiKey": "${YOUR_API_KEY}", "model": "your-model-name", "temperature": 0.2, "maxContextLength": 64000 }

这个配置文件有几个细节值得注意：

• temperature 建议调低，编程任务里我们需要确定性更强的输出，0.1 到 0.3 之间比较合适；
• maxContextLength 是 agent 一次任务能用的上下文上限，太大容易爆上下文，太小则读不完代码，我一般先设 64000，遇到大仓库再动态调整；
• 如果你用的是本地模型，apiKey 随便填一个占位符即可，但 baseUrl 要指向本地服务，比如 Ollama 的默认地址。

配置完成后，用一条命令验证连通性：

pi doctor

如果能正常返回模型的信息，说明 pipeline 通了。到这里，pi agent 就已经具备干活的基本条件。

3. 核心用法：Skills、桌面端、常用指令一次说清

3.1 Skills 机制：给 agent 装上可复用的“技能包”

oh-my-pi 最让我喜欢的设计是 skills。简单说，它就是一段结构化的“操作说明书”，告诉 agent 在处理某类任务时应该遵循什么步骤、调用什么脚本、检查什么输出。你可以把它理解成给智能体装的“技能包”，和 IDE 的插件、浏览器的扩展很类似。

我平时使用 skills 的场景是代码提交信息生成。以前每次提交都手写 commit message，后来我写了一个 skill，规则是“先读当前 git diff，总结变更类型，按 Conventional Commits 规范输出，并且不允许包含任何情绪化词汇”。这样 agent 不仅是“帮我生成”一个 message，而是严格按我预设的规范批量产出统一格式的提交说明。

一个 skill 的目录结构通常是这样：

~/.pi/skills/ └── generate-commit-message/ ├── skill.yaml └── run.sh

skill.yaml描述这个技能的用途和参数，run.sh是对应的执行脚本。一个最小可用的 yaml 示例：

name: generate-commit-message description: Generate a conventional commit message based on current git diff. args: - name: mode type: string required: false default: short

实际看到的效果是：在会话里输入类似“用 generate-commit-message 技能生成提交信息”的指令，agent 会先读取 skill.yaml 来理解规则，再调用 run.sh 去分析代码变更，最后按固定格式输出。这个过程保证了我的提交规范被稳定执行，而不是每次都靠模型临场发挥。

3.2 桌面端实操：看着 agent 一步一步干活

pi agent 桌面端不只是换个皮肤，它其实是把整个执行过程可视化。

我一般的工作流是这样的：打开桌面端，点击打开本地项目目录，左侧会出现项目文件树。中间是对话窗口，右侧有两个 tab，一个是 Diff 面板，展示 agent 正在修改的文件和改动内容；另一个是终端面板，实时滚动 agent 执行过的命令以及输出结果。

举个例子，我给 agent 下一个任务：“给 src/utils/date.ts 增加一个 formatDuration 函数，参数是秒数，返回中文可读时长，并补单元测试。”它在桌面端执行时，我能看到它先打开了 date.ts 读内容，然后在文件树里查找测试目录，接着写代码、创建一个新的测试文件，最后运行测试命令。如果测试失败，它会在终端面板看到报错，然后回到代码区继续修正。

桌面端最有用的功能是“执行确认模式”。默认情况下，agent 在执行高风险命令前会弹出一个确认框，我需要点允许，它才会继续。这个设计极大缓解了我对“AI 乱改代码”的担忧，第一次使用的新手我建议一定开着这个模式，等摸清了它的行为模式再逐步放开。

3.3 常用指令和 agent 工作模式

命令行终端里，oh-my-pi 提供了一组常用指令，我整理了一张速查表：

这里面计划模式（plan）是我最推荐的，尤其是在处理大任务时。普通 run 模式是让 agent 自己一路奔到终点，而 plan 模式会先给出一个分步清单，列清楚它准备改哪些文件、按什么顺序改、用哪些命令验证。我可以在确认前调整任务范围或否决危险操作。

4. 实战一次：让 pi agent 从零完成一个小需求

4.1 任务背景与需求拆分

理论说太多没用，我直接拿一次真实任务拆给大家看。我当时接手一个内部小工具项目，需求是给项目里现有的一组音频文件做批量重命名，规则是把文件名里的中文拼音缩写替换成完整拼音，并保留原来的数字序号。例如bj_zg_001.mp3要变成beijing_zhuangguang_001.mp3。这个任务本身不复杂，但涉及读目录、写脚本、跑测试、对比结果几个环节，非常适合给 agent 练手。

我没有把需求一句“把文件改成完整拼音”丢给 agent，而是先做了一次需求拆分：

• 第一步：扫描指定目录，读取当前所有文件名；
• 第二步：根据映射表，把缩写替换成完整拼音；
• 第三步：生成新文件名，同时检测重名冲突；
• 第四步：执行重命名，并输出变更日志；
• 第五步：写一个包含 5 个用例的单元测试，验证映射逻辑。

拆分完的清单我直接粘进了pi run的指令里。这种做法至关重要——模型对模糊需求的理解能力虽然有提升，但你给的边界越清楚，它跑出来的结果就越接近你要的东西。

4.2 Agent 执行全流程与关键动作

我把桌面端的执行确认模式调成“需要确认”，然后输入任务。接下来观察到的完整流程很值得记录：

第一，agent 先扫描了配置目录里的音频文件列表，并读取了项目里的package.json，判断这是一个 Node 项目，所以它生成计划时直接选了 Node.js 语法写脚本，而不是随便拿 Python 写一套。

第二，它创建了rename.js，里面定义了一个缩写映射对象，然后通过fs.readdirSync读取目录文件、遍历文件名、替换缩写并生成新文件名。代码的核心部分大致是这样的：

const fs = require('fs'); const path = require('path'); const MAP = { bj: 'beijing', zg: 'zhuangguang', sh: 'shanghai', }; function renameFiles(dir) { const files = fs.readdirSync(dir); for (const file of files) { const match = file.match(/^([a-z]+)_(\d+)\.mp3$/); if (!match) continue; const [_, short, seq] = match; const full = MAP[short]; if (!full) continue; const newName = `${full}_${seq}.mp3`; fs.renameSync(path.join(dir, file), path.join(dir, newName)); console.log(`${file} -> ${newName}`); } } renameFiles(process.argv[2]);

第三，它自己执行了测试。因为我在需求里明确写了“要写 5 个用例”，它创建了一个rename.test.js，用 Node 内置的node:test模块跑通映射逻辑，又新建了一个临时目录，放了几个真实文件做了模拟重命名测试。

第四，它停在一个文件上问我是否允许执行真实的fs.renameSync。因为默认配置里写文件操作是需要二次确认的。我点允许后，它正式执行了重命名，并在终端面板打印了完整的变更日志。

全程下来大概用了三分钟。我试过如果同样需求丢给普通对话式助手，它大概率只给你一段代码，然后留给你自己跑、自己改、自己写测试。而 pi agent 把这些杂活全部接管了。

4.3 执行完成后的检查清单

agent 任务跑完不代表可以马上收工。我自己有一套复盘检查清单，每次都会过一遍：

• Diff 复核：在桌面端右侧 diff 面板逐行看改动，确认没有删除关键逻辑；
• 测试验证：虽然 agent 自己跑过测试，我会再手动执行一次完整测试命令看真实输出；
• 敏感信息扫描：检查新增代码里有没有硬编码的密钥、内部网址；
• 边界情况补测：比如空目录、文件名不匹配、缩写不在映射表里的情况，我都会手动再测一遍；
• 提交信息规范：最后让 agent 用我自定义的 commit skill 生成提交信息，老规矩。

这套检查清单和“人工 review 同事代码”的心态一样。agent 是高效执行者，但最终责任人还是我。任何 AI 工具都不可能完全替代人的判断，尤其是涉及线上稳定性的改动时，多看一眼永远不会错。

5. 常见问题与排查技巧实录

5.1 安装与启动阶段的问题速查

我前前后后帮三个同事装过这个工具，遇到的安装问题基本稳定集中在下面几类：

绝大部分安装问题都离不开环境变量和路径配置，遇到问题第一反应不是重装软件，而是先查日志。命令行模式下加--debug参数能输出详细日志，桌面端一般在设置目录下有一个logs文件夹，读日志远比盲猜有效。

5.2 模型连接与执行阶段的问题排查

安装成功只是开始，真正让 agent 跑出高质量结果，模型连接和上下文管理是后面的大头。

我踩过最深的坑是“model 太弱导致 agent 不断自我怀疑”。有一次我用一个较小的本地模型来跑代码重构，agent 始终在同一个函数里改来改去，改完 test 又觉得不行，几乎在死循环。后来换成大参数的云端模型，同一个任务一分钟跑完。所以如果你的任务复杂度高，别吝啬用一个好的模型，生产力和模型能力几乎正相关。

5.3 几条独家避坑经验

下面这几条不是文档里写的，是我自己反复用错以后总结出来的，分享给你们。

第一条，第一次跑任务时，别上来就给最高权限。我建议先把执行确认模式打开，让 agent 在每次修改文件前等你的许可。等你对它的行为模式心里有数了，再改成“只禁止危险命令”。你会发现给 agent 设边界不是不信任它，而是保证任务不失控的基本礼仪。

第二条，skill 别贪多，优先沉淀自己重复次数最多的操作。我一开始看到社区分享的几十个技能就兴奋地全装了，结果杂七杂八的技能反而让 agent 在选择用哪个工具时犹豫不决。后来我把不用的技能全部移除，只留下提交信息规范、单元测试模板生成、依赖安全检查三个，效率和准确率反而上来了。

第三条，长任务一定要拆短。我刚开始喜欢把“帮我完成整个模块开发”这样宏大的一句话丢给 agent，结果它常常在前半段做得很好，后半段因为上下文膨胀开始遗忘早期的需求细节。正确的做法是一个任务只对应一个明确目标，如果任务太复杂，分成多个子任务逐个完成，每个子任务完成后清理一下上下文再继续。

第四条，善用“计划模式”。对我来说，pi plan最大的价值不是让 agent 做规划，而是让规划过程暴露问题。有一次我让 agent 做数据库字段迁移，它的计划里漏掉了更新 ORM 映射这一步，我一眼就看出来了，当场把这条加进去。没有计划模式，我根本发现不了这个遗漏，等它执行完字段全部变完再补救就麻烦了。

6. 一个有趣的视角：pi 到底是不是一个“PI 调节器”

6.1 从控制理论看 agent 的闭环逻辑

写完上面这些实操内容，我还想聊聊一个热词：pi调节器。很多人在搜索 oh-my-pi 时，系统会自动联想到“pi 调节器原理图”，这其实是自动控制理论里的经典概念——PI 控制器，由比例环节 P 和积分环节 I 组成。我之前做过一点控制系统相关的开发，越琢磨越觉得这个概念和 agent 的工作方式有一种奇妙的对应。

PI 调节器的核心逻辑是：系统先测量当前输出与目标值的偏差，P 环节根据当前误差大小做即时调整，I 环节则把历史误差累积起来，用来消除长期偏差。而在 oh-my-pi 这样的编程智能体里，你会发现它也在做类似的事：把“用户期望”作为设定值，把“当前代码状态”作为被控对象，每执行一步就是一次输出采样。模型根据当前任务和最新报错信息决定下一步动作，这是“比例”式的即时响应；同时它会保留任务开始以来读过的文件、写过的代码、跑过的命令结果，让决策不只看眼下，还能结合过程的累计信息，这又非常接近“积分”的作用。

我无意说什么“agent 就是 PI 控制器”这种严格类比，但从调参思维上，这套视角确实给我很多启发。以前我把 agent 当“聪明的实习生”，遇到问题就换模型、换提示词；后来我把它当成一套“带反馈的自动控制系统”，于是开始关注误差信号——也就是 agent 实际输出和预期之间的差距——并想办法压缩这个误差。

6.2 把调参思维用到 agent 工作流上

从控制系统里借来的这套视角，真的改变了我配置 oh-my-pi 的方式。下面几个参数我建议你们也试试调一调：

• 上下文长度：相当于控制系统的输入窗口。窗口太小，agent 看不到足够的历史信息，容易做出短视的修改；窗口太大，无关信息太多，反而干扰注意力。我的经验是先设一个中间值跑一两个任务，再根据反馈微调；
• 自动重试次数上限：相当于控制回路的允许振荡次数。重试次数太多，agent 会在同一个问题上反复横跳；太少，则可能会因为一次随机报错就放弃。我一般设为三次，超过三次我就会介入检查环境问题；
• 执行确认范围：相当于系统的安全限幅。对于 git push、删除文件等危险操作，一定要设置硬性确认，这就好比给执行机构加一个机械限位，防止超调。

还有一点，任务描述写得好不好，直接影响这个“闭环”的稳定性。给 agent 的任务描述越精确，误差信号就越明确，修正动作就越迅速。就像给 PI 控制器设了一个清晰的设定值，后面的反馈调节才有意义。如果你发现 agent 总是朝错误方向修，别急着怪模型，先回过头看目标描述是不是足够无歧义。

我在实际使用中越来越觉得，这类 AI 编程智能体的核心其实不是“自动写代码”，而是“把写代码这件事变成一个可观察、可干预、可迭代的闭环控制过程”。你不再需要自己盯着每一行代码才能保证质量，你只需要盯住误差信号，在关键节点介入调整，然后让 agent 在闭环里高速迭代。这个思路让我从一个“事必躬亲的编码者”慢慢变成了“盯着控制面板的负责人”，工作方式和心态都轻松了不少。

最后再分享一个小技巧：每次跑完一个重要任务，我都习惯把当时的任务描述、运行日志、最终 diff 存到一个备忘录文件里。下一次遇到相似任务时，直接把这个备忘录扔给 agent 当参考，它能少走很多弯路。这个习惯看起来不起眼，但积少成多后，你会发现自己手里攒了一堆极其宝贵的“私有 skills”，这才是把工具用到极致最该做的事情。