Skip to content

插件数据面板(console_resources) ​

插件的数据(商品、订单、卡密库存……)平时存在 ctx.kv 里,只能在群里发指令才能改,安装者看不到也改不了。

在 plugin.json 里声明 console_resources 后,平台会在安装者的配置页渲染「左侧菜单 + 右侧表格」,安装者可以直接搜索、新增、编辑、删除、批量导入这些数据。面板读写的就是插件通过 ctx.kv 存的同一份数据(key 即资源的 key),插件代码一行都不用改,群里指令和面板改的是同一份数据。

声明方式 ​

json
{
  "console_resources": [
    {
      "key": "shop:products",
      "label": "商品管理",
      "mode": "crud",
      "id_field": "id",
      "title_field": "name",
      "search": ["name", "id"],
      "id_seq": { "seq_key": "shop:pseq", "prefix": "P", "start": 1000 },
      "columns": ["id", "name", "price", "stock"],
      "count": { "label": "在售商品", "where": { "on_sale": true } },
      "fields": [
        { "key": "id", "label": "ID", "type": "text", "readonly": true },
        { "key": "name", "label": "商品名", "type": "text", "required": true },
        { "key": "price", "label": "价格", "type": "money", "min": 0, "hint": "以元为单位输入,存储仍是分" },
        { "key": "stock", "label": "库存", "type": "number", "readonly": true },
        { "key": "on_sale", "label": "在售", "type": "switch" }
      ]
    },
    {
      "key": "shop:orders",
      "label": "订单记录",
      "mode": "readonly",
      "id_field": "id",
      "fields": [
        { "key": "id", "label": "订单号", "type": "text" },
        { "key": "buyer", "label": "买家", "type": "text" },
        { "key": "created_at", "label": "时间", "type": "datetime" }
      ]
    }
  ]
}

兼容旧字段名 console(写法相同),但推荐统一用 console_resources。

资源字段 ​

字段必填说明
key是ctx.kv 里的存储 key,如 shop:products;子资源可以用模板(见下方子资源),最多 80 字符
label是菜单显示名,最多 40 字
icon否菜单图标名,最多 24 字符
mode否crud = 可增删改查(默认);readonly = 只读列表(订单、日志这类),拒绝一切写操作
id_field否数据项的唯一 ID 字段名,默认 id(必须存在于 fields)
title_field否列表主标题字段
subtitle_field否列表副标题字段
search否搜索命中的字段 key 数组,最多 16 个
defaults否新建时的默认值。开关类字段务必在这里写 true,否则面板新建时默认关闭(如商品 "enabled": true,新建即上架)
id_seq否自增 ID:{ seq_key, prefix?, start? },新建时按 seq_key 递增,ID 格式 prefix + 数字,start 默认 1000
cascade否删除时一并清掉的关联 key 数组,支持 {id} 占位符,最多 16 个
sort否列表默认排序 { key, dir },dir 为 asc(默认)/ desc
columns否列表展示的列(字段 key),不填则自动取 id + 标题 + 前 3 个字段,最多 16 个
parent否子资源声明(见下方)
bulk否批量导入声明(见下方)
sync否子资源写入后回写父资源统计字段(见下方)
count否列表顶部统计 { label, where }:按条件计数并显示徽章
fields是字段声明数组,最多 100 个

字段类型 ​

fields 里每项的 type 可选:

type行为
text单行文本
textarea多行文本
number数字,支持 min / max / step
money金额:以「元」输入,存储仍是分(自动 ×100)
switch开关(布尔)
select下拉选择,必须提供 options: [{ label, value }](最多 100 项)
datetime时间戳,表格里格式化显示,编辑时只读

每个字段还可以声明:required(必填)、readonly(只读,面板里不可编辑)、hint(表单提示,最多 200 字)、placeholder、width(full 默认 / half 半宽)。

字段 key 规则:字母开头的字母/数字/下划线,最长 32 位(正则 [a-z][a-z0-9_]{0,31},不区分大小写)。

子资源(parent) ​

一个 key 管一类数据,但像「每个商品各自的卡密库存」这种一对多数据,可以用模板 key + parent 声明子资源:

json
{
  "key": "shop:inv:{pid}",
  "label": "卡密库存",
  "mode": "crud",
  "id_field": "id",
  "parent": { "resource": "shop:products", "param": "pid" },
  "id_seq": { "seq_key": "shop:cseq", "prefix": "C", "start": 10000 },
  "bulk": {
    "separator": "|",
    "map": { "content": 0, "extra": 1 },
    "dedupe": "content",
    "note_field": "batch",
    "max_lines": 500
  },
  "sync": { "resource": "shop:products", "field": "stock", "count_where": { "used": false, "voided": false } },
  "fields": [
    { "key": "content", "label": "卡密", "type": "textarea", "required": true },
    { "key": "used", "label": "已使用", "type": "switch" },
    { "key": "voided", "label": "已作废", "type": "switch" }
  ]
}

规则:

  • key 里的 {占位符} 必须与 parent.param 一致,且 parent.resource 必须指向同一清单里的普通资源(不能又是子资源);
  • 面板打开子资源前会先让安装者选一条父级数据(单父级时自动选中),存储 key 是模板替换后的实际 key(如 shop:inv:P1001);
  • 父级数据被删后,对应的子资源数据面板不再展示(可在插件的 cascade 里声明关联 key 一并清理)。

批量导入(bulk) ​

声明 bulk 后,子资源面板会出现「批量导入」按钮:安装者往文本框里粘贴多行,每行按 separator(默认 |,最长 4 字符)切片,按 map 的「字段 → 切片下标」映射写入;下标 -1 表示「剩余全部」(适合附加信息里可能含分隔符的场景)。

  • dedupe:按该字段去重,重复行跳过并在结果里提示;
  • note_field:导入时统一填写的「批次备注」;
  • max_lines:单次最多导入行数,默认 200,最大 1000;
  • 仅 mode: "crud" 的资源支持。

回写统计(sync)与列表统计(count) ​

  • sync:仅子资源可用。子资源增删改后,平台自动统计满足 count_where 条件的子项数,回写到 parent.resource 指向的父级数据的指定字段(如商品的 stock = 未使用且未作废的卡密数)。count_where 的值只能是 boolean / number / string。
  • count:任何资源可用。列表顶部显示一个按 where 条件计数的徽章。

限制与安全 ​

项值
资源数量每个插件最多 32 个
字段数量每个资源最多 100 个
单资源数据条数最多 50000 条
单个 key 数据体积最大 10MB
搜索字段 / 列 / cascade最多各 16 个

安全边界:

  • 面板只能操作当前登录用户自己那台机器人上的安装实例(install_id + user_id 双校验);
  • 只能写声明过的 key 和字段,字段值按类型强转,安装者无法把任意 JSON 塞进插件数据;
  • readonly 资源拒绝一切写操作;sync 会把统计结果直接写入父级字段,即使该字段声明为 readonly;
  • key 模板的父级值限制为 [A-Za-z0-9_-]{1,64},防止拼接出任意 key。

声明不合法的资源会被平台直接丢弃(不影响插件上传),建议对照完整示例逐字段检查。

审核与版本 ​

console_resources 与代码一起进入审核并跟随版本发布;待审版本不会提前改变已安装用户的面板,升级安装后才生效。

薇薇官机平台 · ZL 系列插件