> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PPIO × Pi：极简编码 Agent，定制你的工作流

> 按照 Pi 接入教程配置 PPIO LLM API，了解 API Key、接口地址和 models.json 的设置方式，在终端中使用 Kimi K3 与 Fusion 融合模型完成代码分析和工具调用。

![PPIO × Pi：极简编码 Agent，定制你的工作流](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/hero.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=601e15e9b1606867c6a4baf9ca647228)

从阅读代码、定位问题，到修改文件、运行测试，AI 编程 Agent 正在参与越来越多的开发工作。

如果你习惯在终端里工作，同时希望自己决定使用什么模型、接入哪些工具、怎样组织开发流程，PI Agent（以下简称 Pi）是一个值得了解的选择。

Pi 是一款面向开发者的极简编码 Agent，由知名游戏引擎 libGDX 的创始人 Mario Zechner 发起开发，他曾坦言觉得 Claude Code 变成了一艘飞船，**80% 的功能自己用不上**，而且每次发版都在改系统提示词和工具，打断他的工作流，于是决定自己写一个。因此，当同类产品竞相往里塞功能时，Pi 反其道而行之，秉持“less is more”的设计哲学，实现“让 Pi 适应你的工作流”。

![Pi Agent 项目介绍](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/pi-overview.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=d822b1c71f32e9f788d5cd386283bb13)

## 认识 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 的定制资源](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/customization-resources.jpeg?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=f00508885c6cfe9c38513ddd7ba872d6)

从终端到应用的四种运行模式：

![Pi 的四种运行模式](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/runtime-modes.jpeg?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=a7fd55e5b4da787f7e2d8d1ec060d445)

除此之外，外部工具可通过两条路径接入。Pi 已内置 MCP，可以连接通过 MCP 提供的外部工具，具体能访问哪些系统、执行哪些操作，取决于配置的 MCP 服务及其提供的能力。

对已经拥有内部 API、知识库或自动化工具的团队，通过 MCP 与扩展就能把这些能力接入 Pi，让模型结合项目文件和外部信息完成任务。

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

### 第一步：创建 PPIO API Key

打开 [PPIO 官网](https://ppio.com/)，注册并登录账号，进入 [API 密钥管理页面](https://ppio.com/settings/key-management)，创建并保存 API Key。

![PPIO API 密钥管理](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/api-key-management.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=eab4fd78dbc3ab5bdbbbbcdfb9587fa2)

![创建并保存 PPIO API Key](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/api-key-created.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=4aca5c8b78a5102c49dd9791554948a9)

这串密钥用于验证调用身份。请妥善保管，并确认账号有可用额度、密钥有权访问准备使用的模型。

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

进入 [PPIO 模型广场](https://ppio.com/ai-computing/llm-api)，选择需要使用的模型，在详情页找到 API 接入指南。

![在 PPIO 模型广场选择模型](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/model-selection.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=10a5c3949101138c3cd060d73c3ad8ab)

![查看模型 API 接入指南](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/model-api-guide.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=fe338c1f3b5144fb4845e1db15105bf8)

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`。

在终端执行：

```bash theme={null}
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.4.0
pi --version
```

下面的终端命令以 macOS / Linux 为例。先将 API Key 设置为环境变量，把占位内容替换为自己的密钥：

```bash theme={null}
export PPIO_API_KEY="替换为你的 PPIO API Key"
```

Windows PowerShell 对应写法为：

```powershell theme={null}
$env:PPIO_API_KEY = "替换为你的 PPIO API Key"
```

以上设置仅对当前终端会话及其启动的程序生效，后续也要在已配置该变量的终端中启动 Pi。

接着，在用户目录下创建或编辑 `.pi/agent/models.json`，即默认路径 `~/.pi/agent/models.json`，填入以下内容。如果文件中已有其他服务商配置，将 `ppio` 合并到原来的 `providers` 中即可。

```json theme={null}
{
  "providers": {
    "ppio": {
      "baseUrl": "https://api.ppio.com/openai/v1",
      "api": "openai-completions",
      "apiKey": "$PPIO_API_KEY",
      "compat": {
        "supportsStore": false,
        "supportsDeveloperRole": false,
        "maxTokensField": "max_tokens"
      },
      "models": [
        {
          "id": "moonshotai/kimi-k3",
          "name": "PPIO · Kimi K3"
        }
      ]
    }
  }
}
```

这里的 `apiKey` 使用 Pi 当前版本支持的环境变量引用语法，`PPIO_API_KEY` 会读取前面设置的密钥；`compat` 则让请求使用常见的兼容字段。示例采用基础模型配置，如需使用更长上下文、图像输入或调整思考强度，可按 Pi 与具体模型的文档补充相应参数。

保存后，进入准备处理的项目目录并启动 Pi：

```bash theme={null}
cd /你的项目目录
pi --provider ppio --model moonshotai/kimi-k3
```

也可以在 Pi 中输入 `/model`，搜索并选择 PPIO · Kimi K3。打开模型选择器时，Pi 会重新读取模型配置。

![在 Pi 中选择 PPIO · Kimi K3](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/kimi-model-selection.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=6ba7a37bf6b496b4dd633d9e195938f6)

接下来，先尝试一个简单任务：

> 请读取当前项目的 README，概括项目用途和启动方式，不修改文件。

如果项目没有 README，可以改为读取一个确定存在的文本文件。观察 Pi 是否实际调用了读取工具，并根据文件内容给出回答；再到 PPIO 控制台查看是否产生了对应调用记录。这样可以同时确认模型请求和工具调用链路。

![使用 Kimi K3 验证文件读取和工具调用](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/kimi-tool-call.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=f74b25c40a030333a9aaf8e7bc11df75)

完成接入后，就可以继续让 Pi 分析代码、实现功能、定位问题或运行测试了。

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

对于复杂代码分析、技术方案比较或难定位的问题，PPIO 还提供了 Fusion 融合模型。

Fusion 会将请求分发给多个参考模型并行作答，再由融合主模型结合多方结果生成最终响应。整个过程由 PPIO 网关完成，客户端仍通过标准的 Chat Completions 接口调用。PPIO 文档显示，Fusion 支持流式输出和 Function Calling，能够用于 Agent 的工具调用流程。

在前面的 `models` 数组中追加一个模型条目即可，与原有条目之间用逗号分隔：

```json theme={null}
{
  "id": "pprouter/fusion",
  "name": "PPIO · Fusion"
}
```

接口地址和 API Key 配置保持不变，然后在 Pi 中通过 `/model` 切换，或在启动时指定：

```bash theme={null}
pi --provider ppio --model pprouter/fusion
```

![在 Pi 中选择 PPIO · Fusion](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/fusion-model-selection.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=30fce9fd34f29a69a2c0e574c16a8290)

你可以尝试这样的任务：

> 阅读当前项目的登录与鉴权相关代码，分析可能遗漏的边界条件，给出修改建议和验证方法。

![使用 Fusion 分析项目代码](https://mintcdn.com/ppinfra/ssyXDxnW17EHVzfX/third-party/images/pi/fusion-analysis.png?fit=max\&auto=format\&n=ssyXDxnW17EHVzfX\&q=85\&s=01d039880c5e0784e9d52dc4b9c4c9ce)

Fusion 更适合重视分析质量、能够接受额外等待时间的任务。一次请求内部会发生多次模型调用，费用按实际参与模型的用量汇总，响应时间也通常高于单模型直接调用。可以先将它用于关键分析步骤，再根据实际效果决定使用范围。

**Pi 提供终端中的任务执行能力，PPIO 提供可选择的模型服务与用量管理**。将二者连接起来，就能围绕自己的项目和预算，搭建一套顺手的 AI 编程工作流。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.