跳至主要内容

SDK 設定與擴充功能管理

執行 sima-cli sdk setup 時，選擇選用 SDK 服務、瀏覽器版 VS Code 擴充功能，以及 Model Compiler 安裝來源。

命令參考：sima-cli sdk setup

建置與分享容器映像檔​

使用 DevKit 設定 SDK 3.0 或更新版本時，sima-cli 會提供建立小型本機容器登錄庫的選項。登錄庫會將映像檔儲存在主機上，因此即使 SDK 容器被替換，映像檔仍可繼續使用。

登錄庫從連接埠 5050 啟動。若該連接埠已被使用，sima-cli 會自動選擇下一個可用的連接埠，並顯示所選的位址。

設定也會在 SDK shell 中提供兩個位址：

  • SIMA_CONTAINER_REGISTRY 是 SDK 用來推送映像檔的位址。
  • SIMA_DEVKIT_CONTAINER_REGISTRY 是 DevKit 用來拉取相同映像檔的位址。

在 Dockerfile 中定義應用程式，然後從 SDK 內建置並推送 ARM64 映像檔：

docker buildx build \
  --platform linux/arm64 \
  --tag "${SIMA_CONTAINER_REGISTRY}/hello-neat:develop" \
  --push \
  .

使用 dk container deploy 從同一登錄庫下載映像檔，並在已連接的 DevKit 上執行：

dk container deploy hello-neat:develop \
  --detach \
  --name hello-neat \
  --network host

使用簡短的映像檔名稱即可。dk 會使用 sima-cli 設定的 DevKit 登錄庫位址。若要先不明確更新映像檔就直接啟動，請使用 dk container run hello-neat:develop ...。

登錄庫會在本機開發網路上使用 HTTP。登錄庫只會公開在 SDK 使用的迴路介面和面向 DevKit 的網路路徑上，不會公開在主機的所有介面上。

在 macOS 上，設定會區分實體 LAN 路由與 Cloudex 或其他路由式通道。實體路由會使用 Colima 橋接位址。utun、WireGuard 或類似通道無法承載 Ethernet 橋接，因此設定會讓 Colima 保持共用模式，改為啟用 network.hostAddresses。如此一來，SDK 容器便能沿用 Mac 的通道路由，同時在 DevKit 所使用的 Mac 通道位址上公開登錄庫。由於 Colima 通常也會複製通道的子網路前綴，設定會從 VM 的本機路由表移除過度寬廣的子網路路由，同時將 Mac 位址保留為 /32 本機路由；否則 VM 可能會將 DevKit 對等端誤認為本機位址。此修復會在 Colima 重新啟動後保留。若作用中的設定檔先前是為實體連線設定成橋接模式，設定會使用受保護的設定檔重建流程切換至共用模式，同時保留經驗證的獨立 Docker 資料磁碟。無法安全重建的設定檔（包括已啟用 Kubernetes 的設定檔）不會變更。若通道的主機位址發生變更，請重新連線通道並再次執行設定。

SDK 設定不會在 DevKit 上安裝或設定 Docker。第一個 dk container 命令會處理任何必要的 Docker 安裝，並設定 Docker 使用本機登錄庫；只有在登錄庫設定變更時才會重新啟動 Docker。如此一來，對不使用容器部署的使用者而言，Docker 仍完全是選用項目。安裝 Docker 需要明確核准，並能透過網際網路存取 Docker 的 Debian 軟體庫。免密碼 sudo 並非必要條件；sima-cli 會在設定期間為 DevKit 使用者完成設定。

使用 --no-container-registry 可略過此步驟。這不會停止或移除現有的登錄庫。若要選擇其他連接埠，請使用 --container-registry-port <port> 重新執行設定。變更連接埠時，已儲存的映像檔會保留。

Edgematic Studio​

在 Neat SDK 映像上，設定會在不提示的情況下安裝 Edgematic Studio、公開其連接埠並啟動它。這也適用於 -y 與 --noninteractive。摘要會在 Edgematic Studio 面板中顯示 Studio 的 URL。Studio 使用主機連接埠 8088；若 8088 已被占用，則改用其他可用的連接埠。

第一次聊天前，請從 Studio 的設定登入您的程式開發代理。Studio 不會隨容器重新啟動；若其 URL 無法再開啟，請在 SDK 容器 shell 中執行 activate-edgematic-studio。

使用 --no-edgematic-studio 略過 Studio，且不公開其連接埠。若只要公開連接埠以供之後手動安裝，請使用 --edgematic-studio-port。--minimal 與 --no-insight 也會略過 Studio。由於 Docker 連接埠對應在建立後無法變更，這些選擇會在建立容器時套用。

若 Studio 安裝失敗，設定會繼續進行，並顯示之後從 SDK 容器 shell 安裝的指令。

選擇瀏覽器版 VS Code 擴充功能​

Neat 會自動安裝到目前 SDK 使用者的目錄，不需詢問。新的 SDK 映像已內含擴充功能，設定時會在本機複製；舊映像則沿用下載安裝方式。--minimal 會略過擴充功能設定。

互動式設定提供選用的 Codex 與 Claude 擴充功能。以 Space 選取，按 Enter 確認。初始皆未勾選；不選任何項目就會略過程式開發代理安裝，既有但未選取的擴充功能仍會保留。

自動化時，可不經檢查清單直接安裝程式開發代理：

sima-cli sdk setup --noninteractive --all-extensions

--all-extensions 只略過擴充功能選取。使用 --noninteractive 略過其他問題。重複使用既有 SDK 容器時也會安裝擴充功能。未指定此選項時，除非舊版 SIMA_CLI_INSTALL_CODEX_EXTENSION 設定要求安裝，否則 -y 與 --noninteractive 會略過選用擴充功能。--all-extensions 不能與 --minimal 合併使用，也不會改變 Edgematic Studio 或 Model Compiler 選擇。

瀏覽器版 VS Code 擴充功能版本​

在 code-server（SDK 3.0 以上）中，Codex 預設安裝最新可用版本，不固定版本。若明確指定版本，仍會固定至該版本。舊版 OpenVSCode 映像保留 Codex 的相容性固定版本。Claude 仍使用確切的固定版本。選取確切版本時，重新執行設定會替換不同版本；相符版本則保留並固定，不會重新下載。SDK 映像可在 /etc/sima-neat/vscode-extensions.json 宣告已驗證版本：

{
  "schema_version": 1,
  "extensions": {
    "openai.chatgpt": "26.5825.51511",
    "anthropic.claude-code": "2.1.266"
  }
}

資訊清單本身不代表使用者選擇安裝。結構描述版本 1 要求兩個 ID 都指定確切版本。沒有資訊清單的舊映像會使用 Codex 26.5825.51511 與 Claude 2.1.266 作為相容性備援版本。無法讀取或無效的資訊清單會回報錯誤並略過程式開發代理安裝，但其餘設定會繼續。Codex 或 Claude 安裝命令失敗時，會使用選取的目標與正常 TLS 驗證嘗試最多三次。

環境變數覆寫設定優先：

變數行為
SDK_SKIP_CODING_AGENT_INSTALL設為 1、true、yes 或 on，即可略過 Codex 與 Claude 擴充功能的提示和安裝，即使使用 --all-extensions 也一樣。Neat 設定仍會執行，既有代理不會被移除。
SIMA_CLI_CODEX_EXTENSION_ID以 publisher.extension@exact-version 覆寫 Codex；空值會停用，除非使用 --all-extensions。
SIMA_CLI_CLAUDE_EXTENSION_ID以 publisher.extension@exact-version 覆寫 Claude；空值會停用，除非使用 --all-extensions。
SIMA_CLI_INSTALL_CODEX_EXTENSION不經檢查清單，自動選取擴充功能安裝。

在 code-server 上，未附版本的 Codex ID（或 openai.chatgpt@latest）使用最新版本。其他未附版本的內建 ID 使用 SDK／預設固定版本；其他 ID 必須指定版本。--minimal 會略過選用擴充功能安裝。設定會驗證已安裝版本、寫入每個選定擴充功能的 metadata.pinned 旗標（最新版 Codex 為 false），並重新啟動瀏覽器版 VS Code；之後請重新載入已開啟的瀏覽器分頁。

Model Compiler 安裝來源​

設定只會依 SDK 容器架構，在目前工作目錄尋找 model-compiler-arm64.zip 或 model-compiler-amd64.zip。不會搜尋解壓縮後的資料夾、父目錄、工作區 ZIP 或另一種架構。

找到有效本機 ZIP 時，設定提供本機、線上或略過選項。沒有有效 ZIP 時，提供線上或略過，按 Enter 的預設選擇為略過。

旗標有本機 ZIP無有效本機 ZIP
--noninteractive本機安裝略過
--noninteractive -y本機安裝線上安裝
-y本機安裝線上安裝

無人操作的線上安裝必須使用 -y。舊版 SDK 來源請在主機上使用 sima-cli login 驗證。--minimal、--no-model-compiler 與 --no-model-sdk 一律略過安裝。

官方 ZIP 必須在根目錄包含 install_modelsdk_wheels.sh、source.json、manifest.txt 與套件內容，且必須符合 SDK 選定的編譯器版本。封存檔會解壓縮至主機暫存空間，再複製到 Linux 容器暫存空間，因此請為兩份內容預留空間。成功或失敗後會移除暫存資料，保留原始 ZIP。本機安裝失敗絕不會改用線上來源。系統套件與 Python 必要元件仍可能需要網路存取。