PiDeck 上手指南：本地 AI 编程工作台完整教程

如果你已经在用 Claude Code、Cursor 或其他 AI 编程 CLI 工具写代码，一定遇到过这样的痛点：切换项目、管理会话、回看历史全靠命令行操作，每个终端窗口的 AI 对话彼此独立，关掉窗口后上周的方案就再也找不回来。B 站 UP 主曹阿宇推出的《PiDeck 上手全系列》教程，系统性地介绍了 PiDeck 这个开源桌面工作台如何解决这些问题。本文将其六集内容梳理为一份完整的上手指南。

在展开之前，有必要先理解这类工具所处的生态背景。近两年，命令行式的 AI 编程助手迅速崛起。Anthropic 推出的 Claude Code 允许开发者直接在终端里通过自然语言驱动大模型完成代码编写、调试与重构；Cursor 与 Windsurf 则代表了另一条路线，把 AI 深度集成进类 VS Code 的图形化编辑器。这些工具的共同特点是把大语言模型（LLM）从「问答框」升级为能够读取项目文件、执行命令、修改代码的 Agent。然而 CLI 工具虽然轻量、可脚本化，却也天然缺乏会话持久化与多项目管理能力——每个终端窗口是一个独立进程，历史对话难以检索。PiDeck 正是在这一背景下出现的补位产品，它不重造轮子，而是为现有 CLI 套上统一的图形化管理层。

PiDeck 是什么：给 CLI 套上图形化外壳

PiDeck 本质上是一个桌面工作台，专门用来管理你的 AI Agent 会话。用最直白的话说，它在命令行工具前面套了一个 Electron 壳，但使用者完全不需要关心底层发生了什么，只需要记住一个核心概念：PiDeck 等于一个统一的地方，管理你所有项目的 AI 对话。

这里的 Electron 值得多说一句。它是 VS Code、Slack、Discord 等主流桌面软件的技术底座，核心思路是用 Chromium 渲染界面、用 Node.js 处理系统层逻辑，从而让开发者能用 Web 技术（HTML/CSS/JavaScript）构建跨平台桌面应用。这解释了为什么 PiDeck 强依赖 Node.js 环境，也解释了它能同时提供 Windows EXE、Mac DMG、Linux AppImage 三种安装包。对 PiDeck 而言，Electron 壳负责渲染项目列表、对话区、文件树等图形界面，而真正与大模型交互的仍是底层被封装的 CLI 进程。

它的界面布局非常清晰——左侧是项目列表，中间是对话区，右侧是文件树和会话历史。最关键的设计是项目完全隔离：项目 A 的上下文不会污染项目 B，你可以在多个项目间自由切换，每个项目里的 AI 都记得你上次聊到哪里。

其核心心智模型也很简单：一个 Agent Tab 等于一个 CLI 进程。PiDeck 在保留裸命令行全部能力的基础上，额外提供了多项目工作区、会话可视化、Git 集成、内置终端、配置图形编辑器，以及一个内置的中文提示词精选库（据介绍收录了 4000 多条提示词，可一键导入）。

谁适合使用 PiDeck

根据教程的归纳，PiDeck 主要面向四类用户：一是已经用 CLI 但觉得终端管理太麻烦的开发者；二是从 Cursor、Windsurf 转来、想找更轻量灵活方案的人；三是团队开发中多项目切换成常态的场景；四是仍在观望 AI 编程工具的新手。之所以适合作为起点，是因为它免费、开源、没有厂商锁定。

安装 PiDeck 与环境检测：顺序很关键

安装 PiDeck 有一个容易被忽略却至关重要的原则——先把底层 CLI 配通，再添加项目和启动 Agent。正确的安装顺序分三步：

1. 安装 Node.js 20 或更高版本（从 nodejs.org 中文下载页获取）；
2. 安装对应的 AI 命令行工具；
3. 再安装并打开 PiDeck，完成环境检测。

安装包可从 GitHub Releases 下载：Windows 用 EXE，Mac 用 DMG，Linux 用 AppImage。安装前建议在终端执行 node --version 和相应的 CLI 版本命令，确认底层已就绪。

环境检测的细节

首次打开 PiDeck 时会自动进行环境检测，这是最关键的一步。程序会在系统路径和常见路径里查找 CLI 可执行文件，如果检测不到会给出安装指引。对于使用 NVM、PNPM 或类似版本管理工具的用户，往往需要手动指定可执行文件的路径。这里之所以容易出问题，是因为 NVM（Node Version Manager）等工具会把 Node.js 及其全局包安装在用户目录下的隐藏路径中，而非系统默认目录，导致 PiDeck 的自动扫描无法命中——这也是许多跨语言开发者在配置终端工具时的常见坑点。

在「设置 → 开发设置」中可以自定义路径、设置检测标记并触发重新检测。填好路径后点击「校验并使用」，看到绿色的 CLI 状态就说明配置成功了。本集结束前，务必确认四件事都已完成：Node.js 已装、CLI 已装、PiDeck 已打开、环境检测通过。

配置模型与认证：两种方式别混淆

环境通了还不够，还得告诉 PiDeck 用哪家模型、API Key 怎么填。教程特别强调要先配好模型再开项目——因为 Agent 启动后需要立刻能对话，模型没配好，项目开了也发不出有效请求。

PiDeck 提供两种配置方式，切勿混淆：

• Models（模型页）：适合自定义供应商、中转服务或 OpenAI 兼容接口。需要填写 Base URL、API 类型和 API Key，再获取或手动添加模型列表。
• Auth（认证页）：面向官方直连的提供商，如 DeepSeek 等。多数情况下只需填 API Key，不用自己拼 Base URL。

这一区分背后是当前 AI 模型接入生态的两种典型形态。「OpenAI 兼容接口」已成为事实标准——包括 DeepSeek、通义、众多开源模型部署工具在内的服务，大多提供符合 OpenAI API 规范的 Base URL 与调用格式，使得客户端只需切换 URL 和 Key 即可对接不同模型。而所谓「中转服务」，则是第三方在官方 API 之上搭建的代理层，通常用于统一计费、绕过地域限制或聚合多家模型。理解这一点就能明白为何官方厂商走 Auth（直连、免拼 URL），而中转与自定义供应商走 Models（需手填 Base URL）——两者对应了直连与代理两种不同的网络路径。

简单记住分工：官方厂商优先走 Auth，中转或自定义接口走 Models。在 Models 页配置时，可以先点「配置指南」，填完信息后一定要点「保存」才会生效。

值得一提的是，配置保存后，切换模型的入口在对话输入框底部（而不是顶部），点击模型名即可切换模型和思考级别。这是新手最容易找错的地方。

添加项目与第一次对话

环境和模型都就绪后，就可以添加本地项目了。点击左侧顶部的加号，选择一个本地项目目录，项目就会出现在左侧列表中。

需要注意的是，加完目录不会自动开始对话，还要手动启动 Agent。启动方式有几种：可以在侧栏项目行点加号，也可以在中间空白页点「启动 Agent」按钮，或在右上角新会话区域启动/重启。启动成功进入会话界面后，才能选模型、发消息。

把前四集串起来，完整的基础闭环是：装 Node → 装 CLI → 装 PiDeck → 环境检测 → 配置 Models/Auth 并保存 → 添加项目 → 启动 Agent → 底部选模型 → 发送消息。确认左侧有本地项目、Agent 已启动、底部能切换模型、能收到回复，基础闭环就完成了。

对话进阶：让提问更高效

发消息只是起点。教程第五集讲了一套更稳的提问方式，核心原则是从具体问题开始——不要只说「帮我看看代码」，而要说清目标、文件和约束，比如「看看某个文件有什么问题」或「给登录页加深色模式切换」。

几个实用功能值得掌握：

• 文件引用：在输入框输入 @ 即可选择项目文件，文件内容会直接进入上下文，无需复制粘贴。
• 斜线命令：输入 / 会弹出可用命令列表，常用的 compact 用来压缩上下文、腾出 token，还有会话相关命令可自行探索。
• Shell 命令：输入 ! 加命令（如 !git status）会在当前项目目录执行，输出回到对话区，适合快速核对状态、看 diff、跑测试。

这里出现的「上下文」（Context）是理解 AI 编程工具的关键概念。大模型每次生成回复时，都会把之前的对话、引用的文件内容一并作为输入，这个输入总量受「上下文窗口」限制，以 Token（约等于 0.75 个英文单词或更少的中文字符）为单位计量。当对话变长、引用文件变多，Token 会逐渐逼近上限，导致模型「遗忘」早期信息或响应变慢。这正是斜线命令 compact 存在的意义——它会将冗长的历史压缩为摘要，腾出 Token 空间。同理，教程建议「任务换主题时开新会话」，本质上也是为了避免无关上下文占用宝贵的窗口容量并干扰模型判断。

回答支持 Markdown 和流式显示，下方的活动轨迹会展示 AI 读了哪些文件、跑了哪些命令、改了哪些代码。推荐的工作流是：底部确认模型和思考级别 → @ 相关文件并提出具体需求 → 看活动轨迹和修改结果 → 用 !git diff 核对变更 → 任务换主题时开新会话，避免上下文污染。

PiDeck 进阶功能：释放全部潜力

如果只用对话功能，据教程估算大概只用了 PiDeck 三成的能力。收官集快速盘点了几项进阶特性：

• 多项目工作区：左侧可添加多个本地项目随时切换，各项目上下文互不影响。
• Git 版本管理：右侧可查看分支、变更和提交记录。
• 内置终端：底部可选 PowerShell、cmd、Git Bash 等，与对话里的 ! 命令都在当前项目目录下执行。
• 会话历史：这是相对命令行最直观的提升之一，可按项目浏览历史、一键恢复上下文，也能导出记录归档。
• 提示词商店：内置中文提示词精选，支持分类搜索和一键导入。

小结

与裸 CLI 相比，PiDeck 保留了全部原生能力，并补上了多项目图形管理、会话历史可视化、Git 与终端面板，以及配置图形编辑器。对于每天在多个项目间切换、被终端会话管理折磨的开发者来说，它是一个值得尝试的效率工具。加之免费、开源、无厂商锁定的特点，也让它成为新手入门 AI 编程工作流的一个不错起点。感兴趣的读者可前往其 GitHub 项目页进一步了解。

核心要点