插件数据面板(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 与代码一起进入审核并跟随版本发布;待审版本不会提前改变已安装用户的面板,升级安装后才生效。
