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

# Pi

Pi 是 earendil-works 开源的终端编码 Agent，支持文件读取、编辑和命令执行。通过自定义 Provider，可使用 Anthropic Messages 协议接入 Step Plan。

## 接入条件

* macOS、Linux 或 Windows，已安装 Node.js 22.19 或更高版本及 npm。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

在终端中执行以下命令，检查当前环境：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
node --version
npm --version
```

如果 Node.js 版本为 `v22.19.0` 或更高，且 npm 能正常输出版本号，可直接继续安装 Pi。

## 安装 Pi

安装 Pi 0.87.1：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.87.1
```

检查安装版本：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi --version
```

## 配置 Step Plan

### 设置 API Key

在启动 Pi 的终端中设置环境变量，将 `YOUR_STEP_API_KEY` 替换为实际密钥：

<Tabs>
  <Tab title="macOS / Linux / WSL">
    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    export STEP_API_KEY="YOUR_STEP_API_KEY"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    $env:STEP_API_KEY = "YOUR_STEP_API_KEY"
    ```
  </Tab>
</Tabs>

### 添加模型

1. 打开 `~/.pi/agent/models.json`。如果设置了 `PI_CODING_AGENT_DIR` 时，请使用该目录下的 `models.json`。
2. 将以下 `providers.stepfun` 配置合并到文件中，保留其他 Provider。文件不存在时创建目录并保存以下 JSON。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "providers": {
    "stepfun": {
      "baseUrl": "https://api.stepfun.com/step_plan",
      "api": "anthropic-messages",
      "apiKey": "$STEP_API_KEY",
      "models": [
        { "id": "step-5-preview", "input": ["text", "image"], "contextWindow": 1000000 },
        { "id": "step-3.7-flash", "input": ["text", "image"], "contextWindow": 256000 }
      ]
    }
  }
}
```

| 字段 | 说明 |
| - | - |
| `providers.stepfun` | Provider 标识，启动时通过 `--provider stepfun` 选择。 |
| `baseUrl` | Step Plan 配置地址。Pi 自动追加 `/v1/messages`，最终路径为 `/step_plan/v1/messages`。 |
| `api` | `anthropic-messages` 指定 Anthropic Messages 协议。 |
| `apiKey` | `$STEP_API_KEY` 引用启动进程中的环境变量。 |
| `models[].input` | 允许客户端发送的输入类型。 |
| `models[].contextWindow` | 客户端使用的上下文窗口，填写整数 token 数。 |

[Step 5 Preview](/docs/zh/guides/models/step-5-preview) 的上下文窗口为 1M tokens，[Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash) 为 256K tokens。上述配置分别使用 `1000000` 和 `256000`。

### 设置默认模型

将以下字段合并到同一配置目录中的 `settings.json`：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "defaultProvider": "stepfun",
  "defaultModel": "step-5-preview"
}
```

## 启动 Pi

在项目目录的终端中执行：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi
```

也可在启动时指定 Provider 和模型：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi --provider stepfun --model step-5-preview
```

## 验证接入

### 检查模型配置

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi auth check --provider stepfun --json
pi --list-models stepfun
```

认证检查的 `status` 应为 `ready`，表示客户端能够解析凭据。模型列表应包含配置的模型 ID，Step 5 Preview 的上下文显示为 1M，Step 3.7 Flash 显示为 256K。

### 验证对话

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi --provider stepfun --model step-5-preview --print "请只回复 OK。"
```

预期返回 `OK`。

### 验证工具调用

在安装了 Python 的独立测试目录中创建 `README.md`，内容为 `Pi Step Plan test`。从该目录启动 Pi，输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
读取 README.md，创建 hello.py，输出 Hello, StepFun!。
使用本机可用的 Python 解释器运行 hello.py，并汇报执行命令和输出。
不要修改其他文件。
```

核对文件读取、创建和命令执行记录，确认目录中生成 `hello.py`，运行输出为 `Hello, StepFun!`。

### 核对用量

在 [StepFun 开放平台](https://platform.stepfun.com)的使用详情中，按请求时间核对模型 ID 和计费来源，确认调用使用 Step Plan。

## 常见问题

<AccordionGroup>
  <Accordion title="Q: 模型列表中没有 Step 模型怎么办？">
    检查生效目录中的 `models.json` 是否为有效 JSON，以及 `providers.stepfun.models` 中的模型 ID。打开 `/model` 重新加载配置，或重启 Pi 后运行 `pi --list-models stepfun`。
  </Accordion>

  <Accordion title="Q: 无法解析 API Key 或认证失败怎么办？">
    在启动 Pi 的同一终端中设置 `STEP_API_KEY`，检查密钥是否完整、有效，且属于所用端点对应的账号。若 `auth.json` 中已保存 `stepfun` 凭据，Pi 会优先使用该凭据，应一并核对其内容。
  </Accordion>

  <Accordion title="Q: 请求路径错误怎么办？">
    `api` 使用 `anthropic-messages`，`baseUrl` 填写 `https://api.stepfun.com/step_plan`。Pi 自动追加 `/v1/messages`，配置地址只保留到 `/step_plan`。
  </Accordion>

  <Accordion title="Q: 上下文窗口显示与模型规格不一致怎么办？">
    检查对应模型的 `contextWindow`：`step-5-preview` 使用 `1000000`，`step-3.7-flash` 使用 `256000`。保存后重新加载模型列表并选择该模型。
  </Accordion>
</AccordionGroup>


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