# Pi
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
本文介绍如何配置方舟 Agent Plan 到 Pi 中使用。Pi 是一款开源终端编程 Agent，通过统一 LLM API 兼容 OpenAI、Anthropic、Google 等多家协议。更多详情请参见 [Pi 官方文档](https://pi.dev/docs/latest)。
# 一、前提条件
* 您已按需订阅 Agent Plan 套餐。如未，请访问 [开通管理-Agent Plan](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan?agentMode=close) 页面订阅套餐。
* 您已正确安装 Pi，如未，请参见以下操作完成软件安装。
前提条件：安装 [Node.js 20 或更新版本](https://nodejs.org/en/download/)。
**选项：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
```
# 二、配置 Pi
## 方式 1：自动化助手（推荐）
ArkCLI Helper 是一个编码工具助手，支持快速配置选择的工具接入 Agent Plan。安装并运行该助手，根据界面提示操作可自动完成工具配置，降低手动配置的时间成本和出错风险。
> **注意**
>
> * ArkCLI Helper 是基于 Ark Helper 升级演进的工具配置服务，相关能力将持续在 ArkCLI Helper 上迭代更新。建议优先使用 ArkCLI Helper 完成工具配置。
> * ArkCLI Helper 支持 macOS、Linux、Windows 系统。
1. 安装 Ark CLI。
```Bash
# 1. 通过 NPM 安装
npm install -g @volcengine/ark-cli@latest
# 2. 验证安装
arkcli --version
```
2. 登录 Ark CLI。
```Bash
arkcli auth login
```
根据界面提示选择登录方式。若之前已登录过 arkcli，会沿用上次选择的配置；如需重新选择，请先执行 `arkcli config reset` 后再运行 `arkcli auth login`。首次登录时，按提示完成以下配置：
1. **选择项目（Project）**：可按需选择，或默认选择**账号全部资源**。
2. **选择消费模式（Type）**：选择 `agent-plan`。
3. 运行 ArkCLI Helper，根据界面提示完成 Pi 的配置。
1. 在命令行界面输入 `arkcli helper` 命令，启动 ArkCLI Helper。
2. **选择要配置的 Plan profile**：`agent-plan_cn-beijing_personal (Agent Plan)`。
3. **选择默认 model**：按需选择。
4. **选择要配置的 AI Agent**：`Pi`。
当前支持的 Harness 包括：AI Native 应用开发底座和Computer Use Agent，根据界面提示按需选择`配置`或者`跳过`。
完成上述操作后，将自动完成 Pi 的基础配置，并按选择结果自动安装对应的 Harness 工具，无需手动安装。
## 方式 2：手动配置
下面详细介绍如何手动完成配置。
1. 关注的配置信息如下：
* ``：替换为您自己的 [专属 API Key](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&OpenModelVisible=false&advancedActiveKey=agentPlan)。
* `model`：见[支持模型及 Harness](/docs/agent-plan-personal-plan-overview#3d801f5f)，需配置文本生成模型。
2. 创建并编辑 `~/.pi/agent/models.json` 文件。如目录不存在，先创建后再编辑。
```JSON
{
"providers": {
"agent-plan": {
"api": "openai-completions",
"apiKey": "",
"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.1-flash",
"input": ["text", "image"],
"maxTokens": 393216
},
{
"contextWindow": 1048576,
"id": "deepseek-v4-pro",
"input": ["text"],
"maxTokens": 393216
},
{
"contextWindow": 1048576,
"id": "deepseek-v4-flash",
"input": ["text"],
"maxTokens": 393216
},
{
"contextWindow": 1048576,
"id": "kimi-k3",
"input": ["text", "image"],
"maxTokens": 128000
},
{
"contextWindow": 1048576,
"id": "kimi-k2.8-preview",
"input": ["text", "image"],
"maxTokens": 1048576
},
{
"contextWindow": 1048576,
"id": "glm-latest",
"input": ["text"],
"maxTokens": 128000
},
{
"contextWindow": 1048576,
"id": "minimax-m3",
"input": ["text", "image"],
"maxTokens": 131072
}
]
}
}
}
```
> **说明**
>
> 修改 `models.json` 后无需重启 Pi，在对话中执行 `/model` 会自动重新加载。
# 三、启动并使用 Pi
1. 进入项目目录并启动 Pi：
```Bash
pi
```
2. 在 Pi 交互界面执行 `/model`，可选择切换刚才配置的 provider 和模型。支持的模型可见 [支持模型及 Harness](/docs/agent-plan-personal-plan-overview#3d801f5f)。
3. 发送任意问题验证连通性，例如：
```
简单介绍一下当前目录的文件结构。
```
若返回内容正常，说明 Agent Plan 已成功接入。
> 更多 Pi 使用教程请参见 [Pi 官方文档](https://pi.dev/docs/latest)。
# 其他操作
## 切换模型
Pi 支持两种切换方式：
|配置方式 |操作 |
|---|---|
|交互切换 |在 Pi 对话界面执行 `/model`，从下拉列表选择目标模型。 |
|修改配置 |编辑 `~/.pi/agent/models.json`，在对应 provider 的 `models` 数组中新增或调整模型条目，保存后执行 `/model` 触发重载。 |
## 添加图片生成/视频生成能力
方舟 Agent Plan Medium 及以上套餐提供图片生成模型配额，Large 及以上套餐提供视频生成模型配额。Pi 的 `models[].input` 只声明**输入**模态（`text` / `image`），图片/视频生成需要通过工具调用或 MCP 接入。具体配置方法请参见 [接入视觉模型](/docs/agent-plan-personal-visual-models)。
> **注意**
>
> * 不同的套餐支持的视觉模型有所不同，具体参见[支持模型及 Harness](/docs/agent-plan-personal-plan-overview#3d801f5f)。
> * 视觉模型不支持通过 Auto 及控制台切换使用。