元数据

July 25, 2026 · View on GitHub

PluginMetadata / extra 声明帮助、权限、冷却、热载与装包生效；平台按此消费。

必填面

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

usage 与 menu_data

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

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

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。

reload_policy

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

值含义
config_onlyWebUI 保存配置即可；无需模块 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 可理解
  • 装包生效方式已声明（扩展）

相关