桌面版

本页介绍如何安装桌面应用、它和 Web 版有什么不同，以及如何更新和退出。

桌面应用叫 pi。它在自己的窗口里显示同一个工作台，并且自带 Node.js 和 Pi，所以你不用另外安装这两样。模型凭据、Git 和 SSH 配置，以及项目自己的工具链，仍然需要你自己准备。

测试版

桌面版以未签名的测试预发布版形式发布，面向愿意自己校验下载文件的人。macOS 版本带有 ad-hoc 签名，但没有 Apple 公证，所以 Gatekeeper 可能会拦截；Windows 和 Linux 版本没有签名。如果你不想接受这些，请使用 Web 启动器，功能是一样的。

可以下载什么

在 GitHub Releases 页面找到最新的 desktop-v… 预发布版。每个版本都会列出下面这些平台的安装包。不包含 Windows ARM 和 Linux ARM。

平台	文件
macOS，Apple 芯片	…-mac-arm64.dmg
macOS，Intel	…-mac-x64.dmg
Windows，x64	…-win-x64.exe
Linux，x64	…-linux-x86_64.AppImage

请从同一个版本里下载安装包和名为 SHA256SUMS 的文件。不要使用别人转发给你的安装包，也不要使用源码压缩包。

校验下载的文件

把安装包的校验和与 SHA256SUMS 里对应的那一行比对。

shasum -a 256 ~/Downloads/pi-*-mac-arm64.dmg

Linux 上用 sha256sum；PowerShell 里用 Get-FileHash <文件> -Algorithm SHA256。如果不一致，请停下，不要安装。校验和只能证明这个文件就是当初发布的那个，不能证明软件本身是安全的。

安装

macOS

1. 先退出旧版桌面应用；如果它询问，也一并停止它启动的后台服务。不要删除 ~/.pi。

2. 打开 DMG，把 pi.app 拖进 应用程序。旧的 Pi Webapp.app 不会被新名字覆盖，请更新你的 Dock 快捷方式。

3. 校验应用的签名：

   codesign --verify --deep --strict --verbose=2 "/Applications/pi.app"

   如果这一步失败，请停下。不要为了让报错消失而重新签名。

4. 打开应用。如果 macOS 拦截了它，请到 系统设置 → 隐私与安全性 里找 仍要打开，但前提是你已经校验了来源、校验和与签名，并决定信任这个测试版。

5. 如果下载隔离仍然阻止启动，在完成上面的校验后，你可以只对这一个应用移除隔离标记：

   codesign --verify --deep --strict --verbose=2 "/Applications/pi.app" &&
   xattr -dr com.apple.quarantine "/Applications/pi.app"

   这只会让 macOS 对这个应用跳过下载检查，它不是 Apple 的认证。永远不要全局关闭 Gatekeeper 或 SIP。

Windows

运行 .exe 安装程序。因为它没有签名，Windows 可能提示发布者未知。只有校验和一致时才继续。

Linux

让 AppImage 可执行，然后运行：

chmod +x pi-*-linux-x86_64.AppImage
./pi-*-linux-x86_64.AppImage

如果系统不支持 FUSE，请运行 ./pi-*-linux-x86_64.AppImage --appimage-extract-and-run。

第一次启动后确认版本：在 macOS 上选 pi → 关于 pi。它会显示外壳版本、桌面构建号和正在运行的 pi-webapp 版本。然后按快速开始 → 连接模型继续。

它和 Web 启动器有什么不同

• 数据相同。 桌面应用使用和 npx pi-webapp、Pi 终端相同的 Pi 数据目录（~/.pi/agent），所以你的会话、模型和凭据都是共享的。
• 复用已在运行的服务。 如果已经有兼容的 pi-webapp 服务在运行（比如由 npx pi-webapp 启动的），桌面窗口会连接它，而不是再启动一个。否则它会启动自己的服务。
• 自带运行时。 它运行自己附带的 Node.js 和 Pi。被复用的服务则保留它自己的 Pi 版本。
• 不需要浏览器，不过 窗口 → 在浏览器中打开 可以在你的浏览器里打开同一个服务。

桌面端的菜单是中文的。你可能会用到的有：

菜单项	作用
pi → 关于 pi	显示外壳版本、构建号、运行中的版本、应用位置，以及服务是不是由它自己持有
pi → 检查桌面更新…	检查桌面应用的更新
pi → 取消桌面更新下载	取消更新下载
pi → 安全切换到当前桌面启动器…	把正在运行的服务安全切换到当前桌面的启动器（见更新）
pi → 退出…	退出（Cmd/Ctrl+Q）
窗口 → 重新加载界面	重新加载窗口（Cmd/Ctrl+R）
窗口 → 在浏览器中打开	在你的浏览器里打开这个服务
窗口 → 打开日志目录	打开存放服务日志的文件夹

退出

退出时会询问 是否同时停止后台服务？：

按钮	会发生什么
取消	取消，留在应用里。
仅关窗口，后台继续	只关闭窗口。服务、正在运行的会话和终端继续运行。之后可以用 pi-webapp stop 停止它，或者重新打开应用。
停止服务并退出	停止服务并退出。这会结束所有正在运行的会话和终端，也会断开所有正在使用该服务的浏览器。

如果应用连接的是一个不是它启动的服务，退出时会提示 当前连接的是已有服务，关闭桌面不会停止它，只会关闭窗口。

更新桌面应用

外壳和它里面的 pi-webapp 包是分开更新的：

• 业务包（pi-webapp 的版本）：在 Pi 设置 → 通用设置 → 应用更新 里更新，与更新里完全一样。这不会替换应用本身。
• 外壳（安装好的应用）：pi → 检查桌面更新…。在 macOS Apple 芯片上，它会下载并校验新版本，再交给 Finder 让你手动安装；它从不会替你安装 ad-hoc 签名的构建。其他平台上，它会打开 Releases 页面，由你选择适合自己系统的安装包。

替换之前，请先退出旧应用，并停止它持有的后台服务。你还在用的 Web 服务则保持运行。

由旧版桌面启动的共享服务，会保留那个旧版桌面的能力。如果 Pi 设置 → 通用设置 提示安全交接只在更新的桌面版里可用，请先在 稳定版 上更新业务包，再使用 pi → 安全切换到当前桌面启动器…。交接会等待会话空闲、终端关闭和图稿保存确认，保留本地地址，并且绝不会强制停止旧服务。

反馈问题

请附上你的操作系统和芯片、关于 pi 里的桌面构建号、你做了什么，以及完整的报错。不要附上访问令牌、auth.json、私钥和完整的本地路径。