Community研究與資料分析github.com

detro/quirks

你可能擁有技能,但我有怪癖!

quirks 是什麼?

這個技能允許 AI 代理程式使用 `asdf` 管理專案工具版本和依賴項。它負責建立和更新 `.tool-versions` 檔案,安裝和更新插件,並在安裝第三方插件時實施必要的安全護欄。支援的平台包括所有可以使用 `asdf` 管理執行環境的專案,例如 Node.js、Python、Ruby、Go、Elixir 和 Rust。工作流程從偵測和驗證 `asdf` 環境開始,然後處理「更新所有工具」的請求,搜尋並新增插件(包含社群索引檢查),最後安裝和設定工具版本。此技能對於確保開發環境的一致性、簡化版本管理以及防止安裝不受信任的第三方插件至關重要,尤其是在處理多語言專案或需要鎖定特定工具版本時。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add detro/quirks

Installed? Explore more 研究與資料分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 環境中可存取:

  1. 執行 which asdf 或 asdf --version。
  2. 如果找不到 asdf,請檢查常見安裝路徑(例如 $HOME/.asdf/bin/asdf 或 /opt/homebrew/bin/asdf)。如果已安裝但未載入,請引導使用者如何載入它。
  3. 如果系統中完全缺少 asdf,此技能必須提前退出並通知使用者: 「請從 https://asdf-vm.com/guide/getting-started.html 安裝」
    • 原因:如果沒有安裝 asdf 核心可執行檔,技能無法繼續。使用實用的安裝 URL 快速失敗可確保順暢的使用者設定體驗。

步驟 2:處理「更新所有工具」請求

當使用者要求將所有工具更新至最新版本時:

  1. 找到 .tool-versions 檔案(通常在專案根目錄,或檢查上層目錄)。
  2. 讀取 .tool-versions 檔案中定義的工具清單。
  3. 對於找到的每個工具,執行以下命令以自動解析並寫入最新版本:
    asdf set <tool-name> latest
    
    • 原因:使用 asdf set <tool-name> latest 比手動編輯 .tool-versions 更精確且更穩健,因為它會觸發 asdf 擷取實際已解析的最新可用版本,視需要下載/編譯它,並將確切的靜態版本字串寫回 .tool-versions 檔案。

步驟 3:搜尋並新增插件(社群索引檢查)

當使用者要求安裝工具/插件時:

  1. 首先,透過執行以下命令檢查插件是否已安裝:
    asdf plugin list
    
    如果已安裝,請跳至步驟 5。
  2. 如果插件未安裝,請驗證它是否存在於官方 asdf 社群索引中:
    asdf plugin list all
    
    過濾或搜尋所需工具名稱的輸出。
    • 原因:檢查社群索引可確保我們只安裝經過策劃和審查的插件。官方索引之外的第三方插件有權執行自訂鉤子腳本,並在主機系統上編譯/安裝不受信任的二進位檔。

步驟 4:針對自訂/非社群插件的嚴格安全檢查

如果請求的工具不在官方社群索引 (asdf plugin list all 輸出) 中:

  1. 引導代理程式上網搜尋(例如透過搜尋引擎、GitHub 或文件)以尋找 asdf 插件正確且合法的來源儲存庫 URL。
  2. 在沒有獲得使用者明確許可的情況下,請勿繼續安裝自訂插件。 這是一個關鍵的安全邊界。
  3. 向使用者提出結構化的許可請求,包含:
    • 一個明確的警告,說明該插件不在官方 asdf 社群儲存庫清單中。
    • 找到的插件確切儲存庫 URL(例如 https://github.com/someone/asdf-mytool)。
    • 關於第三方插件安全影響的警告(它們可以在安裝/使用期間執行任意 shell 程式碼)。
    • 一個明確的提示,請求允許繼續安裝。
  4. 如果且僅當使用者同意,才使用驗證過的 URL 新增自訂插件:
    asdf plugin add <tool-name> <plugin-url>
    

步驟 5:安裝並設定工具版本

插件安裝/新增後:

  1. 如果使用者要求特定版本,請安裝它:
    asdf install <tool-name> <version>
    
    否則,安裝最新版本:
    asdf install <tool-name> latest
    
  2. 將版本寫入專案設定:
    • 對於本機專案版本管理(預設):
      asdf set <tool-name> <version-or-latest>
      
    • 對於全域使用者層級版本管理:
      asdf set -u <tool-name> <version-or-latest>
      
  3. 安裝後執行 asdf reshim 以確保所有 shim 都已更新,且新安裝的可執行檔可立即使用。

驗證

  • 執行 asdf current 以驗證新設定的工具版本是否生效且在目錄中正確解析。
  • 確保 .tool-versions 檔案與設定的工具和版本相符。
  • 檢查在官方索引之外新增的自訂插件是否僅在使用者明確確認後才安裝。

常見陷阱

陷阱解決方案
代理程式 shell 中出現 asdf: command not foundasdf 可能已安裝但未在作用中的 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 命令以非互動方式執行,或相依項已預先滿足。

參考資料

相關技能