wisruntime 0.4.2__tar.gz → 0.5.0__tar.gz

{wisruntime-0.4.2/wisruntime.egg-info → wisruntime-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wisruntime
-Version: 0.4.2
+Version: 0.5.0
 Summary: 企业级 Agent Runtime SDK — 让 AI 工程师专注 Agent 能力开发，无需关心底层基础设施
 Author: WIS Team
 License-Expression: MIT
@@ -713,6 +713,30 @@ def create_server(
 └─────────────────────────────────────────────────────────────────────┘
 
 故事 6 ──────────────────────────────────────────────────────────────
+│  用户故事: 作为 AI 工程师，我可以用 WishubMemoryMiddleware 为我的         │
+│           DeepAgents Agent 添加长期记忆能力，自动检索用户历史对话记忆      │
+│                                                                   │
+│  验收标准:                                                          │
+│    from deepagents import create_deep_agent                          │
+│    from wisruntime.adapters.langgraph import WishubMemoryMiddleware  │
+│    from wisruntime.memory import WishubMemoryClient         │
+│                                                                   │
+│    memory_client = WishubMemoryClient(                              │
+│        base_url="https://wishub.example.com",                        │
+│        api_key="your-api-key"                                        │
+│    )                                                                │
+│    middleware = WishubMemoryMiddleware(                             │
+│        client=memory_client,                                         │
+│        namespaces=["user_profile", "preferences"],                   │
+│        top_k=5                                                       │
+│    )                                                                │
+│    agent = create_deep_agent(model=model, middlewares=[middleware]) │
+│    # → Agent 在每次对话前自动检索相关历史记忆                          │
+│    # → 记忆以结构化 XML 格式注入系统提示词                             │
+│    # → 支持优雅降级: API 超时/失败时返回空列表，不影响对话             │
+└─────────────────────────────────────────────────────────────────────┘
+
+故事 7 ──────────────────────────────────────────────────────────────
 │  用户故事: 作为 AI 工程师，我的 Agent 对话历史可以自动持久化到           │
 │           WIS Hub Checkpoint 服务，支持断点续传                         │
 │                                                                   │
@@ -782,16 +806,36 @@ Phase 3: 平台能力接入 (MCP ✅ 已完成 — v0.3)
      分页发现 / 详情 / 302 预签名下载 / 严格 SemVer 版本, create_skill_sources() deepagents 集成
   □ SandboxClient + Sandbox 数据模型
 
+Phase 3.5: 记忆能力接入 (✅ 已完成 — v0.4)
+═══════════════════════════════
+  目标: 用户故事 6 — WishubMemoryMiddleware 长期记忆
+
+  ✅ memory/ 模块: MemoryItem, RetrieveRequest, RetrieveResponse 数据模型
+  ✅ WishubMemoryClient — 异步 HTTP 客户端，对接 Wishub Memory API
+     - 优雅降级: 超时/错误返回空列表，不影响对话
+     - 完整日志: debug/info/warning/error 四级
+  ✅ MemoryPromptFormatter — 记忆列表 → 结构化 XML 提示词片段
+     - 支持相关度评分显示
+     - 空记忆占位符
+     - 可选使用指南
+  ✅ WishubMemoryMiddleware — DeepAgents 中间件
+     - abefore_agent: 检索记忆并存入 state
+     - modify_request: 注入记忆到系统提示词
+     - 跳过重复检索
+     - user_id/query 缺失时优雅处理
+  ✅ wrap_agent config 注入 — user_id, thread_id 传递到 LangGraph config.configurable
+  ✅ 完整测试覆盖 (39 个测试用例全部通过)
+
 Phase 4: 高级特性
 ════════════════
-  目标: 用户故事 6 — Checkpoint、多协议
+  目标: 用户故事 7 — Checkpoint、多协议
 
   □ CheckpointClient + 自动持久化
   □ AGUIHandler
   □ Stop endpoint
   □ ApiKeyMiddleware
 
-Phase 4: 多框架 + 多协议
+Phase 5: 多框架 + 多协议
 ══════════════════════
   目标: 验证可扩展性
 
@@ -817,12 +861,19 @@ wisruntime/
 │   └── client.py                #   MCPClient(ToolClient) — 薄封装标准 mcp 包
 │
 ├── adapters/                    # Adapter + Capability Bridge
+│   ├── memory/                  #   Memory 记忆检索适配器 (✅ v0.4)
+│   │   ├── __init__.py          #     导出 WishubMemoryClient, MemoryPromptFormatter, MemoryItem
+│   │   ├── model.py             #     MemoryItem, RetrieveRequest, RetrieveResponse (Pydantic 模型)
+│   │   ├── client.py            #     WishubMemoryClient — 异步 HTTP 客户端，优雅降级
+│   │   └── formatter.py         #     MemoryPromptFormatter — 记忆列表 → XML 提示词片段
+│   │
 │   └── langgraph/               #   LangGraph/LangChain/DeepAgents 框架 (✅ v0.3)
-│       ├── __init__.py          #     导出 LangGraphEventConverter, wrap_agent, LangChainToolAdapter, create_model, create_mcp_tools
+│       ├── __init__.py          #     导出 LangGraphEventConverter, wrap_agent, LangChainToolAdapter, create_model, create_mcp_tools, WishubMemoryMiddleware
 │       ├── converter.py         #     LangGraphEventConverter (astream_events → CanonicalEvent)
-│       ├── wrap_agent.py        #     wrap_agent() 糖函数
+│       ├── wrap_agent.py        #     wrap_agent() 糖函数 (注入 config: user_id, thread_id)
 │       ├── tool_adapter.py      #     LangChainToolAdapter (ToolInfo → StructuredTool)
-│       └── builtin.py           #     create_model() / create_mcp_tools() 一行接入
+│       ├── builtin.py           #     create_model() / create_mcp_tools() 一行接入
+│       └── memory_middleware.py #     WishubMemoryMiddleware — DeepAgents 记忆中间件
 │
 ├── server/                      # Server 层
 │   ├── __init__.py

{wisruntime-0.4.2 → wisruntime-0.5.0}/README.md

@@ -681,6 +681,30 @@ def create_server(
 └─────────────────────────────────────────────────────────────────────┘
 
 故事 6 ──────────────────────────────────────────────────────────────
+│  用户故事: 作为 AI 工程师，我可以用 WishubMemoryMiddleware 为我的         │
+│           DeepAgents Agent 添加长期记忆能力，自动检索用户历史对话记忆      │
+│                                                                   │
+│  验收标准:                                                          │
+│    from deepagents import create_deep_agent                          │
+│    from wisruntime.adapters.langgraph import WishubMemoryMiddleware  │
+│    from wisruntime.memory import WishubMemoryClient         │
+│                                                                   │
+│    memory_client = WishubMemoryClient(                              │
+│        base_url="https://wishub.example.com",                        │
+│        api_key="your-api-key"                                        │
+│    )                                                                │
+│    middleware = WishubMemoryMiddleware(                             │
+│        client=memory_client,                                         │
+│        namespaces=["user_profile", "preferences"],                   │
+│        top_k=5                                                       │
+│    )                                                                │
+│    agent = create_deep_agent(model=model, middlewares=[middleware]) │
+│    # → Agent 在每次对话前自动检索相关历史记忆                          │
+│    # → 记忆以结构化 XML 格式注入系统提示词                             │
+│    # → 支持优雅降级: API 超时/失败时返回空列表，不影响对话             │
+└─────────────────────────────────────────────────────────────────────┘
+
+故事 7 ──────────────────────────────────────────────────────────────
 │  用户故事: 作为 AI 工程师，我的 Agent 对话历史可以自动持久化到           │
 │           WIS Hub Checkpoint 服务，支持断点续传                         │
 │                                                                   │
@@ -750,16 +774,36 @@ Phase 3: 平台能力接入 (MCP ✅ 已完成 — v0.3)
      分页发现 / 详情 / 302 预签名下载 / 严格 SemVer 版本, create_skill_sources() deepagents 集成
   □ SandboxClient + Sandbox 数据模型
 
+Phase 3.5: 记忆能力接入 (✅ 已完成 — v0.4)
+═══════════════════════════════
+  目标: 用户故事 6 — WishubMemoryMiddleware 长期记忆
+
+  ✅ memory/ 模块: MemoryItem, RetrieveRequest, RetrieveResponse 数据模型
+  ✅ WishubMemoryClient — 异步 HTTP 客户端，对接 Wishub Memory API
+     - 优雅降级: 超时/错误返回空列表，不影响对话
+     - 完整日志: debug/info/warning/error 四级
+  ✅ MemoryPromptFormatter — 记忆列表 → 结构化 XML 提示词片段
+     - 支持相关度评分显示
+     - 空记忆占位符
+     - 可选使用指南
+  ✅ WishubMemoryMiddleware — DeepAgents 中间件
+     - abefore_agent: 检索记忆并存入 state
+     - modify_request: 注入记忆到系统提示词
+     - 跳过重复检索
+     - user_id/query 缺失时优雅处理
+  ✅ wrap_agent config 注入 — user_id, thread_id 传递到 LangGraph config.configurable
+  ✅ 完整测试覆盖 (39 个测试用例全部通过)
+
 Phase 4: 高级特性
 ════════════════
-  目标: 用户故事 6 — Checkpoint、多协议
+  目标: 用户故事 7 — Checkpoint、多协议
 
   □ CheckpointClient + 自动持久化
   □ AGUIHandler
   □ Stop endpoint
   □ ApiKeyMiddleware
 
-Phase 4: 多框架 + 多协议
+Phase 5: 多框架 + 多协议
 ══════════════════════
   目标: 验证可扩展性
 
@@ -785,12 +829,19 @@ wisruntime/
 │   └── client.py                #   MCPClient(ToolClient) — 薄封装标准 mcp 包
 │
 ├── adapters/                    # Adapter + Capability Bridge
+│   ├── memory/                  #   Memory 记忆检索适配器 (✅ v0.4)
+│   │   ├── __init__.py          #     导出 WishubMemoryClient, MemoryPromptFormatter, MemoryItem
+│   │   ├── model.py             #     MemoryItem, RetrieveRequest, RetrieveResponse (Pydantic 模型)
+│   │   ├── client.py            #     WishubMemoryClient — 异步 HTTP 客户端，优雅降级
+│   │   └── formatter.py         #     MemoryPromptFormatter — 记忆列表 → XML 提示词片段
+│   │
 │   └── langgraph/               #   LangGraph/LangChain/DeepAgents 框架 (✅ v0.3)
-│       ├── __init__.py          #     导出 LangGraphEventConverter, wrap_agent, LangChainToolAdapter, create_model, create_mcp_tools
+│       ├── __init__.py          #     导出 LangGraphEventConverter, wrap_agent, LangChainToolAdapter, create_model, create_mcp_tools, WishubMemoryMiddleware
 │       ├── converter.py         #     LangGraphEventConverter (astream_events → CanonicalEvent)
-│       ├── wrap_agent.py        #     wrap_agent() 糖函数
+│       ├── wrap_agent.py        #     wrap_agent() 糖函数 (注入 config: user_id, thread_id)
 │       ├── tool_adapter.py      #     LangChainToolAdapter (ToolInfo → StructuredTool)
-│       └── builtin.py           #     create_model() / create_mcp_tools() 一行接入
+│       ├── builtin.py           #     create_model() / create_mcp_tools() 一行接入
+│       └── memory_middleware.py #     WishubMemoryMiddleware — DeepAgents 记忆中间件
 │
 ├── server/                      # Server 层
 │   ├── __init__.py

{wisruntime-0.4.2 → wisruntime-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wisruntime"
-version = "0.4.2"
+version = "0.5.0"
 description = "企业级 Agent Runtime SDK — 让 AI 工程师专注 Agent 能力开发，无需关心底层基础设施"
 readme = "README.md"
 requires-python = ">=3.11"

{wisruntime-0.4.2 → wisruntime-0.5.0}/wisruntime/adapters/__init__.py

@@ -2,6 +2,7 @@
 
 按框架分子目录组织：
 - langgraph/ — LangGraph/LangChain/DeepAgents 框架适配
+- memory/ — DEPRECATED: 已移至 wisruntime.memory（此处仅为兼容性 shim）
 - (未来) llamaindex/ — LlamaIndex 框架适配
 - (未来) crewai/ — CrewAI 框架适配
 

{wisruntime-0.4.2 → wisruntime-0.5.0}/wisruntime/adapters/langgraph/__init__.py

@@ -6,10 +6,16 @@
 - LangChainToolAdapter: ToolClient → StructuredTool 适配器
 - create_model: 快速创建 LangChain 模型实例
 - create_mcp_tools: 一行获取 MCP 工具列表
+- WishubMemoryMiddleware: Wishub 记忆检索中间件
 """
 
 from wisruntime.adapters.langgraph.builtin import create_mcp_tools, create_model
 from wisruntime.adapters.langgraph.converter import LangGraphEventConverter
+from wisruntime.adapters.langgraph.memory_middleware import (
+    WishubMemoryMiddleware,
+    WishubMemoryState,
+    WishubMemoryStateUpdate,
+)
 from wisruntime.adapters.langgraph.tool_adapter import LangChainToolAdapter
 from wisruntime.adapters.langgraph.wrap_agent import wrap_agent
 
@@ -19,4 +25,7 @@ __all__ = [
     "LangChainToolAdapter",
     "create_model",
     "create_mcp_tools",
+    "WishubMemoryMiddleware",
+    "WishubMemoryState",
+    "WishubMemoryStateUpdate",
 ]

wisruntime-0.5.0/wisruntime/adapters/langgraph/_utils.py

@@ -0,0 +1,34 @@
+"""Utility functions for LangGraph middleware."""
+
+from typing import Optional
+
+from langchain_core.messages import SystemMessage
+
+
+def append_to_system_message(
+    system_message: Optional[SystemMessage], content: str
+) -> SystemMessage:
+    """Append content to an existing system message or create a new one.
+
+    Args:
+        system_message: Existing system message or None
+        content: Content to append
+
+    Returns:
+        SystemMessage with appended content
+    """
+    if system_message is None:
+        return SystemMessage(content=content)
+
+    # Get existing content
+    existing_content = system_message.content
+    if isinstance(existing_content, str):
+        new_content = existing_content + "\n\n" + content
+    elif isinstance(existing_content, list):
+        # Handle list of content blocks
+        new_content = existing_content + [{"type": "text", "text": content}]
+    else:
+        new_content = str(existing_content) + "\n\n" + content
+
+    # Create new message with combined content
+    return SystemMessage(content=new_content)

wisruntime-0.5.0/wisruntime/adapters/langgraph/memory_middleware.py

@@ -0,0 +1,223 @@
+"""Wishub Memory Middleware for DeepAgents。"""
+
+import logging
+from typing import TYPE_CHECKING, Annotated, NotRequired, TypedDict, Optional
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from langchain_core.runnables import RunnableConfig
+    from langgraph.runtime import Runtime
+
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ContextT,
+    ModelRequest,
+    ModelResponse,
+    PrivateStateAttr,
+    ResponseT,
+    TracePolicy,
+    omit_payload,
+)
+
+from wisruntime.memory import WishubMemoryClient, MemoryPromptFormatter, MemoryItem
+from wisruntime.adapters.langgraph._utils import append_to_system_message
+
+logger = logging.getLogger(__name__)
+
+
+class WishubMemoryState(AgentState):
+    """Wishub Memory Middleware 的状态 schema。"""
+
+    retrieved_memories: NotRequired[Annotated[list[MemoryItem], PrivateStateAttr]]
+
+
+class WishubMemoryStateUpdate(TypedDict):
+    """状态更新。"""
+
+    retrieved_memories: list[MemoryItem]
+
+
+class WishubMemoryMiddleware(AgentMiddleware[WishubMemoryState, ContextT, ResponseT]):
+    """Wishub 记忆检索中间件（DeepAgents）。
+
+    在 Agent 执行前，根据用户查询检索相关记忆，并注入到系统提示词中。
+
+    Example:
+        >>> from wisruntime.adapters.langgraph import WishubMemoryMiddleware
+        >>> from deepagents import create_deep_agent
+        >>>
+        >>> middleware = WishubMemoryMiddleware(
+        ...     base_url="https://aip-open-api-dev.infinitus.com.cn",
+        ...     api_key="your-api-key",
+        ...     namespaces=["preference", "history"],
+        ...     top_k=5,
+        ... )
+        >>>
+        >>> agent = create_deep_agent(
+        ...     model=model,
+        ...     middleware=[middleware],
+        ... )
+    """
+
+    trace_policy = TracePolicy(process_inputs=omit_payload)
+    state_schema = WishubMemoryState
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        namespaces: Optional[list[str]] = None,
+        top_k: int = 5,
+        timeout: float = 5.0,
+        include_guidelines: bool = True,
+    ):
+        """初始化 Wishub Memory 中间件。
+
+        Args:
+            base_url: Wishub Memory API 基础地址
+            api_key: API Key (智能体通道鉴权)
+            namespaces: 可选的命名空间过滤列表
+            top_k: 检索记忆数量上限（默认5）
+            timeout: API 请求超时时间（秒）
+            include_guidelines: 是否在提示词中包含使用指南
+        """
+        self.client = WishubMemoryClient(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+        )
+        self.namespaces = namespaces
+        self.top_k = top_k
+        self.include_guidelines = include_guidelines
+        self.formatter = MemoryPromptFormatter()
+
+    def _extract_user_query(self, state: WishubMemoryState) -> Optional[str]:
+        """从状态中提取用户最后一条消息作为检索查询。
+
+        Args:
+            state: Agent 状态
+
+        Returns:
+            用户查询文本，如果没有则返回 None
+        """
+        messages = state.get("messages", [])
+
+        # 从后往前找第一条用户消息
+        for msg in reversed(messages):
+            # LangChain 消息对象
+            if hasattr(msg, "type") and msg.type == "human":
+                content = msg.content
+                if isinstance(content, str):
+                    return content.strip()
+            # 字典格式消息
+            elif isinstance(msg, dict) and msg.get("role") == "user":
+                content = msg.get("content", "")
+                if isinstance(content, str):
+                    return content.strip()
+
+        return None
+
+    def _get_user_id(self, state: WishubMemoryState, config: "RunnableConfig") -> Optional[str]:
+        """获取 user_id，支持多种来源（按优先级）。
+
+        优先级：
+        1. config.configurable.user_id（标准方式，来自 wrap_agent）
+        2. state.user_id（兼容方案，如果有人直接在 state 里传）
+        3. None（无法获取，跳过检索）
+
+        Args:
+            state: Agent 状态
+            config: Runnable 配置
+
+        Returns:
+            user_id 或 None
+        """
+        # 方案1：从 config 读取（推荐）
+        user_id = config.get("configurable", {}).get("user_id")
+        if user_id:
+            return user_id
+
+        # 方案2：从 state 读取（兼容）
+        user_id = state.get("user_id")
+        if user_id:
+            logger.debug("user_id found in state (fallback), consider using config.configurable")
+            return user_id
+
+        # 方案3：无法获取
+        return None
+
+    async def abefore_agent(
+        self,
+        state: WishubMemoryState,
+        runtime: "Runtime",
+        config: "RunnableConfig",
+    ) -> Optional[WishubMemoryStateUpdate]:
+        """在 Agent 执行前检索记忆。"""
+
+        # 跳过重复检索
+        if "retrieved_memories" in state:
+            logger.debug("Memories already retrieved, skipping")
+            return None
+
+        # 提取用户查询
+        query = self._extract_user_query(state)
+        if not query:
+            logger.debug("No user query found, skipping memory retrieval")
+            return WishubMemoryStateUpdate(retrieved_memories=[])
+
+        # 提取 userId
+        user_id = self._get_user_id(state, config)
+        if not user_id:
+            logger.warning(
+                "Cannot retrieve memories: user_id not found. "
+                "Check that wrap_agent is passing request.user to config.configurable"
+            )
+            return WishubMemoryStateUpdate(retrieved_memories=[])
+
+        # 调用检索接口
+        logger.debug(f"Retrieving memories for user={user_id}, query_len={len(query)}")
+        memories = await self.client.retrieve_memories(
+            query=query,
+            user_id=user_id,
+            namespaces=self.namespaces,
+            top_k=self.top_k,
+        )
+
+        logger.info(f"Retrieved {len(memories)} memories for user {user_id}")
+        return WishubMemoryStateUpdate(retrieved_memories=memories)
+
+    def modify_request(
+        self,
+        request: ModelRequest[ContextT],
+    ) -> ModelRequest[ContextT]:
+        """将检索到的记忆注入系统提示词。"""
+
+        memories = request.state.get("retrieved_memories", [])
+
+        # 格式化记忆提示词
+        memory_prompt = self.formatter.format_memories_prompt(
+            memories,
+            include_guidelines=self.include_guidelines,
+        )
+
+        # 注入到系统消息
+        new_system_message = append_to_system_message(
+            request.system_message,
+            memory_prompt,
+        )
+
+        if new_system_message is request.system_message:
+            return request
+
+        return request.override(system_message=new_system_message)
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest[ContextT],
+        handler: "Callable[[ModelRequest[ContextT]], Awaitable[ModelResponse[ResponseT]]]",
+    ) -> ModelResponse[ResponseT]:
+        """异步包装模型调用。"""
+        modified_request = self.modify_request(request)
+        return await handler(modified_request)

{wisruntime-0.4.2 → wisruntime-0.5.0}/wisruntime/adapters/langgraph/wrap_agent.py

@@ -70,8 +70,17 @@ def _build_astream_events_invoker(agent_graph):
         messages = _agent_request_to_messages(request)
         converter = LangGraphEventConverter()
 
+        # 构建 config，将 AgentRequest 元信息注入 configurable
+        config = {
+            "configurable": {
+                "thread_id": request.conversation_id or "default",
+                "user_id": request.user_id,
+            }
+        }
+
         async for event in agent_graph.astream_events(
             {"messages": messages},
+            config=config,
             version="v2",
         ):
             for item in converter.convert(event):
@@ -87,9 +96,18 @@ def _build_astream_invoker(agent_graph, stream_mode: str):
         messages = _agent_request_to_messages(request)
         converter = LangGraphEventConverter()
 
+        # 构建 config，将 AgentRequest 元信息注入 configurable
+        config = {
+            "configurable": {
+                "thread_id": request.conversation_id or "default",
+                "user_id": request.user_id,
+            }
+        }
+
         async for event in agent_graph.astream(
             {"messages": messages},
             stream_mode=stream_mode,
+            config=config,
         ):
             for item in converter.convert(event):
                 yield item

wisruntime-0.5.0/wisruntime/adapters/memory/__init__.py

@@ -0,0 +1,35 @@
+"""
+Deprecated: This module has moved to wisruntime.memory
+
+This compatibility shim will be removed in a future version.
+Please update your imports:
+    from wisruntime.adapters.memory import X  # Old (deprecated)
+    from wisruntime.memory import X           # New
+"""
+
+import warnings
+
+# Issue deprecation warning
+warnings.warn(
+    "wisruntime.adapters.memory is deprecated and will be removed in a future version. "
+    "Please use wisruntime.memory instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Re-export from new location for backward compatibility
+from wisruntime.memory import (
+    WishubMemoryClient,
+    MemoryPromptFormatter,
+    MemoryItem,
+    RetrieveRequest,
+    RetrieveResponse,
+)
+
+__all__ = [
+    "WishubMemoryClient",
+    "MemoryPromptFormatter",
+    "MemoryItem",
+    "RetrieveRequest",
+    "RetrieveResponse",
+]

wisruntime-0.5.0/wisruntime/memory/__init__.py

@@ -0,0 +1,17 @@
+"""
+Wisruntime Memory Module
+
+Provides client and utilities for interacting with Wishub Memory API.
+"""
+
+from .client import WishubMemoryClient
+from .formatter import MemoryPromptFormatter
+from .model import MemoryItem, RetrieveRequest, RetrieveResponse
+
+__all__ = [
+    "WishubMemoryClient",
+    "MemoryPromptFormatter",
+    "MemoryItem",
+    "RetrieveRequest",
+    "RetrieveResponse",
+]

wisruntime-0.5.0/wisruntime/memory/client.py

@@ -0,0 +1,108 @@
+"""Wishub Memory API 客户端（框架无关）。"""
+
+import logging
+from typing import Optional
+
+import httpx
+
+from wisruntime.memory.model import (
+    MemoryItem,
+    RetrieveResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class WishubMemoryClient:
+    """Wishub 记忆检索客户端。"""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = 5.0,
+    ):
+        """初始化记忆客户端。
+
+        Args:
+            base_url: API 基础地址，如 "https://aip-open-api-dev.infinitus.com.cn"
+            api_key: API Key (智能体通道鉴权)
+            timeout: 请求超时时间（秒）
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._endpoint = f"{self.base_url}/wishub-memory/openapi/v1/memories/retrieve"
+
+    async def retrieve_memories(
+        self,
+        *,
+        query: str,
+        user_id: str,
+        namespaces: Optional[list[str]] = None,
+        top_k: int = 5,
+    ) -> list[MemoryItem]:
+        """检索相关记忆。
+
+        Args:
+            query: 用户查询文本（用于语义检索）
+            user_id: 用户ID（智能体通道必填）
+            namespaces: 可选的命名空间过滤
+            top_k: 返回记忆数量上限（默认5，最大20）
+
+        Returns:
+            记忆列表。降级或失败时返回空列表（不抛异常）
+        """
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        payload = {
+            "query": query,
+            "userId": user_id,
+            "topK": min(top_k, 20),
+        }
+
+        if namespaces:
+            payload["namespaces"] = namespaces
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(
+                    self._endpoint,
+                    json=payload,
+                    headers=headers,
+                )
+
+                logger.debug(
+                    f"Memory retrieval: user={user_id}, query_len={len(query)}, "
+                    f"status={response.status_code}"
+                )
+
+                if response.status_code != 200:
+                    logger.warning(
+                        f"Memory API returned {response.status_code}: {response.text[:200]}"
+                    )
+                    return []
+
+                result = RetrieveResponse(**response.json())
+
+                if not result.success:
+                    logger.warning(f"Memory retrieval failed: {result.code} - {result.msg}")
+                    return []
+
+                if result.data.degraded:
+                    logger.warning("Memory service degraded, returning empty list")
+                    return []
+
+                logger.info(f"Retrieved {len(result.data.memories)} memories for user {user_id}")
+                return result.data.memories
+
+        except httpx.TimeoutException:
+            logger.warning(f"Memory retrieval timeout after {self.timeout}s")
+            return []
+        except Exception as e:
+            logger.error(f"Memory retrieval error: {e}", exc_info=True)
+            return []

wisruntime-0.5.0/wisruntime/memory/formatter.py

@@ -0,0 +1,67 @@
+"""记忆提示词格式化器（框架无关）。"""
+
+from wisruntime.memory.model import MemoryItem
+
+
+class MemoryPromptFormatter:
+    """将检索到的记忆格式化为提示词片段。"""
+
+    @staticmethod
+    def format_memories_prompt(
+        memories: list[MemoryItem],
+        *,
+        include_guidelines: bool = True,
+    ) -> str:
+        """格式化记忆为系统提示词片段。
+
+        Args:
+            memories: 记忆列表
+            include_guidelines: 是否包含使用指南
+
+        Returns:
+            格式化的 XML 提示词片段
+        """
+        if not memories:
+            return MemoryPromptFormatter._empty_memory_prompt(include_guidelines)
+
+        # 构建记忆内容
+        memory_items = []
+        for i, mem in enumerate(memories, 1):
+            memory_items.append(
+                f"记忆 {i} (相关度: {mem.score:.2f}):\n{mem.content.strip()}"
+            )
+
+        memories_text = "\n\n".join(memory_items)
+
+        prompt = f"""<user_memory>
+以下是根据用户问题检索到的相关记忆：
+
+{memories_text}
+</user_memory>"""
+
+        if include_guidelines:
+            prompt += """
+
+<memory_usage_guidelines>
+- 上述记忆是从历史对话中检索出的相关信息
+- 相关度分数仅供参考，不同记忆引擎的分数体系不可比
+- 请结合当前问题上下文合理使用这些记忆
+- 如果记忆内容与用户当前问题不符，请以用户当前的明确表述为准
+- 记忆可能包含过时信息，请在回答时注意时效性
+</memory_usage_guidelines>"""
+
+        return prompt
+
+    @staticmethod
+    def _empty_memory_prompt(include_guidelines: bool) -> str:
+        """无记忆时的占位提示。"""
+        prompt = "<user_memory>\n(未检索到相关历史记忆)\n</user_memory>"
+
+        if include_guidelines:
+            prompt += """
+
+<memory_usage_guidelines>
+- 当前未检索到相关历史记忆，请基于用户当前问题直接回答
+</memory_usage_guidelines>"""
+
+        return prompt

wisruntime-0.5.0/wisruntime/memory/model.py

@@ -0,0 +1,45 @@
+"""记忆检索数据模型（框架无关）。"""
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MemoryItem(BaseModel):
+    """单条记忆项。"""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    memory_id: str = Field(alias="memoryId")
+    content: str
+    score: float
+    metadata: Optional[dict] = None
+    user_id: str = Field(alias="userId")
+    app_code: Optional[str] = Field(None, alias="appCode")
+    run_id: Optional[str] = Field(None, alias="runId")
+    created_at: str = Field(alias="createdAt")
+
+
+class RetrieveRequest(BaseModel):
+    """记忆检索请求。"""
+
+    query: str
+    user_id: str = Field(alias="userId")
+    namespaces: Optional[list[str]] = None
+    top_k: int = Field(5, alias="topK")
+
+
+class RetrieveResponseData(BaseModel):
+    """检索响应数据。"""
+
+    memories: list[MemoryItem]
+    degraded: bool = False
+
+
+class RetrieveResponse(BaseModel):
+    """记忆检索响应。"""
+
+    success: bool
+    code: str
+    msg: str
+    data: RetrieveResponseData

{wisruntime-0.4.2 → wisruntime-0.5.0/wisruntime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wisruntime
-Version: 0.4.2
+Version: 0.5.0
 Summary: 企业级 Agent Runtime SDK — 让 AI 工程师专注 Agent 能力开发，无需关心底层基础设施
 Author: WIS Team
 License-Expression: MIT
@@ -713,6 +713,30 @@ def create_server(
 └─────────────────────────────────────────────────────────────────────┘
 
 故事 6 ──────────────────────────────────────────────────────────────
+│  用户故事: 作为 AI 工程师，我可以用 WishubMemoryMiddleware 为我的         │
+│           DeepAgents Agent 添加长期记忆能力，自动检索用户历史对话记忆      │
+│                                                                   │
+│  验收标准:                                                          │
+│    from deepagents import create_deep_agent                          │
+│    from wisruntime.adapters.langgraph import WishubMemoryMiddleware  │
+│    from wisruntime.memory import WishubMemoryClient         │
+│                                                                   │
+│    memory_client = WishubMemoryClient(                              │
+│        base_url="https://wishub.example.com",                        │
+│        api_key="your-api-key"                                        │
+│    )                                                                │
+│    middleware = WishubMemoryMiddleware(                             │
+│        client=memory_client,                                         │
+│        namespaces=["user_profile", "preferences"],                   │
+│        top_k=5                                                       │
+│    )                                                                │
+│    agent = create_deep_agent(model=model, middlewares=[middleware]) │
+│    # → Agent 在每次对话前自动检索相关历史记忆                          │
+│    # → 记忆以结构化 XML 格式注入系统提示词                             │
+│    # → 支持优雅降级: API 超时/失败时返回空列表，不影响对话             │
+└─────────────────────────────────────────────────────────────────────┘
+
+故事 7 ──────────────────────────────────────────────────────────────
 │  用户故事: 作为 AI 工程师，我的 Agent 对话历史可以自动持久化到           │
 │           WIS Hub Checkpoint 服务，支持断点续传                         │
 │                                                                   │
@@ -782,16 +806,36 @@ Phase 3: 平台能力接入 (MCP ✅ 已完成 — v0.3)
      分页发现 / 详情 / 302 预签名下载 / 严格 SemVer 版本, create_skill_sources() deepagents 集成
   □ SandboxClient + Sandbox 数据模型
 
+Phase 3.5: 记忆能力接入 (✅ 已完成 — v0.4)
+═══════════════════════════════
+  目标: 用户故事 6 — WishubMemoryMiddleware 长期记忆
+
+  ✅ memory/ 模块: MemoryItem, RetrieveRequest, RetrieveResponse 数据模型
+  ✅ WishubMemoryClient — 异步 HTTP 客户端，对接 Wishub Memory API
+     - 优雅降级: 超时/错误返回空列表，不影响对话
+     - 完整日志: debug/info/warning/error 四级
+  ✅ MemoryPromptFormatter — 记忆列表 → 结构化 XML 提示词片段
+     - 支持相关度评分显示
+     - 空记忆占位符
+     - 可选使用指南
+  ✅ WishubMemoryMiddleware — DeepAgents 中间件
+     - abefore_agent: 检索记忆并存入 state
+     - modify_request: 注入记忆到系统提示词
+     - 跳过重复检索
+     - user_id/query 缺失时优雅处理
+  ✅ wrap_agent config 注入 — user_id, thread_id 传递到 LangGraph config.configurable
+  ✅ 完整测试覆盖 (39 个测试用例全部通过)
+
 Phase 4: 高级特性
 ════════════════
-  目标: 用户故事 6 — Checkpoint、多协议
+  目标: 用户故事 7 — Checkpoint、多协议
 
   □ CheckpointClient + 自动持久化
   □ AGUIHandler
   □ Stop endpoint
   □ ApiKeyMiddleware
 
-Phase 4: 多框架 + 多协议
+Phase 5: 多框架 + 多协议
 ══════════════════════
   目标: 验证可扩展性
 
@@ -817,12 +861,19 @@ wisruntime/
 │   └── client.py                #   MCPClient(ToolClient) — 薄封装标准 mcp 包
 │
 ├── adapters/                    # Adapter + Capability Bridge
+│   ├── memory/                  #   Memory 记忆检索适配器 (✅ v0.4)
+│   │   ├── __init__.py          #     导出 WishubMemoryClient, MemoryPromptFormatter, MemoryItem
+│   │   ├── model.py             #     MemoryItem, RetrieveRequest, RetrieveResponse (Pydantic 模型)
+│   │   ├── client.py            #     WishubMemoryClient — 异步 HTTP 客户端，优雅降级
+│   │   └── formatter.py         #     MemoryPromptFormatter — 记忆列表 → XML 提示词片段
+│   │
 │   └── langgraph/               #   LangGraph/LangChain/DeepAgents 框架 (✅ v0.3)
-│       ├── __init__.py          #     导出 LangGraphEventConverter, wrap_agent, LangChainToolAdapter, create_model, create_mcp_tools
+│       ├── __init__.py          #     导出 LangGraphEventConverter, wrap_agent, LangChainToolAdapter, create_model, create_mcp_tools, WishubMemoryMiddleware
 │       ├── converter.py         #     LangGraphEventConverter (astream_events → CanonicalEvent)
-│       ├── wrap_agent.py        #     wrap_agent() 糖函数
+│       ├── wrap_agent.py        #     wrap_agent() 糖函数 (注入 config: user_id, thread_id)
 │       ├── tool_adapter.py      #     LangChainToolAdapter (ToolInfo → StructuredTool)
-│       └── builtin.py           #     create_model() / create_mcp_tools() 一行接入
+│       ├── builtin.py           #     create_model() / create_mcp_tools() 一行接入
+│       └── memory_middleware.py #     WishubMemoryMiddleware — DeepAgents 记忆中间件
 │
 ├── server/                      # Server 层
 │   ├── __init__.py

{wisruntime-0.4.2 → wisruntime-0.5.0}/wisruntime.egg-info/SOURCES.txt

@@ -12,14 +12,21 @@ wisruntime.egg-info/requires.txt
 wisruntime.egg-info/top_level.txt
 wisruntime/adapters/__init__.py
 wisruntime/adapters/langgraph/__init__.py
+wisruntime/adapters/langgraph/_utils.py
 wisruntime/adapters/langgraph/builtin.py
 wisruntime/adapters/langgraph/converter.py
+wisruntime/adapters/langgraph/memory_middleware.py
 wisruntime/adapters/langgraph/tool_adapter.py
 wisruntime/adapters/langgraph/wrap_agent.py
+wisruntime/adapters/memory/__init__.py
 wisruntime/conversation/__init__.py
 wisruntime/conversation/client.py
 wisruntime/conversation/model.py
 wisruntime/conversation/recorder.py
+wisruntime/memory/__init__.py
+wisruntime/memory/client.py
+wisruntime/memory/formatter.py
+wisruntime/memory/model.py
 wisruntime/server/__init__.py
 wisruntime/server/dify_handler.py
 wisruntime/server/invoker.py