HeXi/dev/plugin_template/nonebot_plugin_template/README.md

插件模板(MTSS 结构)

按《插件结构标准 + 插件配置文件标准》编写的可复制插件骨架，含配置标准 + Web 子应用样例。

结构(MTSS)

nonebot_plugin_template/
├── __init__.py        # 入口(薄): require + meta + 导入 + config.register_config() + register_web_plugin
├── config.py          # 配置注册(register_model_config / register_config_items / register_object_set)
├── handlers/          # Trigger 层
│   ├── __init__.py
│   └── entry.py       # on_command 示例
├── services/          # Service 层(不 import nonebot)
│   └── main.py
├── models.py          # 模型/异常
├── repository.py      # Model 数据访问(唯一读写入口)
├── web/               # 可选: 插件自带 Web 子应用(FastAPI)
│   ├── __init__.py
│   └── admin.py       # build_admin_app() → 挂载到 /api/template
├── data/              # 运行时数据
└── utils/             # 纯工具

使用

1. 把 nonebot_plugin_template 目录复制到 hexi/plugins/nonebot_plugin_<name>。
2. 全局搜索替换 nonebot_plugin_template → nonebot_plugin_<name>，包括 _PLUGIN_ID 相关说明。
3. 在 __init__.py 改 __plugin_meta__ 的 name/description/usage，并把 register_web_plugin("template", ...) 的 id/name/icon 改掉；Web id 只能使用安全的短标识，不要直接使用带点的模块名。
4. 在 config.py 改成你要的配置项；在 handlers/entry.py 改成你的命令/触发。
5. 重启 bot；/hub 插件页能看到配置，点「打开 Web 页面」进入 /hub/template(子应用挂在 /api/template)。

Web 子应用

• web/admin.py::build_admin_app() 返回一个 FastAPI 实例，经 register_web_plugin 由 hub 挂载到 /api/template。
• 鉴权统一 hexi.web_hub.web_auth.require_admin；示例端点：GET /ping、GET /config(读插件配置)。
• 想要更丰富的管理页：前端放 web/dist/，在 admin.py 里挂 StaticFiles + SPA 兜底即可(参考 hexi/web_hub)。

约定

• plugin_id = 模块名(自动取 __package__；web 子应用用 __package__.rsplit(".", 1)[0])。
• Trigger/View 可 import nonebot；Service/Model/repository 尽量不 import nonebot。
• 配置默认值写进 schema，Web 自动回填；敏感字段 secret=True。GET 只显示 ****；保存配置时带上 GET 返回的 revision，修改冲突会返回 409。
• 同一 plugin_id 多次注册会自动合并(getter/apply 组合)，但字段 key 应由单一注册者负责，避免定义冲突。
• Service 中的文件/数据库访问应使用异步 repository 或 asyncio.to_thread，不要阻塞事件循环。