Skip to main content
PPIO × Pi：极简编码 Agent，定制你的工作流
从阅读代码、定位问题，到修改文件、运行测试，AI 编程 Agent 正在参与越来越多的开发工作。 如果你习惯在终端里工作，同时希望自己决定使用什么模型、接入哪些工具、怎样组织开发流程，PI Agent（以下简称 Pi）是一个值得了解的选择。 Pi 是一款面向开发者的极简编码 Agent，由知名游戏引擎 libGDX 的创始人 Mario Zechner 发起开发，他曾坦言觉得 Claude Code 变成了一艘飞船，80% 的功能自己用不上，而且每次发版都在改系统提示词和工具，打断他的工作流，于是决定自己写一个。因此，当同类产品竞相往里塞功能时，Pi 反其道而行之，秉持“less is more”的设计哲学，实现“让 Pi 适应你的工作流”。
Pi Agent 项目介绍

​
认识 Pi Agent：让 Agent 适应你的工作流

Pi 采用 MIT 开源协议，把模型请求、工具执行、上下文组织和会话记录连接起来，让开发者能够在这个基础上构建自己的工作方式。

​
模型选择开放，同一个会话中也能切换

Pi 支持 15 家以上模型服务商、数百款模型，覆盖 Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、OpenRouter、Ollama 等服务或运行环境，可通过 API Key 或 OAuth 认证。 对于内置列表之外的模型服务，Pi 支持通过 models.json 或扩展添加自定义服务商和模型。本文接入 PPIO，使用的就是这套机制。

​
从需求到执行，形成连续的工作过程

Pi 提供读取文件、执行命令、编辑和写入文件等基础工具。收到任务后，它会结合当前对话、项目指引和可用工具向模型发起请求；模型返回工具调用后，Pi 执行相应操作，再将结果交给模型继续处理。 例如，你可以让 Pi 阅读项目说明和相关代码，分析一个接口报错，修改实现，再运行测试。若测试仍然失败，它可以根据新的输出继续分析。模型负责理解问题和决定下一步，Pi 负责组织执行过程，并记录消息、工具调用及其结果。

​
上下文由你组织，会话历史也可树状回看

编程任务涉及规范、决策、大量文件与工具输出，Pi 提供几种控制方式：AGENTS.md 放项目约定，启动即加载；SYSTEM.md 与 APPEND_SYSTEM.md 替换或追加系统指令；Skills 按需加载，需要时才读全文；接近上限自动压缩，/compact 可指定保留重点，原始消息仍留在记录里。扩展还能注入信息、筛选历史或接入 RAG。 已经发生的对话过程，Pi 则完整保留为树状结构。通过 /tree 可以返回之前的对话节点，从那里继续尝试另一条思路。多个分支可以保存在同一个会话文件中，也能按消息类型筛选记录，为重要节点添加标签。

​
定制能力与运行方式，能力边界由你决定

Pi 将常见定制需求拆成了几种不同的资源，方便按需组合：
Pi 的定制资源
从终端到应用的四种运行模式：
Pi 的四种运行模式
除此之外，外部工具可通过两条路径接入。Pi 已内置 MCP，可以连接通过 MCP 提供的外部工具，具体能访问哪些系统、执行哪些操作，取决于配置的 MCP 服务及其提供的能力。 对已经拥有内部 API、知识库或自动化工具的团队，通过 MCP 与扩展就能把这些能力接入 Pi，让模型结合项目文件和外部信息完成任务。

​
简单三步，在 Pi 中接入 PPIO

​
第一步：创建 PPIO API Key

打开 PPIO 官网，注册并登录账号，进入 API 密钥管理页面，创建并保存 API Key。
PPIO API 密钥管理
创建并保存 PPIO API Key
这串密钥用于验证调用身份。请妥善保管，并确认账号有可用额度、密钥有权访问准备使用的模型。

​
第二步：选择模型，确认接口地址

进入 PPIO 模型广场，选择需要使用的模型，在详情页找到 API 接入指南。
在 PPIO 模型广场选择模型
查看模型 API 接入指南
Pi 需要通过工具调用来读取文件、执行命令，因此应选择支持 Function Calling 的模型。 注意接口地址的拼接方式。 PPIO 页面展示的服务根地址为 https://api.ppio.com/openai，Chat Completions 接口路径为 /v1/chat/completions。Pi 使用的 OpenAI SDK 会在 baseUrl 后追加 /chat/completions，因此本文配置中保留 /v1，使最终请求落到正确的接口。 Model ID 请从模型详情页复制，保留完整的厂商前缀与版本信息。

​
第三步：安装 Pi，添加模型配置

本文按 Pi 1.4.0 的配置方式编写，需要 Node.js 22.19.0 或更新版本。Pi 当前官方 npm 包为 @earendil-works/pi-coding-agent。 在终端执行：
下面的终端命令以 macOS / Linux 为例。先将 API Key 设置为环境变量，把占位内容替换为自己的密钥：
Windows PowerShell 对应写法为：
以上设置仅对当前终端会话及其启动的程序生效，后续也要在已配置该变量的终端中启动 Pi。 接着，在用户目录下创建或编辑 .pi/agent/models.json，即默认路径 ~/.pi/agent/models.json，填入以下内容。如果文件中已有其他服务商配置，将 ppio 合并到原来的 providers 中即可。
这里的 apiKey 使用 Pi 当前版本支持的环境变量引用语法，PPIO_API_KEY 会读取前面设置的密钥；compat 则让请求使用常见的兼容字段。示例采用基础模型配置，如需使用更长上下文、图像输入或调整思考强度，可按 Pi 与具体模型的文档补充相应参数。 保存后，进入准备处理的项目目录并启动 Pi：
也可以在 Pi 中输入 /model，搜索并选择 PPIO · Kimi K3。打开模型选择器时，Pi 会重新读取模型配置。
在 Pi 中选择 PPIO · Kimi K3
接下来，先尝试一个简单任务：
请读取当前项目的 README，概括项目用途和启动方式，不修改文件。
如果项目没有 README，可以改为读取一个确定存在的文本文件。观察 Pi 是否实际调用了读取工具，并根据文件内容给出回答；再到 PPIO 控制台查看是否产生了对应调用记录。这样可以同时确认模型请求和工具调用链路。
使用 Kimi K3 验证文件读取和工具调用
完成接入后，就可以继续让 Pi 分析代码、实现功能、定位问题或运行测试了。

​
接入 Fusion 融合模型，让复杂问题多一层分析

对于复杂代码分析、技术方案比较或难定位的问题，PPIO 还提供了 Fusion 融合模型。 Fusion 会将请求分发给多个参考模型并行作答，再由融合主模型结合多方结果生成最终响应。整个过程由 PPIO 网关完成，客户端仍通过标准的 Chat Completions 接口调用。PPIO 文档显示，Fusion 支持流式输出和 Function Calling，能够用于 Agent 的工具调用流程。 在前面的 models 数组中追加一个模型条目即可，与原有条目之间用逗号分隔：
接口地址和 API Key 配置保持不变，然后在 Pi 中通过 /model 切换，或在启动时指定：
在 Pi 中选择 PPIO · Fusion
你可以尝试这样的任务：
阅读当前项目的登录与鉴权相关代码，分析可能遗漏的边界条件，给出修改建议和验证方法。
使用 Fusion 分析项目代码
Fusion 更适合重视分析质量、能够接受额外等待时间的任务。一次请求内部会发生多次模型调用，费用按实际参与模型的用量汇总，响应时间也通常高于单模型直接调用。可以先将它用于关键分析步骤，再根据实际效果决定使用范围。 Pi 提供终端中的任务执行能力，PPIO 提供可选择的模型服务与用量管理。将二者连接起来，就能围绕自己的项目和预算，搭建一套顺手的 AI 编程工作流。
最后修改于 2026年11月2日