detro/quirks

ASDF Manager

此技能允许代理使用 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 命令之前，验证代理的当前 shell 环境中是否已安装并可访问 asdf：

1. 运行 which asdf 或 asdf --version。
2. 如果未找到 asdf，检查常见安装路径（例如 $HOME/.asdf/bin/asdf 或 /opt/homebrew/bin/asdf）。如果已安装但未 sourcing，指导用户如何 sourcing。
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 found	asdf 可能已安装但未在活动 shell 中 sourcing。找到 asdf.sh（例如在 /opt/homebrew/opt/asdf/libexec/asdf.sh 或 $HOME/.asdf/asdf.sh 下）并 sourcing，或在代理上下文中动态地将 /shims 添加到 $PATH。
安装后工具可执行文件无法运行	运行 asdf reshim 以重新生成 shim 目录包装器，使 shell 能够找到新的二进制文件。
由于缺少编译工具导致安装失败	使用 asdf 从源代码编译的语言（如 Ruby、Python、Erlang）需要本地构建依赖（如 gcc、openssl、make、libyaml 等）。根据构建日志告知用户缺少哪些依赖。
非交互式 shell 在交互式提示处阻塞	确保 asdf 命令以非交互方式运行，或预先满足依赖条件。

参考

• ASDF 官方入门指南
• ASDF 配置选项
• ASDF 官方社区插件列表