secagentx 3.0.0__py3-none-any.whl

backend/memory/manager.py

@@ -0,0 +1,204 @@
+"""
+MemoryManager — 记忆管理器（v2.4 M4）
+
+统一读写三层记忆：
+  1. SessionMemory   — 短期工作记忆（当前会话关键事实）
+  2. EpisodicMemory  — 情景记忆（历史研判案例，experiences 表）
+  3. SemanticMemory  — 语义记忆（高置信度事实向量沉淀）
+
+核心职责:
+  - build_context(text): 召回三层记忆，构造注入 system prompt 的记忆上下文
+  - remember_from_result(...): 从一次研判结果提取关键事实并分层写入
+  - 记忆注入带置信度 + 时间衰减，低置信度不注入（避免误导 LLM）
+
+设计纪律（延续项目纪律）:
+  - 所有记忆带置信度（来自确定性裁决），非 LLM 自拟
+  - 语义记忆仅沉淀高置信度（≥0.7）事实，防止噪声污染
+  - 记忆不可用（DB/Chroma 故障）→ 全部旁路，主链路永不阻断
+"""
+import logging
+from typing import Optional
+
+logger = logging.getLogger("secagentx.memory")
+
+# 记忆注入模板：插入 system prompt 的记忆上下文
+MEMORY_CONTEXT_TEMPLATE = """
+## 历史记忆（带置信度，仅供参考，不作为唯一依据）
+{items}
+
+> 记忆标注: 每条记忆带置信度；旧记忆可能已衰减。若记忆与当前证据冲突，以当前证据为准。
+"""
+
+
+class MemoryManager:
+    """三层记忆管理器。"""
+
+    def __init__(self, session_memory: Optional[dict] = None,
+                 episodic: Optional[object] = None,
+                 semantic: Optional[object] = None):
+        """
+        参数:
+          session_memory: dict {session_id: SessionMemory} 会话记忆注册表
+          episodic: EpisodicMemory 实例（可空）
+          semantic: SemanticMemory 实例（可空）
+        """
+        self._sessions = session_memory if session_memory is not None else {}
+        self.episodic = episodic
+        self.semantic = semantic
+
+    # ═══════════════ 会话记忆 ═══════════════
+    def get_session(self, session_id: str):
+        """获取/创建会话记忆。"""
+        if session_id not in self._sessions:
+            from .session_memory import SessionMemory
+            self._sessions[session_id] = SessionMemory(session_id=session_id)
+        return self._sessions[session_id]
+
+    def remember_session(self, session_id: str, content: str,
+                         category: str = "general", confidence: float = 0.5,
+                         metadata: Optional[dict] = None):
+        try:
+            self.get_session(session_id).remember(
+                content, category=category, confidence=confidence, metadata=metadata,
+            )
+        except Exception as e:
+            logger.debug("会话记忆写入失败（旁路）: %s", e)
+
+    # ═══════════════ 记忆上下文构建 ═══════════════
+    def build_context(self, text: str, session_id: str = "",
+                      top_k: int = 6) -> str:
+        """召回三层记忆，构造注入 system prompt 的记忆上下文。
+
+        返回 markdown 段落（空 → 不注入）。
+        """
+        items = []
+
+        # 1. 会话记忆（短期，当前会话）
+        if session_id:
+            try:
+                for f in self.get_session(session_id).to_context(limit=top_k):
+                    items.append(
+                        f"- [会话·{f['category']}] {f['content']}（置信度 {f['confidence']:.0%}）"
+                    )
+            except Exception:
+                pass
+
+        # 2. 情景记忆（历史案例）
+        if self.episodic is not None:
+            try:
+                import asyncio
+                episodes = asyncio.get_event_loop().run_until_complete(
+                    self.episodic.recall_similar(text, limit=3),
+                )
+                for ep in episodes:
+                    items.append(
+                        f"- [案例·{ep['scenario'][:40]}] 处置: {ep.get('outcome', '')[:80]}"
+                    )
+            except Exception:
+                pass
+
+        # 3. 语义记忆（长期向量）
+        if self.semantic is not None:
+            try:
+                for m in self.semantic.recall(text, k=top_k):
+                    items.append(
+                        f"- [语义·{m['category']}] {m['content']}（置信度 {m['confidence']:.0%}）"
+                    )
+            except Exception:
+                pass
+
+        if not items:
+            return ""
+        return MEMORY_CONTEXT_TEMPLATE.format(items="\n".join(items[:top_k]))
+
+    # ═══════════════ 研判结果沉淀 ═══════════════
+    def remember_from_result(self, session_id: str, text: str,
+                             agent_results: list = None,
+                             risk_scorecard: dict = None,
+                             verdict: dict = None) -> int:
+        """从一次研判结果提取关键事实并分层写入。返回写入条数。"""
+        count = 0
+        try:
+            # 1. 裁决级事实（高置信度 -> 沉淀）
+            if verdict:
+                v = verdict.get("verdict", "unknown")
+                conf = float(verdict.get("confidence", 0.0) or 0.0)
+                if v in ("malicious", "benign") and conf > 0:
+                    self.remember_session(
+                        session_id,
+                        f"分析 '{text[:50]}' 裁决为 {v}（置信度 {conf:.0%}）",
+                        category="verdict", confidence=conf,
+                        metadata={"verdict": v, "source_text": text[:200]},
+                    )
+                    count += 1
+                    # 高置信度恶意 -> 沉淀语义记忆（长期）
+                    if self.semantic is not None and conf >= 0.7:
+                        mid = self.semantic.add(
+                            f"确认 {v}: '{text[:80]}'（置信度 {conf:.0%}）",
+                            category="verdict", confidence=conf,
+                            metadata={"verdict": v},
+                        )
+                        if mid:
+                            count += 1
+
+            # 2. Agent 裁决级事实
+            for r in (agent_results or []):
+                aid = r.get("agent_id", "")
+                rv = r.get("verdict")
+                rc = float(r.get("confidence") or 0.0)
+                if rv in ("malicious", "benign") and rc >= 0.5:
+                    self.remember_session(
+                        session_id,
+                        f"{aid} 裁决 {rv}（置信度 {rc:.0%}）",
+                        category="agent_verdict", confidence=rc,
+                        metadata={"agent_id": aid, "verdict": rv},
+                    )
+                    count += 1
+
+            # 3. 风险评分级事实
+            if risk_scorecard:
+                score = risk_scorecard.get("risk_score")
+                level = risk_scorecard.get("risk_level")
+                if score is not None:
+                    self.remember_session(
+                        session_id,
+                        f"风险评分 {score}（{level}）",
+                        category="risk", confidence=0.8,
+                        metadata={"score": score, "level": level},
+                    )
+                    count += 1
+        except Exception as e:
+            logger.debug("记忆沉淀失败（旁路）: %s", e)
+        return count
+
+    # ═══════════════ 查询/管理 ═══════════════
+    def list_session_memory(self, session_id: str) -> list[dict]:
+        return self.get_session(session_id).facts
+
+    def clear_session(self, session_id: str):
+        self.get_session(session_id).clear()
+
+    async def stats(self) -> dict:
+        """记忆统计（async — episodic.count 为 async 方法）。"""
+        import asyncio
+        episodic_count = 0
+        semantic_count = 0
+        if self.episodic is not None:
+            try:
+                episodic_count = await self.episodic.count()
+            except Exception:
+                episodic_count = 0
+        if self.semantic is not None:
+            try:
+                semantic_count = self.semantic.count()
+            except Exception:
+                semantic_count = 0
+        return {
+            "sessions": len(self._sessions),
+            "episodic_count": episodic_count,
+            "semantic_count": semantic_count,
+        }
+
+
+__all__ = ["MemoryManager", "MEMORY_CONTEXT_TEMPLATE"]
+

backend/memory/semantic_memory.py

@@ -0,0 +1,156 @@
+"""
+SemanticMemory — 语义记忆（v2.4 M4）
+
+长期向量记忆：将高价值事实（已确认 IOC、资产偏好、历史结论）写入 ChromaDB
+独立 collection `session_memory`，支持：
+  - add: 写入带置信度的语义事实
+  - recall: 向量相似度召回（可用本地哈希嵌入降级）
+  - forget: 按 ID 删除
+  - count: 记忆条数
+
+设计纪律:
+  - 写入时必须带置信度阈值（低于阈值不沉淀，避免噪声污染长期记忆）
+  - 召回结果带 distance 分数，低相似度（高距离）不注入
+"""
+import hashlib
+import time
+import logging
+from typing import Optional
+
+logger = logging.getLogger("secagentx.memory")
+
+# 默认 collection 名
+COLLECTION_NAME = "session_memory"
+# 写入置信度阈值
+MIN_CONFIDENCE_TO_STORE = 0.7
+# 归一化距离阈值：超过则视为"不相关"，不注入
+MAX_DISTANCE = 1.2
+
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+
+# 嵌入维度（本地哈希降级方案）
+EMBEDDING_DIM = 64
+
+
+def _hash_embed(text: str) -> list[float]:
+    """本地哈希嵌入降级方案（无模型时使用）：
+    对文本提取 2~5-gram，MD5 哈希后映射到固定维度，按词频归一化。
+    """
+    vec = [0.0] * EMBEDDING_DIM
+    ngrams = set()
+    for n in range(2, 6):
+        for i in range(len(text) - n + 1):
+            gram = text[i:i + n]
+            h = int(hashlib.md5(gram.encode('utf-8')).hexdigest(), 16)
+            ngrams.add(h % EMBEDDING_DIM)
+    for idx in ngrams:
+        vec[idx] += 1.0
+    norm = sum(x * x for x in vec) ** 0.5
+    if norm > 0:
+        vec = [x / norm for x in vec]
+    return vec
+
+
+class SemanticMemory:
+    """语义记忆 — 长期向量记忆（ChromaDB + 本地哈希降级）。"""
+
+    def __init__(self, vector_store=None, min_confidence: float = MIN_CONFIDENCE_TO_STORE):
+        self.vector_store = vector_store
+        self.min_confidence = min_confidence
+
+    def _store_ready(self) -> bool:
+        return self.vector_store is not None
+
+    def add(self, content: str, category: str = "general",
+            confidence: float = 0.5, metadata: dict = None) -> Optional[str]:
+        """写入一条语义记忆（低于置信度阈值不沉淀）。"""
+        if confidence < self.min_confidence:
+            logger.debug("语义记忆跳过低置信度事实: %.2f < %.2f", confidence, self.min_confidence)
+            return None
+        if not self._store_ready():
+            return None
+        mid = f"mem-{int(time.time() * 1000)}-{hashlib.md5(content.encode('utf-8')).hexdigest()[:6]}"
+        meta = dict(metadata or {})
+        meta["category"] = category
+        meta["confidence"] = confidence
+        meta["created_at"] = time.time()
+        try:
+            emb = _hash_embed(content)
+            self.vector_store.add_documents(
+                COLLECTION_NAME,
+                ids=[mid],
+                documents=[content],
+                metadatas=[meta],
+                embeddings=[emb],
+            )
+            return mid
+        except Exception as e:
+            logger.debug("语义记忆写入失败（旁路）: %s", e)
+            return None
+
+    def recall(self, query: str, k: int = 5, category: str = None) -> list[dict]:
+        """向量召回相似记忆，过滤距离过远 + 可选按类别过滤。"""
+        if not self._store_ready():
+            return []
+        try:
+            emb = _hash_embed(query)
+            items = self.vector_store.similarity_search(
+                COLLECTION_NAME, k=k * 3, query_embeddings=emb,
+            )
+            out = []
+            for it in items:
+                if it.get("distance", 0) > MAX_DISTANCE:
+                    continue
+                meta = it.get("metadata") or {}
+                if category and meta.get("category") != category:
+                    continue
+                out.append({
+                    "id": it.get("id"),
+                    "content": it.get("document", ""),
+                    "category": meta.get("category", "general"),
+                    "confidence": meta.get("confidence", 0.5),
+                    "distance": round(it.get("distance", 0), 4),
+                    "created_at": meta.get("created_at", 0),
+                })
+            return out[:k]
+        except Exception as e:
+            logger.debug("语义记忆召回失败（旁路）: %s", e)
+            return []
+
+    def count(self) -> int:
+        if not self._store_ready():
+            return 0
+        try:
+            return self.vector_store.count(COLLECTION_NAME)
+        except Exception:
+            return 0
+
+    def forget(self, mem_id: str) -> bool:
+        """删除单条记忆（按 ID）。"""
+        if not self._store_ready():
+            return False
+        try:
+            coll = self.vector_store.get_or_create_collection(COLLECTION_NAME)
+            coll.delete(ids=[mem_id])
+            return True
+        except Exception as e:
+            logger.debug("语义记忆删除失败（旁路）: %s", e)
+            return False
+
+    def clear(self) -> bool:
+        """清空全部语义记忆。"""
+        if not self._store_ready():
+            return False
+        try:
+            self.vector_store.delete_collection(COLLECTION_NAME)
+            return True
+        except Exception:
+            return False
+
+
+__all__ = ["SemanticMemory", "_hash_embed", "COLLECTION_NAME"]
+

backend/memory/session_memory.py

@@ -0,0 +1,102 @@
+"""
+SessionMemory — 短期会话记忆（v2.4 M4）
+
+维护当前会话的关键事实列表，支持：
+  - remember: 写入结构化事实（IP/CVE/MITRE/裁决/置信度等）
+  - recall:   按类型/关键词召回
+  - 容量限制: 超限自动压缩（丢最旧）
+  - 时间衰减: 旧记忆置信度打折（权重随时间衰减，防止误导）
+
+设计纪律:
+  - 记忆条目必须带置信度（来自确定性裁决，非 LLM 自拟）
+  - 过期/衰减的记忆在召回时标注，注入 system prompt 时降低优先级
+"""
+import time
+from typing import Optional
+
+# 默认单会话记忆容量
+DEFAULT_MAX_FACTS = 50
+# 记忆半衰期（秒）— 超过后置信度衰减
+DEFAULT_HALF_LIFE = 3600  # 1 小时
+
+
+class SessionMemory:
+    """会话工作记忆 — 线程内单实例，每个会话独立。"""
+
+    def __init__(self, session_id: str = "", max_facts: int = DEFAULT_MAX_FACTS,
+                 half_life: float = DEFAULT_HALF_LIFE):
+        self.session_id = session_id
+        self.max_facts = max_facts
+        self.half_life = half_life
+        self.facts: list[dict] = []  # 按时间升序
+
+    def remember(self, content: str, category: str = "general",
+                 confidence: float = 0.5, metadata: Optional[dict] = None) -> dict:
+        """写入一条结构化记忆。category 建议: ip/ioc/cve/mitre/verdict/context。"""
+        now = time.time()
+        fact = {
+            "id": f"{self.session_id}-{now:.0f}-{len(self.facts)}",
+            "content": content,
+            "category": category,
+            "confidence": float(confidence),
+            "created_at": now,
+            "metadata": metadata or {},
+        }
+        # 去重：同一 category + 高相似内容（简单用内容前缀）-> 更新而非追加
+        for existing in self.facts:
+            if existing["category"] == category and existing["content"][:50] == content[:50]:
+                existing["content"] = content
+                existing["confidence"] = float(confidence)
+                existing["created_at"] = now
+                existing["metadata"] = metadata or {}
+                return existing
+        self.facts.append(fact)
+        # 容量限制：超限丢最旧
+        if len(self.facts) > self.max_facts:
+            self.facts = self.facts[-self.max_facts:]
+        return fact
+
+    def recall(self, category: Optional[str] = None, keyword: str = "",
+               limit: int = 10, with_decay: bool = True) -> list[dict]:
+        """召回记忆。with_decay=True 时旧记忆置信度按半衰期衰减。"""
+        now = time.time()
+        results = []
+        for f in self.facts:
+            if category and f["category"] != category:
+                continue
+            if keyword and keyword.lower() not in f["content"].lower():
+                continue
+            item = dict(f)
+            if with_decay:
+                age = now - f["created_at"]
+                decay = 0.5 ** (age / self.half_life) if self.half_life > 0 else 1.0
+                item["effective_confidence"] = round(f["confidence"] * decay, 4)
+            else:
+                item["effective_confidence"] = f["confidence"]
+            results.append(item)
+        # 按有效置信度降序
+        results.sort(key=lambda x: x["effective_confidence"], reverse=True)
+        return results[:limit]
+
+    def clear(self):
+        self.facts = []
+
+    def count(self) -> int:
+        return len(self.facts)
+
+    def to_context(self, limit: int = 8) -> list[dict]:
+        """生成注入 LLM system prompt 的记忆上下文（仅高置信度 + 未衰减）。"""
+        recalled = self.recall(with_decay=True, limit=limit)
+        return [
+            {
+                "category": r["category"],
+                "content": r["content"],
+                "confidence": r["effective_confidence"],
+            }
+            for r in recalled
+            if r["effective_confidence"] >= 0.3
+        ]
+
+
+__all__ = ["SessionMemory", "DEFAULT_MAX_FACTS", "DEFAULT_HALF_LIFE"]
+

backend/ml_model/__init__.py

@@ -0,0 +1,23 @@
+"""
+SecAgentX ML 模型模块 — 基于机器学习的威胁检测引擎
+
+功能:
+  - 多算法支持: XGBoost / LightGBM / RandomForest / Ensemble
+  - SMOTE 过采样处理类别不平衡
+  - 贝叶斯超参数优化
+  - 决策阈值自动调优
+  - 模型持久化与版本管理
+  - 集成到 Agent 工具系统
+
+典型准确率 (NSL-KDD 测试集):
+  - XGBoost:      ~87%
+  - LightGBM:     ~86%
+  - RF + SMOTE:   ~85%
+  - Ensemble:     ~88%
+"""
+
+from .trainer import MLTrainer
+from .pipeline import MLPipeline
+
+__all__ = ["MLTrainer", "MLPipeline"]
+

backend/ml_model/pipeline.py

@@ -0,0 +1,191 @@
+"""
+数据流水线 — 从原始数据到训练就绪的特征矩阵
+
+支持:
+  - KDD Cup 99 / NSL-KDD 数据集（基于 DARPA 真实网络流量）
+    - 来源: https://www.unb.ca/cic/datasets/nsl.html
+    - 数据: 121,938 条网络流记录, 39 种攻击类型
+    - 特征: 41 个网络流特征 (协议/服务/标志/流量统计等)
+  - SMOTE 过采样
+  - 特征工程与标准化
+  - 混合编码 (数值标准化 + 类别独热)
+
+注意:
+  NSL-KDD 是 KDD Cup 99 的改进版本，解决了数据冗余和重复问题。
+  虽然数据集较老（2009年发布），但它是网络安全 ML 领域最广泛使用的
+  基准数据集之一，适合验证模型架构。生产环境建议使用更近期的数据集
+  （如 CIC-IDS2017、UNSW-NB15）重新训练。
+"""
+import numpy as np
+import pandas as pd
+import os
+import logging
+from typing import Optional, Tuple
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler, LabelEncoder
+from imblearn.over_sampling import SMOTE
+
+logger = logging.getLogger("secagentx.ml")
+
+# ─── KDD Cup 99 特征定义 ───
+KDD_FEATURE_NAMES = [
+    'duration', 'protocol_type', 'service', 'flag',
+    'src_bytes', 'dst_bytes', 'land', 'wrong_fragment', 'urgent',
+    'hot', 'num_failed_logins', 'logged_in', 'num_compromised',
+    'root_shell', 'su_attempted', 'num_root', 'num_file_creations',
+    'num_shells', 'num_access_files', 'num_outbound_cmds',
+    'is_host_login', 'is_guest_login', 'count', 'srv_count',
+    'serror_rate', 'srv_serror_rate', 'rerror_rate', 'srv_rerror_rate',
+    'same_srv_rate', 'diff_srv_rate', 'srv_diff_host_rate',
+    'dst_host_count', 'dst_host_srv_count', 'dst_host_same_srv_rate',
+    'dst_host_diff_srv_rate', 'dst_host_same_src_port_rate',
+    'dst_host_srv_diff_host_rate', 'dst_host_serror_rate',
+    'dst_host_srv_serror_rate', 'dst_host_rerror_rate',
+    'dst_host_srv_rerror_rate', 'label'
+]
+
+CATEGORICAL_FEATURES = ['protocol_type', 'service', 'flag']
+NUMERIC_FEATURES = [c for c in KDD_FEATURE_NAMES if c not in CATEGORICAL_FEATURES + ['label']]
+
+
+class MLPipeline:
+    """端到端数据流水线：加载 → 预处理 → 特征工程 → 划分 → 标准化 → SMOTE"""
+
+    def __init__(self, use_smote: bool = True, test_size: float = 0.25,
+                 random_state: int = 42, scale_data: bool = True):
+        self.use_smote = use_smote
+        self.test_size = test_size
+        self.random_state = random_state
+        self.scale_data = scale_data
+        self.scaler: Optional[StandardScaler] = None
+        self.feature_names: list = []
+        self.label_encoder: Optional[LabelEncoder] = None
+        self.is_multiclass = False
+
+    # ─── 真实数据加载 ───
+    def load_nsl_kdd(self, train_path: str = 'dataset/KDDTrain.csv',
+                     test_path: str = 'dataset/KDDTest.csv') -> pd.DataFrame:
+        """加载 NSL-KDD 真实数据集。"""
+        project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+        train_path = os.path.join(project_root, train_path) if not os.path.isabs(train_path) else train_path
+        test_path = os.path.join(project_root, test_path) if not os.path.isabs(test_path) else test_path
+
+        cols = KDD_FEATURE_NAMES[:41] + ['label', 'difficulty']
+        dfs = []
+        for path in [train_path, test_path]:
+            if os.path.exists(path):
+                df = pd.read_csv(path, header=None, names=cols, on_bad_lines='skip')
+                dfs.append(df)
+                logger.info(f"加载 NSL-KDD: {path} ({len(df)} 条)")
+
+        if not dfs:
+            raise FileNotFoundError(f"NSL-KDD 数据集未找到: {train_path} 或 {test_path}")
+
+        combined = pd.concat(dfs, ignore_index=True)
+        combined['label'] = combined['label'].astype(str).str.strip().str.lower().str.rstrip('.')
+        combined = combined.drop(columns=['difficulty'], errors='ignore')
+
+        attack_counts = combined[combined['label'] != 'normal']['label'].value_counts()
+        logger.info(f"NSL-KDD 加载完成: {len(combined)} 条, "
+                    f"攻击类型: {len(attack_counts)} 种")
+        return combined
+
+    # ─── 预处理 ───
+    def preprocess(self, df: pd.DataFrame, binary: bool = True
+                   ) -> Tuple[np.ndarray, np.ndarray]:
+        """完整预处理：编码 + 清洗。"""
+        if 'label' not in df.columns:
+            raise ValueError("数据缺少 'label' 列")
+
+        df = df.copy()
+
+        # 标签处理
+        self.is_multiclass = not binary
+        if binary:
+            y = df['label'].apply(lambda x: 0 if str(x).strip().lower().rstrip('.') == 'normal' else 1).values.astype(int)
+        else:
+            le = LabelEncoder()
+            y = le.fit_transform(df['label'].astype(str).str.strip().str.lower().str.rstrip('.'))
+            self.label_encoder = le
+
+        X_df = df.drop(columns=['label'])
+
+        # 类别特征独热编码
+        present_cats = [c for c in CATEGORICAL_FEATURES if c in X_df.columns]
+        X_df = pd.get_dummies(X_df, columns=present_cats, drop_first=False)
+
+        # 全部转为数值
+        for col in X_df.columns:
+            X_df[col] = pd.to_numeric(X_df[col], errors='coerce').fillna(0)
+
+        self.feature_names = X_df.columns.tolist()
+        X = X_df.values.astype(np.float64)
+
+        logger.info(f"预处理完成: {len(X)} 样本, {X.shape[1]} 特征, "
+                    f"{'二分类' if binary else f'多分类({len(np.unique(y))}类)'}")
+        return X, y
+
+    def split_and_scale(self, X: np.ndarray, y: np.ndarray
+                        ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        """划分训练/测试集 + 标准化 + SMOTE。"""
+        # 划分
+        stratify = y if len(np.unique(y)) > 1 else None
+        X_train, X_test, y_train, y_test = train_test_split(
+            X, y, test_size=self.test_size, random_state=self.random_state,
+            stratify=stratify
+        )
+
+        # 标准化
+        if self.scale_data:
+            self.scaler = StandardScaler()
+            X_train = self.scaler.fit_transform(X_train)
+            X_test = self.scaler.transform(X_test)
+
+        # SMOTE — 仅对二分类使用
+        if self.use_smote and not self.is_multiclass:
+            unique_train, counts_train = np.unique(y_train, return_counts=True)
+            if len(unique_train) > 1:
+                min_class_count = counts_train.min()
+                max_class_count = counts_train.max()
+                if min_class_count < max_class_count * 0.5:
+                    k_neighbors = min(5, min_class_count - 1) if min_class_count > 1 else 1
+                    if k_neighbors >= 1:
+                        try:
+                            smote = SMOTE(random_state=self.random_state, k_neighbors=k_neighbors)
+                            X_train, y_train = smote.fit_resample(X_train, y_train)
+                            logger.info(f"SMOTE 过采样后训练集: {X_train.shape[0]} 样本")
+                        except Exception as e:
+                            logger.warning(f"SMOTE 跳过: {e}")
+
+        return X_train, X_test, y_train, y_test
+
+    def run_pipeline(self, df: Optional[pd.DataFrame] = None,
+                     n_samples: int = 10000, binary: bool = True
+                     ) -> dict:
+        """一键执行完整流水线。"""
+        # 加载数据
+        if df is None:
+            try:
+                df = self.load_nsl_kdd()
+                logger.info("✅ 使用 NSL-KDD 真实数据集")
+            except FileNotFoundError as exc:
+                raise FileNotFoundError(
+                    "未找到 NSL-KDD 真实数据集；已禁止自动生成合成训练数据。"
+                    "请提供 dataset/KDDTrain.csv 和 dataset/KDDTest.csv，或显式传入真实 DataFrame。"
+                ) from exc
+
+        X, y = self.preprocess(df, binary=binary)
+        X_train, X_test, y_train, y_test = self.split_and_scale(X, y)
+
+        info = f"真实标注数据: {len(df)} 条"
+
+        return {
+            'X_train': X_train, 'X_test': X_test,
+            'y_train': y_train, 'y_test': y_test,
+            'feature_names': self.feature_names,
+            'scaler': self.scaler,
+            'is_multiclass': self.is_multiclass,
+            'label_encoder': self.label_encoder,
+            'label_map': dict(enumerate(self.label_encoder.classes_)) if self.label_encoder else {},
+            'info': info,
+        }