modify: 说明文档

README.md

@@ -1,25 +1,144 @@
 # chongming-worker
 
-通用 Worker 框架，提供 Zenoh RPC 端点的装饰器定义、生命周期管理和配置解析。
+通用 Worker 框架核心，提供 Zenoh RPC 端点的装饰器定义、参数解析、生命周期管理和配置加载。
 
-## 功能
+---
 
-- `@rpc_method` 装饰器：将普通函数注册为 Zenoh Queryable 端点
-- 自动参数解析与 Pydantic 模型绑定（支持 `gen_models` 生成的模型）
-- 运行时 `create_worker` / `create_workers` 工厂函数
-- 配置加载：`load_worker_config` 读取 `config/workers/<name>/*.toml`
+## 安装
 
-## 使用示例
-
-```python
-from chongming_worker import rpc_method
-from .models.pydantic import AddGetRequest, AddGetResponse
-
-@rpc_method(subject="example.add", method="GET", response_model=AddGetResponse)
-async def add(req: AddGetRequest) -> AddGetResponse:
-    return AddGetResponse(result=req.a + req.b)
+```bash
+uv pip install -e utils/worker
 ```
 
-## 工厂函数
+---
 
-插件需提供 `create_workers(session, config, count, worker_manager)` 异步函数，返回任务列表。
+## 核心功能
+
+- **`@rpc_method` 装饰器**：将异步函数注册为 Zenoh Queryable 端点
+- **自动参数解析**：根据 HTTP 方法从 query 参数或 JSON body 解析请求
+- **Pydantic 模型绑定**：`auto_bind_models()` 自动绑定生成的模型
+- **Worker 运行时**：`create_worker` / `create_workers` 管理生命周期
+- **配置加载**：`load_worker_config` 读取 TOML 配置
+
+---
+
+## API
+
+### `@rpc_method` 装饰器
+
+```python
+from chongming_worker.decorators import rpc_method
+from ..models.pydantic import AddGetRequest, AddGetResponse
+
+@rpc_method(
+    subject="example.add",
+    method="GET",
+    response_model=AddGetResponse,
+)
+async def add(request: AddGetRequest) -> AddGetResponse:
+    return AddGetResponse(result=request.a + request.b)
+```
+
+| 参数             | 类型              | 说明                                     |
+| ---------------- | ----------------- | ---------------------------------------- |
+| `subject`        | `str`             | Zenoh 主题（必需），如 `"example.add"`   |
+| `method`         | `str`             | HTTP 方法：`"GET"` / `"POST"` / `"MQTT"` |
+| `response_model` | `type[BaseModel]` | Pydantic 响应模型类                      |
+
+**装饰器行为**：
+
+| method | 参数来源          | 请求绑定                 |
+| ------ | ----------------- | ------------------------ |
+| `GET`  | URL query string  | TOML `params` 定义       |
+| `POST` | JSON body         | 自动绑定到 Pydantic 模型 |
+| `MQTT` | MQTT payload JSON | 同 POST                  |
+
+### `auto_bind_models(worker_type)`
+
+自动将 `gen_models` 生成的 Pydantic 模型绑定到对应端点，省去手动导入和绑定。
+
+```python
+from chongming_worker import auto_bind_models
+
+auto_bind_models("example")
+```
+
+### `create_workers`
+
+```python
+from chongming_worker.runtime import create_workers
+
+tasks = create_workers(
+    session=zenoh_session,
+    config=plugin_config,
+    count=3,
+    worker_manager=worker_manager,
+)
+```
+
+| 参数             | 类型            | 说明              |
+| ---------------- | --------------- | ----------------- |
+| `session`        | `zenoh.Session` | Zenoh 会话        |
+| `config`         | `dict`          | 插件配置          |
+| `count`          | `int`           | Worker 副本数     |
+| `worker_manager` | `WorkerManager` | Worker 管理器实例 |
+
+### `load_worker_config`
+
+```python
+from chongming_worker.config import load_worker_config
+
+cfg = load_worker_config("example")
+```
+
+---
+
+## 插件集成模式
+
+```python
+# 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 注册
+
+auto_bind_models("my_plugin")
+
+async def create_workers(session, config, count, worker_manager):
+    """插件入口：初始化资源，启动 Worker"""
+    from chongming_database import Database
+    from .global_var import set_db
+
+    db = Database(...)
+    await db.initialize()
+    set_db(db)
+
+    return _create_workers(session, config, count, worker_manager)
+
+async def cleanup(worker_manager):
+    from .global_var import db
+    await db.dispose()
+```
+
+---
+
+## 导出清单
+
+```python
+from chongming_worker import (
+    RPCMethod, rpc_method,          # 装饰器
+    bind_model, auto_bind_models,   # 模型绑定
+    get_rpc_methods, get_all_rpc_methods, clear_registry,  # 注册表
+    generate_route_configs,         # 路由配置生成
+    load_worker_config,             # TOML 配置加载
+    WorkerConfig, OperationConfig,  # 配置类型
+    create_worker, create_workers,  # 运行时
+)
+```
+
+---
+
+## 依赖
+
+- `zenoh` — Zenoh Python 绑定
+- `pydantic` — 数据验证与序列化
+- `tomli` — TOML 配置解析