Trang này được dịch từ tài liệu tiếng Anh. Lệnh, định danh và ví dụ giữ nguyên. Runtime 7.24.4 · SDK 2.6.7. Bản tiếng Anh

Kênh cài đặt và runtime

Trạng thái: Đang hoạt động Phạm vi: trạng thái hiện tại Xem xét lần cuối: 2026-10-09 Chủ sở hữu: ax-code runtime

README ở gốc giữ đường cài chính. Trang này là nguồn sự thật cho các kênh trình cài CLI được hỗ trợ, nhãn runtime ax-code doctor, hành vi trình khởi chạy cục bộ và hành vi nâng cấp công khai.

Khả dụng công khai

Trình cài phát hành công khai và kho runtime đã ký được phân phối qua download.ax-code.com. Việc cài đặt không cần thông tin xác thực GitHub riêng tư.

AX Code và SDK chỉ hỗ trợ Node.js 26 trở lên. Trình cài độc lập đóng gói một runtime Node đã xác minh. Bản checkout mã nguồn và ứng dụng SDK dựa trên Node phải tự cung cấp Node.js 26+; cài gói sẽ từ chối các phiên bản Node cũ hơn.

AX Code Standard vẫn miễn phí cho sử dụng cá nhân và thương mại theo giấy phép hiện có. Quyền truy cập mã nguồn phát triển được quản lý tách khỏi phân phối công khai. Các thành phần Business độc quyền đã lên kế hoạch có giấy phép riêng; điều này không đổi giấy phép của Standard. Xem Standard và Business để biết chi tiết và hướng dẫn trên website để biết cập nhật cài đặt công khai. Trình cài công khai và tài sản đã ký của chúng phải truy cập được và được xác minh trước khi website quảng bá một lệnh cài một dòng.

Khả dụng của bản phát hành

Đẩy một thẻ git vMAJOR.MINOR.PATCH sẽ khởi động quy trình Release. Chỉ mục phát hành công khai chỉ hiện một phiên bản sau khi quy trình đó đã ký tài sản và xuất bản. Trước đó, Latest vẫn ở thẻ đã xuất bản trước. Sau khi validate thành công, người bảo trì có thể thấy một bản Draft cho thẻ mới; đó chưa phải Latest công khai.

Với các bản cài đã có, hãy theo Nâng cấp và khôi phục.

Đường được khuyến nghị

Dùng trình cài đóng gói được hỗ trợ, trừ khi bạn đang phát triển từ một bản checkout. Trình cài phát hành là đường CLI chính trên macOS và Linux; trên Windows hãy dùng trình cài PowerShell gốc.

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 vẫn là lựa chọn thay thế được hỗ trợ cho CLI trên macOS:

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

Homebrew đòi hỏi sự tin cậy tường minh với các tap không chính thức. Sự tin cậy toàn tap này bao gồm mọi công thức hiện tại và tương lai, cask và lệnh ngoài được xuất bản trong defai-digital/tap. Tap dùng chung chứa cả công thức CLI và cask Desktop, và Homebrew có thể nạp cả hai định nghĩa khi phân giải một lần cài. Hãy dùng trình cài phát hành nếu sự tin cậy toàn tap không chấp nhận được.

Chuyển một bản cài hiện có khỏi tap kế thừa

defai-digital/ax-code giờ chỉ là tap di chuyển. Các bản phát hành AX Code chỉ cập nhật defai-digital/tap. Nếu bạn đã cài từ tap kế thừa, hãy thêm tap dùng chung trước khi cập nhật để Homebrew có thể chuyển quyền sở hữu tap của gói đã cài:

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

Sau khi xác nhận bản cài dùng tap dùng chung, hãy gỡ tap kế thừa:

brew untap defai-digital/ax-code

Nếu Homebrew vẫn báo tap cũ, hãy chạy brew reinstall defai-digital/tap/ax-code trước khi gỡ tap. Kho kế thừa vẫn truy cập được để các bản cài hiện có phát hiện đường di chuyển.

Xác minh trình cài Unix ghim theo phiên bản

Với một lần cài Unix đã kiểm tra và ghim phiên bản, trước hết hãy tải trình cài và chữ ký của nó từ cùng một bản phát hành. Khi đã có minisign đáng tin:

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

Chữ ký của kho không xác thực tập lệnh khởi tạo trước khi thực thi. Một digest tải từ cùng nguồn phát hiện hỏng dữ liệu nhưng không phải kiểm tra danh tính nhà phát hành độc lập. Đường một dòng dựa vào điểm cuối phân phối HTTPS.

Thực thi từ xa một dòng là đường tiện lợi. Trình cài Windows xác minh ZIP CLI đã tải bằng minisign sau khi khởi động, nhưng irm | iex không xác minh chính install.ps1 trước khi thực thi.

Nếu minisign chưa có trên PATH, trình cài PowerShell tải kho minisign 0.12 đã ghim từ download.ax-code.com, kiểm tra SHA-256 của kho, rồi kiểm tra lại tệp thực thi đã giải nén trước khi lưu đệm. Bạn không cần cài minisign thủ công cho đường cài mặc định. Một tệp nhị phân minisign đã có trên PATH được dùng nguyên trạng.

Với môi trường nhạy cảm về bảo mật, hãy tải trình cài, xác minh bằng minisign, kiểm tra nó, và ghim phiên bản phát hành mà CI dùng:

$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

Chỉ đặt AX_CODE_SKIP_MINISIGN_VERIFY=1 khi bạn cố ý chấp nhận một bản tải phát hành không thể xác minh.

Xác minh runtime đã cài:

ax-code doctor

Các bản cài người dùng được hỗ trợ phải báo Runtime: Node vX.Y.Z (node-bundled) trên macOS, Windows và Linux (glibc).

Các trình cài này phân phối runtime CLI/TUI. Quyền sở hữu phát hành Desktop nằm ở AX Coder, và các bản phát hành Desktop mới hiện đang đóng băng. Hướng dẫn này không cung cấp kênh cài đặt hoặc nâng cấp Desktop.

Ma trận kênh

node-bundled và source là chế độ runtime, không phải tên trình quản lý gói. Chúng mô tả tệp thực thi nào nạp mã ứng dụng:

• node-bundled: Node.js nạp runtime phát hành đã đóng gói (mọi kênh cài người dùng được hỗ trợ).
• source: Node nạp tệp trực tiếp từ một bản checkout.

compiled và bun-bundled là các chế độ runtime thời Bun đã ngừng, chỉ giữ lại cho chẩn đoán kế thừa. Chúng không phải kênh cài người dùng được hỗ trợ.

pnpm dev và pnpm cli biên dịch SDK của không gian làm việc (packages/sdk/js) thành dist bằng TypeScript của kho trước khi khởi chạy, nên một bản checkout mới chạy mà không cần dựng SDK thủ công. Bước này gọi typescript/bin/tsc qua node trực tiếp, nên không phụ thuộc vào việc node_modules/.bin đã được liên kết. Các đường đóng gói (pnpm run setup:cli và pnpm --dir packages/ax-code run build) vẫn cần pnpm --dir packages/sdk/js run build trước.

Chính sách nền tảng

• macOS: dùng trình cài phát hành bash làm đường CLI được ghi chính. Nó cài dưới ~/.ax-code, khởi tạo Minisign đã ghim khi cần, xác minh kho phát hành, và không cần Homebrew. Kho darwin-arm64 gồm một sidecar AX Engine tự chứa cho suy luận cục bộ. Bản dựng của người đóng góp dùng pnpm run setup:cli.
• Đường Homebrew được hỗ trợ tap và tin cậy tường minh defai-digital/tap trước khi dùng các lệnh cài đủ điều kiện. Sự tin cậy toàn tap gồm mọi công thức, cask và lệnh ngoài hiện tại lẫn tương lai trong tap dùng chung; hãy dùng trình cài phát hành bash khi phạm vi tin cậy đó không chấp nhận được.
• CLI Linux: dùng trình cài bash cho Ubuntu Desktop/Server 24.04 LTS trở lên trên amd64 và arm64 (glibc). Bản dựng phát hành tạo ax-code-linux-x64.tar.gz và ax-code-linux-arm64.tar.gz trên runner Ubuntu 24.04 để đường cơ sở glibc vẫn tương thích với 24.04+. Musl (Alpine) không được các kho phát hành hiện tại hỗ trợ.
• Kho CLI macOS: bản dựng phát hành chỉ xuất bản darwin-arm64 (Apple Silicon). macOS Intel không phải mục tiêu cài được hỗ trợ cho các gói CLI/Desktop hiện tại.
• CLI Windows: dùng trình cài PowerShell gốc. Nó cài tài sản phát hành GitHub vào một thư mục cục bộ người dùng và cập nhật PATH của người dùng trừ khi có -NoModifyPath. Nó xác minh ZIP đã tải bằng khóa công khai đã ghim trước khi giải nén và thất bại theo hướng đóng trừ khi AX_CODE_SKIP_MINISIGN_VERIFY=1 được đặt có chủ đích. Nếu thiếu minisign, trình cài tải kho minisign 0.12 đã ghim từ download.ax-code.com vào %LOCALAPPDATA%\ax-code\tools\minisign và kiểm tra tệp thực thi đã giải nén trước khi lưu đệm. Một tệp nhị phân minisign đã có trên PATH được dùng nguyên trạng. Dùng -Uninstall để gỡ bản cài cục bộ người dùng và mục PATH.
• Desktop Windows: dùng trình cài Electron đã ký từ GitHub Releases, tên AX-Code-<version>-win-x64.exe hoặc AX-Code-<version>-win-arm64.exe. Nhà phát hành Authenticode kỳ vọng là DEFAI Private Limited. Đừng mô tả install.ps1 là trình cài Desktop. Cài im lặng: .\AX-Code-<version>-win-x64.exe /S (NSIS).
• Winget: manifest gói được tạo bằng pnpm exec tsx tools/winget/generate-manifests.ts --version <ver> và gửi tới microsoft/winget-pkgs (xem tools/winget/README.md). Cho đến khi được xuất bản ở thượng nguồn, GitHub Releases vẫn là nguồn sự thật cho việc cài trên Windows.
• npm: không phải kênh cài hoặc nâng cấp được hỗ trợ.

Thực thi từ xa một dòng là đường tiện lợi, không phải đường duy nhất. Hãy giữ trong tài liệu một luồng trình cài có thể kiểm tra (và trên Windows đã xác minh bằng minisign), dùng phiên bản đã ghim trong CI, và chỉ ghi trình cài nền tảng khi có độ phủ ma trận cài xác minh ax-code --version và xác minh ax-code doctor báo đúng chế độ runtime kỳ vọng của nền tảng đó.

Cài đặt doanh nghiệp và không giám sát

CLI Windows (cục bộ người dùng, không cần quản trị)

# 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 (cục bộ người dùng / Homebrew / MDM)

Dùng trình cài phát hành cho một lần cài CLI cục bộ người dùng mà không cần Homebrew:

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

Máy Mac được quản lý có thể dùng công thức Homebrew để các lần cập nhật CLI theo tap:

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

Với các lần cài DMG đóng gói qua MDM, hãy dùng AX-Code-*-mac-arm64.dmg đã công chứng từ GitHub Releases và xác minh .minisig tách rời khi chính sách yêu cầu kiểm tra chuỗi cung ứng.

Khả dụng của Winget

Dùng trình cài công khai trừ khi đã có một gói CLI cộng đồng đã xác minh. Đừng giả định các bó manifest được lưu trên GitHub có thể truy cập ẩn danh.

Cập nhật

Chọn kênh đang sở hữu bản cài đang hoạt động:

Người dùng tap kế thừa hiện có nên theo di chuyển sang tap dùng chung. Một bản cài thứ hai có thể che bản đầu trên PATH; hãy dùng which -a ax-code, ax-code --version và ax-code doctor trước khi đổi kênh. Cài phiên bản độc lập không gỡ Homebrew. Chỉ chuyển kênh khi có chủ đích, và giữ dữ liệu phiên cùng cấu hình của bạn.

Tự nâng cấp trên Unix lấy trình cài từ bản phát hành đích và yêu cầu tệp kèm SHA-256. Thiếu trình cài hoặc digest sẽ dừng nâng cấp; không có đường lùi về main có thể thay đổi. Để cài một kho cũ hơn từ bản phát hành không có tài sản trình cài, hãy tải và xác minh một trình cài đã phát hành hiện tại, rồi chạy nó với --version <older-version>.

Bản cài Unix độc lập dùng ~/.ax-code/bin/ax-code làm liên kết tượng trưng ổn định vào một thế hệ runtime duy nhất dưới ~/.ax-code/versions/. Trình cài xác minh toàn bộ cây mới trước khi chuyển liên kết đó. Cài lại một phiên bản sẽ tạo một thế hệ mới. Nó giữ các thế hệ cũ và tệp runtime kế thừa để các tác nhân đang chạy vẫn tiếp tục nạp mô-đun của chính chúng. Nó không khởi động lại các tác nhân đang chạy. Hãy mở một máy khách/runtime mới để dùng phiên bản mới; dừng công việc đang hoạt động một cách tường minh trước khi khởi động lại runtime. Tệp Homebrew vẫn do Homebrew quản lý.

Để hoàn tác, hãy dùng trình cài đã xác minh với --version <previous-version>. Tệp version trong mỗi thế hệ được giữ cho biết bản phát hành của nó. Các thế hệ cũ không bị tỉa tự động; sau khi dừng mọi tiến trình đang dùng chúng, bạn có thể gỡ các thế hệ không dùng. Khi gỡ cài, hãy giữ phiên và cấu hình bằng --keep-data --keep-config nếu cần; theo hướng dẫn gỡ tệp nhị phân và chỉ gỡ riêng các thế hệ runtime không dùng sau khi tiến trình của chúng đã dừng. Đừng xóa toàn bộ thư mục .ax-code nếu bạn đã lưu cấu hình khác hoặc tệp cá nhân ở đó.

Một lần cài Unix đồng thời sẽ thất bại với vị trí thư mục .install-lock. Một trình cài bị dừng đột ngột có thể để lại thư mục trống đó. Hãy kiểm tra các trình cài đang hoạt động trước khi gỡ một khóa cũ và thử lại; đừng gỡ khóa khi một lần cài đang chạy.

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

Trên Windows, lệnh này cập nhật CLI. Để gỡ bản cài CLI và mục PATH của người dùng:

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

Hành vi trình khởi chạy của người đóng góp

Mục này cần một bản checkout mã nguồn được ủy quyền. Không cần cho việc cài hoặc nâng cấp công khai; xem Truy cập mã nguồn.

pnpm run setup:cli cố ý đi theo đường đã biên dịch theo mặc định. Nó dựng hoặc dùng lại tệp nhị phân đóng gói cục bộ dưới packages/ax-code/dist/... và cài một trình khởi chạy toàn cục trỏ tới tệp nhị phân đó. Nhờ vậy các lần kiểm tra runtime đóng gói cục bộ gần với những gì người dùng Homebrew và trình cài curl đang chạy.

Trình khởi chạy đó thường nằm ở ~/.local/bin hoặc PNPM_HOME, thường đứng trước Homebrew trên PATH. Nếu Homebrew đã cung cấp ax-code, setup:cli cài bản checkout dưới tên ax-code-src và gỡ một lớp bọc ax-code đã ghi trước đó để brew upgrade ax-code tiếp tục cập nhật lệnh ax-code. Chỉ dùng pnpm run setup:cli -- --override-homebrew khi bạn cố ý muốn bản checkout chiếm ax-code. ax-code doctor vẫn cảnh báo về sự ghi đè đó dưới dạng PATH launchers.

Sau các thay đổi mã nguồn cần ảnh hưởng tới runtime đã đóng gói, hãy làm mới tệp nhị phân đóng gói trước khi thử trình khởi chạy toàn cục:

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

Chỉ dùng trình khởi chạy mã nguồn khi bạn cố ý muốn lệnh của bản checkout thực thi bản checkout này qua Node từ các tệp nguồn:

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

Trình khởi chạy mã nguồn phải báo Runtime: Node vX.Y.Z (source).

Yêu cầu chuỗi công cụ

Kho thực thi pnpm@10.33.4 qua trường gốc packageManager và only-allow pnpm: móc preinstall chặn các lần cài không phải pnpm, và các móc gốc pre<script> chặn npm run <script> với cùng yêu cầu đó. Node.js phải khớp engine gốc package.json (>=26), engine này cũng cung cấp --experimental-ffi cho các lệnh TUI ở chế độ mã nguồn.

Đừng dùng pnpm test ở gốc; tập lệnh gốc cố ý thoát với do not run tests from root. Với packages/ax-code, hãy chạy kiểm thử từ packages/ax-code/.

Các bản cài Homebrew nhận thông báo cập nhật mà không tự nâng cấp ngầm. Hãy kết thúc các lần chạy tác nhân đang hoạt động trước khi nâng cấp tường minh hoặc dọn các keg Homebrew cũ.