♻️ refactor(core): 重构 AI 编排框架与记忆及 RAG 子系统 (#2149)

* ♻️ refactor(core): 重构 AI 编排框架与记忆及 RAG 子系统

- 【重构】重构 `BaseRunnable` 并引入统一的 `RunIntent` 意图载体，规范 Agent、Team 和 Workflow 的执行流
- 【解耦】将中期记忆槽和长期向量记忆从 `MemoryConfig` 中解耦，转为独立的能力组件与工具箱进行管理
- 【记忆】移除 `MemoryReader` 和 `MemoryWriter`，统一封装为 `SessionMemoryContext` 会话记忆门面
- 【RAG】重构检索器与存储后端接口，统一采用 `QueryRequest` 进行多维度联合检索，并引入 `InMemoryScorer` 提升打分性能
- 【事件】优化 `EventBus` 异步事件分发机制，引入队列机制确保事件按序处理，避免并发竞态问题
- 【依赖注入】移除 `memory` 注入项，优化 `DependencyInjector` 的签名解析缓存以提升性能

* 🚨 auto fix by pre-commit hooks

---------

Co-authored-by: webjoin111 <455457521@qq.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

zhenxun/services/ai/context/rag/utils.py

@@ -1,5 +1,10 @@
+from typing import Any
+
 import numpy as np
 
+from zhenxun.services.ai.context.rag.models import BaseRecord, SearchResult
+from zhenxun.services.ai.utils.logger import log_rag as logger
+
 
 def cosine_similarity(vec1: list[float], vec2: list[float]) -> float:
     """使用 numpy 计算两组向量的余弦相似度"""
@@ -10,3 +15,79 @@ def cosine_similarity(vec1: list[float], vec2: list[float]) -> float:
     if norm1 == 0 or norm2 == 0:
         return 0.0
     return float(np.dot(v1, v2) / (norm1 * norm2))
+
+
+def normalize_vector(vec: list[float] | np.ndarray) -> np.ndarray:
+    """将一维向量转化为 float32 数组并进行 L2 归一化"""
+    v = np.array(vec, dtype=np.float32)
+    norm = np.linalg.norm(v)
+    if norm == 0:
+        return v
+    return v / norm
+
+
+def normalize_matrix(mat: np.ndarray) -> np.ndarray:
+    """将二维矩阵的每一行进行 L2 归一化"""
+    norms = np.linalg.norm(mat, axis=1, keepdims=True)
+    norms[norms == 0] = 1.0
+    return mat / norms
+
+
+def normalize_query_text(query: Any) -> str:
+    """辅助函数：提取各种输入形式（如字符串、平台Message对象）的纯文本用于检索"""
+    if isinstance(query, str):
+        return query
+    if hasattr(query, "extract_plain_text"):
+        return query.extract_plain_text()
+    return str(query) if query is not None else ""
+
+
+class InMemoryScorer:
+    """提供内存级别的纯 Python 向量打分与 BM25 稀疏打分工具类"""
+
+    @staticmethod
+    def calculate_sparse_scores(
+        query: str, candidate_records: list[BaseRecord]
+    ) -> list[SearchResult]:
+        import jieba
+
+        tokens = set(jieba.lcut_for_search(query.lower()))
+        if not tokens:
+            return [SearchResult(record=r, score=0.1) for r in candidate_records]
+
+        results = []
+        for r in candidate_records:
+            content_lower = r.content.lower()
+            matched_count = sum(1 for t in tokens if t in content_lower)
+            score = matched_count / len(tokens) if tokens else 0.1
+            results.append(SearchResult(record=r, score=score))
+        return results
+
+    @staticmethod
+    def calculate_dense_scores(
+        query_embedding: list[float], candidate_records: list[BaseRecord]
+    ) -> list[SearchResult]:
+        if not candidate_records or not query_embedding:
+            return []
+
+        q_vec = normalize_vector(query_embedding)
+        vec_records = [r for r in candidate_records if r.embedding]
+        missing_records = [r for r in candidate_records if not r.embedding]
+
+        results = []
+        if vec_records:
+            try:
+                raw_mat = np.array([r.embedding for r in vec_records], dtype=np.float32)
+                norm_mat = normalize_matrix(raw_mat)
+                scores = norm_mat @ q_vec
+                for r, score in zip(vec_records, scores):
+                    results.append(SearchResult(record=r, score=float(score)))
+            except ValueError as e:
+                logger.warning(
+                    "⚠️ 维度不匹配，已安全跳过向量检索(降级)。原因: " + str(e)
+                )
+
+        for r in missing_records:
+            results.append(SearchResult(record=r, score=0.1))
+
+        return results