agstack 1.16.2__tar.gz → 1.17.1__tar.gz

{agstack-1.16.2 → agstack-1.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.16.2
+Version: 1.17.1
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
@@ -20,13 +20,9 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aio-pika>=9.6.2
-Requires-Dist: asyncpg>=0.30.0
-Requires-Dist: elasticsearch[async]>=9.3.0
 Requires-Dist: fastapi>=0.136.1
 Requires-Dist: jwcrypto>=1.5.7
 Requires-Dist: loguru>=0.7.3
-Requires-Dist: nebula3-python>=3.8.3
 Requires-Dist: openai>=2.34.0
 Requires-Dist: bcrypt>=4.0.0
 Requires-Dist: pycasbin>=2.8.0
@@ -37,6 +33,25 @@ Requires-Dist: RestrictedPython>=7.0
 Requires-Dist: sqlobjects>=1.9.1
 Requires-Dist: tiktoken>=0.12.0
 Requires-Dist: uvicorn>=0.46.0
+Provides-Extra: mq
+Requires-Dist: aio-pika>=9.6.2; extra == "mq"
+Provides-Extra: db
+Requires-Dist: asyncpg>=0.30.0; extra == "db"
+Provides-Extra: es
+Requires-Dist: elasticsearch[async]>=9.3.0; extra == "es"
+Provides-Extra: graph
+Requires-Dist: nebula3-python>=3.8.3; extra == "graph"
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: std
+Requires-Dist: agstack[mq]; extra == "std"
+Requires-Dist: agstack[db]; extra == "std"
+Provides-Extra: pro
+Requires-Dist: agstack[std]; extra == "pro"
+Requires-Dist: agstack[es]; extra == "pro"
+Provides-Extra: ent
+Requires-Dist: agstack[pro]; extra == "ent"
+Requires-Dist: agstack[graph]; extra == "ent"
 Dynamic: license-file
 
 # AgStack

agstack-1.17.1/agstack/cache/__init__.py

@@ -0,0 +1,14 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+from .base import CacheBackend
+from .memory import MemoryCacheBackend
+
+
+__all__ = ["CacheBackend", "MemoryCacheBackend"]
+
+try:
+    from .redis import RedisCacheBackend  # noqa: F401
+
+    __all__.append("RedisCacheBackend")
+except ImportError:
+    pass

agstack-1.17.1/agstack/cache/base.py

@@ -0,0 +1,39 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+from abc import ABC, abstractmethod
+
+
+class CacheBackend(ABC):
+    """键值缓存后端抽象"""
+
+    @abstractmethod
+    async def get(self, key: str) -> bytes | None:
+        """获取缓存值，不存在或已过期返回 None"""
+
+    @abstractmethod
+    async def set(self, key: str, value: bytes, ttl: int | None = None) -> None:
+        """设置缓存值，ttl 单位为秒，None 表示永不过期"""
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        """删除指定 key"""
+
+    @abstractmethod
+    async def delete_pattern(self, pattern: str) -> None:
+        """删除匹配 glob 通配符的所有 key"""
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool:
+        """判断 key 是否存在且未过期"""
+
+    @abstractmethod
+    async def incr(self, key: str, ttl: int | None = None) -> int:
+        """原子递增，不存在的 key 从 0 开始；如提供 ttl 且 key 新建则设置过期"""
+
+    @abstractmethod
+    async def expire(self, key: str, ttl: int) -> None:
+        """为已有 key 设置过期时间（秒）"""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """释放连接资源"""

agstack-1.17.1/agstack/cache/memory.py

@@ -0,0 +1,66 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+import time
+from fnmatch import fnmatch
+
+from .base import CacheBackend
+
+
+class MemoryCacheBackend(CacheBackend):
+    """基于内存的缓存后端实现"""
+
+    def __init__(self) -> None:
+        # key -> (value, 过期时间戳 | None)
+        self._store: dict[str, tuple[bytes, float | None]] = {}
+
+    def _is_expired(self, key: str) -> bool:
+        entry = self._store.get(key)
+        if entry is None:
+            return True
+        _, expires_at = entry
+        if expires_at is not None and time.monotonic() >= expires_at:
+            del self._store[key]
+            return True
+        return False
+
+    async def get(self, key: str) -> bytes | None:
+        if self._is_expired(key):
+            return None
+        return self._store[key][0]
+
+    async def set(self, key: str, value: bytes, ttl: int | None = None) -> None:
+        expires_at = time.monotonic() + ttl if ttl is not None else None
+        self._store[key] = (value, expires_at)
+
+    async def delete(self, key: str) -> None:
+        self._store.pop(key, None)
+
+    async def delete_pattern(self, pattern: str) -> None:
+        keys_to_delete = [k for k in self._store if fnmatch(k, pattern)]
+        for k in keys_to_delete:
+            del self._store[k]
+
+    async def exists(self, key: str) -> bool:
+        return not self._is_expired(key)
+
+    async def incr(self, key: str, ttl: int | None = None) -> int:
+        if self._is_expired(key):
+            # key 不存在，从 0 开始递增
+            value = 1
+            expires_at = time.monotonic() + ttl if ttl is not None else None
+            self._store[key] = (str(value).encode(), expires_at)
+        else:
+            current_bytes, expires_at = self._store[key]
+            value = int(current_bytes.decode()) + 1
+            # 已有 key 不修改过期时间
+            self._store[key] = (str(value).encode(), expires_at)
+        return value
+
+    async def expire(self, key: str, ttl: int) -> None:
+        entry = self._store.get(key)
+        if entry is not None:
+            value, _ = entry
+            self._store[key] = (value, time.monotonic() + ttl)
+
+    async def close(self) -> None:
+        pass

agstack-1.17.1/agstack/cache/redis.py

@@ -0,0 +1,63 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+import redis.asyncio as aioredis
+
+from .base import CacheBackend
+
+
+# INCR + 条件 EXPIRE 的 Lua 脚本，保证原子性
+_INCR_WITH_TTL_SCRIPT = """
+local v = redis.call('INCR', KEYS[1])
+if v == 1 and ARGV[1] ~= '0' then
+    redis.call('EXPIRE', KEYS[1], ARGV[1])
+end
+return v
+"""
+
+
+class RedisCacheBackend(CacheBackend):
+    """基于 Redis 的缓存后端实现"""
+
+    def __init__(self, client: aioredis.Redis) -> None:
+        self._client = client
+        self._incr_script = self._client.register_script(_INCR_WITH_TTL_SCRIPT)
+
+    async def get(self, key: str) -> bytes | None:
+        value = await self._client.get(key)
+        return value
+
+    async def set(self, key: str, value: bytes, ttl: int | None = None) -> None:
+        if ttl is not None:
+            await self._client.set(key, value, ex=ttl)
+        else:
+            await self._client.set(key, value)
+
+    async def delete(self, key: str) -> None:
+        await self._client.delete(key)
+
+    async def delete_pattern(self, pattern: str) -> None:
+        cursor: int = 0
+        while True:
+            cursor, keys = await self._client.scan(cursor=cursor, match=pattern, count=100)
+            if keys:
+                await self._client.delete(*keys)
+            if cursor == 0:
+                break
+
+    async def exists(self, key: str) -> bool:
+        result = await self._client.exists(key)
+        return bool(result)
+
+    async def incr(self, key: str, ttl: int | None = None) -> int:
+        if ttl is not None:
+            result = await self._incr_script(keys=[key], args=[ttl])
+            return int(result)
+        else:
+            result = await self._client.incr(key)
+            return int(result)
+
+    async def expire(self, key: str, ttl: int) -> None:
+        await self._client.expire(key, ttl)
+
+    async def close(self) -> None:
+        await self._client.aclose()

agstack-1.17.1/agstack/messagebus/__init__.py

@@ -0,0 +1,14 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+from .base import MessageBus, Subscription
+from .memory import MemoryMessageBus
+
+
+__all__ = ["MessageBus", "Subscription", "MemoryMessageBus"]
+
+try:
+    from .redis import RedisMessageBus  # noqa: F401
+
+    __all__.append("RedisMessageBus")
+except ImportError:
+    pass

agstack-1.17.1/agstack/messagebus/base.py

@@ -0,0 +1,42 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Self
+
+
+class Subscription(ABC):
+    """订阅句柄，支持 async context manager 和 async iteration"""
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    def __aiter__(self) -> AsyncIterator[tuple[str, bytes]]:
+        return self
+
+    @abstractmethod
+    async def __anext__(self) -> tuple[str, bytes]:
+        """返回 (channel, message)，无消息时阻塞等待"""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """取消订阅并释放资源"""
+
+
+class MessageBus(ABC):
+    """发布/订阅消息总线"""
+
+    @abstractmethod
+    async def publish(self, channel: str, message: bytes) -> None:
+        """发布消息到指定 channel，无订阅者时消息丢弃"""
+
+    @abstractmethod
+    def subscribe(self, *channels: str) -> Subscription:
+        """订阅一个或多个 channel，返回 Subscription 句柄"""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """释放连接资源"""

agstack-1.17.1/agstack/messagebus/memory.py

@@ -0,0 +1,54 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+import asyncio
+from collections.abc import AsyncIterator
+
+from .base import MessageBus, Subscription
+
+
+class MemorySubscription(Subscription):
+    """内存消息总线的订阅实现"""
+
+    def __init__(self, bus: "MemoryMessageBus", channels: tuple[str, ...]) -> None:
+        self._bus = bus
+        self._channels = channels
+        self._queue: asyncio.Queue[tuple[str, bytes]] = asyncio.Queue()
+        # 注册到 bus
+        for ch in self._channels:
+            self._bus._subscribers.setdefault(ch, []).append(self._queue)
+
+    def __aiter__(self) -> AsyncIterator[tuple[str, bytes]]:
+        return self
+
+    async def __anext__(self) -> tuple[str, bytes]:
+        try:
+            return await self._queue.get()
+        except asyncio.CancelledError:
+            raise StopAsyncIteration from None
+
+    async def close(self) -> None:
+        for ch in self._channels:
+            queues = self._bus._subscribers.get(ch)
+            if queues and self._queue in queues:
+                queues.remove(self._queue)
+                if not queues:
+                    del self._bus._subscribers[ch]
+
+
+class MemoryMessageBus(MessageBus):
+    """基于内存的发布/订阅消息总线实现"""
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, list[asyncio.Queue[tuple[str, bytes]]]] = {}
+
+    async def publish(self, channel: str, message: bytes) -> None:
+        queues = self._subscribers.get(channel)
+        if queues:
+            for queue in queues:
+                queue.put_nowait((channel, message))
+
+    def subscribe(self, *channels: str) -> Subscription:
+        return MemorySubscription(self, channels)
+
+    async def close(self) -> None:
+        self._subscribers.clear()

agstack-1.17.1/agstack/messagebus/redis.py

@@ -0,0 +1,94 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+import asyncio
+from collections.abc import AsyncIterator
+from typing import Self
+
+import redis.asyncio as aioredis
+from redis.asyncio.client import PubSub
+
+from .base import MessageBus, Subscription
+
+
+class RedisSubscription(Subscription):
+    """Redis Pub/Sub 的订阅实现"""
+
+    def __init__(self, pubsub: PubSub, channels: tuple[str, ...]) -> None:
+        self._pubsub = pubsub
+        self._channels = channels
+        self._task: asyncio.Task[None] | None = None
+        self._queue: asyncio.Queue[tuple[str, bytes]] = asyncio.Queue()
+        self._started = False
+        self._closed = False
+
+    async def _start(self) -> None:
+        if self._started:
+            return
+        self._started = True
+        await self._pubsub.subscribe(*self._channels)
+        self._task = asyncio.create_task(self._listen())
+
+    async def __aenter__(self) -> Self:
+        await self._start()
+        return self
+
+    async def _listen(self) -> None:
+        try:
+            async for msg in self._pubsub.listen():
+                if self._closed:
+                    break
+                if msg["type"] == "message":
+                    channel = msg["channel"]
+                    if isinstance(channel, bytes):
+                        channel = channel.decode()
+                    data = msg["data"]
+                    if isinstance(data, str):
+                        data = data.encode()
+                    self._queue.put_nowait((channel, data))
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            pass
+
+    def __aiter__(self) -> AsyncIterator[tuple[str, bytes]]:
+        return self
+
+    async def __anext__(self) -> tuple[str, bytes]:
+        if not self._started:
+            await self._start()
+        if self._closed and self._queue.empty():
+            raise StopAsyncIteration
+        try:
+            return await self._queue.get()
+        except asyncio.CancelledError:
+            raise StopAsyncIteration from None
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._task and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        await self._pubsub.unsubscribe(*self._channels)
+        await self._pubsub.aclose()
+
+
+class RedisMessageBus(MessageBus):
+    """基于 Redis Pub/Sub 的消息总线实现"""
+
+    def __init__(self, client: aioredis.Redis) -> None:
+        self._client = client
+
+    async def publish(self, channel: str, message: bytes) -> None:
+        await self._client.publish(channel, message)
+
+    def subscribe(self, *channels: str) -> RedisSubscription:
+        pubsub = self._client.pubsub()
+        return RedisSubscription(pubsub, channels)
+
+    async def close(self) -> None:
+        await self._client.aclose()

{agstack-1.16.2 → agstack-1.17.1}/agstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.16.2
+Version: 1.17.1
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
@@ -20,13 +20,9 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aio-pika>=9.6.2
-Requires-Dist: asyncpg>=0.30.0
-Requires-Dist: elasticsearch[async]>=9.3.0
 Requires-Dist: fastapi>=0.136.1
 Requires-Dist: jwcrypto>=1.5.7
 Requires-Dist: loguru>=0.7.3
-Requires-Dist: nebula3-python>=3.8.3
 Requires-Dist: openai>=2.34.0
 Requires-Dist: bcrypt>=4.0.0
 Requires-Dist: pycasbin>=2.8.0
@@ -37,6 +33,25 @@ Requires-Dist: RestrictedPython>=7.0
 Requires-Dist: sqlobjects>=1.9.1
 Requires-Dist: tiktoken>=0.12.0
 Requires-Dist: uvicorn>=0.46.0
+Provides-Extra: mq
+Requires-Dist: aio-pika>=9.6.2; extra == "mq"
+Provides-Extra: db
+Requires-Dist: asyncpg>=0.30.0; extra == "db"
+Provides-Extra: es
+Requires-Dist: elasticsearch[async]>=9.3.0; extra == "es"
+Provides-Extra: graph
+Requires-Dist: nebula3-python>=3.8.3; extra == "graph"
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: std
+Requires-Dist: agstack[mq]; extra == "std"
+Requires-Dist: agstack[db]; extra == "std"
+Provides-Extra: pro
+Requires-Dist: agstack[std]; extra == "pro"
+Requires-Dist: agstack[es]; extra == "pro"
+Provides-Extra: ent
+Requires-Dist: agstack[pro]; extra == "ent"
+Requires-Dist: agstack[graph]; extra == "ent"
 Dynamic: license-file
 
 # AgStack

{agstack-1.16.2 → agstack-1.17.1}/agstack.egg-info/SOURCES.txt

@@ -13,6 +13,10 @@ agstack.egg-info/SOURCES.txt
 agstack.egg-info/dependency_links.txt
 agstack.egg-info/requires.txt
 agstack.egg-info/top_level.txt
+agstack/cache/__init__.py
+agstack/cache/base.py
+agstack/cache/memory.py
+agstack/cache/redis.py
 agstack/config/__init__.py
 agstack/config/logger.py
 agstack/config/manager.py
@@ -55,8 +59,16 @@ agstack/llm/flow/nodes/python_node.py
 agstack/llm/flow/nodes/subflow_node.py
 agstack/llm/flow/nodes/switch_node.py
 agstack/llm/flow/nodes/tool_node.py
+agstack/messagebus/__init__.py
+agstack/messagebus/base.py
+agstack/messagebus/memory.py
+agstack/messagebus/redis.py
 agstack/security/__init__.py
 agstack/security/casbin.py
 agstack/security/crypt.py
+tests/test_cache_memory.py
+tests/test_cache_redis.py
 tests/test_flow_io.py
-tests/test_flow_switch_subflow.py
+tests/test_flow_switch_subflow.py
+tests/test_messagebus_memory.py
+tests/test_messagebus_redis.py

{agstack-1.16.2 → agstack-1.17.1}/agstack.egg-info/requires.txt

@@ -1,10 +1,6 @@
-aio-pika>=9.6.2
-asyncpg>=0.30.0
-elasticsearch[async]>=9.3.0
 fastapi>=0.136.1
 jwcrypto>=1.5.7
 loguru>=0.7.3
-nebula3-python>=3.8.3
 openai>=2.34.0
 bcrypt>=4.0.0
 pycasbin>=2.8.0
@@ -15,3 +11,30 @@ RestrictedPython>=7.0
 sqlobjects>=1.9.1
 tiktoken>=0.12.0
 uvicorn>=0.46.0
+
+[db]
+asyncpg>=0.30.0
+
+[ent]
+agstack[pro]
+agstack[graph]
+
+[es]
+elasticsearch[async]>=9.3.0
+
+[graph]
+nebula3-python>=3.8.3
+
+[mq]
+aio-pika>=9.6.2
+
+[pro]
+agstack[std]
+agstack[es]
+
+[redis]
+redis>=5.0
+
+[std]
+agstack[mq]
+agstack[db]

{agstack-1.16.2 → agstack-1.17.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agstack"
-version = "1.16.2"
+version = "1.17.1"
 description = "Production-ready toolkit for building FastAPI and LLM applications"
 readme = "README.md"
 license = "MIT"
@@ -39,13 +39,9 @@ classifiers = [
 ]
 requires-python = ">=3.12"
 dependencies = [
-    "aio-pika>=9.6.2",
-    "asyncpg>=0.30.0",
-    "elasticsearch[async]>=9.3.0",
     "fastapi>=0.136.1",
     "jwcrypto>=1.5.7",
     "loguru>=0.7.3",
-    "nebula3-python>=3.8.3",
     "openai>=2.34.0",
     "bcrypt>=4.0.0",
     "pycasbin>=2.8.0",
@@ -57,11 +53,23 @@ dependencies = [
     "tiktoken>=0.12.0",
     "uvicorn>=0.46.0",
 ]
+
+[project.optional-dependencies]
+mq = ["aio-pika>=9.6.2"]
+db = ["asyncpg>=0.30.0"]
+es = ["elasticsearch[async]>=9.3.0"]
+graph = ["nebula3-python>=3.8.3"]
+redis = ["redis>=5.0"]
+std = ["agstack[mq]", "agstack[db]"]
+pro = ["agstack[std]", "agstack[es]"]
+ent = ["agstack[pro]", "agstack[graph]"]
+
 [dependency-groups]
 dev = [
     "pre-commit>=4.6.0",
     "pyright>=1.1.409",
     "pytest>=9.0.3",
+    "pytest-asyncio>=1.0.0",
     "ruff>=0.15.12",
     "setuptools>=82.0.0",
 ]
@@ -72,7 +80,7 @@ dev = [
 #default = true
 
 [tool.pyright]
-include = ["app", "depends"]
+include = ["app", "depends", "agstack/cache", "agstack/messagebus", "tests"]
 exclude = ["**/__pycache__"]
 pythonVersion = "3.12"
 reportMissingImports = "error"
@@ -119,3 +127,8 @@ tag_format = "$version"
 version_scheme = "pep440"
 version_provider = "uv"
 update_changelog_on_bump = true
+
+[tool.pytest.ini_options]
+markers = [
+    "redis: 需要真实 Redis 连接的测试",
+]

agstack-1.17.1/tests/test_cache_memory.py

@@ -0,0 +1,145 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""MemoryCacheBackend 全接口测试"""
+
+import time
+from unittest.mock import patch
+
+import pytest
+
+from agstack.cache import MemoryCacheBackend
+
+
+@pytest.fixture
+def cache() -> MemoryCacheBackend:
+    return MemoryCacheBackend()
+
+
+class TestGetSet:
+    @pytest.mark.asyncio
+    async def test_set_and_get(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("key1", b"value1")
+        assert await cache.get("key1") == b"value1"
+
+    @pytest.mark.asyncio
+    async def test_get_nonexistent(self, cache: MemoryCacheBackend) -> None:
+        assert await cache.get("missing") is None
+
+    @pytest.mark.asyncio
+    async def test_set_overwrite(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("key1", b"v1")
+        await cache.set("key1", b"v2")
+        assert await cache.get("key1") == b"v2"
+
+    @pytest.mark.asyncio
+    async def test_set_with_ttl_not_expired(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("key1", b"value1", ttl=10)
+        assert await cache.get("key1") == b"value1"
+
+    @pytest.mark.asyncio
+    async def test_set_with_ttl_expired(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("key1", b"value1", ttl=1)
+        # 模拟时间流逝
+        with patch("agstack.cache.memory.time.monotonic", return_value=time.monotonic() + 2):
+            assert await cache.get("key1") is None
+
+
+class TestDelete:
+    @pytest.mark.asyncio
+    async def test_delete_existing(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("key1", b"value1")
+        await cache.delete("key1")
+        assert await cache.get("key1") is None
+
+    @pytest.mark.asyncio
+    async def test_delete_nonexistent(self, cache: MemoryCacheBackend) -> None:
+        await cache.delete("missing")  # 不应抛异常
+
+
+class TestDeletePattern:
+    @pytest.mark.asyncio
+    async def test_delete_pattern_wildcard(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("user:1:name", b"alice")
+        await cache.set("user:2:name", b"bob")
+        await cache.set("session:1", b"data")
+        await cache.delete_pattern("user:*")
+        assert await cache.get("user:1:name") is None
+        assert await cache.get("user:2:name") is None
+        assert await cache.get("session:1") == b"data"
+
+    @pytest.mark.asyncio
+    async def test_delete_pattern_question_mark(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("a1", b"v1")
+        await cache.set("a2", b"v2")
+        await cache.set("ab", b"v3")
+        await cache.delete_pattern("a?")
+        assert await cache.get("a1") is None
+        assert await cache.get("a2") is None
+        assert await cache.get("ab") is None
+
+
+class TestExists:
+    @pytest.mark.asyncio
+    async def test_exists_true(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("key1", b"value1")
+        assert await cache.exists("key1") is True
+
+    @pytest.mark.asyncio
+    async def test_exists_false(self, cache: MemoryCacheBackend) -> None:
+        assert await cache.exists("missing") is False
+
+    @pytest.mark.asyncio
+    async def test_exists_expired(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("key1", b"value1", ttl=1)
+        with patch("agstack.cache.memory.time.monotonic", return_value=time.monotonic() + 2):
+            assert await cache.exists("key1") is False
+
+
+class TestIncr:
+    @pytest.mark.asyncio
+    async def test_incr_new_key(self, cache: MemoryCacheBackend) -> None:
+        result = await cache.incr("counter")
+        assert result == 1
+        assert await cache.get("counter") == b"1"
+
+    @pytest.mark.asyncio
+    async def test_incr_existing_key(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("counter", b"5")
+        result = await cache.incr("counter")
+        assert result == 6
+        assert await cache.get("counter") == b"6"
+
+    @pytest.mark.asyncio
+    async def test_incr_with_ttl_new_key(self, cache: MemoryCacheBackend) -> None:
+        result = await cache.incr("counter", ttl=10)
+        assert result == 1
+        # 验证 ttl 已设置（过期后取不到）
+        with patch("agstack.cache.memory.time.monotonic", return_value=time.monotonic() + 11):
+            assert await cache.get("counter") is None
+
+    @pytest.mark.asyncio
+    async def test_incr_with_ttl_existing_key(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("counter", b"3", ttl=100)
+        result = await cache.incr("counter", ttl=5)
+        assert result == 4
+        # 已有 key 不修改过期时间，原 ttl 仍有效
+        assert await cache.get("counter") == b"4"
+
+
+class TestExpire:
+    @pytest.mark.asyncio
+    async def test_expire_sets_ttl(self, cache: MemoryCacheBackend) -> None:
+        await cache.set("key1", b"value1")
+        await cache.expire("key1", 1)
+        with patch("agstack.cache.memory.time.monotonic", return_value=time.monotonic() + 2):
+            assert await cache.get("key1") is None
+
+    @pytest.mark.asyncio
+    async def test_expire_nonexistent_key(self, cache: MemoryCacheBackend) -> None:
+        await cache.expire("missing", 10)  # 不应抛异常
+
+
+class TestClose:
+    @pytest.mark.asyncio
+    async def test_close(self, cache: MemoryCacheBackend) -> None:
+        await cache.close()  # 空操作，不应抛异常

agstack-1.17.1/tests/test_cache_redis.py

@@ -0,0 +1,101 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""RedisCacheBackend 测试（需要真实 Redis）"""
+
+import pytest
+import redis.asyncio as aioredis
+
+from agstack.cache import CacheBackend, RedisCacheBackend
+
+
+pytestmark = [
+    pytest.mark.redis,
+    pytest.mark.asyncio,
+]
+
+
+@pytest.fixture
+async def cache():
+    client = aioredis.from_url("redis://localhost:6379/15")
+    await client.flushdb()
+    backend = RedisCacheBackend(client)
+    yield backend
+    await client.flushdb()
+    await backend.close()
+
+
+class TestGetSet:
+    async def test_set_and_get(self, cache: CacheBackend) -> None:
+        await cache.set("key1", b"value1")
+        assert await cache.get("key1") == b"value1"
+
+    async def test_get_nonexistent(self, cache: CacheBackend) -> None:
+        assert await cache.get("missing") is None
+
+    async def test_set_overwrite(self, cache: CacheBackend) -> None:
+        await cache.set("key1", b"v1")
+        await cache.set("key1", b"v2")
+        assert await cache.get("key1") == b"v2"
+
+    async def test_set_with_ttl(self, cache: CacheBackend) -> None:
+        await cache.set("key1", b"value1", ttl=10)
+        assert await cache.get("key1") == b"value1"
+
+
+class TestDelete:
+    async def test_delete_existing(self, cache: CacheBackend) -> None:
+        await cache.set("key1", b"value1")
+        await cache.delete("key1")
+        assert await cache.get("key1") is None
+
+    async def test_delete_nonexistent(self, cache: CacheBackend) -> None:
+        await cache.delete("missing")
+
+
+class TestDeletePattern:
+    async def test_delete_pattern(self, cache: CacheBackend) -> None:
+        await cache.set("user:1:name", b"alice")
+        await cache.set("user:2:name", b"bob")
+        await cache.set("session:1", b"data")
+        await cache.delete_pattern("user:*")
+        assert await cache.get("user:1:name") is None
+        assert await cache.get("user:2:name") is None
+        assert await cache.get("session:1") == b"data"
+
+
+class TestExists:
+    async def test_exists_true(self, cache: CacheBackend) -> None:
+        await cache.set("key1", b"value1")
+        assert await cache.exists("key1") is True
+
+    async def test_exists_false(self, cache: CacheBackend) -> None:
+        assert await cache.exists("missing") is False
+
+
+class TestIncr:
+    async def test_incr_new_key(self, cache: CacheBackend) -> None:
+        result = await cache.incr("counter")
+        assert result == 1
+
+    async def test_incr_existing_key(self, cache: CacheBackend) -> None:
+        await cache.set("counter", b"5")
+        result = await cache.incr("counter")
+        assert result == 6
+
+    async def test_incr_with_ttl(self, cache: CacheBackend) -> None:
+        result = await cache.incr("counter", ttl=60)
+        assert result == 1
+
+
+class TestExpire:
+    async def test_expire_sets_ttl(self, cache: CacheBackend) -> None:
+        await cache.set("key1", b"value1")
+        await cache.expire("key1", 60)
+        assert await cache.exists("key1") is True
+
+
+class TestClose:
+    async def test_close(self) -> None:
+        client = aioredis.from_url("redis://localhost:6379/15")
+        backend = RedisCacheBackend(client)
+        await backend.close()

agstack-1.17.1/tests/test_messagebus_memory.py

@@ -0,0 +1,71 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""MemoryMessageBus 全接口测试"""
+
+import asyncio
+
+import pytest
+
+from agstack.messagebus import MemoryMessageBus
+
+
+@pytest.fixture
+def bus() -> MemoryMessageBus:
+    return MemoryMessageBus()
+
+
+class TestPublishSubscribe:
+    @pytest.mark.asyncio
+    async def test_single_channel(self, bus: MemoryMessageBus) -> None:
+        sub = bus.subscribe("ch1")
+        async with sub:
+            await bus.publish("ch1", b"hello")
+            channel, message = await asyncio.wait_for(sub.__anext__(), timeout=1)
+            assert channel == "ch1"
+            assert message == b"hello"
+
+    @pytest.mark.asyncio
+    async def test_multi_channel(self, bus: MemoryMessageBus) -> None:
+        sub = bus.subscribe("ch1", "ch2")
+        async with sub:
+            await bus.publish("ch1", b"msg1")
+            await bus.publish("ch2", b"msg2")
+            results = []
+            for _ in range(2):
+                ch, msg = await asyncio.wait_for(sub.__anext__(), timeout=1)
+                results.append((ch, msg))
+            assert ("ch1", b"msg1") in results
+            assert ("ch2", b"msg2") in results
+
+    @pytest.mark.asyncio
+    async def test_multiple_subscribers(self, bus: MemoryMessageBus) -> None:
+        sub1 = bus.subscribe("ch1")
+        sub2 = bus.subscribe("ch1")
+        async with sub1, sub2:
+            await bus.publish("ch1", b"broadcast")
+            ch1, msg1 = await asyncio.wait_for(sub1.__anext__(), timeout=1)
+            ch2, msg2 = await asyncio.wait_for(sub2.__anext__(), timeout=1)
+            assert msg1 == b"broadcast"
+            assert msg2 == b"broadcast"
+
+    @pytest.mark.asyncio
+    async def test_publish_no_subscribers(self, bus: MemoryMessageBus) -> None:
+        # 无订阅者时 publish 不应抛异常
+        await bus.publish("ch1", b"nobody listening")
+
+    @pytest.mark.asyncio
+    async def test_subscription_close_removes_queue(self, bus: MemoryMessageBus) -> None:
+        sub = bus.subscribe("ch1")
+        async with sub:
+            pass
+        # close 后不应再收到消息
+        assert "ch1" not in bus._subscribers or len(bus._subscribers.get("ch1", [])) == 0
+
+
+class TestClose:
+    @pytest.mark.asyncio
+    async def test_bus_close_clears_subscribers(self, bus: MemoryMessageBus) -> None:
+        bus.subscribe("ch1")
+        bus.subscribe("ch2")
+        await bus.close()
+        assert len(bus._subscribers) == 0

agstack-1.17.1/tests/test_messagebus_redis.py

@@ -0,0 +1,73 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""RedisMessageBus 测试（需要真实 Redis）"""
+
+import asyncio
+
+import pytest
+import redis.asyncio as aioredis
+
+from agstack.messagebus.redis import RedisMessageBus
+
+
+pytestmark = [
+    pytest.mark.redis,
+    pytest.mark.asyncio,
+]
+
+
+@pytest.fixture
+async def bus():
+    client = aioredis.from_url("redis://localhost:6379/15")
+    mb = RedisMessageBus(client)
+    yield mb
+    await mb.close()
+
+
+class TestPublishSubscribe:
+    async def test_single_channel(self, bus: RedisMessageBus) -> None:
+        async with bus.subscribe("test:ch1") as sub:
+            await asyncio.sleep(0.1)
+            await bus.publish("test:ch1", b"hello")
+            channel, message = await asyncio.wait_for(anext(sub), timeout=3)
+            assert channel == "test:ch1"
+            assert message == b"hello"
+
+    async def test_multi_channel(self, bus: RedisMessageBus) -> None:
+        async with bus.subscribe("test:ch1", "test:ch2") as sub:
+            await asyncio.sleep(0.1)
+            await bus.publish("test:ch1", b"msg1")
+            await bus.publish("test:ch2", b"msg2")
+            results = []
+            for _ in range(2):
+                ch, msg = await asyncio.wait_for(anext(sub), timeout=3)
+                results.append((ch, msg))
+            channels = [r[0] for r in results]
+            assert "test:ch1" in channels
+            assert "test:ch2" in channels
+
+    async def test_lazy_start_without_context_manager(self, bus: RedisMessageBus) -> None:
+        sub = bus.subscribe("test:ch1")
+        await asyncio.sleep(0.1)
+        await bus.publish("test:ch1", b"world")
+        channel, message = await asyncio.wait_for(anext(sub), timeout=3)
+        assert channel == "test:ch1"
+        assert message == b"world"
+        await sub.close()
+
+    async def test_publish_no_subscribers(self, bus: RedisMessageBus) -> None:
+        await bus.publish("test:nobody", b"lost message")
+
+
+class TestSubscriptionClose:
+    async def test_close(self, bus: RedisMessageBus) -> None:
+        async with bus.subscribe("test:ch1") as sub:
+            await asyncio.sleep(0.1)
+        assert sub._closed
+
+
+class TestBusClose:
+    async def test_close(self) -> None:
+        client = aioredis.from_url("redis://localhost:6379/15")
+        mb = RedisMessageBus(client)
+        await mb.close()