问题排查指南
遇到问题时按下面的路径走，大部分情况都不需要看日志。如果这里没有覆盖你的问题，可以用文末的诊断报告把自己环境的信息打包导出，再带着报告找人帮忙。
0. 通用排查套路（先做这三步）
- 重启应用：很多状态（Agent 进程、监听器、会话缓存）卡住时，重启一次往往直接恢复。
- 看版本：设置 → 开发 → 「检查更新」，确保你在最近版本。历史 bug 大多已修复。
- 生成诊断报告：设置 → 开发 → 诊断报告 → 点击生成。报告包含脱敏后的环境信息、体检项、最近报错日志，不包含代码和密钥内容；导出后可直接发给维护者或贴到 Issue。
一、启动与安装
启动时提示「pi 未检测到」
- 先在终端确认 pi 可用：
pi --version - 设置 → 开发 → Pi CLI 状态卡 → 「检测环境」重新扫描
- 若自动检测失败：在「自定义 Pi 路径」填完整路径（如 Windows 下
C:\Users\你的用户名\AppData\Roaming\npm\pi.cmd）→ 「验证路径」 - Windows WSL 用户：在「Pi 来源」切换为 WSL，选择发行版并「验证用户」
应用黑屏 / 白屏 / 图标不出来
- 先重启应用；
- 检查设置 → 外观 → 主题是否被切成不兼容的皮肤；
- 仍异常：设置 → 开发 → 「打开数据目录」并查看应用日志（见文末「日志在哪」）；
- 若与应用杀毒软件冲突（Windows）：尝试关闭 Chromium 沙箱开关（设置 → 开发 → 运行 → Chromium 沙箱，默认关闭是刻意的，改动需重启应用）。
窗口行为怪异（启动了多个实例 / 关不掉）
- 设置 → 常用 → 窗口：检查「关闭到托盘」—— 关闭窗口可能只是收进托盘而非退出；
- 单实例开关改动需重启应用生效；PiDeck 的不同版本可以并行运行（按版本互斥），不要误判为 bug。
界面语言、字体不对
设置 → 外观：语言在「常用设置」；字号、缩放、分区字号都在「外观设置」。
二、会话与 Agent
Agent 起不来 / 一直转圈
- 点击右侧抽屉「轨迹」或左侧会话右键 RPC 日志 查看 Agent 通信情况；
- 检查 模型配置：配置管理 → 模型，确认模型可用（「连接测试」按钮）；
- 检查 RPC 超时：设置 → 开发 → 运行 → RPC 超时（最小 600 秒），网络慢的机器调大；
- 检查 代理：设置 → 代理 → Pi 代理 / 「按模型走代理」名单；
- 试试「重启会话」（会话右键菜单）。
发送消息后没有响应
- 确认 Agent 是 空闲（蓝点） 状态；忙碌（黄点）时消息会进排队卡，看队列状态与行内按钮（插入当前轮 / 排队下一轮 / 并行发送 / 撤回 / 丢弃）；
- 点右下角停止按钮终止当前请求（如果卡在长任务上）；
- 检查网络 / API Key：配置管理 → 认证；
- 查看日志：设置 → 缓存与日志 → 应用日志 / RPC 日志。
模型切换不生效
- 运行中切换模型：当前轮结束后生效，会显示「旧 → 新」；
- 提示需要重启的（比如切到不支持热切换的模型）：点确认重启 Agent；
- 模型列表空 / 拉不到：配置管理 → 模型 → 「刷新列表」或「远端拉取」；检查桌面端代理是否影响模型拉取。
会话消失了 / 找不到历史
- 左侧栏「聊天」Tab 下每个项目默认只显示最近 5 条，点「查看更多」；
- 可能被归档：聊天区块
⋯→ 会话管理 → 归档视图里恢复； - 按来源过滤了：项目行 Filter 图标清除过滤；
- 仍找不到：检查聊天记录保存目录设置（聊天区块
⋯菜单）。
会话内容空了 / 时间线错乱
- 旧版本有此类 bug，v0.6.2 已修复——先更新版本；
- 更新后仍异常：重启该会话（右键 → 重启会话）。
「并行发送」是什么？
Agent 忙碌时，排队卡上的「⑂ 并行发送」会开一个匿名独立会话回答该问题（不打断当前会话），回答显示在浮动胶囊里，可带回主线或继续追问。关闭即回收，不留历史记录。
三、配置、认证与网络
401 / 认证失败
- 配置管理 → 认证：确认供应商与 Key 正确（或 OAuth 重新登录）；
- 代理环境常见坑：请求走了代理但没有正确放行——检查设置 → 代理里 Pi 代理（影响 Agent 进程）与桌面代理（影响模型列表拉取、连接测试）是两回事，分开排查；「按模型走代理」名单内模型强制走代理、名单外强制直连；
- 用量查询类接口（
/usage等）报 401：用量查询按钮 → 用「通用模板 / New API 模板」配置；多数供应商已内置支持，无需配置。
模型列表是空的 / 拉不到
- 配置管理 → 模型 → 「刷新」；
- 检查「桌面代理」是否可用（模型目录从 GitHub 拉取）；
- 模型目录可手动更新：设置 → 开发 → 模型目录 → 「从 GitHub 更新」。
网络慢 / 海外资源访问慢
- 设置 → 代理：配好 Pi 代理 + 桌面代理；
- 下载更新慢：设置 → 开发 → 更新源 切换为 ghfast / ghproxy.net / CN 镜像 或自定义地址（默认 GitHub）。
四、Git 与文件
Git 面板不显示
- 设置 → Git → 「启用 Git 管理」开关（关闭时整个面板都隐藏）；
- 项目得是 Git 仓库：非仓库会显示初始化按钮（
+）。
提交失败 / push 失败
- 看错误信息里的具体原因（认证、网络、远端被改）；
- 无上游分支：工具栏提示复制
git push --set-upstream命令； - AI 提交信息（✨）失败：确认已暂存文件、模型可用（设置 → Git → Git 提交信息模型）。
worktree 工作区删除不掉
- 有运行中 Agent 时禁止删除（会阻止并提示）；先关闭该工作区上的 Agent 会话再删除；
- 「删除工作区」会顺带清理 Git worktree 目录。
文件打开是二进制 / 过大
- 二进制文件（图片等）用预览；代码/文本默认编辑器打开；
- 超过「最大编辑器文件大小」（默认 5MB，设置 → 开发 → 运行）会提示文件过大，可调大该值。
五、界面与布局
找不到某个面板 / 抽屉不见了
- 右侧抽屉：会话 Tab 栏右端面板图标开关；抽屉打开后顶部轨道切换 文件 / 源代码管理 / 轨迹 / 检查点 / 浏览器；
- 面板被「钉住」后不能切换/关闭：点图钉解除；
- 终端：会话 Tab 栏工具区「终端」按钮；
- 草稿本：
Ctrl/Cmd+Shift+S或工具区按钮。
对话框太大 / 太小 / 字体不合适
设置 → 外观：窗口缩放（0.8–1.5）、字号档位、分区字号（UI/聊天/输入框独立）、聊天内容宽度。
主题怪怪的 / 背景图没了
设置 → 外观 → 主题（系统/定时/浅色/深色）与皮肤主题、背景图片、背景不透明度（默认 80%）。定时切换的日出/日落时刻在「定时」里配置。
桌面宠物碍事
设置 → 桌面宠物：关闭开关 / 取消置顶 / 调缩放与巡逻间隔；宠物是纯娱乐组件，不参与任何编码逻辑。
六、性能与资源
内存占用高
- 设置 → 常用 → 闲置 Agent 内存优化：自动释放闲置 Agent（默认开）、保留数量（默认 5）、超时分钟（默认 60）——长时间不用的 Agent 会被回收，重新使用会重启；
- 设置 → 进程监控：查看每个 Agent 进程的内存，可直接「停止」异常进程（带确认）；
- 打开的项目/会话太多时，减少并行运行的 Agent 数量。
界面卡顿
- 大文件 diff / 长会话渲染是常见来源：关闭不需要的抽屉面板（轨迹/检查点）；
- 设置 → 缓存与日志 → 「清理界面缓存」（清空本地存储并整页刷新，不影响会话文件）。
Agent 卡住（不回应、不停止）
会话 Tab ⋯ → 停止 / 重启；仍无效 → 设置 → 进程监控 → 停止该进程；最后手段重启应用。卡死时的 RPC 日志对定位问题非常有用（记得先开启「RPC 日志」再复现）。
七、数据、日志与隐私
日志在哪
设置 → 缓存与日志：
- 应用日志 / RPC 日志：显示大小，「打开」日志目录（文件）、删除、内嵌查看器（等级过滤 + 搜索 + 时间范围 + 刷新）；
- 「清理全部日志」与「清理界面缓存」是分开的两个按钮。
会话数据存在哪 / 怎么备份
- 会话文件：设置 → 缓存与日志 → 打开数据目录；聊天记录保存目录可在聊天区块
⋯菜单修改； - 导出单个会话：会话右键/菜单 → 导出 HTML（DSH 不支持）。
隐私与遥测
PiDeck 默认发送匿名、低频的 app_heartbeat（版本分布/平台/活跃数量），不收集项目路径、代码、消息内容；可在设置 → 开发 → 隐私 → 遥测关闭。诊断报告导出前请确认不含敏感信息（报告本身已脱敏，但仍建议自查）。
八、更新与回退
更新下载失败 / 慢
设置 → 开发 → 更新源 切换网关（ghfast / ghproxy.net / CN 镜像 / 自定义）；Windows 可开「自动下载更新」（默认开）。
更新后出现新问题
- 先重启应用；若确认是新版本引入：GitHub Releases 下载上一版本重新安装（会话数据不冲突）；
- 反馈时请附上「诊断报告」+ 复现步骤。
九、各领域配置速查
| 症状 / 需求 | 去哪配置 |
|---|---|
| 图片识别（截图提问）不好用 | 设置 → 视觉桥（模型/接口/API Key/并发/超时） |
| 生成图片 | 设置 → 生图设置（供应商/模型/参考图模式） |
| 飞书机器人 | 设置 → 飞书机器人（「使用指南」弹窗含完整流程） |
| 用量/余额查询 | 用量查询按钮（通用 / New API 模板），或设置 → 用量统计 |
| DSH 后端 | 设置弹窗 → 配置管理 → DSH（安装/版本/模型/权限） |
| 外部编辑器 | 设置 → 外部编辑器（检测/路径/启用） |
| 局域网访问（手机预览） | 设置 → Web 服务（端口/QR 码） |
十、还解决不了？
- 生成诊断报告（设置 → 开发 → 诊断报告）；
- 到 GitHub Issues 搜索或新建 Issue（附报告 + 版本号 + 复现步骤）；
- 加入 QQ 群：1026218644 交流。
排查时先确认右上角/设置里的版本号，再对照 更新日志 看是否已知问题。