元数据

July 30, 2026 · View on GitHub

本页说明 PluginMetadata / extra 如何声明帮助、权限、冷却、热载与装包生效。平台按此消费；命令 ID 须全链路一致。

最小群命令插件可先看写第一个插件。热载与装包正交细节见 Reload 与 Activation。

必填面

字段	消费者
`name` / `description` / `usage`	帮助图、插件说明
`extra.menu_data`	帮助结构化入口、治理展示
`extra.help_tag`	帮助图总览分组（`core
`extra.help_audience`	帮助可见性：`superuser` / `maintainer` 时整插件不进普通总览
`extra.command_permissions`	matcher 权限、WebUI 覆盖、「何人可用」
`extra.command_limits`	冷却默认与展示
`extra.reload_policy`	热载分级
`extra.activation_policy`	扩展装包生效（官方 / 社区注册）

`usage` 与 `menu_data`

字段	职责
`usage`	命令展示；用 `usage_line` + `join_usage`
`menu_data`	`func` / `trigger_*` / `brief_des` / `detail_des`；权限绑 `command_permission(s)`

MUST NOT：在 usage 或 trigger_condition 写死权限角色。细则：cmd_perm。

帮助「谁能看见」用 help_audience（插件级或 menu_data 条目级），与「谁能执行」的 command_permissions 分开；普通 / 超管私聊双视图见牛牛帮助。

`command_permissions`

"command_permissions": [
    {"id": "my_plugin.demo", "label": "牛牛示例", "default": "everyone"},
]

同一 id 贯穿 matcher、WebUI 覆盖、帮助「何人可用」。

`command_limits`

"command_limits": [
    {"id": "my_plugin.demo", "cd_sec": 10},
]

即使 handler 内自行判断冷却，也 MUST 声明默认值。见 command_limits。

`llm_tools` 的素材透传

llm_command_tool_row() 默认不携带原消息的图片、@ 或「自己」，避免帮助、点歌等文本命令被追加无关参数。

画图、表情等需要引用素材的工具显式声明 source_segments="media"：

llm_command_tool_row(
    name="my_plugin.make",
    command_id="my_plugin.make",
    description="生成图片",
    parameters={"type": "object", "properties": {}},
    command_template="牛牛制作",
    source_segments="media",
)

media 会透传非 bot 的 @、图片与用户显式写出的「自己」；若原消息没有这些素材，则补「自己」供生成类插件使用。

`ingress_route`

可选。声明该插件在入站预筛里的车道与是否吃闲聊：

extra={
    "ingress_route": {
        "lane": "storage",   # 可选：command / chat / storage / remote 等调度档
        "passive": True,     # 闲聊严格模式下仍会激活（复读、智能对话、局内玩法等）
        "always_run": False, # 极少用：几乎每条群消息都激活
    },
}

热群默认开启闲聊严格预筛（PALLAS_CHAT_MATCHER_STRICT）：非命令消息主要只跑 passive / always_run 与路由命中的模块。

passive: true：声明本插件要吃闲聊车道（复读、智能对话、局内玩法等）。不标则严格模式下普通群聊可能收不到事件。
always_run: true：极少用；几乎每条群消息都激活，热群代价高。
lane：调度档位（与是否 passive 正交），如 storage / remote。

用户向说明（含对照表）见语料联邦 · 热闹群与入站设计。

`reload_policy`

类型：Literal["config_only", "metadata", "full"]（pallas.core.plugin_reload.metadata.ReloadPolicy）。默认 config_only。

值	含义
`config_only`	WebUI 保存配置即可；无需模块 reload
`metadata`	帮助 / 权限 / ingress 等声明变更需重建索引
`full`	需完整模块重载或重启

`activation_policy`

类型：Literal["hot-reloadable", "workers-restart", "full-restart"]。与 reload_policy 正交。

值	装包 / 升级后
`hot-reloadable`	可热载激活（视部署模式）
`workers-restart`	需重启 worker
`full-restart`	需全进程 / hub+worker 重启

官方表：OFFICIAL_EXTENSION_ACTIVATION_POLICY（plugin_matrix.py）。

最小组合

插件类型	MUST
纯命令型	`command_permissions` + `command_limits` + `menu_data`
维护者向	`help_audience`、`activation_policy`（若扩展）、WebUI/运维说明
带配置页	上列 + `reload_policy` + 热载接入

extra={
    "command_permissions": [
        {"id": "my_plugin.demo", "label": "牛牛示例", "default": "everyone"},
    ],
    "command_limits": [
        {"id": "my_plugin.demo", "cd_sec": 10},
    ],
    "reload_policy": "metadata",
    "activation_policy": "hot-reloadable",
}

可选增强：menu_template、plugin_storage、完整 menu_data、knowledge_sources。

检查

命令 ID 全链路一致
权限未写死在文案
帮助仅靠 metadata 可理解
装包生效方式已声明（扩展）

必填面

usage 与 menu_data

command_permissions

command_limits

llm_tools 的素材透传

ingress_route

reload_policy

activation_policy