配置参数设计

配置参数是技能与用户交互的界面。用户安装技能时看到的表单，就来自 config.schema.json。设计好配置参数，让用户填得顺手、不困惑。

配置文件结构

config.schema.json 遵循 JSON Schema 规范：

{
  "type": "object",
  "required": ["city", "api_key"],
  "properties": {
    "city": {
      "type": "string",
      "title": "城市",
      "description": "要获取天气的城市名称（英文）",
      "default": "Beijing"
    },
    "api_key": {
      "type": "string",
      "title": "API Key",
      "description": "在 openweathermap.org 免费注册获取",
      "format": "password"
    }
  }
}

字段详解

字段必填说明
type是参数类型：string、number、integer、boolean
title推荐显示给用户的标签（中文友好）
description推荐帮助文本，解释参数用途
default推荐默认值，降低用户填写负担
enum可选限定可选值，生成下拉菜单
format可选特殊格式："password"（敏感输入）、"uri"（URL）
pattern可选正则表达式校验
minimum/maximum可选数值范围

设计原则

1. 给默认值——降低填写门槛

每个参数尽可能提供合理的默认值。用户不填也能用，想定制再改。

✅ 好的设计：

{
  "push_time": {
    "type": "string",
    "title": "推送时间",
    "description": "每天推送天气的时间",
    "default": "08:00"
  }
}

❌ 差的设计：

{
  "push_time": {
    "type": "string",
    "title": "推送时间",
    "description": "请输入推送时间，格式 HH:MM"
  }
}

没有默认值，用户必须手动输入，而且不知道填什么格式。

2. 用 enum 代替自由文本——减少出错

当参数只有几个可选值时，用 enum 生成下拉菜单，而非让用户输入。

✅ 好的设计：

{
  "language": {
    "type": "string",
    "title": "语言",
    "enum": ["zh", "en"],
    "default": "zh"
  }
}

❌ 差的设计：

{
  "language": {
    "type": "string",
    "title": "语言",
    "description": "请输入语言代码：zh 或 en"
  }
}

用户可能输入 Chinese、中文、zh-CN，都不对。

3. 敏感信息用 format: password

API Key、Token、密码等敏感信息，用 "format": "password" 标记，前端会显示为密码输入框。

{
  "api_key": {
    "type": "string",
    "title": "OpenWeatherMap API Key",
    "description": "在 openweathermap.org 免费注册获取",
    "format": "password"
  }
}

4. 用 title 和 description 引导用户

title 是标签，短而清晰。description 是帮助文本，告诉用户「这是什么、从哪获取、怎么填」。

{
  "api_key": {
    "type": "string",
    "title": "API Key",
    "description": "在 openweathermap.org 注册后，在「My API Keys」页面获取"
  },
  "webhook_url": {
    "type": "string",
    "title": "飞书 Webhook 地址",
    "description": "在飞书群设置 → 群机器人 → 添加机器人 → 复制 Webhook 地址",
    "format": "uri"
  }
}

5. 必填参数越少越好

必填参数是用户安装的障碍。每多一个必填参数，就多一个用户放弃安装的理由。

原则：

  • 能设默认值的，不设必填
  • 能自动获取的，不让用户填
  • 只能用户提供的（如 API Key），才设必填

6. 分组和排序

将相关参数放在一起，按使用频率排序。最常用的参数放最前面。

{
  "properties": {
    "city": { "title": "城市", "default": "Beijing" },
    "api_key": { "title": "API Key", "format": "password" },
    "push_time": { "title": "推送时间", "default": "08:00" },
    "language": { "title": "语言", "enum": ["zh", "en"], "default": "zh" },
    "units": { "title": "温度单位", "enum": ["celsius", "fahrenheit"], "default": "celsius" }
  }
}

参数顺序：核心功能参数 → 辅助参数 → 外观/偏好参数。

参数类型速查

需求类型示例
文本输入string城市名称、用户名
数字输入number温度阈值、超时时间
开关boolean是否开启通知
下拉选择string + enum语言、单位
密码/Tokenstring + format: "password"API Key
网址string + format: "uri"Webhook URL
正则校验string + pattern时间格式 HH:MM

完整示例：会议纪要助手的配置

{
  "type": "object",
  "required": ["meeting_language", "output_format"],
  "properties": {
    "meeting_language": {
      "type": "string",
      "title": "会议语言",
      "description": "会议主要使用的语言",
      "enum": ["zh", "en", "ja", "auto"],
      "default": "zh"
    },
    "output_format": {
      "type": "string",
      "title": "纪要格式",
      "description": "生成的会议纪要格式",
      "enum": ["standard", "detailed", "brief"],
      "default": "standard"
    },
    "auto_send_email": {
      "type": "boolean",
      "title": "自动发送邮件",
      "description": "纪要生成后自动发送给参会人员",
      "default": false
    },
    "recipient_emails": {
      "type": "string",
      "title": "收件人邮箱",
      "description": "多个邮箱用逗号分隔，仅在开启自动发送时需要",
      "default": ""
    },
    "max_duration_minutes": {
      "type": "integer",
      "title": "最长会议时长（分钟）",
      "description": "超过此时长的会议将分段记录",
      "default": 60,
      "minimum": 10,
      "maximum": 240
    }
  }
}

自检清单

写完 config.schema.json 后，逐条检查：

  1. 每个参数有默认值（除了 API Key 类敏感信息）
  2. 可选值用了 enum（而非让用户自由输入）
  3. 敏感信息标记了 format: "password"
  4. 每个参数有 title 和 description
  5. 必填参数不超过 3 个
  6. 参数按使用频率排序
  7. description 告诉用户从哪获取、怎么填

← 工具定义指南 | 技能测试与调试 →

返回文档中心