DeepSeek 终端助手接入

Pi（pi-mono）接入

2 分钟阅读

接入 Pi

Pi（pi-mono）是面向追求高度自定义的开发者打造的极简且高度可扩展的终端编码框架，核心优势在于采用 TypeScript 扩展体系，支持自定义技能、提示模板、主题，可完全适配你的个性化工作流，同时支持树状会话结构（方便回溯不同的解决方案分支），内置 15+ 模型供应商，是终端重度开发者的理想编码助手。

接入 DeepSeek V4 后，可充分利用 DeepSeek 强推理能力、百万上下文窗口、低延迟 Flash 版本的特性，满足从简单代码生成到复杂架构设计的全场景编码需求，同时 Pi 的高扩展性可让你基于 DeepSeek 的能力定制专属的编码工作流。

本教程将带你完成 Pi 的安装、DeepSeek 供应商配置、模型选择全流程，看完即可在 Pi 中流畅使用 DeepSeek 模型进行编码工作。

1. 安装 Pi

操作目的：完成 Pi 运行环境部署，获取 pi 可执行命令。

安装 Node.js。操作说明：Pi 的 npm 安装方式依赖 Node.js 运行环境，建议下载 LTS 版本，稳定性更高，安装完成后执行 node -v 确认安装成功。
在命令行界面，执行以下命令安装 Pi：

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

操作说明：全局安装 Pi 编码 Agent 包，将 pi 命令添加到系统 PATH 中。若安装时提示权限不足，Linux/macOS 用户可添加 sudo，或配置 npm 全局安装目录到用户目录下避免权限问题；Windows 用户需以管理员身份运行 PowerShell 执行安装命令。

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

pi --version

注意： Linux / macOS 用户也可以通过官方脚本安装（无需 Node.js 环境）：
curl -fsSL https://pi.dev/install.sh | sh
该脚本会自动检测系统架构，下载原生二进制版本，适合没有 Node.js 环境的用户。

2. 配置 DeepSeek 供应商

操作目的：通过自定义模型配置文件，添加 DeepSeek 作为新的模型供应商，确保 DeepSeek V4 的思考模式、工具调用等功能正常使用。 Pi 通过 models.json 支持自定义供应商，配置文件路径如下：

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

首先确认配置目录存在，若不存在可手动创建：Linux/macOS 执行 mkdir -p ~/.pi/agent，Windows 手动创建对应目录。写入以下配置（完全保留原有参数，无修改）：

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai-completions",
      "apiKey": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 1.74,
            "output": 3.48,
            "cacheRead": 0.145,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        },
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 0.14,
            "output": 0.28,
            "cacheRead": 0.028,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        }
      ]
    }
  }
}

配置字段说明：

baseUrl：DeepSeek OpenAI 兼容接口根地址，无需添加 /v1 后缀。
api：指定使用 OpenAI completions 协议适配 DeepSeek 接口。
apiKey：通过环境变量读取 API Key，避免明文存储泄露。
contextWindow/maxTokens：DeepSeek V4 官方参数，支持百万级上下文，可满足大型项目全量代码上传需求。
cost：模型计费参数，Pi 会基于该参数统计你的调用成本，方便费用管控。
compat：兼容配置，requiresReasoningContentOnAssistantMessages 要求保留 DeepSeek 返回的思考内容，避免工具调用报错；thinkingFormat 指定使用 DeepSeek 原生思考格式，确保思考内容正确解析；reasoningEffortMap 将 Pi 的多档位推理强度映射为 DeepSeek 支持的两档，避免参数错误。

其中 API Key 在 DeepSeek 开放平台获取。

设置环境变量：操作目的：配置 DEEPSEEK_API_KEY 环境变量，供 Pi 读取用于接口认证。 Linux / Mac 用户：

export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

持久化提示：可将上述命令写入 ~/.bashrc 或 ~/.zshrc 配置文件中，执行 source ~/.zshrc 立即生效，无需每次打开终端重复配置。

Windows 用户：

$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

持久化提示：可在系统属性→环境变量中添加 DEEPSEEK_API_KEY 系统变量，重启终端后永久生效。

环境变量验证：Linux/macOS 执行 echo $DEEPSEEK_API_KEY，Windows 执行 echo $env:DEEPSEEK_API_KEY，确认输出为正确的 API Key。

3. 运行并选择模型

操作目的：启动 Pi 并选择 DeepSeek 模型，自动加载项目上下文开始编码。

cd /path/to/my-project
pi

操作说明：进入项目目录后启动 Pi，会自动扫描当前目录的所有代码文件作为上下文，生成的代码会自动适配项目的技术栈与编码规范，预期结果为进入 Pi 交互界面，显示欢迎语与命令提示。

输入 /model 打开模型切换器。
选择 deepseek，然后选择 DeepSeek-V4-Pro 或 DeepSeek-V4-Flash。
开始使用你的极简终端编码框架。

使用技巧与最佳实践

树状会话结构下，可使用 /branch 命令新建会话分支，尝试不同的解决方案，不会覆盖原有对话内容，适合多方案对比场景。
使用 /save <名称> 命令保存当前会话，后续可通过 /load <名称> 恢复，方便长期处理大型项目的迭代需求。
日常编码使用 DeepSeek-V4-Flash 控制成本，处理复杂任务时切换为 DeepSeek-V4-Pro 提升准确率。

更多配置选项请参阅 Pi 模型文档。

常见问题（FAQ）

配置完成后找不到 DeepSeek 模型？排查步骤：首先检查 models.json 文件路径是否正确，其次使用在线 JSON 校验工具确认 JSON 语法正确，最后检查文件权限允许当前用户读取。
调用时提示 reasoning_content 相关错误？排查步骤：检查 compat 字段配置是否完整，无拼写错误，特别是 requiresReasoningContentOnAssistantMessages 和 thinkingFormat 字段是否正确配置。
调用时返回 401 未授权？排查步骤：检查 DEEPSEEK_API_KEY 环境变量是否正确设置，确认 API Key 状态正常且有可用余额。

参考资料

上一页Claude Code 接入下一页 Crush 接入