PiDeck 初体验:多项目管理 pi 编码 Agent 的开源桌面工作台,完整功能一览
PiDeck 初体验:多项目管理 pi 编码 Agent 的开源桌面工作台,完整功能一览
PiDeck 是一款开源的 pi 编码 Agent 桌面工作台,主打多项目管理——把 pi、DSH 等多个本地 AI 编码助手会话,连同 Git、内置终端、模型配置和插件,全部收进同一个桌面窗口。作为 pi desktop 客户端,它不复刻 Agent 能力,只把「框架层」的体验做到极致。本文带你从下载安装、环境自检,到核心功能全览,一次看懂它能帮你省多少事。
一、PiDeck 是什么?先看懂它的定位
一句话概括:PiDeck 不是 pi 的分支,而是一个轻量 Electron 外壳。它通过为每个会话启动独立的 pi --mode rpc 进程,把项目管理、会话历史、对话界面、配置和工具编排整合到一个原生桌面应用里——所有 Agent 能力仍由 pi 原生提供,会话文件也由 pi 原生读写。
它适合谁? 想在桌面端同时管理多个本地项目的 AI 编程助手、需要统一查看会话历史与 Git 状态、并希望用图形化方式管理 pi 配置的开发者。
核心亮点速览:
- 🖥️ 多项目多会话并行:一个窗口管理多个本地项目的全部 Agent 会话,项目间完全隔离。
- 🔌 三种会话后端:pi、DSH(DeepSeek Harness)、生图模式并存,同一项目下自由切换。
- 🧠 上下文感知输入:
@文件引用、/斜线命令、!Shell 执行,全部在同一个输入框。 - 🗂️ 会话资产化:历史浏览与恢复、Codex / Claude 会话导入、一键导出 HTML。
- 🛠️ 配置可视化:
models.json/auth.json/settings.json免手写 JSON,连接测试一键直达。 - 📊 用量看得见:供应商余额/额度查询 + 本地会话用量统计(热力图、每日/模型/项目维度)。
二、下载安装与环境自检(一键检测 pi)
PiDeck 提供 Windows、macOS、Linux 三平台的预构建安装包,可从项目发布页直接下载。安装后首次启动会自动检测 pi 是否可用。
PiDeck 依赖系统 PATH 中的 pi 命令。若检测失败,会弹出「pi 环境检测」向导,分四步引导你完成:安装 pi → 确认路径 → 校验权限 → 完成。
检测通过前,输入框里的 Agent 无法正常工作;一旦 pi --version 可用,你就可以放心配置模型并开始编码。
小贴士:验证 pi 是否可用,可在终端执行
pi --version与pi --mode rpc。更多排错方法见 常见问题。
三、快速上手:添加项目并启动第一个 Agent
进入主界面后,只需三步就能开跑:
- 添加一个本地项目目录(点击项目区的
+); - 在项目下创建 Agent 会话,点击加号即可启动;
- 选择模型与思考档位,在输入框里发送第一个任务。
项目列表顶部还有一个固定的「聊天」入口,写入应用用户目录,适合不绑定代码目录的通用对话。
从源码运行的开发者可执行:
git clone https://gitcode.com/ayuayue/PiDeck
cd PiDeck
npm install
npm run make-icon
npm run dev
四、开始对话:@ 文件、/ 命令、! Shell
PiDeck 的输入框是「上下文感知」的,几个快捷键能显著提升效率:
@引用文件:把项目内文件作为上下文喂给 Agent;/斜线命令:弹出命令菜单,如/plan、/todos、/websearch、/compact等;!执行 Shell:直接在会话里运行命令;&会话引用:跨会话注入历史上下文。
对话过程会以「活动轨迹」聚合展示:思考、工具调用和回答片段按流程排列,工具详情可展开复制,状态与退出码清晰标识。右侧的刻度定位轴把时间线映射到会话右缘,长会话点击即可跳转到对应消息。
五、多项目工作区与三种会话后端
多项目工作区让你添加、搜索、拖动排序和切换本地项目目录,每个 Agent 会话绑定独立的 cwd 与独立 pi RPC 进程,互不污染。
更强大的是三种会话后端并存:
| 后端 | 说明 |
|---|---|
| pi | 原生 pi 编码 Agent,能力由 pi CLI 提供。 |
| DSH | DeepSeek Harness,零端口内嵌运行,支持历史分页、fork、/compact 压缩。 |
| 生图模式 | 独立生图后端(OpenAI 兼容 /images/generations),会话内一键切换。 |
新建会话时,输入框左下角即可在 pi 与 DSH 之间自由切换,会话列表与头部都会用徽标区分来源。
六、文件树 · Git 面板 · 内置终端 Dock
PiDeck 把「编码三件套」直接内建,不用来回切窗口:
- 🗂️ 文件抽屉:项目文件树(含 Git 状态标识)+ 内置文件编辑器;
- 🌿 Git 集成:实时显示当前分支,本地 + 远程分支选择器、分支切换与新建;
- 🖥️ 内置终端 Dock:当前 Agent 绑定独立终端 tab,支持 PowerShell/cmd/sh、多 tab、主题切换、拖拽高度、右键复制选区。
终端选择 Shell 时会自动按系统回退,Windows 下可在 PowerShell、cmd、WSL 间切换,Linux/macOS 下自动用 sh 兜底。
外部编辑器集成同样内置:支持 VS Code、Cursor、Zed 及 JetBrains 系列(IDEA / WebStorm / PyCharm 等),在文件面板右键即可用指定编辑器打开项目或文件。
七、可视化模型配置与连接测试
最让人省心的是配置可视化:models.json、auth.json、settings.json 全部免手写 JSON。Provider 卡片 + 模型网格 + 类型感知键值编辑 + 源文件原始 JSON,一应俱全。
每个 Provider 卡片都能一键测试连接,避免把「配置回退」误判为成功;模型能力(上下文窗口 / maxTokens / 思考档位)按端点返回自适应,新模型不再不可见。
安全方面,可在「安全管理」中为工具调用设置确认等级(关闭 / 标准 / 严格),危险命令与敏感文件操作按需拦截。
八、用量统计:Token 花费一目了然
长期跑 Agent 最关心的就是成本。PiDeck 内置用量统计:累计 Token、累计成本、对话轮次、活跃天数,再配合每日用量、模型与项目维度的明细,以及一张活跃热力图,让你清楚每一分钱花在哪。
供应商余额/额度查询同样内置,支持 OpenRouter、Moonshot-Kimi、通用 OpenAI 兼容网关等模板,卡片直接显示用量。
九、常用资料与进一步探索
一句话总结:如果你正被多个本地项目的 AI 编码会话、零散的终端窗口和手写的 JSON 配置搞得头大,PiDeck 这个 pi 编码 Agent 的开源桌面工作台值得你花十分钟装一下——多项目管理、Git、终端、模型配置一次到位,让本地 AI 编码工作流真正稳定、可追溯、可配置。










