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

本機引擎整合（AX Code）

狀態：有效範圍：現行狀態上次審閱：2026-09-19 負責人：ax-code runtime 相關：ax-engine LOCAL-ENGINE-CLIENTS

本機執行環境設定

在 /connect 中選擇 AX-Engine 執行環境，然後選 選擇模型。AX Code 會設定本機執行環境，並在需要所選模型時啟動它。沒有端點 URL 或 API 金鑰表單。檢視狀態、停止本機執行環境 （執行中時）與停用用來管理本機行程。

AX Code 使用 附屬程式 HTTP 後端連接 AX Engine。它啟動 ax-engine serve，追蹤所擁有的行程，並自動解析迴路位址與連接埠。使用者選擇模型；AX Code 處理傳輸設定。

AX Code (TypeScript)
  -> select local model -> ensure/prepare -> spawn ax-engine serve
  -> managed loopback /v1 -> @ai-sdk/openai-compatible language model

明確選擇模型會儲存受管理的生命週期，並清除舊式附加的端點與金鑰設定。這也會覆寫殘留的 AX_ENGINE_HOST 值。較舊的 SDK 用戶端仍保留僅限迴路的舊式附加 API 與其憑證驗證。那條相容路徑不在供應商選單中。

AX Code 不會在行程內連結 AX Engine SDK。AX Engine 擁有模型執行，AX Code 擁有用戶端的行程生命週期。主機資格、模型準備與即時工具呼叫檢查仍然適用。

冷啟動有 600 秒的就緒限制。啟動時間取決於模型大小、儲存吞吐與可用記憶體。耗盡的啟動會以伺服器日誌與模型路徑停止該回合； AX Code 不會自動重新開始另一次冷載入，也不會切換供應商。在明確重試之前，先解決回報的問題。模型設定封套，包含生命週期鎖等待與能力探索，限制為 660 秒。到期會取消待處理的設定並停止自動重試。取消請求也會立即停止等待，即使某個設定相依尚未回應。在就緒期限之後，或所擁有行程結束之後才到達的健康回覆，不能建立就緒狀態。

一旦就緒，引擎會在對話回合之間保持常駐。完成或取消發起的回合，不會停止已就緒的引擎。若在啟動仍在進行時取消，會終止該次嘗試並移除其行程紀錄。使用 停止本機執行環境 可以明確停止常駐引擎。

AX Code 遵循標準的 Hugging Face 快取位置，並尊重使用者的儲存選擇，包含本機磁碟、SMB 與 NFS 掛載。快取解析順序是 HF_HUB_CACHE，然後 HF_HOME/hub，然後 XDG_CACHE_HOME/huggingface/hub，然後 ~/.cache/huggingface/hub。已明確設定或已準備好的模型路徑，優先於快取探索。AX Code 不會依儲存類型搬移權重或覆寫這些選擇。啟動診斷會回報實際模型路徑，讓使用者能在所選儲存上調查可用性與讀取效能。

對於既有引擎，AX Code 最多做三次健康探測，每次限制兩秒，並以 250 毫秒間隔，然後才重啟無回應的行程。取消請求會保留既有行程。

為什麼使用附屬程式

因素	附屬程式的選擇
主機語言	Node／Bun 的 agent 執行環境，並有明確的原生行程邊界
隔離	數 GB 的模型與原生當機留在 agent 行程之外
升級	有版本閘門的內建下限，加上可選的受管理覆疊，不必重新建置 ax-code
供應商模型	與其他本機與雲端供應商相同的 OpenAI 相容路徑
多用戶端	一台伺服器可以透過 `server.json` 做健康檢查並停止

生命週期階段

實作：packages/ax-code/src/provider/ax-engine/lifecycle.ts

階段	時機（AX Code 對應）
`unavailable`	平台資格失敗
`missing_dependency`	二進位檔遺失、版本過舊或無法執行
`missing_model`	模型路徑尚未準備
`starting`	伺服器行程已記錄但尚未就緒
`ready`	`server.ready`，且行程健康正常
`degraded`	已就緒，但能力檢查指出不支援工具呼叫
`error`	進行中的嘗試出現健康或啟動失敗的阻擋項

嚴重性順序與 ax-engine 的 docs/LOCAL-ENGINE-CLIENTS.md 一致。

區域	路徑
伺服器啟動與健康	`packages/ax-code/src/provider/ax-engine/server.ts`
供應商載入器（受管理與附加）	`packages/ax-code/src/provider/ax-engine/provider-loader.ts`
TUI 本機執行環境	`packages/ax-code/src/cli/tui/component/dialog-provider.tsx`
本機動作輔助	`packages/ax-code/src/cli/tui/component/dialog-provider-options.ts`
彙總狀態	`packages/ax-code/src/provider/ax-engine/status.ts`
階段對應	`packages/ax-code/src/provider/ax-engine/lifecycle.ts`
模型政策	AX Engine 模型選擇

受管理的釘選附屬程式佈建，並不是行程內嵌入。Darwin-arm64 發行版會把 engine/<version>/ 放在 CLI 旁邊；ax-code providers ax-engine install 是較新釘選版本發布時的覆疊與更新器。

非目標

以行程內 SDK 嵌入取代 AX Code 中的附屬程式
採用 gRPC 作為主要聊天傳輸
為第一方用戶端使用自訂 Unix socket，或非 OpenAI 的聊天框架
把模型權重內建進 AX Code 安裝程式

本機引擎整合（AX Code）

本機執行環境設定

為什麼使用附屬程式

生命週期階段

相關程式碼

非目標