使用指南
如果你没用过 pi 或类似的 AI 编码助手，这份指南会从零开始带你走完从安装到完成第一个任务的完整流程。
什么是 PiDeck？什么是 pi？
pi 是一个命令行编码助手工具——你在终端输命令，它理解你的项目代码，能帮你写代码、改代码、解释代码。
PiDeck 是一个桌面应用，相当于给 pi 配了一个图形界面。它让你不需要一直盯着终端，而是可以在一个窗口里：
- 同时管理多个项目的 pi 对话（像聊天软件一样）
- 查看项目文件和 Git 分支
- 在有需要的时候打开终端
- 用可视化的方式配置 API 密钥和模型
简单说：pi 是"干活的大脑"，PiDeck 是"干活的桌面"。
第一步：安装 pi
PiDeck 本身只是一个桌面外壳，所有编码能力来自 pi，所以必须先安装 pi。
什么是 pi？
pi 是一个类似 Claude Code、Cursor 的命令行 AI 编码助手。它运行在你本地的项目目录里，能读取你的代码文件、帮你修改代码、执行命令、回答代码问题。
如何安装 pi？
pi 的安装方式在它的官方文档里有详细说明。安装完成后，在终端验证：
pi --version如果能正确显示版本号，说明 pi 已经可用。
💡 安装 pi 时，它通常会自动配置一个 API 密钥（例如 Anthropic 或 OpenAI 的密钥）。如果你已经配好了，PiDeck 可以直接使用这个配置。
第二步：安装 PiDeck
下载安装包
访问 PiDeck 的 GitHub Releases 页面：
https://github.com/ayuayue/PiDeck/releases
找到最新版本，根据你的操作系统选择：
| 操作系统 | 推荐下载 |
|---|---|
| Windows | 安装版：PiDeck-Setup-x.x.x.exe / 便携版：PiDeck-x.x.x.zip |
| macOS | PiDeck-x.x.x-arm64.dmg（Apple Silicon）或 PiDeck-x.x.x-x64.dmg（Intel） |
| Linux | PiDeck-x.x.x.AppImage 或 PiDeck-x.x.x.deb |
下载后直接运行安装程序。
首次启动
第一次打开 PiDeck 时，它会自动检测系统里有没有装 pi。如果检测成功，你会看到主界面。
如果检测失败：
- 点击左下角的齿轮图标 ⚙️ 打开设置
- 在设置页里找到 pi 路径 设置
- 手动填写 pi 命令的完整路径（例如 Windows 下的
C:\Users\你的用户名\AppData\Roaming\npm\pi.cmd） - 点击保存，重启应用
第三步：认识主界面
打开 PiDeck 后，你会看到三个主要区域：
┌──────────────┬──────────────────────────────────────┬──────────┐
│ 左侧栏 │ 中间（主区域） │ 右侧栏 │
│ │ │ │
│ 项目列表 │ 聊天对话面板 │ 文件树 │
│ Agent 列表 │ 消息时间线 │ 或 │
│ 历史会话 │ 输入框（底部） │ 会话历史 │
│ │ │ │
│ 底部： │ │ │
│ 设置 终端 │ │ │
└──────────────┴──────────────────────────────────────┴──────────┘左侧栏——项目与对话
左侧栏是主菜单。这里从上到下分为：
- 项目列表：每个你添加的本地项目目录显示为一行
- Agent 列表：每个项目下正在运行中的 Agent 会话
- 历史会话：以前运行过的、已关闭的对话记录
每个项目默认只显示最近 5 个（Agent + 历史会话混排），点击 "查看更多" 可以展开。
中间——聊天区
选中一个 Agent 后，这里显示你和 pi 的对话：
- 消息时间线：你的问题和 pi 的回复依次显示
- 输入框：在底部输入你的需求，按快捷键发送
右侧栏——文件与工具
右侧可以切换显示：
- 文件树：当前项目的目录结构
- 会话历史：该项目的所有历史会话
第四步：开始你的第一个任务
添加项目
- 点击左侧栏顶部的"+"按钮
- 在弹出的对话框里选择你的代码项目文件夹
- 项目会出现在左侧栏
创建 Agent 会话
- 点击项目右侧的"启动 Agent"按钮
- PiDeck 会启动一个 pi 进程，加载你的项目
- 几秒钟后，中间的聊天面板就准备好了
选择模型
在顶部工具栏，你可以：
- 点击模型名称（如
claude-sonnet-4-20250514）切换模型 - 点击思考等级调整 AI 的推理深度
如果你是第一次使用，默认模型通常就可以了。
发送第一条消息
在底部的输入框里输入你的需求，例如：
帮我看看这个项目是做什么的或者：
帮我解释一下 main.go 文件的结构按发送键（快捷键可以配置：Enter 发送 / Ctrl+Enter 发送）。
pi 会开始思考，你会看到：
- 思考过程（thinking）：AI 在推理时的内部思路
- 工具调用：AI 在读取文件或执行命令
- 最终回答：AI 给你的回复
继续修改
你可以在同一个会话里继续提需求，pi 会记住上下文。
第五步：日常工作流
新建一个会话
如果你不想在当前对话里继续，可以：
- 点击顶部"新会话"按钮 → 选择"新会话"
- 这会启动一个新的 Agent 进程，旧的对话仍然保留在历史里
恢复历史会话
- 在左侧栏找到你要恢复的会话
- 点击它，PiDeck 会重新打开这个会话
- 你可以查看历史消息，也可以继续发送新消息
关闭 Agent
右键点击左侧栏中的 Agent → 选择关闭。
Agent 关闭后，它会在左侧栏消失，重新变为可点击的历史会话。
重命名会话
右键菜单或顶部操作可以重命名会话，方便以后查找。
常用技巧
斜线命令
在输入框里输入 /，会弹出命令建议菜单：
/compact— 压缩上下文（长时间对话后释放 token 空间）/session— 查看或管理当前会话信息
Shell 命令
如果只是想快速执行一个 Shell 命令而不想打开终端：
!command— 执行命令并将结果发给 AI!!command— 执行命令但不将结果发给 AI
例如：
!git status
!ls -la文件引用
输入 @ 可以搜索并引用项目里的文件。
选择模型
不同任务适合不同的模型：
- 日常编码：Claude Sonnet / GPT-4o
- 复杂推理：Claude Opus
- 节省成本：Claude Haiku / GPT-4o-mini
- 快速测试：Gemini Flash
配置 API 密钥
如果你需要在 PiDeck 里配置密钥（而不是用 pi 的已有配置）：
- 点击左下角齿轮 ⚙️
- 进入 Auth 页面
- 点击 "添加认证"
- 选择供应商（Anthropic、OpenAI、DeepSeek 等），或手动输入
- 填入你的 API Key
- 点击保存
我该用哪个 API？
- Anthropic Claude：编码能力最强的选项之一，适合日常开发
- OpenAI GPT：通用能力强，生态最成熟
- DeepSeek / 其他：价格更低的替代选择
如果你不确定，建议先从 Anthropic Claude 或 OpenAI GPT 开始。
常见问题
启动报错："pi 未检测到"
- 确认 pi 已安装并在终端可以运行：
pi --version - 在设置里手动填写 pi 路径
- 重启 PiDeck
发送消息后没有响应
- 检查网络连接
- 确认 API 密钥有效
- 查看设置 → 日志页，看是否有错误信息
- 尝试重启 Agent
历史会话内容空白
这是旧版本的一个 bug，v0.6.2 已修复。如果仍有问题，请重启应用。
Agent 运行中卡住了
点击聊天面板上方的停止按钮（停止图标 ⏹），可以终止当前请求。
如何更新 PiDeck？
- 设置 → 检查更新
- 如果有新版本，点击下载
- 下载完成后运行安装包更新
下一步
- 功能介绍 — 了解 PiDeck 的所有功能
- 配置与 Skills — 深入学习配置管理
- 更新日志 — 查看各版本变化