2. 设置项与配置读写

插件可为每个机器人提供自定义设置，定义在 meta.settingsSchema 数组中。前端会自动渲染表单（无需单独写配置页）。

2.1 定义设置项

meta: {
  settingsSchema: [
    {
      key: 'api_key',              // 存储键名（写入 plugin_settings 表）
      label: 'API Key',            // 前端显示标签
      type: 'password',            // text / password / select / number / textarea
      placeholder: '请输入',        // 占位符
      help: '从 xxx 获取',          // 帮助文本
      options: [                   // 仅 type='select' 时可用
        { value: 'a', label: '选项A' },
        { value: 'b', label: '选项B' },
      ],
    },
  ],
},

2.2 读取设置（推荐）

lib/plugins.js 提供 loadPluginConfig(botId, pluginId)，返回扁平化的 { config_key: config_value }：

const plugins = require('../../lib/plugins');

async onMessage(msg, ctx) {
  const cfg = await plugins.loadPluginConfig(ctx.bot.id, 'my-plugin');
  const apiKey = cfg.api_key || '';   // 键名为 settingsSchema 里定义的 key
  // ...
}

2.3 底层直连 db（单个键 / 动态键）

plugin_settings 表以「bot_id + plugin_id + config_key → config_value」存储（非 JSON）：

const db = require('../../lib/db');

async function getSetting(botId, key, fallback) {
  const row = await db.row(
    'SELECT config_value FROM plugin_settings WHERE bot_id=? AND plugin_id=? AND config_key=?',
    [botId, 'my-plugin', key]
  );
  if (row && row.config_value != null && String(row.config_value).trim() !== '') return row.config_value;
  return fallback;
}

2.4 写入设置（运行时动态保存）

async function saveSetting(botId, key, value) {
  const existing = await db.row(
    'SELECT id FROM plugin_settings WHERE bot_id=? AND plugin_id=? AND config_key=?',
    [botId, 'my-plugin', key]
  );
  if (existing) {
    await db.exec('UPDATE plugin_settings SET config_value=? WHERE id=?', [value, existing.id]);
  } else {
    await db.exec(
      'INSERT INTO plugin_settings (bot_id, plugin_id, config_key, config_value) VALUES (?,?,?,?)',
      [botId, 'my-plugin', key, value]
    );
  }
}

2.5 连通性测试（verifyConnection）

在插件市场设置页提供「测试连接」按钮：

async function verifyConnection(cfg) {
  const resp = await axios.get(`${cfg.api_base}/status`, {
    timeout: 5000,
    headers: { 'Authorization': `Bearer ${cfg.api_key}` },
  });
  if (resp.status === 200) return { success: true, message: '连接成功' };
  return { success: false, message: `连接失败：${resp.status}` };
}

module.exports = { meta, verifyConnection, onMessage };

返回 { success: boolean, message: string }。

2.6 配置变更热重载（applyConfigChange）

导出 applyConfigChange(botId)，该插件配置被保存时会被自动调用（用于重建长连接、刷新缓存等）。框架在保存后会清除缓存并派发此钩子。