modify: 插件风格统一

README.md

@@ -14,10 +14,11 @@ uv pip install -e utils/worker
 
 ## 核心功能
 
-- **`@rpc_method` 装饰器**：将异步函数注册为 Zenoh Queryable 端点
+- **`@rpc_method` 装饰器**：将异步函数注册为 Zenoh Queryable 端点（同 `subject#METHOD` 冲突注册即报错）
 - **自动参数解析**：根据 HTTP 方法从 query 参数或 JSON body 解析请求
 - **Pydantic 模型绑定**：`auto_bind_models()` 自动绑定生成的模型
-- **Worker 运行时**：`create_worker` / `create_workers` 管理生命周期
+- **信封协议**：请求负载统一为 `{"meta": {...}, "data": {...}}`，运行时按 `meta.method` 分派
+- **Worker 运行时**：`create_worker` / `create_workers` 管理生命周期（结构化日志）
 - **`Plugin` 基类**：统一插件初始化 / 清理生命周期（幂等、日志、数据库、后台任务、清理钩子）
 - **配置加载**：`load_worker_config` 读取 TOML 配置
 
@@ -34,7 +35,6 @@ uv pip install -e utils/worker
 # 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 注册
@@ -42,8 +42,6 @@ from . import router  # noqa: F401  触发 @rpc_method 注册
 
 logger = logging.getLogger(__name__)
 
-auto_bind_models("my_plugin")
-
 
 class MyPlugin(Plugin):
     type = "my_plugin"
@@ -79,13 +77,13 @@ cleanup = plugin.cleanup
 
 ### 框架自动处理
 
-- **幂等**：重复 `create_workers` 只初始化一次（旧写法需手写 `_initialized` 标志）
+- **幂等**：重复 `create_workers` 只初始化一次（`asyncio.Lock` 守卫，并发调用安全）
 - **统一日志**：`logger` 自动带 `[type]` 前缀
 - **数据库**：`init_database()` 统一建路径、建表、记录，`cleanup` 自动 `dispose()`
-- **global_var**：`set_var()` / `get_var()` 统一读写插件 `global_var` 模块
+- **global_var**：`set_var()` / `get_var()` 统一读写插件 `global_var` 模块；`cleanup` 时自动将已发布的变量重置为 `None`，避免业务代码拿到已释放的资源
 - **后台任务**：`spawn_task()` 跟踪，`cleanup` 时自动取消并 `gather`
 - **清理钩子**：`register_cleanup()` 注册，`cleanup` 时逆序执行
-- **委托**：自动调用 `runtime.create_workers` 创建 Worker 副本
+- **委托**：自动调用 `runtime.create_workers` 创建 Worker 副本（经 `_create_workers_impl`，测试可替换桩）
 
 ---
 
@@ -114,11 +112,32 @@ async def add(request: AddGetRequest) -> AddGetResponse:
 
 **装饰器行为**：
 
-| method | 参数来源          | 请求绑定                 |
-| ------ | ----------------- | ------------------------ |
-| `GET`  | URL query string  | TOML `params` 定义       |
-| `POST` | JSON body         | 自动绑定到 Pydantic 模型 |
-| `MQTT` | MQTT payload JSON | 同 POST                  |
+| method | 参数来源           | 请求绑定                 |
+| ------ | ------------------ | ------------------------ |
+| `GET`  | URL query string   | TOML `params` 定义       |
+| `POST` | JSON body          | 自动绑定到 Pydantic 模型 |
+| `MQTT` | MQTT payload JSON  | 同 POST                  |
+
+### 请求信封协议
+
+Worker 运行时收到的请求负载统一为信封结构（网关 HTTP 路由 / MQTT Bridge / `chongming-request` Client 自动组装）：
+
+```json
+{
+  "meta": { "method": "GET", "user_info": {...}, "timeout": 30, "cacheable": false },
+  "data": { "a": 1, "b": 2 }
+}
+```
+
+- `meta.method` 决定分派到哪个 `@rpc_method`（GET/POST/.../MQTT），缺省 `GET`
+- `meta.user_info` 注入到签名为 `user_info: dict | None = None` 的处理器参数
+- `data` 为业务参数，经请求模型校验后传给处理器
+- 非信封载荷（无 `meta`/`data`）按旧行为兜底：整包视为 `data`、method 取 GET，并输出一次告警
+
+### 注册表冲突检测
+
+`@rpc_method` 注册时以 `subject#METHOD` 为唯一键；同一键重复注册且函数不同时直接抛
+`ValueError`（含双方函数位置），不再静默覆盖——静默覆盖会悄悄改变运行时分派行为。
 
 ### `auto_bind_models(worker_type)`
 
@@ -162,10 +181,11 @@ cfg = load_worker_config("example")
 
 ## 插件集成模式
 
-> 推荐使用上文的 **Plugin 基类**；以下为不依赖基类的传统写法（仍受支持）。
+> 推荐使用上文的 **Plugin 基类**（`src/plugins/` 下所有插件均已迁移到该风格）；
+> 以下为不依赖基类的传统写法，仅框架层面保留兼容，新插件请勿采用。
 
 ```python
-# src/plugins/my_plugin/__init__.py
+# src/plugins/my_plugin/__init__.py（旧式写法，已不推荐）
 from chongming_worker import auto_bind_models
 from chongming_worker.runtime import create_workers as _create_workers
 from .router import *  # 触发 @rpc_method 注册
@@ -188,7 +208,7 @@ async def create_workers(session, config, count, worker_manager):
     _initialized = True
     return _create_workers(session, config, count, worker_manager)
 
-async def cleanup(worker_manager):
+async def cleanup(worker_item: str):
     from .global_var import db
     await db.dispose()
 ```