modify: rust worker

2026-08-22 03:26:50 +08:00
parent 5ba1a2a8cd
commit 440efa716f
3 changed files with 402 additions and 0 deletions
@@ -0,0 +1,175 @@
+# 多语言插件演进统一规划（Rust 优先）
+
+> 背景：团队技术栈杂糅，Python 在部分计算密集场景性能有限。
+> 目标：在不破坏现有体系的前提下，开放进程插件多语言实现能力，
+> **Rust 优先落地**，为后续其他语言（Go / C++ 等）铺路。
+>
+> 配套文档：[进程插件线协议规范（语言无关）](./plugin-wire-protocol.md)、
+> [进程插件开发指南（Python）](./process-plugin.md)
+
+---
+
+## 1. 总体原则
+
+| # | 原则 | 说明 |
+| - | ---- | ---- |
+| P1 | **规范先行，协议是唯一契约** | 网关与插件之间只认线协议（[plugin-wire-protocol.md](./plugin-wire-protocol.md)）。任何语言实现均以规范为准，不得依赖其他语言 SDK 的内部行为 |
+| P2 | **网关零改动起步** | 阶段 1 的 Rust 插件按协议实现即可对接，网关代码不允许为适配单语言做改动 |
+| P3 | **混合部署兼容** | 同一 `<type>` 下可混布 Python 与 Rust 副本（协议相同、负载均衡透明）；但流式语义、错误格式、超时行为必须与规范完全一致 |
+| P4 | **契约校验不旁路** | Python SDK 的进程内契约校验（TOML ↔ 注册 ↔ 模型）是 Python 特有能力；其他语言实现须提供等价的自检（描述符字段完整性），网关侧强校验在阶段 2 补齐 |
+| P5 | **修改即更新规范** | 任何实现侧改动触及协议语义时，必须同步修订规范（含[附录 A 事实来源索引](./plugin-wire-protocol.md)） |
+| P6 | **性能收益只认实测** | 语言选型以基准测试为准（见 §6），不凭直觉切换 |
+
+---
+
+## 2. 阶段划分总览
+
+| 阶段 | 内容 | 产出 | 状态 |
+| ---- | ---- | ---- | ---- |
+| **0** | 协议规范定稿 | `docs/plugin-wire-protocol.md` | ✅ 已完成 |
+| **1** | Rust 参考实现 | `chongming-worker-rs`（`utils/worker-rs/`）+ demo 参考插件，端到端验证通过 | ✅ 已完成（见 §3.4 验证结果） |
+| **2** | 工具链与治理 | build_plugin 支持非 Python、网关描述符强校验、跨语言互操作测试 | ⏳ 未开始 |
+| **3** | 推广与最佳实践 | 团队规范、性能基准、Go 等其他语言按需跟进 | ⏳ 未开始 |
+
+每阶段有明确的 Done 定义（见 §5），未达验收标准不得进入下一阶段。
+
+---
+
+## 3. 阶段 1：Rust 参考实现（`chongming-worker-rs`）
+
+### 3.1 目标
+
+用 Rust 实现一个**最小但完整**的进程插件 SDK 与参考插件，证明：
+路由注册、RPC、流式、摘除、自愈、混合部署全链路可用，且与 Python SDK 行为等价。
+
+参考实现（两形态，均已完成）：
+- SDK 内示例：`utils/worker-rs/examples/demo.rs`（`--type rsdemo` / `--type demo` 混布对拍）
+- **独立插件形态**：`workers/rsdemo/`（与 Python 示例 `workers/demo/` 对位的完整插件 crate，
+  含生成模型与说明文档，新插件以此为模板）
+
+### 3.2 crate 结构建议
+
+```
+chongming-worker-rs/            # 独立仓库（或 utils/worker-rs/，与 Python SDK 并列）
+├── Cargo.toml                  # 依赖: zenoh / tokio / serde+serde_json / toml /
+│                               #        serde_json5 / tracing / clap
+└── src/
+    ├── lib.rs
+    ├── config.rs               # 读取 config.toml [zenoh].json5_path + JSON5 会话配置
+    ├── descriptor.rs           # 描述符结构体（规范 §2.2 字段表）+ 端点 TOML 解析
+    ├── publisher.rs            # RoutePublisher 等价：PUT / DELETE / 10s 重发布
+    ├── serve.rs                # worker_serve 等价：liveliness token + Queryable + 生命周期
+    ├── envelope.rs             # 请求信封解析（meta.method / user_info / data）
+    │                           #   与三种响应形态序列化（普通 / 流式 / 错误）
+    ├── gen.rs                  # 模型生成：端点 TOML → Rust 结构体 + FINGERPRINT 指纹
+    │                           #   （bin: gen_models，对齐 Python gen_models）
+    └── error.rs                # 非流式错误格式、流式 {"error":...} 收尾块
+└── examples/
+    └── demo.rs                 # demo 参考插件（对位 workers/demo 的 hello / storage 端点）
+```
+
+### 3.3 与协议规范的对应（实现对照）
+
+| 协议项（规范章节） | Rust 实现要点 |
+| ---- | ---- |
+| §2 路由描述符 | `descriptor.rs` 构造 + `publisher.rs` PUT/DELETE；`route_id = subject.replace('.','_') + "__" + METHOD` |
+| §3 服务发现 | `session.liveliness().declare_token("worker/<type>/<id>")`，`--count` 多副本 id 互异 |
+| §4 RPC | `declare_queryable("worker/<type>/<id>/<subject>")` 异步 handler；信封解析 + 分派；流式多次 `query.reply()` |
+| §4.3 异常 | 非流式：`{"result":0.0,"operation":"error","error":...,"worker":...}`；流式：`{"error":...}` 收尾块 |
+| §5 配置 | `config.rs`：TOML + JSON5 双重解析 |
+| 生命周期 | `publisher.rs` 10s tokio interval 重发布；`tokio::signal` 监听 SIGTERM/SIGINT → DELETE 全部 key |
+
+### 3.4 端到端验收场景（已全部通过 ✅）
+
+| # | 场景 | 结果 |
+| - | ---- | ---- |
+| 1 | 路由注册 + HTTP 端点可用 | ✅ 描述符 keyexpr/字段 15 项断言全过；网关动态挂载后 `GET /api/v1/rsdemo/hello` 返回 200 |
+| 2 | GET/POST RPC + user_info 透传 | ✅ 信封分派、worker_id 注入、user_info 经 `meta` 透传（协议层验证）；网关层 echo 端点按配置要求认证头（预期行为） |
+| 3 | 流式 SSE 逐块 + 流中异常收尾 | ✅ `tokens=5` 逐块 5 块；`tokens=60` 第 26 块后 SSE 收到 `{"error":...}` 收尾块并终止 |
+| 4 | SIGTERM 摘除 + 重启自愈 | ✅ 退出码 0、DELETE 全部描述符；重启后 ≤10s 重发布恢复 |
+| 5 | 混布（Python + Rust 同 type） | ✅ 描述符内容 hash 完全一致（网关幂等去重零告警）；双副本统一 liveliness 发现；网关 HTTP 10 次调用 6:4 随机打到两实现（`worker-0-54257`=Rust / `worker-0-54258`=Python）；互不干扰 |
+| 6 | 错误描述符健壮性 | ✅ Rust SDK 发布前自检跳过无 subject 描述符（不发布残缺路由）；网关侧非法 JSON 丢弃为既有行为 |
+
+验证命令（见 `utils/worker-rs/README.md`）：
+
+```bash
+.venv/bin/python utils/worker-rs/scripts/verify_e2e.py --type rsdemo   # 协议级 15/15
+.venv/bin/python utils/worker-rs/scripts/verify_mixed.py               # 混布对拍 6/6
+```
+
+### 3.5 与 Python SDK 的差异（有意为之）
+
+| 差异 | 说明 |
+| ---- | ---- |
+| 契约校验 | Python 进程内三方校验（硬失败退出）；Rust 降级为发布前自检：无 handler 端点告警跳过，不发布残缺路由 |
+| 模型生成 | Rust 有 gen_models 等价物（`--bin gen_models`，命名/类型映射对齐 Python）：从端点 TOML 生成强类型结构体，并做**启动时指纹校验**（TOML 变更未重生成即告警，比 Python 只查模型存在性更强） |
+| handler 注入 | worker_id / user_info 经 `Request` 结构注入（Python 为函数参数注入） |
+
+---
+
+## 4. 阶段 2：工具链与治理
+
+### 4.1 build_plugin 支持非 Python 插件
+
+- 现状：`build_plugin` 产物为 pyproject.toml + start.sh（`uv run worker_serve --type <name>`），纯 Python 链路
+- 目标：支持声明插件语言/入口，允许打包任意可执行产物 + 自定义 start.sh
+  （Rust 插件 = 编译产物 + `--type` 参数约定），`--type` 语义跨语言保持一致
+- 约束：打包结构（zip 根 = 容器工作目录）不变
+
+### 4.2 网关侧描述符强校验（补齐契约旁路）
+
+- 现状：描述符健壮性只有"非法 JSON 丢弃 / 缺字段取默认"，字段语义错误会挂载错误路由
+- 目标：`route_registry` 对必填字段（`subject` / `method` / `path`）做校验，缺必填字段的
+  描述符丢弃并告警；为 `schema_version` 未知版本预留拒绝策略
+- 收益：非 Python 插件（无契约校验）的错误在网关侧被兜底，两端受益
+
+### 4.3 跨语言互操作测试
+
+- 复用 `test_process_mode_e2e.py` 模式，新增协议一致性测试矩阵：
+  Python SDK ↔ Rust SDK 对同一描述符/信封的序列化结果一致性（黄金样本对比）
+- 纳入 CI：任何实现侧协议改动，先跑互操作测试再合入（配合原则 P5）
+
+---
+
+## 5. 验收标准（Done 定义）
+
+| 阶段 | Done 定义 |
+| ---- | ---- |
+| 0 | 规范文档覆盖：描述符字段、信封、三种响应形态、生命周期、演进规则；任一语言实现者可仅凭规范写出插件 |
+| 1 | §3.4 六个场景全部通过；Rust 插件与 Python 插件行为对拍一致（普通/流式/错误/超时） |
+| 2 | `build_plugin` 可打包 Rust 插件并部署运行；网关描述符强校验生效；互操作测试入 CI |
+| 3 | 性能基准文档发布；团队多语言插件开发规范定稿 |
+
+---
+
+## 6. 选型指引（何时用 Rust）
+
+| 场景 | 建议 | 依据 |
+| ---- | ---- | ---- |
+| 个别计算热点慢（加解密/编解码/大体积处理） | **Python + PyO3 扩展**（网关 jwt/password 已有先例） | 保留 Python 全部工具链，改动最小 |
+| 整个插件即高性能计算服务 / 高吞吐短请求 | **Rust 进程插件**（本规划主线） | 消除 GIL 与解释器开销，收益在 handler 侧 |
+| 纯 I/O 编排（HTTP/DB/存储调用） | 维持 Python | 瓶颈在外部服务，换语言边际收益小 |
+| 团队语言偏好 / 组件复用（已有 Rust 库） | Rust 进程插件 | 混合部署兼容，可渐进替换 |
+
+> 性能收益只发生在 handler 执行侧；Zenoh 传输与 JSON 序列化开销各语言相同。
+> 落地前先做基准：同端点 Python vs Rust 的 p99 / 吞吐对比，以数据决策。
+
+---
+
+## 7. 风险与缓解
+
+| 风险 | 等级 | 缓解 |
+| ---- | ---- | ---- |
+| 协议漂移（双实现维护） | 高 | 规范为唯一契约 + 附录 A 事实索引 + P5 强制更新 + 阶段 2 互操作测试入 CI |
+| 行为差异导致混布异常（流式/错误/超时） | 中 | §3.4 场景 5/6 混布对拍；各实现须通过同一互操作测试矩阵 |
+| 契约校验旁路 | 中 | 阶段 2 网关强校验兜底；Rust SDK 提供描述符自检（等价 contracts.py 的必填校验） |
+| 网关被不规范描述符影响 | 低 | 现有健壮性处理已覆盖（非法 JSON 丢弃、冲突保留先到者、防抖） |
+| 多语言 SDK 维护成本 | 中 | 阶段 1 只做最小 SDK（协议层），业务框架（路由/模型/契约）不复制，避免重复投入 |
+
+---
+
+## 8. 相关文档
+
+- [进程插件线协议规范（语言无关）](./plugin-wire-protocol.md) —— 唯一契约
+- [进程插件开发指南（Python）](./process-plugin.md) —— Python SDK 开发流程
+- [主 README：进程插件与混合部署](../README.md)
@@ -0,0 +1,224 @@
+# 进程插件线协议规范（语言无关）
+
+> 本规范定义网关与进程插件（`load_mode = "external"`）之间的**唯一契约**：
+> Zenoh keyexpr + JSON 载荷。任何拥有 Zenoh 绑定的语言（Rust / Go / C / C++ / Java 等）
+> 只要按本规范实现，即可与网关零改动对接，与 Python 插件共存于同一类型、参与同一套负载均衡。
+>
+> **事实来源**：本规范以 `chongming_worker` SDK 与网关代码为唯一事实来源
+> （见文末[附录 A](#附录-a-事实来源索引)）。修改任何一侧实现必须同步更新本规范。
+
+---
+
+## 1. 总览
+
+进程插件是一个**独立进程**，生命周期由 Docker/K8s 编排拉起（网关不负责 spawn）。
+插件进程启动后：
+
+1. 打开 Zenoh 会话（配置见 §5）
+2. 发布路由描述符 → 网关 RouteRegistry 订阅后动态挂载 HTTP 端点
+3. 声明 liveliness token 与 Queryable → 网关 WorkerManager 发现并按负载均衡转发 HTTP 请求
+4. 退出时摘除路由描述符（DELETE），网关 2s 防抖后移除 HTTP 端点
+
+```
+HTTP 客户端 ──> 网关 FastAPI 动态路由
+                  │  WorkerManager（15s liveliness 发现 + 随机负载均衡 + 超时重试）
+                  ▼
+        Zenoh Query: worker/<type>/<id>/<subject>
+                  ▲        │
+                  │        ▼
+        插件进程 Queryable（解析信封 → 业务处理 → JSON 回复）
+
+插件进程 ──PUT/DELETE──> chongming/routes/<type>/<route_id>   （路由描述符）
+插件进程 ──liveliness──> worker/<type>/<id>                    （服务发现）
+```
+
+### 关键时间参数
+
+| 参数 | 值 | 语义 |
+| ---- | -- | ---- |
+| 描述符重发布周期 | 10s | 插件侧周期性重发布全部描述符（自愈：网关后启动 / 样本丢失） |
+| 网关路由防抖 | 2s | 网关收到描述符变更后防抖重建路由（合并重启风暴） |
+| liveliness 刷新 | 15s | 网关 WorkerManager 轮询 `worker/*/*` |
+| 优雅退出摘除 | 即时 | 插件收到 SIGTERM/SIGINT 后 DELETE 全部已发布 key |
+
+---
+
+## 2. 路由描述符协议（`chongming/routes/**`）
+
+### 2.1 keyexpr 结构
+
+```
+chongming/routes/<type>/<route_id>    # 端点描述符（PUT 发布 / DELETE 摘除）
+chongming/routes/<type>/__meta__      # 插件级元信息（可选，仅在声明 MQTT 主题时发布）
+```
+
+- `<type>`：插件类型（worker type），与 `config/workers/<type>/` 目录名一致
+- `<route_id>`：`<subject 的 "." 替换为 "_">__<METHOD>`，如 `demo.hello` + `GET` → `demo_hello__GET`
+- 载荷一律 UTF-8 JSON
+
+### 2.2 描述符字段（schema_version = 1）
+
+发布端在端点描述符上附加两个字段：
+
+```json
+{
+  "schema_version": 1,
+  "type": "demo",
+  ...以下字段来自端点定义（TOML 兼容 dict）
+}
+```
+
+网关侧消费的字段（`RouteConfig`，缺失时取默认值，未知字段忽略）：
+
+| 字段 | 类型 | 默认 | 说明 |
+| ---- | ---- | ---- | ---- |
+| `subject` | string | 必填 | RPC 主题，如 `demo.hello`；与 `worker/<type>/<id>/<subject>` 对应 |
+| `method` | string | `"GET"` | HTTP 方法（`GET/POST/PUT/PATCH/DELETE`）；`"MQTT"` 为纯 MQTT 端点（不注册 HTTP 路由）；网关侧统一大写处理 |
+| `path` | string | 空 | HTTP 路径，如 `/demo/hello`；含 `{param}` 时构成路径参数 |
+| `params` | array[string] | `[]` | 参数声明，每项 `"名称: 类型"`（类型支持 `str/int/float/bool/any`、`list[...]`、`dict[...]`）；无 `:` 的项按 `str` 处理 |
+| `response_model` | object | `{}` | 响应模型声明：`{"字段": {"type": "...", "required": bool, "default": ...}}` 或 `{"字段": "type"}`（仅用于网关 OpenAPI 文档与响应模型校验） |
+| `summary` | string | `""` | OpenAPI 摘要 |
+| `docstring` | string | `""` | OpenAPI 描述 |
+| `timeout` | number | `3.0` | 单次调用超时（秒）；流式端点为其**总寿命上限**，须配大（如 300） |
+| `cacheable` | bool | `false` | 网关侧结果缓存开关（成功响应按 `(type, subject, payload)` 缓存） |
+| `auth_required` | bool | `true` | 网关是否注入鉴权依赖（认证用户经信封 `meta.user_info` 透传给插件） |
+| `internal` | bool | `false` | 内部端点：不注册 HTTP 路由，仅保留 Zenoh RPC 调用能力 |
+| `stream` | bool | `false` | 流式端点：网关以 SSE 逐块转发多回复 |
+| `stream_idle_timeout` | number | `10.0` | 流式空闲超时（秒）：连续无数据块的最大间隔 |
+| `route_name` | string | 无 | 端点名（TOML 文件名），契约校验用于推断模型名；网关运行时不消费 |
+| `schema_version` | int | 1 | 协议版本（见 §7 演进规则） |
+| `type` | string | 插件类型 | 插件类型，网关缺失时以 keyexpr 中的 `<type>` 兜底 |
+
+> **描述符生成约定**（Python SDK 行为，其他语言须输出等价结构）：
+> - `method` 恒取自端点 TOML 节键并大写，不被 defaults 覆盖
+> - `path` 缺省为 `router_prefix + "/" + 端点名`
+> - `subject` 缺省为 `<type>.<端点名>`
+> - `[worker.defaults]` 中的键作为字段缺省值合并进描述符（显式字段优先）
+
+### 2.3 发布 / 摘除语义
+
+| 操作 | 行为 |
+| ---- | ---- |
+| 发布 | PUT 单个端点描述符到 `chongming/routes/<type>/<route_id>`；多端点逐个 PUT |
+| 元信息 | 声明了 `[[workers.mqtt_topics]]` 时，额外 PUT `chongming/routes/<type>/__meta__`，载荷 `{"schema_version": 1, "mqtt_topics": [{"topic": "...", ...}]}`；网关据此动态订阅外部主题 |
+| 重发布 | 每 10s 将**全部**描述符重新 PUT（幂等） |
+| 摘除 | 优雅退出（SIGTERM/SIGINT）时 DELETE 全部已发布 key；进程被 SIGKILL 时描述符残留，重启后重发布覆盖 |
+
+### 2.4 网关侧行为（实现方须知）
+
+- 订阅 `chongming/routes/**`；PUT → upsert，DELETE → remove
+- **幂等去重**：同一 `route_id` 描述符内容 hash 相同视为多副本重复发布，忽略
+- **冲突**：同一 `route_id` 内容不同 → 告警并**保留先到者**
+- **防抖**：type 级 2s 防抖，变更合并为一次路由重建
+- **健壮性**：非法 JSON / 非 dict 描述符 → 丢弃并告警，不影响网关
+- **路由筛选**：`method == "MQTT"` 或 `internal == true` 的端点不注册 HTTP 路由，但保留在路由表中
+
+---
+
+## 3. 服务发现协议（liveliness）
+
+- 插件进程为**每个副本**声明 liveliness token：`worker/<type>/<id>`
+- `<id>` 无格式约束（Python SDK 惯例 `worker-<i>-<pid>`）；网关只解析 `parts[1]` 作为类型
+- 网关每 15s 轮询 `worker/*/*` 刷新存活列表，调用时随机选择副本（负载均衡）
+
+---
+
+## 4. RPC 调用协议（Queryable）
+
+### 4.1 keyexpr
+
+```
+worker/<type>/<id>/<subject>
+```
+
+`<subject>` 与描述符的 `subject` 字段一致（多方法共享同一 subject 时，同一 keyexpr 由多个方法分派）。
+
+### 4.2 请求信封
+
+```
+{"meta": {"method": "GET", "user_info": {...}}, "data": {...业务参数...}}
+```
+
+| 字段 | 说明 |
+| ---- | ---- |
+| `meta.method` | HTTP 方法（大写）；**缺失默认 `GET`** |
+| `meta.user_info` | 网关注入的认证用户信息（`auth_required = true` 时存在，结构由网关鉴权决定） |
+| `data` | 业务参数：GET/DELETE 为查询/路径参数的 `{name: value}` 字典；POST/PUT/PATCH 为请求体字段 |
+
+**兼容规则**：非信封载荷（不含 `meta`/`data` 键的 JSON 对象）整包视为业务 `data`，按 `method = GET` 处理。
+
+### 4.3 响应
+
+| 形态 | 行为 |
+| ---- | ---- |
+| 普通 | 单个回复，载荷为业务结果 JSON 对象 |
+| 异常（非流式） | 单个回复：`{"result": 0.0, "operation": "error", "error": "<异常信息>", "worker": "<worker_id>"}` |
+| 流式 | 对同一 Query **多次 reply** 逐块推送；生成器正常结束 = 流结束（无结束哨兵）；中途异常以 `{"error": "<异常信息>"}` **收尾块**结束流；查询已终止（客户端断开）时停止回复 |
+
+网关侧对应行为：
+
+- 普通调用 `WorkerManager.call`：取首个回复；空回复 / zenoh 层错误 / 超时 → **切换副本重试**（默认重试 1 次）
+- 流式调用 `WorkerManager.call_stream`：逐块消费（`ConsolidationMode.NONE`）；收到含 `error` 键的块视为终止信号转发后结束；`reply.err`（zenoh 层错误）同样终止流
+- 无可用副本 → HTTP 503
+
+---
+
+## 5. 配置约定
+
+插件进程自读两份配置（其他语言实现须兼容读取语义）：
+
+| 配置 | 位置 | 用途 |
+| ---- | ---- | ---- |
+| 全局配置 | `config.toml`（`--config` 可指定） | 仅 `[zenoh].json5_path`（默认 `config/zenoh_config.json5`），JSON5 格式的 Zenoh 会话配置 |
+| 插件配置 | `config/workers/<type>/config.toml` | `[workers]` 节（type/count/load_mode/mqtt_topics/运行时配置）与端点 TOML 定义（描述符来源） |
+
+进程入口参数：`--type <name> [--count N] [--config config.toml]`（Python SDK 约定；其他语言可自定入口，但 `--type` 语义应保持一致）。
+
+> 非 Python 插件的配置读取完全由自身实现，**网关不读取插件配置**
+> （描述符经 Zenoh 发布，网关与插件配置解耦）。
+
+---
+
+## 6. 最小实现清单（其他语言插件）
+
+一个合规的插件进程必须实现：
+
+1. [ ] 解析 `config.toml` 的 `[zenoh].json5_path` 并打开 Zenoh 会话
+2. [ ] 为每个端点构造描述符（§2.2 字段表）并 PUT 到 `chongming/routes/<type>/<route_id>`
+3. [ ] 声明 `[[workers.mqtt_topics]]` 时 PUT `__meta__` 描述符
+4. [ ] 为每个副本声明 liveliness token `worker/<type>/<id>`（多副本时 id 互异）
+5. [ ] 为每个 subject 声明 Queryable `worker/<type>/<id>/<subject>`
+6. [ ] 解析请求信封（§4.2），按 `meta.method` 分派；回复符合 §4.3 三种形态
+7. [ ] 每 10s 重发布全部描述符
+8. [ ] 优雅退出时 DELETE 全部已发布 key
+
+**自检义务**：网关侧不做描述符强校验（契约校验是 Python SDK 的进程内行为），
+插件须自行保证描述符字段完整（尤其 `subject` / `method` / `path` / `params` / `response_model`），
+否则会挂载出错误路由。
+
+---
+
+## 7. 版本与演进规则
+
+- 描述符携带 `schema_version`（当前 `1`），网关对未知版本暂不拒绝（缺失时兜底为 1）
+- **协议变更分级**：
+  - 破坏性变更（keyexpr 结构、信封结构、错误格式、描述符语义）→ `schema_version` 递增，网关须先发布兼容处理，再切换
+  - 新增可选字段 / 新增端点形态 → 允许同版本内演进，但必须同步更新本规范
+- **修改即更新**：任何实现侧改动（`routes_publisher.py` / `runtime.py` / `route_registry.py` / `worker_manager.py` / `route_generator.py`）触及本规范描述的语义时，必须同步修订本规范
+
+---
+
+## 附录 A：事实来源索引
+
+| 协议项 | 唯一实现（文件:行号） |
+| ---- | ---- |
+| 描述符 keyexpr / route_id 编码 / 发布摘除 | `utils/worker/src/chongming_worker/routes_publisher.py:23-89` |
+| 描述符字段定义与消费 | `src/chongming/app/core/route_generator.py:82-100`（RouteConfig） |
+| 描述符生成约定（TOML → dict） | `utils/worker/src/chongming_worker/route_config.py:25-103` |
+| 网关订阅 / 防抖 / 幂等 / 冲突 / 筛选 | `src/chongming/app/core/route_registry.py:44-261` |
+| liveliness 发现 / 负载均衡 / 超时重试 / 缓存 | `src/chongming/app/core/worker_manager.py:73-379` |
+| 请求信封构造（meta.method / user_info） | `src/chongming/app/core/route_generator.py:241-405` |
+| 信封解析 / 分派 / 三种响应形态 | `utils/worker/src/chongming_worker/runtime.py:27-220` |
+| 进程生命周期（10s 重发布 / 优雅退出） | `utils/worker/src/chongming_worker/process.py:35-197` |
+| 配置读取（json5_path / 插件配置） | `utils/worker/src/chongming_worker/process.py:39-136` |
+| 契约校验语义（仅 Python SDK 进程内） | `utils/worker/src/chongming_worker/contracts.py:150-189` |
@@ -463,7 +463,10 @@ uv run python test_process_mode_e2e.py          # 端到端测试（先启动网
 - [主 README：进程插件与混合部署](../README.md)
 - [Worker 插件开发指南（inline，结构约定与装饰器细节）](../src/plugins/README.md)
 - [Worker 框架（chongming-worker）](../utils/worker/README.md)
+- [Worker 框架（Rust：chongming-worker-rs，多语言参考实现）](../utils/worker-rs/README.md)
 - [chongming-cli（build_plugin / gen_models 等命令）](../utils/cli/README.md)
+- [进程插件线协议规范（语言无关）](./plugin-wire-protocol.md)——网关与插件的唯一契约，其他语言实现（Rust/Go 等）据此开发
+- [多语言插件演进统一规划（Rust 优先）](./multi-language-plugin-plan.md)
 - 代码：`utils/worker/src/chongming_worker/process.py`（进程入口）、
  `routes_publisher.py`（路由发布协议）、`contracts.py`（契约校验）、
  `utils/cli/src/chongming_cli/build_plugin.py`（打包器）