使用 Pi Agent 搭建个人开发工作流实战
Eric从多模型接入、自定义交互模式、个性化命令配置到上下文扩展，手把手带你用开源极简的 Pi Agent 搭建完全属于自己的稳定开发工作流。
8 月 28 日，OpenAI 宣布 11 月 12 日终止向 Cursor 供应模型——xAI 以 600 亿美元收购 Cursor 母公司后，触发了合同里的「控制权变更」条款，OpenAI 的回应很直接：无法确信新东家会遵守服务条款，于是给了合同允许的最大通知期。Cursor 的回应更直白：GPT 系模型只占使用量约 5%。
这类事情以前发生过，未来也不会少。但作为付费用户来说，你在 Cursor 里用 GPT 的通道，从来不是「你的」——是 Cursor 替你和 OpenAI 签的租约，所有者一变，说断就断。
模型重要还是 Harness 重要？都重要——模型决定能力上限，Harness 决定能力释放。但现实往往很骨感：很多时候你根本没有选择权，因为你的工作流被某款工具绑得太死，或者太依赖某一家模型。
用户为什么总被迫站队？因为捆绑是厂商的商业策略，从来不是技术必然。我们不妨看下现状：
| 产品 | 商业捆绑 | 用户被迫的站边 |
|---|---|---|
| Claude Code | Anthropic 模型 + 自家壳（CLI + Desktop） | 用 Claude 并使用它的生态 |
| Codex | OpenAI 模型 + OpenAI 壳（CLI + Desktop） | 用 GPT 并使用它的生态 |
| Cursor | Auto / Claude / GPT 为主要可选模型 | 要么留 Cursor 换模型，要么弃 Cursor 保模型 |
| Grok Build | xAI 模型 + CLI 工具 | 只能使用 Grok 模型 |
| OpenCode | 主要是第三方开源模型 | 外部渠道一涨价，直接调整用户额度 |
| DeepSeek Harness | 通用 Agent Harness 框架 | 刚发布 Preview 版本，稳定性待验证 |
所以，把工作流彻底解耦是迟早要做的事。对开发者来说，真正值钱的是你沉淀下来的那套工作流资产——模型、规则、扩展，每一层都握在自己手里，才叫真正的工作流。
这篇文章就来聊聊，怎么用开源极简的 Pi Agent 把这套属于自己的工作流真正搭起来。
Pi 的架构设计：开源、极简、自由组合
首先看它的基础架构，四层分工非常清晰：
pi-ai：负责模型和 Provider，主流订阅账号、API Key 基本都能接pi-agent-core：负责 Agent 循环、消息、工具和状态pi-coding-agent：在核心之上加代码能力pi-tui：终端交互界面
除了核心功能之外，其他功能都是「按需插拔」而不是「出厂塞满」。刚上手会觉得它「功能少」，但其实这是它主动的架构选择：把决定权还给你，而不是替你决定你该有什么。
现在主要有两种路线：
- 全家桶：好处就是开箱即用，产品形态齐全，如：Claude、Codex、Cursor 等，代价是内置了很多默认的工作流和工具。
- 毛坯房：只提供基础的地基，房子装修成什么样子，你自己定。如：Pi Agent、DeepSeek Harness。
快速安装使用，可以参考上一篇 用 Pi Agent 打造独属于你的 AI Harness。
模型层：扩充自己的模型池
Pi 的 pi-ai 模块把模型接口做得很纯粹，不管是官方订阅还是第三方 API Key 都能直接接。日常用 /scoped-models 圈定真正高频的那几个模型即可。
我实际先配置两家进行工作流验证：
- OpenAI Codex 订阅（
gpt-5.6-sol）：负责复杂判断、长链推理、高质量文档 - DeepSeek API（
deepseek-v4-flash）：负责日常快速迭代、中低难度实现
可以在 settings.json 中加入如下配置，按 Ctrl+P 就在已启用的模型间切换，并且自动带上预设的推理强度。
"enabledModels": [
"openai-codex/gpt-5.6-sol:high",
"deepseek/deepseek-v4-flash:max",
"deepseek/deepseek-v4-flash-vision-exp:max"
]这也是我之前写 Codex 系列时提到的组合思路：「前沿模型规划 + 快速执行模型」。gpt-5.6-sol 开 high/xhigh 推理，deepseek-v4-flash 拉满 max——各干各的活，切模型就是按一下键的事。
当然，模型分层的思路还有很多，比如经典的编排（Orchestrator）、执行（Worker）、规划（Planner）、评审（Reviewer）等。
核心逻辑就一条：把模型层和工作流彻底解耦。按任务难度挑合适性价比的模型，模型爱怎么换就怎么换，完全不影响底层的规则与技能——换模型不换工作流。
资产层：先想清楚沉淀什么
这一层是全篇最核心的部分。很多人以为搭工作流就是到处找插件、配工具，其实恰恰相反——先想清楚你要沉淀什么资产，工具和存放位置只是载体（有跨工具标准就按默认放）。
我按价值排序，沉淀三类核心资产：
01 规则：AGENTS.md
一个项目不管换什么 Agent 来干，规范和底线不能变。AGENTS.md 就是做这个的：项目结构边界、编码规范、验证命令、高压线、规范路由，一次写明白，任何 Agent 接手都生效。
我现在项目里的 AGENTS.md 已经完善到可以直接当「新人入职手册」：仓库边界、事实来源路由（什么场景读哪份规范）、工作原则（外科手术式最小修改、简单优先）、架构红线、变更影响清单、验证要求。放在根目录，走到哪都能被识别。规则资产天然跨工具。
刚开始可以把规范全写在一个 AGENTS.md 里；等内容多了，再慢慢拆解分类，在主文件里只留 Source of Truth 索引路由，让 Agent 按需去读。
02 项目知识：让 Agent 懂业务和规范
规则管「怎么做」，docs 管「懂业务」。业务术语（CONTEXT.md）、架构决策（docs/adr/）、技术规范（docs/specs/）、需求与验收清单（docs/requirements/）——Agent 有了这些背景打底，改代码才不会胡思乱想或自由发挥。
这类资产的迁移成本几乎为零：它老老实实呆在 git 仓库里，任何 Agent 照着路由表去读就行。天然就是「跟着项目走」的核心资产。和 AGENTS.md 整合后参考下图：
03 技能：把方法论变成 Agent 能力
规则和知识解决「懂」，技能解决「会」。高频任务的方法论，值得沉淀成 SKILL.md——对齐流程、评审流程、实现流程、写作流程，一次沉淀，处处复用。
技能要放在跨工具标准位置：.agents/skills/（Anthropic 的 Agent Skills 标准，Claude Code / Codex / Pi 等主流工具都读）。维护一个技能仓库做单一来源，用 skills.json + 同步脚本按分类分发到各项目的 .agents/skills——只带需要的分类，排除废弃的；任何工具打开都是同一个目录，谁读都一样。
我是参考 mattpocock/skills 的结构，进行个人 Skill 工作库的整理，然后通过脚本配置，按需导入到不同的项目。
{
"skills_src": "/Users/eric/CodeBase/XymProjects/xym-skills/skills",
"use_category_prefix": false,
"include_categories": [
"engineering"
],
"exclude": [
"productivity",
"deprecated",
"in-progress",
"misc",
"personal"
]
}关于 Pi 中 Prompt Templates（/命令 展开的 markdown 片段）——它也常被归到资产里，但我一直用得很少。原因很现实：它本质是「不想沉淀成技能的一次性长指令」，而且每个工具各管各的（.pi/prompts、.claude/commands、.cursor/commands 互不通用），工具绑定比较深。Claude Code 和 Cursor 现在也都在把命令收编进 Skills 体系。等规则、项目知识、技能都沉淀完了，还有不想技能化的高频长指令，再用它，优先级放在最后。
判断标准就一句话：换个工具，这些文件夹还在不在？ 在，就是你的；不在，就是租的。AGENTS.md、docs/、.agents/skills 都在仓库里，任何工具都能读——这就是「换壳不换资产」。
扩展层：按工作流需要，按需选型
插件绝不是装得越多越好，原则永远是：工作流卡在哪，就补哪一块。我目前常用的一套配置如下：
- 调研需要：
pi-web-access—— 写代码、做选型时要搜资料查文档，Agent 能自己联网 - 找文件需要：
@ff-labs/pi-fff—— 大项目里找文件、搜代码更快，而且「越用越懂你」，常用文件排前面 - 长任务需要：
@juicesharp/rpiv-todo—— 多步骤开发时，Agent 当前在做什么、还剩多少，一眼可见。 - 安全需要：
@gotgenes/pi-permission-system—— Pi 默认 bash 全放开，配好黑名单（git push、sudo、rm -rf拦截或询问）才敢放心用 - 并行需要：
pi-subagents—— 需要并行调研、多视角审查时派子代理（实际体验下来缺点比较明显，一是上下文传递效果难以保证，二是 Token 消耗变大，建议非特别适用场景，还是少用。特别是现在模型上下文越来越大以后，单 Agent + 大上下文 + 良好的 compaction，很多时候反而是更简单、更可靠的方案。） - 体验需要：
pi-craft-tui——自研界面，类 Codex 风格，footer 一行直接显示 token 用量、速度、缓存命中率、成本。
这六类对应六种常见场景：联网、文件查找、长任务进度、安全、并行、体验。按你自己的高频场景挑，别全装。 生态没有合适的，才是下一步——自己写。
部分示例图：
1）下图提示词：DeepSeek 创始人梁文锋为何叫梁文谷，用网络搜索。
2）下图是实际项目中 Todos 的展示，对于长耗时任务来说非常友好，能实时看到执行进度。
3）Pi Agent 的排版和终端渲染非常干净舒服，来看一张信息密度比较高的实际运行图：
自定义扩展层：需要什么，自己写
Pi Agent 自己写扩展非常轻量，官方生态也有大量现成代码可以参考。我自己顺手开源了两个日常离不开的插件：
1）第一个插件是 pi-craft-tui：Claude Code 风格 Header、Codex 风格输入区与单行 Footer 状态栏。
主要包含的功能点：
- Claude Code 风格 Header
- Codex 风格的输入框
- 单行 Footer 状态栏，包含：模型 + 推理强度、上下文使用率、项目目录、token 速率、缓存利用率
- 清屏命令：
/clear 或 /cls进行清屏操作 - 短 Skill 命令：Pi 默认调 Skill 必须敲前缀
/skill:name，不仅繁琐还跟其他工具割裂，我改成直接敲/name即可调用 - 命令补全确认：输入
/触发命令联想，按回车后是先填入输入框供你确认修改，而不是直接触发执行（原生 Pi 按回车直接执行，极易手滑误操作） - 统计命令：使用
/stats命令查看当前会话的统计数据，如下图所示
完整启动界面：
统计命令示例图：
2）第二个插件是 pi-simple-permission，主打一个简洁、易用的权限管理。
这是基于 @gotgenes/pi-permission-system 精简后的版本。原版在执行像 xargs 这类管道命令时频繁弹窗确认，非常打断编码心流，所以搞了个简洁可控的配置：
{
"permission": {
"*": "allow",
"path": {
"*": "allow",
"*.env": "deny",
"*.env.*": "deny",
"*.env.example": "allow"
},
"bash": {
"*": "allow",
"rm -rf *": "deny",
"sudo *": "ask",
"git push*": "ask"
},
"external_directory": {
"*": "allow",
"~/.ssh/*": "deny"
}
}
}总之，你不一定要用我的扩展——重点是 Pi 把「定制权」给了你：生态不适合的，自己写完全可行，我的扩展都是这么来的。
最后
聊回开头的 Cursor 和 OpenAI 事件。其实在 AI 这个圈子里，厂商之间的商业博弈、接口调整或者悄悄变相涨价，以后只会多不会少。如果每次大厂打架，我们都得手忙脚乱地适应新规则、重构开发习惯，那所谓的「AI 提效」反而成了负担。
把工作流彻底拆开来搭，本质上就想明白了一件事：工具和模型都是随时可以换的租客，你的项目规范和开发资产才是房东。
- 模型随意换：哪家性价比高用哪家跑日常代码，哪家推理强用哪家做架构规划，按一下按键切过去，不影响任何流程；
- 资产随身带：
AGENTS.md、docs/、.agents/skills/全都在 git 仓库里，换什么 CLI、换什么 IDE，打开就能直接跑； - 工具只留必需：不迷信各种花哨全家桶，用最克制的毛坯底座，缺什么功能自己补个插件，清爽又稳定。
工具形态会过时，大模型代际会更替，但你在实战中沉淀下来的这一套工程规范和方法论，才是真正带得走的东西。
不用等到哪天主力工具被断供才开始着急解耦，今天不妨就先在你的项目里建一个 AGENTS.md，把属于你自己的第一份工作流资产沉淀下来。
推荐阅读
Pi Agent 系列精选
