从源码构建

Crystal Code 由两个并排放置的仓库构建。引擎、工具、提供程序和插件通过相对路径引用 Crystal 库，因此本仓库旁边的检出目录必须命名为 Crystal。

环境要求

.NET 10 或 .NET 11 SDK。global.json 要求 10.0.0，使用 rollForward: latestMajor，并允许预发行版 SDK。
Git。
PATH 中有 bash。在 Windows 上由 Git Bash 提供。
交互式界面需要 TTY。构建和测试不需要。
API key 只在运行会话时需要，构建不需要。

克隆两个仓库

选择一个父目录，把两个仓库都克隆进去：

mkdir -p ~/src
cd ~/src
git clone https://github.com/YELANDAOKONG/CrystalCode.git
git clone https://github.com/YELANDAOKONG/Crystal.git

结果必须是这样：

~/src/
├── Crystal/
└── CrystalCode/

项目引用使用的是字面相对路径，例如 ../../Crystal/Crystal/Crystal.csproj 和 ../../Crystal/Crystal.Tools/Crystal.Tools.csproj。使用这些引用的是 CrystalCode.Engine、CrystalCode.Tools、CrystalCode.Providers 和 CrystalCode.Plugins。重命名 CrystalCode 目录没有问题；重命名 Crystal 目录会导致还原失败。

构建前先确认目录布局和 SDK：

cd ~/src/CrystalCode
ls ../Crystal/Crystal/Crystal.csproj
dotnet --version

dotnet --version 必须以 10. 或 11. 开头。安装脚本会检查这个主版本号，不符合就停止。

构建和测试

在 CrystalCode 仓库根目录：

dotnet build CrystalCode.sln
dotnet test CrystalCode.sln

CrystalCode.sln 包含可执行项目 CrystalCode、CrystalCode.Engine 类库，以及 display、tools、providers 和 plugins 项目及其测试项目。Crystal 项目通过项目引用参与构建，不在此解决方案中列出。

从检出运行

export DEEPSEEK_API_KEY="..."
dotnet run --project CrystalCode -- --provider deepseek --model deepseek-flash

若要把另一个目录作为工作区，把 --workspace 放在最后一个 -- 之后的应用参数中：

dotnet run --project CrystalCode -- --workspace ~/projects/app \
  --provider deepseek --model deepseek-flash

交互式运行需要 TTY。crystal run 是非交互形式，见无头运行。

为本地开发安装此检出

在 Linux 或 macOS 的仓库根目录：

sh scripts/install-local.sh

在 Windows 上：

powershell -ExecutionPolicy Bypass -File scripts/install-local.ps1

脚本根据自身路径定位仓库，因此可以在任意工作目录运行。每项检查都会在继续前打印。

脚本检查的内容

检查	要求
仓库	`CrystalCode.sln` 和 `CrystalCode/CrystalCode.csproj` 存在
命令	`dotnet`、`grep`、`cp`、`mv`、`find`、`chmod`、`mkdir`、`rm`、`touch`、`uname` 和 `tail` 在 `PATH` 中（Unix）
.NET SDK	所选 SDK 主版本为 10 或 11
Crystal 同级检出	`../Crystal` 中包含 `Crystal/Crystal.csproj`、`Crystal.Tools/Crystal.Tools.csproj`、`Crystal.Agents/Crystal.Agents.csproj` 和 `Crystal.Harness/Crystal.Harness.csproj`
平台	操作系统和架构能映射到受支持的运行时标识符
安装目标	`~/.crystal/binaries/code` 可写、不是符号链接、也不是普通文件
运行中的进程	没有名为 `CrystalCode` 的进程在运行
发布输出	`build/CrystalCode` 存在、可执行、旁边没有 `CrystalCode.dll`，且至少 10,000,000 字节
暂存副本	暂存和已安装的二进制与发布大小一致

运行时标识符

平台	运行时标识符
Linux x64	`linux-x64`
Linux ARM64	`linux-arm64`
macOS Apple 芯片	`osx-arm64`
Rosetta 下的 macOS x64	`osx-arm64`
非 Rosetta 的 macOS x64	拒绝：`macOS x64 is not supported.`
Windows x64	`win-x64`

脚本发布的内容

脚本使用与发布工作流相同的参数，把 Release 发布到 build/：

dotnet publish CrystalCode/CrystalCode.csproj
  --configuration Release
  --runtime <rid>
  --self-contained true
  -p:PublishSingleFile=true
  --output build

发布工作流为 GitHub 资产写入 ./publish。此脚本写入 build/，该目录已被 gitignore。发布包含运行时，因此生成的单文件很大。脚本会拒绝小于 10 MB 的二进制，因为这表明运行时没有被打包进去。

脚本替换的内容

输出先复制到安装目录旁的暂存目录 code.new。当前 code 目录重命名为 code.previous，暂存目录移动到目标位置，然后删除备份。移动前发生失败或中断时，会恢复 code.previous。符号链接会被拒绝。

只替换 ~/.crystal/binaries/code/ 下的二进制。配置、凭据、提示、会话、插件和工具都保留在原处。

PATH 和 `crystal` 命令

在 Linux 和 macOS 上，脚本会向当前 shell 的配置文件写入一段内容：

zsh：~/.zshrc
bash：~/.bashrc
其他 shell：不修改任何配置文件

该段内容以 # Crystal Code CLI (Installer) 标记，并添加：

export PATH="$HOME/.crystal/binaries/code:$PATH"
alias crystal=CrystalCode

这段内容只写入一次。重新运行脚本会更新不完整或旧格式的内容，而不是追加重复项。打开新终端或重新加载配置文件，然后运行 crystal。

在 Windows 上，安装目录会加入用户级 PATH。命令仍是 CrystalCode。

如果 shell 没有配置文件可修改，可直接启动已安装的二进制：

~/.crystal/binaries/code/CrystalCode

手动发布

若只想发布而不安装，可自行运行上面的命令，并选择本机的运行时标识符。可执行项目是 CrystalCode，Spectre 应用程序名是 crystal，会话引擎位于 CrystalCode.Engine 类库中。

故障排查

消息	原因与处理
`Missing sibling Crystal checkout: ...`	把 `https://github.com/YELANDAOKONG/Crystal.git` 克隆到 CrystalCode 仓库旁的目录，并命名为 `Crystal`。
`Missing Crystal project: ...`	同级检出不完整或版本过旧。用 `git pull` 更新。
`Crystal Code requires the .NET 10 or .NET 11 SDK.`	安装受支持的 SDK。检查 `dotnet --version`；`global.json` 会前滚到最新的主版本 SDK。
`Crystal Code is running. Exit it, then run this script again.`	关闭所有正在运行的 `CrystalCode` 进程。
`macOS x64 is not supported.`	原生 Intel macOS 不是发布目标。在 Apple 芯片上通过 Rosetta 运行时，脚本会使用 `osx-arm64`。
`Published binary is ... bytes.`	发布不是自包含的，或没有完成。重新运行发布命令。