夜雨聆风在对 4 款热门 Agent 框架（Pi Agent, Prime Agent, Deep Agents, Hermes Agent）在 30 个复杂 Agent 任务上进行了实测后，结果如下：
🏆 Pi Agent 为最大赢家：不仅通过率最高，速度最快，而且成本最低！
📊 核心数据对比：1️⃣ Pi Agent• 通过率：66.7% (20/30) • 中位成本：$0.012 / 任务 • 中位耗时：132s2️⃣ Prime Agent• 通过率：62.5% (15/24) • 中位成本：$0.045 / 任务 • 中位耗时：242s3️⃣ Deep Agents (LangChain)• 通过率：53.3% (16/30) • 中位成本：$0.018 / 任务 • 中位耗时：187s4️⃣ Hermes Agent• 通过率：50.0% (15/30) • 中位成本：$0.017 / 任务 • 中位耗时：176s
在模型相同的前提下，选对 Agent 调度框架可带来 50% → 66.7% 的成功率提升，且成本能降低近 4 倍。这也是给今天大家推荐的Pi Agent的原因。
Pi Agent 本身是一个强大的 AI Agent 工具包，它包含统一的大模型 API、Agent 运行环境、终端用户界面以及一个可自我扩展的交互式编程助手 。
第一部分：Pi Agent 安装教程
环境准备
在开始之前，请确保你的系统中已安装 Node.js 和 npm（建议使用 Node.js 18 或 20 以上的 LTS 版本）。
方法一：从源码编译安装（推荐）
如果你想体验最新功能或进行本地开发，官方推荐通过源码进行构建：
- 克隆代码仓库 打开终端，将项目克隆到本地并进入目录：
1 2 git clone https://github.com/earendil-works/pi.gitcd pi - 安装依赖 为了保证软件供应链安全，官方推荐在安装依赖时加上
--ignore-scripts，以防运行未受信任的生命周期脚本：
1 npm install --ignore-scripts - 构建项目 这一步会获取最新的模型数据目录，并编译所有的 monorepo 子包（如核心层、AI层、TUI 等）：
1 npm run build (注：如果在离线或网络不佳的环境下，可以使用 npm run build:offline 利用本地缓存的模型数据进行构建。)
- 运行与测试 构建完成后，你可以直接使用自带的脚本在任意目录启动 Pi Agent：
Linux / macOS 运行: ./pi-test.shWindows 运行: ./pi-test.bat或./pi-test.ps1
方法二：通过 NPM 安装 CLI 工具
如果你只想作为普通用户使用它的编程助手，可以直接全局安装其发布的 npm 包：
1 npm install -g @earendil-works/pi-coding-agent 安装完成后，在终端直接输入 pi 即可启动。
第二部分：接入 DeepSeek API 教程
Pi 包含了一个统一的多模型 API 包 (@earendil-works/pi-ai)。由于 DeepSeek 官方提供了完全兼容 OpenAI 格式的 API 接口，我们可以通过环境变量覆盖的方式，非常无缝地将 Pi Agent 接入 DeepSeek。
1. 获取 API 密钥
前往 DeepSeek 开放平台，登录并生成你的专属 API Key（通常以 sk- 开头）。
2. 配置环境变量
你需要将 OpenAI 的默认调用地址重定向到 DeepSeek 的服务端点。在终端中配置以下环境变量：
在 Linux / macOS 中：
1 2 3 4 5 # 设置 DeepSeek 的 API Keyexport OPENAI_API_KEY="sk-你的deepseek-api-key"# 将基础 URL 指向 DeepSeek 的 API 接口export OPENAI_BASE_URL="https://api.deepseek.com/v1" 在 Windows (PowerShell) 中：
1 2 $env:OPENAI_API_KEY="sk-你的deepseek-api-key"$env:OPENAI_BASE_URL="https://api.deepseek.com/v1" (注意：如果你将环境变量写入了 ~/.bashrc 或 ~/.zshrc，请记得 source 使其永久生效。)
3. 指定 DeepSeek 模型并运行
DeepSeek 主要有两个模型，推荐在代码辅助场景下使用 deepseek-coder（或者最新一代的 deepseek-chat）。
在启动 Pi 时，通过 --model 参数明确告诉它使用该模型：
如果你是全局安装：
1 pi --model deepseek-coder 如果你是从源码运行：
1 ./pi-test.sh --model deepseek-coder 4. 验证运行
进入 Pi 的 TUI（终端用户界面）后，你可以尝试给它下达一个简单的指令，例如：
“写一个 Python 的快速排序算法并保存为 qsort.py”
如果 Pi Agent 能够正常思考、调用工具（写入文件）并给出回复，说明 DeepSeek API 已经成功接入并完美驱动了 Agent 循环！
💡 安全建议： 根据 Pi 官方的声明，Pi Agent 默认以当前用户权限运行。因为 DeepSeek Coder 具备极强的代码编写和执行能力，如果让它操作复杂的本地工程，建议按照官方文档在 Docker 容器或 OpenShell 沙盒中运行 Pi，以避免 Agent 误删文件或破坏宿主机环境。
第三部分：为 Pi Agent 添加视觉能力 (基于 pi-deepseek-vision)
由于 DeepSeek 的核心模型通常是纯文本模型，默认无法处理图像（多模态）输入，但可以通过安装开源扩展 pi-deepseek-vision 来实现。
它的工作原理： 采用“视觉预处理”代理机制。它会调用 Pi Agent 中已配置好的其他视觉模型（比如 GPT-4o 或 Claude 3.5 Sonnet）作为 DeepSeek 的“眼睛”。该扩展会拦截你发送的图片，让视觉模型将其分析并转化为详细的纯文本描述，随后将带有纯文本描述的请求无缝转发给 DeepSeek。整个过程对 DeepSeek 而言是完全纯文本的。
1. 安装 Vision 扩展
在终端中，你可以直接使用 Pi 的内置扩展安装命令，从 GitHub 拉取并安装该项目：
1 pi install git:github.com/sanvibyfish/pi-deepseek-vision (注：如果你的网络环境受限，也可以将代码克隆到本地，然后运行 pi install /绝对路径/到/pi-deepseek-vision)
2. 配置视觉预处理模型
该扩展通过读取固定的全局 JSON 文件来运行。你需要告诉它“用哪个模型作为眼睛”以及“哪些 DeepSeek 模型可以触发预处理”。
首先，创建配置目录（如果尚未存在）：
1 mkdir -p ~/.pi/agent 然后，创建并编辑配置文件 ~/.pi/agent/deepseek-vision.json，填入以下内容：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "visionModel": { "provider": "openai", "id": "gpt-4o" }, "targetModels": [ "deepseek-coder", "deepseek-chat", "deepseek-v4-pro", "deepseek-v4-flash" ], "language": "auto", "maxAnalysisChars": 20000, "cache": { "capacity": 128, "ttlSeconds": 900 }} 关键配置项说明：
visionModel: 指定预处理视觉模型的provider（提供商）和id（模型名称）。前提是你必须已经在 Pi 中配置好了该提供商（如 OpenAI、Anthropic）的 API Key，且该模型原生支持图像输入。targetModels: 指定需要触发此扩展的目标模型列表。请确保你当前使用的 DeepSeek 模型名（如deepseek-coder）包含在这个数组中。language: 图像分析结果的语言。设为auto会自动跟随上下文的对话语言（如输出中文分析）。cache: 内置了 LRU（最近最少使用）缓存功能。同一张图在有效时间内不会被重复调用 API 分析，节省 Token 和时间。
3. 重载配置与使用
保存配置文件后，回到正在运行的 Pi Agent 终端交互界面 ，输入以下命令使配置生效：
1 /reload 如何使用：
配置成功后，操作与原生多模态大模型毫无差异。在使用 DeepSeek 模型的对话中，你可以直接向终端拖入图片，或让 Pi 读取本地图片：
“读取 /path/to/screenshot.png，对比这张设计稿，帮我用 React 和 TailwindCSS 写出对应的前端组件代码。”
运行表现：
扩展会触发，Pi 界面会提示当前正在分析图像的数量。 原始图片会被替换为形如 [图片 1 — 由视觉模型分析：这是一个包含顶部导航和双列瀑布流布局的电商页面...]的纯文本。纯文本被安全地传递给 DeepSeek 进行逻辑处理和代码生成。如果视觉处理环节失败，它会执行“安全阻断”（Fail-closed），绝不会将未处理的乱码或原始图像强行发送给不支持图像的 DeepSeek，从而保证工作流的稳定性。
