故障排查与反馈

报错是什么意思、日志在哪、怎么报 bug。

agent 起不来

Tab 里会显示一条错误，写明是哪个 agent、去哪装，还有一个 Retry。Kumo 在开始对话前会先检查 CLI 在不在、能不能跑，缺失的 agent 只在这一个地方报告。

通常是这几种情况之一：没装；装了，但不在 app 继承到的 PATH 上；装了，但版本太旧，没有 Kumo 需要的模式。Settings → Agents 会显示它找到的版本。

agent 起来了，但拒绝干活

这是登录问题，归 CLI 自己管。打开终端，在那里登录（命令见配置 agent），然后按 Retry。Kumo 没有给 agent 用的登录，不保存任何 API key，这件事它帮不了你。

这一轮失败了

失败的这一轮会单独成一个气泡，在你的消息下面写着 agent 自己给的原因。再发一次，或者换个说法。如果是 agent 的进程崩了，Kumo 会自己用同一个会话重启它几次（间隔 1、4、16 秒）。

Tab 卡住了

右键 tab → Reopen Agent（⇧⌘R）。它会停掉进程，用同一个会话重新启动。tab、名字和历史都在；排队的消息不保留，确认框里会写明。如果这个 agent 的 CLI 不能恢复会话，确认框会改口说明：历史还留在屏幕上，但 agent 不会记得。

`Runtime is down`

窗口和 runtime 断开了。会出现一条横幅，带一个重新启动它的按钮；Kumo 不会自己反复重试。

这时 agent 不会丢。它们的进程托管在 runtime 之外，所以 runtime 回来后会重新连上所有还活着的 agent，从原来的地方接着来。真的已经死掉的会变灰，等你点它的 tab 或给它发消息时再回来。

`Restart runtime to finish the upgrade`

窗口和 runtime 的协议版本对不上，通常是更新之后旧 runtime 还占着 socket。Kumo 一般会悄悄把它换掉；换不了的时候，横幅会来问你。重启 runtime 不会停掉你的 agent。

agent 是灰的，写着 `asleep`

正常现象。闲置 30 分钟的 agent 会被关掉进程以节省内存，对话还在。给它发一条消息，几秒钟就醒，显示为 Waking up · 3s。在 Settings → General 里可以改超时时间或关掉。

Mac 重启之后，每个 agent 都是灰的，直到你点它的 tab 或给它发消息。Kumo 不会在开机时一口气拉起二十个进程。

`Free is full here`

公测结束后，Free 有数量限制（见套餐）。被拒绝的操作会写明是哪一项，已经开着的一切照常工作。关掉不再需要的东西，或者升级到 Personal。

手机上显示 `Linked`，但 tab 全是空的

你手上的页面比它连着的 runtime 旧。手机页面随每次发版更新；升级前缓存下来的页面，每个请求都会因为协议不匹配被拒绝。重新加载页面（因为是主屏幕 app，要强制刷新），还不行的话就重新配对。

Offline 是另一回事：连接真的没有回应，正在重连。Subscription ended 表示这台 Mac 的套餐不包含 Remote Control。

通知一直收不到

macOS 会在 Kumo 第一次需要发通知时询问，而不是第一次启动时。如果你当时拒绝了，Settings → General 里会有一行说明，以及一个直接跳到系统设置对应位置的按钮。app 没法自己给自己打开这个权限。

手机上，只有添加到主屏幕的页面才能收到通知。在 Safari 标签页里，iOS 连问都不会问。

日志

~/Library/Logs/kumo-runtime.log
~/Library/Logs/kumo-gui.log

记录启动、停止、方法名、错误，出错时偶尔附一小段 prompt 或气泡的摘录。不记录：完整对话、协议帧、终端输出、附件。

退出

关窗口（⌘Q、红点、Dock → Quit）：只关窗口。agent 继续跑，菜单栏图标还在。
菜单栏 → Quit Kumo：全部停掉：agent、终端、runtime、窗口。会先问你。

报告 bug

Issue 放在公开的发布仓库里： github.com/wiseria-ai-labs/kumo-release/issues。

最快的入口是 Settings → About 或应用菜单里的 Report a bug。它会把两份日志合成一个文件放进剪贴板，再打开 issue 表单，版本号、macOS 版本和日志末尾都已经填好。在表单里粘贴，文件就作为附件加上了。

公测期间有奖励。每个被我们标上 confirmed 的 issue，都能换一个月的 Kumo Personal，每个账号最多 12 个月，公测结束时统一发放。功能建议同样欢迎，但不计入。

最好写上：你做了什么、期望发生什么、用的是哪个 agent CLI，以及崩溃或卡住时的日志。功能想法请走 About 里旁边那个 Request a feature。