# Pi

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

本文介绍如何在 Pi 中配置并使用方舟 Agent Plan 企业版。

<span id="pre-operation"></span>
# 前提条件

* 需由管理员账号完成以下操作后，子账号方可配置并使用 Pi：

  1. 购买方舟 Agent Plan 企业版套餐：[一、购买 Agent Plan 企业版](/docs/agent-plan-enterprise-get-started#purchase-plan)。
  2. 为子账号分配席位：[二、分配席位](/docs/agent-plan-enterprise-get-started#assign-seats)。

* 安装 [Node.js 20 或更新版本](https://nodejs.org/en/download/)。

<span id="install-pi"></span>
# 安装 Pi

**选项：macOS/Linux**

在命令行界面，执行以下命令安装 Pi。

```Bash
# 方式 1：npm 全局安装
npm install -g @earendil-works/pi-coding-agent

# 方式 2：官方一键脚本
curl -fsSL https://pi.dev/install.sh | sh
```

安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。

```Bash
pi --version
```

**选项：Windows**

需先额外安装 [Git for Windows](https://git-scm.com/download/win)，Pi 依赖其提供的 `bash.exe` 执行 `!` / `!!` shell 命令；官方 curl 一键脚本在 Windows 上不支持。

通过 npm 全局安装：

```Bash
npm install -g @earendil-works/pi-coding-agent
```

安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功。

```Bash
pi --version
```

<span id="configure-pi"></span>
# 配置 Pi

<span id="method-1-auto-helper"></span>
## 方式 1：一键配置（推荐）

Ark CLI 是火山方舟平台官方命令行工具，支持在本地终端快速完成认证与资源管理，并可将能力安装到常用 AI Agent 中，降低手动配置的时间成本和出错风险。

1. 安装 Ark CLI

    环境要求：Node.js 18 或更新版本。支持 macOS、Linux、Windows。

```Bash
npm install -g @volcengine/ark-cli@latest
arkcli --version
```

2. 登录 Ark CLI

    根据界面提示选择登录方式，推荐选择 **火山 SSO (浏览器登录)**，在浏览器中完成授权即可。

```Bash
arkcli auth login
```

3. 一键配置 Pi

```Bash
arkcli helper
```
运行 ArkCLI Helper，根据界面提示完成配置。
* **选择 Profile**：`agent-plan-team_cn-beijing_team`。
* **选择默认 model**：按需选择。
* **选择 AI Agent**：`Pi`。
    支持配置 Harness 能力，根据界面提示按需选择`配置`或者`跳过`。

配置完成后，Pi 会自动识别配置的模型。启动 Pi 即可使用。

<span id="method-2-manual"></span>
## 方式 2：手动配置

创建并编辑 `~/.pi/agent/models.json` 文件。关注的配置信息如下：

* `<ARK_API_KEY>`：替换为您自己的 [专属 API Key](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan-enterprise/mine)。
![image-20260909-103103-932.png](https://arkdocs.tos-cn-beijing.volces.com/images/agent-plan/agent-plan-enterprise-api-key.png)
* `model`：见[支持模型及 Harness](/docs/agent-plan-enterprise-plan-overview#supported-models-harness)，需配置文本生成模型。

    ```JSON
    {
      "providers": {
        "agent-plan": {
          "api": "openai-completions",
          "apiKey": "<ARK_API_KEY>",
          "baseUrl": "https://ark.cn-beijing.volces.com/api/plan/v3",
          "models": [
            {
              "id": "ark-code-latest"
            },
            {
              "contextWindow": 1048576,
              "id": "doubao-seed-evolving",
              "input": ["text", "image"],
              "maxTokens": 256000
            },
            {
              "contextWindow": 1048576,
              "id": "doubao-seed-2.1-pro",
              "input": ["text", "image"],
              "maxTokens": 256000
            },
            {
              "contextWindow": 1048576,
              "id": "doubao-seed-2.1-lite",
              "input": ["text", "image"],
              "maxTokens": 256000
            },
            {
              "contextWindow": 262144,
              "id": "doubao-seed-2.0-mini",
              "input": ["text", "image"],
              "maxTokens": 128000
            },
            {
              "contextWindow": 1048576,
              "id": "glm-5.3",
              "input": ["text"],
              "maxTokens": 128000
            },
            {
              "contextWindow": 1048576,
              "id": "glm-5.3-flash",
              "input": ["text", "image"],
              "maxTokens": 128000
            },
            {
              "contextWindow": 1048576,
              "id": "deepseek-v4-pro",
              "input": ["text"],
              "maxTokens": 393216
            },
            {
              "contextWindow": 1048576,
              "id": "deepseek-v4.1-flash",
              "input": ["text", "image"],
              "maxTokens": 393216
            },
            {
              "contextWindow": 1024000,
              "id": "deepseek-v4.1-flash-economy",
              "input": ["text", "image"],
              "maxTokens": 393216
            },
            {
              "contextWindow": 1048576,
              "id": "deepseek-v4-flash",
              "input": ["text"],
              "maxTokens": 393216
            },
            {
              "contextWindow": 1048576,
              "id": "glm-latest",
              "input": ["text"],
              "maxTokens": 128000
            },
            {
              "contextWindow": 1048576,
              "id": "kimi-k2.8-preview",
              "input": ["text", "image"],
              "maxTokens": 1048576
            },
            {
              "contextWindow": 1024000,
              "id": "kimi-k3.1-pro",
              "input": ["text", "image"],
              "maxTokens": 1024000
            }
          ]
        }
      }
    }
    ```

> **说明**
>
> 修改 `models.json` 后无需重启 Pi，在对话中执行 `/model` 会自动重新加载。

<span id="use-pi"></span>
# 使用 Pi

1. 进入项目目录并启动 Pi：

    ```Bash
    pi
    ```

2. 在 Pi 交互界面执行 `/model`，可选择切换刚才配置的 provider 和模型。
    支持的模型参见 [支持模型及 Harness](/docs/agent-plan-enterprise-plan-overview#supported-models-harness)。

    ![ap-team-pi-choose-model.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/ap-team-pi-choose-model.png)

3. 发送任意问题验证连通性，例如：

    ```
    简单介绍一下当前目录的文件结构。
    ```

    若返回内容正常，说明 Agent Plan 企业版已成功接入。

> 更多 Pi 使用教程请参见 [Pi 官方文档](https://pi.dev/docs/latest)。

<span id="other-operations"></span>
# 其他操作

<span id="switch-model"></span>
## 切换模型

Pi 支持两种切换方式：

|配置方式 |操作 |
|---|---|
|交互切换 |在 Pi 对话界面执行 `/model`，从下拉列表选择目标模型。 |
|修改配置 |编辑 `~/.pi/agent/models.json`，在对应 provider 的 `models` 数组中新增或调整模型条目，保存后执行 `/model` 触发重载。 |

<span id="add-image-video-generation"></span>
## 添加图片生成/视频生成能力

方舟 Agent Plan 企业版 Team Medium 及以上套餐提供图片生成模型配额，Team Large 及以上套餐提供视频生成模型配额。Pi 的 `models[].input` 只声明**输入**模态（`text` / `image`），图片/视频生成需要通过工具调用或 MCP 接入。具体配置方法请参见 [接入视觉模型](/docs/agent-plan-enterprise-visual-models)。

> **注意**
>
> * 不同的套餐支持的视觉模型有所不同，具体参见[支持模型及 Harness](/docs/agent-plan-enterprise-plan-overview#supported-models-harness)。
> * 视觉模型不支持通过 Auto 及控制台切换使用。