第17篇-条件激活-fallback-for-toolsets与requires-toolsets实战

【Skills 系统从入门到精通】第 17 篇条件激活——fallback_for_toolsets 与 requires_toolsets 实战本篇你将学到条件激活的需求场景付费工具不可用时自动启用免费替代四个条件激活字段的语义和行为差异DuckDuckGo 作为 web 搜索 fallback 的经典案例分析编写一个条件激活技能的完整实战条件激活组合使用的逻辑规则读完本篇你将能够让技能根据当前环境的工具集自动显隐实现优雅的降级和升级。一、条件激活的需求1.1 场景付费 vs 免费Hermes 的某些功能依赖付费 API。例如高质量的 web 搜索需要 Firecrawl API Key。如果用户没有配置这个 Keyweb 搜索工具就不可用。但是用户仍然需要搜索能力。这时候一个免费的替代方案如 DuckDuckGo 搜索应该自动出现。问题是如果 DuckDuckGo 搜索技能始终可见当付费的 web 搜索也可用时Agent 可能不确定该用哪个。理想的行为是有 Firecrawl Key 时隐藏 DuckDuckGo 技能使用 web 搜索工具没有 Firecrawl Key 时自动显示 DuckDuckGo 技能作为 fallback这就是条件激活要解决的问题。1.2 另一个场景工具依赖有些技能必须使用特定工具才能工作。例如一个 Docker 操作技能必须依赖 terminal 工具——如果没有 terminal比如在一个受限的只读会话中这个技能不应该出现因为出现了也无法执行。二、四个条件激活字段2.1 字段总览字段语义显示条件fallback_for_toolsets工具集的 fallback列出的工具集不可用时显示fallback_for_tools单个工具的 fallback列出的工具不可用时显示requires_toolsets工具集依赖列出的工具集可用时才显示requires_tools单个工具依赖列出的工具可用时才显示条件激活四字段fallback_for_toolsets工具集不可用时显示降级激活fallback_for_tools精确到单个工具requires_toolsets工具集可用时才显示依赖激活requires_tools精确到单个工具2.2 配置位置这四个字段放在metadata.hermes下metadata:hermes:fallback_for_toolsets:[web]# 或requires_toolsets:[terminal]# 或fallback_for_tools:[web_search]# 或requires_tools:[terminal]2.3 fallback 字段详解fallback_for_toolsets和fallback_for_tools实现的是降级激活——当某个工具/工具集不可用时这个技能作为替代方案自动出现。工作逻辑有 FIRECRAWL_API_KEY没有 API Key检查 fallback_for_toolsetsweb 工具集可用?技能隐藏不需要 fallback技能显示作为 fallback 出现2.4 requires 字段详解requires_toolsets和requires_tools实现的是依赖激活——只有当某个工具/工具集可用时这个技能才显示。工作逻辑可用不可用 如受限会话检查 requires_toolsetsterminal 工具集可用?技能显示依赖满足技能隐藏无法工作2.5 四字段组合四个字段可以组合使用。组合逻辑metadata:hermes:requires_toolsets:[terminal]# 必须有 terminalfallback_for_toolsets:[web]# 且没有 web 搜索时这个技能只在有 terminal 但没有 web 搜索时显示。逻辑是 AND两者都必须满足。三、经典案例DuckDuckGo 搜索3.1 案例背景Hermes 内置了一个duckduckgo-search技能它使用 DuckDuckGo 的 HTML 接口做免费搜索。这个技能使用了条件激活metadata:hermes:fallback_for_toolsets:[web]3.2 行为分析场景一用户配置了 FIRECRAWL_API_KEYweb 工具集可用web_search、web_extract 等工具激活 → duckduckgo-search 技能隐藏 → Agent 使用 web_search 做搜索 → 用户获得高质量搜索体验场景二用户没有配置 Firecrawl Keyweb 工具集不可用 → duckduckgo-search 技能自动显示 → Agent 使用技能中的 DuckDuckGo 搜索方法 → 用户仍然可以搜索只是质量略低3.3 设计精妙之处这种设计实现了零配置的优雅降级用户不需要手动选择用付费搜索还是免费搜索系统自动根据当前环境选择最佳可用方案当用户后来添加了 API KeyDuckDuckGo 技能自动隐藏无缝升级duckduckgo 技能web 工具集Agent用户duckduckgo 技能web 工具集Agent用户无 FIRECRAWL_API_KEY用户后来配置了 API Key技能自动隐藏 无缝升级搜索 transformer 论文web_search 不可用自动加载 fallback 技能DuckDuckGo 免费搜索结果再搜 transformer 论文web_search 可用高质量搜索结果四、实战编写条件激活技能4.1 场景编写一个免费图片生成技能作为付费图片生成工具的 fallback。当系统没有配置图片生成 API 时使用免费的 Pollinations.ai API。4.2 技能编写---name:free-image-gendescription:Use when generating images without API key. Free Pollinations.ai fallback for image generation.version:1.0.0metadata:hermes:fallback_for_toolsets:[image_gen]tags:[creative,image,fallback]category:creative---# Free Image Generation (Pollinations.ai)## OverviewGenerate images using the free Pollinations.ai API. No API key required. This skill automatically appears when the premium image generation tools are unavailable.## When to Use-Need to generate an image but no image generation API is configured-Quick image generation for prototypes or drafts-Testing image prompts before using paid services## Procedure### Step 1: Construct the URLbash# Basic image generation via URLPROMPTa serene mountain landscape at sunset ENCODED_PROMPT$(python3-c import urllib.parse; print(urllib.parse.quote($PROMPT))) URLhttps://image.pollinations.ai/prompt/${ENCODED_PROMPT}Step 2: Download the imagecurl-s-ogenerated-image.jpg${URL}?width1024height1024nologotrueStep 3: Verifyfilegenerated-image.jpg# Should show: JPEG image data, ...PitfallsRate limiting: Pollinations.ai may throttle after ~50 requests/hourQuality: Lower quality than DALL-E or Stable DiffusionGeneration time: Can take 5-15 seconds per imageContent filtering: Pollinations has its own content policy### 4.3 验证行为 **没有 image_gen 工具集时** bash hermes skills list | grep free-image # 输出free-image-gen Use when generating images without API key...技能可见可以用/free-image-gen 画一只猫调用。配置了 image_gen 工具后hermes skills list|grepfree-image# 无输出——技能自动隐藏五、条件激活的优先级5.1 与 platforms 的组合条件激活字段和 platforms 可以同时存在platforms:[linux,macos]# 先过滤平台metadata:hermes:fallback_for_toolsets:[web]# 再过滤工具集过滤顺序先平台过滤再工具集过滤。两个条件都满足时技能才可见。不兼容当前系统兼容条件满足不满足候选技能platforms 过滤隐藏工具集条件过滤可见隐藏5.2 无条件字段的技能如果技能没有任何条件激活字段大多数技能的情况它的行为是始终显示——不做任何工具集检查。这是默认行为不需要配置。本篇小结知识点核心内容条件激活目的根据当前工具集自动显隐技能fallback_for_toolsets列出的工具集不可用时显示降级方案fallback_for_tools精确到单个工具的 fallbackrequires_toolsets列出的工具集可用时才显示工具依赖requires_tools精确到单个工具的依赖组合逻辑多个条件 AND 关系全部满足才显示DuckDuckGo 案例web 工具集不可用时自动出现的免费搜索过滤优先级先 platforms 过滤再工具集过滤默认行为无条件字段 始终显示下篇预告下一篇讲解技能的环境变量声明——当技能需要 API Key 等敏感信息时如何安全地声明和配置。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。