Troubleshooting

故障排查

📚 参考 · 🏠 首页 › Troubleshooting

---

📑 本页目录

• 0. 三步快速定位法
• 1. LLM 相关
• 2. 权限 / 设备能力
• 3. 终端 / Ubuntu
• 4. 记忆（cs-mem）
• 5. UI / 视觉
• 6. 构建 / CI
• 7. 报告问题时的必备信息
• 8. 相关页面

按症状查。每条给出"先看什么 → 再做什么"。没有覆盖的情况欢迎提 Issue 并附上运行日志屏导出。

0. 三步快速定位法

1. 运行日志屏：结构化日志（含分类与级别）是第一现场；
2. 缩小范围：同一件事换 Build 模式重试；能复现就大概率不是偶发网络抖动；
3. 先看是否为预期行为：很多"卡住"其实是设计如此 —— 例如批量执行首错即停是契约，不是 bug。

1. LLM 相关

现象	排查
一直提示"请先配置 LLM"	设置屏未完成配置或 Base URL 格式不对；NoOpLlmClient 是故意的降级
测试连接失败	Base URL 是否以 /v1 结尾；局域网 Ollama 是否 --host 0.0.0.0 且防火墙放行；端点是否需要自定义 header
能聊天但从不调用工具	该模型不支持 tool calling（看能力徽章有无 Tools）；或中转站剥掉了工具协议
思维链不显示	端点是否透传 reasoning_content；设置里的 showThinking 是否关闭
并行工具调用参数被截断	旧版本 index 累加 bug，已修；确认不是旧 APK
报"上下文已压缩"太频繁	单次工具输出过大；见 上下文压缩
响应极慢	模型/中转本身慢；或思考档位过高（ThinkingLevel=MAXIMUM / ReasoningEffort=MAX 会消耗大量 token）

2. 权限 / 设备能力

现象	排查
pm install 之类的命令失败	没有 Root 也没有 Shizuku → 已降级到沙箱 shell（预期行为），去 权限屏 授权 Shizuku
UI 自动化工具无响应	无障碍服务未开启或被系统杀；到权限屏重新授权
悬浮球不出现	未授予悬浮窗权限；部分国产 ROM 需要额外在"应用管理"里允许后台弹窗
Root 已刷但没识别到	PrivilegeDetector 依赖可用 su 与管理 App 授权；检查 su 版本与授权弹窗

3. 终端 / Ubuntu

现象	排查
execve: permission denied	targetSdk 28 红线；或装的是没带内置 rootfs 的包
一直卡在 rootfs 供给	内置版应完全离线；若用了按需下载，检查网络与磁盘剩余空间
apt 无法解析域名	rootfs 内 resolv.conf；宿主网络是否可用
终端输出乱码 / 方框字	需要支持 box-drawing 的等宽字体；检查 Compose 渲染层字体设置
会话重启后消失	会话恢复的是元数据而非进程（Linux 语义）；这是设计限制
编译/运行很慢	PRoot ptrace 开销 + 手机 CPU，属预期；大工程请用宿主或 PC

4. 记忆（cs-mem）

现象	排查
宏从不触发 0 token 回放	是否真的蒸馏成功 → 能量是否被衰减 → 是否被梦境剪枝；见 记忆生命周期
App 升级后宏集体失配	TopologyMigrator 是否跑过（梦境条件不满足就不会跑）→ migration_map 是否有记录
敏感操作没被记住	这是正确的安全行为，免疫 拦下了它
界面操作变卡	MemoryWriterActor 邮箱是否长期积压（有界 256 → 会背压）；摄取是否过于频繁

5. UI / 视觉

现象	排查
玻璃效果不明显 / 像贴了层灰	该组件是 Frosted 档（诚实降级，不采样背后内容），见 Liquid Glass
低端机上模糊很卡	API < 32 走 scrim 降级路径；实时采样本身有成本，检查是否在列表里滥用 Backdrop
抽屉里看到"Skill"屏	旧版本 Skill 屏，新版已合并进市场

6. 构建 / CI

现象	排查
gradlew: command not found	仓库没锁 wrapper，先 gradle wrapper --gradle-version 8.10
NDK / CMake 缺失	sdkmanager "ndk;27.0.12077973" "cmake;3.22.1"
质量门禁红（文件超预算）	拆文件，不要改阈值；见 质量门禁
工具 ID 重复红	改名或用命名空间前缀
rootfs 指纹校验红	三处 sha256 漂移：scripts/fetch_rootfs.sh 表 / rootfs-bundle.sha256 / BundledRootfsSource.kt
Windows 上脚本 \r 报错	用 LF 换行并在 Git Bash / WSL 中执行

7. 报告问题时的必备信息

① 设备型号 / Android 版本 / ABI
② App 版本（当前：1.4.4, code 19）
③ 是否 Root / Shizuku / 无障碍
④ LLM 端点类型（脱敏后）与模型名
⑤ 复现步骤（越具体越好）
⑥ 运行日志屏导出的相关片段（打码 Key/PAT！）

Caution

贴日志前务必删除 API Key、PAT、手机号、Cookie 等敏感内容。

8. 相关页面

• FAQ · 权限执行链 · 终端运行时
• 记忆生命周期 · 质量门禁 · 从源码构建

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}