從原始碼建置

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.	發行不是自含式，或沒有完成。重新執行發行命令。