dsh-go 排障与反馈

这个技能只做一件事：先把事实拿到，再下结论。App 自己会写一份本机诊断，路径和管理规则见全局指令的「本机诊断」一节——先读它，再按下面的清单走。不要凭"可能是……"就开药方。

1. 先读诊断

# 使用可用的文件读取工具读取以下路径（不要输出整份诊断到外部）：
# $DSH_HOME/dsh-app/diagnostics.md        自动环境快照
# $DSH_HOME/dsh-app/diagnostics-manual.md 用户主动发布的报告（存在时优先核对）
# direct 启动时路径带 rootfs 前缀，以 AGENTS.md 为准

这是 App 从自身状态、Android 可获得的信息和运行时日志采集并写出的有限快照，可能包含版本、设备、运行时、连接、性能、App 捕获的最近错误及引擎/失败日志尾部；部分来源不可用或信息过期时会缺失。Markdown 有大小预算，日志只保留有限尾部，不是完整历史。

App 捕获的完整错误信息仍是本进程内有限的内存记录；新版本另将错误类别和少量自有源码位置、内容无关的语音阶段有界持久化。Android 11+ 可按系统可用性提供本应用历史进程退出原因，不读取退出描述或原始 trace。这些记录不是完整崩溃堆栈；缺失、不可用或空结果不能当作正常证据。诊断包也不是系统 logcat：普通 App 对其他应用和系统日志的读取受 Android 权限与版本限制，不能假定有全系统日志或绕过权限。确需 logcat 时，先说明范围与隐私风险，由用户自行选择合法可用的采集方式；不同 Android 版本、设备和权限下内容可能不同。

• 先核对可用报告的生成时间、App 版本和设备是否与本次反馈一致；另一台设备或旧时间的报告不能当成本次现场。优先读取本次手动报告，再用自动快照补充环境。只有可用报告都缺失或过旧时才请用户到 设置 → 诊断 → 让 AI 看诊断 发布，再读；不要因另一个文件缺失反复要求刷新。旧版只有主快照也是正常情况。
• 新版本提供 mcp__phone__diagnostics 时，用户要求排障即可先自行调用：默认 refresh:true，按 section 取 summary、evidence、appErrors、voice、engine 或 failure，不用先读屏或开启手机操控。核对 collectedAt、refreshed、code，失败不能把旧快照说成本次现场；refresh:false 只读缓存。每段有界且可能标记 truncated。工具不采系统输入法证据、不导出任意路径、不替用户对外发送。工具缺失或不可用时再读已有快照，不反复调用逼用户开启权限。
• 信息不足时可请用户通过诊断功能导出 ZIP：它由同类采集结果生成，包含摘要、设置，按可用性包含崩溃分类、引擎/失败日志尾部和 App 错误；日志仍有上限，并非日志全文或完整 crash 细节。用户检查后自行保管或上传，不替他发。

用户点 让 AI 看诊断 后，只原子写入同目录固定的 diagnostics-manual.md 手动报告，供 AI 读取本次采集的系统输入法证据；自动刷新只写 diagnostics.md，两者不互相覆盖。分别核对生成时间、设备与版本，不把旧手动报告当新现场；旧版只有主快照时读已有文件，不推断故障不存在。路径与主快照相同的目录，direct/safe 模式同样按 AGENTS 指示定位。

读诊断之前先自己看，不要先问用户一堆问题；诊断里没有的信息再问。

2. 按症状查

闪退 / 语音回复时退出

• 先读 evidence 和 voice：对照错误位置、语音阶段与进程退出时间，区分原生崩溃、异常退出或内存回收。请求播放不等于已播放；没有系统堆栈就直说未知，不把模型回复错误等同 App 崩溃。
• 自动故障分析默认关闭，用户明确同意后才会将内容白名单内的结构化事实发送给本机引擎模型（可能计费），不会发送原始日志、录音、正文、凭据或系统输入法证据。分析会话没有工具，不自动修复、不公开发 issue；失败/结果不明不自动重试，关闭或切主机后不发新请求，已发送无法撤回。
• 分析记录读写失败时，自动分析暂停；诊断页的本地恢复入口仅恢复记录、跳过已留存故障，不向模型重发旧请求。不要通过删除用户设置、重放 prompt 或擅自清数据来绕过。

卡顿 / 掉帧 / 不跟手

先分清楚是"App 界面"还是"引擎/模型"慢：

• 诊断看 性能（档位、温度）、环境（运行时状态是其中一行，本机 vs 远程）、最近错误。
• 本机引擎 + 大任务（npm install、大量文件）会跟 UI 抢 CPU，界面卡是正常的，建议切远程主机或等任务结束。
• 长回复流式输出时卡：查看回复长度、代码块数量；这是渲染成本，不是网络。
• 让用户试一次 设置 → 性能 → 轻量（关模糊/动效/桌宠），如果立刻好转，就是特效成本，不是引擎。
• 高刷设备可在 设置 → 性能 → 刷新率 选「系统」或「自动」再对比；选「最高」时低端机更容易掉帧。
• 仍然卡：请用户记下"哪一页、什么操作、持续多久"，并导出诊断包。

发热 / 耗电

• 本机引擎常驻 + 手机操控（无障碍/悬浮条）+ 桌宠 + 高刷是主要来源；诊断看 环境 是否 running、设置 里自动起本机/可视化回复/手机存储。
• 不用时让用户停止本机引擎（设置 → 本机引擎 → 停止），或改用远程主机；手机操控不用时关掉。
• 看诊断 性能 里温度档位；长时间流式输出本身就会热，属正常。
• 不要建议用户改系统电池优化/无障碍权限来"提速"——那类改动先解释清楚再让用户自己点。

连不上远程 / 一直"重新连接中"

• 先确认：主机端和手机端登录同一个账号；主机端插件在跑（/remote status 在主机侧看）。
• 主机端同时开两个 TUI/两个 dsh 实例共用同一个 DSH_HOME 会互相顶掉连接（插件会暂停自动重连）——这是最常见的"手机在线但连不上"。让用户只留一个实例，或给第二个单独的 DSH_HOME。
• 局域网/P2P 不通会回落 TURN/Relay，延迟高但能连；诊断看 连接。
• 需要主机日志，让用户在主机上导出或粘贴相关几行；不要在手机端猜。

引擎起不来 / 进了安全模式

• 诊断看 环境 的 phase、error、safeReason、strikes，以及 内置运行时 / 已装 是否一致。
• 常见原因：运行时没装好、存储不足、插件把启动搞崩（安全模式就是为这个准备的）、direct 启动失败回退 proot。
• 先让用户在 设置 → 本机引擎 页点重试或以安全模式启动，并看日志里的失败原因（只有运行时没装时才点安装运行环境；不要和「重置」混用——重置会删除对话、工作区、插件和设置，见 docs/guide/zh/03-engine-hosts.md）；插件问题引导到 设置 → 插件 停用最近装的。
• 需要更多线索：请用户导出诊断包；其中仍只有有限日志，缺失不代表没有发生。

更新装不上

• 先看 App 里能不能直接更新：1.0.16 起支持经 Shizuku 或自连 ADB 直接安装更新，也能导出已下载的安装包自行安装；入口在更新提示与 设置 → 通用 → 检查更新 相关页。
• 系统安装确认页不出现 / 被当作取消：国产 ROM（HyperOS、ColorOS 等）常见；让用户从 GitHub Release 手动下载 dsh-go-<版本>-arm64.apk 安装，或在系统设置里允许本应用安装未知来源。
• 安装包解析失败：多半是下载不完整，重新下载并对照 SHA256SUMS。

引擎被系统杀掉后自动重启 / 上一轮中断

• 1.0.16 起引擎异常退出会尝试自动重启；若通知里出现「已重启」一类的提示，说明恢复过一次，不是新的故障。
• 上一轮正在生成时进程被杀，回复可能停在半截；让用户重新发送或重试，不要据此判断模型或网络坏了。
• 反复重启：导出诊断包，看 最近错误 与 环境 的 phase/strikes；仍起不来按上一节「引擎起不来」处理。
• 排查启动方式：诊断 › 开发者选项 里能看到 direct/proot/tawcroot 等启动路径；tawcroot 是加速启动的方式，失败会回退，不要把它当成故障本身。

插件不生效 / 设置页空白

• 让用户确认插件是否装到了当前主机、当前 profile，插件市场里状态是否 enabled。
• 远程主机的插件在主机上，不在手机上；App 里只是入口。
• 插件把引擎搞崩 → 会进安全模式；停用插件再启动。

输入法 / 键盘异常

• 先读现有快照与用户已给的信息；只补问缺少的复现步骤、发生时间或输入法。不要重复询问已经给出的环境，不要求输入或发送真实聊天内容。核对快照时间与事件是否对应。
• 区分用户观察到的失焦、键盘隐藏和输入连接关闭，保留观察但不要混为同一件事。普通快照不包含完整焦点/键盘事件；本次系统证据记录的是已知显示/隐藏请求或连接关闭，并不直接证明键盘实际可见性，也不能证明 Flutter 输入框发生了重建。
• 基础信息不足且当前版本支持时，可以提出更高权限的只读诊断：先说明用途、采集范围及隐私风险，询问用户意愿，再由用户亲自在原生确认界面批准本次采集。它只复用已配置且正在运行的高权限通道，读取近期由本 App 进程输出的系统输入法请求并返回有限的结构化事件（显示/隐藏请求或输入连接关闭、时间、来源及可识别的原因），不返回原始系统日志行；既有通道授权不等于本次诊断许可。不要主动触发系统权限申请；通道不可用、用户拒绝、取消或采集失败时如实说明，不当作故障证据，也不绕过授权。
• 用户完成一次采集后，点 让 AI 看诊断，再读取快照里的系统输入法证据；需要更多有限事件时再导出 ZIP。采集结果只留在 App 内存，清除或重启后不再保留；已导出的文件不被撤回。不要循环采集、跑压力测试或擅自装测试 APK。
• 事件不含输入正文，原始日志仅在采集时瞬时读取并丢弃；其他日志、截图和诊断包仍可能含隐私。Android 12 或部分 ROM 可能不产生匹配日志；noEvents、未知原因或缺少 fromUser 不是正常证据，也不能把未知当成 false。证据不足时明确说明，不单凭这些事件归责输入法、App 或系统。

手机操控失败

• 检查诊断中的手机操控与无障碍状态；未就绪或未采集不等于已关闭。信息不足时再问用户，部分 ROM 可能自行关闭无障碍服务。
• 敏感页（密码/支付）读不到是系统策略，不是 bug；让用户 handoff。
• 悬浮条异常：让用户关掉再开一次手机操控。
• 多个任务同时跑：后台任务有上限，超出时后提交的会排队或被拒；让用户等前一个结束，或减少并行。
• 想确认链路通不通：设置 → 手机操控 里有自检；自检失败按它指出的那一项处理，不要拿别的项替它下结论。
• 实时后台预览看着不动/发黑：先确认不打扰模式和后台上限，再看诊断 手机操控（本机） 一节，不要直接说是无障碍坏了。

3. 生成反馈（issue 草稿）

用户要反馈时，给他一份可直接粘贴的草稿，不要替他发：

## 环境
- App：<版本> (<构建号>)
- 设备：<厂商 型号> · Android <版本> (SDK <n>)
- 运行时：<内置版本> / <DSH 版本> / Node <版本>，启动方式 <proot|direct>
- 连接：<本机 | 远程 | 未连接>

## 现象
<一两句话>

## 复现步骤
1. …
2. …

## 期望 / 实际
…

## 诊断
<诊断文件里相关的几段：最近错误、性能、连接；完整包见附件>

• 环境部分直接从诊断抄，不要手编。
• 完整诊断包（zip）让用户自己附到 GitHub issue 或发给维护者；包里有引擎日志，不要经过你转发。
• 提醒用户：贴之前扫一眼有没有自己的路径、账号名、设备名不想公开。

4. 隐私红线

• 诊断会尝试脱敏，但不能保证无遗漏；路径、设备型号、账号昵称、聊天内容截图和日志仍可能暴露个人信息。分享前请用户人工检查并决定保留或遮盖什么。
• 永远不要把 token、API key、验证码、聊天正文原样复述、回显或写进文件。
• 不要在没问过用户的情况下：改系统设置、装/卸应用、清数据、重启引擎。

5. 什么时候说"够了"

• 诊断 + 用户三句话能复现 → 给草稿即可，不要再要日志。
• 诊断缺失、日志对不上、只在特定网络/机型出现 → 才让用户导完整诊断包。
• 拿不准就先说"现有数据还不能定位"，再列一个下一步要什么；不要一次列五条。