第16篇-平台限定Skill-platforms字段与自动隐藏机制

【Skills 系统从入门到精通】第 16 篇平台限定 Skill——platforms 字段与自动隐藏机制本篇你将学到platforms 字段的精确语法和取值三层自动隐藏机制的工作原理多平台技能的配置方式实战编写一个 macOS 专属技能并验证跨平台行为平台限定与技能发现的关系读完本篇你将能够让技能在不同操作系统上智能显隐避免不兼容技能干扰用户。一、为什么需要平台限定1.1 问题场景有些技能依赖操作系统专属的工具或命令iMessage 技能依赖 macOS 上的imsgCLILinux 上不存在Apple Notes 技能依赖 macOS 的memoCLIWindows Service 技能依赖 Windows 的sc.exeLinux 上不存在Homebrew 技能依赖 macOS/Linux 的brewWindows 上不存在如果这些技能在所有平台上都可见Linux 用户调用 iMessage 技能时会直接失败——Agent 尝试运行imsg命令发现不存在然后报错。更糟糕的是这些不兼容的技能占据了 Level 0 索引空间增加了 Agent 的认知负担还可能导致自然语言触发的误匹配。1.2 解决方案platforms 字段提供了一种声明式的解决方案——技能自己声明我只在这些平台上工作系统自动在不兼容的平台上隐藏它。二、platforms 字段语法2.1 取值取值匹配系统系统检测macosmacOS (Darwin)platform.system() DarwinlinuxLinuxplatform.system() LinuxwindowsWindowsplatform.system() Windows2.2 配置方式单平台限定platforms:[macos]这个技能只在 macOS 上可见。多平台限定platforms:[macos,linux]这个技能在 macOS 和 Linux 上可见在 Windows 上隐藏。不限定全平台# 省略 platforms 字段# 等同于全平台可见三、三层自动隐藏机制3.1 机制详解当技能声明了 platforms 后系统在不兼容的平台上执行三层隐藏兼容不兼容技能声明 platforms匹配当前操作系统正常进入三层Level 0 索引展示skills list 列出斜杠命令可调用三层自动隐藏索引不出现Agent 不知道其存在列表不出现命令行也看不到斜杠命令提示不可用知道名称也无法调用3.2 检测时机平台检测在技能加载阶段完成——会话启动时扫描技能目录根据platforms字段和当前操作系统过滤。这个过滤是静态的、确定性的不会在会话中途变化。会话启动扫描技能目录读取 platforms 字段检测当前操作系统静态确定性过滤不兼容技能不进入索引Level 0 索引构建完成3.3 对 Progressive Disclosure 的影响platforms 过滤发生在 Level 0 阶段——不兼容的技能根本不进入索引。这意味着Level 0 索引更紧凑少了不兼容的技能Agent 的自然语言匹配范围更精准不会匹配到不可用的技能Token 开销更小四、实战编写 macOS 专属技能4.1 技能编写创建一个 iMessage 发送技能---name:send-imessagedescription:Use when sending iMessages. Compose and send via the imsg CLI on macOS.version:1.0.0platforms:[macos]metadata:hermes:tags:[messaging,apple,imessage]category:productivity---# Send iMessage## OverviewSend iMessages/SMS via the imsg CLI tool. Supports individual contacts and group chats. Requires macOS with Messages app configured.## When to Use-Need to send an iMessage to a contact-Need to send a group message-Responding to a conversation from the terminal## Procedure### Step 1: Verify imsg is installedbash which imsg# If not found: brew install imsgStep 2: Send a message# Send to a phone number or Apple IDimsg send--to1234567890--messageHello from Hermes# Send to a groupimsg send--to1234567890,0987654321--messageTeam updatePitfallsMessages app must be logged in: Check System Settings → MessagesPhone numbers need country code: Use 1 for US numbersRate limiting: Apple may throttle if sending too many messages### 4.2 跨平台验证 在 macOS 上 bash hermes skills list | grep imessage # 输出: send-imessage Use when sending iMessages... hermes chat -q send an iMessage to John # Agent 自动匹配到 send-imessage 技能执行发送在 Linux 上hermes skills list|grepimessage# 无输出技能被隐藏hermes chat-qsend an iMessage to John# Agent 不会匹配到 send-imessage 技能# 可能回复当前系统不支持发送 iMessagesend-imessage 技能platforms macosmacOS 上list 可见 chat 自动匹配Linux 上list 无输出 chat 不匹配4.3 实际内置技能示例Hermes 内置技能中有多个平台限定的例子技能platforms依赖apple-notes[macos]memo CLIapple-reminders[macos]remindctlfindmy[macos]FindMy.appimessage[macos]imsg CLIAgentLinux 用户macOS 用户AgentLinux 用户macOS 用户chat 发送 iMessage 给 John匹配 send-imessage 技能 执行发送chat 发送 iMessage 给 John技能被三层隐藏 不存在此技能回复当前系统不支持五、常见问题5.1 platforms 写错了怎么办如果 platforms 写了一个不合法的值如osx而非macos技能会怎样答案技能会在所有平台上隐藏——因为没有系统能匹配osx这个值。这不是报错而是静默隐藏。排查方法检查 platforms 取值是否是macos、linux、windows之一。合法值 macos linux windows无法匹配platforms 写入非法值如 osx有系统能匹配吗按平台正常显隐静默在所有平台隐藏不报错 难以察觉排查需检查取值拼写5.2 跨平台技能如何处理平台差异一个技能需要在多个平台运行但命令略有不同。处理方式在正文中用条件分支## Procedure ### Step 1: Install dependencies **macOS:** bash brew install jqLinux:apt-getinstalljq# Debian/Ubuntuyuminstalljq# CentOS/RHELWindows (WSL):apt-getinstalljqAgent 会根据当前系统选择对应的命令。 --- ## 本篇小结 | 知识点 | 核心内容 | |--------|---------| | platforms 作用 | 让技能在不兼容的操作系统上自动隐藏 | | 取值 | macos / linux / windows | | 三层隐藏 | 系统提示索引 → skills_list → 斜杠命令 | | 检测时机 | 会话启动时静态过滤 | | 默认行为 | 不写 platforms 全平台可见 | | 非法值 | 静默在所有平台隐藏不报错 | | 跨平台差异 | 正文中用条件分支处理不同系统的命令 | --- ## 下篇预告 下一篇讲解条件激活的另一个维度——fallback_for_toolsets 和 requires_toolsets。这是比平台限定更精细的激活控制基于当前可用的工具集来决定技能的显隐。 --- 如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。