SurgeCode 赞助 · Sponsored by SurgeCode · OpenAI / Claude compatible API access
左:新建会话页,列出等你回复的会话和未合并的 PR(Draft / Open / Checks failing / Ready to merge…) · 中:Code 模式修 bug,右侧是 Diff · 右:Work 模式整理收件箱,移动文件前先问你(均为离线演示模型)
## 简介 界面仿照 Claude desktop,有 **Work** 和 **Code** 两种模式。界面用 React + TypeScript + [shadcn/ui](https://ui.shadcn.com) 构建;agent 直接复用 **pi SDK**(`createAgentSession`),所有会话跑在一个常驻的 Electron utilityProcess 里。Claude 风格界面里 pi 没有的能力(权限模式、计划审批、待办、子 agent、后台任务)由内置的 desktop-kit 扩展补上。 | | 做什么 | |---|---| | 💻 **Code** | 在项目的独立 git worktree 里写代码,配有 diff、PR / CI 状态、终端和预览。 | | 🗂️ **Work** | 在你选的文件夹里做知识类工作,比如整理文件、写文档、做简报;不选文件夹时会新建一个临时工作区。右侧面板显示进度、Pi Desktop 生成的文件和任务上下文。 | ## 功能一览 - 🔐 **权限模式**:Auto / Ask / Accept edits / Plan / Bypass,高风险命令始终先问。 - 🌳 **独立 worktree**:每个 Code 会话一个分支,互不干扰,删会话时一并清理。 - 🔀 **PR 条与 CI 自动化**:host 内监听 PR,CI 变红自动修、可合并时自动合并。 - 🧠 **后台小请求**:会话命名、下一句输入预测,不占会话上下文。 - 🤖 **子 agent 与后台任务**:`explore` / `plan` 内置,自定义身份放 `~/.pi-desktop/agents/`。 - ⏰ **定时任务**:手动 / 每小时 / 每天 / 工作日 / 每周 / 一次性 / cron。 - 🧩 **Customize**:技能、MCP、插件、提示模板,读写 pi 自己的文件,和 CLI 一致。 - 🌐 **远程**:遥控另一台电脑上的 Pi Desktop 或装了 `pi-remote` 的 pi 命令行。 - 📎 **附件与引用**:粘贴截图、拖入文件,Diff / 文件正文里选代码加评论。 ## 快速开始 正常使用不用构建: - macOS:`brew tap liuscraft/tap && brew install --cask pi-desktop`(升级用 `brew upgrade --cask pi-desktop`)。 - Windows:[Releases](https://github.com/LiusCraft/pi-desktop/releases/latest) 下载并运行 `Pi-Desktop-<版本>-win-x64-setup.exe`。 - Linux x86_64:从同一 Release 下载 `Pi-Desktop-<版本>-linux-x86_64.AppImage`,赋予执行权限后直接运行(见 [Linux](#linux))。 从源码跑: ```bash npm install npm run dev # electron-vite 开发模式(界面热更新) npm run build && npm start # 构建后运行 npm run build && npm run demo # 打开内置演示项目,默认使用离线演示模型(仅未打包运行可用) ``` - 需要 Node 22.12+(构建与测试用);运行时 agent 跑在 Electron 自带的 Node 上。 - 想和已安装的 Pi Desktop 同时运行:用 `make dev` / `make demo`,它们各自使用 `~/.pi-desktop-dev` / `~/.pi-desktop-demo` 和对应的 Electron profile;直接 `npm run dev` / `npm run demo` 仍用默认目录(会与已安装版抢单实例锁)。两者仍共用当前目录的 `out/`,同时跑请换一个 worktree。 - 离线 demo 只在未打包运行(`npm run dev` / `npm run demo` / 测试)时启用,打包产物不含 `demo/` 目录也不注册 demo 模型。启动时会把 `demo/todo-app`(Code 演示项目)和 `demo/work-workspace`(Work 演示文件夹:收件箱、日程、待办)复制到 `~/.pi-desktop/demo`。不配置任何 API Key 也能用 **Demo (offline)** 模型体验完整流程。 - 接真实模型:打开设置(`Ctrl/⌘+,`)→ **模型管理**,和 pi CLI 用同一套配置: - **账号登录**:Anthropic(Claude Pro/Max)、OpenAI(ChatGPT)、GitHub Copilot、xAI、Meta、Kimi、OpenRouter、Radius 等 provider 的 OAuth 登录,浏览器授权或设备码,凭证写入 `~/.pi/agent/auth.json`。 - **API 密钥**:所有支持密钥的 provider,交互流程和 pi 的 `/login` 完全一致(包括需要多个环境变量的 provider)。 - **自定义端点**:OpenAI Chat Completions / Responses、Anthropic Messages、Google Generative AI 兼容地址写入 `~/.pi/agent/models.json`;可以直接从端点的 `/models` 拉取模型列表。每个模型都能编辑名称、上下文大小、最大输出、四项每百万 token 价格、推理与图像输入能力;[models.dev](https://models.dev) 仅补充缺失值,手动值(包括免费价格 0)始终优先。保存不等待公开目录网络请求;目录中的 0 token 限制会忽略,重新保存端点也能清理旧配置里的无效 0 值。密钥仍只存 `auth.json`,本地端点自动写入 pi 的占位密钥。 - 环境变量、`auth.json`、`models.json` 里已有的配置都会识别;你在 `~/.pi/agent` 里装的扩展、技能、提示模板和 MCP 服务器照常加载,和 CLI 一致。 - 设置窗口(`Ctrl/⌘+,`)是独立窗口:外观(浅色 / 深色 / 跟随系统、侧边栏)、通用(通知、输入预测、默认分区)、模型管理、项目与文件夹(Code 项目、Work 文件夹、worktree 位置)、关于。偏好保存在 `~/.pi-desktop/settings.json`,修改后主窗口立即跟随;preload 用同步 IPC(`app:boot`)拿到首屏需要的值,不会先闪一下再变色。 ## 数据目录 Pi Desktop 只把**自己的**数据放在 `~/.pi-desktop`(可用 `PI_DESKTOP_HOME` 指向别的位置,测试就靠它隔离)。pi 的配置留在 pi 自己的默认位置,Electron 的 Chromium 数据留在系统默认目录,互不混用。 | 位置 | 内容 | |---|---| | `~/.pi-desktop/settings.json` | 应用偏好:主题、通知、输入预测、默认分区、worktree 位置… | | `~/.pi-desktop/sessions.json`、`projects.json`、`workFolders.json` | 会话元数据、Code 项目列表、Work 文件夹列表 | | `~/.pi-desktop/cache/models-dev.json` | models.dev 目录缓存(按天刷新,可随时删除) | | `~/.pi-desktop/demo/` | 首次启动复制的演示项目和 Work 演示文件夹 | | `~/.pi-desktop/work/` | 没有选择文件夹时 Work 任务的临时工作区 | | `~/.pi-desktop/extensions/` | Pi Desktop 自己的扩展目录,和 pi 的扩展分开,不污染 `~/.pi` | | `~/.pi-desktop/.worktree/` | Code 会话 git worktree 的默认根目录;可在设置 → 项目与文件夹 → Worktree 位置改成任意本地文件夹,只影响之后新建的会话 | | `~/.pi/agent/` | pi 自己的配置:`auth.json`、`models.json`、`sessions/`、扩展 / 技能 / 提示模板、MCP。路径由 pi SDK 决定(`PI_CODING_AGENT_DIR` 可覆盖),Pi Desktop 只在原处读写,不搬家 | | Electron 的 Chromium 数据 | 仍在系统默认位置(macOS 为 `~/Library/Application Support/Pi Desktop`),和上面的应用配置无关 | ## 架构 ``` Renderer (src/renderer) Main (src/main) Agent host (src/agent, utilityProcess) ┌────────────────────────────┐ IPC ┌──────────────────────────┐ port ┌──────────────────────────────────────┐ │ React + shadcn/ui │◀───▶│ 窗口 / 设置 / 项目 │◀────▶│ SessionHub │ │ zustand 状态,pi 事件 → │ │ 对话框、剪贴板、shell │ │ 每个会话一个 AgentSessionRuntime │ │ transcript(store/) │ │ 会话调用原样转发给 host │ │ (pi SDK,进程内) │ │ preload:只暴露协议里的通道 │ │ host 崩溃后下次调用自动重启│ │ desktop-kit · demo 模型 · 命名 · git │ └────────────────────────────┘ └──────────────────────────┘ └──────────────────────────────────────┘ src/shared:三方共用的协议类型、附件消息格式、工具预览 ```