feat(cache): add native KVCM cache event publisher

[putaopi7]

Summary

• add a native asynchronous KV cache event publisher that reports cache state directly to KVCM
• publish logical cache ADD/DELETE updates and authoritative FULL snapshots from SharedBlockCache
• integrate publisher startup and shutdown with the engine lifecycle
• expose the deployment configuration required to identify each publisher instance

Design

• publishing is limited to tp_rank == 0 for each data-parallel replica
• cache operations enqueue events without waiting for network I/O
• the queue is bounded and publishing failures remain fail-open for inference
• authoritative snapshots recover KVCM state after dropped or failed incremental updates
• publisher shutdown drains and joins the worker before detaching it from the cache

Configuration

• KV_CACHE_EVENT_PUBLISHER_TYPE
• KV_CACHE_EVENT_MANAGER_ENDPOINT
• KV_CACHE_EVENT_INSTANCE_GROUP
• KV_CACHE_EVENT_INSTANCE_ID
• KV_CACHE_EVENT_HOST_IP_PORT

Test plan

• //rtp_llm/cpp/cache/events/test:kv_cache_event_queue_test
• //rtp_llm/cpp/cache/events/test:kv_cache_event_publisher_test
• //rtp_llm/cpp/cache/test:cache_group_publication_test
• Python syntax checks and C++ formatting checks for the changed event-publisher sources

[LLLLKKKK]

AI Code Review - PR #1340

Status: LGTM

Summary: P0/0 · P1/0 · P2/11 · P3/11

Reviewed: commit 30ca7ca09b46 · 2026-08-27 18:16 UTC+8

lgtm ready to ci

Non-blocking Suggestions

P2

• 多 DP 副本共用 host_ip_port 时 KVCM host 状态被静默互相覆盖，dp 维度未参与身份构造 @ rtp_llm/cpp/cache/KVCacheManager.cc:729
  • 建议：二选一并补测试：（1）dp_size > 1 时由 host_ip_port 与 dp_rank 组合派生副本唯一 host 标识（同时用于上报 header 与 location_uri），使身份不依赖运维逐副本配置 env；（2）保持现语义但在 dp_size > 1 且 host_ip_port 无副本区分成分时打 WARNING 说明冲突风险，而不是静默注册冲突 host。建议在 KVCacheManagerTest.cc 补一条 dp_size>1 用例锁定所选行为。
• publisher_type 的 choices 校验在 CLI+env 混合路径被绕过，非法取值静默降级为关闭发布器 @ rtp_llm/server/server_args/kv_cache_group_args.py:46
  • 建议：把 type=str, choices=[...] 改为自定义转换函数（内部做 strip().lower() 归一化 + 集合校验，失败抛 argparse.ArgumentTypeError），这样混合路径的 action.type(env_value) 也会触发 server_args.py:363-364 的 self.error() 而 fail-fast，两条入口行为一致。更彻底的做法是在 env 回填分支统一校验 action.choices（该缺口对 fifo_scheduler_group_args.py、moe_group_args.py、ssm_state_dtype 等既有 choices 参数同样存在，属公共基础设施修复，可另开 PR）。无论哪种，都应补一条「非法 env 取值 + 存在 CLI 参数」的用例锁定行为，消除「已被校验」的错觉。
• 选择 kvcm 时缺少必填伴随字段的解析期联合校验，误配只表现为两条 WARNING @ rtp_llm/server/server_args/kv_cache_group_args.py:50
  • 建议：在 init_kv_cache_group_args 返回前或 setup_args 归一化阶段补一处联合校验：publisher_type == "kvcm" 且三项端点信息存在空值时直接 parser.error() 并报出缺失字段名。fail-soft 适合运行期抖动，「启动参数不完整」属配置错误，更适合在参数层 fail-fast，把配置错误与运行期 KVCM 不可用两类故障区分开。若产品上必须永不阻断推理，则至少为「发布器被禁用」暴露可告警指标或 ERROR 级日志。
• 发布器运行状态无指标或周期日志出口，头文件注释声称的 metrics 导出并不存在 @ rtp_llm/cpp/cache/events/KVCacheEventPublisher.h:18
  • 建议：在 reportMetricsLoop() 中读取 cache_event_publisher_->status()（为空则跳过），把 state、queue_size、accepted_count、dropped_count 上报为 kmonitor 指标，并沿用现有 kLogInterval（1 分钟）节流打印摘要日志，便于对 DEGRADED 与 dropped 增长告警；同时在文档补一节可观测性，列出注册/心跳/mutation 失败的 WARNING 关键字与 KVCMPublisher snapshot committed 正常态日志。若本版本确定不导出指标，请先删除或修正该注释，避免运维误以为已有监控看板。另注：新枚举已在 2 处留编号空洞并用 static_assert 钉死 STOPPED==7（:29），暗示一个尚不存在的外部编号契约，建议一并澄清。
• 注册到 KVCM 的 hbm spec_size_bytes 汇总了非 HBM 与不参与发布的 cache group @ rtp_llm/cpp/cache/KVCacheManager.cc:742
  • 建议：按 policy.memory_placement == CacheMemoryPlacement::DEVICE 过滤，并建议只累加同函数已得到的 reuse_group_ids（复用同一份筛选结果，避免第二套隐式口径），使该值与 medium=hbm、与实际发布的 key 口径一致；聚合可直接复用已有的 CacheConfig::groupBlockSizeBytesSnapshot()（CacheConfig.h:241）而非手写循环。若确需上报整机每 block 总字节，请在 KVCacheEventPublisherContext::spec_size_bytes 注释与文档中写明该字段是「全 group 合计」，并说明 hybrid 场景消费者应如何解读。
• instance_group 回落到字面量 default，使非空校验不可达并引入跨部署分组冲突 @ rtp_llm/cpp/cache/KVCacheManager.cc:726
  • 建议：二选一：其一，把该字段视为 kvcm 模式下的必填项，为空（或回落值仍等于字面量 default）时打 WARNING 甚至禁用发布，使校验语义真正生效；其二，保留回落但在参数 help 与文档中写明「回落值默认为 default，多部署共用会在 KVCM 侧发生分组冲突，生产环境必须显式配置」。同时建议在 isConfigValid() 注释中说明该字段实际不可能为空，避免读者误判校验强度。
• 文档声称的发布完备性语义比实现更宽，hybrid 下已发布 key 会高估可复用前缀 @ docs/backend/kv_cache_event_publisher.md:8
  • 建议：把条件收窄为实现口径，例如「only cache groups that participate in prefix reuse and materialize every block position are required; tail-sparse LINEAR/SWA groups are excluded」，并补一句说明混合注意力模型下已发布 key 是可复用前缀的上界而非精确值；同时补边界行为「必需组集合为空时完全不发布任何 key」（SharedBlockCache.cc:737-739）。若外部消费方依赖精确性，建议 hybrid 拓扑下先禁用发布或另行上报 tail 约束。
• 文档未列出 reuse_cache / enable_device_cache 前置条件，按文档配置会静默不生效 @ docs/backend/kv_cache_event_publisher.md:41
  • 建议：在 Configuration 小节补前置条件：启用 kvcm 需同时开启 --reuse_cache（默认关闭）与 --enable_device_cache，且必须存在参与前缀复用的稠密 cache group，否则发布器静默禁用；并给出可据以自查的日志关键字（配合上文可观测性建议）。
• initCacheEventPublisher 的门控决策树与 reuseParticipatingGroupIds 虚派发零测试覆盖 @ rtp_llm/cpp/cache/KVCacheManager.cc:679
  • 建议：在 KVCacheManagerTest.cc（已支持 warmup=true/false 构造，成本很低）补门控用例：type="kvcm" 分别配合 tp_rank=1、pp_size=2、kv_cache_sharded=true、reuse_cache=false、非法 type、纯 SWA（完备集为空）时断言不产生发布器；再覆盖 type=none 不创建、以及 start() 失败后 SharedBlockCache 上的发布器已被摘除。同时把两个匿名命名空间纯函数移入 KVCMPublisherUtils.h 的 detail（该头已被现有 test 覆盖）以便直接单测，并在 SingleTypeKVCacheAllocatorTest/HybridTypeKVCacheAllocatorTest 各加一条 reuseParticipatingGroupIds() 返回值断言。
• setEventPublisher 的存量挂载分支在唯一生产调用点不可达且无测试，detach 与空必需集路径同样零覆盖 @ rtp_llm/cpp/cache/SharedBlockCache.cc:476
  • 建议：先决定去留：若确认生产永不会挂到非空 cache，建议删除 :476-480 的 seeding 循环（YAGNI）；若保留作防御，则补用例——先 put 若干完整/不完整 key 再挂载，断言无事件但 logicalCacheSnapshot().cache_keys 已含完整 key，随后 remove 其中一个 pre-existing key 才产生 BLOCK_DELETE。另补两条：setEventPublisher(nullptr, {}) 后 put/remove/selectAndEvict 不再投递事件；setEventPublisher(publisher, {}) 与越界组 {7} 后做完整 put，断言零事件且快照为空，把「必需集为空 ⇒ 静默」钉成显式契约。
• 阻塞型测试替身使用无界等待且未覆写 cancel，断言早退会退化为整目标超时挂死 @ rtp_llm/cpp/cache/events/test/KVCacheEventPublisherTest.cc:118
  • 建议：把两处 cv_.wait 改为 wait_for(lock, kAsyncTestTimeout, ...)，超时后直接放行；同时覆写 cancel() 置位 release_mutation_ = release_snapshot_ = true 并 notify_all()，让 stop() 能确定性解除阻塞。另可把 :622 的 ASSERT_EQ 降为 EXPECT_EQ，或用 RAII guard 在测试退出时无条件 releaseMutation()/releaseSnapshot()，确保任何失败路径都产出可读断言（:556-562 的同类用例正因先 release 再 FAIL() 而无此风险）。

P3

• pickle 新增块用 t.size() == 62 精确匹配，与同函数既有 >= 惯例不一致 @ rtp_llm/cpp/pybind/ConfigInit.cc:664
  • 建议：将 :664 改为 >= 62，与 :645、:658 保持一致，使追加式演进天然安全；或把长度白名单（:598）与各块边界抽成一处常量（如 kStateSizeV4 = 62）并统一用 >=，避免同一函数并存两种互斥的扩展约定。同时把注释与测试名中的「declaration order」改为准确表述——元组只允许尾部追加，索引与结构体声明位置无关，照声明顺序在中段插入字段会破坏 43/54/57 三种历史布局。
• publisher type 合法值字面量在四处重复，且消费侧不做归一化 @ rtp_llm/cpp/config/ConfigModules.h:207
  • 建议：按模块既有惯例把 publisher type 定义为 C++ 枚举并通过 pybind 导出，Python 侧 choices 由枚举成员派生；若因跨版本 pickle 兼容需保留字符串存储，至少把合法值集中为一个常量（如 C++ 侧 kKVCacheEventPublisherTypeKvcm 与 Python 侧模块级常量）供 args 层与消费侧共同引用，并在消费前统一归一化。
• reuseParticipatingGroupIds override 与 spec 字节聚合重复既有实现 @ rtp_llm/cpp/cache/HybridKVCacheAllocator.cc:76
  • 建议：删除该 override 直接复用基类实现；若确需从 group 对象读取，请补 RTP_LLM_CHECK 保证已完成 init，避免未初始化时静默返回空集。KVCacheManager 侧改为调用 groupBlockSizeBytesSnapshot()，与上文 spec_size_bytes 过滤建议一并落地。
• 接入层存在冗余 reset 与日志级别不一致 @ rtp_llm/cpp/cache/KVCacheManager.cc:711
  • 建议：:711 统一降为 RTP_LLM_LOG_WARNING，并在消息中补充 group 数量与各 group 的 enable_prefix_reuse/active_tail_blocks 取值，便于直接定位是哪种拓扑导致禁用；删除三处调用点后的重复 reset 与 :718 的冗余 reset，让「清空发布器指针」这一职责只保留在 stopCacheEventPublisher() 内。
• metrics 线程启动位置的注释与实际依赖不符，并顺带改变了 connector 初始化顺序 @ rtp_llm/cpp/cache/KVCacheManager.cc:280
  • 建议：修正或删除该注释（若按上文接入发布器指标，可改为真实成立的理由）；若确需前移 initConnectorCoordinator()，请在 commit message 或注释中单独说明动机，否则恢复原有相对顺序、仅把 initCacheEventPublisher() 插入到 metrics 线程启动之前。
• 文档「bounded non-blocking enqueue」未反映溢出路径会在 cache 锁内取发布器互斥量 @ docs/backend/kv_cache_event_publisher.md:12
  • 建议：改为「正常路径为无锁入队；队列溢出时会在 cache 锁内额外做一次极短临界区唤醒」，并明确溢出属于「丢事件 + 触发快照」而非阻塞等待，便于读者评估持续溢出场景下的锁竞争成本。
• 文档缺少快照 fencing 载荷说明与内部固定参数、快照体量、关停耗时 @ docs/backend/kv_cache_event_publisher.md:25
  • 建议：把 fencing 表述改为「当前依赖单发布者串行提交与到达顺序，载荷不携带快照版本；若要求端点真正 fencing，需先在 EVENT_BLOCK_SNAPSHOT 中补单调递增的 generation 并约定语义」。在 KVCM lifecycle 小节补：上述固定参数及「本版本不可调」、快照体量与已发布 key 规模成正比（对端需承受周期性全量快照）、引擎关停最坏会因在途 mutation 与 HOST_DOWN 增加约两个请求超时；并在开头补一句 KVCM 角色定义与对端最小接口清单（/api/registerInstance、/api/reportEvent）及事件类型说明，避免 KVCM、EVENT_BLOCK_SNAPSHOT 等术语在对外文档中首次出现即无定义。
• 部分异步/并发测试断言强度不足或依赖线程调度 @ rtp_llm/cpp/cache/events/test/KVCacheEventPublisherTest.cc:580
  • 建议：把正向断言改为带 key 的形式（如 request.find("\"block_add\":{\"block_key\":\"42\"")），与负向断言共用同一 JSON 前缀，使单看正向断言即可证明「每个 key 只保留末态」。队列用例在 waiter 侧加一个「已进入 waitPop」的 std::promise/std::atomic<bool> 信号，主线程先等该信号再开始 wake 循环（或把 wake 循环 deadline 提到略小于 waitPop 的 2s 超时），使唯一可能的失败原因就是 wake 未生效。
• 新增测试 target 的 size/timeout 与依赖声明不一致 @ rtp_llm/cpp/cache/events/test/BUILD:20
  • 建议：把 kv_cache_event_publisher_test 的 size/timeout 按最坏等待预算放宽到 medium/moderate，保证失败时先命中 gtest 断言而非被外层超时截断；给 kv_cache_event_queue_test 补上明确的 size 声明。shared_block_cache_test 建议显式写出 + torch_deps() + cuda13_torch_link_deps（与同文件 cache_layer_layout_test:76-85 至少对齐 torch_deps()），或更彻底地把 cuda13_torch_link_deps 收进 //rtp_llm/cpp/cache:block_pool 自身依赖，让消费者不必各自追加；并在 PR 描述中说明移除 exec_properties = {'gpu':'H20'} 是有意放宽调度、cuda13 配置已在验证矩阵内。
• pickle 契约测试的魔法常量缺少同步说明，且常量命名与内容不符 @ rtp_llm/config/test/kv_cache_config_pickle_test.py:31
  • 建议：在两个常量上方加简短注释，说明它们是 pickle 兼容契约的一部分，新增字段需按「加入合法长度集合 → 新增恢复分支 → 更新本文件常量」三步同步；把 DISK_CACHE_FIELDS 更名为能反映真实含义的名字（如 STATE_54_BLOCK_FIELDS）；并按 server_args_test.py 既有范式补一行生产类型往返（pickle.loads(pickle.dumps(py_env_configs.kv_cache_config))），把断言覆盖到真正跨进程使用的类型上。
• 测试数据 NamedTuple 的 raw/expected 字段冗余、类型被弱化，且消费侧混用位置解包 @ rtp_llm/config/test/kv_cache_event_test_values.py:8
  • 建议：在真正出现非字符串 env 之前，把 raw_value/expected_value 收敛为单一 value: str；若为扩展预留，至少标注为 str，待引入非字符串字段时再放宽为显式 Union 并附原因注释。server_args_test.py:490/501 统一改为命名访问，并把两个用例共同的「设置 env → reload → 逐字段断言」抽成接受 argv 的私有辅助方法，分别传入 ["prog", "--model_type", "qwen"] 与 ["prog"]。

Checklist Findings (19 fail / 55 total)

General Principles Checklist

• [6.1] Architecture — 兼容性：外部 HTTP/RPC API、持久数据、配置、环境迁移安全 → issue pickle 契约测试的魔法常量缺少同步说明，且常量命名与内容不符
CURRENT_STATE_SIZE = 62 与 EVENT_FIELD_OFFSET = 57（:31-32）被 5 个用例共同依赖，新增字段会同时触发 :41 长度断言、:54 切片比对与 :110 的 CURRENT_STATE_SIZE - 1 三处失败。tripwire 设计合理，但文件内无任何注释告知维护者正确修复方向（需同步 ConfigInit.cc:598 的长度白名单并新增恢复分支），容易被误判为「测试坏了」而直接改数字、绕过兼容分支。另 DISK_CACHE_FIELDS（:9-21）实际涵盖 enable_gpu_prefix_tree、load_cache_retry_times 等非磁盘缓存字段，命名与内容不符。测试导入的是 pybind 基类 rtp_llm.ops.KVCacheConfig，而生产跨进程 pickle 的是 rtp_llm/config/kv_cache_config.py:9 的子类（该子类未新增状态也未覆写 __reduce_ex__，故风险有限）。
• [6.1] Architecture — 分层边界：新概念在正确层级，不泄漏内部 → issue 文档缺少快照 fencing 载荷说明与内部固定参数、快照体量、关停耗时
:25 要求「The endpoint must support snapshot fencing and crash-safe commit semantics」，但 buildSnapshotReport（KVCMPublisher.cc:377-401）生成的 EVENT_BLOCK_SNAPSHOT 只含 blocks[]，header 只有 trace_id/instance_id/host_ip_port（:252-259），不含单调 version/generation（两者仅出现在本地 INFO 日志 :575-582），且 next_request_id_ 每次启动都从 1 开始（:758），对端没有可跨重启 fencing 的标识。另 KVCacheEventPublisherConfig.h:12-19 的队列容量、批量、flush 20ms、心跳 1s、请求超时 1500ms、快照超时/退避上限 30s、快照周期 5 分钟全部硬编码不可调，文档未提及；快照 payload 为 published_keys_
• [6.1] Architecture — 可观测性：日志/指标/超时可操作、非噪声 → issue 新增测试 target 的 size/timeout 与依赖声明不一致
kv_cache_event_publisher_test 声明 size = "small" + timeout = "short"（60s），但该文件 kAsyncTestTimeout = 10s 的等待点十余处，另有并发 start/stop 竞争循环；一旦某个 waitForBody 真的等不到（叠加上文无界阻塞替身问题），累计等待远超 60s，Bazel 只报 target TIMEOUT 而丢掉 gtest 失败用例名。同目录 kv_cache_event_queue_test（BUILD:5-16）反而未声明 size，尽管它跑 20000 事件压力循环，两者取向相反。另 cache/test/BUILD:174-187 把 shared_block_cache_test 的 deps 由 block_cache_test_deps（含 torch_deps() + cuda13_torch_link_deps）裁剪为 :block_pool + gtest 并移除 exec_properties，但 `block_p
• [6.1] Architecture — 回滚路径：风险行为存在运维回滚手段 → issue 文档缺少快照 fencing 载荷说明与内部固定参数、快照体量、关停耗时
:25 要求「The endpoint must support snapshot fencing and crash-safe commit semantics」，但 buildSnapshotReport（KVCMPublisher.cc:377-401）生成的 EVENT_BLOCK_SNAPSHOT 只含 blocks[]，header 只有 trace_id/instance_id/host_ip_port（:252-259），不含单调 version/generation（两者仅出现在本地 INFO 日志 :575-582），且 next_request_id_ 每次启动都从 1 开始（:758），对端没有可跨重启 fencing 的标识。另 KVCacheEventPublisherConfig.h:12-19 的队列容量、批量、flush 20ms、心跳 1s、请求超时 1500ms、快照超时/退避上限 30s、快照周期 5 分钟全部硬编码不可调，文档未提及；快照 payload 为 published_keys_
• [6.1] Architecture — 状态不变量：创建/更新/失败/重试/回滚路径有效 → issue 文档声称的发布完备性语义比实现更宽，hybrid 下已发布 key 会高估可复用前缀
  文档写「A key is added only after every cache group that participates in prefix reuse is complete and matchable」，但实现要求 enable_prefix_reuse && active_tail_blocks == 0（CacheGroupType.h:161-162）。defaultCacheGroupPolicy 对 LINEAR 恰好给出 enable_prefix_reuse=true, active_tail_blocks=1（:146-147），即 LINEAR 确实参与 prefix reuse 却被排除在必需集合外。而 HybridKVCacheAllocator::reuseCache() 的 reuse_blocks_len 由 pos 向前回退到所有 tail group 同时命中处决定（:117-158）：LINEAR/SWA tail 被淘汰时实际可复用前缀显著短于已发布 key，外部 cache-aware 路由按文档理
• [6.1] Architecture — 错误语义：fail-fast/retry/fallback/silent 行为显式 → issue 文档「bounded non-blocking enqueue」未反映溢出路径会在 cache 锁内取发布器互斥量
  文档称 cache mutation「only attempt a bounded non-blocking enqueue」，:14 称发布「never affects allocation, eviction」。实现中 updatePublishedStateLocked 在持有 SharedBlockCache::mu_ 的临界区内调用 tryPublish（SharedBlockCache.cc:763/767），而 tryPublish 在非 ACCEPTED 分支调用 queue_.wake()（KVCMPublisher.cc:481），后者会 std::lock_guard<std::mutex> lock(wait_mu_) 并 notify_all（KVCacheEventQueue.cc:74-80）。即队列满/已停时每次 put 与 evict 都会在 cache 全局锁内再取一次发布器互斥量，并非纯非阻塞。已核对无锁序倒挂：worker 侧 waitPop/waitForStop 均在退出临界区后才回调 sn
• [6.1] Quality — Commit 原子、message 与行为匹配 → issue metrics 线程启动位置的注释与实际依赖不符，并顺带改变了 connector 初始化顺序
:280-281 注释写「Start metrics only after the publisher pointer becomes stable」，但 reportMetricsLoop()（:830-857）与 collectGlobalCacheMetrics()（:51-74）只访问 metrics_reporter_/allocator_；本文件对 cache_event_publisher_/publisher_shared_cache_ 的引用仅出现在 :681-805，不存在该依赖。同时 diff 显示 initConnectorCoordinator() 由原先「metrics 线程之后」被前移到「之前」，这是与事件发布无关的行为变更，会使 KV cache 指标首次上报被 connector 初始化（可能含远端连接建立）阻塞。
• [6.1] Quality — 逻辑变更未混入无关格式化 → issue metrics 线程启动位置的注释与实际依赖不符，并顺带改变了 connector 初始化顺序
:280-281 注释写「Start metrics only after the publisher pointer becomes stable」，但 reportMetricsLoop()（:830-857）与 collectGlobalCacheMetrics()（:51-74）只访问 metrics_reporter_/allocator_；本文件对 cache_event_publisher_/publisher_shared_cache_ 的引用仅出现在 :681-805，不存在该依赖。同时 diff 显示 initConnectorCoordinator() 由原先「metrics 线程之后」被前移到「之前」，这是与事件发布无关的行为变更，会使 KV cache 指标首次上报被 connector 初始化（可能含远端连接建立）阻塞。
• [6.1] Software Engineering — DRY：重复非平凡逻辑被抽取或显式复用 → issue reuseParticipatingGroupIds override 与 spec 字节聚合重复既有实现
  基类实现取 config_.groupPoliciesSnapshot()（KVCacheAllocator.cc:493-495），override 则遍历 kv_cache_groups_ 取 group->policy()（HybridKVCacheAllocator.cc:80-85）。kv_cache_groups_ 由同一份 config_ 构造，两者结果恒等，属重复实现；且 kv_cache_groups_ 在 doInit() 后才填充，当前调用点（KVCacheManager.cc:709，位于 allocator_->init() 之后）安全，但若将来有调用点早于 init，override 会静默返回空集（等价于禁用发布）而基类仍返回正确结果，形成难以察觉的行为分叉。同理 KVCacheManager.cc:735-739 手写的 per-group 字节循环重复了 CacheConfig::groupBlockSizeBytesSnapshot()（CacheConfig.h:241）。
• [6.1] Software Engineering — KISS/YAGNI：无投机性抽象 → issue 测试数据 NamedTuple 的 raw/expected 字段冗余、类型被弱化，且消费侧混用位置解包
KVCacheEventEnvCase 同时声明 raw_value: str 与 expected_value: object（:7-8），但全部 5 个 case 两值完全相同（:12-41 均为字符串恒等映射），当前不存在需要类型转换的字段，属为假想需求预留；expected_value: object 还在 pyright strict 下削弱了 server_args_test.py:503 与 kv_cache_config_pickle_test.py:45 断言的类型校验能力，而对应字段在 .pyi:740-744 均为 str，且无注释说明放宽原因。消费侧 server_args_test.py:490、:501 用位置解包，紧邻的 :510、:519 用 case.env_name 命名访问，两种风格并存且位置解包在追加字段时会直接因元素个数不匹配报错；两个 env 用例的断言循环也高度重复。
• [6.1] Software Engineering — LSP：子类/重写保持基类契约 → issue reuseParticipatingGroupIds override 与 spec 字节聚合重复既有实现
  基类实现取 config_.groupPoliciesSnapshot()（KVCacheAllocator.cc:493-495），override 则遍历 kv_cache_groups_ 取 group->policy()（HybridKVCacheAllocator.cc:80-85）。kv_cache_groups_ 由同一份 config_ 构造，两者结果恒等，属重复实现；且 kv_cache_groups_ 在 doInit() 后才填充，当前调用点（KVCacheManager.cc:709，位于 allocator_->init() 之后）安全，但若将来有调用点早于 init，override 会静默返回空集（等价于禁用发布）而基类仍返回正确结果，形成难以察觉的行为分叉。同理 KVCacheManager.cc:735-739 手写的 per-group 字节循环重复了 CacheConfig::groupBlockSizeBytesSnapshot()（CacheConfig.h:241）。
• [6.1] Software Engineering — OCP：本地扩展点优先于修改中心逻辑 → issue pickle 新增块用 t.size() == 62 精确匹配，与同函数既有 >= 惯例不一致
  同一 KVCacheConfig unpickle 函数内既有两块用范围判断（:645 的 >= 54、:658 的 >= 57），本次新增块 :664 写成 == 62，而 :589-590 注释又明确写着「Future fields must be appended after the block」；按该注释追加第 63 个字段时 == 62 不再成立，5 个事件字段会全部跳过赋值。降为 P3 的依据：kv_cache_config_pickle_test.py:41 硬断言 len(__getstate__()) == 62、:44-45 断言事件字段 round-trip，追加字段时会先在 CI 失败并迫使维护者同步修改。另 :589 与测试方法名的「declaration order」表述不准确：新字段在 ConfigModules.h:207-211 实际插在 reco_* 块之前，与「pickle 跟随声明顺序」的心智模型冲突。
• [6.1] Tests — 分布式/跨平台变更有对应覆盖 → issue 新增测试 target 的 size/timeout 与依赖声明不一致
kv_cache_event_publisher_test 声明 size = "small" + timeout = "short"（60s），但该文件 kAsyncTestTimeout = 10s 的等待点十余处，另有并发 start/stop 竞争循环；一旦某个 waitForBody 真的等不到（叠加上文无界阻塞替身问题），累计等待远超 60s，Bazel 只报 target TIMEOUT 而丢掉 gtest 失败用例名。同目录 kv_cache_event_queue_test（BUILD:5-16）反而未声明 size，尽管它跑 20000 事件压力循环，两者取向相反。另 cache/test/BUILD:174-187 把 shared_block_cache_test 的 deps 由 block_cache_test_deps（含 torch_deps() + cuda13_torch_link_deps）裁剪为 :block_pool + gtest 并移除 exec_properties，但 `block_p
• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue 部分异步/并发测试断言强度不足或依赖线程调度
  其一，coalesce 用例的正向断言 saw_final_add_42 = request.find("EVENT_BLOCK_ADD") != npos（:580）与 saw_final_delete_43（:584）只检查报文中存在某个 ADD/DELETE，未把事件类型与 block_key 关联；由于同一请求同时携带 key 42 的 ADD 与 key 43 的 DELETE，即使实现把两者方向搞反这两个布尔量仍为 true，真正生效的是 :581、:585 两条带 key 的负向断言。其二，KVCacheEventQueueTest.cc:83 的 WakeInterruptsEmptyWaitPop 用 1s wall-clock 循环调 wake()，而 waitPop 进入等待前先快照 wake_generation_（KVCacheEventQueue.cc:44），若 std::async 线程 1s 内始终未被调度，实现正确也会失败且无法区分失败原因。
• [6.1] Tests — 边界 case 覆盖（空、单元素、最大值） → issue 部分异步/并发测试断言强度不足或依赖线程调度
  其一，coalesce 用例的正向断言 saw_final_add_42 = request.find("EVENT_BLOCK_ADD") != npos（:580）与 saw_final_delete_43（:584）只检查报文中存在某个 ADD/DELETE，未把事件类型与 block_key 关联；由于同一请求同时携带 key 42 的 ADD 与 key 43 的 DELETE，即使实现把两者方向搞反这两个布尔量仍为 true，真正生效的是 :581、:585 两条带 key 的负向断言。其二，KVCacheEventQueueTest.cc:83 的 WakeInterruptsEmptyWaitPop 用 1s wall-clock 循环调 wake()，而 waitPop 进入等待前先快照 wake_generation_（KVCacheEventQueue.cc:44），若 std::async 线程 1s 内始终未被调度，实现正确也会失败且无法区分失败原因。

RTP-LLM Checklist

• [I] 代码质量 — 同一功能用统一工具函数 → issue 新增测试 target 的 size/timeout 与依赖声明不一致
kv_cache_event_publisher_test 声明 size = "small" + timeout = "short"（60s），但该文件 kAsyncTestTimeout = 10s 的等待点十余处，另有并发 start/stop 竞争循环；一旦某个 waitForBody 真的等不到（叠加上文无界阻塞替身问题），累计等待远超 60s，Bazel 只报 target TIMEOUT 而丢掉 gtest 失败用例名。同目录 kv_cache_event_queue_test（BUILD:5-16）反而未声明 size，尽管它跑 20000 事件压力循环，两者取向相反。另 cache/test/BUILD:174-187 把 shared_block_cache_test 的 deps 由 block_cache_test_deps（含 torch_deps() + cuda13_torch_link_deps）裁剪为 :block_pool + gtest 并移除 exec_properties，但 `block_p

Python Static-First Checklist

• [P.A] 静态结构与类型纪律 — 字符串分发用 Enum/Literal → issue publisher type 合法值字面量在四处重复，且消费侧不做归一化
none | kvcm 这组合法值散落四处独立维护：ConfigModules.h:207 的行尾注释、kv_cache_group_args.py:46 的 choices、KVCacheManager.cc:682/685 的字符串比较、以及文档配置表。同一 pybind 配置模块内已有 CacheEvictPolicy、CacheReusePolicy、CacheMemoryPlacement、CacheGroupType 等 C++ 枚举导出到 Python 的先例，本次却退回裸字符串分发，且消费侧不做 tolower；与上文 choices 绕过叠加后，同一笔误在两条入口行为不同。
• [P.G] 测试规范 — mock/fake/stub 不得替代本次声称覆盖的生产边界 → issue pickle 契约测试的魔法常量缺少同步说明，且常量命名与内容不符
CURRENT_STATE_SIZE = 62 与 EVENT_FIELD_OFFSET = 57（:31-32）被 5 个用例共同依赖，新增字段会同时触发 :41 长度断言、:54 切片比对与 :110 的 CURRENT_STATE_SIZE - 1 三处失败。tripwire 设计合理，但文件内无任何注释告知维护者正确修复方向（需同步 ConfigInit.cc:598 的长度白名单并新增恢复分支），容易被误判为「测试坏了」而直接改数字、绕过兼容分支。另 DISK_CACHE_FIELDS（:9-21）实际涵盖 enable_gpu_prefix_tree、load_cache_retry_times 等非磁盘缓存字段，命名与内容不符。测试导入的是 pybind 基类 rtp_llm.ops.KVCacheConfig，而生产跨进程 pickle 的是 rtp_llm/config/kv_cache_config.py:9 的子类（该子类未新增状态也未覆写 __reduce_ex__，故风险有限）。
• [P.H] 类型标注 — Any 必须附注释说明原因 → issue 测试数据 NamedTuple 的 raw/expected 字段冗余、类型被弱化，且消费侧混用位置解包
KVCacheEventEnvCase 同时声明 raw_value: str 与 expected_value: object（:7-8），但全部 5 个 case 两值完全相同（:12-41 均为字符串恒等映射），当前不存在需要类型转换的字段，属为假想需求预留；expected_value: object 还在 pyright strict 下削弱了 server_args_test.py:503 与 kv_cache_config_pickle_test.py:45 断言的类型校验能力，而对应字段在 .pyi:740-744 均为 str，且无注释说明放宽原因。消费侧 server_args_test.py:490、:501 用位置解包，紧邻的 :510、:519 用 case.env_name 命名访问，两种风格并存且位置解包在追加字段时会直接因元素个数不匹配报错；两个 env 用例的断言循环也高度重复。

Strengths

• 分层边界干净：cache 变更点只依赖 KVCacheEventPublisher 四个纯虚函数（KVCacheEventPublisher.h:40-48），传输、批量、重试、快照全部封在 events/ 内；events/BUILD 把 kv_cache_event_queue 的 visibility 精确收敛到 events 及其 test 包，block_pool 只引 header-only 的 :kv_cache_event，无循环依赖。
• 生命周期顺序可推理：~KVCacheManager()（:229-237）先 join metrics 线程、再 stopCacheEventPublisher()（先 stop() join worker，后 setEventPublisher(nullptr, {}) 摘除），最后 reset allocator，避开 worker 持 cache 锁与清理路径互等。
• snapshot_provider 捕获 weak_ptr<SharedBlockCache>（:750-764）而非 shared_ptr，避开 manager→cache→publisher→cache 引用环；缓存失效时以异常显式暴露而非静默返回空快照。
• 发布完备集被提炼为纯函数 cacheGroupPublishesPrefixChain（CacheGroupType.h:161），把「参与 prefix reuse」与「稠密物化每个 block 位置」拆成两个条件，并在 CacheGroupType.h:156-160 与 HybridKVCacheAllocator.cc:77-79 两处说明为何不能沿用 skipReuseCacheGroup() 口径，规避了「几乎所有 key 都无法发布」的陷阱；配套测试仅依赖 :cache_group_type，无 GPU 可跑。
• 队列不变量设计正确且被精确锁定：enqueue() 先 CAS 占位再按 pos 赋 sequence（KVCacheEventQueue.cc:102-115），配套 8 producer × 2000 事件的并发单调性用例；锁序经核对无倒挂——worker 持 wait_mu_ 期间从不回调 logicalCacheSnapshot()。
• 全链路 fail-open 且 gating 完备：未知 type、reuse_cache/enable_device_cache 关闭、pp_size!=1/tp_rank!=0、CP 分片、完备集为空、SharedBlockCache 缺失、start() 失败与两个 catch 分支均只降级不影响推理；start() 失败还会把发布器从 cache 上摘除，避免长期无谓的 tryPublish 开销。
• coalesce 语义有代码级理由：coalesceMutations（KVCMPublisher.cc:312-329）注释说明 KVCM 在单请求内先应用全部 ADD 再 DELETE，故同 key 只能保留最后一次跃迁，避免 DELETE→ADD 被反转。
• 事件去重有实现支撑：published_keys_ 成员关系翻转时才发事件（SharedBlockCache.cc:752-769），重复 put 与 LRU touch 不产生事件；isLogicallyCompleteLocked 对空集与越界 gid 双重返回 false。
• pickle 演进克制：新字段一律尾部追加、旧索引 0..56 完全不动、保留 43/54/57 三个 legacy 分支；测试同时覆盖 62 项往返、三种降级取默认值与 7 个非法长度拒绝，形成有效 canary。
• 测试替身全部通过生产接口注入（KVCacheEventReporter / KVCacheEventPublisher），未引入 #ifdef TEST 或 friend 钩子；kv_cache_event_test_values.py 把「env 名/字段名/取值」收敛为单一数据源供两个测试共用，并以 __pkg__ 精确限定可见性。
• 能力边界主动记录：文档的 pp/CP/tp_rank 限制、medium 仅 hbm、none 不创建队列/线程/连接、pickle 四种布局与「进程需同步升级或回滚」的运维约束，均逐条对得上实现；文档已注册进 docs/index.rst:69 的 Advanced Features toctree，非孤儿页。

[putaopi7]

Internal CI run 66497312 failed only in ut-sm8x before the test binary started: shared_block_cache_test exited with code 127 because libcuda.so.1 was unavailable.

The existing target had accidentally lost its block_cache_test_deps and exec_properties = {'gpu':'H20'} declarations during BUILD cleanup. I restored the target to the main-branch configuration and kept the new CPU-only cache_group_publication_test as a separate target. No production source changed.

The branch remains three commits; current HEAD is 00a155b511bf. Please re-review the current HEAD / issue a fresh lgtm ready to ci.

[LLLLKKKK]

AI Code Review - PR #1340

Status: LGTM

Summary: P0/0 · P1/0 · P2/11 · P3/14

Reviewed: commit 00a155b511bf · 2026-08-27 20:24 UTC+8

lgtm ready to ci

Non-blocking Suggestions

P2

• 注册到 KVCM 的 hbm spec_size_bytes 汇总了非 HBM 与不参与发布的 cache group @ rtp_llm/cpp/cache/KVCacheManager.cc:742
  • 建议：改用 config_.groupBlockSizeBytesSnapshot() 并把求和范围收敛为 reuse_group_ids（与发布完备集同源），同时显式跳过 policy.memory_placement != DEVICE 的 group，避免把 pinned DRAM 字节计入 hbm spec。若确实意图上报「整块物理占用」，请在代码注释与 docs/backend/kv_cache_event_publisher.md 中写明该语义及 * tp_size 的聚合口径（blockSizeBytesForGroup 是 per-rank 值，乘 tp_size 得到的是 TP 组合计）。
• instance_group 回落到字面量 default，使非空校验不可达并引入跨部署分组冲突 @ rtp_llm/cpp/cache/KVCacheManager.cc:726
  • 建议：在启动成功日志补打 publisher_context.instance_group 与 publisher_config.manager_endpoint；当 kv_cache_event_instance_group 为空而实际使用 reco_instance_group 兜底时输出一条显式 WARNING（尤其当兜底值本身就是默认 "default"），或直接要求 kvcm 模式必须显式配置 group。文档 :37 的「falls back to reco_instance_group」也应补充该字段自身默认为 default、共享分组会互相污染。
• 多 DP 副本共用 host_ip_port 时 KVCM host 状态被静默互相覆盖，dp 维度未参与身份构造 @ rtp_llm/cpp/cache/KVCacheManager.cc:729
  • 建议：在 initCacheEventPublisher() 增加启动期校验：dp_size > 1 且 kv_cache_event_host_ip_port 无法区分副本时打 ERROR 并禁用发布，而不是静默注册；或改为由运行期实际监听地址推导该值，仅在显式覆盖时使用配置值。最低限度应把 dp_rank 纳入节点身份或 location_uri，并在启动日志中同时打印 dp_rank/dp_size/host_ip_port 以便快速发现冲突。
• 发布器运行状态无指标或周期日志出口，头文件注释声称的 metrics 导出并不存在 @ rtp_llm/cpp/cache/events/KVCacheEventPublisher.h:18
  • 建议：在 reportMetricsLoop() 中读取 cache_event_publisher_->status()，把 state、queue_size、accepted_count、dropped_count 接入既有 kmonitor 上报，使 DEGRADED 与 dropped 增长可告警；或至少在 worker 内周期打印一条聚合状态日志。同时在文档补「可观测性与排障」小节列出各 PublisherState 含义与关键日志关键字。若本版本确实不提供指标，请先修正头文件注释与文档表述，避免误导后续维护者以为链路已存在。
• publisher_type 的 choices 校验在 CLI+env 混合路径被绕过，非法取值静默降级为关闭发布器 @ rtp_llm/server/server_args/kv_cache_group_args.py:46
  • 建议：对该参数改用会抛 argparse.ArgumentTypeError 的受约束 type= 转换器（混合分支已对该异常调用 self.error，server_args.py:363-364），使两条路径错误语义一致，并补两条用例：混合模式与纯 env 模式下同一非法值分别断言 SystemExit。若决定保持 fail-soft，请把 KVCacheManager.cc:686 的 unknown type 日志提升为 ERROR 并提示疑似拼写错误，同时在测试中断言当前语义并注明这是已知框架分歧。
• 选择 kvcm 时缺少必填伴随字段的解析期联合校验，误配只表现为两条 WARNING @ rtp_llm/server/server_args/kv_cache_group_args.py:50
  • 建议：在 args 层对「type=kvcm 且 manager_endpoint/instance_id/host_ip_port 任一为空」的组合直接 parser.error() 快速失败；若坚持 fail-open，请把 isConfigValid() 失败日志改为逐项列出缺失字段名并升级为 ERROR，并在文档表格把这三项标注为「type=kvcm 时必填，为空则整体降级为不发布」，同时给出一条最小可用启动参数示例。
• 文档声称的发布完备性语义比实现更宽，hybrid 下已发布 key 会高估可复用前缀 @ docs/backend/kv_cache_event_publisher.md:8
  • 建议：把 :8-9 改为「仅当所有稠密物化的可复用 group（active_tail_blocks == 0）完整且可匹配时才发布该 key；LINEAR/SWA 等仅保留尾块的 group 不计入完备集」，并显式声明 hybrid 拓扑下发布结果是可复用长度的上界而非精确值。可在 initCacheEventPublisher() 检测到存在 tail-sparse 且 enable_prefix_reuse=true 的 group 时打一条 WARNING，说明该实例的发布语义为上界。
• 文档未列出 reuse_cache / enable_device_cache 前置条件，按文档配置会静默不生效 @ docs/backend/kv_cache_event_publisher.md:41
  • 建议：在 Configuration 或 Semantics 段补充硬前置条件：启用 kvcm 还需 --reuse_cache=True（默认 False，必须显式打开）与 --enable_device_cache=True，且 warmup 阶段不发布；不满足时发布被静默关闭、仅留一条 WARNING、推理不受影响。同时补一句运维回滚说明：把 type 置回 none 即可完全关闭。
• 发布器门控决策树与 reuseParticipatingGroupIds 虚派发零测试覆盖 @ rtp_llm/cpp/cache/KVCacheManager.cc:679
  • 建议：复用 kv_cache_manager_test fixture 加一组表驱动用例：以合法 kvcm 配置为基线逐个翻转 warmup_、reuse_cache、enable_device_cache、tp_rank=1、pp_size=2、CP 分片，断言 cache_event_publisher_ == nullptr && publisher_shared_cache_ == nullptr 且 init() 仍返回 true；再补一例 start() 返回 false 时两个成员被清空、回调已摘除。把 resolveKVCacheEventInstanceGroup/aggregateKVCacheEventSpecSizeBytes 上移到已导出的 KVCMPublisherUtils.h（与 normalizeKVCacheEventEndpoint 一致）并补纯函数单测；在 Single/Hybrid allocator 测试中各加一例覆盖纯 FULL、FULL+SWA、FULL+LINEAR、enable_prefix_reuse=false 与空分组边界。
• setEventPublisher 的存量挂载分支在唯一生产调用点不可达且无测试，detach 与空必需集路径同样零覆盖 @ rtp_llm/cpp/cache/SharedBlockCache.cc:476
  • 建议：补两条 SharedBlockCacheTest 用例：一是先 put 若干完整/不完整 key 再 setEventPublisher，断言 logicalCacheSnapshot().cache_keys 恰好等于完整 key 集合（覆盖回填分支）；二是挂载后 setEventPublisher(nullptr, {})，断言后续 put/remove 不再产生事件且快照为空（覆盖 detach）。若确认回填分支在当前架构下永远不可达，则应删除该循环或加注释说明它为未来「运行期热挂载」预留，避免留下无法验证的死分支。
• isConfigValid 12 个条件只覆盖 instance_id，「kvcm + endpoint 为空」这条最常见误配零覆盖 @ rtp_llm/cpp/cache/events/test/KVCacheEventPublisherTest.cc:257
  • 建议：改为表驱动：以 makeContext() 为基线逐项置空字符串字段、置零 block_size_tokens/spec_size_bytes、置空 snapshot_provider，统一断言 start()==false && status().state==DEGRADED && tryPublish(...)==NOT_RUNNING；再补一条不注入 reporter 且 manager_endpoint 为空的用例，锁定该组合必须 fail-safe 关闭且析构不崩溃；另补一条 endpoint 非空的构造用例，使 snapshot_timeout_ms 不再是无人验证的旋钮。

P3

• pickle 新增块用 t.size() == 62 精确匹配，与同函数既有 >= 惯例不一致 @ rtp_llm/cpp/pybind/ConfigInit.cc:664
  • 建议：将 :664 改为 if (t.size() >= 62)，与相邻两块保持同一展开模式；并把注释补充为「新增字段块必须使用 >= 下界判断，且不得改动已有块的下界」。改成 >= 后可再补一条「state 长度大于 62 时事件字段仍被还原」的用例，把该前向兼容约束固化为测试。
• publisher type 合法值字面量在四处重复，且新增字段块的等号对齐与 clang-format 不一致 @ rtp_llm/cpp/config/ConfigModules.h:207
  • 建议：把合法值收敛为一处常量（例如在 KVCMPublisherUtils.h 暴露 kKVCacheEventPublisherTypeKvcm 与一个归一化+校验函数），Python 侧 choices 与文档表格引用同一来源；消费侧在比较前做 trim/tolower 归一化。同时对 ConfigModules.h 跑一次 clang-format（或本地 pre-commit），让新块的等号列由工具决定，避免后续任何人改动该文件时被动带上无关格式化 diff。
• reuseParticipatingGroupIds override 与基类实现语义等价，属重复维护面 @ rtp_llm/cpp/cache/HybridKVCacheAllocator.cc:76
  • 建议：删除该 override 与 HybridKVCacheAllocator.h 中的声明，统一走基类实现；若确实担心未来 kv_cache_groups_ 与 topology 顺序解耦，请把该假设写成基类内的断言或在 override 注释中说明它防的是哪种未来变化，而不是留一份等价副本。initCacheEventPublisher() 改为直接调用 config_.groupBlockSizeBytesSnapshot()。
• 接入层存在冗余 reset、日志级别不一致与缺失的顺序约束注释 @ rtp_llm/cpp/cache/KVCacheManager.cc:711
  • 建议：把 :711 降为 WARNING 与其余禁用出口一致；删除 :718、:773、:787、:791 的冗余 reset()，统一由 stopCacheEventPublisher() 负责清理；在 stopCacheEventPublisher() 内加一行注释说明必须先 join worker 再清空 published_keys_，并在 :768 补充说明 setEventPublisher() 必须先于 start() 调用，以便 worker 的首个快照包含 attach 时回填的既有 key。
• metrics 线程启动位置的注释与实际依赖不符，并顺带改变了 connector 初始化顺序 @ rtp_llm/cpp/cache/KVCacheManager.cc:280
  • 建议：删除关于 publisher 指针稳定性的错误注释；如需保留重排，改为写明真实理由（coordinator 与 publisher 初始化均可能抛异常，放在起线程之前可避免异常路径下遗留未 join 的 metrics 线程），并在 commit message 中说明该顺序调整。若后续按前述 finding 把 publisher status 接入 metrics 线程，则该注释可改为届时真实成立的约束。
• 文档「bounded non-blocking enqueue」未反映溢出路径会在 cache 锁内取发布器互斥量并唤醒 worker @ docs/backend/kv_cache_event_publisher.md:12
  • 建议：把 :12 调整为「正常路径为无锁有界入队；队列溢出时会额外获取一次发布器内部等待锁以唤醒 worker（不阻塞在 I/O 上）」，让读者能据此评估极端负载下缓存关键区的抖动来源。实现侧可仅在队列由未满转为满的边沿触发 wake()（或按时间窗节流），或让 workerLoop 在未注册状态下也周期性 discardPending()，使队列不会长期满载。
• 文档缺少快照 fencing 载荷说明与内部固定参数、快照体量、关停耗时 @ docs/backend/kv_cache_event_publisher.md:25
  • 建议：二选一并保持一致：要么把 snapshot.version（可选加 generation）写入 block_snapshot 载荷，让文档声明的 fencing 真正可实施；要么删除该要求，改为说明「客户端单 worker 串行保证顺序，服务端只需幂等的整体替换」，并删掉仅为日志而贯穿三层的 version 透传。同时在 Semantics 补一段量化说明（含「本版本除 endpoint 外均为硬编码」、最坏陈旧窗口 5 分钟叠加退避、快照一次携带全部已发布 key、关停可能等待一次 in-flight 请求）。
• 文档 pickle 兼容方向表述含糊，未说明旧版本读取新布局会直接抛错 @ docs/backend/kv_cache_event_publisher.md:44
  • 建议：改为明确方向性描述：新版本可读 43/54/57 旧布局，因此升级可滚动进行；旧版本读取 62 元素 state 会抛 Invalid state!，因此回滚必须整组进行。同时保留「新增字段必须追加在 event 字段块之后并同步更新本文档元素个数」的约束提示。
• 阻塞型测试替身未覆写 cancel，仍存在一处断言早退会退化为整目标挂死的窗口 @ rtp_llm/cpp/cache/events/test/KVCacheEventPublisherTest.cc:622
  • 建议：给 BlockingReporter 覆写 cancel()，把 release_mutation_/release_snapshot_ 一并置真并 notify_all()，使任何早退路径下的 stop() 都能解除阻塞；或把 :622 改为 EXPECT_EQ 并在其后无条件 releaseMutation()。前者更彻底，可让所有阻塞用例天然免疫断言早退。
• 部分异步测试断言依赖线程调度，另有未使用的重复实现辅助方法 @ rtp_llm/cpp/cache/events/test/KVCacheEventQueueTest.cc:78
  • 建议：把 :90 的最终断言改为带非零超时的等待（如 wait_for(std::chrono::seconds(2))），或循环退出后先再做一次 queue.wake() 再以秒级超时断言，使失败原因可区分。删除未使用的 waitForOccurrenceCount；若确需该能力，让它复用 countOccurrences（把后者上移到 reporter 定义之前）而非重复实现，并至少有一个用例调用它。
• 新增测试 target 的 size/timeout 与其异步等待预算自相矛盾，队列测试则完全未声明 @ rtp_llm/cpp/cache/events/test/BUILD:20
  • 建议：把 kv_cache_event_publisher_test 改为 size = "medium" 或显式 timeout = "moderate"，使单用例 10s 预算与 target 超时相容、失败以断言而非超时暴露；给 kv_cache_event_queue_test 显式声明 size/timeout 以反映其多线程与数据量，避免两个同类 target 依赖不同的隐式默认值。若希望保留 60s 上限，则应把 kAsyncTestTimeout 下调到 2~3s 并降低 32 轮竞态循环。
• pickle 契约测试的魔法常量缺少同步说明，且存在一条空转用例与一行不可能生效的赋值 @ rtp_llm/config/test/kv_cache_config_pickle_test.py:31
  • 建议：在两个常量上方补一行说明：新增 KVCacheConfig 字段时必须同步更新常量并复核 __setstate__ 的 size 白名单与索引。57 元组用例改为先用 KV_CACHE_EVENT_FIELD_VALUES 把 5 个事件字段设为非默认值再截断，使「回落默认值」成为可失败断言，并顺带断言前 57 项被原样保留以覆盖索引错位。删除 :80 这行无效赋值，或改为给 DISK_CACHE_FIELDS 每项赋非默认值并断言前 43 项被原样保留。
• 测试数据 NamedTuple 的 expected_value 字段冗余、类型被弱化，且消费侧混用位置解包 @ rtp_llm/config/test/kv_cache_event_test_values.py:8
  • 建议：删除 expected_value，让两个测试统一使用 raw_value（若确为未来非字符串参数预留，请收窄为具体联合类型并注明原因）；并把 server_args_test.py:489-506 统一改为 for case in KV_CACHE_EVENT_ENV_CASES: 配合具名属性访问，去掉 _ 占位。
• 跨包共享的测试常量 py_library 未标记 testonly @ rtp_llm/config/test/BUILD:17
  • 建议：为该 py_library 增加 testonly = True；若后续还有更多跨包共享的测试常量，考虑集中到一个专用测试夹具包，避免 config/test 逐渐演变成隐式的公共依赖节点。

Checklist Findings (18 fail / 55 total)

General Principles Checklist

• [6.1] Architecture — 依赖方向：无循环依赖/跨层惊喜 → issue 跨包共享的测试常量 py_library 未标记 testonly
  新增的 py_library(name = "kv_cache_event_test_values")（:17-23）把测试常量表从 rtp_llm/config/test 导出给 //rtp_llm/server/server_args/test（visibility 已合理收窄到单包，且该包 BUILD:8 确实依赖它），但未声明 testonly = True。这意味着在 visibility 允许范围内非测试目标也可依赖它，测试夹具有机会渗入生产依赖图；Bazel 中同类做法一般会显式标记 testonly，让依赖方向由构建系统而非约定来保证。
• [6.1] Architecture — 兼容性：外部 HTTP/RPC API、持久数据、配置、环境迁移安全 → issue pickle 契约测试的魔法常量缺少同步说明，且存在一条空转用例与一行不可能生效的赋值
CURRENT_STATE_SIZE = 62（:31）与 EVENT_FIELD_OFFSET = 57（:32）是有意的兼容性绊线，但文件内没有说明「为何允许它们随字段增长而失败、失败后应如何更新」；按 ConfigInit.cc:665-666 的指引在 event 块之后追加字段时，test_event_pickle_block_follows_declaration_order 的 [57:] 切片会失败——一次完全正确的改动却得到失败信号。test_legacy_57_element_state_uses_event_defaults（:91）只把 source 的 3 个 dsv4 字段设为非默认值，5 个事件字段仍是默认值，随后截断到 [:57] 再断言 restored 等于默认值，该循环（:105-106）必然通过，用例名承诺的语义未被验证。:80 的 source.kv_cache_event_publisher_type = "kvcm" 位于截断到 43 元素之前，索引 57 不进入 legacy_state
• [6.1] Architecture — 分层边界：新概念在正确层级，不泄漏内部 → issue 跨包共享的测试常量 py_library 未标记 testonly
  新增的 py_library(name = "kv_cache_event_test_values")（:17-23）把测试常量表从 rtp_llm/config/test 导出给 //rtp_llm/server/server_args/test（visibility 已合理收窄到单包，且该包 BUILD:8 确实依赖它），但未声明 testonly = True。这意味着在 visibility 允许范围内非测试目标也可依赖它，测试夹具有机会渗入生产依赖图；Bazel 中同类做法一般会显式标记 testonly，让依赖方向由构建系统而非约定来保证。
• [6.1] Architecture — 可观测性：日志/指标/超时可操作、非噪声 → issue 新增测试 target 的 size/timeout 与其异步等待预算自相矛盾，队列测试则完全未声明
kv_cache_event_publisher_test 声明 size = "small"（:20）+ timeout = "short"（:25），经 cc_test_wrapper 透传后 target 硬超时 60s；但该文件有 13 个用例，kAsyncTestTimeout = 10s（KVCacheEventPublisherTest.cc:19），其中 8 个含 1~3 次 10s 级等待，ConcurrentStartAndStopAlwaysLeavesJoinedWorkers 还跑 32 轮建对象 + 双线程竞态 + join。真实缺陷下只需约 6 次等待耗尽即先撞 target 超时，得到的是不含失败用例名的 timeout 而非精确的 waitForBody 失败点。反向不一致同样存在：更重的 kv_cache_event_queue_test（:5-16）完全不声明 size/timeout，其压测用 4 个自旋 producer 推 2 万条事件并以 10s 硬 wall-clock 作失败判据。
• [6.1] Architecture — 回滚路径：风险行为存在运维回滚手段 → issue 文档 pickle 兼容方向表述含糊，未说明旧版本读取新布局会直接抛错
:44-45 先说支持 43/54/57 legacy 布局，紧接又说「必须一起升级或一起回滚」，两句语义相互抵消，读者无法判断哪个方向安全。实现是单向兼容：ConfigInit.cc:598 白名单为 43/54/57/62，新 build 可读旧 state（:645/:658/:664 三级条件填充）；旧 build 白名单不含 62，读到 62 元素 state 会抛 Invalid state!。触发条件：灰度期仅回滚部分进程。
• [6.1] Architecture — 状态不变量：创建/更新/失败/重试/回滚路径有效 → issue 接入层存在冗余 reset、日志级别不一致与缺失的顺序约束注释
  三处小问题集中在同一函数对：（1）:711 的「无 group 参与前缀复用」用 RTP_LLM_LOG_ERROR，而语义相同的其余 6 条禁用出口（:686/:690/:698/:704/:717）都用 WARNING，级别不一致会误导告警规则；（2）:718、:773、:787、:791 的 cache_event_publisher_.reset() 均冗余——:718 处发布器尚未创建，其余三处 stopCacheEventPublisher()（:797-806）末尾已 reset 两个成员；（3）stopCacheEventPublisher() 内 stop→detach 顺序是硬约束却无注释：setEventPublisher() 会清空 published_keys_（SharedBlockCache.cc:472），而 worker 的快照回调读的正是 published_keys_（:455-465），若为「先摘除更安全」调换两行，worker 在 join 前可能把空集合当作权
• [6.1] Architecture — 错误语义：fail-fast/retry/fallback/silent 行为显式 → issue 文档「bounded non-blocking enqueue」未反映溢出路径会在 cache 锁内取发布器互斥量并唤醒 worker
  文档 :12 称「Cache mutations only attempt a bounded non-blocking enqueue」。正常路径确实无锁（KVCacheEventQueue.cc:18-39 只做 CAS + notify_one()）。但 updatePublishedStateLocked() 是在持有 SharedBlockCache::mu_ 时调用 tryPublish（SharedBlockCache.cc:752-768），而队列满时 tryPublish 会走 queue_.wake()（KVCMPublisher.cc:481），后者取 wait_mu_ 并 notify_all()（KVCacheEventQueue.cc:74-80）。反向持锁不存在（worker 在 waitPop 内的 wait_mu_ 作用域早于 snapshot_provider 调用结束），故无死锁；但 workerLoop 在 registerNode() 持续失败时 continue（`:634-
• [6.1] Quality — Commit 原子、message 与行为匹配 → issue metrics 线程启动位置的注释与实际依赖不符，并顺带改变了 connector 初始化顺序
:280-281 注释写道「Start metrics only after the publisher pointer becomes stable. The destructor joins this thread before stopping/resetting the publisher.」，但 reportMetricsLoop()（:830-857）只访问 metrics_reporter_ 与 allocator_，完全不读 cache_event_publisher_ 或 publisher_shared_cache_，注释声称的顺序约束并不存在（与「状态无指标出口」那条 finding 互为印证）。同时本次重排真正改变的行为是 initConnectorCoordinator()（:278）被前移到 metrics 线程启动之前，该实质变化未被记录，属逻辑变更混入看似纯注释的改动。
• [6.1] Quality — 逻辑变更未混入无关格式化 → issue metrics 线程启动位置的注释与实际依赖不符，并顺带改变了 connector 初始化顺序
:280-281 注释写道「Start metrics only after the publisher pointer becomes stable. The destructor joins this thread before stopping/resetting the publisher.」，但 reportMetricsLoop()（:830-857）只访问 metrics_reporter_ 与 allocator_，完全不读 cache_event_publisher_ 或 publisher_shared_cache_，注释声称的顺序约束并不存在（与「状态无指标出口」那条 finding 互为印证）。同时本次重排真正改变的行为是 initConnectorCoordinator()（:278）被前移到 metrics 线程启动之前，该实质变化未被记录，属逻辑变更混入看似纯注释的改动。
• [6.1] Software Engineering — DRY：重复非平凡逻辑被抽取或显式复用 → issue 部分异步测试断言依赖线程调度，另有未使用的重复实现辅助方法
WakeInterruptsEmptyWaitPop（:78-92）在最多 1s 的循环里反复 wake()，退出循环后立即 ASSERT_EQ(std::future_status::ready, waiter.wait_for(0ms))（:90）。waitPop 自身超时为 2s（:81），因此在高负载 CI 上若 std::async 线程延迟超过 1s 才被调度，全部 wake() 都发生在它捕获 wake_generation 之前，该线程会整整等 2s，1s 处的断言必失败，且无法区分「唤醒语义坏了」与「线程未被调度」。另 KVCacheEventPublisherTest.cc:58 的 RecordingReporter::waitForOccurrenceCount 定义后全文件无任何调用点，其出现次数统计逻辑又在自由函数 countOccurrences（:190）中重复实现了一遍。
• [6.1] Software Engineering — KISS/YAGNI：无投机性抽象 → issue 测试数据 NamedTuple 的 expected_value 字段冗余、类型被弱化，且消费侧混用位置解包
KVCacheEventEnvCase 同时定义 raw_value: str 与 expected_value: object，但 5 个用例中两者字符串完全相同；由于这批参数全为 type=str，env 原值与期望值不可能分叉，expected_value 不承载信息，反而把类型放宽成 object，使 KV_CACHE_EVENT_FIELD_VALUES（:44-46）的值类型在 pyright 下退化为 object，削弱 pickle 测试中 assertEqual 的静态检查价值。消费侧风格也不统一：server_args_test.py:490 用 for env_name, _, raw_value, _ in ...、:501 用 for _, field_name, _, expected_value in ... 位置解包，而紧邻的 :510-523 用 case.env_name/case.field_name 具名访问——位置解包放弃了 NamedTuple 的抗重排能力，字段调序后会静默
• [6.1] Software Engineering — LSP：子类/重写保持基类契约 → issue reuseParticipatingGroupIds override 与基类实现语义等价，属重复维护面
  基类实现（KVCacheAllocator.cc:493-495）基于 config_.groupPoliciesSnapshot()，即按 topology group 顺序取 group.policy。override（:76-86）遍历 kv_cache_groups_ 调用 group->policy()，而 KVCacheGroup::policy() 返回的正是 cache_group_.policy；HybridTypeKVCacheAllocator 与 HybridPoolKVCacheAllocator.cc:105-143 都在 for gid in [0, group_nums) 内按 groupById(gid) 构造并 push_back（:122/:142），二者顺序与内容一一对应。因此 override 当前无行为差异，只多一次 policy 向量拷贝，并制造两份需同步维护的实现。同理 KVCacheManager.cc:735-739 手写的分组字节循环与 `CacheConfig.h:2
• [6.1] Software Engineering — OCP：本地扩展点优先于修改中心逻辑 → issue pickle 新增块用 t.size() == 62 精确匹配，与同函数既有 >= 惯例不一致
  同一 __setstate__ 内两个历史兼容块用 if (t.size() >= 54)（:645）与 if (t.size() >= 57)（:658），新增块却写成 if (t.size() == 62)（:664），而块内注释（:665-666）与 __getstate__ 注释（:589-590）都明确要求「append future fields after this block」。由于 :598 的白名单当前只接受 43/54/57/62，== 与 >= 目前完全等价，线上无实际问题；但一旦后续按注释追加第 63 个字段并把 63 加入白名单，== 62 分支即不再命中，5 个事件字段会在 spawn 到 backend 进程时静默回落为 "none"/空串，KVCacheManager.cc:682 随即直接 return，发布链路被彻底关闭且不抛异常。现有 pickle 测试硬编码 62，无法在该场景报警。
• [6.1] Tests — 分布式/跨平台变更有对应覆盖 → issue 发布器门控决策树与 reuseParticipatingGroupIds 虚派发零测试覆盖
initCacheEventPublisher()/stopCacheEventPublisher() 新增约 120 行，含 7 条互斥禁用出口（:682/:685/:689/:697/:703/:710/:716）、context 构造与 start() 失败回滚，其中 pp_size==1 && tp_rank==0 是同一 replica 内避免多 rank 重复注册同一 node、并在析构时重复发 HOST_DOWN 的唯一屏障。本 PR 在 rtp_llm/cpp/cache/test/BUILD 只新增 cache_group_publication_test（:187），覆盖面止于 CacheGroupType.h 两个纯函数；kv_cache_manager_test（BUILD:257）未做任何扩展；KVCacheAllocator::reuseParticipatingGroupIds()（:493）与 Hybrid override（`HybridKVCacheAllocator.cc:
• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue pickle 契约测试的魔法常量缺少同步说明，且存在一条空转用例与一行不可能生效的赋值
CURRENT_STATE_SIZE = 62（:31）与 EVENT_FIELD_OFFSET = 57（:32）是有意的兼容性绊线，但文件内没有说明「为何允许它们随字段增长而失败、失败后应如何更新」；按 ConfigInit.cc:665-666 的指引在 event 块之后追加字段时，test_event_pickle_block_follows_declaration_order 的 [57:] 切片会失败——一次完全正确的改动却得到失败信号。test_legacy_57_element_state_uses_event_defaults（:91）只把 source 的 3 个 dsv4 字段设为非默认值，5 个事件字段仍是默认值，随后截断到 [:57] 再断言 restored 等于默认值，该循环（:105-106）必然通过，用例名承诺的语义未被验证。:80 的 source.kv_cache_event_publisher_type = "kvcm" 位于截断到 43 元素之前，索引 57 不进入 legacy_state
• [6.1] Tests — 边界 case 覆盖（空、单元素、最大值） → issue pickle 契约测试的魔法常量缺少同步说明，且存在一条空转用例与一行不可能生效的赋值
CURRENT_STATE_SIZE = 62（:31）与 EVENT_FIELD_OFFSET = 57（:32）是有意的兼容性绊线，但文件内没有说明「为何允许它们随字段增长而失败、失败后应如何更新」；按 ConfigInit.cc:665-666 的指引在 event 块之后追加字段时，test_event_pickle_block_follows_declaration_order 的 [57:] 切片会失败——一次完全正确的改动却得到失败信号。test_legacy_57_element_state_uses_event_defaults（:91）只把 source 的 3 个 dsv4 字段设为非默认值，5 个事件字段仍是默认值，随后截断到 [:57] 再断言 restored 等于默认值，该循环（:105-106）必然通过，用例名承诺的语义未被验证。:80 的 source.kv_cache_event_publisher_type = "kvcm" 位于截断到 43 元素之前，索引 57 不进入 legacy_state

RTP-LLM Checklist

• [I] 代码质量 — 同一功能用统一工具函数 → issue 测试数据 NamedTuple 的 expected_value 字段冗余、类型被弱化，且消费侧混用位置解包
KVCacheEventEnvCase 同时定义 raw_value: str 与 expected_value: object，但 5 个用例中两者字符串完全相同；由于这批参数全为 type=str，env 原值与期望值不可能分叉，expected_value 不承载信息，反而把类型放宽成 object，使 KV_CACHE_EVENT_FIELD_VALUES（:44-46）的值类型在 pyright 下退化为 object，削弱 pickle 测试中 assertEqual 的静态检查价值。消费侧风格也不统一：server_args_test.py:490 用 for env_name, _, raw_value, _ in ...、:501 用 for _, field_name, _, expected_value in ... 位置解包，而紧邻的 :510-523 用 case.env_name/case.field_name 具名访问——位置解包放弃了 NamedTuple 的抗重排能力，字段调序后会静默

Python Static-First Checklist

• [P.A] 静态结构与类型纪律 — 数据容器用 dataclass/NamedTuple/TypedDict → issue 测试数据 NamedTuple 的 expected_value 字段冗余、类型被弱化，且消费侧混用位置解包
KVCacheEventEnvCase 同时定义 raw_value: str 与 expected_value: object，但 5 个用例中两者字符串完全相同；由于这批参数全为 type=str，env 原值与期望值不可能分叉，expected_value 不承载信息，反而把类型放宽成 object，使 KV_CACHE_EVENT_FIELD_VALUES（:44-46）的值类型在 pyright 下退化为 object，削弱 pickle 测试中 assertEqual 的静态检查价值。消费侧风格也不统一：server_args_test.py:490 用 for env_name, _, raw_value, _ in ...、:501 用 for _, field_name, _, expected_value in ... 位置解包，而紧邻的 :510-523 用 case.env_name/case.field_name 具名访问——位置解包放弃了 NamedTuple 的抗重排能力，字段调序后会静默

Strengths

• 门控策略保守且逐条可定位：KVCacheManager.cc:682-720 依次拒绝 warmup、未知 type、reuse_cache/enable_device_cache 关闭、pp_size!=1||tp_rank!=0、CP 分片、发布完备集为空、SharedBlockCache 缺失，每条都带独立日志。
• fail-open 落到实处：initCacheEventPublisher() 同时捕获 std::exception 与 ...，start() 返回 false 也走同一回退路径（:769-775），必定先 detach 再清指针，不会把 DEGRADED 发布器留在热路径上。
• 生命周期无引用环且顺序正确：stopCacheEventPublisher() 先 join worker 再清空 published_keys_，避免把空集合当作权威快照上报；weak_ptr 过期时抛异常由 worker 侧兜住。
• 发布完备集与既有 reuse 判定被刻意区分：cacheGroupPublishesPrefixChain()（CacheGroupType.h:161）用 active_tail_blocks == 0 排除 tail-sparse 组，并在 HybridKVCacheAllocator.cc:77-79 注释说明与 skipReuseCacheGroup() 的差异，配有含空输入边界的纯函数单测。
• 快照/增量时序无丢失：reconcile() 先 discardPending() 再取快照（KVCMPublisher.cc:546-564），discardPending() 只丢弃边界处已发布项（KVCacheEventQueue.cc:66-72），边界后入队的事件保留并在 ACK 后按序重放；失败时复用同一 payload 与 trace_id，并按 2 的幂次对持续脏态降噪告警。
• 增量批内 coalesceMutations() 按出队序做「每 key 保留末态」，注释明确写出「KVCM 在单请求内先应用全部 ADD 再 DELETE」这一外部约束（:312-315），并有对应用例钉住。
• BlockingReporter 用条件变量精确卡住 ADD/SNAPSHOT，把「快照在途期间的增量必须保序发出」「同键只发末态」「队列溢出转快照」转成不依赖 sleep 的确定性用例；退避断言只取下界，留足 CI 余量。
• pickle 契约由可执行测试锁定：CURRENT_STATE_SIZE=62/EVENT_FIELD_OFFSET=57 配合 test_unknown_state_sizes_are_rejected（7 种非法长度必须抛 Invalid state），把「新增字段须同步白名单与索引」从注释升级为会失败的测试。
• 依赖方向单向无环：events/BUILD 三个 target 只依赖 core_utils/rapidjson/curl，不回指 cache；kv_cache_event_queue 的 visibility 精确收窄到两个包。
• 三个新增 CPU 测试目标均未声明 exec_properties={'gpu':'H20'}，与同目录 GPU 用例区分得当，不占 GPU 执行槽位；test/BUILD 补上 data = ["//:th_transformer_config"] 是对既有缺失的实质修正。

[LLLLKKKK]

AI Code Review - PR #1340

Status: LGTM

Summary: P0/0 · P1/0 · P2/12 · P3/17

Reviewed: commit 3901c632225b · 2026-08-28 18:10 UTC+8

lgtm ready to ci

Non-blocking Suggestions

P2

• 注册到 KVCM 的 hbm spec_size_bytes 汇总了非 HBM 与不参与发布的 cache group @ rtp_llm/cpp/cache/KVCacheManager.cc:742
  • 建议：把 group_block_size_bytes 的遍历范围改为 reuse_group_ids（或至少排除非 DEVICE placement 的组），与 setEventPublisher() 传入的完整性集合保持同一口径；并在 KVCacheEventPublisherContext::spec_size_bytes（KVCacheEventPublisherConfig.h:32）上补注释明确单位是「单 rank 载荷字节」还是「整机物理占用字节」——注册 payload 已单独携带 use_mla/tp_size/dp_size/pp_size（KVCMPublisher.cc:219-226），若消费侧会再换算则不应预乘。补一个 hybrid + DSV4 pinned-CPU 配置的单测固定该数值。
• 发布器装配门控决策树与两个 reuseParticipatingGroupIds 实现零测试覆盖 @ rtp_llm/cpp/cache/KVCacheManager.cc:679
  • 建议：在已存在的 kv_cache_manager_test（cache/test/BUILD:256-271，已带 mock_allocator_lib 且 test_copts 含 -fno-access-control）补参数化用例：分别以 publisher_type 取 none/未知值、reuse_cache=false、enable_device_cache=false、tp_rank=1、pp_size=2、CP 分片、空 reuse group 构造并 init()，断言 init() 成功且 publisher 未安装；happy path 断言 required_group_ids 等于期望 gid 列表、spec_size_bytes/block_size_tokens/location_uri 取值正确；再补一条 start 失败后 publisher 已解绑的回滚用例。同时在 hybrid 与 single-type allocator 测试各补一条 reuseParticipatingGroupIds() 断言，覆盖 FULL-only 与 FULL+LINEAR/SWA 两种拓扑。若不便在 GPU target 中测，可把 resolveKVCacheEventInstanceGroup/aggregateKVCacheEventSpecSizeBytes 提为自由函数放进 CPU-only target。
• instance_group 回落到字面量 default，使非空校验不可达并引入跨部署分组冲突 @ rtp_llm/cpp/cache/KVCacheManager.cc:726
  • 建议：在启动成功日志中补上解析后生效的 instance_group、manager_endpoint 与 spec_name；当 kv_cache_event_instance_group 为空而使用回落值时额外打一条 WARNING 说明回落来源。若产品语义要求 kvcm 必须显式指定分组，则把该字段纳入下述解析期联合校验并在装配前做一次显式非空校验，让 isConfigValid() 的检查真正可达，而不是接受一个与 remote connector 共享的通用默认分组名。
• 多 DP 副本共用 host_ip_port 时 KVCM host 状态被静默互相覆盖，dp 维度未参与身份构造 @ rtp_llm/cpp/cache/KVCacheManager.cc:729
  • 建议：dp_rank 已在 KVCacheEventPublisherContext（KVCacheEventPublisherConfig.h:36）中，建议直接把它拼进身份，如 location_uri = "rtp-llm://<host_ip_port>/hbm/dp<dp_rank>"，或为空时按默认 IP + dp_rank 派生（仓库已有类似派生做法），使唯一性由代码保证而非运维手工保证；若维持现契约，至少在 dp_size > 1 时以 ERROR 级别打印 (dp_rank, host_ip_port) 便于碰撞排查，并把唯一性约束与违反后果写进 --kv_cache_event_host_ip_port 的 help 文本。
• 发布器运行状态无指标出口，头文件注释声称的 metrics 导出并不存在 @ rtp_llm/cpp/cache/events/KVCacheEventPublisher.h:18
  • 建议：在 reportMetricsLoop() 中读取 cache_event_publisher_->status()，把 state（数值枚举）、queue_size、dropped_count 增量上报为 kmonitor 指标，并在文档新增 Observability 一节列出 PublisherState 各取值含义（含 DEGRADED 常见成因）与 dropped_count 解读方式、告警阈值建议。若本次不接指标，请把 :18 的注释改为「预留供后续导出指标」，不要在头文件里声明一个尚不存在的可观测契约。
• publisher_type 的 choices 校验在 CLI+env 混合路径被绕过，非法取值静默降级为关闭发布器 @ rtp_llm/server/server_args/kv_cache_group_args.py:46
  • 建议：不要依赖 argparse 的 choices 兜底这条新契约：改用 type= 传入一个做归一化 + 白名单校验的转换函数（action.type 在 env 回填路径会被调用，抛 argparse.ArgumentTypeError 会被 server_args.py:364-365 转成 self.error），或在 init_kv_cache_group_args 之后做一次显式白名单校验并 fail-fast。同时补一条混合模式负例用例（sys.argv=["prog","--model_type","qwen"] + KV_CACHE_EVENT_PUBLISHER_TYPE=KVCM）把期望行为钉死。若判定该缺口应普遍修复，可在 EnvArgumentParser 的 env 回填分支统一补 action.choices 校验，对所有带 choices 的参数同样有效。
• 选择 kvcm 时缺少必填伴随字段的解析期联合校验，误配只表现为两条 WARNING @ rtp_llm/server/server_args/kv_cache_group_args.py:50
  • 建议：在 init_kv_cache_group_args 之后的参数后处理阶段增加联合校验：kv_cache_event_publisher_type == "kvcm" 时 kv_cache_event_manager_endpoint、kv_cache_event_instance_id、kv_cache_event_host_ip_port 必须非空，否则 parser.error(...) fail-fast，把「配了但没生效」前移到启动阶段；C++ 侧现有 WARNING 降级路径保留作为分布式兜底。若产品上确实要保留「配置不全则降级但不影响推理」，请至少把 KVCacheManager.cc:770 与 KVCMPublisher.cc:445 提到 ERROR 级并配合上一条 finding 的状态指标，让运维能直接观测到「已开启但未生效」。
• 文档声称的发布完备性语义比实现更宽，hybrid 下已发布 key 会高估可复用前缀 @ docs/backend/kv_cache_event_publisher.md:8
  • 建议：二选一：（1）与 PP/CP 门禁一致，检测到存在 enable_prefix_reuse && active_tail_blocks > 0 的组时直接禁用发布并 WARNING，把「不支持混合 tail-sparse 模型」显式化；（2）保留当前行为，但把文档该句改为「仅要求所有能形成完整块链的稠密 reuse group 完整」，并在文档与 cacheGroupPublishesPrefixChain() 注释中同时写明「混合模型下宣告长度可能超过实际可复用长度」，便于 KVCM 侧路由策略做折扣。
• 文档未列出 reuse_cache / enable_device_cache 前置条件，按文档配置会静默不生效 @ docs/backend/kv_cache_event_publisher.md:41
  • 建议：在 Configuration 段增加 Prerequisites 小节，列出完整前置条件：reuse_cache=1（可链接同目录 reuse KV cache 文档）、enable_device_cache=1、tp_rank=0、pp_size=1、非 CP 分片、存在参与 prefix reuse 的稠密 cache group；并说明不满足时的表现（发布器不启动、仅 WARNING、推理不受影响）与自查日志关键字（如 "publisher disabled because device cache reuse is disabled"）。
• setEventPublisher 的存量回填分支在唯一生产调用点不可达且零测试覆盖 @ rtp_llm/cpp/cache/SharedBlockCache.cc:476
  • 建议：若确认「安装时缓存已非空」不是当前需求，按 YAGNI 删除该回填循环，仅保留 published_keys_.clear()；若要保留（例如为将来热挂载留口），补一条用例：先 put 若干完整 key 与不完整 key 再安装 publisher，断言 logicalCacheSnapshot().cache_keys 只含完整 key、publisher->events 为空（回填不应补发 ADD），随后对既有完整 key 再 put 一次也不产生新事件；同时补一条 detach（传 nullptr）后 mutation 不再产生事件的用例。
• isConfigValid 12 个条件只覆盖 instance_id，「kvcm + endpoint 为空」这条最常见误配零覆盖 @ rtp_llm/cpp/cache/events/test/KVCacheEventPublisherTest.cc:257
  • 建议：把该用例改为参数化：对 instance_group/instance_id/host_ip_port/model_name/dtype/spec_name/location_uri 逐个置空、对 block_size_tokens/spec_size_bytes 置 0，各断言 start() 返回 false、状态为 DEGRADED、tryPublish 返回 NOT_RUNNING 且 reporter 无请求；另补一条不注入 reporter、仅 manager_endpoint 为空的用例，覆盖 reporter_/snapshot_reporter_ 未构造这条独立分支。
• 「默认不外联」这条安全不变量无任何断言 @ rtp_llm/config/test/kv_cache_config_pickle_test.py:71
  • 建议：增加显式断言：KVCacheConfig() 的 kv_cache_event_publisher_type == "none" 且其余四个 endpoint/identity 字段为空串；并补一条「不设置任何 KV_CACHE_EVENT_* env 时 py_env_configs.kv_cache_config 保持默认关闭」的用例。

P3

• pickle 新增块用 t.size() == 62 精确匹配，与同函数既有 >= 惯例不一致 @ rtp_llm/cpp/pybind/ConfigInit.cc:664
  • 建议：将 :664 改为 if (t.size() >= 62)，与 :645/:658 保持同一写法，使「追加字段只需改 __getstate__ 尾部 + :598 白名单」成为不需额外记忆的安全操作；如需严格校验可引入 constexpr size_t kStateSizeV4 = 62; 一类版本常量并统一用 >=。另把 :589/:665 注释与测试名 test_event_pickle_block_follows_declaration_order 中的 "declaration order" 改为 "append order"（ConfigModules.h:206-211 把 event 块声明在 reco_* 之前，而 tuple 中 reco_* 位于 22-41、event 位于 57-61，实际遵循追加顺序），并去掉 "unreleased" 这类时效性描述；建议再补一条「构造 63 元素 state 仍能还原事件字段」的前向兼容用例把该约束固化。
• 接入层存在冗余 reset、死代码与日志级别不一致 @ rtp_llm/cpp/cache/KVCacheManager.cc:711
  • 建议：删除 :718、:773、:787、:791 四处冗余/死 reset，让 stopCacheEventPublisher() 成为唯一清理入口，并在该函数上方补一行注释说明「必须先 stop 再解绑再 reset」的顺序约束；把 :711 的日志级别与其余门禁统一为 WARNING（或反之统一提级并说明理由）。
• metrics 线程启动位置的注释与实际依赖不符，并顺带改变了 connector 初始化顺序 @ rtp_llm/cpp/cache/KVCacheManager.cc:280
  • 建议：若不打算在 metrics 线程中接入 publisher 状态上报，删除或改写 :280-281 注释为真实约束（metrics 线程依赖 allocator_/coordinator_ 已就绪）；若按上文 observability finding 接入 status()，则该注释成立并应补充「析构先 join 再 stop」的原因。另建议在 commit message 中显式说明 connector 初始化顺序调整及其修复的竞态，便于后续 bisect。
• 快照数据被冗余全量拷贝一次，且 group 字节循环未复用已有的 groupBlockSizeBytesSnapshot @ rtp_llm/cpp/cache/KVCacheManager.cc:759
  • 建议：把 const auto logical_snapshot 去掉 const 并改为 snapshot.block_keys = std::move(logical_snapshot.cache_keys)，消除第二次拷贝；group_block_size_bytes 改为调用 config_.groupBlockSizeBytesSnapshot()（若按上文改为只统计 reuse group，则在其结果上按 gid 过滤）。
• HybridKVCacheAllocator 的 reuseParticipatingGroupIds override 与基类实现语义等价 @ rtp_llm/cpp/cache/HybridKVCacheAllocator.cc:76
  • 建议：若确认 group->policy() 与 config_.groupPoliciesSnapshot() 恒等，直接删除该 override 由基类统一提供；若二者在某些初始化时序下可能不同（例如 group 构造后 policy 被覆写），请在 override 注释中写明该差异与必须重写的理由，并补一条对比两者输出一致性的断言。
• publisher type 合法值字面量在四处重复，且新增字段块的等号对齐与 clang-format 不一致 @ rtp_llm/cpp/config/ConfigModules.h:207
  • 建议：在 C++ 侧引入一个小的 enum class KVCacheEventPublisherType 与 parseKVCacheEventPublisherType()（返回 optional，未知值即失败），KVCacheManager 只与枚举比较；Python 侧的 choices 从同一份常量列表生成或至少在注释中互相引用，使取值域只有一个事实来源。并在提交前对 ConfigModules.h 跑一次 clang-format 以消除后续无关格式 diff。
• 文档「bounded non-blocking enqueue」未反映溢出路径会在 cache 锁内唤醒 worker、快照持锁做 O(N) 拷贝 @ docs/backend/kv_cache_event_publisher.md:12
  • 建议：把「非阻塞」限定到 mutation 的正常入队路径，并补充：队列饱和时每次变更额外做一次唤醒；周期快照会短暂持有 SharedBlockCache 锁，开销与当前可复用 key 数量成正比，超大 HBM 缓存实例启用前需评估该抖动。把「never affects allocation, eviction」改为「不改变分配/淘汰的功能行为」这类限定表述。实现侧可考虑在 logicalCacheSnapshot() 内先 swap/move 出数据再于锁外整理，缩短 mu_ 持有时间。
• 文档缺少与 KVCM 的 wire 契约说明，且 fencing 表述与实际载荷不符 @ docs/backend/kv_cache_event_publisher.md:25
  • 建议：新增一小段列出两条 route 名、完整事件类型（含 EVENT_NODE_REGISTER）、block_key 编码方式与 spec_name/location_uri/location_spec_infos[].size 的命名与口径规则，并声明这些字段属于与 KVCM 的兼容契约、任一侧变更需双侧同步与同步回滚；同时把 fencing 表述改为准确说明「客户端按内部 generation 保证快照与增量的先后关系，服务端需保证快照的原子替换与崩溃安全提交」。若确实需要服务端按版本号去重迟到快照，则应把 snapshot.version 写入 block_snapshot 载荷并补相应断言。另建议以小表列出 KVCacheEventPublisherConfig.h:12-19 的 8 个本版本不可调固定参数，据此给出「最坏情况 KVCM 侧 key 陈旧不超过一个快照周期」的结论。
• 文档 pickle 兼容方向表述含糊，未说明旧版本读取新布局会直接抛错 @ docs/backend/kv_cache_event_publisher.md:44
  • 建议：把该段改写为明确的方向性说明：新版本向后兼容 43/54/57 三种历史布局；旧版本读取 62 元素布局会直接抛 Invalid state! 并导致 backend 进程启动失败，因此升级与回滚必须整实例同批进行，不支持前后端跨版本混跑。
• 阻塞型测试替身未覆写 cancel，一处断言早退会退化为整目标挂死 @ rtp_llm/cpp/cache/events/test/KVCacheEventPublisherTest.cc:622
  • 建议：给 BlockingReporter 覆写 cancel()，在其中置位并 notify_all 释放所有阻塞的 post()，使析构路径始终可收敛；或把 :622-624 改为 EXPECT_* 并在函数出口用 RAII guard（析构中 releaseMutation()）保证无论断言结果如何都先解除阻塞。
• 部分异步队列测试断言依赖线程调度而非确定性同步 @ rtp_llm/cpp/cache/events/test/KVCacheEventQueueTest.cc:78
  • 建议：改为确定性同步：让消费侧先通过一个 std::promise/原子标志宣告「已进入 waitPop」，主线程等到该信号后只调用一次 wake()，再以较宽松的超时等待 future；或把 waitPop 的超时设得远大于测试窗口，使「未被唤醒」与「超时自然返回」在结果上可区分。
• 新增测试 target 的 size/timeout 与其异步等待预算自相矛盾，队列测试则完全未声明 @ rtp_llm/cpp/cache/events/test/BUILD:20
  • 建议：给 kv_cache_event_queue_test 显式声明 size = "medium" 并通过 tags/exec_properties 申报核数；把 kv_cache_event_publisher_test 的 timeout 放宽到 moderate；把测试内的 10s 常量提为统一的更宽松超时，并把判定条件从「绝对墙钟到点即失败」改为「一个采样窗口内 received.size() 无增长则失败」，以区分真实死锁与调度抖动。
• pickle 契约测试的魔法常量与 C++ 侧双份维护，EVENT_FIELD_OFFSET 承担两种语义 @ rtp_llm/config/test/kv_cache_config_pickle_test.py:31
  • 建议：把 legacy 长度单独命名为 LEGACY_DSV4_STATE_SIZE = 57 并在 :96 使用，与 EVENT_FIELD_OFFSET 解耦；EVENT_FIELD_OFFSET 改为由 CURRENT_STATE_SIZE - len(EVENT_PICKLE_FIELDS) 派生，43/54 两个历史边界用 len(DISK_CACHE_FIELDS) 表达，使这组测试只保留一个需人工维护的常量；删除 :80 那行无效赋值或在注释中说明其意图。
• 测试数据 NamedTuple 的 expected_value 字段冗余、类型被弱化，且消费侧混用位置解包 @ rtp_llm/config/test/kv_cache_event_test_values.py:8
  • 建议：在当前只有 str 直通字段的前提下去掉 expected_value，由 raw_value 单一字段驱动断言并让 KV_CACHE_EVENT_FIELD_VALUES 从它派生；待引入需类型转换的字段时再补回并给出明确类型标注。同时把 server_args_test.py:544,555 统一改为按名访问，并把两个 env 用例重复的断言体抽成私有辅助方法（保留两条用例以继续覆盖两条不同的 parser 路径）。
• 跨包共享的测试常量 py_library 未标记 testonly @ rtp_llm/config/test/BUILD:17
  • 建议：在该 py_library 上加 testonly = True，让「测试夹具不得进入生产依赖图」由构建系统强制而非仅靠 visibility 约定。
• shared_block_cache_test 依赖传递头文件而未显式声明 events target @ rtp_llm/cpp/cache/test/BUILD:174
  • 建议：在 block_cache_test_deps 或 shared_block_cache_test 的 deps 中显式加入 //rtp_llm/cpp/cache/events:kv_cache_event，与 cache_group_publication_test 的写法保持一致。
• snapshot 一致性令牌 version 在缓存侧与发布侧测试中都无断言 @ rtp_llm/cpp/cache/test/SharedBlockCacheTest.cc:83
  • 建议：在 PublisherTracksCompleteLogicalKeysOnly 中记录每次 put/remove 后的 logicalCacheSnapshot().version，断言其在发布转换时严格递增、在重复幂等 put 时保持不变、remove 后再次递增；在 PublisherReportsWholeChainEvictionDeletes 中断言链式驱逐后 version 增量与 DELETE 事件数一致。若后续把 version 纳入上报载荷，请同步在 publisher 测试中断言其被序列化。

Checklist Findings (17 fail / 55 total)

General Principles Checklist

• [6.1] Architecture — 依赖方向：无循环依赖/跨层惊喜 → issue shared_block_cache_test 依赖传递头文件而未显式声明 events target
SharedBlockCacheTest.cc:34-61 的 RecordingPublisher 直接实现 KVCacheEventPublisher 并使用 PublishResult/PublisherStatus/KVCacheEventType，这些符号来自 //rtp_llm/cpp/cache/events:kv_cache_event。但 shared_block_cache_test 的 deps = block_cache_test_deps（:36-47）中只有 //rtp_llm/cpp/cache，头文件靠 block_pool 本次新增的传递依赖（cache/BUILD:186）才可见。同包 cache_group_publication_test（:186-199）则正确显式声明了 :cache_group_type，两者风格不一致；一旦后续收敛该传递 dep，此测试会以头文件缺失的形式失败。
• [6.1] Architecture — 兼容性：外部 HTTP/RPC API、持久数据、配置、环境迁移安全 → issue 文档 pickle 兼容方向表述含糊，未说明旧版本读取新布局会直接抛错
  第 44-45 行只写「supports legacy 43-, 54-, and 57-element layouts plus the current 62-element layout. Processes exchanging this state must be upgraded or rolled back together.」，未点明兼容是单向的：新版本可读旧布局（ConfigInit.cc:645,658 的 >= 阶梯），但旧版本读到 62 元素 state 会命中其 :598 等价 guard 直接 throw std::runtime_error("Invalid state!")。这决定了灰度与回滚顺序（前后端必须同批回滚，不可只回滚 backend），是运维最需要的一句话，目前需要读 C++ 源码才能推断。
• [6.1] Architecture — 分层边界：新概念在正确层级，不泄漏内部 → issue 跨包共享的测试常量 py_library 未标记 testonly
kv_cache_event_test_values 作为 py_library 声明（:17-23），visibility 已收敛到 //rtp_llm/server/server_args/test:__pkg__，但缺少 testonly = True。同 BUILD 内其余目标都是 py_test（天然带 testonly）；该库是唯一一个可被非测试目标依赖的测试夹具，缺少标记时 Bazel 不会阻止生产目标误引入测试数据，一旦后续有人放宽 visibility，测试常量可被链入发布产物且无构建期报错。
• [6.1] Architecture — 可观测性：日志/指标/超时可操作、非噪声 → issue 文档「bounded non-blocking enqueue」未反映溢出路径会在 cache 锁内唤醒 worker、快照持锁做 O(N) 拷贝
  文档第 12-14 行称「Cache mutations only attempt a bounded non-blocking enqueue」「never affects allocation, eviction, readiness, or inference responses」。ACCEPTED 路径确为无锁有界环形队列，但两处成本未被覆盖：(1) updatePublishedStateLocked() 是在 mu_ 临界区内调用 tryPublish（SharedBlockCache.cc:752-768），而队列满时 tryPublish 会走 queue_.wake()（KVCMPublisher.cc:481），即溢出期间每次 cache 变更都在分配热路径锁内多做一次短临界区唤醒；(2) logicalCacheSnapshot() 在同一把 mu_ 内 reserve + 整段拷贝 published_keys_（SharedBlockCache.cc:455-462），且 `snapshot_interval_ms=
• [6.1] Architecture — 回滚路径：风险行为存在运维回滚手段 → issue 文档 pickle 兼容方向表述含糊，未说明旧版本读取新布局会直接抛错
  第 44-45 行只写「supports legacy 43-, 54-, and 57-element layouts plus the current 62-element layout. Processes exchanging this state must be upgraded or rolled back together.」，未点明兼容是单向的：新版本可读旧布局（ConfigInit.cc:645,658 的 >= 阶梯），但旧版本读到 62 元素 state 会命中其 :598 等价 guard 直接 throw std::runtime_error("Invalid state!")。这决定了灰度与回滚顺序（前后端必须同批回滚，不可只回滚 backend），是运维最需要的一句话，目前需要读 C++ 源码才能推断。
• [6.1] Architecture — 状态不变量：创建/更新/失败/重试/回滚路径有效 → issue 接入层存在冗余 reset、死代码与日志级别不一致
stopCacheEventPublisher()（:797-806）末尾已 reset cache_event_publisher_ 与 publisher_shared_cache_，但三个调用点（:773、:787、:791）都在其后再写一次 cache_event_publisher_.reset()，永远无效；:718 的 reset 位于该指针首次赋值（:766）之前，是死代码。另外 8 条门禁中只有「空 reuse group」用 RTP_LLM_LOG_ERROR（:711），其余七条同类「配置不满足 → 禁用发布」全部用 WARNING，语义等价却级别不一，会干扰按级别配告警。
• [6.1] Architecture — 错误语义：fail-fast/retry/fallback/silent 行为显式 → issue 文档「bounded non-blocking enqueue」未反映溢出路径会在 cache 锁内唤醒 worker、快照持锁做 O(N) 拷贝
  文档第 12-14 行称「Cache mutations only attempt a bounded non-blocking enqueue」「never affects allocation, eviction, readiness, or inference responses」。ACCEPTED 路径确为无锁有界环形队列，但两处成本未被覆盖：(1) updatePublishedStateLocked() 是在 mu_ 临界区内调用 tryPublish（SharedBlockCache.cc:752-768），而队列满时 tryPublish 会走 queue_.wake()（KVCMPublisher.cc:481），即溢出期间每次 cache 变更都在分配热路径锁内多做一次短临界区唤醒；(2) logicalCacheSnapshot() 在同一把 mu_ 内 reserve + 整段拷贝 published_keys_（SharedBlockCache.cc:455-462），且 `snapshot_interval_ms=
• [6.1] Quality — Commit 原子、message 与行为匹配 → issue metrics 线程启动位置的注释与实际依赖不符，并顺带改变了 connector 初始化顺序
:280-281 注释称「Start metrics only after the publisher pointer becomes stable. The destructor joins this thread before stopping/resetting the publisher.」，但 reportMetricsLoop()（:830-857）只访问 metrics_reporter_ 与 allocator_，从不读取 cache_event_publisher_，该依赖关系当前并不存在。同时本次把 initConnectorCoordinator() 一并移到 metrics 线程启动之前——这个顺序变化本身有益（消除了 coordinator_ 的既有数据竞争），但与本 PR 主题无关且未在注释或 commit message 中说明。
• [6.1] Quality — 逻辑变更未混入无关格式化 → issue publisher type 合法值字面量在四处重复，且新增字段块的等号对齐与 clang-format 不一致
"none"/"kvcm" 这组取值域散落在四处独立维护：ConfigModules.h:207 的默认值与行尾注释、kv_cache_group_args.py:46 的 choices、KVCacheManager.cc:682 的 == "none"、:685 的 != "kvcm"。新增第三种 publisher 类型时必须同步修改全部四处，遗漏其一即表现为「参数能传但功能不生效」，且该失效路径只有一条 WARNING。另 :207-211 新增块的 = 对齐到了下方 reco_* 块的列位置，而 .clang-format 的 AlignConsecutiveAssignments 不跨空行对齐（:212 为空行），pre-commit 重跑 clang-format 时该块会被重新排版，形成与本次改动无关的格式 diff。
• [6.1] Software Engineering — DRY：重复非平凡逻辑被抽取或显式复用 → issue pickle 契约测试的魔法常量与 C++ 侧双份维护，EVENT_FIELD_OFFSET 承担两种语义
CURRENT_STATE_SIZE = 62（:31）与 EVENT_FIELD_OFFSET = 57（:32）是对 ConfigInit.cc tuple 布局的手工镜像，二者存在 62 - 5 的可推导关系却各自硬编码；test_unknown_state_sizes_are_rejected 的拒绝集合（:110）也混用字面量与派生值。后续每加一个字段需同步 C++ 白名单、__getstate__ 顺序、本文件两个常量与拒绝列表共 4 处。另 EVENT_FIELD_OFFSET 在 :54 用作「事件字段块起始偏移」，在 :96 又被当作「legacy 57 元素状态长度」截断用，数值恰好相同但概念不同。:80 的 source.kv_cache_event_publisher_type = "kvcm" 因随后截断到 43 元素而对断言无任何影响。
• [6.1] Software Engineering — KISS/YAGNI：无投机性抽象 → issue 测试数据 NamedTuple 的 expected_value 字段冗余、类型被弱化，且消费侧混用位置解包
KVCacheEventEnvCase 同时定义 raw_value: str 与 expected_value: object，但 5 个用例两者逐字相同（:15/16、:21/22、:27/28、:33/34、:39/40）。这 5 个参数全是 type=str 直通字段，不存在类型转换，expected_value 未承载任何信息，object 标注还使消费侧 setattr/断言失去静态类型约束；该结构承诺的归一化维度（空串清空、endpoint 末尾斜杠、非法 host_ip_port 格式）一个用例都没覆盖。消费侧风格也不统一：server_args_test.py:544,555 按位解包，:564-577 与 kv_cache_config_pickle_test.py 按名访问；由于两值当前相同，字段顺序调整导致的错位不会被任何断言发现。
• [6.1] Software Engineering — LSP：子类/重写保持基类契约 → issue HybridKVCacheAllocator 的 reuseParticipatingGroupIds override 与基类实现语义等价
  基类实现为 reuseParticipatingGroupIdsFromPolicies(config_.groupPoliciesSnapshot())（KVCacheAllocator.cc:493-495），override 则遍历 kv_cache_groups_ 收集 group->policy() 后调用同一个自由函数（:80-85）。两者的 policy 来源都是同一份 CacheConfig 组策略，结果必然一致，等于把同一语义维护两遍；两个实现都没有直接单测（见上文覆盖缺口 finding），一旦其中一侧被改动，另一侧的行为漂移只会表现为「发布集合与实际 reuse 面不一致」这类静默偏差。
• [6.1] Tests — 分布式/跨平台变更有对应覆盖 → issue 发布器装配门控决策树与两个 reuseParticipatingGroupIds 实现零测试覆盖
initCacheEventPublisher()/stopCacheEventPublisher() 共约 120 行，含 8 条互斥门禁（:682 type、:685 未知 type、:689 reuse/device cache、:697 pp_size!=1||tp_rank!=0、:703 CP 分片、:710 空 reuse group、:716 SharedBlockCache、:769 start 失败回滚）与 2 个 catch 分支，全部静默 fail-open。全仓检索 initCacheEventPublisher/reuseParticipatingGroupIds 只命中生产代码与 CacheGroupPublicationTest.cc（后者仅测纯函数 reuseParticipatingGroupIdsFromPolicies），无任何用例构造 KVCacheManager 验证接线。:697 是「每 DP replica 只有一个发布者」的唯一执行点，一旦回退，多个 TP rank 会
• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue snapshot 一致性令牌 version 在缓存侧与发布侧测试中都无断言
logicalCacheSnapshot() 返回 snapshot.version = cache_event_version_（SharedBlockCache.cc:459），该计数在每次发布状态转换处自增（:762、:766），并由 provider 透传（KVCacheManager.cc:758）。但新增的 5 个 publisher 用例（:83/94/108/127/133）全部只断言 .cache_keys，从不断言 .version；唯一的版本断言 EmptyCacheKeepsLegacyVersion（:65-68）检查的是另一个字段 version_。若递增逻辑退化为恒定值，现有测试全绿。风险有限：该 version 当前只进日志、不进上报载荷，故定级 P3。
• [6.1] Tests — 边界 case 覆盖（空、单元素、最大值） → issue snapshot 一致性令牌 version 在缓存侧与发布侧测试中都无断言
logicalCacheSnapshot() 返回 snapshot.version = cache_event_version_（SharedBlockCache.cc:459），该计数在每次发布状态转换处自增（:762、:766），并由 provider 透传（KVCacheManager.cc:758）。但新增的 5 个 publisher 用例（:83/94/108/127/133）全部只断言 .cache_keys，从不断言 .version；唯一的版本断言 EmptyCacheKeepsLegacyVersion（:65-68）检查的是另一个字段 version_。若递增逻辑退化为恒定值，现有测试全绿。风险有限：该 version 当前只进日志、不进上报载荷，故定级 P3。

RTP-LLM Checklist

• [I] 代码质量 — 同一功能用统一工具函数 → issue 测试数据 NamedTuple 的 expected_value 字段冗余、类型被弱化，且消费侧混用位置解包
KVCacheEventEnvCase 同时定义 raw_value: str 与 expected_value: object，但 5 个用例两者逐字相同（:15/16、:21/22、:27/28、:33/34、:39/40）。这 5 个参数全是 type=str 直通字段，不存在类型转换，expected_value 未承载任何信息，object 标注还使消费侧 setattr/断言失去静态类型约束；该结构承诺的归一化维度（空串清空、endpoint 末尾斜杠、非法 host_ip_port 格式）一个用例都没覆盖。消费侧风格也不统一：server_args_test.py:544,555 按位解包，:564-577 与 kv_cache_config_pickle_test.py 按名访问；由于两值当前相同，字段顺序调整导致的错位不会被任何断言发现。

Python Static-First Checklist

• [P.A] 静态结构与类型纪律 — 字符串分发用 Enum/Literal → issue publisher type 合法值字面量在四处重复，且新增字段块的等号对齐与 clang-format 不一致
"none"/"kvcm" 这组取值域散落在四处独立维护：ConfigModules.h:207 的默认值与行尾注释、kv_cache_group_args.py:46 的 choices、KVCacheManager.cc:682 的 == "none"、:685 的 != "kvcm"。新增第三种 publisher 类型时必须同步修改全部四处，遗漏其一即表现为「参数能传但功能不生效」，且该失效路径只有一条 WARNING。另 :207-211 新增块的 = 对齐到了下方 reco_* 块的列位置，而 .clang-format 的 AlignConsecutiveAssignments 不跨空行对齐（:212 为空行），pre-commit 重跑 clang-format 时该块会被重新排版，形成与本次改动无关的格式 diff。

Strengths

• 门禁与 fail-open 覆盖完整：warmup、未知 type、reuse_cache/enable_device_cache 关闭、pp_size!=1/tp_rank!=0、CP 分片、空 reuse group、SharedBlockCache 缺失、start() 失败共 8 条路径均只禁用发布并保留推理（KVCacheManager.cc:679-794），未引入新的启动失败点。
• 发布完整性集合被单独抽成 cacheGroupPublishesPrefixChain()（CacheGroupType.h:161），并用注释说明为何不能复用 skipReuseCacheGroup()（后者接纳 tail-sparse LINEAR 组），避免了「几乎所有 key 都发不出去」的隐性缺陷；CacheGroupPublicationTest.cc 覆盖正向/反向/空输入/多组乱序。
• 生命周期与所有权干净：snapshot provider 持 weak_ptr、publisher_shared_cache_ 持 shared_ptr，无循环引用；lambda 内 lock() 失败抛异常由 reconcile()（KVCMPublisher.cc:550-558）捕获降级，无 terminate 风险。
• 事件语义实现精准：isLogicallyCompleteLocked() 只要求 required_group_ids_ 全部非空且可匹配，重复 put 与 LRU touch 因 published_keys_ 集合语义天然不产生事件（SharedBlockCache.cc:752-769）；coalesceMutations() 按 KVCM「先 ADD 后 DELETE」聚合语义取每 key 终态，避免 DELETE→ADD 倒置。
• reconcile() 用 pending_snapshot_report_ 缓存已构造的快照载荷，重试复用同一 payload 而不重复调用 provider，避免退避期反复回压缓存锁。
• 六层配置面同步无遗漏：ConfigModules.h:206-211 默认值、ConfigModules.cc:153-157 to_string、ConfigInit.cc:502-506 pybind、:591-595/:667-671 pickle 索引、libth_transformer_config.pyi:740-744 存根、kv_cache_group_args.py:41-81 CLI/env 逐项对齐，未出现「只加 pybind 忘了 pickle」缺口。
• pickle 兼容处理稳妥：__setstate__ 保留 43/54/57 并新增 62，kv_cache_config_pickle_test.py 对三种历史长度分别断言「旧字段保值 + 事件字段回落默认」，并有 7 个非法长度带 assertRaisesRegex(RuntimeError, "Invalid state") 的负向用例。
• publisher 测试覆盖真实失败语义：注册失败重试、snapshot provider 抛异常后恢复、快照重试复用同一载荷、指数退避只断言下界（慢机器不 flaky）、队列溢出后用快照恢复、同 key ADD/DELETE 合并为终态；RecordingReporter/BlockingReporter 用 condition_variable 精确复现时序而非 sleep。
• 队列并发测试同时校验序号单调与无重复投递，超时分支先 queue.stop() 再 join，使 while(...==FULL) yield() 自旋生产者能退出，不会挂死整目标。
• init() 把 initConnectorCoordinator()/initCacheEventPublisher() 提到 metrics 线程启动之前（KVCacheManager.cc:278-285），顺带消除了 reportMetricsLoop() 读取尚未赋值 coordinator_ 的既有数据竞争。
• 测试夹具 kv_cache_event_test_values.py 使 env 名 ↔ 字段名成为两个测试包的单一事实来源，visibility 精确收敛到唯一跨包消费方；cache_group_publication_test 与 kv_cache_config_pickle_test 未挂 GPU exec_properties，不占用稀缺执行资源。
• 文档主动记录了不支持矩阵（PP、CP 分片）、每 DP 副本需独立 KV_CACHE_EVENT_HOST_IP_PORT，以及 pickle 四种布局与「交换该状态的进程必须同步升级或回滚」，并已注册进 docs/index.rst toctree。

[wht21]

internal source has been updated, please review the changes!

[rtp-llm-review-bot]

PR #1340 第 4 轮评审 — LGTM

• 标题：feat(cache): add native KVCM cache event publisher（@putaopi7，open）
• head fb3451f86cd4 · base d5434acfa9eb · delta 5 文件 · discover 5/5 成功

无阻塞项

非阻塞发现（并集报告：单票也保留，降级不丢弃）

• [P2] 端点派生公式与文档/日志不一致：代码用 server_port（测试显示按 local_rank），文档/日志声称按 rank_id，多机 DP 下可能冲突 — rtp_llm/config/server_config_setup.py:572 · 票数 5/5

已确认修复（recheck）

• [P1] 62 元素 pickle 状态可能丢失 dsv4 三个字段（round-trip 测试未覆盖） — 第658行 dsv4 恢复块条件为 if (t.size() >= 57)（而非推测的 == 57），62 元素状态满足该条件，索引 54-56 的 dsv4 字段会被正确恢复，发现所述丢失问题不成立。
• [P1] KVCacheConfig 反序列化 62 元素状态时丢失 dsv4 字段 — 第658行反序列化分支为 if (t.size() >= 57)，62 元素状态同样会执行第660-662行读取 dsv4 三个字段，不再丢失。

本轮 KPI

{
 "reps": 5,
 "agentic_reps": 2,
 "diff_truncated": false,
 "patch_bytes": 11280,
 "coverage": 1.0,
 "shards": 1,
 "discover_ok": 5,
 "discover_fail": 0,
 "discover_attempts": 5,
 "clusters": 1,
 "synth_fail": 0,
 "confirm": {
  "candidates": 0,
  "to_block": 0,
  "confirm_fail": 0
 },
 "blocking_dedup_merged": 0,
 "fact_check": {
  "checked": 0,
  "hold": 0,
  "refuted": 0,
  "parse_fail": 0
 },
 "model": "whale/DeepSeek-V4-Pro-0813",
 "round_index": 4,
 "delta_files": 5,
 "full_files": 41,
 "new_findings": 1,
 "merged": 0,
 "recheck": {
  "fixed": 0,
  "still_open": 14,
  "cannot_substantiate": 0,
  "fail": 0
 },
 "blocking": 0,
 "blocking_on_unchanged": 0
}

本报告由 rtp-llm-agent-platform 自动生成，同一 PR 的后续轮次就地更新同一条评论。

---

_{rtp-llm-agent-platform review · 第 4 轮 · head fb3451f86cd4 · LGTM · 同一 PR 的结论就地更新这一条评论}

[LLLLKKKK]

AI Code Review - PR #1340

Status: LGTM

Summary: P0/0 · P1/0 · P2/10 · P3/1

Reviewed: commit fb3451f86cd4 · 2026-09-01 16:54 UTC+8

lgtm ready to ci

Non-blocking Suggestions

P2

• hybrid 下发布完整性只校验 FULL 组，高估可复用前缀深度 @ rtp_llm/cpp/cache/CacheGroupType.h:161
  • 建议：将所有启用前缀复用的组纳入逐 key 完整性判断，仅发布每组均可匹配的边界；补充 FULL+LINEAR/SWA、linear_step>1 的端到端复用测试，并同步修正文档语义。
• 注册到 KVCM 的 HBM spec 汇总了尾稀疏/非 DEVICE 组 @ rtp_llm/cpp/cache/KVCacheManager.cc:742
  • 建议：发布资格增加 memory_placement==DEVICE 校验，spec_size_bytes 仅汇总实际发布的 DEVICE 组；补充 DEVICE 与 HOST_PINNED 混合拓扑测试。
• 同步快照阻塞唯一 worker，心跳可被延迟至快照超时 @ rtp_llm/cpp/cache/events/KVCMPublisher.cc:568
  • 建议：将快照上传移至独立、可取消的 worker，或将快照超时严格约束在租约预算内；补充“快照阻塞期间心跳仍按周期发送”的测试。
• 多 DP 副本共享显式 host 标识仅告警不保证唯一 @ rtp_llm/config/server_config_setup.py:583
  • 建议：支持按 dp_rank 展开的模板/映射；无法证明唯一时拒绝启动或禁用 publisher，并补充多 DP 副本身份唯一性测试。
• 生产接线 initCacheEventPublisher 与 Curl 传输缺少集成测试 @ rtp_llm/cpp/cache/events/test/KVCacheEventPublisherTest.cc:351
  • 建议：新增真实 KVCacheManager+KVCMPublisher+本地 loopback HTTP 的集成测试，覆盖门控命中/跳过、注册、快照、增删、非 2xx、非法响应、超时与停止取消。
• 上报载荷缺少跨进程 fencing 身份 @ rtp_llm/cpp/cache/events/KVCMPublisher.cc:252
  • 建议：注册时获取 session epoch/boot ID 并在所有事件与快照 generation 中携带，明确服务端拒绝旧 epoch 的规则。
• 瞬时上报失败后停机会跳过 HOST_DOWN @ rtp_llm/cpp/cache/events/KVCMPublisher.cc:722
  • 建议：分别维护“曾成功注册”和“当前连接健康”两个状态；只要远端可能仍保留该节点，停机时就 best-effort 发送 HOST_DOWN。
• publisher_type 的 choices 校验在 CLI+env 混合路径被绕过 @ rtp_llm/server/server_args/kv_cache_group_args.py:46
  • 建议：env 回填后统一执行 choices 校验（复用 argparse 校验或显式比对），并补充非法 publisher 值与任意 CLI 参数混用的回归测试。
• 选择 kvcm 时缺少必填伴随字段的解析期联合校验 @ rtp_llm/server/server_args/kv_cache_group_args.py:42
  • 建议：在参数后处理阶段联合校验必填字段与拓扑前提，并在文档列出全部门控、降级行为与诊断日志。
• 头文件声称的 metrics 导出不存在，发布器运行状态无出口 @ rtp_llm/cpp/cache/events/KVCacheEventPublisher.h:18
  • 建议：在 manager 指标循环导出发布器 state、队列深度、accepted 与 dropped 计数；若暂不实现，则删除该误导性注释契约。

P3

• 阻塞型测试替身未覆写 cancel，一处断言早退会挂死整目标 @ rtp_llm/cpp/cache/events/test/KVCacheEventPublisherTest.cc:622
  • 建议：让 cancel() 释放所有等待，或用作用域清理守卫确保断言失败时也解除阻塞并 join。

Checklist Findings (8 fail / 55 total)

General Principles Checklist

• [6.1] Architecture — 兼容性：外部 HTTP/RPC API、持久数据、配置、环境迁移安全 → issue 选择 kvcm 时缺少必填伴随字段的解析期联合校验
kvcm 可与空 endpoint、空 instance_id、reuse_cache=False 或关闭 device cache 一起解析成功；消费端随后仅告警并关闭发布(KVCacheManager.cc:689-706)。参数 help 与文档也未完整列出 device cache、PP/CP、可发布组等前置门控，易出现“服务健康但始终无事件”。
• [6.1] Architecture — 可观测性：日志/指标/超时可操作、非噪声 → issue 头文件声称的 metrics 导出不存在，发布器运行状态无出口
  注释声明 PublisherState 值“exported through metrics and documented for alerting”(KVCacheEventPublisher.h:18)，但全仓 status() 仅测试引用；KVCacheManager 指标循环未读取 cache_event_publisher_->status()，未上报 state/queue_size/accepted/dropped。队列持续溢出或长期 DEGRADED 只能靠日志发现。
• [6.1] Architecture — 回滚路径：风险行为存在运维回滚手段 → issue 上报载荷缺少跨进程 fencing 身份
writeReportHeader(KVCMPublisher.cc:252-259) 仅写 trace_id/instance_id/host_ip_port；next_request_id_ 每次构造从 1 开始(KVCMPublisher.cc:758)，nextTraceId 仅含 dp_rank 与自增序号；buildSnapshotReport(KVCMPublisher.cc:377-401) 不携带内部维护的 version/generation。旧进程延迟的快照或 HOST_DOWN 跨重启到达时，服务端无法区分新旧发布者，与文档所述 snapshot fencing 不符。
• [6.1] Architecture — 状态不变量：创建/更新/失败/重试/回滚路径有效 → issue 阻塞型测试替身未覆写 cancel，一处断言早退会挂死整目标
BlockingReporter(KVCacheEventPublisherTest.cc:108) 仅覆写 post()，在 release_mutation_ 上阻塞，未覆写 cancel()。若 622/623 行 ASSERT_EQ 在 releaseMutation()(627) 前失败，析构触发 Impl::stop() 的 snapshot_reporter_->cancel()(KVCMPublisher.cc:496) 对该替身无效，worker_.join() 永久阻塞，退化为整目标超时。上轮 review 记为 P3，证据未变。
• [6.1] Architecture — 错误语义：fail-fast/retry/fallback/silent 行为显式 → issue 选择 kvcm 时缺少必填伴随字段的解析期联合校验
kvcm 可与空 endpoint、空 instance_id、reuse_cache=False 或关闭 device cache 一起解析成功；消费端随后仅告警并关闭发布(KVCacheManager.cc:689-706)。参数 help 与文档也未完整列出 device cache、PP/CP、可发布组等前置门控，易出现“服务健康但始终无事件”。
• [6.1] Tests — 新逻辑有聚焦单测 + 相关集成/smoke 测试 → issue 阻塞型测试替身未覆写 cancel，一处断言早退会挂死整目标
BlockingReporter(KVCacheEventPublisherTest.cc:108) 仅覆写 post()，在 release_mutation_ 上阻塞，未覆写 cancel()。若 622/623 行 ASSERT_EQ 在 releaseMutation()(627) 前失败，析构触发 Impl::stop() 的 snapshot_reporter_->cancel()(KVCMPublisher.cc:496) 对该替身无效，worker_.join() 永久阻塞，退化为整目标超时。上轮 review 记为 P3，证据未变。
• [6.1] Tests — 边界 case 覆盖（空、单元素、最大值） → issue 选择 kvcm 时缺少必填伴随字段的解析期联合校验
kvcm 可与空 endpoint、空 instance_id、reuse_cache=False 或关闭 device cache 一起解析成功；消费端随后仅告警并关闭发布(KVCacheManager.cc:689-706)。参数 help 与文档也未完整列出 device cache、PP/CP、可发布组等前置门控，易出现“服务健康但始终无事件”。

Python Static-First Checklist

• [P.G] 测试规范 — mock/fake/stub 不得替代本次声称覆盖的生产边界 → issue 生产接线 initCacheEventPublisher 与 Curl 传输缺少集成测试
  成功路径测试均注入 RecordingReporter/BlockingReporter(KVCacheEventPublisherTest.cc:351/602)，SharedBlockCache 测试也用 fake publisher。没有测试经过 KVCacheManager::initCacheEventPublisher()(KVCacheManager.cc:679) 的门控决策树与真实 CurlKVCacheEventReporter。因此配置门控、context 拼装、snapshot_provider 取数、URL/HTTP 状态码/非法响应/超时取消可同时失效而现有测试仍通过。状态机与 wire format 已有较好单测，故 P2。

Strengths

• 发布特性默认 publisher_type=none，初始化全程 try/catch fail-open，异常时推理保持可用。
• 缓存热路径仅依赖 KVCacheEventPublisher 抽象接口，传输、批量、重试、快照均隔离在 cache 之外。
• 单测覆盖较完整：队列并发/溢出、发布器状态机、注册失败恢复、快照重放、mutation coalesce、pickle 布局与配置绑定。

[wht21]

internal source has been updated, please review the changes!