pi 开源编程 Agent
pi 把「Agent 运行时 / 统一模型接口 / 终端 UI / 编码 CLI」拆成了各自独立的包，是少见的能逐层拆开读的真实工程样本。 本专题共 30 篇，每篇都对着仓库里的真实文件写：能用的先讲怎么用，想改的再往下读源码。 项目仍在快速迭代，文中结论以 官方文档 与仓库最新代码为准。
开源编程 Agent pi 是什么：三个独立包拆出来的终端编码工具
从仓库结构出发讲清 pi 这个开源编程 Agent 项目：统一模型接口、Agent 运行时、终端界面各自被拆成独立 npm 包，一个请求从回车到模型返回要穿过哪几层，它明确不管权限与沙箱。读完你能判断它适不适合你的场景，但本文不覆盖逐个配置项的用法。
上手与使用
装起来、接上模型、把边界圈好，再按自己的习惯调顺手。
把开源编程 Agent pi 调顺手：配置、键位、主题、终端四处各改哪里
pi 把可定制的部分拆成四层：设置管行为、键位管按键、主题管配色、终端配置决定按键能不能传进来。这篇按仓库文档梳理每层的位置、生效方式与最该先改的几项，也说清哪些设置改了反而添乱。不讲怎么用 pi 干活，只讲怎么调顺手。
把开源编程 Agent pi 嵌进自己的程序：三条集成路线怎么选
pi 官方文档给了三条把 Agent 接进自己程序的路线：同进程 SDK、子进程 JSON-RPC、单次 JSON 事件流。这篇逐条拆开它们的形态、能力边界和适用场景，给出对照表、避坑清单和选型判据。不讲提示词技巧，也不评价 pi 与其它工具孰优孰劣。
开源编程 Agent pi 的本地模型接入：路由服务器与自定义服务商
拆解开源编程 Agent pi 官方文档给出的本地推理接入形态：llama.cpp 路由服务器走的是内置扩展注册 Provider 的路子，models.json 走声明式配置，两者与自定义服务商机制是同一套接口的不同入口。读完你能判断自己该走哪条，也知道它不解决模型质量与显存问题。
开源编程 Agent pi 的会话怎么存、怎么续、怎么翻回去看
从磁盘形态入手拆解 pi 的会话机制：JSONL 文件放在哪、每一行是什么条目、id 与 parentId 怎么拼成一棵树、压缩和分支摘要在文件里留下什么痕迹，以及这套设计让你能做哪些事、明确不管哪些事。不讲通用上下文方法论，只讲这个项目的落地做法。
开源编程 Agent pi 的扩展、技能、提示词模板与包该怎么选
pi 把可扩展性拆成扩展、技能、提示词模板、包四个位置，各自装在不同的层，触发方式和能力边界完全不同。这篇讲清楚每一层解决什么问题、什么场景该用哪一个、选错会付出什么代价，并给出一份基于仓库文档的避坑清单。不涉及价格、额度与安装教程。
开源编程 Agent pi 的上下文压缩：长会话崩掉前它做了什么
长会话失控不是模型变笨，是上下文账本溢出。这篇拆开源编程 Agent pi 的压缩机制：三种触发口径、切点怎么选、摘要里保留哪些结构化字段、文件追踪如何跨轮累计，以及它明确不管的那部分。读完你能判断自己的会话该不该手动压、参数该怎么调；源码级实现细节不在本篇。
开源编程 Agent pi 的终端界面为什么不闪：差分渲染在管什么
pi 自带的终端 UI 库用差分渲染处理界面闪烁与错位。本文按仓库源码梳理它的渲染主循环、宽度硬校验、光标标记与覆盖层合成，说明哪些情况下它会退回整屏重画，以及你写扩展组件时哪几条约束不能商量。不涉及价格与模型选型，也不覆盖非终端形态的界面。
开源编程 Agent pi 接入国产模型：目录、接入位与切换机制
从 pi 仓库的 provider 目录出发，讲清内置了哪些国内厂商条目、每条对应什么 API 与环境变量、切换模型时改动到底落在 auth.json 还是 models.json，以及凭据的解析优先级。只讲机制与配置位置，不讨论价格额度，也不替你做厂商选型。
开源编程 Agent pi 没有内置权限系统：三种隔离路线怎么选
pi 明说自己不提供限制文件系统、进程、网络、凭据的内置权限系统。这篇拆开它为什么这么设计、项目信任到底拦住了什么、Gondolin/Docker/OpenShell 三条隔离路线各挡住和挡不住什么、按风险怎么选。不解决提示注入，也不给合规方案。
开源编程 Agent pi 上手实录：从 npm 安装到跑通第一个任务
一篇只盯着 pi 这一个仓库的上手记录。讲清它的安装命令为什么带 --ignore-scripts、凭据的四条来源与优先级、第一次对话该给它哪些上下文、Windows 上必须先备好的 bash 和终端按键映射，以及它明确不管的那几件事。不讲模型选型，也不给任何价格与额度数字。
终端编程 Agent 选型五条线：以 pi 这个 Agent 框架为样本
开源终端编程 Agent 的差别不在功能列表，而在许可证、隔离能力、可嵌入性、模型自由度、可审计性这五条能自己查证的线上。本文以开源编程 Agent pi 的仓库与文档为样本，逐条演示每项该翻哪个文件、看哪句话、验哪个字段，并给出边界与避坑清单，不给产品排座次。
源码与设计
按包逐层读：主循环、工具层、会话存储、上下文压缩、扩展加载器与安全边界。
给开源编程 Agent pi 接入自定义模型服务：填什么，哪里最容易配错
拆解开源编程 Agent pi 的自定义 provider 机制，讲清 models.json 与扩展注册两条入口分别要你提供哪些信息、字段的默认值和替换语义、值解析语法的坑，以及上下文溢出识别失灵这类隐蔽故障。读完你能照着填一份不返工的配置，但本篇不评测任何模型服务好坏。
开源编程 Agent pi 的安全边界：项目信任与输出防护分别拦住了什么
拆开 pi 仓库里真正跟安全沾边的两处代码——项目信任的判定链路和 stdout 接管机制，说清它们各自拦住什么、拦不住什么，并对照官方安全文档里承认的不设防地带。读完你能判断在什么场景下必须把 pi 关进容器，不解决模型侧越权和提示注入的根治问题。
开源编程 Agent pi 的仓库结构导读：七个包各管什么、依赖怎么排
拆解开源编程 Agent 项目 pi 的 monorepo：七个工作区各自的职责边界、依赖方向为什么是单向的、拿到仓库后按什么顺序读源码最省时间，以及它明确不管哪些事。不讲怎么用 pi 干活，也不做工具横评。
开源编程 Agent pi 的服务端包：进程怎么拉起、怎么看住
拆解开源编程 Agent 项目 pi 的实验性服务端包，讲清它如何把 agent 拉起为子进程、如何用一条 stdin 送请求、如何在异常退出和守护进程重启后维持状态记账，以及它明确不负责的部分。读完你能判断这套结构值不值得借鉴，不涉及模型效果与价格。
开源编程 Agent pi 的服务商层：模型清单从哪来，怎么加一家
拆解开源编程 Agent pi 仓库里的服务商层：Provider 接口与 Models 集合各管什么、内置模型目录由哪个脚本生成、动态清单怎么刷新和缓存，以及往仓库里加一家新服务商需要改哪些文件。读完能照着仓库定位每一处改动点，不涉及各家模型的价格与额度对比。
开源编程 Agent pi 的钩子与可观测性：能插手哪些时机，又能看到哪些数据
拆解开源编程 Agent pi 的两套机制——可以改变执行结果的事件钩子，和只读不干预的观测事件契约。你会拿到完整的事件时机清单、能落到审计与成本归因上的数据来源，以及一份避坑清单。不解决怎么装 pi、怎么调模型，也不替你选 APM 方案。
开源编程 Agent pi 的会话存储：JSONL 追加树与恢复流程
拆解开源编程 Agent pi 的会话持久化：文件落在磁盘哪个位置、一行 JSONL 长什么样、追加写与 leaf 条目怎么配合出一棵可分叉的树、恢复一次会话时按什么顺序读文件并重建上下文。读完你能自己写脚本解析它的会话，也知道这套结构在哪些场景会吃亏。不讲价格与额度。
开源编程 Agent pi 的基础工具层：四把工具的参数、边界与克制
逐个拆开 pi 内置的 bash、read、write、edit 四把基础工具，看清每把工具向模型暴露了哪几个参数、边界画在哪、超出边界时返回什么提示，以及默认工具集为什么只留四个而不是七个。读完你能照着这套取舍去审视自己的工具层。不涉及安装配置、模型接入与扩展开发。
开源编程 Agent pi 的技能机制：怎么被发现、被筛选、装进上下文
拆开 pi 这个 Agent 框架的技能加载链路，讲清楚技能目录是怎么被扫出来的、重名和软链怎么裁决、进系统提示的到底是哪几个字段，以及这套设计把成本压在了描述行和一次额外读文件上。不讲怎么写好一个技能的正文，也不做工具优劣排序。
开源编程 Agent pi 的可持久化运行：中断后能续上需要哪些前提
拆解 pi 仓库里关于可持久化 Agent 运行的设计文档，讲清楚半可持久化这个取舍是怎么来的、会话日志为什么被当成唯一的耐久状态树、恢复时宿主应用必须自己重建哪些依赖，以及默认保守恢复策略覆盖了哪些崩溃点。不解决具体的部署与存储选型问题，也不承诺该设计的落地时间表。
开源编程 Agent pi 的扩展加载器：从被发现到被执行要过几层
拆解开源编程 Agent pi 的扩展加载链路，从目录发现、jiti 载入、注册期与运行期分离，到工具包装层做了什么。读完你能照着排查扩展没生效、动作方法报未初始化、快捷键被吞这类问题。不涉及扩展怎么写业务逻辑，也不讲 MCP 协议本身。
开源编程 Agent pi 的模型解析链路：从你写的名字到真正发出的请求
拆解开源编程 Agent pi 里模型名的解析过程：模式匹配怎么把模糊字符串变成具体模型、注册表的三层叠加如何决定候选集、组装器又往请求里塞了什么。读完你能定位「为什么选中的不是我要的那个模型」，但它不替你做路由与成本决策。
开源编程 Agent pi 的评测包：它怎么给一个 Agent 建回归
拆开 pi 仓库里的 evals 包，看它怎么把一次 Agent 运行压成可断言的结构化结果、怎么用临时目录保证每次从干净状态开始、怎么把模型选择做成硬失败。读完你能拿到一套可以直接搬进自己项目的回归骨架，以及它明确不管的那几件事。不解决评分标准和线上质量监控。
开源编程 Agent pi 的上下文压缩：源码级拆解触发时机与保留策略
从 pi 仓库里的 compaction.ts、branch-summarization.ts 和官方文档出发，拆开这套上下文压缩的三个入口、切分点规则、分裂轮次的双摘要、文件轨迹累积，以及分支摘要在解决什么问题。读完你能自己判断该怎么调那几个阈值、哪些信息注定会丢。不覆盖记忆检索与跨会话长期记忆。
开源编程 Agent pi 的统一模型接口：一套类型怎么盖住十种协议
拆解开源编程 Agent pi 的 @earendil-works/pi-ai 包，看它用哪几层类型把 Anthropic Messages、OpenAI Responses 等十种形态各异的接口收敛成同一份消息与事件模型，接缝落在 compat 位、签名回放和工具切分这三处。读完你能拿到一张组件对照表和一份避坑清单，不涉及价格、额度与选型排名。
开源编程 Agent pi 的文件编辑：差异比对与写入排队各挡什么事故
从 pi 仓库里 edit、edit-diff、file-mutation-queue 三个文件出发，讲清它的编辑工具靠哪几道校验避免改坏文件，模糊匹配的代价被关在哪里，多个工具同时改一个文件时队列怎么排。读完能拿到一份可复用的设计与避坑清单，不涉及安装配置与模型选型。
开源编程 Agent pi 的系统提示词是怎么拼出来的：固定段、动态段与替换位
逐行拆解开源编程 Agent pi 的系统提示词拼装逻辑：默认正文里写死了哪几块、工具清单和守则从哪来、项目上下文与技能清单怎么注入、替换与追加两条路径的差别在哪。读完你能自己定位每一段文本的来源文件，也知道哪些配置会让某一段静默消失。不涉及模型效果调优与提示词写法优劣。
逐段读开源编程 Agent pi 的主循环：一轮里发生了什么，循环靠什么停
打开 pi 仓库里 packages/agent 的三个文件，把它的 Agent 主循环拆成可跟读的几段：一轮（turn）的边界在哪、工具调用在哪一步接回上下文、并行与串行怎么切、循环有哪几个出口。读完你能照着改自己的循环，也知道它有意不管哪些事。不讲提示词技巧，不讲模型选型。
想把 Agent 真正搭起来，而不只是会用？
从 Agent 工程实践到数字员工落地，站内有成体系的教程与课程。