本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文

安裝與執行環境通道

狀態：有效 範圍：目前狀態 上次審閱：2026-10-09 負責人：ax-code runtime

根目錄 README 保留主要安裝路徑。本頁是受支援 CLI 安裝程式通道、ax-code doctor 執行環境標籤、本機啟動器行為，以及公開升級行為的權威來源。

公開可用性

公開發行安裝程式與已簽署的執行環境封存透過 download.ax-code.com 散布。安裝不需要私人 GitHub 憑證。

AX Code 與 SDK 只支援 Node.js 26 或更新版本。獨立安裝程式內含 已驗證的 Node 執行環境。原始碼檢出與以 Node 為基礎的 SDK 應用程式必須提供 Node.js 26+；套件安裝會拒絕較舊的 Node 版本。

AX Code Standard 在既有授權下，個人與商業用途仍然免費。 開發原始碼存取與公開散布分開管理。規劃中的 專有 Business 元件有另行授權；這不改變 Standard 的授權。細節見 Standard 與 Business，公開安裝更新見 網站指南。 公開安裝程式及其已簽署資產必須可取得並通過驗證，網站才會 宣傳一行安裝指令。

發行可用性

推送 vMAJOR.MINOR.PATCH git 標籤會啟動 Release 工作流程。 公開發行索引 只在 該工作流程已簽署資產並發布之後才列出 版本。在那之前，Latest 停留在上一個已發布的標籤。驗證成功後，維護者可以 看到新標籤的 Draft；它不是公開的 Latest。

既有安裝請遵循升級與復原。

建議路徑

除非你從檢出開發，否則請使用受支援的封裝安裝程式。發行安裝程式是 macOS 與 Linux 上的主要 CLI 路徑；Windows 請使用原生 PowerShell 安裝程式。

macOS（Apple Silicon）

curl -fsSL https://download.ax-code.com/install | bash

Windows

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://download.ax-code.com/install.ps1 | iex"

Ubuntu 24.04+

curl -fsSL https://download.ax-code.com/install | bash

Homebrew 仍是 macOS CLI 的受支援替代方案：

brew tap defai-digital/tap
brew trust defai-digital/tap
brew install defai-digital/tap/ax-code

Homebrew 對非官方 tap 需要明確信任。這整個 tap 的信任涵蓋目前與未來在 defai-digital/tap 中發布的所有 formula、 cask 與外部指令。共用 tap 同時包含 CLI formula 與 Desktop cask，Homebrew 在解析安裝時可以載入這兩份定義。若 整個 tap 的信任不能接受，請改用發行安裝程式。

把既有安裝從舊版 tap 移出

defai-digital/ax-code 現在只是遷移用 tap。AX Code 發行只更新 defai-digital/tap。若你從舊版 tap 安裝，請在更新前加入共用 tap， 讓 Homebrew 能移動已安裝套件的 tap 擁有權：

brew tap defai-digital/tap
brew trust --formula defai-digital/tap/ax-code
brew update
brew upgrade defai-digital/tap/ax-code
brew info defai-digital/tap/ax-code

確認安裝使用共用 tap 之後，移除舊版 tap：

brew untap defai-digital/ax-code

若 Homebrew 仍回報舊 tap，請在取消 tap 之前執行 brew reinstall defai-digital/tap/ax-code。舊版 儲存庫對既有安裝仍然可存取，以便發現遷移。

驗證版本釘選的 Unix 安裝程式

對於已檢查、版本釘選的 Unix 安裝，請先從同一發行下載安裝程式與 其簽章。已有受信任的 minisign 時：

AX_INSTALL_VERSION="<release>"
AX_INSTALL_BASE="https://download.ax-code.com/releases/download/v${AX_INSTALL_VERSION}"
curl -fsSL "$AX_INSTALL_BASE/install" -o ax-code-install
curl -fsSL "$AX_INSTALL_BASE/install.minisig" -o ax-code-install.minisig
minisign -Vm ax-code-install -x ax-code-install.minisig -P 'RWSlDu++afxCz01OqhYWhfo8+L8pVbSYXJBEb2zoWBuK0WACIzbGVZRO'
# Inspect ax-code-install before running it.
bash ax-code-install --version "$AX_INSTALL_VERSION" --no-modify-path

封存的簽章並不會在執行前驗證啟動指令稿。 從同一來源下載的摘要可以偵測損毀，但不是獨立的 發布者身分檢查。一行路徑依賴 HTTPS 散布端點。

一行遠端執行是方便路徑。Windows 安裝程式在啟動後會用 minisign 驗證下載的 CLI ZIP，但 irm | iex 在執行前並不會驗證 install.ps1 本身。

若 minisign 尚未在 PATH 上，PowerShell 安裝程式會從 download.ax-code.com 下載釘選的 minisign 0.12 封存，檢查其 SHA-256，並在快取前再次檢查解出的可執行檔。預設安裝路徑不需要手動安裝 minisign。PATH 上已有的 minisign 二進位檔會照原樣使用。

在安全敏感的環境中，請下載安裝程式、用 minisign 驗證、檢查它，並釘選 CI 使用的發行版本：

$AX_CODE_VERSION = "<release>"
$AxCodeMinisignPublicKey = "RWSlDu++afxCz01OqhYWhfo8+L8pVbSYXJBEb2zoWBuK0WACIzbGVZRO"
irm https://download.ax-code.com/install.ps1 -OutFile ax-code-install.ps1
irm https://download.ax-code.com/install.ps1.minisig -OutFile ax-code-install.ps1.minisig
# Optional: use a preinstalled minisign, or let install.ps1 bootstrap one when verifying the archive.
minisign -Vm ax-code-install.ps1 -x ax-code-install.ps1.minisig -P $AxCodeMinisignPublicKey
Get-Content .\ax-code-install.ps1
.\ax-code-install.ps1 -Version $AX_CODE_VERSION -NoModifyPath

只有在你刻意接受無法驗證的發行下載時，才設定 AX_CODE_SKIP_MINISIGN_VERIFY=1。

驗證已安裝的執行環境：

ax-code doctor

受支援的使用者安裝在 macOS、Windows 與 Linux（glibc）上應回報 Runtime: Node vX.Y.Z (node-bundled)。

這些安裝程式散布 CLI／TUI 執行環境。Desktop 發行的擁有權在 AX Coder，而且新的 Desktop 發行目前凍結。本指南不 提供 Desktop 安裝或升級通道。

通道矩陣

node-bundled 與 source 是執行環境模式，不是套件管理器名稱。它們描述哪個可執行檔載入應用程式碼：

• node-bundled：Node.js 載入隨附的發行執行環境（所有受支援的使用者安裝通道）。
• source：Node 直接從檢出載入檔案。

compiled 與 bun-bundled 是已淘汰的 Bun 時代執行環境模式，只為舊版診斷保留。它們不是受支援的使用者安裝通道。

pnpm dev 與 pnpm cli 會在啟動前用儲存庫的 TypeScript 把工作區 SDK（packages/sdk/js）編譯到 dist，因此全新檢出不必手動建置 SDK。該步驟直接呼叫 typescript/bin/tsc，經由 node，所以不依賴 node_modules/.bin 已被連結。隨附路徑（pnpm run setup:cli 與 pnpm --dir packages/ax-code run build）仍需要先有 pnpm --dir packages/sdk/js run build。

平台原則

• macOS：以 bash 發行安裝程式作為主要記載的 CLI 路徑。它安裝在 ~/.ax-code 之下，必要時啟動釘選的 Minisign，驗證發行封存，並且不需要 Homebrew。darwin-arm64 封存包含自足的 AX Engine 附屬程式，供本機推論使用。貢獻者建置使用 pnpm run setup:cli。
• 受支援的 Homebrew 路徑會在使用完整限定的安裝指令之前，明確 tap 並信任 defai-digital/tap。整個 tap 的信任包含共用 tap 中目前與未來的所有 formula、cask 與外部指令；當該信任範圍不能接受時，請使用 bash 發行安裝程式。
• Linux CLI：在 amd64 與 arm64（glibc）上，對 Ubuntu Desktop／Server 24.04 LTS 及更新版本使用 bash 安裝程式。發行建置在 Ubuntu 24.04 執行器上產生 ax-code-linux-x64.tar.gz 與 ax-code-linux-arm64.tar.gz，使 glibc 基準與 24.04+ 相容。目前的發行封存不支援 Musl（Alpine）。
• macOS CLI 封存：發行建置只發布 darwin-arm64（Apple Silicon）。Intel macOS 不是目前 CLI／Desktop 套件的受支援安裝目標。
• Windows CLI：使用原生 PowerShell 安裝程式。它把 GitHub 發行資產安裝到使用者本機目錄，並更新使用者 PATH，除非提供了 -NoModifyPath。它在解壓縮前用釘選的公開金鑰驗證下載的 ZIP，並且失敗即關閉，除非刻意設定 AX_CODE_SKIP_MINISIGN_VERIFY=1。若缺少 minisign，安裝程式會從 download.ax-code.com 把釘選的 minisign 0.12 封存下載到 %LOCALAPPDATA%\ax-code\tools\minisign，並在快取前檢查解出的可執行檔。PATH 上已有的 minisign 二進位檔會照原樣使用。使用 -Uninstall 移除使用者本機安裝與 PATH 項目。
• Windows Desktop：使用來自 GitHub Releases、名為 AX-Code-<version>-win-x64.exe 或 AX-Code-<version>-win-arm64.exe 的已簽署 Electron 安裝程式。預期的 Authenticode 發布者是 DEFAI Private Limited。不要把 install.ps1 描述成 Desktop 安裝程式。靜默安裝：.\AX-Code-<version>-win-x64.exe /S（NSIS）。
• Winget：套件資訊清單以 pnpm exec tsx tools/winget/generate-manifests.ts --version <ver> 產生，並提交到 microsoft/winget-pkgs（見 tools/winget/README.md）。在上游發布之前，GitHub Releases 仍是 Windows 安裝的權威來源。
• npm：不是受支援的安裝或升級通道。

一行遠端執行是方便路徑，不是唯一路徑。文件中保留可檢查（在 Windows 上並以 minisign 驗證）的安裝程式流程，在 CI 中使用釘選版本，並且只有在安裝矩陣涵蓋、能驗證 ax-code --version，以及驗證 ax-code doctor 回報該平台預期的執行環境模式時，才記載平台安裝程式。

企業與無人值守安裝

Windows CLI（使用者本機，不需要系統管理員）

# Pin version in CI/images
$env:AX_CODE_VERSION = "7.9.4"
irm https://download.ax-code.com/releases/download/v$env:AX_CODE_VERSION/install.ps1 -OutFile install.ps1
# Optional: verify install.ps1.minisig first (see SECURITY.md)
.\install.ps1 -Version $env:AX_CODE_VERSION -NoModifyPath
# Then add %USERPROFILE%\.ax-code\bin to the machine/user PATH via your MDM.

macOS（使用者本機／Homebrew／MDM）

使用者本機 CLI 安裝且不用 Homebrew 時，使用發行安裝程式：

curl -fsSL https://download.ax-code.com/install | bash

受管 Mac 可以使用 Homebrew formula，讓 CLI 更新跟隨 tap：

brew tap defai-digital/tap
brew trust defai-digital/tap
brew install defai-digital/tap/ax-code

對於 MDM 封裝的 DMG 安裝，使用來自 GitHub Releases、已公證的 AX-Code-*-mac-arm64.dmg，並在原則要求供應鏈檢查時驗證分離的 .minisig。

Winget 可用性

除非已有經過驗證的社群 CLI 套件，否則使用公開安裝程式。 不要假設 GitHub 託管的資訊清單套件可以匿名存取。

更新

選擇擁有作用中安裝的通道：

既有的舊版 tap 使用者應遵循共用 tap 遷移。第二個安裝可能在 PATH 上遮蔽 第一個；變更通道前請使用 which -a ax-code、ax-code --version 與 ax-code doctor。 安裝獨立版本並不會解除安裝 Homebrew。 只在刻意時才在通道之間移動，並保留你的工作階段／設定資料。

Unix 自我升級會從目標發行取得安裝程式，並需要其 SHA-256 附屬檔。缺少安裝程式或摘要會停止升級；沒有可變 main 退回。若要從沒有安裝程式資產的發行安裝較舊封存，請下載 並驗證目前已發行的安裝程式，然後以 --version <older-version> 執行它。

獨立 Unix 安裝使用 ~/.ax-code/bin/ax-code 作為穩定符號連結，指向 ~/.ax-code/versions/ 下唯一的執行環境世代。安裝程式會在切換該連結前驗證完整的 新樹。重新安裝某個版本會建立新的世代。 它保留舊世代與舊版執行環境檔，讓已經在執行的 agent 可以 繼續載入自己的模組。它不會重新啟動正在執行的 agent。請啟動新的 用戶端／執行環境來使用新版本；在執行環境 重新啟動前，請明確停止作用中的工作。Homebrew 檔案仍由 Homebrew 管理。

回復時，使用已驗證的安裝程式搭配 --version <previous-version>。每個保留世代中的 version 檔識別其發行。舊世代不會自動修剪；停止所有使用它們的行程之後，可以移除未使用的世代。 解除安裝時，若需要請用 --keep-data --keep-config 保留工作階段／設定； 遵循二進位檔移除指引，並只在 其行程停止後，另外移除未使用的執行環境世代。若你在 .ax-code 資料夾中存放了 其他設定或個人檔案，不要刪除整個資料夾。

並行的 Unix 安裝會以 .install-lock 目錄位置失敗。 被突然終止的安裝程式可能留下該空目錄。移除過期鎖定並重試之前，請檢查是否有作用中的安裝程式；安裝進行中時不要移除它。

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://download.ax-code.com/install.ps1 | iex"

在 Windows 上這會更新 CLI。若要移除 CLI 安裝及其使用者 PATH 項目：

irm https://download.ax-code.com/install.ps1 -OutFile ax-code-install.ps1
.\ax-code-install.ps1 -Uninstall

貢獻者啟動器行為

本節需要已授權的原始碼檢出。公開 安裝或升級不需要它；見原始碼存取。

pnpm run setup:cli 刻意預設為編譯路徑。它會建置或重用 packages/ax-code/dist/... 下的本機隨附二進位檔，並安裝指向該二進位檔的全域啟動器。這讓本機封裝執行環境檢查接近 Homebrew 與 curl 安裝程式使用者所執行的內容。

該啟動器通常落在 ~/.local/bin 或 PNPM_HOME，這通常在 PATH 上早於 Homebrew。若 Homebrew 已經提供 ax-code，setup:cli 會把檢出安裝為 ax-code-src，並移除先前寫入的 ax-code 包裝，使 brew upgrade ax-code 繼續更新 ax-code 指令。只有在你刻意要讓檢出接管時才使用 pnpm run setup:cli -- --override-homebrew，目標是 ax-code。ax-code doctor 仍會把該覆寫警告為 PATH launchers。

原始碼變更應影響封裝執行環境時，請在測試全域啟動器之前重新整理隨附二進位檔：

pnpm --dir packages/ax-code run build -- --single
pnpm run setup:cli -- --rebuild
ax-code-src --version   # or `ax-code` if Homebrew is not installed

只有在你刻意要讓檢出指令透過 Node 從原始碼檔執行此檢出時，才使用原始碼啟動器：

pnpm run setup:cli -- --source
ax-code-src doctor      # or `ax-code doctor` if Homebrew is not installed

原始碼啟動器應回報 Runtime: Node vX.Y.Z (source)。

工具鏈需求

儲存庫強制 pnpm@10.33.4，方式是根目錄 packageManager 欄位與 only-allow pnpm：preinstall hook 會阻擋非 pnpm 安裝，根目錄 pre<script> hook 會以相同需求阻擋 npm run <script>。Node.js 必須符合根目錄 package.json 引擎（>=26），它也為原始碼模式的 TUI 指令提供 --experimental-ffi。

不要使用根目錄 pnpm test；根指令稿刻意以 do not run tests from root 結束。對於 packages/ax-code，請從 packages/ax-code/ 執行測試。

Homebrew 安裝會收到更新通知，但不會自動在背景升級。明確升級或清理舊的 Homebrew keg 之前，請先結束作用中的 agent 執行。