MaaFramework中带选项任务的interface.json编写指南

在MaaFramework项目中，interface.json文件是定义任务接口的重要配置文件。对于需要带选项和参数的任务，其编写方式与普通任务有所不同，需要遵循特定的JSON Schema规范。

基本结构

带选项的任务在interface.json中主要通过"options"字段来定义。一个完整的带选项任务定义通常包含以下几个关键部分：

1. 任务名称(name)
2. 任务描述(description)
3. 选项列表(options)
4. 参数列表(params)

选项定义规范

options字段是一个数组，每个选项对象包含以下属性：

• name: 选项名称(必填)
• description: 选项描述(必填)
• type: 选项类型(如string, number, boolean等)
• default: 默认值(可选)
• required: 是否为必填项(可选，默认为false)
• enum: 枚举值列表(对于限定取值的选项)

参数定义规范

params字段也是一个数组，每个参数对象包含与选项类似的属性，但通常用于主任务参数而非选项。

示例解析

以下是一个典型的带选项任务定义示例：

{
  "name": "custom_task",
  "description": "这是一个带选项的自定义任务",
  "options": [
    {
      "name": "debug_mode",
      "description": "是否启用调试模式",
      "type": "boolean",
      "default": false
    },
    {
      "name": "retry_count",
      "description": "重试次数",
      "type": "number",
      "default": 3,
      "minimum": 1,
      "maximum": 10
    }
  ],
  "params": [
    {
      "name": "target",
      "description": "任务目标",
      "type": "string",
      "required": true
    }
  ]
}

最佳实践

1. 命名规范：使用下划线命名法(snake_case)来命名选项和参数
2. 类型明确：为每个选项和参数指定明确的类型
3. 默认值：为可选参数提供合理的默认值
4. 范围限制：对于数值型参数，使用minimum/maximum限制合理范围
5. 枚举值：对于有限取值的参数，使用enum列出所有可能值
6. 必填标记：明确标记必填参数(required: true)

验证与测试

编写完成后，建议使用JSON Schema验证工具检查配置文件的合法性。MaaFramework提供了完整的schema定义，可以确保配置符合规范。

通过遵循这些规范，开发者可以创建出结构清晰、易于维护的带选项任务配置，为自动化流程提供更灵活的控制能力。