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` 控制结果是否缓存