Pi Agent：国内 API 上手

Pi 是一个在终端里运行的编程助手，可以读取和修改项目文件。本课使用 Windows PowerShell，安装 Pi 0.85.1 并接入 DeepSeek，最后让它整理一份 README；需要 Node.js ≥22.19.0 和 Git for Windows。

安装 Pi

Pi 可以使用自己的 DeepSeek API Key，无需先购买海外聊天订阅。下面通过 CC Switch 添加供应商。软件包和模型服务需要分别联网，国内网络下能否顺利下载还取决于 npm、GitHub 等地址的连通情况。

国内读者可以先用 npm 镜像，下面保留 npm 已发布的 0.85.1 版本。安装 Node.js 和 Git for Windows 后，重新打开 PowerShell：

node --version
npm --version
git --version
Test-Path 'C:\Program Files\Git\bin\bash.exe'

前三条会显示版本号，最后一条在默认 Git Bash 路径存在时返回 True。Pi 在 Windows 默认使用 Git Bash。

下面创建独立的练习目录，再安装 Pi：

$work = Join-Path $HOME 'agent-atlas-pi-lab'
New-Item -ItemType Directory -Force -Path $work | Out-Null
Set-Location $work
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.85.1 --registry=https://registry.npmmirror.com
pi --version

出现版本号就说明 Pi 已安装好。--ignore-scripts 会禁用依赖安装脚本，是官方安装命令中的选项。如果 PowerShell 拦截 npm.ps1，改用同目录的 npm.cmd。

这条 --registry 只对本次命令生效，不修改 npm 全局配置。镜像可能有同步延迟；遇到 ETARGET，先核对包名和版本，官方源可达时把地址换成 https://registry.npmjs.org 重试。镜像不代理 GitHub、官方安装脚本或模型 API，也不代装 Node.js、Git；证书报错时保留 SSL 校验，检查网络和系统证书。

**macOS / Linux：**使用相同 npm 安装命令；创建目录改用 mkdir -p ~/agent-atlas-pi-lab，再 cd ~/agent-atlas-pi-lab。不要照抄 PowerShell 的 $env: 语法。

获取 DeepSeek API Key

还没有 Key 时，先按API 与配置的完整申请流程准备并保管；准备好后继续下面的 Pi 地址、协议和模型设置。不要把 Key 放进项目文件、截图或 Git。

CC Switch v3.20.3 已支持 Pi 的供应商管理。先按CC Switch 配置教程完成下载、备份、选择应用、添加供应商、填写 Key 和启用，再确认 Pi 特有差异：当前应用是 Pi，不要选 Claude Code 或 Codex；该 Pi 预设使用 https://api.deepseek.com/v1 与 OpenAI Chat Completions，不是 Claude 的接口配置。

这个版本的预设仍列出 deepseek-v4-flash；DeepSeek 文档目前建议 deepseek-flash，旧名称作为兼容别名处理。不要把预设里的名称误当成最新型号。完成 CC Switch 启用后，回到练习目录重新启动 pi，输入 /model，选择供应商及模型。

CC Switch 的“启用”只是把供应商加入 Pi 配置，不会替你切换当前模型。在 Pi 里选完模型后，再进行下面的文件练习。卡片里有密钥时，不要把截图发到公开位置。

如果列表里没有新供应商，检查 CC Switch 是否选中了 Pi、卡片是否已启用，以及 Pi 是否已重新启动。不要在另一个工具页重复添加同一配置。

已经用过 Pi 登录怎么办？

CC Switch 不管理 Pi 的 /login 和 auth.json。以前保存的登录信息仍由 Pi 管理，不会自动变成 CC Switch 卡片。想继续使用 Pi 自带的 DeepSeek 入口，也可以在 Pi 输入 /login、填写 Key，再用 /model 选择；这条路线无需手改配置文件。

简短验证

完成模型选择后，在不含隐私的练习目录只读检查 README，确认 Pi 引用了文件且没有写入；完整的读取、创建、检查和定向修改流程见第一项任务。

常见问题

现象	先做什么
找不到 pi	重新开终端，检查 npm 全局命令目录与 PATH
Bash 启动失败	检查 Git Bash；非默认安装路径按官方 shellPath 配置
能聊天但工具失败	记录模型、版本、脱敏错误；检查工具参数／模型目录兼容性
下载超时	区分 npm 下载与模型端点；镜像同步延迟时核对版本，官方源可达后再回退

401、额度和限流按API 与配置的通用排错表检查。

结束先退出 Pi；只移除本次练习文件。撤销本次模型配置时，先在 Pi 切回原模型，再从 CC Switch 移除这张供应商卡片的启用状态。需要恢复文件时使用配置前的备份，不删除整个 .pi 目录。卸载 CLI 可执行 npm uninstall -g @earendil-works/pi-coding-agent，平台 Key 和历史会话会保留。

添加其他模型

更换供应商时，按CC Switch 配置教程添加配置；然后检查 Pi 特有设置：准备服务地址、模型 ID 和对应地域的密钥，确认协议与入口匹配。普通 API 与 Coding Plan 可能使用不同入口，保留原来的可用供应商，方便随时切回。

切换模型后，按上面的简短验证确认 /model 和工具调用；出现错误时切回原模型，保留错误码和模型 ID 便于排查。

向维护者提问时，附版本号、模型 ID、错误码和发生步骤即可。截图遮住密钥和个人信息，不要上传 auth 文件；密钥已经泄露时，到平台撤销。

下一步与参考资料

进入 Pi Skills 与原生扩展。其他国内模型也要区分地域入口、API 协议和 Coding Plan，内置供应商名称不是全部套餐兼容保证。

资料核对：2026-09-15；镜像包元数据已查询，安装、命令和 API 尚未实机测试。