PI-Desktop 安装完整指南：三个平台 10 分钟从装好到发出第一条提示词-二趣网

PI-Desktop 安装完整指南：三个平台 10 分钟从装好到发出第一条提示词

【免费下载链接】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 安装指南。PI-Desktop 是本地优先的 AI 编程 Agent 桌面客户端，由 Electron 前端、Rust host core 与 pi Agent Harness 构成，把项目、会话、模型和插件收进同一个独立桌面工作区。

装好之后，你能在 macOS、Windows 或 Linux 机器上接入自己的模型、打开一个本地项目，并让第一条编码提示词得到回应，全程约 10 分钟。

开始前三件事值得知道：

数据留在本机：项目与会话都存在本地，API 凭据进系统钥匙串，不要求账号，也没有强制云端中转。
模型可以换：OpenAI、Anthropic、任意 OpenAI 兼容 API，以及 Ollama / LM Studio 这类本地网关都能接。
已有成果可迁：Claude Code、Codex、OpenCode、Pi 的本地会话支持直接导入。

第 1 分钟：确认系统满足 PI-Desktop 安装条件

macOS 与 Windows 没有硬性前置，可以直接跳过这一节。

Linux 有一条硬线：glibc 版本要不低于 2.35，常见对应 Ubuntu 22.04 起、Debian 12 起、Fedora 36 起的发行版。用下面这条命令核对当前版本：

ldd --version

低于这个版本时，内置 Rust 宿主进程会加载失败，表现为窗口闪退或无响应，唯一解法是升级发行版。

⚠️ 这一条只针对 Linux，其他两个平台不受影响。

第 3 分钟：按架构选对安装包并完成安装

先到项目 Releases 页面取最新版本，下载时核对文件名里的版本号与架构标识。

你是 Apple Silicon Mac：选PI-Desktop-<version>-arm64.dmg；Intel Mac 选PI-Desktop-<version>-x64.dmg，同版本另有.zip等价可用。打开 DMG 后把.app拖进 Applications 即可。
你是 Windows：常规场景运行PI-Desktop-Setup-<version>.exe（NSIS 向导）；受管控环境或 U 盘场景选PI-Desktop-Portable-<version>.zip，普通用户权限运行、不弹管理员授权。
你是 Linux：图省事直接双击.AppImage免安装；Ubuntu/Debian 装.deb，Fedora/RHEL 系装.rpm（会落在/opt/PI-Desktop），另有.asar可选。

💡 更新行为有差别：macOS、Windows 的 NSIS 安装版与 Linux 的 AppImage 都支持应用内直接装新版；便携 ZIP 只给提示，需要手动换文件。

第 4 分钟：启动应用并核对主界面

双击启动PI-Desktop。左侧能看到项目/会话列表、中间是会话区、底部有输入框，就说明安装成功了。

首次启动时主界面会显示 "Get started" 清单，具体规格见 docs/spec/04-ux/05-onboarding.md。接下来两节的动作都沿着这份清单推进。

第 5 分钟：接入模型并把 API Key 存入系统钥匙串

点击清单里的 "Add an AI provider"，界面会直接带你到 Settings → Model configuration 页面。

挑好 Provider（或任意兼容 API）并填好端点与凭据，凭据最终存进系统钥匙串。保存后确认页面上模型列表显示正常，这一步就算完成。

第 8 分钟：打开项目并发出第一条提示词

回主界面点击 "Open a project folder"，指向任意一个本地仓库目录，文件读取与命令执行能力会随项目一起解锁。

输入框上方有三种模式：Agent mode 直接执行，适合日常改码；Plan 先给方案再动手，适合大型重构；Goal 只锁验收标准、路径交给 agent，适合只关心结果的任务。

输入一条提示词，例如"给这个项目写一个 README 的目录章节"，发送后，文件 diff 与命令输出会出现在右侧 Work Panel。

卡住了：按现象定位并一步修复

macOS 报"已损坏 / 无法打开"：个别渠道的构建未走公证，带着隔离属性，首次打开被 Gatekeeper 拦截。终端执行一条命令清掉隔离属性后重试：

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

Linux 启动即闪退或窗口无响应：基本是 glibc 低于 2.35。ldd --version复核一遍，不达标就升级发行版，没有绕法。

Windows 上怀疑缺 VC++ 运行库：不需要装。宿主进程pi-desktop-host-core.exe是静态链接 MSVC CRT 的，干净系统也能直接起本地服务。便携版任务栏图标异常时，确认你运行的是 ZIP 内的PI-Desktop.exe，而非目录外的复制件。

输入框提示 "Open a project to reference files"：项目目录没打开，本地工具被锁。从侧边栏的 Add project 入口选一个本地目录即可。

便携版应用内更新不生效：便携 ZIP 走的是手动更新。去 Releases 拿新 ZIP，覆盖解压到原位置。

从源码构建一个开发版

依赖：Node.js 22.19 或更高、pnpm 10 或更高、稳定版 Rust 工具链。克隆仓库（git clone https://gitcode.com/GitHub_Trending/pid/PI-Desktop）之后，依次完成依赖安装、host-core 构建与前端构建，最后用pnpm dev拉起开发版；环境细节见 README.md 的 For Developers 一节。

3 个问题确认安装到位

安装包与系统架构一致，Linux 用户复核过 glibc 版本不低于 2.35？
应用可正常启动，Settings → Model configuration 已接入至少一个 provider，并且打开了本地项目目录？
第一条提示词得到了回应，Work Panel 里能看到文件改动 diff？

三个都答"是"，这个本地优先的 AI 编程工作台就正式可用了。下一步可以试一次 Plan 模式的大型重构。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析