docs: 插件开发指南精简（路由选择合并为一句）并更新依赖声明分工说明

README.md

@@ -282,16 +282,8 @@ async def upload(file: UploadFile = File(...)):
 
 在 `__init__.py` 顶部暴露给网关：`from .routes import router`（网关通过 `getattr(module, "router")` 自动发现）。
 
-### 两种路由对比
-
-|            | 路由一 `@rpc_method`                      | 路由二 `APIRouter`                            |
-| ---------- | ----------------------------------------- | --------------------------------------------- |
-| 文件位置   | `router/<op>.py`                          | `routes.py`                                   |
-| 入口发现   | 装饰器注册 → Worker Queryable             | `__init__.py` 暴露 `router` 属性              |
-| 函数签名   | `(request: Pydantic模型) -> Pydantic模型` | FastAPI 风格（`Request`/`UploadFile`/`Form`） |
-| 适用场景   | 标准 JSON / query 端点                    | multipart 上传、手动解析报文                  |
-| 读共享对象 | `from ..global_var import require`        | `from .global_var import db`                  |
-| 请求路径   | HTTP → Zenoh → Worker 回调                | FastAPI 直接调用                              |
+**怎么选**：标准 JSON / query 端点（参数与响应可被 Pydantic 模型描述）用路由一
+`@rpc_method`；multipart 上传、需手动解析报文等无法用 TOML 描述的端点用路由二 `APIRouter`。
 
 ### 经验
 
@@ -329,6 +321,31 @@ MQTT 专用端点要显式 `"meta": {"method": "MQTT"}`。
 
 ---
 
+## 插件专属依赖（第三方包）
+
+插件用了网关本体不 import 的第三方包（如 doubao 的 `openai` / `volcenginesdkarkruntime`），
+除在根 `pyproject.toml` 的 dependencies 里安装外，还要在**根目录 `plugins_deps.toml`** 里
+按插件分节声明，打包收集清单（`--hidden-import` / `--include-module`）才会带上它：
+
+```toml
+# 多个插件共用（顶层 imports）
+imports = ["httpx"]
+
+[<插件名>]
+imports = ["openai", "volcenginesdkarkruntime"]
+```
+
+- **声明位置**：inline 插件在 `.mbank` 内 import，打包静态分析看不到，因此除根
+  `pyproject.toml`（venv 安装）外，插件专属依赖还必须写进根目录 `plugins_deps.toml`，
+  打包收集清单（`--hidden-import` / `--include-module`）才会带上它
+- 改为 external 进程插件后不需要本文件：依赖随插件项目 `workers/<name>/pyproject.toml` 自包含
+- **一键迁移**：`uv run migrate_plugin <name>` 把 `src/plugins/<name>/` 迁移为
+  `workers/<name>/` 进程插件项目（代码/配置/依赖一并迁移，`plugins_deps.toml`
+  对应节自动注释）。注意：挂载了自定义 FastAPI 路由（`APIRouter`）或导入了网关包的
+  插件会被拦截拒绝迁移（`--force` 可跳过），前者需先改成 TOML `@rpc_method` 端点
+
+---
+
 ## 启动契约校验
 
 服务启动时（`load_workers` 之后、注册路由之前），网关自动核对三方一致性：
@@ -357,14 +374,6 @@ MQTT 专用端点要显式 `"meta": {"method": "MQTT"}`。
 | Python 文件名 | 与操作名一致                   | `add.py`                     |
 | 模型类名      | `<操作><方法>Request/Response` | `AddGetRequest`              |
 
-| 概念              | 约定            | 示例                                |
-| ----------------- | --------------- | ----------------------------------- |
-| 插件名            | 小写下划线      | `doubao`, `auth`, `example`         |
-| 操作名            | 小写下划线      | `analyze`, `add`, `change_password` |
-| Zenoh subject     | `<插件>.<操作>` | `example.add`, `doubao.analyze`     |
-| TOML 文件名       | 与操作名一致    | `analyze.toml`, `add.toml`          |
-| Python 路由文件名 | 与操作名一致    | `analyze.py`, `add.py`              |
-
 ---
 
 ## 现有插件