功能操作手册
这份手册按界面区域梳理 PiDeck 的全部功能点：每个按钮、菜单、右键菜单、快捷键在哪、怎么用、解决什么问题。 刚接触从哪里下手？先读 完整使用指南。想了解设置项含义？见 配置与 Skills 与 问题排查指南。
界面总览
┌───────────────┬─────────────────────────────────────┬──────────────┐
│ 左侧栏 │ 会话 Tab 栏 / 会话头部 │ 右侧抽屉轨 │
│ (项目/会话/ │ 消息时间线 │ (文件/源代码 │
│ 搜索/设置) ├─────────────────────────────────────┤ 管理/轨迹/ │
│ │ 输入框(Composer) │ 检查点/ │
│ ├─────────────────────────────────────┤ 浏览器) │
│ │ 终端 Dock (可选) │ │
└───────────────┴─────────────────────────────────────┴──────────────┘- 左侧栏：管理项目、会话，全局搜索，设置入口。
- 中央区：会话 Tab（可多开、分屏）＋聊天时间线＋输入框＋可选终端。
- 右侧抽屉：文件树、Git、运行轨迹、检查点（回滚）、内置浏览器。
一、左侧栏
顶部入口
| 功能 | 位置 | 怎么用 | 说明 |
|---|---|---|---|
| 折叠/展开侧栏 | 栏顶 Logo 旁面板图标 | 点击 | 收起侧栏为窄条，再次点击展开；收起后会话 Tab 栏最左会出现展开按钮 |
| 新建会话 | 栏顶第一个 + | 点击；或 Ctrl+N（macOS Cmd+N） | 直接打开新会话引导页（Ctrl/Cmd+N 在输入框/编辑器聚焦时不触发，避免误操作） |
| 全局搜索 | 栏顶 Search 图标 | 点击；或 Ctrl+F（macOS Cmd+F） | 打开居中命令面板，跨项目检索会话与项目；输入时同步驱动下方列表过滤 |
导航 Tab（活动 / 聊天 / 项目）
三枚药丸按钮切换左侧栏视图，选择会记住：
- 活动：当前运行中的 Agent 会话列表（跨项目）。点击打开预览，双击固定为常驻，右键打开菜单。
- 聊天：聊天会话树。所有会话（草稿 / Agent / 历史 / 归档）按项目分组展示。
- 项目：项目工作区树。项目、Git worktree 工作区、每个项目下的会话。
聊天视图
- 区块标题：点击折叠/展开整个区块。
- 区块右侧
+：新建普通会话。 - 展开/折叠全部（标题上两条折叠图标）：一键收起/展开所有项目。
- 区块
⋯菜单：匿名会话、会话管理（批量归档/删除）、修改聊天记录保存目录。 - 会话行（聊天区每行）：
- 点击 → 在中央区打开预览；双击 → 固定为常驻 Tab。
- 状态点颜色：运行中（黄）/ 空闲（蓝）/ 错误（红）。
- 行尾徽标：后端（pi / DSH / Codex / Claude / OpenCode / 生图）、匿名标识、固定标识、子 Agent 数（点击展开子 Agent 列表）。
⋯/ 右键 → 会话菜单（见下方）。- 拖拽会话行到聊天区边缘 → 创建分屏。
- 查看更多/收起：每项目默认显示最近 5 条，点击底部按钮翻页。
- 来源过滤（项目行悬停 Filter 图标）：按会话来源过滤该项目历史（pi / codex / claude / opencode / dsh / imagegen 等），状态本地记忆。
项目视图
- 添加项目（标题右侧
+）：选择或输入本地目录。项目空态页也有「添加项目」按钮。 - 项目行：点击展开并选中；拖拽调整排序（持久化）；目录缺失显示黄色徽标。
- 项目行悬停：
+→ 新建会话；⋯→ 项目菜单；- Filter → 来源过滤。
- 项目菜单（右键或
⋯）：
| 菜单项 | 说明 |
|---|---|
| 新建：普通会话 / 匿名会话 | 匿名会话：临时对话，不写入保存目录（关闭即回收） |
| 在文件管理器中定位 | 打开系统资源管理器 |
| 打开方式 | 用已配置的外部编辑器 / 浏览器打开项目 |
| 复制项目路径 | 复制绝对路径 |
| 重命名项目 | 仅顶层普通项目可重命名 |
| 会话管理 | 批量归档 / 删除 |
| 技能 & 扩展 & 提示词 | 打开项目资源弹窗，管理该项目级技能、扩展、提示词模板 |
| 过滤历史记录 | 来源筛选 |
| 刷新项目 | 重新扫描目录 |
| 启用/关闭工作区 | 把项目登记为 Git worktree 工作区（非 Git 仓库会提示） |
| 导入会话 | 导入 Codex / Claude / OpenCode 本地会话 |
| 删除目录记录 | 危险区。有运行中 Agent 时阻止删除；worktree 子项目走「删除工作区」流程 |
- 主工作区行：启用工作区后，顶层显示主工作区分组（分支名 + 项目名）。
- 新建工作区（「其他工作区」标题
+）：为分支创建独立 Git worktree 目录，创建后可并行开发同一仓库的不同分支。 - 工作区子项目行：分支名 + 目录提示，悬停
+/⋯操作与普通项目一致。
会话菜单（右键 / 悬停 ⋯）
| 菜单项 | 说明 |
|---|---|
| 重命名 | 就地编辑会话标题 |
| 置顶 / 取消置顶 | 固定到列表顶部（持久化） |
| 复制会话 | 复制为新的会话副本 |
| 导出 HTML | 导出会话为网页（DSH 会话不支持）；也可在会话时间线入口做 |
| 复制会话文件路径 / 打开会话 JSONL | 调试用；按文件是否存在显隐 |
| 重启会话 | 重启 Agent 进程（运行中可用） |
| 重新加载会话 | 仅对没有运行中进程的会话可用 |
| 会话代理 | 为该会话配置转发代理 |
| RPC 日志 | 仅运行中会话：开启后记录 Agent RPC 通信，可新窗口查看 |
| 关闭 Agent / 删除会话 | 关闭进程 / 删除会话（确认弹窗） |
| 归档会话 | 移入归档；在「会话管理」里可恢复或删除 |
底部 Dock
- 设置（齿轮）：打开设置弹窗；有可用更新时带红点。
- 反馈（气泡图标）：打开意见反馈页。
- 官网：打开 PiDeck 官网。
- 主题切换：循环浅色 / 深色 / 跟随系统 / 定时切换。
注：终端面板在中央区底部，不在左侧栏。
二、中央会话区
会话 Tab 栏
- 新建（末位
+）：下拉选择「聊天对话区」或任一已打开项目新建会话。 - 关闭：点 Tab 上的
×，或中键点击 Tab。 - Tab 右键菜单：固定/取消固定、关闭、关闭其他、关闭全部。
- Tab 排序：拖拽 Tab 到目标位置；拖到聊天区边缘创建分屏窗格。
- Tab 自动分组：按项目归组（组间竖线分隔）；后打开的会话自动归入所属项目组尾。
- 分屏组胶囊：点击展开/收起；右键重命名、选组色、取消分屏。
- 预览 Tab（斜体）：双击晋升为常驻会话。
- 更多操作
⋯：停止、重启、重新加载当前会话；下方是工具入口（终端、草稿纸、打开方式等，激活项打勾）。 - 抽屉开关（Tab 栏右端面板图标）：开/关右侧抽屉。
会话头部
- 面包屑：
项目名 / 会话标题，悬停看全名。 - 匿名徽章：无项目绑定的「聊天对话区」显示。
- DSH 工具按钮（仅 DSH 会话且 Agent 已启动）：打开工具面板 —— 目标（进度/暂停/恢复/完成/清除/新建）、子代理、技能。
- 权限预设胶囊（DSH 草稿期）：选择权限预设；激活后锁定显示。
- 退出分屏（分屏窗格上的最大化按钮）：退出分屏布局。
输入框（Composer）
发送
- 右下圆形主按钮：空闲时是发送箭头；Agent 忙碌且输入为空时变停止方块（停止当前请求）；生图模式显示进度。
- 快捷键：按设置里的「发送快捷键」—— 裸 Enter、
Ctrl/Cmd+Enter或Shift+Enter发送；其余 Enter 为换行。规划模式下裸 Enter 固定发送。
引用与命令（输入框内键入触发）
| 输入 | 作用 |
|---|---|
@ | 文件引用：弹出项目文件树补全，连续 /目录/ 下钻；选中后成为文件芯片，点击可查看/移除 |
& | 会话引用：弹出同项目历史会话选择器，勾选消息后把历史内容注入当前对话 |
其他输入能力
- 图片粘贴 / 拖入：显示缩略图，点击放大预览，
×移除；大文本粘贴会转为「粘贴文件」芯片。 - 方向键历史：光标在首行按
↑、末行按↓浏览发送历史，越过最后一条恢复当前草稿。 - 划选消息文本 → 浮动「引用并提问」：把选中内容作为引用芯片追加进输入框。
底栏按钮
+菜单：附件（生图模式下隐藏）、技能、提示词模板、模式切换（普通 / 目标 / 规划 / 生图；特殊模式底栏出现退出×）。- 模型 / 思考 chip（底栏中央）：
模型 · 思考档位。点击弹出模型选择器（搜索、按供应商分组、星标收藏、用量徽标、刷新列表）或思考档位选择器（off → max）。运行中切换模型显示「旧 → 新」，当前轮结束后生效；需要重启的会弹确认。 - 后端切换（底栏左下 logo）：pi / DSH / 生图。会话激活后锁定（避免运行中换后端）。
- 安全等级（底栏左下）：pi 会话选安全门等级（off / standard / strict）；DSH 显示权限预设。
- 上下文圆环（发送钮旁）：显示上下文占用；点击展开面板：两段占比、缓存命中、token 明细、回复性能、用量查询、压缩入口。
- Git 分支 chip（底栏右侧）：当前分支，点击切换（切换前弹确认）。
排队消息卡
Agent 忙碌时仍可输入多条，形成排队卡。行内按钮：
↑插入当前轮（作为当前请求的补充）；☰排队下一轮；⑂并行发送（开独立侧面会话，见「并行问询」）；✎撤回进输入框；×丢弃。
统计条
输入卡下方：轮数/步数、耗时、首字延迟、tps、累计 token、缓存命中。仅当前会话统计。
消息与时间线
- 悬停操作栏（hover 消息出现）：复制（主钮复制纯文本；箭头菜单选纯文本 / Markdown / 图片）、分享、编辑、删除；用户消息另有重发、从此处分支（fork）、回滚到此。
- 执行过程折叠栏：
N 次工具调用 · N 次思考。流式时自动展开，历史默认收起；最终回答常驻。 - 工具调用卡：图标 + 工具名 + 状态（运行/成功/失败/停止）+ 耗时 + 语义短语。点击展开：
- 文件类：内联 diff，「打开文件」跳转编辑器；
- 命令输出：复制按钮；超长输出「查看完整输出」；
- 问询卡（ask_question）：逐题回答。
- 安全确认卡：文件/命令类高权限工具会弹「允许执行 / 拒绝」。
- 代码块：右上角复制按钮；文件路径可点击打开。
- 回到底部按钮：滚动离开底部时，右下角出现圆形按钮。
- 大纲预览轨道（会话区左上缘）：竖排条带（本地文案「会话定位」），悬停预览标题/时间，点击跳转到对应消息；随流式更新。各条目可拖拽调整位置，底部可「显示全部」。
信息条（输入框上方）
- 目标条：当前目标 + 相位（进行中 / 已暂停 / 受阻），可暂停 / 恢复 / 清除（需确认）。DSH 目标模式。
- 待办条：从 Agent 待办卡同步，显示已完成/进行中数量。
- 文件条：本轮修改的文件，展开看 diff，「保存全部」;行尾可打开文件 / 独立 diff 查看器。
- 子代理条：运行中的子代理；行内「打开子会话」跳转、「查看完整结果」弹窗。
并行问询（Ask 面板）
从排队行「并行发送」触发。面板会：
- 创建一个匿名会话（独立子进程，与当前会话并行，不打断当前输出）；
- 可用
@引用上下文（经模型可见、UI 不可见的通道注入）； - 回答显示在独立浮动胶囊里，可复制、把回答插入主会话输入框、继续追问、关闭（关闭即回收匿名进程）。
其他面板与入口
- 草稿本：
Ctrl/Cmd+Shift+S开关（会话 Tab 栏工具区也有按钮）。新建/删除草稿、Markdown 模式、任务复选框、导出文件。草稿随会话保留。 - 轨迹面板：右侧抽屉「轨迹」tab—— 按轮次 + 活动车道展示输入/模型/工具事件。
- 检查点（Rewind）：右侧抽屉「检查点」tab—— 见下文。
- 会话起始页：无消息时居中大输入框 + 项目切换器，提供完整底栏能力。
- 首次信任确认：打开项目目录时弹「拒绝 / 仅本次信任 / 信任并记住」（安全设置可调整）。
三、右侧工作区抽屉
抽屉开关：会话 Tab 栏右端按钮；开关状态按项目记忆。
抽屉轨道（面板切换）：顶部分组按钮 —— 文件、源代码管理（设置开启 Git 管理且有项目时显示）、轨迹、检查点（仅 pi 后端）、内置浏览器。点击打开/切换；再点一次关闭当前面板。
- 宽度拖拽：拖抽屉左边缘分隔条（240–560px，跨重启记忆）。
- 折叠面板（收成细栏）→ 右侧
←展开。 - 钉住面板（图钉）：按项目记住当前面板；钉住后不可关闭/切换。
- 关闭（
×或面板标题栏）。
文件面板
- 文件树：单击文件 = 中间栏预览 Tab（斜体）；双击 = 常驻编辑 Tab；目录单击展开/收起。
- 右键菜单（文件/目录/空白）：加入对话引用（
@相对路径）、默认方式打开、在文件夹中显示、复制路径、粘贴文件到此处、重命名、删除（进回收站 + 确认）。 - 工具行：排序（名称/修改时间/创建时间/大小 + 升降序）、折叠中间包（深目录链压成一行）、打开文件夹、刷新、收起全部。
- 拖放：OS 文件拖入 = 复制到目标目录；树内拖拽 = 移动；面板内
Ctrl/Cmd+V粘贴剪贴板文件。
中间栏文件编辑
- 显示模式：split（左右分屏）/ maximize（内容占满），查看器头部按钮切换；可拖拽分隔条调宽度。
- 编辑 Tab：最多 5 个；双击预览 Tab 转常驻；
×关闭。 - 文本编辑（CodeMirror）：行号、代码折叠、自动换行、括号匹配、查找（
Ctrl+F）、JSON 即时校验、注释（Ctrl+/）；编辑 500ms 自动保存，Ctrl/Cmd+S立即保存；未保存显示●。 - 预览：Markdown（GitHub 风格 + KaTeX 公式）、HTML（沙箱 iframe，可切到内置浏览器）、SVG/图片/PDF；二进制文件提示不支持；超过 5MB（可配置）提示文件过大。
- Diff 查看器（只读）：分栏/单栏切换；从修改文件列表、提交内文件、工作区变更等打开。
path:line链接：打开文件并定位到行；编辑器选中文本右键「引用选中内容」→ 插入@path:行号到输入框。
Git 面板（源代码管理）
- 分支切换（顶部当前分支按钮）：下拉选分支切换；底部「创建分支」输入名称创建并切换；非 Git 仓库显示
+（git init）。 - 仓库切换：多个仓库时顶部下拉（VS Code SCM 风格）。
- 变更区三组：合并冲突 / 暂存区 / 工作区变更；组头折叠 + 计数 + 组级全部暂存/取消暂存；目录头悬停可目录级暂存/丢弃（带确认）。
- 文件行内按钮：
+暂存、−取消暂存、↺丢弃改动（确认）、📄 打开到中栏编辑；点击文件名打开 diff；右键删除文件（进回收站 + 确认）。 - 工具栏：收起/展开全部、刷新、Push（领先数角标；无上游时提示复制
git push --set-upstream）、Pull（落后数角标）。 - 提交：消息框（
Ctrl/Cmd+Enter提交）＋「提交」按钮（无暂存时弹「暂存全部并提交」，可选 是/总是/从不 并记忆）。 - AI 提交信息（✨）：基于暂存文件生成提交说明（需先暂存；未配置模型时提示去设置）。
- 提交历史图（泳道图）：最多 8 道 6 色。提交行显示作者/信息/分支 tag 徽章；点击展开该提交文件列表（点文件看 diff）；悬停 500ms 显示详情卡（作者/邮箱/时间/完整消息/±行数）；「加载更多」每次 +30 条。
- 提交行右键：Cherry-pick、Revert、Soft/Mixed/Hard Reset（确认）、Drop（危险确认）。
- 分支对比：基准 → 目标 + 「比较」→ ahead/behind、文件数、文件列表（A/D/R/M 着色）。
浏览器面板
- 地址栏：回车导航；无协议自动补
https://。 - 多标签：
+新建（默认 PiDeck 首页）、点击切换、×关闭；标签状态跨抽屉/全屏保留。 - 导航：后退/前进/刷新/主页。
- 设备预设：PC / iPhone（移动 UA）/ iPad（平板 UA），切换 UA 并限制视口。
- 全屏：头部最大化进入全屏浮层（点空白关闭）；全屏时可最小化回抽屉或关闭。
- 新窗口：http(s) 链接在应用内开新标签；mailto 等非 http 协议抛给系统浏览器。
轨迹面板
展示当前会话的运行轨迹（消息/工具事件，按轮次分车道）。无会话时空态;底部「加载更多」。
检查点（Rewind）面板
- 检查点列表：自动（回合/工具触发）+ 手动快照，倒序展示：触发类型徽章、工具名/回合数、相对时间、变更摘要（文件数 + ±行）。
- 查看变更：每条右侧 diff 按钮，展开该检查点与当前工作区的差异。
- 恢复（undo 按钮下拉三选）：
- 仅文件：工作区文件回到检查点状态（覆盖当前改动不可撤销；清理新出现的未跟踪文件；忽略目录不受影响）；
- 仅对话：只回退对话内容；
- 全部：文件 + 对话，含对话范围会在新会话分叉（原会话保留）。
- 恢复均有确认弹窗。
- 刷新 / 加载更多：手动刷新 + 分页。
- 边界：仅 pi 后端会话支持；DSH / 生图会提示不支持。
四、底部终端 Dock
- 打开/关闭：会话 Tab 栏工具区「终端」按钮。归属按 owner 隔离：有 Agent = Agent 终端；无 = 项目终端；切换会话不串台。局域网 Web 预览模式不提供。
- 多 Tab：
+新建（当前 shell）；点 Tab 切换；×关闭（已退出显示「· 已退出」）；「关闭全部」带确认。 - Shell 选择（header 下拉）：PowerShell / CMD / Zsh / Bash / Fish / Sh / Git Bash / WSL；不可用置灰。
- 主题（header
⋯）：pi-soft（亮/暗）、Solarized（亮/暗）、One Dark、Monokai。 - 折叠/展开：header 折叠按钮；高度拖拽 120px 起，全局记忆。
- 右键：有选区 = 复制（toast 提示）。
- 其他：URL 点击走系统浏览器；滚动回看 5000 行；shell 退出显示退出码。
五、快捷键速查表
| 快捷键 | 作用 | 生效区域 |
|---|---|---|
Ctrl/Cmd+N | 新建会话 | 全局（输入框聚焦时跳过） |
Ctrl/Cmd+F | 打开全局搜索 | 全局（输入框聚焦时为编辑器内查找） |
Ctrl/Cmd+Shift+S | 开关草稿本 | 全局 |
Ctrl/Cmd+S | 保存当前文件 | 文件编辑器/配置编辑器 |
Ctrl/Cmd+Enter | 提交 Git 消息 / 发送消息（按设置） | Git 面板 / 输入框 |
Enter | 发送或换行（按「发送快捷键」设置） | 输入框 |
↑ / ↓ | 历史输入导航（光标在首/末行时） | 输入框 |
Ctrl+/ | 注释 | 文件编辑器 |
| 中键点击 Tab | 关闭会话 Tab | 会话 Tab 栏 |
| 双击会话行 / Tab | 预览转常驻 | 左侧栏 / Tab 栏 |
| 拖拽到聊天区边缘 | 创建分屏 | 会话行 / Tab / 文件 |
所有按钮均有
title提示；悬停 1–2 秒可见。快捷键按平台为Ctrl（Windows/Linux）或Cmd（macOS）。
六、输入语法速查
| 输入 | 作用 |
|---|---|
@路径 | 引用文件（@/src/... 连续下钻） |
&关键词 | 引用历史会话消息 |
| 粘贴/拖入图片 | 附带图片提问（模型需支持图片） |
七、设置与配置入口速查
- 系统设置（左栏底部齿轮）：外观、代理、Web 服务、编辑器、Git 提交、开发/更新、飞书、桌面宠物、存储与日志、用量统计、进程监控、视觉桥、生图 —— 详见 配置与 Skills。
- 配置管理（设置弹窗顶部可切到「配置管理」分区）：pi / DSH 后端的模型、认证、settings.json、信任、MCP、Raw 源文件、安全（工具确认）、扩展、技能、提示词。
常见问题处理请看 问题排查指南。