# Pi Agent Desktop **把 Pi Coding Agent 变成真正的桌面工作台。** 本地优先 · 零内部服务器 · 跨平台应用 [![Desktop Build](https://github.com/DLYZZT/pi-desktop/actions/workflows/build-desktop.yml/badge.svg)](https://github.com/DLYZZT/pi-desktop/actions/workflows/build-desktop.yml) ![Electron 43](https://img.shields.io/badge/Electron-43-47848F?logo=electron&logoColor=white) ![React 19](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=0B1F2A) ![macOS, Windows & Linux](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey) ![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue) [English](./README.en.md) · **简体中文** [下载 v0.4.3](https://github.com/DLYZZT/pi-desktop/releases/tag/v0.4.3) · [截图](#应用截图) · [功能](#核心能力) · [快速开始](#快速开始) · [架构](#架构设计) · [变更记录](https://github.com/DLYZZT/pi-desktop/releases) · [路线图](#路线图)

## 应用截图主工作区与主要设置界面，点击图片可查看原图。 [![Pi Agent Desktop 主工作区：会话侧栏、Auto 模型选择、工具预设与右侧浏览器](./images/app-main.png)](./images/app-main.png)

_{模型与自动路由：快模型、强模型和决策模型}	_{MCP 服务：配置、连接测试与登录}
_{浏览器设置：Profile、标签页与网络访问}	_{Herdr：连接状态与 Agent CLI 诊断}
_{技能管理：启用开关与 SKILL.md 编辑}	_{系统工具发现与托管运行时管理}

## 核心能力 ### 一个完整的 Agent 工作台 - 创建、切换、重命名和删除会话，并持续展示流式回复 - 新会话可根据首条有效消息在后台自动生成简短标题；可在设置中关闭，手动名称始终优先 - 搜索会话、按日期分组浏览，并在列表和主对话顶部使用稳定的会话标题 - 查看工具调用、执行过程和上下文压缩状态 - 支持排队消息、Steer / Follow-up 等交互方式 - 快速切换模型、推理等级、工具预设和提示音 - 支持图片附件、斜杠命令与 `@` 文件引用 - 对话与输入框使用一致的阅读宽度，右侧文件面板可通过鼠标或键盘调整并记住宽度 ### 会话工具与执行历史 - 在会话工具菜单中管理 Codemode、工具搜索和工具预设；“完全访问”预设包含 Codemode 与工具搜索 - 分别控制模型可见的工具入口、可被嵌套查找的工具与实际执行授权；嵌套调用同样遵守当前会话的工具权限 - 按父子执行树查看直接与嵌套调用的状态、耗时和原始参数／结果，并按当前会话分支查看历史 - 大结果和临时输出持久化后可分页读取；重开或压缩会话后，Agent 可通过 `tool_history_get` 查询原文 - Host 中断后保留已完成的子调用，将未确认结果的调用标为中断／结果未知，恢复时不自动重放操作 ### 用户与 Agent 共享的内置浏览器 - 在主界面右侧使用 Electron `WebContentsView` 承载真实 Chromium 页面，支持多 Tab、临时/持久 Profile、登录态、下载、上传和代理 - Agent 可在独立的 Browser read/interact 授权下执行导航、结构化页面快照、截图、点击、输入、键盘与等待；首次需要时由主窗口弹窗询问，Coding 权限不会隐式开启浏览权限 - 用户与 Agent 操作同一个页面，并可随时接管；提交、下载、上传、权限和外部协议继续经过本地策略或确认 - 设置页管理全局默认与具体会话的永久权限，授权弹窗只产生当前会话的临时权限；高级浏览器模式由一个仅本次启动有效的本机开关统一控制 - 高级浏览器模式整合三层 UA/Client Hints 身份、可信输入、CDP 网络抓包与确认后的写请求重放、JavaScript 经验库和专用高级 Profile；Agent 工具不接收或返回 Cookie value - 私网保护当前为明确标记的 best-effort；未部署受控网络沙箱时，Strict 模式会直接拒绝请求 ### 可观察、可控制的受管开发进程 - 在受支持平台上让 Agent 用显式 `process_*` tools 持续运行 Vite、React、Three.js、Storybook、Flask、Spring Boot、mock API 和 watch build；普通短命令继续走 Bash - 右侧 Processes 面板展示 owner、状态、readiness、脱敏日志、loopback endpoint 和退出原因；用户可随时发送行式 stdin、停止、强制停止、重启、复制或导出日志 - 框架页面使用受管 localhost 服务与内置 Browser 联调，进程权限与 Browser 授权保持分离；慢启动可复用日志 cursor 继续等待，不需要 shell `&`、nohup 或外部终端 - macOS/Linux 使用 POSIX process group；Windows x64 使用经过完整性校验的 Rust helper 和 Job Object，helper、reaper 或 owner identity 未就绪时会 fail-closed - 功能默认关闭且不是安全沙箱：子进程拥有与 Agent Bash 相同的本机文件、网络和环境权限；常见 LAN bind 需要确认，Host/App 故障或退出时会有界清理进程树受管后台进程支持 macOS、Linux 和 Windows 11 x64；Windows ARM64、Windows Server 和 32 位 Windows 暂不支持。 ### Pi 对话式控制 Herdr - 可选连接本机 Herdr，可在原主对话中查看 Fleet，创建、聚焦或重命名 workspace/tab/pane，解释 Agent 状态，脱敏查看进程，等待输出，并启动、提示或等待 Agent - Pi Session 侧栏和主对话始终是主入口；Agent Fleet 在初始页和激活会话中都位于标题栏右侧，右侧 ANSI terminal 仅用于观察、故障排查和显式接管 - workspace/pane/Agent close 均需要 Pi 本机确认，确认框随界面语言显示完整中英文；Herdr v0.8.2 没有 `agent.stop`，因此 Agent close 会明确关闭其所在 pane，不会静默伪造停止语义 - Herdr 随 macOS/Linux/Windows x64 应用内置；安装、版本、更新、修复和卸载统一在“开发工具”中管理，Managed 模式从已校验内置副本激活且不单独联网下载。Windows 已支持 Fleet/Agent 控制，以及由原生 Job Object 保护的实时 ANSI 终端和显式键盘接管 - Attach 只连接用户手动启动的系统 Herdr，Pi Desktop 永不停止它；Managed 由 Pi Desktop 自动启动、监控、重启并在禁用、切换模式、卸载或应用退出时关闭私有 server - Pi Session 与 Herdr Session 完全并存；关闭 Pi Desktop terminal 不关闭 Herdr pane/Agent，未知协议会 fail-closed - 设置导航中的 Herdr 位于“浏览器”和“消息渠道”之间；安装、更新、修复和卸载仍统一在“开发工具”中管理 ### MCP 服务与工具 - 在“设置 → MCP”新增、编辑或导入全局及当前项目的 stdio／Streamable HTTP 服务，查看连接状态、测试连接和重新连接 - 支持 MCP OAuth 登录、取消与凭据刷新，以及服务商凭据引用；可浏览工具、资源和资源模板，并预览资源内容 - 项目配置覆盖同名全局配置，扩展注册来源及待应用状态会单独显示；保存配置后，仍需在当前会话授权工具 - MCP 工具可按配置直接提供给模型，或通过工具搜索／Codemode 按需发现与调用；原始结果和完整结构化内容进入执行历史 ### 围绕项目工作的文件体验 - 原生选择项目目录，管理 Git 分支与 Worktree - 浏览项目文件、打开多标签页、下载或引用文件 - Agent 回复和 Markdown 文件支持代码高亮、Mermaid、KaTeX，并可预览 Word（`.docx`）文档 - 文件变更监听与 Git 状态感知，让会话始终贴近当前项目 ### 模型与扩展统一管理 - main 中的 Windows 新会话默认 Shell 为 PowerShell，可在“设置 → 通用 → Agent 默认 Shell”改为 Bash。 - 会话启动优先使用本地模型目录；需要时可显式刷新远程目录，离线、超时或部分 provider 失败时继续保留缓存模型 - 按服务商提供 API Key、订阅或 OAuth 登录，支持多步凭据配置向导、已有凭据替换确认和 Azure 旧配置迁移 - 模型编辑支持采样参数、按思考级别设置采样参数、图像与请求输入限制，以及按模型 ID 覆盖参数；支持的模型可选择 `max` 推理级别 - 在“设置 → 模型 → 模型高级配置”调整自动压缩、Token 保留、重试、超时及 SSE／WebSocket 传输方式；这些 Pi 全局设置与 CLI 共享，现有会话需重新加载后生效 - 保存模型和高级配置时检测外部修改冲突，避免覆盖在 CLI 或编辑器中更新的配置 - 搜索、安装和配置 Skills；正常安装沿用 npm 默认并发，遇到网络、超时或 cache lock 故障时使用隔离缓存重试一次 - 管理 Plugins，并沿用 Pi Agent 的扩展体系开发分支的模型配置可先运行 `npm run check:models-config` 只读预检；无效字段会使整份自定义配置暂不生效，设置页保留原内容以便修正。OpenRouter 的个性化目录与 Pi CLI 共享缓存，不按 key 或 endpoint 分区；不同凭据交替使用、特别是离线启动时，列表可能来自另一个运行环境，不能将缓存目录视为当前 key 已获授权。 ### Auto 虚拟模型与自动路由在“设置 → 模型 → 自动路由”启用 Auto，选择快模型、强模型及各自的思考级别，保存后在聊天模型菜单中选择 **Auto**。 - 支持按思考级别路由：`high` 及以上使用强模型，其余使用快模型；也可配置决策模型，根据每次新提问的复杂度选择模型 - 每轮新提问选择一次模型，后续工具执行沿用已选模型；可启用自动重试时切换到另一个已配置模型 - 决策请求会增加耗时和用量，失败或不可用时使用强模型；实际调用用量计入会话统计 - 最近实际使用的模型和思考级别显示在输入框下方 **Auto** 右侧，并可查看按实际模型统计的用量路由配置在新建、重新加载会话或重新选择 Auto 后生效。 ### Codemode 图片生成与决策模型通过会话工具菜单启用 Codemode（“完全访问”预设已包含），让 Agent 按需生成图片，或调用决策模型进行分类、是非判断和评分。支持图片输入的分类器也可判断截图和图片。模型按提供商的现有凭据发现，分类器作为辅助能力使用，不进入聊天主模型选择器。每次模型调用都遵循 Codemode 权限，支持停止，并保存原始输入、结果和执行状态；用量计入会话统计，可在已有工具记录中查看。OpenAI 决策接口需要 API key，ChatGPT 订阅登录不提供该能力。TypeSafe Jev 可在“设置 → 模型 → 添加服务商”中搜索 TypeSafe 或 Jev，填写 API key 后使用；详情页会列出 `jev-latest`。可以让 Agent“使用可用的决策模型给这些条目分类”。生成的图片可在最终回复及重开的会话历史中查看。服务商详情页列出可用的图片与决策模型，并提供测试请求；测试使用所配置的服务商凭据，可能产生用量费用。 ### 跨平台开发工具管理 - 优先发现并验证用户已有的 Node.js/npm、Python、uv、Git/Bash、Bun 和 jq，覆盖 GUI 启动时 PATH 不完整的常见场景 - 为 Skills、Plugins、Agent Bash、Git/worktree 和搜索工具提供一致的绝对路径与局部执行环境 - 用户确认后可把 Node.js LTS、CPython、uv、PortableGit、Bun 和 jq 安装到应用私有目录，不修改系统 PATH、Shell 配置或注册表 - 安装包内置经过清单校验的目标平台 ripgrep 与 fd，保证基础搜索离线可用 ### 微信、Telegram 与飞书/Lark 消息渠道 - 个人微信二维码登录、Telegram BotFather token，以及飞书/Lark 官方扫码创建新机器人或已有应用 App ID/App Secret 接入 - 私聊配对，以及 Telegram、飞书/Lark 群聊白名单与 @触发控制；微信群尚未开放，默认不授予远程工具权限 - 外部对话默认使用独立 Pi Session，也可从当前会话顶部快速绑定并与 UI 共用上下文；绑定列表会在窗口内自动定位，长列表支持内部滚动 - 账号的默认工具权限用于新建独立渠道会话，保存变更时也会同步到该账号已经绑定的会话；工具权限按 Pi Session 生效，共用同一 Session 的多个渠道入口共享同一权限 - 模型用户正文只包含 IM 实际文本；桌面端用本地黑、微信绿、Telegram 蓝、飞书/Lark 橙的用户气泡区分来源 - 微信、Telegram 与飞书/Lark 支持入站图片、文件和语音；飞书/Lark 还支持视频资源，图片直接作为多模态输入，其他附件进入隔离暂存区，微信 SILK 语音优先转为 WAV - Telegram 私聊支持流式预览，并折叠思考与工具详情 - 飞书/Lark 通过官方 SDK 长连接收取私聊、受控群聊和 thread，并使用 Card 渲染 Markdown、流式显示思考/工具调用、最终折叠过程 - Telegram 与飞书/Lark 在原消息上显示回合 Reaction 状态；飞书单聊可用原生菜单触发 `/help`、`/status`、`/new`、`/compact` 和 `/reload` ### 为长期运行而设计 - 单实例、系统托盘、桌面通知与 Dock / 任务栏角标 - 窗口状态记忆、系统主题跟随和自定义协议 - Agent Host 异常恢复、崩溃报告与诊断信息导出 - 区分自然完成与主动停止：停止的回合显示“已停止”，重开历史后保留该状态，并且不会触发完成提示音或后台完成通知 - 已启用平台的正式安装版可定时或手工检查稳定版更新，由用户确认下载，并在任务结束后重启安装 - `sandbox: true`、严格 CSP 与类型化 IPC 契约 ## 快速开始 ### 使用桌面安装包最新稳定版为 [v0.4.3](https://github.com/DLYZZT/pi-desktop/releases/tag/v0.4.3)，提供 macOS Apple Silicon / Intel、Windows x64 和 Linux x64 安装包。 v0.4.3 内置 Pi Coding Agent 1.4.0，改进上下文压缩、工具调用与多会话代码编排，补充模型配置兼容提示，并精简普通服务商的 API Key 配置入口。也可按下方步骤[从源码运行](#本地运行)。普通用户使用 Agent 本身无需单独安装 Pi CLI、Pi Coding Agent、Node.js 或 npm；安装桌面应用并配置模型提供商后即可使用。Skills、Plugins 或 Agent 脚本需要额外开发工具时，应用会优先复用健康的系统安装，也可以在用户确认后安装应用私有运行时。应用会读取 `~/.pi/agent/` 中的会话与配置。如果你已经使用 Pi CLI，可以直接复用现有数据，无需迁移；此前没有使用过 Pi CLI 也不影响使用。 Pi Desktop 会先发现并验证用户已经安装的 Node.js/npm、Python、Git、Bash、uv、jq 和 Bun；内置的 `rg`/`fd` 保证离线搜索可用。 ### 桌面安装包系统要求 - macOS 12 Monterey 或更高版本，支持 Apple Silicon（arm64）和 Intel（x64） - Windows 10 或 Windows 11 64 位（x64） - Linux 64 位（x64）AppImage，需要现代 glibc 发行版和可用的桌面图形会话；当前采用手工下载安装更新 - 暂不提供 Windows 32 位（x86）或 Windows ARM64 安装包 ### 源码开发环境要求 - Node.js 22.19 或更高的 22.x 版本（`>=22.19.0 <23`） - npm（随 Node.js 安装即可） - macOS、Windows 或 Linux ### 本地运行 ```bash git clone https://github.com/DLYZZT/pi-desktop.git cd pi-desktop npm ci npm run dev ``` ### 构建 - macOS Apple Silicon（arm64）：DMG + ZIP - macOS Intel（x64）：DMG + ZIP - Windows（x64）：NSIS 安装程序 - Linux（x64）：AppImage ## 架构设计 Pi Agent Desktop 使用 Electron 三进程模型，将高权限桌面能力、Agent 运行时和 UI 隔离开来。 ```mermaid flowchart LR Main["Electron Main
窗口 · 托盘 · 协议 · Host 监督"] Host["Agent Host / utilityProcess
Pi Agent · 会话 · 文件 · 配置"] UI["Renderer
React 19 · Vite"] Browser["Main-owned WebContentsView
远程网页 · Profile · 网络策略"] Processes["受管项目进程
dev server · watcher · mock API"] Data["~/.pi/agent/
会话 · 模型 · 配置"] Main --> Host Main --> UI Main --> Browser Host -->|"revisioned Browser RPC"| Main Host -->|"POSIX worker / Windows Job helper"| Processes Main -.->|"crash reaper"| Processes Browser -->|"独立授权的 localhost 访问"| Processes UI <-->|"Typed MessagePort IPC"| Host Host <--> Data ``` - **Main**：负责窗口生命周期、菜单、托盘、通知、软件更新、自定义协议和 Agent Host 监督 - **Agent Host**：在独立 `utilityProcess` 中运行 Pi Coding Agent，处理会话、文件、配置与扩展 - **Renderer**：运行 React UI，只通过受控的 preload bridge 与 Host 交互 - **Browser View**：远程站点与 localhost 项目页只进入 Main 创建的沙箱化 `WebContentsView`，不获得应用 preload、Node 或主 Renderer bridge - **无内部本地服务**：应用不使用 TCP 端口承载 UI 或控制面；用户显式启动的受管项目服务可以监听 loopback ## 数据、安全与隐私 - 会话与 Pi 配置默认留在本机 `~/.pi/agent/` - Desktop 的工具权限和工具执行记录另存于应用数据目录；备份完整工具历史时，还需保留其中的 `tool-executions` 日志及内容文件 - 应用不会为了 UI 通信额外开放本地网络端口 - Renderer 开启 Electron sandbox，并使用严格的 Content Security Policy - preload 只暴露受控桥接接口，Host RPC 由 TypeScript 契约约束 - Agent Browser tools 与高级浏览器模式默认关闭；Main 在任何目标工具副作用前按 session、持久策略、临时 grant、lease 和 policy revision 逐次校验 - 受管后台进程默认关闭，并要求受支持的平台与架构、项目 trust、Session cwd containment、健康的 crash reaper 和有界资源策略；Windows x64 还会校验 Rust helper 的固定路径、版本与完整性。它是生命周期控制，不是容器或沙箱 - 更新客户端只使用正式包内固定的公开 GitHub Release 配置，不接收 Renderer 提供的更新地址或发布凭证 - 微信和 Telegram 只发起出站 long polling，飞书/Lark 使用出站 WebSocket；均不开放 webhook 或本地监听端口 - 模型请求的数据处理方式取决于你配置的模型提供商，请同时查看对应服务的隐私政策 ## 参与开发 ### 常用命令 | 命令 | 说明 | | ------------------------------------------------------------ | ------------------------------------------------ | | `npm run dev` | 启动 Vite、主进程构建监听与 Electron | | `npm run typecheck` | 执行 TypeScript 类型检查 | | `npm run test` | 运行自动化测试套件 | | `npm run check:contract` | 检查 API 方法与 Host handler 覆盖关系 | | `npm run check:architecture` | 检查进程架构边界与代码结构约束 | | `npm run smoke` | 运行 Electron 冒烟测试 | | `npm run test:execution-recovery` | 验证 Host 崩溃后的工具执行历史恢复 | | `npm run test:browser-electron` | 运行本地 Browser Electron 集成测试 | | `npm run test:managed-process-workflows` | 运行受管进程生命周期与清理测试 | | `npm run test:herdr-e2e` | 使用指定官方 binary 运行隔离 Herdr E2E | | `npm run test:herdr-desktop-e2e` | 运行 production Electron/Renderer Herdr 集成 E2E | | `npm run test:windows-managed-helper` | 在 Windows x64 验收 Rust helper 与 Job Object | | `npm run test:windows-nsis-upgrade -- <旧安装包> <新安装包>` | 在 Windows x64 验证安装、升级、回滚和卸载 | | `npm run verify` | 执行提交前的完整质量检查 | | `npm run build` | 构建 main、preload 与 renderer | | `npm run pack` | 生成未封装的应用目录 | | `npm run dist` | 生成当前平台配置的全部架构安装包 | | `npm run dist:mac:signed` | 生成当前 Mac 架构的 Developer ID 签名包 | | `npm run dist:mac:notarized` | 生成签名并经 Apple 公证的 macOS 包 | ### 项目结构 ```text src/ ├── contract/ # IPC 类型契约与 RPC 层 ├── main/ # Electron 主进程与 crash reaper ├── preload/ # 安全桥接接口 ├── agent-host/ # Agent、会话、文件、配置与受管进程 ├── renderer/ # React 桌面界面 └── shared/ # 可测试的纯函数与共享模块 native/ └── windows-managed-process-helper/ # Windows x64 Rust / Job Object helper ``` 欢迎通过 [Issues](https://github.com/DLYZZT/pi-desktop/issues) 提交问题或建议，也欢迎直接发起 Pull Request。提交代码前请至少运行： ```bash npm run verify ``` ## 路线图 - [x] Electron 三进程架构与类型化 IPC - [x] 会话、项目文件、模型、Skills、Plugins 与 OAuth - [x] Pi 1.1.0 运行时、服务商认证流程和扩展后的模型／高级配置界面 - [x] MCP 服务管理、OAuth、资源预览与会话工具授权 - [x] Codemode／工具搜索、嵌套调用、执行树和持久化原文历史 - [x] 图片生成、决策模型、Auto 自动路由与 `max` 推理级别 - [x] 个人微信、Telegram 与飞书/Lark 文本、图片、文件和语音消息渠道，以及飞书/Lark 视频资源 - [x] 托盘、通知、系统主题、崩溃恢复与诊断导出 - [x] Linux、macOS、Windows CI 测试与正式发布构建矩阵 - [x] macOS 本地签名/公证工具与 `v*` tag release workflow - [x] 首次 `v*` tag 双架构签名、公证与正式 Release 端到端验收 - [x] Windows x64 正式 Release 资产管线（当前不配置代码签名） - [x] 首个同时包含 macOS 与 Windows 正式资产的 Release 验收（v0.1.1） - [x] 实现主进程稳定版检查、用户确认下载、重启安装和设置界面 - [x] 实现 Main-owned WebContentsView 内置浏览器、按需 Agent 会话授权和统一高级浏览器模式 - [x] 实现 macOS/Linux 受管后台进程、Agent tools、Processes UI、日志游标与 crash reaper - [x] 实现 Windows x64 Rust helper、Job Object containment、打包门禁与 Windows 11 验收 - [x] 完成 updater-enabled 基线到更高版本的 macOS 与 Windows 端到端升级验证 - [x] macOS arm64/x64、Windows x64、Linux x64 安装包生产启动 E2E 与发布前检查 ## 与 Pi 生态的关系 Pi Agent Desktop 是 Pi Coding Agent 的桌面工作台，继续使用 `~/.pi/agent/` 中的会话和配置，因此可以与 CLI 配合使用。 Plugins 继续通过 Pi 的包管理器与运行时加载。仅适用于终端 TUI 的扩展接口（例如自定义终端组件或原始按键监听）无法在桌面 Renderer 中等价呈现；应用会显示明确的兼容性提示，不会静默忽略。 ## License [Apache License 2.0](./LICENSE)