modify: aibox_sophon_adapter plugins

example/README.md

@@ -1,22 +1,71 @@
 # Example Worker 插件
 
-演示 `@rpc_method` 与显式模型绑定的用法。
+演示 `@rpc_method` 装饰器与显式模型绑定的完整用法，是学习开发新插件的**入门参考**。
+
+---
 
 ## 实现的功能
 
-- 加、减、乘、除四则运算（GET / POST）
-- 基于 `modelvault` 的访问计数器
+### 四则运算（GET / POST）
 
-## 如何工作
+| 端点 | 方法       | 路径             | 说明                     |
+| ---- | ---------- | ---------------- | ------------------------ |
+| 加法 | GET / POST | `/calc/add`      | `a + b`                  |
+| 减法 | GET        | `/calc/subtract` | `a - b`                  |
+| 乘法 | GET        | `/calc/multiply` | `a * b`                  |
+| 除法 | GET        | `/calc/divide`   | `a / b`（除数为 0 报错） |
 
-1. 配置位于 `config/workers/example/*.toml`
-2. 模型由 `gen_models` 生成，位于 `models/pydantic.py`
-3. 路由实现在 `router/` 下，使用 `@rpc_method` 装饰
-4. 工厂函数 `create_workers` 初始化数据库并启动 Worker
+### 访问计数器
+
+| 端点 | 方法 | 路径          | 说明              |
+| ---- | ---- | ------------- | ----------------- |
+| 计数 | GET  | `/calc/count` | 每次调用计数器 +1 |
+
+基于内存缓存实现，用于演示 GET 端点的无参数调用模式。
+
+---
 
 ## 调用示例
 
 ```bash
+# GET 加法
 curl "http://localhost:8000/api/v1/calc/add?a=3&b=4"
-# {"result":7,"operation":"add","timestamp":...}
+# {"result":7.0,"operation":"add","timestamp":1720000000.123}
+
+# POST 加法
+curl -X POST "http://localhost:8000/api/v1/calc/add" \
+  -H "Content-Type: application/json" \
+  -d '{"a": 3.5, "b": 2.5}'
+# {"result":6.0,"operation":"add","timestamp":1720000000.456}
+
+# 除法（除数为零）
+curl "http://localhost:8000/api/v1/calc/divide?a=10&b=0"
+# {"result":0.0,"operation":"divide","error":"Division by zero"}
+
+# 计数器
+curl "http://localhost:8000/api/v1/calc/count"
+# {"count":1}
 ```
+
+---
+
+## 如何工作
+
+1. **配置**：`config/workers/example/*.toml` — 定义每个端点的参数和响应结构
+2. **模型**：`models/pydantic.py` — 由 `gen_models` 根据 TOML 自动生成
+3. **路由**：`router/` 下每个文件实现一个 RPC 端点，使用 `@rpc_method` 装饰器
+4. **工厂**：`__init__.py` 中的 `create_workers` 初始化数据库并启动 Worker
+
+---
+
+## 开发参考
+
+此插件展示了以下模式：
+
+- GET 端点的 `params` 定义与 `@rpc_method` 参数绑定
+- POST 端点的 JSON body 自动解析
+- `response_model` 在 TOML 中定义并在装饰器中引用
+- 全局变量 (`global_var.py`) 管理共享资源
+- 错误处理（如除法除零返回错误信息）
+- `auth_required` 控制端点是否需要 JWT 鉴权
+- `cacheable` 控制结果是否缓存

example/models/__init__.py

@@ -5,31 +5,32 @@
 
 from .pydantic import AddGetRequest
 from .pydantic import AddGetResponse
+from .pydantic import AddMqttRequest
 from .pydantic import AddPostRequest
 from .pydantic import AddPostResponse
 from .pydantic import CountGetResponse
 from .pydantic import DivideGetRequest
 from .pydantic import DivideGetResponse
 from .pydantic import ExampleResponse
+from .pydantic import HeartbeatMqttRequest
 from .pydantic import MultiplyGetRequest
 from .pydantic import MultiplyGetResponse
 from .pydantic import SubtractGetRequest
 from .pydantic import SubtractGetResponse
 
-from .counter import Counter
-
 __all__ = [
     "AddGetRequest",
     "AddGetResponse",
+    "AddMqttRequest",
     "AddPostRequest",
     "AddPostResponse",
     "CountGetResponse",
     "DivideGetRequest",
     "DivideGetResponse",
     "ExampleResponse",
+    "HeartbeatMqttRequest",
     "MultiplyGetRequest",
     "MultiplyGetResponse",
     "SubtractGetRequest",
     "SubtractGetResponse",
-    "Counter"
 ]

example/models/pydantic.py

@@ -30,6 +30,11 @@ class AddPostResponse(BaseModel):
     operation: str = Field(default='add')
     timestamp: Optional[float] = Field(default=0.0)
 
+class AddMqttRequest(BaseModel):
+    """Add two numbers via MQTT — 请求体"""
+    a: float = Field(...)
+    b: float = Field(...)
+
 class CountGetResponse(BaseModel):
     """Get visit count and increment — 响应体"""
     name: str = Field(...)
@@ -47,6 +52,10 @@ class DivideGetResponse(BaseModel):
     timestamp: Optional[float] = Field(default=0.0)
     error: Optional[str] = Field(default='')
 
+class HeartbeatMqttRequest(BaseModel):
+    """Heartbeat ping (no response) — 请求体"""
+    worker_id: str = Field(...)
+
 class MultiplyGetRequest(BaseModel):
     """Multiply two numbers — 请求体"""
     a: float = Field(...)
@@ -71,4 +80,4 @@ class SubtractGetResponse(BaseModel):
 
 
 # 所有响应模型的联合类型
-ExampleResponse = SubtractGetResponse | CountGetResponse | MultiplyGetResponse | AddPostResponse | AddGetResponse | DivideGetResponse
+ExampleResponse = AddPostResponse | AddGetResponse | DivideGetResponse | SubtractGetResponse | CountGetResponse | MultiplyGetResponse

example/router/__init__.py

@@ -1,4 +1,6 @@
 from .add import add, add_post
+from .add_mqtt import add_mqtt
+from .heartbeat import heartbeat
 from .subtract import subtract
 from .multiply import multiply
 from .divide import divide
@@ -8,6 +10,8 @@ from .count import count_get
 __all__ = [
     "add", 
     "add_post",
+    "add_mqtt",
+    "heartbeat",
     "subtract",
     "multiply",
     "divide",

example/router/add_mqtt.py

@@ -0,0 +1,24 @@
+"""
+MQTT 端点处理器 — 通过 MQTT 主题 chongming/example/add 调用
+
+与 GET/POST 的 add 共用同一个 subject (example.add)，
+通过 _method="MQTT" 区分。
+"""
+import time
+
+from chongming_worker import rpc_method
+from ..models.pydantic import AddMqttRequest
+
+
+@rpc_method(
+    subject="example.add",
+    method="MQTT",
+    summary="Add two numbers via MQTT",
+)
+async def add_mqtt(request: AddMqttRequest) -> dict:
+    """MQTT 加法 — 通过 MQTT 主题 chongming/example/add 调用，返回 dict"""
+    return {
+        "result": request.a + request.b,
+        "operation": "add_mqtt",
+        "timestamp": time.time(),
+    }

example/router/heartbeat.py

@@ -0,0 +1,20 @@
+"""
+心跳 MQTT 端点 — 仅上报，无需响应
+
+通过 MQTT 主题 chongming/example/heartbeat 发送心跳，
+Worker 返回 None，MQTT Bridge 不发布响应。
+"""
+import time
+
+from chongming_worker import rpc_method
+
+
+@rpc_method(
+    subject="example.heartbeat",
+    method="MQTT",
+    summary="Heartbeat ping via MQTT (no response)",
+)
+async def heartbeat(worker_id: str = "") -> None:
+    """心跳上报 — 无返回值，MQTT Bridge 跳过响应发布"""
+    print(f"[Heartbeat] worker={worker_id} time={time.time()}")
+    return None  # 显式返回 None，MQTT Bridge 不发布响应