modify: 插件初始化

README.md

@@ -18,10 +18,77 @@ uv pip install -e utils/worker
 - **自动参数解析**：根据 HTTP 方法从 query 参数或 JSON body 解析请求
 - **Pydantic 模型绑定**：`auto_bind_models()` 自动绑定生成的模型
 - **Worker 运行时**：`create_worker` / `create_workers` 管理生命周期
+- **`Plugin` 基类**：统一插件初始化 / 清理生命周期（幂等、日志、数据库、后台任务、清理钩子）
 - **配置加载**：`load_worker_config` 读取 TOML 配置
 
 ---
 
+## Plugin 基类（推荐）
+
+`chongming_worker.plugin.Plugin` 统一了各插件 `__init__.py` 的初始化/清理风格，
+消除重复样板（数据库初始化、global_var 写入、幂等保护、后台任务、日志、清理钩子）。
+
+### 最小示例
+
+```python
+# src/plugins/my_plugin/__init__.py
+import logging
+
+from chongming_worker import auto_bind_models
+from chongming_worker.plugin import Plugin
+
+from . import router  # noqa: F401  触发 @rpc_method 注册
+# from .routes import router  # 可选：自定义 FastAPI 路由（网关自动发现）
+
+logger = logging.getLogger(__name__)
+
+auto_bind_models("my_plugin")
+
+
+class MyPlugin(Plugin):
+    type = "my_plugin"
+    db_name = "my_plugin.db"   # 自动在 data_dir 下建 SQLite 库；不需要则置 None
+    auto_bind = True           # 首次初始化时自动 auto_bind_models(self.type)
+
+    async def on_init(self):
+        # 数据库已由基类自动初始化（self.db）
+        self.set_var("db", self.db)          # 写入插件 global_var 模块
+        # self.spawn_task(self._background_loop())   # 后台任务（cleanup 自动取消）
+        # self.register_cleanup(self._close_client)  # 注册清理钩子（逆序执行）
+
+    async def on_cleanup(self):
+        # 关闭自定义客户端等（后台任务与数据库由基类统一处理）
+        ...
+
+
+# 暴露给 app lifespan 的模块级入口（bound method，签名与旧写法一致）
+plugin = MyPlugin()
+create_workers = plugin.create_workers
+cleanup = plugin.cleanup
+```
+
+### 子类可覆写点
+
+| 属性 / 方法    | 说明                                                                         |
+| -------------- | ---------------------------------------------------------------------------- |
+| `type`         | 插件类型（worker type），匹配 subject 前缀与 `config/workers/<type>`（必填） |
+| `db_name`      | 默认 SQLite 文件名（放 `data_dir` 下）；`None` 表示不自动建库                |
+| `auto_bind`    | 首次初始化时是否自动 `auto_bind_models(self.type)`                           |
+| `on_init()`    | 首次 `create_workers` 时调用一次，初始化资源                                 |
+| `on_cleanup()` | `cleanup` 时调用，清理自定义资源                                             |
+
+### 框架自动处理
+
+- **幂等**：重复 `create_workers` 只初始化一次（旧写法需手写 `_initialized` 标志）
+- **统一日志**：`logger` 自动带 `[type]` 前缀
+- **数据库**：`init_database()` 统一建路径、建表、记录，`cleanup` 自动 `dispose()`
+- **global_var**：`set_var()` / `get_var()` 统一读写插件 `global_var` 模块
+- **后台任务**：`spawn_task()` 跟踪，`cleanup` 时自动取消并 `gather`
+- **清理钩子**：`register_cleanup()` 注册，`cleanup` 时逆序执行
+- **委托**：自动调用 `runtime.create_workers` 创建 Worker 副本
+
+---
+
 ## API
 
 ### `@rpc_method` 装饰器
@@ -95,6 +162,8 @@ cfg = load_worker_config("example")
 
 ## 插件集成模式
 
+> 推荐使用上文的 **Plugin 基类**；以下为不依赖基类的传统写法（仍受支持）。
+
 ```python
 # src/plugins/my_plugin/__init__.py
 from chongming_worker import auto_bind_models
@@ -103,15 +172,20 @@ from .router import *  # 触发 @rpc_method 注册
 
 auto_bind_models("my_plugin")
 
+_initialized = False
+
 async def create_workers(session, config, count, worker_manager):
     """插件入口：初始化资源，启动 Worker"""
+    global _initialized
+    if _initialized:
+        return _create_workers(session, config, count, worker_manager)
     from chongming_database import Database
     from .global_var import set_db
 
     db = Database(...)
     await db.initialize()
     set_db(db)
-
+    _initialized = True
     return _create_workers(session, config, count, worker_manager)
 
 async def cleanup(worker_manager):
@@ -132,6 +206,7 @@ from chongming_worker import (
     load_worker_config,             # TOML 配置加载
     WorkerConfig, OperationConfig,  # 配置类型
     create_worker, create_workers,  # 运行时
+    Plugin,                         # 统一生命周期基类
 )
 ```