2026-09-16
Router 新增饱和下限，全队排队时钉住前缀拥有者
值得精读：`policies/admission.rs` 的 pin 分支是完整的「何时不该分流」判据实现，`policies/engine_load.rs` 的极性注释解释了为什么缺采样两个方向的默认动作都是留在前缀拥有者。重点关注三个设计决策：floor 与 limit 的取值关系如何决定标签口径；压力排序与缓存局部性排序之间的取舍（作者明确标记为未决）；`all_queued` 语义扩张对现有看板的影响。若计划在生产启用，建议先确认 prefill 舰队负载采样覆盖率，并观察 `saturation_pin` 与 `all_queued` 计数是否出现预期外的增长。
路由器按请求强制与注入采样契约，拒绝码与指标落地
值得精读，尤其是三处设计决策：(1) `ProbedValue` 三态把「省略 / 可读数字 / 读不出」在反序列化期一次定形，避免了在每次请求上物化客户端大小的 `serde_json::Value`；(2) `parse_as_engine_number` 的注释解释了为什么不能靠推导 pydantic 规则写这个函数（Python 数字字面量规则与 pydantic 在 `1._5`、`1e_5`、`-_1` 上不一致），以及为什么 `reject` 选择 fail-closed；(3) 采样键 last-wins、路由键重复即 400 的非对称设计，理由是「让契约比较的值与引擎真正采样用的值一致」。建议重点关注：注入语义对客户端的影响评估、`Unusable` 误拒的线上可观测性、以及 stack 3 是否真的消除了 `build_outgoing_body` 的额外解析开销。适合作为「如何为跨 fleet 的强制契约编写 fail-closed 守卫、并为灰度准备指标」的工程范例。
为 Router 新增优雅关闭排空配置面与启动校验、告警
值得精读，但**只推荐给关心 router 部署形态与滚动升级语义的人**（k8s / 平台 / Router owner）；对模型、内核方向的工程师，读执行摘要即可，因为本 PR 没有任何运行期行为变化。精读时建议关注四个设计决策：① `shutdown_drain_advisory` 的 `>=` 边界与 `grace_declared` 字段（前者决定「drain 正好等于 grace」是否告警，后者决定同一告警是否能被日志聚合去重）；② 把秒 → `Duration` 的转换从 `main.rs` 收进 `ServerConfig::shutdown_drain()` 的理由；③ 软 advisory 与硬 `MAX_SHUTDOWN_DRAIN_SECS` 的职责切分，以及它留下的「drain > grace 仍可启动」空隙是否可接受；④ `Default` impl（服务测试）与穷举 `into_config`（约束生产）并存这一对取舍。同时把 #39016 一起拉出来读，才能真正判断这套配置面是否够用。
Router 双端支持 h2c：入站同端口协商、出站按 worker 选协议转发
值得精读，尤其适合关注路由层网络栈的工程师。推荐关注三个设计决策：其一，客户端对象在构造期分裂并在热路径做纯选择，这是把“per-worker 属性”落到共享代理对象上的通用解法，可直接迁移到其他按 worker 差异化的配置项；其二，`admin_client()` 把“扇出型流量不属于任何 worker”这一语义显式编码进 API，而不是让调用点随便借一个 worker 的协议；其三，测试用“只讲 HTTP/2 的 mock”与“只讲 HTTP/1.1 的 mock”制造互斥，让错误绑定在线上失败而不是在断言里失败，这套手法比断言“传进去的值是 X”强得多。阅读时建议同时看 #39004（解析规则与 `dials_cleartext` 的 URL 归一化陷阱）以及 `Cargo.toml` 中 `http2` feature 的存在理由，否则容易误以为 `WireProtocol::Http1` 在 TLS 上也只讲 HTTP/1.1。
Router 新增队列闸门：排队 worker 不再凭缓存亲和夺冠
值得精读，尤其是做路由 / KV 局部性 / 负载均衡的同学。重点看三处设计决策：(1) 为什么用 `num_waiting_reqs` 而不是 in-flight 或运行深度，以及 fail-open 的取舍（`queue_gate_admits` 的注释本身就是设计说明）；(2) 两条「第二层」为何不是同一个条件——这是把闸门从「一个 if」变成「一个可上线的特性」的关键，PR body 里「with a single prefix owner the gate rejects it, the set empties, the ungated tier re-admits that same queueing owner, and affinity traffic keeps flowing exactly where the gate meant to divert it」是最值得记住的一段；(3) `cache_aware_fallback_decision` 的判定顺序（`fleet_all_queued` 先于容量）如何决定「饱和 fleet 会不会读成健康 fleet」，这条正是 review 抓出来的 bug。上线前建议先确认引擎确实发布负载样本，并在目标 fleet 上评估 `fleet_is_all_queued` 的每请求开销。
新增采样契约配置面：类型、解析与启动校验
值得精读。本 PR 展示了一个高质量的「配置面先行、请求路径后置」的分层实现策略，手写解析器、有序 entries 解码、编译期 `ALL`/`index` 一致性断言、启动即失败（fail fast）的运维理念都很有参考价值。重点关注 `sampling.rs` 的解析与校验架构，以及它如何为 Stack 2/3 的注入与拒绝逻辑预留清晰的接口边界。
路由器按 worker 解析并存储 h2c/HTTP1 转发协议，为 h2c 转发铺路
值得精读。重点关注三点：(1) per-worker 协议 vs fleet-wide 客户端的设计取舍，由 `manager_resolves_protocol_per_worker_no_fleet_lock` 锁定，防止回归；(2) `dials_cleartext` 的 URL 规范化坑——无 scheme 短名被 `url` 解析成 scheme，是极易被复制错的模式；(3) 测试对「默认值假阳性」的防御——`wait_for_protocol` 同时等待 `model_ids` 非空，避免实现从未读取协议也通过断言。作为 h2c 功能的地基 PR，注释密度极高，几乎每条都在解释一个决策边界，适合作为 Rust 服务端工程实践范本。
Rust 前端新增外部多模态处理器扩展点
值得精读，尤其是扩展点设计：`MmProcessor` trait 抽象、`ProcessorExtensions` 的不透明字段透传、`validate-before-park` 的防御式结果校验、以及 BF16 以 `u16` 位模式零拷贝过界的做法。关注点建议放在：外部处理器接入文档是否补齐、`multimodal_*` 字段行为变更的兼容性说明、以及 GPU 实测落地前的风险接受度。
