# Pi
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
Pi 是一款开源终端编程 Agent，通过统一 LLM API 兼容 OpenAI、Anthropic、Google 等多家协议。方舟 Coding Plan 支持在 Pi 中使用，可参考本文进行配置及使用。更多详情请参见 [Pi 官方文档](https://pi.dev/docs/latest)。
> **说明**
>
> 需要先访问 [方舟 Coding Plan活动](https://www.volcengine.com/activity/codingplan)，按需订阅套餐后再配置使用编程工具。
# 核心配置
接入工具的核心参数如下：
## **模型配置**
支持以下两种方式配置模型：
**选项：配置 Model Name (配置文件指定)**
在工具配置文件中指定 Model Name，可实时切换模型。支持配置的 Model Name：
> **注意**
>
> 配置 Model Name 时，支持使用全小写格式，同时也支持直接复制 [开通管理页面](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe) 中的模型名称。
* `doubao-seed-evolving`
* `doubao-seed-2.1-pro`
* `doubao-seed-2.1-lite`
* `doubao-seed-2.0-mini`
* `minimax-m3`
* `glm-5.3` (`glm-latest`)
* `glm-5.3-flash`
* `deepseek-v4.1-flash`
* `deepseek-v4-flash`
* `deepseek-v4-pro`
* `kimi-k2.8-preview`
* `kimi-k3`
> **说明**
>
> Model Name 不支持配置为 `Auto`，如需使用，请通过控制台切换该模式。
**选项：配置 ark-code-latest (控制台管理)**
1. 在配置文件中指定模型为`ark-code-latest`。
2. 通过 [开通管理页面](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe) 选择或切换目标模型，切换模型后 3-5 分钟即可生效。
支持 Auto 模式，通过「效果 + 速度」双维度智能算法自动选择模型。
## **Base URL**
不同的工具配置的 Base URL 根据兼容的协议会有不同：
* 兼容 Anthropic 接口协议工具：`https://ark.cn-beijing.volces.com/api/coding`
* 兼容 OpenAI 接口协议工具：`https://ark.cn-beijing.volces.com/api/coding/v3`
> **注意**
>
> 请勿使用 `https://ark.cn-beijing.volces.com/api/v3` ：该 Base URL 不会消耗您的 Coding Plan 额度，而是会产生额外费用。
## **API Key**
[获取 API Key](https://ark.volcengine.com/region:cn-beijing/apikey)
# 一、安装 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 是一个编码工具助手，支持快速配置选择的工具接入 Coding 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）**：选择 `coding-plan`。
3. 运行 ArkCLI Helper，根据界面提示完成 Pi 的配置。
1. 在命令行界面输入 `arkcli helper` 命令，启动 ArkCLI Helper。
2. **选择要配置的 Plan profile**：选择 `coding-plan_cn-beijing_personal (Coding Plan)`。
3. **选择默认 model**：按需选择。
4. **选择要配置的 AI Agent**：`Pi`。
完成上述操作后，将自动完成 Pi 的基础配置，无需手动安装。
## 方式 2：手动配置
1. 关注的配置信息如下：
* ``：替换为您自己的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
* `model`：更新为需要使用的模型信息。
2. 创建并编辑 `~/.pi/agent/models.json` 文件。如目录不存在，先创建后再编辑。
```JSON
{
"providers": {
"coding-plan": {
"api": "openai-completions",
"apiKey": "",
"baseUrl": "https://ark.cn-beijing.volces.com/api/coding/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": 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": 1048576,
"id": "kimi-k3",
"input": ["text", "image"],
"maxTokens": 65536
},
{
"id": "minimax-m3"
}
]
}
}
}
```
> **说明**
>
> 修改 `models.json` 后无需重启 Pi，在对话中执行 `/model` 会自动重新加载。
# 三、使用 Pi
1. 进入项目目录并启动 Pi：
```Bash
pi
```
2. 在 Pi 交互界面执行 `/model`，可选择切换刚才配置的 provider 和模型。
3. 发送任意问题验证连通性，例如：
```
简单介绍一下当前目录的文件结构。
```
若返回内容正常，说明 Coding Plan 已成功接入。
> 更多 Pi 使用教程请参见 [Pi 官方文档](https://pi.dev/docs/latest)。
# 常见问题
* [OpenCode 如何开启深度思考模式？](/docs/coding-plan-personal-faq#1cfacd2b)
* [如何升级 Ark Helper？](/docs/coding-plan-personal-faq#7bdd6584)
* [如何卸载 Ark Helper？](/docs/coding-plan-personal-faq#e2f455fc)
# 错误码
在编程工具中使用 Coding Plan 套餐时可能会遇到报错，您可以根据错误信息查看对应的报错场景并定位问题，具体可参考[错误码](/docs/error-codes)。