pideck-doctor

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 自身的排障）。
• 报告里的路径是 ~ 缩写：需要真实路径定位时，请用户在应用内通过「设置 → 打开数据目录」 查看，而不是要求贴完整路径。