modify: rust插件

docs/multi-language-plugin-plan.md

@@ -52,18 +52,29 @@
 ```
 chongming-worker-rs/            # 独立仓库（或 utils/worker-rs/，与 Python SDK 并列）
 ├── Cargo.toml                  # 依赖: zenoh / tokio / serde+serde_json / toml /
-│                               #        serde_json5 / tracing / clap
+│                               #        serde_json5 / tracing / clap / redis(optional)
+│                               #   features: redis-cache（共享缓存后端，多实例用）
 └── src/
     ├── lib.rs
-    ├── config.rs               # 读取 config.toml [zenoh].json5_path + JSON5 会话配置
+    ├── config.rs               # 读取 config.toml [zenoh].json5_path + JSON5 会话配置；
+    │                           #   另有 [workers.config] 运行时读写（保留键校验 + 原子落盘）
     ├── descriptor.rs           # 描述符结构体（规范 §2.2 字段表）+ 端点 TOML 解析
     ├── publisher.rs            # RoutePublisher 等价：PUT / DELETE / 10s 重发布
     ├── serve.rs                # worker_serve 等价：liveliness token + Queryable + 生命周期
+    ├── runtime.rs              # 托管副本模型：ReplicaController（index/epoch/restart/stop/drain）
+    │                           #   + WorkerPool（按 target 动态扩缩，优雅排空）
+    ├── admin.rs                # __admin__ Queryable：status/restart/stop/drain/get_config/
+    │                           #   config_set/rescale（对齐 Python runtime._handle_admin_command）
+    ├── cache.rs                # 配置缓存抽象：Redis 共享缓存（feature redis-cache）+ 无缓存回退；
+    │                           #   实例登记/心跳/租约、quota 全局分摊、resolve_worker_count
     ├── envelope.rs             # 请求信封解析（meta.method / user_info / data）
     │                           #   与三种响应形态序列化（普通 / 流式 / 错误）
     ├── gen.rs                  # 模型生成：端点 TOML → Rust 结构体 + FINGERPRINT 指纹
     │                           #   （bin: gen_models，对齐 Python gen_models）
-    └── error.rs                # 非流式错误格式、流式 {"error":...} 收尾块
+    ├── error.rs                # 非流式错误格式、流式 {"error":...} 收尾块
+    ├── database.rs             # 数据库封装：SQLite/PostgreSQL 异步连接池（sqlx，feature `database`）
+    │                           #   from_config/sqlite/from_url + initialize/pool/raw_execute/dispose
+    │                           #   + database_for/init_database（对齐 Python chongming_database）
 └── examples/
     └── demo.rs                 # demo 参考插件（对位 workers/demo 的 hello / storage 端点）
 ```
@@ -105,6 +116,48 @@ chongming-worker-rs/            # 独立仓库（或 utils/worker-rs/，与 Pyth
 | 模型生成 | Rust 有 gen_models 等价物（`--bin gen_models`，命名/类型映射对齐 Python）：从端点 TOML 生成强类型结构体，并做**启动时指纹校验**（TOML 变更未重生成即告警，比 Python 只查模型存在性更强） |
 | handler 注入 | worker_id / user_info 经 `Request` 结构注入（Python 为函数参数注入） |
 
+### 3.6 生命周期管理与多实例协同（已对齐 Python runtime.py）
+
+阶段 1 之后补强的两块能力，使 Rust 进程插件在**管理指令、配置热更、多实例 quota 分摊**上与 Python SDK 平齐：
+
+| 能力 | Python（`utils/worker/`） | Rust（`utils/worker-rs/`） | 对齐结论 |
+| ---- | ---- | ---- | ---- |
+| 托管副本 | `WorkerController`（index/epoch/exit_event/reload_cb）+ `WorkerPool.set_target` | `ReplicaController`（index/epoch/request_restart/stop/drain）+ `WorkerPool.set_target`（`runtime.rs`） | ✅ 机制等价 |
+| admin Queryable | `worker/<type>/<id>/__admin__`，指令 status/restart/stop/drain/get_config/config_set/rescale | 同一 keyexpr，`admin.rs::handle_admin` 全量分派 | ✅ keyexpr 与指令一致 |
+| 优雅排空 | drain：隔离新请求 → 等在途归零（30s 超时强制关闭） | `draining` 标记 + `wait_inflight_zero`（同 30s）；先摘 liveliness/业务/admin 再等在途 | ✅ 行为一致 |
+| 配置热更 | config_set：仅 index0 落盘（原子写）+ 触发重启，`[workers.config]` 保留键校验 | `persist_worker_config_section`（tmp+rename 原子写）+ `merge_confirmed`/`count_allowed` 保留键校验 | ✅ 语义一致 |
+| 配置缓存 | chongming-cache（redis / diskcache）作为 counts/configs 单一事实来源 | `Cache` 抽象：Redis（feature `redis-cache`）+ 无缓存回退 | ✅ Redis 路径一致；本地 diskcache 因格式特性不可复用（多实例走 Redis） |
+| quota 分摊 | 按在线网关/存活实例均分全局 count（余数给序较早方） | `distribute_quota` / `resolve_worker_count` 同算法 | ✅ 同协议键 `worker:cm:*` |
+| CLI | `--config` / `--instance` / `--count` | `examples/demo.rs`：`--config` / `--instance` / `--count` | ✅ 对齐 |
+
+> 注：Python 默认的本地 `diskcache` 后端为 Python 库，Rust 无法读其存储文件格式；故 Rust 侧多实例协同统一走 Redis（`redis-cache` feature），单实例走 `Cache::None`，与 Python「多实例必须 redis/共享卷」约束一致。
+
+### 3.7 数据库对齐（`chongming_database` ↔ Rust `database.rs`）
+
+Python 插件通过 `chongming_database`（aiosqlite/asyncpg + SQLAlchemy 引擎）落库；
+Rust 侧用 sqlx 在 `utils/worker-rs` 内提供等价封装（feature `database`，随插件按需开启），
+使插件能对 SQLite / PostgreSQL 做异步读写。语义逐项对齐：
+
+| 能力 | Python（`chongming_database`） | Rust（`database.rs`，sqlx） | 对齐结论 |
+| ---- | ---- | ---- | ---- |
+| 配置声明 | `[workers.config].database` + `db_name`（SQLite）/ `url`（PostgreSQL） | 同一键 `[workers.config.database]`：`type` / `database_path` / `url` | ✅ 同键 |
+| 构造 | `Database.from_config` / `Database(Path)` / `from_url` | `from_config` / `sqlite(path)` / `from_url(url)` | ✅ 三态等价 |
+| 建池（建引擎） | `initialize()`（幂等） | `initialize(max_connections)`（幂等） | ✅ `connect_with` 建池 |
+| 取会话 | `get_session()` 上下文 | `pool()` 返回 `Pool<Any>`（`Arc`，可 Clone） | ✅ 共享引用等价 |
+| 建表 | 基类 `_bootstrap` + SQLModel `create_all` | `raw_execute("CREATE TABLE IF NOT EXISTS ...")` | ✅ 启动时 `init_database` |
+| 关断 | `dispose()` | `dispose()`（幂等） | ✅ 对齐 |
+| 降级 | 未配置时不建库（`db_name = None`） | `database_for`/`init_database` 返回 `None` | ✅ 语义一致 |
+
+关键点：
+- **开启方式**：SDK/插件 `Cargo.toml` 开启 `database` feature（同时引入 sqlx）；打包 `bash build.sh dist "database"`。
+- **handler 共享**：`init_database` 返回 `Option<Arc<Database>>`，`Clone` 后捕获进 handler 闭包，
+  内部用 `db.pool().await` 拿共享连接池做 `sqlx::query` —— 与 Python 用模块级 `db` 访问对位。
+- **后端差异**：SQLite 连接串 `sqlite:<path>?mode=rwc`（`rwc` 自动建库，同 aiosqlite）；PostgreSQL 走 `postgres://...`。
+  SQL 占位符遵循各自方言（SQLite `?`、PostgreSQL `$1`），SDK 不做 SQL 重写。
+- **TLS**：默认不启用 TLS 后端；PostgreSQL 走 SSL 时需追加 `tls-rustls-ring` 等 feature。
+- **参考实现**：`workers/rsdemo` 的 `db_ping` 端点（写 + 读一表做连通性探测）；`gen_plugin --rust` 模板已内置
+  注释版 `[workers.config.database]` 段与 `database` feature（见 [rsdemo README](../../workers/rsdemo/README.md)）。
+
 ---
 
 ## 4. 阶段 2：工具链与治理
@@ -172,4 +225,5 @@ chongming-worker-rs/            # 独立仓库（或 utils/worker-rs/，与 Pyth
 
 - [进程插件线协议规范（语言无关）](./plugin-wire-protocol.md) —— 唯一契约
 - [进程插件开发指南（Python）](./process-plugin.md) —— Python SDK 开发流程
+- [Rust 插件编写说明](./rust-plugin.md) —— Rust SDK 开发流程（脚手架/端点/模型/handler/管理/数据库/打包）
 - [主 README：进程插件与混合部署](../README.md)