故障排查

首次启动警告、终端边缘情况、运行时故障状态，以及阅读或导出诊断信息。

本页汇总了值得了解的一些"毛边"——首次启动警告、若干终端怪象、运行时故障状态，以及在你需要提交报告时如何阅读或导出诊断信息。

首次启动安全警告

由于构建未签名，你首次运行 Cordy 时操作系统会发出警告：Windows SmartScreen（"更多信息 → 仍要运行"）与 macOS Gatekeeper（右键点击应用 → 打开 → 确认打开）。各操作系统的完整步骤见安装。若右键 → 打开之后 macOS 仍然拒绝，请先确认你已把应用移入 应用程序 文件夹，然后重试。

运行时问题

运行时是拥有你终端与智能体的后台进程。它的状态以一个小小的指示条显示在右下角；点击它可展开一个"Runtime Monitor（运行时监视器）"面板。运行时首次进入故障状态时，Cordy 还会显示一条"Runtime unavailable（运行时不可用）"toast。

Runtime: binary missing（运行时二进制缺失）

指示条显示 Runtime: binary missing，展开面板会列出它尝试过的每一个路径。

源码构建？ 构建运行时：pnpm runtime:build（或 pnpm dist，它会把运行时打包进去）。见安装。
打包构建？ 重新安装一个完整构建，或用 CORDY_RUNTIME_BIN 把应用指向某个运行时二进制。解析顺序见运行时。

Runtime: incompatible（运行时不兼容）

指示条显示 Runtime: incompatible，附带类似"expected X, got Y"的细节——运行时的协议版本与当前应用构建不匹配。这发生在应用与运行时二进制来自不同版本时。请从匹配的源码重新构建运行时，或重新安装一个匹配的应用构建。

Runtime: crashed（运行时崩溃，以及崩溃循环）

指示条显示 Runtime: crashed，并附带退出码与信号。Cordy 会以指数退避（1s、2s、4s……上限 30s）自动重启运行时，并在运行时健康满一分钟后重置该退避。真正的崩溃循环会表现为 crashed 反复出现且重启计数不断增加，而不是一个单独的状态。若它始终无法稳定下来，请导出一个诊断包（见下文）并查看 runtime.log——重启历史记录在那里，并能在重新启动后依然保留。

重启运行时

Runtime Monitor 面板有一个 Restart（重启） 按钮。若有智能体或终端处于活动状态，它会先行确认（"Restarting the runtime will stop N running agents and all terminal sessions"），因为重启运行时会结束这些会话。

终端边缘情况

有少数终端行为是已知的，值得了解。除特别说明外，这些都在跟踪以待日后修复。

完整重新启动后终端错乱

现象。 在完整退出并重新启动 Cordy 之后（而非收起到托盘），恢复的终端可能显示一个 [previous session restored] 横幅，且布局错乱——顶部有空白、智能体的输入框画在了 shell 提示符之上，或出现一行重叠。

原因。 收起到托盘会让运行时与你的 PTY 保持存活，因此以那种方式返回时会干净地重新挂接。完整重新启动则没有可重新挂接的活动会话，于是渲染进程会重放本地保存的最后屏幕快照，而这种冷重放无法完美重建全屏（备用屏）TUI 的布局。

该怎么做。 终端仍然可用——错乱只是视觉上的。运行 clear（或按 Ctrl+L）重绘，或打开一个新的终端标签页。若想彻底避免，当你希望恢复同一套智能体布局时，请优先选择收起到托盘，而非完整退出。

中文 IME（拼音）输入

终端中可靠的中文 IME 输入已在 0.1.2 中随版本发布：长拼音句子不再丢失或重复字符，候选窗口也会保持锚定，而不再追逐全屏 TUI 的重绘。该修复始终开启。

在全屏智能体 TUI 中使用微软拼音时，仍有两种狭窄情形可能丢字，且正在跟踪：先输入一个英文单词、再一个空格、再输入中文（边界字符可能被吞掉）；以及从中文候选窗口中选取一个英文候选。这些源自底层终端组件。若你遇到，重新输入受影响的字符即为规避办法。

语音或听写输入无法抵达终端

现象。 某个第三方听写工具能正常把文字输入到 Cordy 自己的输入框（笔记、设置），但其文字无法抵达智能体终端。

原因。 有些听写工具通过一种非键盘的"粘贴"路径注入文字，而 Cordy 的终端并不将其识别为粘贴，于是该按键被编码送往 shell，而不是被粘贴。

该怎么做。 启用该工具的 "模拟键盘输入"（或等效）模式。在该模式下，输入会以真实的按键事件送达，并能正常抵达终端。

Ctrl+C：复制还是中断

在终端中，Ctrl+C 仅在有选区时复制；在没有选区时它始终作为中断（SIGINT）发送。该规则是有意为之，且不会改变。

在全屏智能体运行期间有一处小插曲：智能体 TUI 常会启用鼠标上报，这会禁用普通的点击拖拽选择——于是 Ctrl+C 没有可复制的选区，便始终执行中断。要在这种情况下复制，请按住 Shift 拖拽以强制形成一个选区，然后按 Ctrl+C。（Ctrl+Shift+C 目前尚未接线到复制，因此请用 Shift 拖拽后再按 Ctrl+C。）

诊断

Cordy 会保留本地日志与一份滚动的指标历史，供你查看与导出——在提交错误报告时很有用。

性能监视器

从顶栏的 CPU 图标打开性能监视器。它显示实时的 CPU 与内存图表、按进程的分解、运行时状态、活动计数器，以及一个 Export（导出） 按钮。采样贯穿应用的整个生命周期，因此当你去查看时历史早已就绪。

日志与崩溃转储的位置

一切都写在 Cordy 的用户数据目录下（各操作系统的确切位置见隐私）：

项目	位置	说明
应用日志	`logs/main.log`	控制台输出、诊断事件与崩溃栈。到 2 MiB 轮转，保留 3 份。
运行时日志	`logs/runtime.log`	Rust 运行时的输出流。相同轮转策略。
结构化事件	`diagnostics/events.jsonl`	机器可读的事件历史。
崩溃 minidump	`Crashpad/`	原生崩溃转储。绝不上传——未配置任何服务器。

导出诊断包

在性能监视器中点击 Export。Cordy 会在 diagnostics/exports/ 下写入一个带时间戳的文件夹，其中包含：

diagnostics.json——应用与环境信息、指标历史，以及运行时重启历史；
events.jsonl——最近的结构化事件；以及
main.log 与 runtime.log——各自日志的尾部。

写入导出前路径会被脱敏：绝对文件路径变为 [redacted-path]，路径样式的元数据变为 [redacted]。该导出仅为本地文件写入——不会向任何地方传输任何内容。面板会向你显示该文件夹在磁盘上的路径；请你自行把该文件夹附加到错误报告中。Cordy 保留最近十次导出，并清除更早的。