diff --git a/README.md b/README.md
index 7f509d7..4bc77e3 100644
--- a/README.md
+++ b/README.md
@@ -2,22 +2,175 @@
 
 本目录存放应用所有 TOML 配置文件。
 
-## 主要文件
+---
 
-- `config.toml`：应用主配置（环境、服务器、日志、安全、缓存等）
-- `zenoh_config.json5`：Zenoh 会话配置（JSON5 格式）
-- `workers/config.toml`：Worker 插件加载列表（指定模块、工厂函数、副本数）
-- `workers/<worker_type>/*.toml`：每个 Worker 的路由定义（如 `add.toml`, `divide.toml`）
+## 文件总览
 
-## Worker 路由配置格式
-
-每个接口文件（如 `add.toml`）包含 HTTP 方法节（`[GET]`, `[POST]` 等）：
-
-```toml
-[GET]
-summary = "Add two numbers"
-params = ["a: float", "b: float"]
-response_model = { result = { type = "float", required = true }, operation = { type = "str", default = "add" } }
+```
+config/
+├── config.toml                         # 应用主配置
+├── zenoh_config.json5                  # Zenoh 会话配置（JSON5 格式）
+└── workers/
+    ├── config.toml                     # Worker 插件加载列表
+    ├── auth/                           # 鉴权插件路由定义
+    │   ├── config.toml                 # 分组配置（路由前缀、默认值）
+    │   ├── register.toml               # 用户注册
+    │   ├── login.toml                  # 登录
+    │   ├── me.toml                     # 获取用户信息
+    │   ├── change_password.toml        # 修改密码
+    │   └── update_profile.toml         # 更新资料
+    ├── doubao/                         # 豆包视觉理解路由定义
+    │   ├── config.toml
+    │   └── analyze.toml
+    └── example/                        # 示例路由定义
+        ├── config.toml
+        ├── add.toml
+        ├── subtract.toml
+        ├── multiply.toml
+        ├── divide.toml
+        └── count.toml
 ```
 
-执行 `uv run gen_models config/workers/example src/plugins/example` 可自动生成对应的 Pydantic 模型。
+---
+
+## 1. 应用主配置 (`config.toml`)
+
+定义应用全局设置：环境、服务器、日志、安全、缓存、对象存储等。
+
+### 主要节
+
+| 节              | 说明                                                   |
+| --------------- | ------------------------------------------------------ |
+| `[default]`     | 应用元信息：`app.name`, `app.version`, `env`, `prefix` |
+| `[nanio]`       | S3 兼容存储配置：endpoint、access key、bucket          |
+| `[zenoh]`       | Zenoh 配置：`json5_path` 指向 Zenoh 会话配置文件       |
+| `[scheduler]`   | 任务调度器：`job_store_path`                           |
+| `[cache]`       | 缓存：`cache_store_path`                               |
+| `[security]`    | JWT 安全：`secret_key`, `algorithm`                    |
+| `[development]` | 开发环境配置（server、logging、cors）                  |
+| `[production]`  | 生产环境配置                                           |
+
+---
+
+## 2. Worker 加载配置 (`workers/config.toml`)
+
+定义哪些插件被加载，以及每个插件的运行时参数。
+
+```toml
+[[workers]]
+type = "auth"                        # 插件类型名
+module = "plugins.auth"              # Python 模块路径
+factory = "create_workers"           # 工厂函数名
+cleanup = "cleanup"                  # 清理函数名
+count = 3                            # Worker 副本数
+
+[workers.config]
+type = "auth"
+data_dir = "./data"                  # 插件自定义配置
+```
+
+### 字段说明
+
+| 字段               | 必填 | 说明                                                 |
+| ------------------ | ---- | ---------------------------------------------------- |
+| `type`             | ✅   | 插件类型名，需与 `config/workers/<type>/` 目录名一致 |
+| `module`           | ✅   | Python 模块导入路径                                  |
+| `factory`          | ✅   | 工厂函数名，用于创建 Worker 实例                     |
+| `cleanup`          | ❌   | 清理函数名，插件卸载时调用                           |
+| `count`            | ✅   | Worker 副本数（并行处理请求数）                      |
+| `[workers.config]` | ❌   | 传递给插件的自定义配置字典                           |
+
+---
+
+## 3. 分组配置 (`workers/<type>/config.toml`)
+
+每个插件目录下的 `config.toml` 定义该插件所有路由的公共设置。
+
+```toml
+[worker]
+name = "example"
+version = "0.1.0"
+description = "示例插件"
+defaults = { timeout = 3.0, auth_required = false, cacheable = true, internal = false }
+
+[worker.registration]
+router_prefix = "/calc"     # 所有路由的统一前缀
+tags = ["example"]          # OpenAPI 分组标签
+```
+
+### 字段说明
+
+| 字段                     | 说明                                        |
+| ------------------------ | ------------------------------------------- |
+| `defaults.timeout`       | 默认超时时间（秒）                          |
+| `defaults.cacheable`     | 端点结果是否默认缓存                        |
+| `defaults.auth_required` | 端点是否默认需要 JWT 鉴权                   |
+| `defaults.internal`      | 端点是否默认仅内部调用（不注册 HTTP 路由）  |
+| `router_prefix`          | 路由前缀，如 `/calc` → 完整路径 `/calc/add` |
+
+---
+
+## 4. 端点配置 (`workers/<type>/<operation>.toml`)
+
+每个操作一个 TOML 文件，支持多个 HTTP 方法节。
+
+```toml
+# add.toml — 每个方法节独立定义
+
+[GET]
+summary = "Add two numbers"
+docstring = "通过 URL 参数执行加法运算"
+params = ["a: float", "b: float"]
+cacheable = true
+auth_required = false
+timeout = 5.0
+internal = false
+
+[GET.response_model]
+result = { type = "float", required = true }
+operation = { type = "str", default = "add" }
+timestamp = { type = "float", required = false, default = 0.0 }
+
+[POST]
+summary = "Add two numbers (POST)"
+params = ["a: float", "b: float"]
+auth_required = true
+
+[POST.response_model]
+result = { type = "float", required = true }
+operation = { type = "str", default = "add" }
+```
+
+### 端点字段
+
+| 字段            | 类型        | 默认值                   | 说明                                                           |
+| --------------- | ----------- | ------------------------ | -------------------------------------------------------------- |
+| `summary`       | `str`       | —                        | 端点描述，显示在 OpenAPI 文档                                  |
+| `docstring`     | `str`       | —                        | 详细说明（可选）                                               |
+| `params`        | `list[str]` | `[]`                     | GET 参数列表，格式 `"name: type"`，POST 也需定义以生成请求模型 |
+| `cacheable`     | `bool`      | `defaults.cacheable`     | 结果是否可缓存                                                 |
+| `auth_required` | `bool`      | `defaults.auth_required` | 是否需要 JWT 鉴权                                              |
+| `timeout`       | `float`     | `defaults.timeout`       | RPC 超时（秒）                                                 |
+| `internal`      | `bool`      | `false`                  | 设为 `true` 则只允许内部 Zenoh RPC 调用，不注册 HTTP 路由      |
+
+### 响应模型字段
+
+```toml
+[GET.response_model]
+field_name = { type = "str", required = true }            # 必填字段
+optional_field = { type = "int", required = false, default = 0 }  # 可选字段
+```
+
+支持的 `type` 值：`str`/`string`、`int`/`integer`、`float`/`number`、`bool`/`boolean`、`dict`、`list[type]`、`Optional[type]`。
+
+---
+
+## 修改配置后的操作
+
+修改任何 TOML 配置后，**必须重新生成 Pydantic 模型**：
+
+```bash
+uv run python -m chongming.scripts.gen_models
+```
+
+该命令会扫描所有 `config/workers/*/` 下的 `.toml` 文件，自动更新 `src/plugins/*/models/pydantic.py`。
diff --git a/workers/example/config.toml b/workers/example/config.toml
index 0dd934d..d8e49a7 100644
--- a/workers/example/config.toml
+++ b/workers/example/config.toml
@@ -3,7 +3,7 @@ name = "example"
 version = "0.1.0"
 description = "chongming worker example — demonstrates new config features"
 config_version = "1.0"
-defaults = { method = "GET", ttl = 30, timeout = 2.0, auth_required = true, cacheable = false }
+defaults = { method = "GET", ttl = 30, timeout = 2.0, auth_required = true, cacheable = false, internal = false }
 
 [worker.registration]
 router_prefix = "/calc"