fix(extensions-redis): ERR 'EVAL' command keys must in same slot` in Redis Cluster

[BG0527]

关联 issue

• Fixes [Bug]:ERR 'EVAL' command keys must in same slot in Redis Cluster #2165

AgentScope-Java Version

v2.0.0

Description

Background

The RedisStore implementation fails when running against a Redis Cluster. The put operation executes a Lua script (EVAL) involving two keys: the item hash key and the namespace index key. Since these keys have different prefixes (item: vs idx:), they are hashed to different slots in the cluster, causing the EVAL command to fail with ERR 'EVAL' command keys must in same slot.

Root Cause

跨 key 原子操作 vs Redis Cluster 的 slot 分片机制 。

需要两个 key（item hash + namespace index ZSET）在一个 Lua 脚本中原子更新。但 key 命名中类型前缀 item: 和 idx: 不同，导致 CRC16 哈希到不同 slot。Redis Cluster 要求 EVAL 中所有 key 必须在同一 slot，因此报错。

Fix

在 key 中使用 Redis Hash Tag {...} 语法，让 CRC16 只计算 {} 内的内容。确保同一 namespace 下的 item hash 和 namespace index 落入同一 slot，Lua EVAL 脚本在 Redis Cluster 下不再报错。

Changed files:

1. RedisStore.java

Key layout 变更 （第240-248行）：

• itemKey : prefix:item:\0 → prefix:item:{}\0
• indexKey : prefix:idx: → prefix:idx:{}

Namespace 校验增强 （第258-266行）：

• 新增：禁止 namespace 段包含 { 或 } ，防止 hash tag 解析被干扰
• 新增：禁止 namespace 段包含 NUL 字符，防止 namespace 路径歧义

2. RedisStoreTest.java

42 个测试覆盖：

• Hash tag key 生成正确性（itemKey 和 indexKey 共享同一 hash tag）
• Namespace 段校验（ { 、 } 、NUL、null）
• Key 校验（null、空、NUL）
• 构造器（prefix 归一化、空 prefix 回退）
• get/put/putIfVersion/search/delete 全流程 mock 测试
• 序列化边界（null value、空 JSON、非法 JSON）

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[codecov]

Codecov Report

❌ Patch coverage is 81.94444% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../agentscope/extensions/redis/store/RedisStore.java	81.94%	4 Missing and 9 partials ⚠️

📢 Thoughts on this report? Let us know!

[AgentScopeJavaBot]

🤖 AI Review

This PR fixes the ERR 'EVAL' command keys must in same slot error in Redis Cluster by wrapping the namespace portion of Redis keys in hash tags ({<ns>}). The approach is correct and well-documented — using Redis hash tags to ensure the item hash key and namespace index key always map to the same slot is the standard solution for cross-slot Lua script issues. The namespace segment validation for {, }, and NUL is appropriate. The 42 new unit tests provide excellent coverage. However, there are two issues that should be addressed: (1) the key prefix is not validated for {/} characters, which can silently break the hash tag mechanism, and (2) the key format change is a silent breaking change with no migration path for existing deployments.

[AgentScopeJavaBot]

🤖 AI Review

This PR fixes the ERR 'EVAL' command keys must in same slot error in Redis Cluster by wrapping the namespace portion of Redis keys in hash tags ({<ns>}). The approach is correct and well-documented — using Redis hash tags to ensure the item hash key and namespace index key always map to the same slot is the standard solution for cross-slot Lua script issues. The namespace segment validation for {, }, and NUL is appropriate. The 42 new unit tests provide excellent coverage. However, there are two issues that should be addressed: (1) the key prefix is not validated for {/} characters, which can silently break the hash tag mechanism, and (2) the key format change is a silent breaking change with no migration path for existing deployments.

[oss-maintainer]

Summary

Fixes Redis Cluster EVAL command error — all keys must be in the same slot. The fix uses {tag} hash tags to ensure keys are routed to the same slot.

Findings

• [Info] RedisAgentStateStore.java — Added hash tags to key construction. Correct approach for Redis Cluster.
• [Info] Tests added to verify cluster compatibility. Good.

Verdict

Essential fix for Redis Cluster deployments. LGTM.

---

Automated review by github-manager

[AgentScopeJavaBot]

All previously raised review comments have been addressed.