---
name: pideck-doctor
description: 排查 PiDeck 桌面应用的问题。当用户说「PiDeck 出问题了」「帮我诊断 PiDeck」「会话起不来」「pi 连不上」「应用报错」等时使用。引导用户在「问题反馈」页生成环境诊断报告并导出，读取诊断报告定位根因，结合故障模式库给出可执行的修复步骤。报告含脱敏后的环境信息、体检项、最近报错日志，不接触任何原始配置文件内容。
---

# PiDeck 环境诊断（pideck-doctor）

## 这是什么

用户在 PiDeck 里遇到问题（pi 连不上、会话起不来、卡顿、闪退、模型列表为空等）时，
本技能引导用户走一条**标准排障路径**，用一份脱敏诊断报告替代反复追问环境细节，
快速定位根因。

## 第一步：让用户生成诊断报告

请用户打开 PiDeck 的**「问题反馈」入口（侧边栏/帮助菜单 → 意见反馈 → 环境诊断 tab）**，
点击**「生成诊断报告」**，然后：

1. 描述问题现象，最好补充复现步骤；
2. 在「导出分享」里**复制报告**（Markdown 或 AI 提示词形态）；
3. 把报告粘贴给 AI（本会话）。

用户也支持直接导出 zip（含脱敏日志），但**尽量先拿 Markdown 报告**，zip 仅在报告不足以
定位时再要求（zip 里是逐行脱敏的日志，同样不含原始配置内容）。

## 报告包含什么

- **环境信息**：PiDeck 版本、安装形态（安装版/便携版/开发态）、OS 版本、Electron/Node/Chrome 版本、
  locale、时区、WSL/代理等开关状态（**只给开关布尔值，不给代理地址**）；
- **体检项**：pi 是否已装且可读版本、pi 配置（models/auth/settings.json）是否可解析、
  最近 7 天 error/warn 条数、数据盘剩余空间、主进程常驻内存、代理配置是否自洽、
  WSL 兜底是否自洽；
- **最近报错日志**：脱敏后的最新 warn/error（时间/级别/作用域/消息）。

所有路径都把 home 目录替换成 `~`，token/Key/邮箱/手机号一律替换为 `[redacted]`。

## 第二步：对照故障模式库定位

### pi 未安装 / 版本读不出来
- 现象：体检项 `pi.installed` 为 error/warn。
- 处置：引导用户检查自定义 pi 路径设置（可能指到了非 pi 程序）；安装正式 pi；Windows 上用
  WSL 兜底时确认发行版已填。定位到 `~/.pi/agent` 目录存在且 models.json 在。

### 配置损坏（models/auth/settings 解析失败）
- 现象：体检项 `config.parsable` 为 error，模型列表为空、会话起不来。
- 处置：**不要直接改配置原文**（可能含 apiKey）。先建议备份对应 json 到别处，
  再让用户在「配置管理」界面重新填写/重置。若 JSON 明显缺字段导致解析失败，
  可重建最小结构，但保留原有 key 值不动。

### 报错密度高（logs.errors 异常）
- 现象：`logs.errors` 为 error/warn，且 recent 里能看到具体错误作用域。
- 处置：读取 recent 报错，按作用域归类（rpc / agent / terminal / git / web 等），
  定位具体异常类型。若错误消息里出现路径/Key，已由脱敏替换，需结合上下文推断。

### 磁盘不足
- 现象：`disk.space` 为 error（< 512MB）或 warn（< 2GB）。
- 处置：引导清理数据目录（userData）或系统磁盘；会话/日志写不进去是闪退常见根因。

### 内存过高
- 现象：`memory.rss` 为 error（≥ 3GB）。
- 处置：多为内存泄漏或超大会话，建议重启应用、关闭大会话后复测。

### 代理自相矛盾
- 现象：`proxy.consistency` 为 warn（开了代理却没填地址）。
- 处置：在设置里填代理地址或关闭对应代理开关。

### WSL 兜底失效
- 现象：`wsl.config` 为 warn（开了 WSL 却没填发行版）。
- 处置：在设置里填发行版名，或关闭 WSL 兜底用原生 pi。

## 第三步：给出修复并复测

- 每给一条修复建议，都让用户**重新生成一次诊断报告**，对比相关体检项是否从 error/warn
  变为 ok——用数据验证修复是否生效，而不是猜。
- 若修复后仍异常，导出 zip 日志包，@群内支持者继续排查。

## 边界与隐私

- **只读诊断报告，不读原始配置**：报告已脱敏，绝不要求用户把 auth.json/models.json 原文贴出来。
- **不代替 pi 做 Agent 行为**：本技能只管 PiDeck 应用自身的安装/配置/环境问题，不处理
  pi 内部的模型调用/工具逻辑（那些属于 pi 自身的排障）。
- **报告里的路径是 `~` 缩写**：需要真实路径定位时，请用户在应用内通过「设置 → 打开数据目录」
  查看，而不是要求贴完整路径。