【Skills 系统从入门到精通】第 16 篇：平台限定 Skill——platforms 字段与自动隐藏机制

---

本篇你将学到

• platforms 字段的精确语法和取值
• 三层自动隐藏机制的工作原理
• 多平台技能的配置方式
• 实战：编写一个 macOS 专属技能并验证跨平台行为
• 平台限定与技能发现的关系

读完本篇，你将能够让技能在不同操作系统上智能显隐，避免不兼容技能干扰用户。

---

一、为什么需要平台限定

1.1 问题场景

有些技能依赖操作系统专属的工具或命令：

• iMessage 技能：依赖 macOS 上的 imsg CLI，Linux 上不存在
• Apple Notes 技能：依赖 macOS 的 memo CLI
• Windows Service 技能：依赖 Windows 的 sc.exe，Linux 上不存在
• Homebrew 技能：依赖 macOS/Linux 的 brew，Windows 上不存在

如果这些技能在所有平台上都可见，Linux 用户调用 iMessage 技能时会直接失败——Agent 尝试运行 imsg 命令，发现不存在，然后报错。

更糟糕的是，这些不兼容的技能占据了 Level 0 索引空间，增加了 Agent 的认知负担，还可能导致自然语言触发的误匹配。

1.2 解决方案

platforms 字段提供了一种声明式的解决方案——技能自己声明"我只在这些平台上工作"，系统自动在不兼容的平台上隐藏它。

---

二、platforms 字段语法

2.1 取值

取值	匹配系统	系统检测
macos	macOS (Darwin)	platform.system() == "Darwin"
linux	Linux	platform.system() == "Linux"
windows	Windows	platform.system() == "Windows"

2.2 配置方式

单平台限定：

platforms: [macos]

这个技能只在 macOS 上可见。

多平台限定：

platforms: [macos, linux]

这个技能在 macOS 和 Linux 上可见，在 Windows 上隐藏。

不限定（全平台）：

# 省略 platforms 字段
# 等同于全平台可见

---

三、三层自动隐藏机制

3.1 机制详解

当技能声明了 platforms 后，系统在不兼容的平台上执行三层隐藏：

3.2 检测时机

平台检测在技能加载阶段完成——会话启动时扫描技能目录，根据 platforms 字段和当前操作系统过滤。这个过滤是静态的、确定性的，不会在会话中途变化。

3.3 对 Progressive Disclosure 的影响

platforms 过滤发生在 Level 0 阶段——不兼容的技能根本不进入索引。这意味着：

• Level 0 索引更紧凑（少了不兼容的技能）
• Agent 的自然语言匹配范围更精准（不会匹配到不可用的技能）
• Token 开销更小

---

四、实战：编写 macOS 专属技能

4.1 技能编写

创建一个 iMessage 发送技能：

---
name: send-imessage
description: Use when sending iMessages. Compose and send via the imsg CLI on macOS.
version: 1.0.0
platforms: [macos]
metadata:
  hermes:
    tags: [messaging, apple, imessage]
    category: productivity
---

# Send iMessage

## Overview
Send 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 installed
```bash
which imsg
# If not found: brew install imsg

Step 2: Send a message

# Send to a phone number or Apple ID
imsg send --to "+1234567890" --message "Hello from Hermes"

# Send to a group
imsg send --to "+1234567890,+0987654321" --message "Team update"

Pitfalls

• Messages app must be logged in: Check System Settings → Messages
• Phone numbers need country code: Use +1 for US numbers
• Rate 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 | grep imessage
# 无输出（技能被隐藏）

hermes chat -q "send an iMessage to John"
# Agent 不会匹配到 send-imessage 技能
# 可能回复"当前系统不支持发送 iMessage"

4.3 实际内置技能示例

Hermes 内置技能中有多个平台限定的例子：

技能	platforms	依赖
apple-notes	[macos]	memo CLI
apple-reminders	[macos]	remindctl
findmy	[macos]	FindMy.app
imessage	[macos]	imsg CLI

---

五、常见问题

5.1 platforms 写错了怎么办

如果 platforms 写了一个不合法的值（如 osx 而非 macos），技能会怎样？

答案：技能会在所有平台上隐藏——因为没有系统能匹配 osx 这个值。这不是报错，而是静默隐藏。

排查方法：检查 platforms 取值是否是 macos、linux、windows 之一。

5.2 跨平台技能如何处理平台差异

一个技能需要在多个平台运行，但命令略有不同。处理方式：

在正文中用条件分支：

## Procedure

### Step 1: Install dependencies

**macOS:**
```bash
brew install jq

Linux:

apt-get install jq   # Debian/Ubuntu
yum install jq       # CentOS/RHEL

Windows (WSL):

apt-get install jq

Agent 会根据当前系统选择对应的命令。

---

## 本篇小结

| 知识点 | 核心内容 |
|--------|---------|
| platforms 作用 | 让技能在不兼容的操作系统上自动隐藏 |
| 取值 | macos / linux / windows |
| 三层隐藏 | 系统提示索引 → skills_list → 斜杠命令 |
| 检测时机 | 会话启动时静态过滤 |
| 默认行为 | 不写 platforms = 全平台可见 |
| 非法值 | 静默在所有平台隐藏（不报错） |
| 跨平台差异 | 正文中用条件分支处理不同系统的命令 |

---

## 下篇预告

下一篇讲解条件激活的另一个维度——fallback_for_toolsets 和 requires_toolsets。这是比平台限定更精细的激活控制：基于当前可用的工具集来决定技能的显隐。

---

> 如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。