开篇导语

在 OpenClaw 中，Skill 参数是用户与你的 Agent 交互的核心接口。设计良好的参数能让用户用得顺手、表达自然；设计糟糕的参数则会让用户困惑、放弃使用。本文将深入探讨 Skill 参数设计的最佳实践，帮助你打造用户友好的 Skill。

---

一、为什么参数设计重要

1.1 参数是用户界面

想象一下，你的 Skill 是一个应用程序，参数就是它的用户界面：

❌ 糟糕的设计：
/skill action="execute" target="file" path="/tmp/x" options={"a":1}

✅ 优秀的设计：
/skill 整理文件 路径=~/Downloads 分类=类型

1.2 好参数的标准

标准 | 说明 | 示例

|------|------|------|

直观 | 一看就懂，无需解释 | `路径` 比 `target_path` 更直观

简洁 | 用最少的字表达意思 | `分类` 比 `文件分类方式` 更简洁

一致 | 同类参数命名一致 | 都用 `路径` 而不是混用 `path/目录`

可选 | 提供合理默认值 | `分类=类型` 可省略，用默认值

灵活 | 支持多种输入方式 | 支持 `~/Downloads` 和 `/Users/xxx/Downloads`

---

二、参数类型

2.1 基础类型

#### 字符串参数

parameters:
  - name: 路径
    type: string
    required: true
    description: 要整理的文件路径
    example: ~/Downloads

最佳实践：

• 支持路径展开（`~` → 用户主目录）
• 支持相对路径和绝对路径
• 提供清晰的错误提示

#### 数字参数

parameters:
  - name: 数量
    type: number
    required: false
    default: 10
    min: 1
    max: 100
    description: 要处理的项目数量

最佳实践：

• 设置合理的范围限制
• 提供有意义的默认值
• 超出范围时给出友好提示

#### 布尔参数

parameters:
  - name: 递归
    type: boolean
    required: false
    default: false
    description: 是否递归处理子目录

最佳实践：

• 用肯定的命名（`递归` 而非 `不递归`）
• 默认值设为更安全的选项
• 支持多种输入（`是/否 `、`true/false`、`1/0`）

2.2 高级类型

#### 枚举参数

parameters:
  - name: 分类方式
    type: enum
    required: false
    default: 类型
    options:
      - 类型
      - 日期
      - 大小
      - 自定义
    description: 文件分类的方式

最佳实践：

• 选项不超过 5-7 个
• 按使用频率排序
• 提供"自定义"等扩展选项

#### 数组参数

parameters:
  - name: 扩展名
    type: array
    required: false
    default: ["pdf", "doc", "docx"]
    description: 要处理的文件扩展名
    example: pdf,doc,txt

最佳实践：

• 支持多种分隔符（逗号、空格）
• 自动去重和标准化
• 提供常用默认值

#### 对象参数

parameters:
  - name: 规则
    type: object
    required: false
    description: 自定义分类规则
    example: {"pdf": "文档", "jpg": "图片"}

最佳实践：

• 提供清晰的格式说明
• 支持简写语法
• 验证对象结构

---

三、参数命名

3.1 命名原则

✅ 好的命名：
路径
分类方式
目标目录
是否递归

❌ 糟糕的命名：
path
type
dest
recursive_flag

3.2 命名规范

场景 | 推荐 | 避免

|------|------|------|

文件路径 | `路径 `、` 源路径 `、` 目标路径` | `path`、`src`、`dst`

数量 | `数量 `、` 限制 `、` 最大数量` | `count`、`num`、`limit`

开关 | `是否 xxx`、`启用 xxx` | `xxx_flag`、`enable_xxx`

类型 | `类型 `、` 方式 `、` 模式` | `type`、`mode`

3.3 避免歧义

❌ 歧义命名：
类型（是文件类型？还是分类方式？）
模式（是操作模式？还是匹配模式？）

✅ 清晰命名：
文件类型
分类方式
操作模式
匹配模式

---

四、默认值设计

4.1 何时使用默认值

# ✅ 应该有默认值
有安全默认值的参数
常用场景的参数
新手友好的参数

❌ 不应该有默认值
必须用户指定的参数
默认值可能导致问题的参数
上下文相关的参数

4.2 默认值原则

parameters:
  - name: 路径
    required: true  # ❌ 必须用户提供
    description: 要处理的目录
    
  - name: 递归
    default: false  # ✅ 安全默认值
    description: 是否处理子目录
    
  - name: 数量
    default: 10     # ✅ 合理默认值
    description: 处理多少文件

4.3 智能默认值

根据上下文提供智能默认值：

// 示例：根据时间提供默认值
function getDefaultDateRange() {
  const today = new Date();
  const isMonday = today.getDay() === 1;
  
  if (isMonday) {
    return '上周';  // 周一默认看上周
  } else {
    return '昨天';  // 其他时间默认看昨天
  }
}

---

五、参数验证

5.1 基础验证

parameters:
  - name: 路径
    type: string
    required: true
    validate:
      - exists: true      # 路径必须存在
      - type: directory   # 必须是目录
      - writable: true    # 必须可写
      
  - name: 数量
    type: number
    validate:
      - min: 1
      - max: 1000
      - integer: true

5.2 自定义验证

// 自定义验证函数
async function validatePath(path) {
  // 检查路径是否存在
  if (!fs.existsSync(path)) {
    throw new Error(`路径不存在：${path}`);
  }
  
  // 检查是否是目录
  const stats = fs.statSync(path);
  if (!stats.isDirectory()) {
    throw new Error(`不是目录：${path}`);
  }
  
  // 检查权限
  try {
    fs.accessSync(path, fs.constants.W_OK);
  } catch {
    throw new Error(`没有写入权限：${path}`);
  }
  
  return true;
}

5.3 错误提示

❌ 糟糕的错误提示：
参数验证失败：路径无效

✅ 优秀的错误提示：
路径 "~/notexist" 不存在，请检查路径是否正确

可用选项：
~/Downloads
~/Documents
~/Desktop

---

六、参数组合

6.1 互斥参数

parameters:
  - name: 路径
    type: string
    description: 单个文件路径
    
  - name: 目录
    type: string
    description: 目录路径
    
  # 互斥规则
  constraints:
    - oneOf: [路径，目录]

6.2 依赖参数

parameters:
  - name: 分类方式
    type: enum
    options: [类型，日期，自定义]
    
  - name: 自定义规则
    type: object
    required: false
    # 仅当分类方式=自定义时需要
    when: "分类方式 == '自定义'"

6.3 参数组

parameterGroups:
  - name: 源配置
    parameters: [源路径，源类型]
    
  - name: 目标配置
    parameters: [目标路径，覆盖策略]
    
  - name: 高级选项
    parameters: [递归，过滤规则，日志级别]
    optional: true

---

七、实战示例

7.1 文件整理 Skill

name: 整理文件
description: 自动整理指定目录中的文件

parameters:
  - name: 路径
    type: string
    required: true
    description: 要整理的目录路径
    example: ~/Downloads
    
  - name: 分类方式
    type: enum
    required: false
    default: 类型
    options:
      - 类型
      - 日期
      - 大小
    description: 文件分类的方式
    
  - name: 递归
    type: boolean
    required: false
    default: false
    description: 是否处理子目录
    
  - name: 过滤
    type: array
    required: false
    default: []
    description: 只处理指定扩展名的文件
    example: pdf,doc,txt
    
  - name: 预览
    type: boolean
    required: false
    default: true
    description: 是否先预览再执行

7.2 天气查询 Skill

name: 天气查询
description: 查询指定城市的天气

parameters:
  - name: 城市
    type: string
    required: false
    default: 当前城市
    description: 要查询的城市名
    example: 北京
    
  - name: 天数
    type: number
    required: false
    default: 3
    min: 1
    max: 15
    description: 查询几天的天气预报
    
  - name: 详细
    type: boolean
    required: false
    default: false
    description: 是否显示详细信息

---

八、测试与迭代

8.1 参数测试清单

• [ ] 所有必填参数都能正确识别
• [ ] 默认值在省略参数时生效
• [ ] 边界值（最小/最大）处理正确
• [ ] 无效输入给出友好错误提示
• [ ] 参数组合规则正确执行
• [ ] 帮助信息清晰完整

8.2 用户反馈

收集用户反馈，持续改进：

用户常见问题：
"这个参数是什么意思？" → 改进描述
"能不能不写这个参数？" → 考虑加默认值
"我想同时用 A 和 B" → 检查互斥规则
"能不能记住我的选择？" → 考虑持久化

---

总结

好的参数设计让用户用得爽，差的参数设计让用户想放弃。记住以下要点：

设计原则：

• ✅ 直观：一看就懂
• ✅ 简洁：用最少的字
• ✅ 一致：命名风格统一
• ✅ 灵活：支持多种输入
• ✅ 安全：合理的默认和验证

避坑指南：

• ❌ 避免技术术语
• ❌ 避免歧义命名
• ❌ 避免必填过多
• ❌ 避免验证不足
• ❌ 避免错误提示模糊

记住：参数设计不是一次性的工作，而是需要持续迭代的过程。多听用户反馈，不断改进，让你的 Skill 越用越顺手！

---

本文属于「OpenClaw 小龙虾专区」系列专题
版本：v1.0

本文标签：OpenClaw , Skill , 参数设计