Pi

Pi（Pi Coding Agent）是一款在终端中运行的 AI 编程助手。它可以读取、编辑和创建项目文件，也可以在你的确认下执行终端命令。本文介绍 Pi 的安装、模力方舟 API 配置与基础使用。

1. 准备运行环境

Pi 通过 npm 安装，要求 Node.js 22.19.0 或更高版本。推荐安装满足该要求的 Node.js LTS 版本。

Windows

安装 Node.js

方式一：从官网下载（推荐）

1. 打开 Node.js 官网。
2. 下载 LTS 版本的 Windows 安装包（.msi）。
3. 双击下载的安装包，按向导完成安装；安装时保留默认的 Add to PATH 选项。
4. 关闭并重新打开 PowerShell 或 Windows Terminal。

方式二：使用包管理器

如果已安装 Chocolatey 或 Scoop，也可以在 PowerShell 中执行：

# 使用 Chocolatey
choco install nodejs-lts

# 或使用 Scoop
scoop install nodejs-lts

提示

如果安装时出现权限错误，请以管理员身份打开 PowerShell。Windows 用户建议使用 PowerShell 或 Windows Terminal，而不是 CMD。

准备 Bash

Pi 的 bash 工具统一使用 Bash 语法执行命令；Windows 原生不提供 Bash，因此需要安装 Git for Windows 提供的 Git Bash。

安装完成后，在 Git Bash 中执行：

bash --version

Pi 会自动查找默认位置的 Git Bash。若 Git 安装在自定义路径，可以在 %USERPROFILE%\.pi\agent\settings.json 中指定 Bash 路径，例如：

{
  "shellPath": "E:\\Git\\Git\\bin\\bash.exe"
}

将示例路径替换为自己电脑上 bash.exe 的实际位置。

macOS

方式一：从官网下载

1. 打开 Node.js 官网。
2. 下载 LTS 版本的 macOS 安装包（.pkg）。
3. 双击安装包并按向导完成安装。

方式二：使用 Homebrew

如果已安装 Homebrew，在终端中执行：

brew install node

Linux / WSL2

推荐通过发行版的包管理器安装当前 LTS 版本。Ubuntu、Debian、Fedora 和其他 Linux 发行版的具体命令可参考 Node.js 下载页。安装完成后请验证版本不低于 22.19.0。

验证安装

安装完成后，打开新的终端并执行：

node --version
npm --version

两个命令均能输出版本号，且 node --version 显示 v22.19.0 或更高版本后，再继续下一步。

2. 安装 Pi

在任意终端中执行：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 会跳过依赖安装脚本；Pi 的正常 npm 安装不依赖这些脚本。

安装完成后，验证命令是否可用：

pi --version
pi --help

若能分别看到版本号和帮助信息，说明安装完成。

提示

如果终端提示找不到 pi，请关闭并重新打开终端，使 npm 的全局命令目录重新加载到 PATH 中。

3. 配置 Pi

配置模力方舟模型

获取访问令牌

访问 工作台 -> 设置 -> 访问令牌 获取访问令牌。没有购买 Serverless API 的开发者，可以使用免费体验访问令牌（仅供体验，每日调用次数有限）。复制要使用的令牌，稍后填入 Pi 配置文件。

添加模型配置

使用 CC-Switch 自动配置（推荐）

CC-Switch 是社区开源的桌面 GUI，可集中管理多个 AI 编程工具的服务商与模型配置，并在多套 API Key 或计费方案之间一键切换，无需手动修改 Pi 的配置文件。

如果已安装 CC-Switch，可以通过它的界面自动写入 Pi 的模型配置文件，无需手动编辑 models.json。请使用支持 Pi 的 CC-Switch v3.20.0 或更高版本。

1. 打开 CC-Switch，在顶部应用列表中选择 Pi。

2. 点击添加供应商，选择 自定义配置，然后填写以下信息(这里以模力方舟的 deepseek-v4-flash-0731 模型作为示例)：

   • 供应商标识：填写 moark-cc。(该标识可自定义且必须唯一)
   • 供应商名称：填写 模力方舟。
   • 备注：可填写 模力方舟访问令牌。
   • 官网链接：填写 https://ai.gitee.com。
   • 接口格式：选择 OpenAI Chat Completions。
   • API Key：粘贴上一步获取的模力方舟访问令牌。
   • Base URL：填写 https://api.moark.com/v1。

   然后添加以下模型参数：

   • 模型 ID：填写 deepseek-v4-flash-0731。
   • 显示名称：填写 DeepSeek-V4-Flash-0731（模力方舟）。
   • 支持扩展思考：开启。
   • 支持图片输入：关闭。
   • 上下文长度：填写 1000000。(按照官方参数提供)
   • 最大输出 Token 数：填写 16384。(按照官方参数提供)

配置提示

模型能力因模型及接口而异，请按实际能力设置以上开关。

示例映射（DeepSeek）：

• Pi high → DeepSeek high：高强度推理。
• Pi xhigh → DeepSeek max：最大强度推理。

本示例的 DeepSeek 官方 Chat API 仅支持文本输入。配置其他模型时，请以对应模型及模力方舟接口文档为准，不要直接套用上述映射。

3. 保存配置。CC-Switch 会自动写入 Pi 的模型配置文件。
4. 启动 Pi，输入 /model，选择 deepseek-v4-flash-0731。

提示

同一个 CC-Switch 中不能有重复的供应商标识。若 moark 已被使用，可改为 moark-dsv4 或 moark-cc。

手动添加模型配置

Pi 通过 models.json 配置自定义模型服务(pi不会自动创建，需要手动创建)。创建或编辑下列文件：

• macOS / Linux：~/.pi/agent/models.json
• Windows：%USERPROFILE%\.pi\agent\models.json

写入以下配置(这里用模力方舟的 deepseek-v4-flash-0731 模型作为示例)：

{
  "providers": {
    "moark": {
      "baseUrl": "https://api.moark.com/v1",
      "api": "openai-completions",
      "apiKey": "你的API密钥",
      "authHeader": true,
      "headers": {
        "X-Failover-Enabled": "true"
      },
      "models": [
        {
          "id": "deepseek-v4-flash-0731",
          "name": "DeepSeek-V4-Flash-0731（模力方舟）"
        }
      ]
    }
  }
}

提示

将 "你的API密钥" 替换为上一步获取的实际访问令牌。请妥善保管该文件，不要将访问令牌提交到代码仓库或分享给他人。

Pi 会在打开模型选择器时读取此文件。配置完成后，启动 Pi 并输入 /model，选择你要使用的模型。

使用其他服务商

在 Pi 中输入 /login 后，可以选择以下两种认证方式：

• 订阅服务：选择订阅登录选项，按界面提示在浏览器中完成服务商账号授权。
• API Key 服务：选择 API Key 选项，并在列表中选择要使用的服务商。

以 DeepSeek API Key 为例：

1. 输入 /login，选择 Use an API key。
2. 在服务商列表中选择 DeepSeek。
3. 按提示粘贴你的 DeepSeek API Key 并确认保存。

完成认证后，输入 /model，从 DeepSeek 的可用模型中选择本次会话使用的模型。

信息

这里的 DeepSeek 仅作为 Pi 内置 API Key 服务商的示例，与前文通过 models.json 配置的模力方舟模型相互独立。

4. 开始使用 Pi

进入希望让 Pi 协助处理的项目目录：

cd path/to/your-project
pi

选择模力方舟模型后，直接用自然语言描述任务即可。例如：

请阅读这个项目的 README，告诉我如何在本地启动它。

Pi 默认向模型提供 read、write、edit 和 bash 四种工具。因此在让它修改文件或执行命令前，应先阅读它的计划与操作说明，并检查变更结果。

常用交互命令：

命令	用途
/login	登录或管理模型服务凭据
/model	选择或切换模型
/new	创建新的会话
/session	查看当前会话的文件、消息数、Token 用量和费用信息
/settings	调整主题、思考等级等设置

更多命令说明请参见 Pi Coding Agent README 中的官方命令列表。

更多资源

• Pi 官方快速入门
• Pi Coding Agent 官方仓库
• 平台 API 文档