PiDeck
一个用于管理多个 Pi和DSH编码 Agent 会话的开源桌面工作台（pi desktop workbench）。
PiDeck = pi desktop：把 pi 编码 Agent 装进桌面应用。如果你在 GitHub 搜索「pi desktop」「pi 客户端」「pi GUI」，找的正是它。
国内 AtomGit 托管：https://atomgit.com/ayuayue/PiDeck
这是什么
PiDeck 是一个开源的 pi 和 DSH 桌面工作台，用于在本地项目目录中统一管理 pi Agent 会话，并支持导入 Codex、Claude 本地会话以便统一浏览和恢复。基于 Electron + TypeScript 构建，提供多项目工作区、AI 会话管理、Git 集成、内置终端、模型配置和插件扩展能力，让本地 AI 编码助手在多项目环境中保持统一、可追溯、可配置。
适合谁用： 希望在桌面端同时管理多个本地项目的 AI 编程助手会话、需要统一查看会话历史与 Git 状态、并希望以图形化方式管理 pi 配置的开发者。
PiDeck 不是 pi 的分支。它是一个轻量 Electron 外壳，通过启动多个 pi --mode rpc 进程，将项目管理、会话管理、对话界面、配置管理和工具编排整合到一个原生桌面应用中——所有 Agent 能力由 pi 原生提供，会话文件也由 pi 原生读写，PiDeck 不复刻、不劫持。除 pi 外，PiDeck 还深融合了 DSH（DeepSeek Harness） 后端，详见 DSH 后端。
❤️ 赞助商
| Logo | 简介 |
|---|---|
 |
88API Token聚合站 88API 是一站式多模型 API 聚合平台，平台由海外企业运营，稳定高效支持开票。平台提供 DeepSeek 官转和开源渠道，价格低至 5 折，完美适配PiDeck项目。一个 API Key 即可统一接入海内外多种模型，覆盖文本对话、图片、音频、音乐和视频生成接口，适用于 AI 编程、Agent 自动化、内容创作及应用开发。 立即注册 → |
📑 目录
✨ 核心亮点
- 🖥️ 多项目多会话并行 —— 一个窗口管理多个本地项目的全部 Agent 会话，项目间完全隔离。
- 🔌 三种会话后端 —— pi、DSH（DeepSeek Harness）、生图模式并存，同一项目下自由切换。
- 🧠 上下文感知输入 ——
@文件引用、/斜线命令、!Shell 执行，全部在同一个输入框。 - 🗂️ 会话资产化 —— 历史浏览与恢复、Codex / Claude 会话导入、一键导出 HTML。
- 🛠️ 配置可视化 —— pi 的
models.json/auth.json/settings.json免手写 JSON，连接测试一键直达。 - 📊 用量看得见 —— 供应商余额/额度查询 + 本地会话用量统计（热力图、每日/模型/项目维度）。
- 🧰 工作台全家桶 —— 文件树、Git 面板、内置终端、内置浏览器、草稿本，不用来回切窗口。
- 🐾 有温度的桌面集成 —— 桌面宠物、主题切换、系统托盘、飞书机器人、局域网 Web 访问。
📋 更新日志
最新版本 v0.9.0 (2026-10-14)（2026-10-14）
v0.9.0 (2026-10-14) 更新亮点
- 🚀 ACP 协议后端：接入更多 AI 编程工具
- 🚀 独立 PiDeck 宿主插件系统
- 🚀 内置外网访问与访问令牌
- 🚀 Web 实时事件推送与计划模式
- 🚀 终端设置、WebGL 与快照回放
- 🚀 对齐 pi 1.0.4 原生会话与模型目录
- 🚀 MCP 服务目录与 AI 配置助手
- 🚀 会话分支面板
- 🚀 项目置顶与列表管理
- 🚀 繁体中文界面
- 🚀 通知历史可跨重启查看
- 🚀 输入框功能按需显示
- ✨ 草稿会话可预览扩展命令
- ✨ 资源开关反馈更及时
- ✨ 远程与移动端体验完善
- ✨ 安全与长运行稳定性加固
🧩 功能总览
工作区与项目
| 功能 | 说明 |
|---|---|
| 多项目工作区 | 添加、搜索、拖动排序和切换本地项目目录，同时运行多个 pi Agent，项目间完全隔离。 |
| 内置 Chat | 项目列表顶部固定 Chat 入口，写入应用用户目录，适合无需绑定代码项目的通用对话。 |
| 会话引导页 | 新建会话时预选模型与思考档位，支持 @ 文件引用，开箱即聊。 |
| 信任确认系统 | 桌面端拦截 pi 的信任确认；不信任的项目仍可打开，有 Agent 运行时禁止删除项目。 |
会话与对话
| 功能 | 说明 |
|---|---|
| 双 Agent 后端（pi / DSH） | 同一项目下可创建 pi 或 DSH 会话并自由切换浏览，详见下方 DSH 后端。 |
| 生图模式 | 独立生图后端（OpenAI 兼容 /images/generations，支持 OpenAI / 火山方舟 / SiliconFlow 等），在会话中一键切换生图。 |
| 计划模式 (Plan Mode) | Composer 工具栏切换计划模式，Agent 先生成计划，逐条确认后执行，取消后返回选单。 |
| Ask 并行问询 | 在后台创建独立问询会话并行提问，可携带主会话上下文，答案一键引用回主输入框。 |
| 活动轨迹 | 思考、工具调用和回答片段按流程聚合展示，工具详情可展开复制，状态和退出码清晰标识。 |
| 回答级修改摘要 | 每轮回答完成后在下方展示本轮修改文件名与行数，Files 面板保留本次会话总览。 |
| 待办条 | Composer 上方常驻 Agent 任务列表，待处理 / 进行中 / 已完成进度一目了然。 |
| 消息编辑/删除 | AI 回答和用户消息均支持复制、编辑和删除，编辑后回填到输入框重新发送。 |
| 会话管理 | 新建、重命名、复制、导出 HTML、删除历史会话、重启与重新加载、关闭 Agent——侧栏或右键菜单即可完成。 |
| 会话导入 | 项目右键导入 Codex 和 Claude 本地会话，转换为 PiDeck 历史会话后继续浏览和恢复。 |
| 刻度定位轴 | 会话右缘刻度轴映射时间线位置，长会话点击即可跳转到对应消息。 |
| 内容行宽限制 | 可拖拽的内容宽度滑块，默认不限宽，适应长行代码阅读或紧凑布局。 |
文件 · Git · 终端
| 功能 | 说明 |
|---|---|
| 文件抽屉 | 项目文件树（含 Git 状态标识）、内置文件编辑器；Files 面板保留本次会话修改文件列表。 |
| 外部编辑器集成 | 「在编辑器中打开 / 在资源管理器中显示」自动检测系统文件管理器，支持 JetBrains 系列编辑器目录扫描。 |
| Git 集成 | 实时显示当前分支，本地 + 远程分支选择器、分支数量徽章、分支切换和新建分支。 |
| 内置终端 Dock | 当前 Agent 绑定独立终端 tab，支持 PowerShell/cmd/sh fallback、多 tab、主题切换、拖拽高度、右键复制选区和关闭确认。 |
模型与配置
| 功能 | 说明 |
|---|---|
| 可视化配置管理 | 编辑器管理 pi 的 models.json、auth.json、settings.json：Provider 卡片 + 模型网格 + 类型感知键值编辑 + 源文件原始 JSON，保存后按需重启 Agent 生效。 |
| 连接测试 | Provider 卡片一键测试连接，模型验证不再把配置回退误判为成功。 |
| 模型能力自适应 | 兼容 pi 0.84.3：上下文窗口 / maxTokens / 思考档位按端点返回自适应，模型目录自动刷新（后台检测到新版本即拉取，设置里可关闭，也可手动检查），新模型不再不可见。 |
| 用量查询 | 供应商余额/额度查询（内置 OpenRouter、Moonshot-Kimi、通用 OpenAI 兼容网关模板，支持多账号与独立端点），卡片直接显示用量，支持自定义探针配置。 |
| 用量统计 | 基于用量统计插件的本地统计：累计概览、活跃热力图、每日用量、模型与项目维度。 |
| 代理设置 | pi agent 子进程代理与桌面端代理独立配置，模型拉取与连接测试可走桌面端代理。 |
扩展与生态
| 功能 | 说明 |
|---|---|
| 配置、Skill 与 Extension 管理 | 可视化管理全局 Skills 与 Extensions，支持启用/禁用内置扩展，区分全局与项目级配置。 |
| Prompt & Skill 商店 | prompts.chat 国际商店 + skills.sh 社区技能商店，在线搜索、浏览详情、一键安装到本地。 |
| 中文提示词精选 | 内置 XuePrompt 数据库（4000+ 中文提示词），分类/搜索/分页浏览，一键导入本地模板。 |
| 内置扩展 | 内置 pi-deck-retry-no-body（空响应自动重试）、图片生成技能模板等开箱即用的扩展。 |
| 视觉桥 | 给不支持看图的模型「装眼睛」：图片先由视觉模型转成文字描述再进入会话，模型/接口/Key 均可在设置中配置。 |
桌面与系统集成
| 功能 | 说明 |
|---|---|
| 系统托盘 | 关闭窗口默认最小化到托盘，托盘右键菜单，双击恢复窗口。 |
| 桌面宠物 | 把多 Agent 的运行状态化作桌面上的一只小精灵：状态聚合、置顶、缩放，支持 petdex 社区宠物。 |
| 主题与外观 | 浅色 / 暗色 / 跟随系统一键循环切换（侧栏底栏），语义化设计 token，暗色模式自然适配。 |
| 通知 | 全局通知升级为卡片 toast，Ask 并行问询有独立系统通知开关，后台问题可保持静默；可开启「仅失焦时提醒」，窗口在前台时不弹通知、不响铃。 |
| 主动更新 | 应用更新始终后台检查，autoDownloadUpdates 默认开启；下载完成后由用户在设置页确认「重启并安装」。Windows/Linux 使用包内 updater，macOS 打开 GitHub Release 手动安装；Pi CLI 检查独立运行。 |
| 飞书机器人 | 会话可绑定飞书机器人，在飞书群里同步消息与状态。 |
| 局域网 Web 服务 | 设置中启动本机 Web 服务，局域网设备通过 IP + 端口访问网页版，支持双后端会话浏览与 DSH 工具面板。 |
| 进程监控 / 日志管理 | 设置页内置进程监控与缓存日志管理，排查问题不用翻目录。 |
🐳 DSH 后端
除 pi 外，PiDeck 还深融合了 DSH（DeepSeek Harness，DeepSeek 官方 Agent Harness）：同一项目下 pi 与 DSH 会话并存、自由切换浏览，会话列表与头部均有 pi / DSH 徽标区分。
- 零端口深融合 —— DSH host 以 utilityProcess 内嵌引导运行，无
dsh web、无监听端口、无后台 HTTP，懒启动不拖慢应用打开速度。 - 完整会话能力 —— 历史分页浏览、fork（从锚点裁剪分叉，fork 点文案回填输入框）、
/compact压缩上下文；应用重启后自动恢复原会话。 - 审批与提问桥 —— DSH 的审批请求 / 提问通过桌面 Ask 弹窗应答，与 pi 会话体验一致。
- DSH 配置管理页 —— 设置页 DSH 分页：settings / credentials 可视化编辑（schema 驱动表单）、host 级模型目录、host 状态与重启。
- 技能目录与命令补全 —— 会话工具面板展示可调用的 DSH 技能（
/name直呼），Composer/菜单实时枚举 host 注册的命令（含用户/插件注册）。 - 用量查询与导出 —— DSH 模型配置页同款供应商用量显示，凭据读取 DSH 官方凭据库；历史会话可导出为自包含 HTML。
启用方式： 在设置页的 DSH 分页完成配置后，新建会话时选择 DSH 后端即可。
🏗️ 工作原理
PiDeck ├─ Electron 主进程 │ ├─ 管理项目记录 │ ├─ 启动 pi --mode rpc 进程（每个会话一个独立进程） │ ├─ 内嵌 DSH host（utilityProcess，无端口、无后台 HTTP） │ ├─ 管理 Agent 绑定的本地 pty 终端 │ ├─ 桥接文件、会话、Git 操作 │ ├─ 检查应用与 Pi CLI 更新 │ └─ 暴露最小化、经校验的安全 IPC API │ ├─ Electron Preload │ └─ 经 contextBridge 向 Renderer 暴露 window.piDesktop │ ├─ React Renderer │ ├─ 项目 / 会话列表与会话时间线（流式输出） │ ├─ 文件 / 历史 / Git / 浏览器抽屉 │ ├─ 配置管理 / 技能商店 / 提示词库 │ ├─ Agent 绑定的 Terminal Dock │ ├─ 模型与上下文状态栏 │ └─ 设置 UI（常用 / 外观 / 代理 / Web 服务 / 桌面宠物 / 视觉桥 / 生图 等） │ └─ Pi 运行时 ├─ 每个 Agent 会话一个独立 pi RPC 进程 ├─ 项目级 cwd 隔离 └─ 使用 pi 原生会话 / 工具 / 模型 / 上下文
核心设计原则：一个 Agent 会话 = 一个 pi RPC 进程，确保会话隔离，让 pi 继续负责其原生能力；PiDeck 与 pi 之间只通过 stdio JSON-RPC 通信。DSH 后端以 utilityProcess 内嵌引导，同样不引入额外网络端口。
📦 下载安装
Windows、macOS、Linux 平台的预构建安装包在 GitHub Release 中发布：
PiDeck 需要单独安装
piCLI 并确保其加入系统PATH。
开发版（PiDeck Dev）
除正式版（PiDeck）外，项目同时发布**开发版（PiDeck Dev）**安装包，用于提前体验预发布功能：
- 获取入口：GitHub Releases 中标记为 Pre-release 的版本（版本号带
-beta或-beta.N后缀，如v0.7.8-beta、v0.8.0-beta.1）。 - 并行安装：PiDeck Dev 与正式版使用独立的应用标识（appId）、安装目录与快捷方式，可同时安装、互不影响。
- 数据模式二选一：首次启动 PiDeck Dev 时可选择「与正式版共用数据」或「独立数据目录」，后续可在应用内切换并按引导迁移数据。
- 协议差异：开发版注册
pideck-dev://深度链接协议，与正式版的pideck://互不抢占。
环境要求：
- 系统
PATH中可访问pi命令 - 已完成 pi 的 Provider / 登录 / API Key 配置
验证 pi 是否可用：
pi --version pi --mode rpc
从源码构建开发版：
npm run dist:win:dev # Windows（NSIS + portable + zip） npm run dist:mac:dev # macOS（DMG + zip） npm run dist:linux:dev # Linux（AppImage + deb + tar.gz）
产物名带 PiDeck-Dev- 前缀，可与 stable 包并存安装。注意 npm run dist:win 等 stable 系打包命令不会注入 dev 通道标记——版本号含 -beta 也不改变通道判定（通道由构建命令决定，不由版本号决定）。
🧰 快速开始（从源码运行）
git clone https://github.com/ayuayue/PiDeck.git
cd PiDeck
npm install
npm run make-icon
npm run dev环境要求：Node.js 20+、npm。
❓ 常见问题 FAQ
Q：PiDeck 和 pi 是什么关系？会改动我的会话文件吗？
A：PiDeck 是 pi 的桌面外壳（不是分支）：Agent 行为、工具调用、会话读写、模型调用全部由 pi 原生完成，PiDeck 只负责窗口管理、进程生命周期、会话浏览、Git 面板、终端和设置这些「框架层」的事，两者通过 stdio JSON-RPC 通信。pi / DSH 会话仍由各自后端原生读写，PiDeck 不改变原有会话格式；导入的 Codex / Claude 会话会转换为 PiDeck 历史副本，不影响原文件。
Q：启动后提示找不到 pi？
A：PiDeck 依赖系统 PATH 中的 pi 命令。先在终端执行 pi --version 确认可用；若不可用，请先安装 pi CLI 并配置好 Provider / API Key，再启动 PiDeck。
Q：支持哪些模型？在哪配置？
A：模型能力完全由 pi 的配置决定。PiDeck 提供可视化编辑器管理 models.json / auth.json / settings.json，支持连接测试；DSH 后端使用 DeepSeek 系模型，生图模式使用独立配置的生图供应商（OpenAI / 火山方舟 / SiliconFlow 等）。
Q：DSH 是什么？怎么启用？
A：DSH（DeepSeek Harness）是 DeepSeek 官方的 Agent Harness，PiDeck 对其做了深融合，能力清单见上文 DSH 后端专节。在设置页的 DSH 分页完成配置后，新建会话时选择 DSH 后端即可。
Q：会收集我的数据吗？
A：应用默认发送匿名、低频的 app_heartbeat 使用统计（可在设置中关闭），仅用于了解版本分布与平台兼容性；不会收集项目路径、代码、消息内容、会话内容或文件名，也不会上传文件。
Q：遇到问题如何反馈？
A：欢迎加入文末 QQ 群 / 微信群反馈（也可加作者微信 caoayu97），或到 GitHub Issues 提交问题；排查问题时可在设置页导出日志。
🧑💻 开发指南
| 命令 | 说明 |
|---|---|
npm run dev |
启动开发模式 |
npm run typecheck |
运行 TypeScript 类型检查 |
npm run test |
运行全量单测（node --test） |
npm run build |
构建 Renderer + Main 产物 |
npm run pack |
快速打包（--dir，用于验证） |
npm run dist |
为当前平台打包 |
npm run dist:win |
打包 Windows（NSIS + portable + zip） |
npm run dist:mac |
打包 macOS（DMG + zip） |
npm run dist:linux |
打包 Linux（AppImage + deb + tar.gz） |
npm run dist:win:dev |
打包开发版 Windows（PiDeck Dev，dev 通道 + 独立应用身份） |
npm run dist:mac:dev |
打包开发版 macOS（PiDeck Dev，dev 通道 + 独立应用身份） |
npm run dist:linux:dev |
打包开发版 Linux（PiDeck Dev，dev 通道 + 独立应用身份） |
npm run test:e2e |
运行 Playwright 端到端测试 |
npm run docs:dev |
本地预览官网（docs-site） |
npm run make-icon |
生成图标资源到 build/icon.svg |
浏览器预览模式
直接打开 http://localhost:5173/ 进行布局和响应式调试。Renderer 在 window.piDesktop 不可用时自动降级为 mock 数据，无需 Electron 环境。但涉及 Agent、会话、文件操作等真实 IPC 功能仍需在 Electron 中验证。
项目结构
src/ ├─ main/ # Electron 主进程（唯一可访问 Node 能力的业务层） │ ├─ pi/ # pi RPC 进程管理、消息解析 │ ├─ sessions/ # 会话扫描、导入、SessionRuntimeCoordinator │ ├─ git/ # GitService（status/diff/commit 等） │ ├─ prompts/ # 本地模板 + XuePrompt 中文精选 │ ├─ skills/ # SkillManager │ ├─ extensions/ # ExtensionManager │ ├─ settings/ # SettingsStore + DesktopProxy │ ├─ terminal/ # node-pty 终端会话 │ ├─ pet/ # 桌面宠物 │ ├─ feishu/ # 飞书集成 │ ├─ web/ # 局域网 Web 服务 │ ├─ ipc/ # IPC 域注册（按域拆分 handler） │ └─ index.ts # 主进程入口（只做装配） │ ├─ preload/ # contextBridge 暴露受限 IPC API │ ├─ renderer/ │ └─ src/ │ ├─ atoms/ # Jotai 状态（session-first） │ ├─ components/ # session / sidebar / workspace / ui-shadcn 等 │ ├─ hooks/ # 渲染层 hooks │ ├─ i18n/ # 文案（zh-CN / zh-TW / en-US，繁体由 scripts/genZhTwCopy.mjs 生成） │ └─ styles/ # 按域拆分的样式 + 语义 token │ └─ shared/ # 主/渲染共享类型与 IPC 通道定义
更多架构约定见 AGENTS.md，参与开发前请先阅读 CONTRIBUTING.md。
🤝 参与贡献
欢迎任何形式的贡献：Bug 反馈、功能建议、文档改进、代码 PR。
- 提交 Issue 前请先搜索是否已有同类问题；
- 代码 PR 请遵循仓库的架构约定与提交规范，详见 CONTRIBUTING.md。
感谢所有为 PiDeck 做出贡献的人！完整名单请查看 CONTRIBUTORS.md。
💬 社区交流
欢迎加入 PiDeck 社区群进行交流、反馈和讨论：
| 渠道 | 入口 |
|---|---|
| QQ 交流群 | 1026218644 |
| 微信群 | 扫描下方二维码（群二维码 7 天有效，过期请加作者微信） |
| 作者微信 | caoayu97（加好友请备注「PiDeck」） |
🔒 安全与隐私
本应用启动本地 pi 进程并通过 Electron IPC 暴露有限的文件操作。请仅运行你信任的源码。应用默认发送匿名、低频的 app_heartbeat 使用统计，用于了解版本分布、平台兼容性和活跃安装数量，可在设置中关闭；不会收集项目路径、代码、消息内容、会话内容或文件名，也不会上传文件。第三方统计服务会接收请求元数据。pi agent 子进程代理和桌面端模型拉取/测试代理可独立配置；系统浏览器打开的外部链接仍由系统浏览器网络设置决定。
🛒 作者的小店
顺手打个广告：需要充值 ChatGPT Plus / Pro、Claude 的同学可以找我 —— 官网直充、保订阅，成品号质保订阅，可开发票（加 6% 税点）。
☕ 赞助
如果 PiDeck 对你有帮助，欢迎请作者喝杯咖啡。微信扫码即可赞赏，感谢支持。
License
MIT