PiDeck：把 pi Agent 会话装进桌面工作台

当你同时追三个项目，AI 编程助手开始"失忆"

想象一下这个场景：你在同时维护一个 Web 前端项目（Vue）、一个后端 API（Python Flask）和一个数据处理脚本（R），每个项目都跑了十几轮 AI 编程对话。某天客户问起"上周四在 Vue 项目里，你让 AI 改的那个登录页面的字段名是什么来着？"你翻了半天终端历史记录，发现早就被刷掉了——AI 会话就这样消失在终端的滚动里。

这不只是你一个人的痛。pi（pi.dev）是一款优秀的本地 AI 编程 Agent，支持 Claude Code、OpenAI Codex 等多种后端，它原生的交互界面是命令行。这意味着：每次重启终端、切换目录，你的对话上下文随之丢失；多个项目并行开发时，Agent 会话散落在各自的目录里，无法统一浏览。

PiDeck 正是为解决这个"会话碎片化"问题而生的。

背景：为什么需要一个桌面外壳来包裹 AI Agent？

PiDeck 的开发者 ayuayue 是 pi 的活跃用户，也是 LinuxDO 社区的贡献者。在使用 pi 进行日常开发的过程中，他发现原生 pi CLI 工具虽然强大，但缺乏几个关键能力：

第一，会话不可持久化。 pi 的对话历史存储在本地 .pi 目录，但浏览历史需要手动翻文件，效率低下。没有统一的 GUI 来管理这些会话。

第二，多项目协作困难。 如果你同时做三个项目，每个项目都需要一个独立的 pi 实例，切换项目时 Agent 的上下文状态无法保留。

第三，配置管理分散。 pi 的 models.json、auth.json、settings.json 等配置文件分散在用户目录里，没有可视化编辑器，调试 API Key 或切换模型非常麻烦。

基于这些真实痛点，ayuayue 决定用 Electron + TypeScript 构建一个桌面"工作台"，将 pi 的 CLI 能力包装成原生桌面应用，同时增加会话管理、项目工作区、Git 集成等实用功能。

类比：PiDeck 就是 AI 编程的"多标签浏览器"

如果你把 Chrome 多标签页类比成浏览器管理多个网站的体验，那么 PiDeck 就是 AI 编程 Agent 的"多标签管理器"。每个标签页对应一个本地项目，每个项目里有独立的 Agent 会话、Terminal、Git 状态——而这一切都在同一个桌面窗口里，无需切换终端窗口。

图1：PiDeck 主界面 — 多项目工作区 + 内置 Chat 对话区

核心功能：从会话管理到深度集成

多项目工作区

PiDeck 支持同时添加多个本地项目目录，每个项目对应独立的 Agent 实例。与 pi 原生 CLI 不同的是，这些项目之间完全隔离，但可以在 PiDeck 的统一界面中快速切换。你可以对项目列表进行搜索、拖动排序，分组管理不同类型的项目。

会话导入：打通 Claude Code 和 Codex 的历史

这是 PiDeck 最具特色的功能之一。项目右键菜单中提供了"导入 Codex 会话"和"导入 Claude 会话"的入口，可以自动扫描本地目录中的会话元数据文件，转换为 PiDeck 的历史会话格式。这意味着你无需重新开始，可以在 PiDeck 中无缝恢复之前的编程对话，继续之前的上下文。

图2：PiDeck 会话管理界面 — 支持导入 Claude 和 Codex 历史会话

内置 Chat + 计划模式（Plan Mode）

每个项目都有独立的消息流视图，支持 AI 回答的编辑、删除、多选转发和复制。更实用的是"计划模式"（Plan Mode）：Agent 先生成行动计划，逐条等待用户确认后再执行。这解决了 AI 自主操作可能偏离意图的问题，尤其适合生产环境或需要精确控制的场景。

配置、Skill 和 Extension 管理

PiDeck 提供了完整的可视化配置编辑器，可以直接管理 pi 的 models.json（模型配置）、auth.json（认证信息）、settings.json（全局设置），以及 Skill 和 Extension 插件。内置扩展包括提问助手、文件捕获、计划模式辅助和待办管理四个模块。

图3：PiDeck 配置管理 — 可视化编辑器管理模型和认证

内嵌终端 + Git 集成

PiDeck 为每个 Agent 项目嵌入了独立的终端 Dock（基于 node-pty + xterm.js），支持 PowerShell/cmd/sh 自动切换，主题切换，多 tab 操作。Git 集成则提供实时分支状态显示、分支选择器、新建分支等能力，让你在不离开 PiDeck 的情况下完成版本控制操作。

桌面宠物系统

PiDeck 还别出心裁地内置了一个桌面宠物系统（类似经典游戏《星露谷物语》的宠物），开发者可以选择"小 Capy"、"Duoduo"等卡通角色作为应用悬浮宠物，增加工作的趣味性。

技术架构：Electron + React + RPC 的精妙分层

PiDeck 的技术选型非常清晰：Electron 38 + React 19 + TypeScript。

整体架构

项目采用 electron-vite 作为构建工具，将代码分为三层：

• Main Process（src/main/）：Node.js 主进程，负责系统级操作——文件管理、Git 操作、Terminal 进程（node-pty）、pi Agent 进程管理（PiProcess）、配置持久化、会话导入、飞书集成等。
• Preload（src/preload/）：安全的桥接层，暴露 IPC 通道供渲染进程调用主进程 API。
• Renderer Process（src/renderer/）：React 19 渲染进程，负责 UI 展示——Monaco Editor、对话流、终端面板、配置表单等。

RPC 通信机制

PiDeck 不修改 pi 的任何源码，它通过 RPC 模式启动 pi Agent（pi --mode rpc），然后通过自定义的 RPC 客户端（PiRpcClient.ts）与 pi 进程通信。PiRpcClient 管理连接生命周期、代理配置、进程重启等细节，主进程中的 AgentManager 负责协调多个 pi 实例。

这种设计非常优雅：PiDeck 是 pi 的桌面外壳，而非 pi 的分支。所有 AI 编程能力由 pi 原生提供，PiDeck 专注于交互体验的提升。

渲染优化

electron-vite 配置中的 manualChunks 策略值得称道：将 React 全家桶、Monaco Editor、图标库（lucide-react）、Markdown 渲染栈（remark/rehype/unified）分别打包为独立 chunk，利用浏览器缓存机制加快二次加载。Mermaid 图表采用 dynamic import 惰性加载，不阻塞首屏。

飞书集成

主进程中有完整的飞书 SDK 集成（@larksuiteoapi/node-sdk），支持飞书卡片消息渲染、富文本处理、文件意图捕获和文档操作。这使得 PiDeck 的 Agent 输出结果可以直接推送到飞书群或文档中。

代码质量

项目使用 TypeScript 严格模式，有完整的类型定义（src/shared/types.ts），包含 39 个测试文件覆盖核心逻辑，ESLint 代码检查，CI/CD 自动化构建（GitHub Actions 支持 Windows/macOS/Linux 三平台）。

上手体验

门槛评估：适中。 适合有 Electron/React 开发经验的开发者。用户需要先在本地安装 pi（pip install pi-agent 或通过官方安装脚本），然后通过 npm install && npm run dev 启动 PiDeck。

配置复杂度：低。 首次使用需要配置 pi 的 API Key（支持多种模型后端）和代理设置，之后便可持续使用。

适用人群： 有多项目并行 AI 编程需求的开发者，或希望以图形化方式管理 AI 会话历史的用户。

局限与争议

1. 平台依赖：Electron 应用在 Linux 上需要 X11/Wayland 支持，部分纯服务器环境无法使用。
2. 非云端：会话存储在本地，换设备需要手动迁移，且没有内置的跨设备同步能力。
3. 与 pi 版本同步风险：如果 pi 的 RPC 协议发生 Breaking Change，PiDeck 需要及时更新版本。
4. 资源占用：Electron + React + Monaco Editor 的组合相对较重，在低配置机器上可能有性能压力。

行业意义与趋势

PiDeck 代表了 AI 编程工具从 CLI 向 GUI 演进的一个方向：随着 Claude Code、OpenAI Codex 等本地 AI 编程 Agent 越来越成熟，用户对会话管理、项目组织、上下文持久化的需求日益增长。PiDeck 通过零侵入式的 RPC 外壳设计，巧妙地在不修改上游工具的前提下，极大提升了使用体验。

这种"外壳包装"模式为开源社区提供了很好的借鉴：对于强大的 CLI 工具，如果上游不打算做 GUI，不妨在生态中诞生一个独立的工作台项目，专注于体验层的优化，而非 fork 源码造成分裂。

---

本报告基于 PiDeck v0.6.5（2026-07-13）版本生成，项目由 ayuayue 开发维护，采用 MIT 协议开源。