ASDF 管理工具
此技能允許代理程式使用 asdf 管理專案工具版本和依賴項。它處理 .tool-versions 檔案的建立和更新,安裝和更新插件,並在安裝第三方插件時實施必要的安全護欄。
使用時機
- 當專案使用
asdf管理執行環境(例如 Node.js、Python、Ruby、Go、Elixir、Rust)時。 - 當儲存庫中存在
.tool-versions檔案,或使用者想要設定多執行階段版本管理時。 - 當使用者要求「更新所有工具」或將工具設定為「最新」版本時。
- 當使用者想要新增一個可透過
asdf管理的新開發工具、語言執行階段或工具程式時。
不應使用時機
- 當專案明確設定使用其他套件/執行階段管理器(例如
mise、fnm、nvm、pyenv、rbenv、gvm,或未安裝/不想要asdf-vm)時。 - 當安裝應透過系統層級套件管理器(例如
brew、apt、pacman或dnf)管理且不需要每個專案版本鎖定的套件時。
輸入項
| 輸入 | 必要 | 說明 |
|---|---|---|
| 工具名稱 | 是 | 執行階段或工具的名稱(例如 nodejs、python、golang)。 |
| 版本 | 否 | 要設定或安裝的特定版本(例如 18.16.0、latest、system)。 |
| 動作 | 是 | 要執行的操作:update-all、install-tool、set-version 或 add-plugin。 |
| 全域 | 否 | 設為 true 以套用設定至全域 ($HOME/.tool-versions) 而非本機專案目錄。 |
工作流程
步驟 1:偵測並驗證 ASDF 環境
在執行任何 asdf 命令之前,請驗證 asdf 是否已安裝且在代理程式的目前 shell 環境中可存取:
- 執行
which asdf或asdf --version。 - 如果找不到
asdf,請檢查常見安裝路徑(例如$HOME/.asdf/bin/asdf或/opt/homebrew/bin/asdf)。如果已安裝但未載入,請引導使用者如何載入它。 - 如果系統中完全缺少
asdf,此技能必須提前退出並通知使用者: 「請從 https://asdf-vm.com/guide/getting-started.html 安裝」- 原因:如果沒有安裝
asdf核心可執行檔,技能無法繼續。使用實用的安裝 URL 快速失敗可確保順暢的使用者設定體驗。
- 原因:如果沒有安裝
步驟 2:處理「更新所有工具」請求
當使用者要求將所有工具更新至最新版本時:
- 找到
.tool-versions檔案(通常在專案根目錄,或檢查上層目錄)。 - 讀取
.tool-versions檔案中定義的工具清單。 - 對於找到的每個工具,執行以下命令以自動解析並寫入最新版本:
asdf set <tool-name> latest- 原因:使用
asdf set <tool-name> latest比手動編輯.tool-versions更精確且更穩健,因為它會觸發asdf擷取實際已解析的最新可用版本,視需要下載/編譯它,並將確切的靜態版本字串寫回.tool-versions檔案。
- 原因:使用
步驟 3:搜尋並新增插件(社群索引檢查)
當使用者要求安裝工具/插件時:
- 首先,透過執行以下命令檢查插件是否已安裝:
如果已安裝,請跳至步驟 5。asdf plugin list - 如果插件未安裝,請驗證它是否存在於官方
asdf社群索引中:
過濾或搜尋所需工具名稱的輸出。asdf plugin list all- 原因:檢查社群索引可確保我們只安裝經過策劃和審查的插件。官方索引之外的第三方插件有權執行自訂鉤子腳本,並在主機系統上編譯/安裝不受信任的二進位檔。
步驟 4:針對自訂/非社群插件的嚴格安全檢查
如果請求的工具不在官方社群索引 (asdf plugin list all 輸出) 中:
- 引導代理程式上網搜尋(例如透過搜尋引擎、GitHub 或文件)以尋找
asdf插件正確且合法的來源儲存庫 URL。 - 在沒有獲得使用者明確許可的情況下,請勿繼續安裝自訂插件。 這是一個關鍵的安全邊界。
- 向使用者提出結構化的許可請求,包含:
- 一個明確的警告,說明該插件不在官方
asdf社群儲存庫清單中。 - 找到的插件確切儲存庫 URL(例如
https://github.com/someone/asdf-mytool)。 - 關於第三方插件安全影響的警告(它們可以在安裝/使用期間執行任意 shell 程式碼)。
- 一個明確的提示,請求允許繼續安裝。
- 一個明確的警告,說明該插件不在官方
- 如果且僅當使用者同意,才使用驗證過的 URL 新增自訂插件:
asdf plugin add <tool-name> <plugin-url>
步驟 5:安裝並設定工具版本
插件安裝/新增後:
- 如果使用者要求特定版本,請安裝它:
否則,安裝最新版本:asdf install <tool-name> <version>asdf install <tool-name> latest - 將版本寫入專案設定:
- 對於本機專案版本管理(預設):
asdf set <tool-name> <version-or-latest> - 對於全域使用者層級版本管理:
asdf set -u <tool-name> <version-or-latest>
- 對於本機專案版本管理(預設):
- 安裝後執行
asdf reshim以確保所有 shim 都已更新,且新安裝的可執行檔可立即使用。
驗證
- 執行
asdf current以驗證新設定的工具版本是否生效且在目錄中正確解析。 - 確保
.tool-versions檔案與設定的工具和版本相符。 - 檢查在官方索引之外新增的自訂插件是否僅在使用者明確確認後才安裝。
常見陷阱
| 陷阱 | 解決方案 |
|---|---|
代理程式 shell 中出現 asdf: command not found | asdf 可能已安裝但未在作用中的 shell 中載入。找到 asdf.sh(例如在 /opt/homebrew/opt/asdf/libexec/asdf.sh 或 $HOME/.asdf/asdf.sh)並載入它,或在代理程式環境中動態地將 /shims 加入 $PATH。 |
| 安裝後工具可執行檔無法執行 | 執行 asdf reshim 以重新產生 shim 目錄包裝器,讓 shell 能找到新的二進位檔。 |
| 因缺少編譯工具而導致安裝失敗 | 像 Ruby、Python 和 Erlang 這類語言使用 asdf 從原始碼編譯時,需要本機建置相依項(例如 gcc、openssl、make、libyaml 等)。根據建置日誌告訴使用者缺少哪些相依項。 |
| 非互動式 shell 在互動式提示處阻塞 | 確保 asdf 命令以非互動方式執行,或相依項已預先滿足。 |