安装与首次启动

本指南介绍如何在 Windows、macOS 与 Linux 上运行 Cordy Desktop——包括当前的源码构建路径，以及如何越过因构建尚未代码签名而在首次启动时出现的安全警告。

请先阅读。 Cordy 是早期软件（版本 0.1.2，尚未到 1.0）：

• 构建未签名，因此你的操作系统会在首次启动时发出警告。继续操作的步骤见下文。
• 0.1.x 各版本为源码构建——打包流水线已暂停，需从检出的源码进行构建。见 从源码构建。
• 没有自动更新。 请自行从 GitHub Releases 下载更新版本。

系统要求

Cordy 运行于 Windows、macOS 与 Linux。正式的最低操作系统版本与硬件要求尚未公布；实际的基准是：

• 一个 64 位（x64） 操作系统。Windows 安装程序与 Linux 软件包均面向 x64 构建。
• 已安装并加入 PATH 的 Git——Cordy 在本地 Git 仓库上工作，并使用 Git worktree。
• 你打算使用的每个 CLI 智能体，需分别安装并完成认证（见 智能体）。Cordy 启动智能体，但不捆绑它们。

开发与发布验证主要在 Windows 与 macOS 上进行；Linux 软件包接受的真实世界测试最少。

打包安装程序，还是源码构建？

获取 Cordy 有两种方式，具体取决于对应的发布版本：

• 打包安装程序（.exe、.dmg / .zip、.AppImage / .deb）——当某个发布附带了它们时，按 安装打包版本 中的说明下载并运行。
• 源码构建——当前的 0.1.x 各版本仅提供源码（不附带安装程序）。按 从源码构建 中的说明从检出的源码进行构建。

两者都发布于项目的 GitHub Releases 页面；你所用版本的发布说明会写明附带了哪些产物。

安装打包版本

当某个发布附带了安装程序时，下载适配你平台的产物，然后按首次启动的步骤越过未签名应用的警告。

Windows（NSIS 安装程序）

1. 从发布页下载 cordy-Setup-<version>.exe。
2. 运行它。由于构建未签名，Windows SmartScreen 可能会显示"Windows 已保护你的电脑"。
3. 点击 更多信息，再点击 仍要运行。
4. 安装程序是一个常规向导——你可以更改安装目录。它会安装一个名为 Cordy 的应用，并创建开始菜单与桌面快捷方式。

Windows 安装程序面向 x64。

macOS（dmg 或 zip）

1. 为你的 Mac 下载 .dmg（磁盘映像）或 .zip。
2. 从 .dmg 中，将 Cordy 拖入 应用程序。从 .zip 中，解压后将 Cordy.app 移入 应用程序。
3. 由于构建未签名且未公证，Gatekeeper 会阻止常规的双击（例如"无法打开 Cordy，因为它来自身份不明的开发者"）。
4. 右键点击（或按住 Control 点击）该应用 → 打开，然后在对话框中点击 打开。每次安装只需这样操作一次。

若右键 → 打开之后 macOS 仍然拒绝，见 故障排查。

Linux（AppImage 或 deb）

AppImage（便携，免安装）：

1. 下载 .AppImage。
2. 赋予可执行权限：chmod +x Cordy-*.AppImage。
3. 运行它：./Cordy-*.AppImage。

deb（Debian / Ubuntu）：

1. 下载 .deb。
2. 安装它：sudo apt install ./cordy_*.deb（或 sudo dpkg -i cordy_*.deb）。
3. 从应用程序菜单启动 Cordy。

Linux 软件包面向 x64，且是三个平台中测试最少的。

从源码构建

0.1.x 各版本仅提供源码，因此这是当前的主要路径。最终你要么在开发模式下运行应用，要么自行产出一个打包安装程序。

前置条件

• Git。
• Node.js 22.x 与 pnpm 9.x。本仓库使用 pnpm，并提交了 pnpm-lock.yaml；主版本对齐可避免 lockfile 抖动。
• 通过 rustup 安装的 Rust 1.85.0。仓库在 rust-toolchain.toml 中固定了工具链（并包含 rustfmt 与 clippy 组件），因此 rustup 会自动选择正确的版本。构建 cordy-runtime 二进制需要 Rust。
• 仅 Windows，用于打包： 装有 使用 C++ 的桌面开发 工作负载（含 Spectre 缓解库）的 Visual Studio Build Tools，以及一个可被 node-gyp 发现的 Python 安装。

克隆并安装

git clone https://github.com/DS-Studio/cordy-desktop.git
cd cordy-desktop
pnpm install

在开发模式下运行

这是试用 Cordy 最快的方式。先构建一次 Rust 运行时，然后启动应用：

pnpm runtime:build   # 编译 cordy-runtime 二进制（debug）
pnpm dev             # 以开发模式启动 Vite + Electron

若跳过 pnpm runtime:build，应用仍会启动，但运行时状态会显示 binary-missing 并提示你去构建它——在二进制存在之前，终端与智能体都无法工作。见 运行时。

产出打包应用

为当前操作系统构建一个安装程序——这同时会编译发布版运行时并将其打包进去——运行以下之一：

pnpm dist            # 为当前操作系统打包
pnpm dist:win        # Windows NSIS 安装程序（x64）
pnpm dist:mac        # macOS dmg + zip
pnpm dist:linux      # Linux AppImage + deb
pnpm dist:dir        # 未打包的应用目录（不生成安装程序）

构建完成的安装程序与未打包应用会写入 dist/ 目录。你以这种方式构建的安装程序同样是未签名的，因此上文的首次启动步骤依然适用。

更新

Cordy 不会自我更新。要升级到更新的版本，请从 GitHub Releases 下载（或拉取仓库并重新构建），然后覆盖安装到你现有的副本上。你的项目、工作区、笔记与设置存放在一个独立的用户数据目录中（见 隐私），不会因替换应用而受影响。

相关页面

• 运行时——cordy-runtime 二进制及其环境变量覆盖。
• 智能体——安装并认证你的 CLI 智能体。
• 故障排查——首次启动与运行时问题。