feat(对齐): 上下文组装与SSE协议对齐，并统一错误映射

- 新增 ContextAssembler（会话+SQLite+向量三层上下文），并接入 SessionManager
- SSE 补齐 step_key/scope/context_debug，适配并行子任务时间线
- 引入统一错误码/脱敏与上游 LLM 错误分类（HTTP+SSE）
- 适配 TaskExecutor 结果结构与穿插规划（Adaptive Replan）
- API Key 规范化（去 Bearer 前缀）并在鉴权失败时自动清理无效 Key

Made-with: Cursor

Author: 赵明俊

hackbot_config/__init__.py

@@ -133,16 +133,23 @@ def delete_provider_api_key(provider: str) -> bool:
 _get_api_key_from_sqlite = _get_config_from_sqlite
 
 
+def normalize_bearer_api_key(key: str) -> str:
+    """去掉用户误写的 'Bearer ' 前缀，与 npm normalizeBearerApiKey 对齐。"""
+    if key and key.strip().lower().startswith("bearer "):
+        return key.strip()[7:].strip()
+    return key.strip() if key else ""
+
+
 def get_provider_api_key(provider: str) -> Optional[str]:
-    """获取任意厂商的 API Key（优先 SQLite，其次环境变量）"""
+    """获取任意厂商的 API Key（优先 SQLite，其次环境变量），自动规范化 Bearer 前缀。"""
     # SQLite
     key = _get_config_from_sqlite(f"{provider}_api_key")
     if key and key.strip():
-        return key.strip()
+        return normalize_bearer_api_key(key)
     # 环境变量 (如 OPENAI_API_KEY / DEEPSEEK_API_KEY / ...)
     env_val = os.getenv(f"{provider.upper()}_API_KEY")
     if env_val and env_val.strip():
-        return env_val.strip()
+        return normalize_bearer_api_key(env_val)
     return None
 
 

router/chat.py

@@ -15,12 +15,14 @@
 from router.dependencies import (
     get_agent,
     get_agents,
+    get_context_assembler,
     get_planner_agent,
     get_qa_agent,
     get_summary_agent,
 )
 from router.schemas import ChatRequest, ChatResponse, RootResponseRequest
 from secbot_agent.core.session import SessionManager
+from utils.error_mapper import map_exception_to_client, redact_sensitive_text
 from utils.event_bus import EventBus, EventType, Event
 from utils.logger import logger
 from utils.log_context import log_context
@@ -32,6 +34,14 @@
 _root_pending: dict[str, asyncio.Future[dict[str, Any] | None]] = {}
 
 
+def _sse_step_key(data: dict, iteration: int) -> str:
+    """与 npm 端 sseStepKey 对齐：并行子任务以 todo_id 区分，避免前端时间线串台。"""
+    todo_id = data.get("todo_id") or data.get("todoId")
+    if todo_id is not None and str(todo_id).strip():
+        return f"todo-{todo_id}"
+    return f"iter-{iteration}"
+
+
 def _event_to_sse(event: Event) -> tuple[str, dict] | None:
     """将 EventBus 事件映射为前端 SSE 的 (event_name, data)。"""
     t, d = event.type, event.data
@@ -40,55 +50,67 @@ def _event_to_sse(event: Event) -> tuple[str, dict] | None:
             "planning",
             {
                 "content": d.get("summary", ""),
+                "summary": d.get("summary", ""),
+                "scope": d.get("scope", "master"),
                 "todos": d.get("todos", []),
                 "agent": d.get("agent"),
             },
         )
     if t == EventType.THINK_START:
+        iteration = d.get("iteration", 1)
         return (
             "thought_start",
             {
-                "iteration": d.get("iteration", 1),
+                "iteration": iteration,
+                "step_key": _sse_step_key(d, iteration),
                 "agent": d.get("agent"),
             },
         )
     if t == EventType.THINK_CHUNK:
+        iteration = d.get("iteration", 1)
         return (
             "thought_chunk",
             {
                 "chunk": d.get("chunk", ""),
-                "iteration": d.get("iteration", 1),
+                "iteration": iteration,
+                "step_key": _sse_step_key(d, iteration),
                 "agent": d.get("agent"),
             },
         )
     if t == EventType.THINK_END:
+        iteration = d.get("iteration", 1)
         return (
             "thought",
             {
                 "content": d.get("thought", ""),
-                "iteration": d.get("iteration", 1),
+                "iteration": iteration,
+                "step_key": _sse_step_key(d, iteration),
                 "agent": d.get("agent"),
             },
         )
     if t == EventType.EXEC_START:
+        iteration = d.get("iteration", 1)
         return (
             "action_start",
             {
                 "tool": d.get("tool", ""),
                 "params": d.get("params", {}),
-                "iteration": d.get("iteration", 1),
+                "iteration": iteration,
+                "step_key": _sse_step_key(d, iteration),
                 "agent": d.get("agent"),
             },
         )
     if t == EventType.EXEC_RESULT:
+        iteration = d.get("iteration", 1)
         return (
             "action_result",
             {
                 "tool": d.get("tool", ""),
                 "success": d.get("success", True),
                 "result": d.get("result"),
                 "error": d.get("error", ""),
-                "iteration": d.get("iteration", 1),
+                "iteration": iteration,
+                "step_key": _sse_step_key(d, iteration),
                 "view_type": d.get("view_type", "raw"),
                 "agent": d.get("agent"),
             },
@@ -201,6 +223,7 @@ async def get_root_password(command: str) -> dict[str, Any] | None:
         planner=get_planner_agent(),
         qa_agent=get_qa_agent(),
         summary_agent=get_summary_agent(),
+        context_assembler=get_context_assembler(),
         get_root_password=get_root_password,
     )
 
@@ -229,10 +252,15 @@ async def _run_interaction():
                 )
                 final_response.append(response)
         except Exception as e:
+            mapped = map_exception_to_client(e)
             queue.put_nowait(
                 {
                     "event": "error",
-                    "data": {"error": str(e), "traceback": traceback.format_exc()},
+                    "data": {
+                        "error": mapped.message,
+                        "code": mapped.code.value,
+                        "statusCode": mapped.status_code,
+                    },
                 }
             )
         finally:

router/dependencies.py

@@ -12,8 +12,11 @@
 from secbot_agent.core.agents.qa_agent import QAAgent
 from secbot_agent.core.agents.planner_agent import PlannerAgent
 from secbot_agent.core.agents.summary_agent import SummaryAgent
+from secbot_agent.core.context_assembler import ContextAssembler
 from secbot_agent.database.manager import DatabaseManager
 from secbot_agent.core.memory.database_memory import DatabaseMemory
+from secbot_agent.core.memory.manager import MemoryManager
+from secbot_agent.core.memory.vector_store import VectorStoreManager
 from secbot_agent.defense.defense_manager import DefenseManager
 from secbot_agent.controller.controller import MainController
 from secbot_agent.system.controller import OSController
@@ -41,6 +44,9 @@ class _Singletons:
     _qa_agent: QAAgent | None = None
     _planner_agent: PlannerAgent | None = None
     _summary_agent: SummaryAgent | None = None
+    _context_assembler: ContextAssembler | None = None
+    _memory_manager: MemoryManager | None = None
+    _vector_store_manager: VectorStoreManager | None = None
     _defense_manager: DefenseManager | None = None
     _main_controller: MainController | None = None
     _os_controller: OSController | None = None
@@ -110,6 +116,29 @@ def summary_agent(cls) -> SummaryAgent:
             cls._summary_agent = SummaryAgent()
         return cls._summary_agent
 
+    # -- 记忆与上下文 --
+    @classmethod
+    def memory_manager(cls) -> MemoryManager:
+        if cls._memory_manager is None:
+            cls._memory_manager = MemoryManager()
+        return cls._memory_manager
+
+    @classmethod
+    def vector_store_manager(cls) -> VectorStoreManager:
+        if cls._vector_store_manager is None:
+            cls._vector_store_manager = VectorStoreManager()
+        return cls._vector_store_manager
+
+    @classmethod
+    def context_assembler(cls) -> ContextAssembler:
+        if cls._context_assembler is None:
+            cls._context_assembler = ContextAssembler(
+                db_manager=cls.db_manager(),
+                memory_manager=cls.memory_manager(),
+                vector_store_manager=cls.vector_store_manager(),
+            )
+        return cls._context_assembler
+
     # -- 防御管理器 --
     @classmethod
     def defense_manager(cls) -> DefenseManager:
@@ -193,5 +222,17 @@ def get_os_detector() -> OSDetector:
     return _Singletons.os_detector()
 
 
+def get_context_assembler() -> ContextAssembler:
+    return _Singletons.context_assembler()
+
+
+def get_memory_manager() -> MemoryManager:
+    return _Singletons.memory_manager()
+
+
+def get_vector_store_manager() -> VectorStoreManager:
+    return _Singletons.vector_store_manager()
+
+
 def get_session_id() -> str:
     return _session_id

secbot_agent/core/context_assembler.py

@@ -0,0 +1,165 @@
+"""
+ContextAssembler：三层上下文组装器
+与 npm-release 的 ContextAssemblerService 对齐，组合：
+1. 当前会话最近消息（RecentSession）
+2. SQLite 历史轮次（SQLiteHistory）
+3. 向量 episodic 记忆检索（VectorMemory）
+"""
+
+import math
+import unicodedata
+from dataclasses import dataclass
+from typing import Dict, List, Optional, TYPE_CHECKING
+
+from utils.logger import logger
+
+if TYPE_CHECKING:
+    from secbot_agent.core.memory.manager import MemoryManager
+    from secbot_agent.core.memory.vector_store import VectorStoreManager
+    from secbot_agent.core.models import Session
+    from secbot_agent.database.manager import DatabaseManager
+
+VECTOR_DIMENSION = 128
+
+
+@dataclass
+class ContextDebugMeta:
+    session_messages: int = 0
+    sqlite_turns: int = 0
+    vector_hits: int = 0
+
+
+@dataclass
+class AssembledContext:
+    context_block: str = ""
+    debug: ContextDebugMeta = None
+
+    def __post_init__(self):
+        if self.debug is None:
+            self.debug = ContextDebugMeta()
+
+
+class ContextAssembler:
+    """
+    三层上下文组装器 —— 合并会话消息、SQLite 对话历史和向量 episodic 记忆，
+    为 QA / Agent 提供统一的 contextBlock。
+    """
+
+    def __init__(
+        self,
+        db_manager: "DatabaseManager",
+        memory_manager: Optional["MemoryManager"] = None,
+        vector_store_manager: Optional["VectorStoreManager"] = None,
+    ):
+        self.db_manager = db_manager
+        self.memory_manager = memory_manager
+        self.vector_store_manager = vector_store_manager
+
+    async def build(
+        self,
+        query: str,
+        session: "Session",
+        session_id: str,
+        agent_type: str = "hackbot",
+    ) -> AssembledContext:
+        recent_session = [
+            f"{m.role.value}: {m.content}" for m in session.messages[-24:]
+        ]
+
+        sqlite_history = self.db_manager.get_conversations(
+            session_id=session_id, limit=8
+        )
+
+        dedupe = set()
+        sqlite_lines: List[str] = []
+        for turn in reversed(sqlite_history):
+            pair = f"用户: {turn.user_message}\n助手: {turn.assistant_message}"
+            if pair in dedupe:
+                continue
+            dedupe.add(pair)
+            sqlite_lines.append(pair)
+
+        vector_lines: List[str] = []
+        if self.vector_store_manager is not None:
+            try:
+                query_vec = text_to_vector(query)
+                store = self.vector_store_manager.get_store("episodic", VECTOR_DIMENSION)
+                hits = store.search(query_vec, limit=6, collection="episodic", threshold=0.3)
+                for item, similarity in hits:
+                    content = item.content.strip()
+                    if not content or content in dedupe:
+                        continue
+                    dedupe.add(content)
+                    sid = (item.metadata or {}).get("sessionId", "unknown")
+                    vector_lines.append(
+                        f"{content}\n来源: {sid} / 相似度: {similarity:.3f}"
+                    )
+            except Exception as e:
+                logger.warning(f"ContextAssembler 向量检索失败: {e}")
+
+        parts: List[str] = []
+        if recent_session:
+            parts.append(f"【RecentSession】\n" + "\n".join(recent_session))
+        if sqlite_lines:
+            parts.append(f"【SQLiteHistory】\n" + "\n\n".join(sqlite_lines))
+        if vector_lines:
+            parts.append(f"【VectorMemory】\n" + "\n\n".join(vector_lines))
+        parts.append(f"【RequestMeta】\nsession_id: {session_id}\nagent: {agent_type}")
+
+        return AssembledContext(
+            context_block="\n\n".join(parts),
+            debug=ContextDebugMeta(
+                session_messages=len(recent_session),
+                sqlite_turns=len(sqlite_lines),
+                vector_hits=len(vector_lines),
+            ),
+        )
+
+    async def remember_turn(
+        self,
+        session_id: str,
+        agent_type: str,
+        user_message: str,
+        assistant_message: str,
+    ) -> None:
+        merged = f"用户: {user_message}\n助手: {assistant_message}"
+        try:
+            if self.memory_manager is not None:
+                await self.memory_manager.remember(
+                    merged, "short_term", 0.6, sessionId=session_id, agentType=agent_type
+                )
+                await self.memory_manager.remember(
+                    merged, "episodic", 0.75, sessionId=session_id, agentType=agent_type
+                )
+            if self.vector_store_manager is not None:
+                from datetime import datetime, timezone
+
+                vec = text_to_vector(merged)
+                await self.vector_store_manager.add_memory(
+                    content=merged,
+                    vector=vec,
+                    memory_type="episodic",
+                    metadata={
+                        "sessionId": session_id,
+                        "agentType": agent_type,
+                        "createdAt": datetime.now(timezone.utc).isoformat(),
+                    },
+                )
+        except Exception as e:
+            logger.warning(f"ContextAssembler.remember_turn 失败: {e}")
+
+
+def text_to_vector(text: str) -> List[float]:
+    """确定性字符哈希式向量（128 维），与 npm 端 textToVector 对齐。"""
+    vector = [0.0] * VECTOR_DIMENSION
+    normalized = unicodedata.normalize("NFKC", text).lower()
+    if not normalized:
+        return vector
+    for i, ch in enumerate(normalized):
+        code = ord(ch)
+        index = (code + i * 31) % VECTOR_DIMENSION
+        vector[index] += 1 + (code % 7) * 0.05
+    norm = math.sqrt(sum(v * v for v in vector))
+    if norm <= 1e-8:
+        return vector
+    return [v / norm for v in vector]