modify: 统一插件风格

README.md

@@ -30,7 +30,7 @@
 | **example**              | 最简示例，Plugin 基类 + Database + 生命周期  | 入门学习   |
 | **auth**                 | SQLModel ORM + 管理员初始化 + 多进程幂等     | 数据库操作 |
 | **doubao**               | 外部 API 客户端（Ark/OpenAI）+ AICC 安全通道 | 外部集成   |
-| **aibox_sophon_adapter** | 自定义 `APIRouter` + MQTT 转发 + 后台任务    | 高级模式   |
+| **aibox_sophon_adapter** | 自定义 `APIRouter` + MQTT 客户端组件（`mqtt_clients.py`）+ 后台任务 | 高级模式   |
 
 ---
 
@@ -56,21 +56,24 @@ touch src/plugins/<name>/router/__init__.py
 
 ### 第二步：注册插件
 
-在 `config/workers/config.toml` 中添加：
+在 `config/workers/<name>/config.toml` 中通过 `[workers]` 节注册（网关启动时自动扫描发现）：
 
 ```toml
-[[workers]]
-type = "<name>"
-module = "plugins.<name>"
-factory = "create_workers"
-cleanup = "cleanup"
-count = 3
+# config/workers/<name>/config.toml
+[workers]
+type = "<name>"              # 插件类型（worker type）
+module = "plugins.<name>"    # Python 模块路径
+factory = "create_workers"   # 工厂函数名（Plugin 基类绑定的方法）
+cleanup = "cleanup"          # 清理函数名
+count = 3                    # Worker 副本数
 
+# 运行时配置（展平后传给 create_workers 的 config 参数）
 [workers.config]
-type = "<name>"
 data_dir = "./data"
 ```
 
+> 旧式全局注册文件 `config/workers/config.toml`（`[[workers]]` 数组）仅作兜底兼容，新插件请使用各插件自己的 `config.toml`。
+
 ### 第三步：编写端点 TOML 配置
 
 创建 `config/workers/<name>/config.toml`（分组配置）：
@@ -167,9 +170,9 @@ create_workers = _plugin.create_workers
 cleanup = _plugin.cleanup
 ```
 
-基类自动处理：幂等、统一日志、数据库建库/释放、后台任务取消、清理钩子、模型自动绑定。详见 `utils/worker/README.md` 的「Plugin 基类」章节。
+基类自动处理：幂等（初始化锁）、统一日志、数据库建库/释放、后台任务取消、清理钩子、模型自动绑定、cleanup 时重置已发布的 global_var。详见 `utils/worker/README.md` 的「Plugin 基类」章节。
 
-> **兼容旧写法**：不依赖基类的传统 `create_workers` / `cleanup` 模块级函数写法仍受支持（见 `utils/worker/README.md`）。
+> **旧写法已废弃**：不依赖基类的传统 `create_workers` / `cleanup` 模块级函数写法仅框架层面保留兼容，现有插件（auth / doubao / aibox_sophon_adapter / example）均已迁移到 Plugin 基类，新插件请勿采用旧写法。
 
 ---
 
@@ -310,17 +313,39 @@ async def handler(request: RequestCls) -> ResponseCls:
     ...
 ```
 
-| 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                      |
+
+**请求信封协议**：网关统一把请求组装为 `{"meta": {"method", "user_info"}, "data": {...}}`
+发给 Worker；运行时按 `meta.method` 分派到对应 `@rpc_method`，`data` 经请求模型校验后
+传给处理器。MQTT 客户端发布消息时需按信封格式（见主 README「请求负载格式」），
+MQTT 专用端点要显式 `"meta": {"method": "MQTT"}`。
 
 - 设置 `internal = true` 后，端点不注册 HTTP 路由，仅可通过 Zenoh RPC 或 MQTT 内部调用
 - MQTT 方法返回 `None` 时，Bridge 自动跳过响应发布
 
 ---
 
+## 启动契约校验
+
+服务启动时（`load_workers` 之后、注册路由之前），网关自动核对三方一致性：
+
+| 检查项                       | 策略                        |
+| ---------------------------- | --------------------------- |
+| TOML HTTP 路由缺 `@rpc_method` | **硬失败**，启动直接终止    |
+| `[MQTT]` / `internal` 路由缺注册 | 警告日志                    |
+| 已注册方法无 TOML 路由       | 警告日志（反向漂移检测）    |
+| params/response_model 缺生成模型 | 警告日志（gen_models 过期） |
+| 生成模型未被任何路由引用     | 警告日志（孤儿模型）        |
+
+新增端点后如果启动报错「缺少对应的 @rpc_method 注册」，检查 TOML 的 `subject`/方法节
+与 `router/<op>.py` 中的 `@rpc_method(subject=..., method=...)` 是否一致。
+
+---
+
 ## 命名约定
 
 | 概念          | 约定                           | 示例                         |