[kvcm_ops] support instance_group revisit_interval_buckets (#303)

Author: wangxiyu191

docs/develop/README.md

@@ -168,6 +168,10 @@ grep -E "DoPut|DoGet|Alloc failed|Init|SdkWrapper" kv_cache_manager_client.log
 
 githooks中已经添加了C++等语言的格式化脚本，请确保开发环境安装了clang-format、autopep8、buildifier。（开发镜像均已预装）。
 
+## Proto 修改
+
+修改 `kv_cache_manager/protocol/protobuf` 下的 proto 定义时，请遵循 [Proto 文件修改指南](proto_modification_guide.md)，并同步完成其中列出的适配步骤（例如修改 AdminService 接口定义时需适配 `package/kvcm_ops` 运维 CLI）。
+
 ## 提交要求
 
 提交前检查和 commit message 格式见 [Commit 要求](commit_requirements.md)。

docs/develop/proto_modification_guide.md

@@ -153,6 +153,12 @@ bazel test //kv_cache_manager/xxxx:xxxx
 - RTP-LLM C++客户端: kv_cache_manager/client
 - vLLM等Python客户端：kv_cache_manager/py_connector
 
+### 8. （如果是修改AdminService）同步适配 kvcm_ops 运维 CLI
+
+- 工具位置：`package/kvcm_ops`
+- 若 InstanceGroup / Storage 等管理对象新增或变更字段，需同步更新对应的 Python 模型（如 `kvcm/instance_group/util.py`）的构造、校验与 JSON 序列化/反序列化，以及相关 create/update 命令参数。
+- 否则 kvcm_ops 的 update 流程（GET → 整体 PUT）会静默丢弃服务端已有字段，导致配置被意外清空。
+
 ## 注意事项
 
 1. **字段编号**：在proto文件中添加新字段时，使用递增的字段编号，避免重复使用已存在的编号。

kv_cache_manager/protocol/protobuf/admin_service.proto

@@ -1,3 +1,5 @@
+// 修改本文件前请阅读 docs/develop/proto_modification_guide.md（Proto 文件修改指南），并同步完成其中列出的适配步骤。
+
 syntax = "proto3";
 
 package kv_cache_manager.proto.admin;

kv_cache_manager/protocol/protobuf/debug_service.proto

@@ -1,3 +1,5 @@
+// 修改本文件前请阅读 docs/develop/proto_modification_guide.md（Proto 文件修改指南），并同步完成其中列出的适配步骤。
+
 syntax = "proto3";
 
 package kv_cache_manager.proto.debug;

kv_cache_manager/protocol/protobuf/kv_meta_service.proto

@@ -1,3 +1,5 @@
+// 修改本文件前请阅读 docs/develop/proto_modification_guide.md（Proto 文件修改指南），并同步完成其中列出的适配步骤。
+
 syntax = "proto3";
 
 package kv_cache_manager.proto.kv_meta;

kv_cache_manager/protocol/protobuf/meta_service.proto

@@ -1,3 +1,5 @@
+// 修改本文件前请阅读 docs/develop/proto_modification_guide.md（Proto 文件修改指南），并同步完成其中列出的适配步骤。
+
 syntax = "proto3";
 
 package kv_cache_manager.proto.meta;

kv_cache_manager/protocol/protobuf/optimizer_service.proto

@@ -1,3 +1,5 @@
+// 修改本文件前请阅读 docs/develop/proto_modification_guide.md（Proto 文件修改指南），并同步完成其中列出的适配步骤。
+
 syntax = "proto3";
 
 package kv_cache_manager.proto.optimizer;

package/kvcm_ops/BUILD

@@ -29,3 +29,9 @@ py_test(
     srcs = ["test/storage_util_test.py"],
     deps = [":kvcm_ops_lib"],
 )
+
+py_test(
+    name = "instance_group_revisit_buckets_test",
+    srcs = ["test/instance_group_revisit_buckets_test.py"],
+    deps = [":kvcm_ops_lib"],
+)

package/kvcm_ops/kvcm/instance_group/create_instance_group.py

@@ -92,7 +92,8 @@ def create_instance_group(args) -> InstanceGroup:
                                    user_data=args.user_data,
                                    version=1,
                                    extra_info=args.extra_info,
-                                   event_report_storage_candidates=args.event_report_storage_candidates)
+                                   event_report_storage_candidates=args.event_report_storage_candidates,
+                                   revisit_interval_buckets=args.revisit_interval_buckets)
     return instance_group
 
 

package/kvcm_ops/kvcm/instance_group/update_instance_group.py

@@ -60,6 +60,8 @@ def main():
         current._extra_info = json.dumps(existing, ensure_ascii=False)
     if hasattr(args, "event_report_storage_candidates"):
         current._event_report_storage_candidates = args.event_report_storage_candidates
+    if hasattr(args, "revisit_interval_buckets"):
+        current._revisit_interval_buckets = args.revisit_interval_buckets
     current.check()
     current_version = current._version
     current._version += 1