疑难排查
解决 Cordy Desktop 的安装、更新、运行时、终端、笔记、浏览器、项目工具与诊断问题,并提交反馈。
除非某节写明其他版本,本页描述 Windows 上的 Cordy Desktop 0.6.0。macOS 与 Linux 构建为 0.5.3;见安装。
安装警告
- 「Windows 已保护你的电脑」:Windows 安装程序未做代码签名,因此 SmartScreen 会警告。先校验下载,选择更多信息,确认应用名,再选择仍要运行。不要关闭 SmartScreen 或 Microsoft Defender。
- Apple 无法验证该应用(macOS 0.5.3):macOS 构建未经公证。选择完成,然后打开系统设置 → 隐私与安全性 → 仍要打开。
- AppImage 无法启动(Linux 0.5.3):用
chmod +x赋予可执行权限。0.5.3 的沙箱启动与 AppImage 挂载未经完整验证;如仍无法启动,请改装.deb包。 - 没有适合我机器的构建:目前没有 Windows on ARM 构建,也没有 Intel Mac 构建。
完整步骤与下载校验方法见安装。
更新之后
Cordy 没有自动更新器。在旧版本之上安装新版本即可,数据会保留。
- 数据转换:0.5.4 转换了使用独立检出的工作区,0.5.5 把 Markdown 笔记转换为块笔记。每项转换只在首次启动时执行一次,并保留原件的字节副本(
.pre-upgrade-<stamp>文件),Cordy 永不删除这些副本。 - 转换后不支持退回旧版本。由更新版 Cordy 写入、当前版本无法读取的快照会被完整地移到一旁,而不是被覆盖。
- 好像少了东西:查看用户数据目录中的
project-workspace/project-workspace-migration.log。它记录每次转换,以及 Cordy 拒绝读取或移到一旁的每个快照,并写明保留副本的路径。目录结构见隐私与数据。
运行时状态
运行时状态指示器显示 Runtime: <state>;运行时首次失败时,Cordy 还会显示一条 toast。
- unresponsive:运行时仍在运行,但已有数秒没有响应。它一旦响应就会回到
ready。如果一直无响应,请重启运行时。 - binary-missing:找不到运行时二进制文件;Cordy 会列出它尝试过的路径。请重新安装 Cordy。
- incompatible:应用与运行时协议版本不同。请重新安装 Cordy,使两者来自同一构建。
- crashed:Cordy 使用从 1 秒到最多 30 秒的指数退避重启运行时。反复崩溃会出现在诊断日志中。
手动重启运行时会停止所有运行中的终端与智能体会话,因此 Cordy 会先警告 "Restarting the runtime will stop N running agent(s)"。见运行时。
终端输入
- Shift+Enter 提交而不换行:Cordy 按程序请求的键盘协议转发按键;Shift+Enter 是否换行由 CLI 决定。Codex 与 Claude Code 把它解释为换行。见终端。
- 在接管鼠标的 TUI 中复制:按住 Shift 拖动,再按 Ctrl+C 或 Ctrl+Shift+C;macOS 也可用 Option 拖动强制选择。
- Ctrl+C 中断:普通 Shell 中,没有选区时它是中断。CLI 请求 kitty 键盘模式后,由 CLI 接收并解释按键事件。
- 快捷键抢走了 Shell 按键:在设置 → 快捷键 中关闭该快捷键的 In terminal 开关,或重新绑定。见键盘快捷键。
- Ctrl+Alt+方向键旋转了屏幕:部分 Intel 显卡驱动用它旋转屏幕。请在设置 → 快捷键 中重新绑定 Next tab 与 Previous tab。
- 中文 IME 或听写:支持组合输入与无键码粘贴。如果输入丢失,提交反馈时请写明所用 IME 以及你输入的程序。
[process exited N - press Enter to restart]:Shell 崩溃或被终止,或该标签已固定。按 Enter 重启;之前的输出保留在[session restarted]上方。[previous session restored]:完整退出后,它标记本地恢复的终端历史,下方是新 Shell。旧进程已不再运行;请重新启动智能体。
笔记
- 笔记不再保存:一篇笔记最多容纳 1,100,000 个字符和 150,000 个元素。超出上限时,你的编辑仍留在屏幕上,提示会说明超出多少,Show what's over the limit 可带你定位。回到上限以内后会继续保存。
- 发送被拒绝:多行代码只会发送给开启了括号粘贴的程序;可选择 Paste first line 或 Copy instead。含控制字符的代码永远不会发送;发送还需要一个程序仍在运行的已打开终端。
- 导入没有添加任何内容:导入会让笔记超出上限,因此没有添加任何内容。
- 链接打不开:链接必须以
http://或https://开头,且不含用户名或密码。
见笔记。
浏览器
- 权限被拒:Cordy 只询问剪贴板读写与全屏。摄像头、麦克风、地理位置和未列出权限会按策略拒绝。
- 站点仍保持登录:使用设置 → 站点数据 → 退出登录清除该主机,或清除全部浏览数据。
- 密码填充不可用:激活一个协议、主机与端口均和保存凭据完全匹配的内置浏览器标签。
- 下载目录不对:检查设置 → 下载,包括每次询问保存位置。
项目工具
- Search tool not available:ripgrep 随 Cordy 一同提供。如果搜索报告找不到它,请重新安装 Cordy。
- 提交按钮不可用:至少暂存一个文件,解决所有合并冲突(Mark resolved),输入提交信息,并等待正在运行的 Git 操作完成。原因会显示在按钮下方。
- 改动列表被截断:列表最多显示 2,000 行。隐藏行不能从面板暂存或丢弃;请在终端使用 Git,或缩小工作集。
- History moved while loading:在 Graph 中选择 Refresh history,从当前分支顶端重新开始。
诊断
紧凑性能概览提供 2 分钟、10 分钟与 1 小时图表,并有 View details 操作。Workload 部分只在 Windows 可用。
打开设置 → 诊断查看本地日志与存储占用。Export log bundle 会创建 ZIP;时间范围可选 Last hour、Last 24 hours、Last 7 days 或 Everything,内容可选主进程日志、运行时日志、诊断事件与系统信息。
完整性能监视器另有 Export diagnostics,会写出带时间戳的本地诊断包,其中包含:
- 应用与环境信息、指标和运行时重启历史;
- 最近的结构化事件;
main.log与runtime.log的尾部。
两种导出都会脱敏绝对路径与类似路径的值。Cordy 不会上传任何一种;请检查内容后自行附到问题报告。用户数据目录中的 logs/ 保存日志,diagnostics/ 保存事件,Crashpad/ 保存原生崩溃转储。
反馈与支持
报告问题在 GitHub 使用该产品的问题表单,表单会询问版本与平台。功能建议说明它要解决的问题。反馈文档问题本站内容缺失、错误或不清楚。发送邮件dsdev.cn@gmail.com不适合用表单提交的事项。报告安全漏洞通过 GitHub 安全通告私下报告,不要公开提交 issue。
安全问题请通过私密安全公告表单报告,不要提交公开 issue。