PI-Desktop 安装教程：10 分钟装好并跑通第一个 AI 编程任务

【免费下载链接】PI-DesktopLocal-first AI coding agent desktop: Electron + Rust host core + pi Agent Harness + user-installable plugins项目地址: https://gitcode.com/GitHub_Trending/pid/PI-Desktop

PI-Desktop 是本地优先的 AI 编程 Agent 桌面客户端，把项目、会话、模型和插件收进同一个独立工作区，API 凭据直接进系统钥匙串，无账号、无强制云端中转。照这篇教程，你能在 macOS、Windows 或 Linux 上完成安装并发出第一条编码任务，全程约 10 分钟。

动手前：5 秒确认 Linux glibc 是否达标

先对齐各平台的最低要求：macOS 支持 Apple Silicon 与 Intel x64；Windows 为 x64；Linux 为 x64 或 arm64，且glibc 必须 ≥ 2.35（即 Ubuntu 22.04+、Debian 12+、Fedora 36+）。macOS 和 Windows 用户没有额外依赖，直接跳到下一节。

Linux 用户执行这一条命令自检：

ldd --version

⚠️ 判断分支：第一行输出2.35 及以上 → 继续；低于 2.35 → 内置 Rust 宿主进程无法加载（症状是窗口闪退或无响应），必须先升级发行版，没有绕法。

跑起来：从下载到启动只要 3 步

1. 下载：打开项目 Releases 页面，取当前 0.21.x 发布线的最新包，按系统挑对应架构——macOS 是.dmg（.zip亦可），Windows 是安装程序或便携 zip，Linux 首选.AppImage，.deb/.rpm也随包提供。
2. 安装：macOS 把 DMG 里的应用拖入Applications；Windows 安装版跑一遍 NSIS 向导，便携版解压后直接双击PI-Desktop.exe，普通用户权限即可；Linux 直接运行 AppImage，或按发行版走包管理器安装。
3. 启动验证：双击启动PI-Desktop。看到左侧项目/会话栏、中间会话区、底部输入框，就说明启动成功了；首次启动还会弹出Get started新手清单，下一节就是照着它走完。

💡 macOS、Windows 安装版和 Linux AppImage 支持应用内下载安装新版；Windows 便携 zip 只提示，需手动下载新包替换旧目录。各平台产物细节见 发布运行手册。

第一个任务：接入模型并发出第一条编码提示词

1. 接入模型：点清单里的Add an AI provider，会直达Settings → Model configuration。选 OpenAI、Anthropic 或任意 OpenAI 兼容端点（Ollama、LM Studio 这类本地网关也行），填Base URL与API key，点Save provider。凭据写入系统钥匙串、请求直连你自己配置的 Provider，这是本地优先设计的入口。成功标志：新 Provider 下能看到模型列表。

2. 打开项目：回主界面点Open a project folder，选一个本地仓库。为什么：文件读取与命令执行能力只有开了项目才解锁，未开项目时输入框会提示 "Open a project to reference files"。成功标志：左侧项目栏出现该项目，右侧Work Panel能浏览项目文件。

3. 选工作模式：输入框上方切换——日常改码用Agent mode直接执行；大型重构用Plan先出方案再执行；锁定验收标准用Goal。

4. 发第一条提示词：点清单里的Send your first message，输入一个真实小任务，例如"给这个项目写一个 README 的目录章节"，按Send。成功标志：会话区开始流式输出，右侧 Work Panel 出现文件改动 diff 与命令输出。清单步骤详见 首次运行清单规格。

出问题怎么办：5 个高频场景一步修复

1. 现象：macOS 提示"已损坏/无法打开"。原因：个别渠道构建未走公证，被 Gatekeeper 隔离属性拦截。修复：终端执行后重试。

xattr -r -d com.apple.quarantine /Applications/PI-Desktop.app

2. 现象：Linux 启动即闪退或窗口无响应。原因：glibc 低于 2.35。修复：ldd --version确认版本，不达标只能升级发行版。
3. 现象：Windows 怀疑缺 VC++ 运行库。原因：不需要——内置pi-desktop-host-core.exe已静态链接 MSVC CRT。修复：忽略，干净系统直接启动即可。
4. 现象：输入框提示 "Open a project to reference files"。原因：没打开项目目录，本地工具未解锁。修复：侧边栏Add project选一个本地目录。
5. 现象：Windows 便携版应用内更新提示点了没反应。原因：便携 ZIP 走手动更新。修复：下载新 ZIP 解压替换旧目录。

收尾：装完即上岗，下一步跑一次 Plan 模式

走到这里，你的本地优先 AI 编程工作台已经上线：项目留在本机，模型随时可换。建议下一个任务用Plan模式跑一次大型重构，感受"先方案、后执行"的审批边界；想深入的话，备齐Node ≥ 22.19、pnpm ≥ 10、稳定版 Rust 工具链，一组命令即可跑起源码开发版：

git clone https://gitcode.com/GitHub_Trending/pid/PI-Desktop cd PI-Desktop pnpm install cargo build -p host-core pnpm build:js pnpm dev

【免费下载链接】PI-DesktopLocal-first AI coding agent desktop: Electron + Rust host core + pi Agent Harness + user-installable plugins项目地址: https://gitcode.com/GitHub_Trending/pid/PI-Desktop