Pi Agent Desktop

把 Pi Coding Agent 变成真正的桌面工作台。

本地优先 · 零内部服务器 · 跨平台应用

English · 简体中文

下载 v0.2.3 · 截图 · 功能 · 快速开始 · 架构 · 变更记录 · 路线图

应用截图

核心能力

一个完整的 Agent 工作台

• 创建、切换、重命名和删除会话，并持续展示流式回复
• 新会话可根据首条有效消息在后台自动生成简短标题；可在设置中关闭，手动名称始终优先
• 搜索会话、按日期分组浏览，并在列表和主对话顶部使用稳定的会话标题
• 查看工具调用、执行过程和上下文压缩状态
• 支持排队消息、Steer / Follow-up 等交互方式
• 快速切换模型、推理等级、工具预设和提示音
• 支持图片附件、斜杠命令与 @ 文件引用
• 对话与输入框使用一致的阅读宽度，右侧文件面板可通过鼠标或键盘调整并记住宽度

用户与 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 故障或退出时会有界清理进程树

v0.2.3 的受管后台进程支持 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 应用内置；安装、版本、更新、修复和卸载统一在“开发工具”中管理，Managed 模式从已校验内置副本激活且不单独联网下载
• Attach 只连接用户手动启动的系统 Herdr，Pi Desktop 永不停止它；Managed 由 Pi Desktop 自动启动、监控、重启并在禁用、切换模式、卸载或应用退出时关闭私有 server
• Pi Session 与 Herdr Session 完全并存；关闭 Pi Desktop terminal 不关闭 Herdr pane/Agent，未知协议会 fail-closed
• 设置导航中的 Herdr 位于“浏览器”和“消息渠道”之间；安装、更新、修复和卸载仍统一在“开发工具”中管理

围绕项目工作的文件体验

• 原生选择项目目录，管理 Git 分支与 Worktree
• 浏览项目文件、打开多标签页、下载或引用文件
• Agent 回复和 Markdown 文件支持代码高亮、Mermaid、KaTeX，并可预览 Word（.docx）文档
• 文件变更监听与 Git 状态感知，让会话始终贴近当前项目

模型与扩展统一管理

• 内置 Pi Coding Agent 0.85.0，管理模型提供商和模型配置
• 会话启动优先使用本地模型目录；需要时可显式刷新远程目录，离线、超时或部分 provider 失败时继续保留缓存模型
• 支持浏览器 OAuth 登录流程
• 搜索、安装和配置 Skills；正常安装沿用 npm 默认并发，遇到网络、超时或 cache lock 故障时使用隔离缓存重试一次
• 管理 Plugins，并沿用 Pi 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.2.3，提供 macOS Apple Silicon / Intel、Windows x64 和 Linux x64 安装包。

Pi Agent Desktop v0.2.3 已内置 Pi Coding Agent 0.85.0 运行时。普通用户使用 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 或更高版本
• npm（随 Node.js 安装即可）
• macOS、Windows 或 Linux

本地运行

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 隔离开来。

flowchart LR
    Main["Electron Main<br/>窗口 · 托盘 · 协议 · Host 监督"]
    Host["Agent Host / utilityProcess<br/>Pi Agent · 会话 · 文件 · 配置"]
    UI["Renderer<br/>React 19 · Vite"]
    Browser["Main-owned WebContentsView<br/>远程网页 · Profile · 网络策略"]
    Processes["受管项目进程<br/>dev server · watcher · mock API"]
    Data["~/.pi/agent/<br/>会话 · 模型 · 配置"]

    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/
• 应用不会为了 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 或本地监听端口
• 模型请求的数据处理方式取决于你配置的模型提供商，请同时查看对应服务的隐私政策

参与开发

常用命令

项目结构

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 提交问题或建议，也欢迎直接发起 Pull Request。提交代码前请至少运行：

npm run verify

路线图

• Electr