故障排查

这个页面用于快速定位常见问题。用户可以先按现象查找，再按建议操作。

键盘扩展打不开或自动回到系统键盘

用户应先确认当前宿主 App 是否允许第三方键盘。部分密码输入框、支付页面和安全输入场景会强制使用系统键盘。如果普通输入框也失败，用户可以重启宿主 App、切换系统键盘再切回，或重启设备。

这通常是键盘扩展启动时布局没有完成或系统中断绘制。用户可以记录 iOS 版本、设备型号、键盘页面和是否刚安装 App。开发版可以通过键盘扩展启动诊断日志检查每个阶段的布局高度。

用户应确认同一 Apple ID、iCloud 权限、网络、完全访问和 CloudKit Production Schema。用户可以在主 App 中手动刷新同步。如果发布版本不同步，而调试版本同步，需要优先检查 CloudKit Production Schema 是否已部署。

用户应确认 Markdown 文件不是空文件。App 侧应该使用同一个 Markdown 渲染器处理 Markdown 编辑页、文件格子编辑预览和 macOS 空格预览，避免某个入口只显示纯文本。

视频预览可能只显示首帧。如果首帧本身是黑色，App 可以使用更靠后的时间点生成封面。用户点击播放后应能看到视频内容。

如果 .pkdrawing 在 iOS 和 macOS 之间打开后黑白反转，说明语义色解析不一致。App 应让 iOS 和 macOS 使用同一套语义色 sidecar 和渲染逻辑。

macOS 中选中文件格子按空格可以打开预览。再次按空格应该只关闭预览窗口，不应该关闭主窗口。如果焦点被预览窗口抢走，App 需要在窗口级别处理空格关闭。