PI-Desktop 安装与首次配置指南：10 分钟在 macOS、Windows、Linux 跑通第一个 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 桌面客户端，基于 Electron + Rust host core + pi Agent Harness 构建。从下载安装到发出第一条编码提示词，全程约 10 分钟；项目与会话留在本机，API Key 存系统钥匙串，无需账号。
开装前自检
| 条件 | 验证方式 |
|---|---|
| Linux 需 glibc ≥ 2.35（Ubuntu 22.04+ / Debian 12+ / Fedora 36+） | 终端执行ldd --version，输出 ≥ 2.35 |
| macOS 确认芯片架构（Apple Silicon 或 Intel） | “关于本机”里查看，决定选 arm64 还是 x64 包 |
| 模型 API 端点可访问 | 保存 Provider 后模型列表能自动拉取即通 |
30 秒选定你的安装包
当前发布线为0.21.x（Early Preview），到项目 Releases 页面取最新版，按下表对号入座：
| 系统 / 架构 | 推荐包 | 备注 |
|---|---|---|
| macOS · Apple Silicon | PI-Desktop-<版本>-arm64.dmg | Developer ID 签名 + Apple 公证 |
| macOS · Intel | PI-Desktop-<版本>-x64.dmg | 另有.zip |
| Windows · x64 | PI-Desktop-Setup-<版本>.exe（NSIS 向导） | 支持应用内更新 |
| Windows · 免安装 | PI-Desktop-Portable-<版本>.zip | 解压直接运行 |
| Linux · x64 / arm64 | .AppImage（首选） | 另有.deb/.rpm/.asar |
macOS、Windows NSIS 版和 Linux AppImage 支持应用内下载安装新版；便携 ZIP 版只弹提示，需手动下载新 ZIP 替换旧目录。
主线三步：下载 → 安装 → 启动验证
- 下载：打开 Releases 页面，下载与上表匹配的包。【成功判据】文件名中的版本号与架构（arm64 / x64 / arm64-linux）和你的系统一致。
- 安装：macOS 把
PI-Desktop.app拖入/Applications；Windows 运行 NSIS 向导（便携版直接解压）；Linux 双击 AppImage，或执行apt install ./xxx.deb/dnf install ./xxx.rpm。【成功判据】桌面、开始菜单或应用列表中出现 PI-Desktop。 - 启动验证：双击启动 PI-Desktop。【成功判据】看到左侧项目/会话栏、中间会话区和底部输入框；首次启动会弹出Get started新手清单，先别关，下一步就靠它。
分平台坑点速查
| 平台 | 易踩坑 | 一句话修复 |
|---|---|---|
| macOS | 个别未公证构建被 Gatekeeper 拦截，提示"已损坏" | xattr -r -d com.apple.quarantine /Applications/PI-Desktop.app后重试 |
| Windows | 怀疑缺 VC++ 运行库；便携版任务栏图标异常 | 宿主已静态链接 CRT，直接启动即可；图标异常时直接运行 ZIP 内的PI-Desktop.exe |
| Linux | 旧系统 glibc 不够，宿主进程加载失败、窗口闪退 | ldd --version确认 ≥ 2.35，不达标只能升级发行版 |
跑通第一个真实任务
- 接入模型：点击清单中的Add an AI provider，深链到Settings → Model configuration，选择 Service、填 Base URL 与 API key、勾选要用的模型，点Save provider。API key 会写入系统钥匙串。
验证：模型列表能从服务端自动拉取、provider 保存成功即通过。
- 打开项目：回主界面点清单中的Open a project folder，选任意本地仓库目录。验证：侧边栏出现该项目，本地文件与命令能力随之解锁。
- 选工作模式：输入框左下角切换——日常改码用Agent直接执行；大型重构用Plan先出方案再执行；只关心结果用Goal锁定验收标准。
- 发送第一条提示词：点清单中的Send your first message，输入例如"给这个项目写一个 README 的目录章节"，点Send。验证：右侧 Work Panel 出现文件改动 diff 与命令输出。
新手清单的规格与交互细节见 docs/spec/04-ux/05-onboarding.md。
至此 PI-Desktop 已正式上线：项目留在本机，模型随时可换。下一步可以试试用Plan模式跑一次大型重构。想从源码构建开发版，环境需 Node.js ≥ 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各平台打包、签名与产物清单见 docs/spec/06-delivery/06-release-runbook.md。
完成度自检
- ☐ 下载并安装了与系统架构匹配的安装包
- ☐Settings → Model configuration已接入至少一个 Provider 并保存
- ☐ 已打开一个本地项目目录
- ☐ 第一条提示词已发送，Work Panel 中看到改动 diff 或命令输出
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
