脚本配置 JSON 开发指南

Aimaxbot 支持通过一个统一的 JSON 配置文件，动态渲染客户端脚本的设置界面。开发者可以通过此配置文件定义脚本运行所需的各项参数，如工作模式、模块开关、数值限制、多行文本输入、下拉列表、数值滑块以及各种级联的子配置。

配置文件核心结构

配置文件是一个 JSON 数组，数组中的每个元素代表一个配置组件。配置组件可以相互嵌套，形成复杂的设置层级。

支持的通用属性

所有配置组件都支持以下通用属性：

属性名	类型	是否必填	说明
`name`	`string`	是	组件的变量名/唯一标识符。在脚本运行中，通过该字段获取用户配置的实际值。
`type`	`string`	是	组件类型。支持 `text`, `textarea`, `number`, `radio`, `select`, `slider`, `checkbox`, `switch`, `group` 九种。
`label`	`string`	是	组件在界面上显示的标题/标签文本。
`help`	`string`	否	辅助说明或提示文本。会以小字形式显示在组件下方。
`placeholder`	`string`	否	输入框或下拉框未输入/未选择时的默认占位提示文本。
`value`	`any`	否	组件的默认值（在 `children` 或其他类型中常用作默认值）。
`default`	`any`	否	组件的默认值（在 `radio` 等单选组件中常用作默认值）。
`min`	`number`	否（仅对 `number` 和 `slider` 有效）	支持输入的最小值或滑块的起点，默认值为 `0`。
`max`	`number`	否（仅对 `number` 和 `slider` 有效）	支持输入的最大值或滑块的终点，默认值为 `100`。
`step`	`number`	否（仅对 `slider` 有效）	滑动条的调整步长（如 1、5 等），默认值为 `1`。
`rows`	`number`	否（仅对 `textarea` 有效）	多行文本框的默认行数，默认值为 `3`。
`options`	`array`	否（特定组件必填）	选项列表，用于 `radio`, `select` 和 `checkbox`。
`children`	`array`	否（特定组件必填）	子组件数组，用于 `group` 和 `checkbox` 进行级联嵌套。

九大核心组件详解

1. 单行文本输入框 (text)

用于收集用户输入的单行字符串参数，例如 API 密钥、设备名称、服务器 IP 地址等。

格式定义

json

{
  "name": "api_key",
  "type": "text",
  "label": "第三方 API 密钥",
  "placeholder": "请输入 Key",
  "help": "请输入您的第三方平台 API Key 用于身份验证",
  "value": "your_api_key_here"
}

关键字段说明

value: 输入框中的默认文本（可选）。
placeholder: 未输入内容时的占位符提示。

2. 多行文本框 (textarea)

用于收集用户输入的较长文本，比如多段关键词列表、多行备注、运行白名单等。

格式定义

json

{
  "name": "white_list",
  "type": "textarea",
  "label": "全局白名单列表",
  "placeholder": "每行输入一个 ID...",
  "rows": 4,
  "help": "用于配置过滤条件，多项输入请使用换行分隔",
  "value": "user_id_1\nuser_id_2"
}

关键字段说明

rows: 文本域的纵向展示高度，默认渲染为 3 行。
value: 默认输入的多行文本内容。

3. 数字输入框 (number)

用于收集用户输入的数值参数，如重试次数、超时限制、间隔时间等。

格式定义

json

{
  "name": "max_retry_count",
  "type": "number",
  "label": "最大重试次数",
  "help": "任务失败时的最大尝试次数，默认为 3 次",
  "value": "3"
}

关键字段说明

value: 输入框中的默认数值（以字符串形式传入，可选）。

4. 单选按钮 (radio)

提供一组互斥的选项，以平铺按钮的形式排列，用户只能选择其中一个。

格式定义

json

{
  "name": "work_mode",
  "type": "radio",
  "label": "工作运行模式",
  "options": [
    { "value": "standard", "label": "标准模式" },
    { "value": "compat", "label": "兼容模式" }
  ],
  "default": "standard"
}

关键字段说明

options: 选项数组，每个选项包含：
- value: 选中时对应的变量值。
- label: 界面上显示的选项名称。
default: 默认选中的 value 值。

5. 下拉选择器 (select)

功能与单选按钮 (radio) 相同，但以折叠下拉列表的形式呈现。适合选项较多时使用，避免页面过于冗长。

格式定义

json

{
  "name": "timezone",
  "type": "select",
  "label": "同步时区",
  "placeholder": "请选择时区",
  "options": [
    { "value": "gmt_8", "label": "北京时间 (GMT+8)" },
    { "value": "gmt_0", "label": "格林威治时间 (GMT)" },
    { "value": "gmt_est", "label": "美东时间 (EST)" }
  ],
  "value": "gmt_8"
}

关键字段说明

options: 下拉可选项列表，每个元素包含 value 和 label。
value: 默认选中的 value 值。

6. 数值滑动条 (slider)

用于以可视化的滑块形式调节数值范围。特别适合微调声音大小、任务运行阈值、亮度百分比或限制延迟时间等。

格式定义

json

{
  "name": "brightness_level",
  "type": "slider",
  "label": "设备运行亮度",
  "min": 10,
  "max": 100,
  "step": 5,
  "value": 50,
  "help": "调节该脚本在静默执行时的模拟设备亮度比例，默认为 50"
}

关键字段说明

min: 最小值起起点，默认为 0。
max: 最大值终点，默认为 100。
step: 滑块拖拽的步长增量（如每拖动格加 5），默认为 1。
value: 默认被调节数值。

7. 开关 (switch)

用于开关布尔型参数（true/false），如开启某项实验性功能、启用本地通知等。

格式定义

json

{
  "name": "enable_notify",
  "type": "switch",
  "label": "自动发送通知",
  "help": "脚本完成后是否通过通知渠道发送报告",
  "value": true
}

关键字段说明

value: 布尔默认值（true 或 false）。在渲染时，会以滑动开关样式展示。

8. 复选框与级联项 (checkbox)

提供多个可选项目，支持用户勾选零个或多个。此外，checkbox 还支持嵌套 children。当用户勾选了对应的大项后，其下面的子配置项才会在界面展开供用户配置。

格式定义

json

{
  "name": "enable_modules",
  "type": "checkbox",
  "label": "高级模块启用",
  "options": [
    { "value": "module_log", "label": "日志上报模块" },
    { "value": "module_clean", "label": "自动清理模块" }
  ],
  "children": [
    {
      "name": "clean_interval_sec",
      "type": "number",
      "label": "清理间隔时间（秒）",
      "value": "300"
    }
  ]
}

关键字段说明

options: 多选选项列表。每个选项包含 value 和 label。
children: （可选）子配置组件数组。只有当用户开启了该 checkbox 大项后，下方的子组件才会动态展示出来。

9. 分组容器 (group)

用于将多个相关的配置项聚合在一起。界面上会渲染成一个具有标题的独立区块，使复杂设置项排列井然有序。

格式定义

json

{
  "name": "notification_group",
  "type": "group",
  "label": "消息通知设置",
  "children": [
    {
      "name": "notify_enable",
      "type": "switch",
      "label": "是否开启通知",
      "value": false
    },
    {
      "name": "receiver_address",
      "type": "text",
      "label": "通知接收邮箱",
      "help": "用于接收通知的电子邮件地址"
    }
  ]
}

关键字段说明

children: 分组内包含的子组件数组，支持嵌套定义任意组件。

综合配置 JSON 示例

以下是一个涵盖所有 9 类组件的脱敏配置 JSON 示例：

json

[
  {
    "name": "basic_settings",
    "type": "group",
    "label": "1. 基础运行设置",
    "children": [
      {
        "name": "work_mode",
        "type": "radio",
        "label": "工作运行模式",
        "options": [
          { "value": "standard", "label": "标准模式" },
          { "value": "compat", "label": "兼容模式" }
        ],
        "default": "standard"
      },
      {
        "name": "access_token",
        "type": "text",
        "label": "服务访问令牌",
        "help": "用于访问后台服务所需的身份授权验证"
      }
    ]
  },
  {
    "name": "alert_settings",
    "type": "group",
    "label": "2. 提醒与通知配置",
    "children": [
      {
        "name": "notify_channel",
        "type": "select",
        "label": "通知发送渠道",
        "options": [
          { "value": "email", "label": "电子邮件" },
          { "value": "webhook", "label": "Webhook 推送" }
        ],
        "value": "email"
      },
      {
        "name": "volume_level",
        "type": "slider",
        "label": "通知警报音量",
        "min": 0,
        "max": 100,
        "step": 10,
        "value": 50
      },
      {
        "name": "silence_mode",
        "type": "switch",
        "label": "夜间免打扰模式",
        "value": true
      }
    ]
  },
  {
    "name": "advanced_settings",
    "type": "group",
    "label": "3. 扩展模块管理",
    "children": [
      {
        "name": "active_features",
        "type": "checkbox",
        "label": "功能模块选择",
        "options": [
          { "value": "feature_analytics", "label": "统计分析" },
          { "value": "feature_backup", "label": "备份恢复" }
        ],
        "children": [
          {
            "name": "backup_frequency",
            "type": "number",
            "label": "自动备份频率（小时）",
            "value": "24"
          },
          {
            "name": "custom_rules",
            "type": "textarea",
            "label": "自定义备份规则",
            "placeholder": "请输入自定义过滤后缀（例如 .log）...",
            "rows": 3
          }
        ]
      }
    ]
  }
]

在脚本中获取运行配置

在运行环境启动时，系统会将本次执行的配置参数以一个全局对象 aimaxbot 的形式直接注入。

开发者可以直接在脚本的任何地方直接访问全局变量 aimaxbot 从而取得所有配置字段。

1. 嵌套结构解析说明

aimaxbot 全局变量会完全保留配置所定义的嵌套层级结构（除了特定系统大项以外，所有嵌套在 group 和 checkbox 内部的子项都会包裹在其父级变量名下）。

因此，读取嵌套属性时，需通过 aimaxbot.父组名.子项名 的方式进行读取。

2. 读取基础与分组配置示例

根据前文的综合配置 JSON 示例，脚本读取配置的标准示例如下：

javascript

// 1. 读取嵌套在 group "basic_settings" 内的基本参数
const workMode = aimaxbot.basic_settings.work_mode || "standard";
const apiToken = aimaxbot.basic_settings.access_token || "";

// 2. 读取嵌套在 group "alert_settings" 内的参数
const channel = aimaxbot.alert_settings.notify_channel || "email";
const alertVolume = aimaxbot.alert_settings.volume_level || 50;

// 3. 读取开关状态 (switch - 自动解析为布尔值)
if (aimaxbot.alert_settings.silence_mode === true) {
    // 开启了夜间免打扰
}

3. 读取复选框与子配置级联数据

对于带有子项的复选框 (checkbox)，读取规则与分组一致：

_enabled (boolean): 表示该大模块是否勾选开启。
rw_list (array): 包含多选选项（options）中被勾选启用的选项值列表。
级联子参数：其他嵌套在 children 里的子组件值，会作为该子对象的平级属性。

读取示例：

javascript

// 1. 获取 checkbox "active_features" 对象的引用
const activeFeaturesObj = aimaxbot.advanced_settings.active_features;

// 2. 判断该功能大项是否启用
if (activeFeaturesObj && activeFeaturesObj._enabled === true) {
    
    // 3. 获取选中的多选功能列表 (rw_list 数组)
    const rwList = activeFeaturesObj.rw_list || [];
    
    // 检查是否勾选了“备份恢复”
    if (rwList.indexOf("feature_backup") !== -1) {
        
        // 4. 读取同样嵌套在 active_features 对象里的级联参数
        const backupFreq = activeFeaturesObj.backup_frequency || 24;
        const customRules = activeFeaturesObj.custom_rules || "";
    }
}

脚本配置 JSON 开发指南 ​

配置文件核心结构 ​

支持的通用属性 ​

九大核心组件详解 ​

1. 单行文本输入框 (text) ​

格式定义 ​

关键字段说明 ​

2. 多行文本框 (textarea) ​

格式定义 ​

关键字段说明 ​

3. 数字输入框 (number) ​

格式定义 ​

关键字段说明 ​

4. 单选按钮 (radio) ​

格式定义 ​

关键字段说明 ​

5. 下拉选择器 (select) ​

格式定义 ​

关键字段说明 ​

6. 数值滑动条 (slider) ​

格式定义 ​

关键字段说明 ​

7. 开关 (switch) ​

格式定义 ​

关键字段说明 ​

8. 复选框与级联项 (checkbox) ​

格式定义 ​

关键字段说明 ​

9. 分组容器 (group) ​

格式定义 ​

关键字段说明 ​

综合配置 JSON 示例 ​

在脚本中获取运行配置 ​

1. 嵌套结构解析说明 ​

2. 读取基础与分组配置示例 ​

3. 读取复选框与子配置级联数据 ​

读取示例： ​

脚本配置 JSON 开发指南

配置文件核心结构

支持的通用属性

九大核心组件详解

1. 单行文本输入框 (text)

格式定义

关键字段说明

2. 多行文本框 (textarea)

格式定义

关键字段说明

3. 数字输入框 (number)

格式定义

关键字段说明

4. 单选按钮 (radio)

格式定义

关键字段说明

5. 下拉选择器 (select)

格式定义

关键字段说明

6. 数值滑动条 (slider)

格式定义

关键字段说明

7. 开关 (switch)

格式定义

关键字段说明

8. 复选框与级联项 (checkbox)

格式定义

关键字段说明

9. 分组容器 (group)

格式定义

关键字段说明

综合配置 JSON 示例

在脚本中获取运行配置

1. 嵌套结构解析说明

2. 读取基础与分组配置示例

3. 读取复选框与子配置级联数据

读取示例：