langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/observability/trace/sqlite_store.py

@@ -0,0 +1,873 @@
+"""
+SqliteTraceStore：SQLite 持久化存储。
+
+职责：
+1. 管理 SQLite schema（trace_sessions / trace_spans）
+2. 提供写入接口（save_session / save_spans）
+3. 提供查询接口（query_sessions / get_span_tree）
+
+设计要点：
+- WAL 模式：并发读写安全
+- 索引优化：session_id / parent_span_id / span_type
+- 批量写入：减少 I/O
+"""
+
+import sqlite3
+import json
+import os
+import time
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+from contextlib import contextmanager
+
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+from .models import TraceSession, TraceSpan
+
+
+class SqliteTraceStore:
+    """SQLite trace 存储"""
+    
+    def __init__(self, db_path: str = None):
+        """
+        初始化 SqliteTraceStore。
+
+        Args:
+            db_path: SQLite 数据库路径（默认：<workspace_root>/<agent_home>/data/db/traces.db）
+        """
+        if db_path is None:
+            workspace_cfg = resolve_agent_workspace_config()
+            db_file = workspace_cfg.traces_db_path
+            db_file.parent.mkdir(parents=True, exist_ok=True)
+            db_path = str(db_file)
+
+        self.db_path = db_path
+        self._init_db()
+    
+    def _init_db(self) -> None:
+        """初始化数据库 schema（非破坏性，不清空历史数据）。"""
+        with self._get_connection() as conn:
+            current_journal_mode = str(
+                conn.execute("PRAGMA journal_mode").fetchone()[0]
+            ).lower()
+            if current_journal_mode != "wal":
+                conn.execute("PRAGMA journal_mode=WAL")
+
+            # 创建 trace_sessions 表
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS trace_sessions (
+                    session_id              TEXT PRIMARY KEY,
+                    conversation_session_id TEXT NOT NULL,
+                    parent_session_id       TEXT,
+                    parent_tool_call_id     TEXT,
+                    workflow_id             TEXT,
+                    container_type          TEXT NOT NULL DEFAULT 'agent_session',
+                    unit_type               TEXT NOT NULL DEFAULT 'main_loop',
+                    origin                  TEXT NOT NULL DEFAULT 'user',
+                    visibility              TEXT NOT NULL DEFAULT 'default',
+                    user_query              TEXT,
+                    graph_name              TEXT,
+                    start_time              REAL NOT NULL,
+                    end_time                REAL,
+                    status                  TEXT NOT NULL DEFAULT 'running',
+                    finish_reason           TEXT,
+                    exit_code               TEXT,
+                    terminal_reason         TEXT,
+                    loop_count              INTEGER DEFAULT 0,
+                    total_input_tokens      INTEGER DEFAULT 0,
+                    total_output_tokens     INTEGER DEFAULT 0,
+                    total_latency_ms        REAL DEFAULT 0.0,
+                    metadata_json           TEXT
+                )
+            """)
+            self._ensure_session_columns(conn)
+            
+            # 创建 trace_spans 表
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS trace_spans (
+                    span_id         TEXT PRIMARY KEY,
+                    session_id      TEXT NOT NULL,
+                    parent_span_id  TEXT,
+                    span_type       TEXT NOT NULL,
+                    name            TEXT NOT NULL,
+                    start_time      REAL NOT NULL,
+                    end_time        REAL,
+                    latency_ms      REAL,
+                    status          TEXT NOT NULL DEFAULT 'running',
+                    input_json      TEXT,
+                    output_json     TEXT,
+                    error           TEXT,
+                    metadata_json   TEXT,
+                    FOREIGN KEY (session_id) REFERENCES trace_sessions(session_id)
+                )
+            """)
+            
+            # 创建索引
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_spans_session 
+                ON trace_spans(session_id)
+            """)
+            
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_spans_parent 
+                ON trace_spans(parent_span_id)
+            """)
+            
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_spans_type 
+                ON trace_spans(span_type)
+            """)
+            
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_sessions_time 
+                ON trace_sessions(start_time DESC)
+            """)
+            
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_sessions_status
+                ON trace_sessions(status)
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_sessions_conversation
+                ON trace_sessions(conversation_session_id)
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_sessions_parent
+                ON trace_sessions(parent_session_id)
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_sessions_visibility
+                ON trace_sessions(visibility)
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_sessions_container_type
+                ON trace_sessions(container_type)
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_sessions_workflow
+                ON trace_sessions(workflow_id)
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_sessions_unit_type
+                ON trace_sessions(unit_type)
+            """)
+            self._init_views(conn)
+
+            conn.commit()
+
+    @staticmethod
+    def _init_views(conn: sqlite3.Connection) -> None:
+        conn.execute("""
+            CREATE VIEW IF NOT EXISTS v_session_summary AS
+            SELECT
+                s.session_id,
+                s.graph_name,
+                s.user_query,
+                s.start_time,
+                s.end_time,
+                s.total_latency_ms,
+                s.total_input_tokens,
+                s.total_output_tokens,
+                s.finish_reason,
+                s.status,
+                s.container_type,
+                s.unit_type,
+                s.visibility,
+                (SELECT COUNT(*) FROM trace_spans sp
+                 WHERE sp.session_id = s.session_id AND sp.span_type = 'loop_step') AS step_count,
+                (SELECT COUNT(*) FROM trace_spans sp
+                 WHERE sp.session_id = s.session_id AND sp.span_type = 'tool_call') AS tool_count
+            FROM trace_sessions s
+            ORDER BY s.start_time DESC
+        """)
+        conn.execute("""
+            CREATE VIEW IF NOT EXISTS v_conversation_summary AS
+            SELECT
+                conversation_session_id AS conversation_id,
+                COUNT(*) AS run_count,
+                MIN(start_time) AS first_start_time,
+                MAX(COALESCE(end_time, start_time)) AS last_end_time,
+                SUM(total_input_tokens) AS total_input_tokens,
+                SUM(total_output_tokens) AS total_output_tokens,
+                SUM(total_latency_ms) AS total_latency_ms
+            FROM trace_sessions
+            WHERE conversation_session_id IS NOT NULL
+              AND conversation_session_id != ''
+            GROUP BY conversation_session_id
+            ORDER BY last_end_time DESC
+        """)
+        conn.execute("""
+            CREATE VIEW IF NOT EXISTS v_workflow_summary AS
+            SELECT
+                workflow_id,
+                COUNT(*) AS total_tasks,
+                SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) AS succeeded,
+                SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed,
+                SUM(CASE WHEN status = 'interrupted' THEN 1 ELSE 0 END) AS interrupted,
+                MIN(start_time) AS workflow_start,
+                MAX(COALESCE(end_time, start_time)) AS workflow_end,
+                (MAX(COALESCE(end_time, start_time)) - MIN(start_time)) * 1000 AS total_latency_ms,
+                SUM(total_input_tokens) AS total_input_tokens,
+                SUM(total_output_tokens) AS total_output_tokens
+            FROM trace_sessions
+            WHERE workflow_id IS NOT NULL
+              AND workflow_id != ''
+            GROUP BY workflow_id
+            ORDER BY workflow_start DESC
+        """)
+
+    @staticmethod
+    def _ensure_session_columns(conn: sqlite3.Connection) -> None:
+        """为历史数据库补齐新增列（幂等）。"""
+        existing = {
+            str(row[1])
+            for row in conn.execute("PRAGMA table_info(trace_sessions)").fetchall()
+        }
+        required_columns = {
+            "container_type": "TEXT NOT NULL DEFAULT 'agent_session'",
+            "unit_type": "TEXT NOT NULL DEFAULT 'main_loop'",
+            "origin": "TEXT NOT NULL DEFAULT 'user'",
+            "visibility": "TEXT NOT NULL DEFAULT 'default'",
+            "workflow_id": "TEXT",
+        }
+        for column, column_type in required_columns.items():
+            if column in existing:
+                continue
+            conn.execute(f"ALTER TABLE trace_sessions ADD COLUMN {column} {column_type}")
+    
+    @contextmanager
+    def _get_connection(self):
+        """获取数据库连接（上下文管理器）
+
+        Note:
+            timeout=30.0 用于并发写入场景（WAL 模式下写锁竞争）。
+            详见 docs/architecture/observability-sqlite-concurrency.md
+        """
+        conn = sqlite3.connect(self.db_path, timeout=30.0, check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+        finally:
+            conn.close()
+    
+    def save_session(self, session: TraceSession) -> None:
+        with self._get_connection() as conn:
+            conn.execute("""
+                INSERT OR REPLACE INTO trace_sessions (
+                    session_id, conversation_session_id, parent_session_id, parent_tool_call_id,
+                    workflow_id,
+                    container_type, unit_type, origin, visibility,
+                    user_query, graph_name, start_time, end_time,
+                    status, finish_reason, exit_code, terminal_reason, loop_count,
+                    total_input_tokens, total_output_tokens, total_latency_ms, metadata_json
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, (
+                session.session_id,
+                session.conversation_session_id or session.session_id,
+                session.parent_session_id,
+                session.parent_tool_call_id,
+                session.workflow_id,
+                session.container_type,
+                session.unit_type,
+                session.origin,
+                session.visibility,
+                session.user_query,
+                session.graph_name,
+                session.start_time,
+                session.end_time,
+                session.status,
+                session.finish_reason,
+                session.exit_code,
+                session.terminal_reason,
+                session.loop_count,
+                session.total_input_tokens,
+                session.total_output_tokens,
+                session.total_latency_ms,
+                json.dumps(session.metadata, default=str) if session.metadata else None,
+            ))
+            conn.commit()
+    
+    def save_spans(self, spans: List[TraceSpan]) -> None:
+        """
+        批量保存 spans。
+        
+        Args:
+            spans: TraceSpan 列表
+        """
+        if not spans:
+            return
+        
+        with self._get_connection() as conn:
+            conn.executemany("""
+                INSERT OR REPLACE INTO trace_spans (
+                    span_id, session_id, parent_span_id, span_type, name,
+                    start_time, end_time, latency_ms, status,
+                    input_json, output_json, error, metadata_json
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, [
+                (
+                    span.span_id,
+                    span.session_id,
+                    span.parent_span_id,
+                    span.span_type.value if hasattr(span.span_type, 'value') else span.span_type,
+                    span.name,
+                    span.start_time,
+                    span.end_time,
+                    span.latency_ms,
+                    span.status.value if hasattr(span.status, 'value') else span.status,
+                    json.dumps(span.input_data, default=str) if span.input_data else None,
+                    json.dumps(span.output_data, default=str) if span.output_data else None,
+                    span.error,
+                    json.dumps(span.metadata, default=str) if span.metadata else None,
+                )
+                for span in spans
+            ])
+            conn.commit()
+    
+    def _row_to_session(self, row) -> TraceSession:
+        return TraceSession(
+            session_id=row["session_id"],
+            conversation_session_id=row["conversation_session_id"],
+            parent_session_id=row["parent_session_id"],
+            parent_tool_call_id=row["parent_tool_call_id"],
+            workflow_id=row["workflow_id"] if "workflow_id" in row.keys() else None,
+            container_type=row["container_type"] if "container_type" in row.keys() else "agent_session",
+            unit_type=row["unit_type"],
+            origin=row["origin"],
+            visibility=row["visibility"],
+            user_query=row["user_query"],
+            graph_name=row["graph_name"],
+            start_time=row["start_time"],
+            end_time=row["end_time"],
+            status=row["status"],
+            finish_reason=row["finish_reason"],
+            exit_code=row["exit_code"],
+            terminal_reason=row["terminal_reason"],
+            loop_count=row["loop_count"],
+            total_input_tokens=row["total_input_tokens"],
+            total_output_tokens=row["total_output_tokens"],
+            total_latency_ms=row["total_latency_ms"],
+            metadata=json.loads(row["metadata_json"]) if row["metadata_json"] else {},
+        )
+
+    def get_session(self, session_id: str) -> Optional[TraceSession]:
+        """
+        获取 session。
+        
+        Args:
+            session_id: session 唯一标识
+            
+        Returns:
+            TraceSession 或 None
+        """
+        with self._get_connection() as conn:
+            row = conn.execute("""
+                SELECT * FROM trace_sessions WHERE session_id = ?
+            """, (session_id,)).fetchone()
+            
+            if not row:
+                return None
+            return self._row_to_session(row)
+    
+    def query_sessions(
+        self,
+        limit: int = 20,
+        offset: int = 0,
+        status: Optional[str] = None,
+        graph_name: Optional[str] = None,
+        visibility: Optional[str] = None,
+        workflow_id: Optional[str] = None,
+        **kwargs
+    ) -> List[TraceSession]:
+        """
+        查询 session 列表。
+        
+        Args:
+            limit: 返回条数
+            offset: 偏移量
+            status: 过滤状态
+            graph_name: 过滤 graph 名称
+            
+        Returns:
+            TraceSession 列表
+        """
+        query = "SELECT * FROM trace_sessions WHERE 1=1"
+        params = []
+        
+        if status:
+            query += " AND status = ?"
+            params.append(status)
+        
+        if graph_name:
+            query += " AND graph_name = ?"
+            params.append(graph_name)
+
+        if visibility:
+            query += " AND visibility = ?"
+            params.append(visibility)
+
+        if workflow_id:
+            query += " AND workflow_id = ?"
+            params.append(workflow_id)
+        
+        query += " ORDER BY COALESCE(end_time, start_time) DESC LIMIT ? OFFSET ?"
+        params.extend([limit, offset])
+        
+        with self._get_connection() as conn:
+            rows = conn.execute(query, params).fetchall()
+            return [self._row_to_session(row) for row in rows]
+
+    def query_workflow_summary(self, limit: int = 20) -> List[Dict[str, Any]]:
+        """按 workflow_id 聚合查询摘要。"""
+        with self._get_connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT
+                    workflow_id,
+                    COUNT(*) AS total_tasks,
+                    SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) AS succeeded,
+                    SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed,
+                    SUM(CASE WHEN status = 'interrupted' THEN 1 ELSE 0 END) AS interrupted,
+                    MIN(start_time) AS workflow_start,
+                    MAX(COALESCE(end_time, start_time)) AS workflow_end,
+                    (MAX(COALESCE(end_time, start_time)) - MIN(start_time)) * 1000 AS total_latency_ms,
+                    SUM(total_input_tokens) AS total_input_tokens,
+                    SUM(total_output_tokens) AS total_output_tokens
+                FROM trace_sessions
+                WHERE workflow_id IS NOT NULL AND workflow_id != ''
+                GROUP BY workflow_id
+                ORDER BY workflow_start DESC
+                LIMIT ?
+                """,
+                (limit,),
+            ).fetchall()
+        return [dict(row) for row in rows]
+
+    def get_workflow_summary(self, workflow_id: str) -> Optional[Dict[str, Any]]:
+        """获取单个 workflow 的聚合摘要。"""
+        with self._get_connection() as conn:
+            row = conn.execute(
+                """
+                SELECT
+                    workflow_id,
+                    COUNT(*) AS total_tasks,
+                    SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) AS succeeded,
+                    SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed,
+                    SUM(CASE WHEN status = 'interrupted' THEN 1 ELSE 0 END) AS interrupted,
+                    MIN(start_time) AS workflow_start,
+                    MAX(COALESCE(end_time, start_time)) AS workflow_end,
+                    (MAX(COALESCE(end_time, start_time)) - MIN(start_time)) * 1000 AS total_latency_ms,
+                    SUM(total_input_tokens) AS total_input_tokens,
+                    SUM(total_output_tokens) AS total_output_tokens
+                FROM trace_sessions
+                WHERE workflow_id = ?
+                GROUP BY workflow_id
+                """,
+                (workflow_id,),
+            ).fetchone()
+        return dict(row) if row else None
+
+    def get_sessions_by_ids(self, session_ids: List[str]) -> Dict[str, TraceSession]:
+        """按 session_id 批量读取 sessions。"""
+        if not session_ids:
+            return {}
+        placeholders = ",".join("?" for _ in session_ids)
+        query = f"SELECT * FROM trace_sessions WHERE session_id IN ({placeholders})"
+        with self._get_connection() as conn:
+            rows = conn.execute(query, session_ids).fetchall()
+            sessions = [self._row_to_session(row) for row in rows]
+            return {session.session_id: session for session in sessions}
+
+    def _conversation_id_of(self, session: TraceSession) -> str:
+        return session.conversation_session_id or session.session_id
+
+    def query_conversations(
+        self,
+        limit: int = 20,
+        status: Optional[str] = None,
+        include_hidden: bool = False,
+        main_loop_only: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """按 conversation_session_id 聚合查询会话列表（SQL 聚合）。"""
+        where_clause = ""
+        params: List[Any] = []
+        if status:
+            where_clause = "WHERE s.status = ?"
+            params.append(status)
+
+        query = f"""
+            WITH grouped AS (
+                SELECT
+                    COALESCE(s.conversation_session_id, s.session_id) AS conversation_id,
+                    COUNT(*) AS run_count,
+                    AVG(s.total_latency_ms) AS avg_latency_ms,
+                    SUM(s.total_input_tokens) AS total_input_tokens,
+                    SUM(s.total_output_tokens) AS total_output_tokens,
+                    MAX(COALESCE(s.end_time, s.start_time)) AS latest_end_time
+                FROM trace_sessions s
+                {where_clause}
+                GROUP BY COALESCE(s.conversation_session_id, s.session_id)
+            )
+            SELECT
+                g.conversation_id AS session_id,
+                g.run_count,
+                g.avg_latency_ms,
+                g.total_input_tokens,
+                g.total_output_tokens,
+                g.latest_end_time,
+                (
+                    SELECT s2.graph_name
+                    FROM trace_sessions s2
+                    WHERE COALESCE(s2.conversation_session_id, s2.session_id) = g.conversation_id
+                    {f"AND s2.status = ?" if status else ""}
+                    ORDER BY COALESCE(s2.end_time, s2.start_time) DESC
+                    LIMIT 1
+                ) AS graph_name,
+                (
+                    SELECT s2.status
+                    FROM trace_sessions s2
+                    WHERE COALESCE(s2.conversation_session_id, s2.session_id) = g.conversation_id
+                    {f"AND s2.status = ?" if status else ""}
+                    ORDER BY COALESCE(s2.end_time, s2.start_time) DESC
+                    LIMIT 1
+                ) AS last_status
+                ,
+                (
+                    SELECT s2.visibility
+                    FROM trace_sessions s2
+                    WHERE COALESCE(s2.conversation_session_id, s2.session_id) = g.conversation_id
+                    {f"AND s2.status = ?" if status else ""}
+                    ORDER BY COALESCE(s2.end_time, s2.start_time) DESC
+                    LIMIT 1
+                ) AS last_visibility,
+                (
+                    SELECT s2.user_query
+                    FROM trace_sessions s2
+                    WHERE COALESCE(s2.conversation_session_id, s2.session_id) = g.conversation_id
+                    AND s2.unit_type = 'main_loop'
+                    ORDER BY s2.start_time ASC
+                    LIMIT 1
+                ) AS topic_query,
+                (
+                    SELECT 1
+                    FROM trace_sessions s2
+                    WHERE COALESCE(s2.conversation_session_id, s2.session_id) = g.conversation_id
+                    AND s2.unit_type = 'main_loop'
+                    LIMIT 1
+                ) AS has_main_loop
+            FROM grouped g
+            ORDER BY g.latest_end_time DESC
+            LIMIT ?
+        """
+        query_params = list(params)
+        if status:
+            query_params.append(status)
+            query_params.append(status)
+            query_params.append(status)
+        query_params.append(limit)
+
+        with self._get_connection() as conn:
+            rows = conn.execute(query, query_params).fetchall()
+            items = [
+                {
+                    "session_id": row["session_id"],
+                    "graph_name": row["graph_name"],
+                    "run_count": row["run_count"],
+                    "latest_end_time": row["latest_end_time"],
+                    "last_status": row["last_status"],
+                    "last_visibility": row["last_visibility"] or "default",
+                    "avg_latency_ms": row["avg_latency_ms"] or 0.0,
+                    "total_input_tokens": int(row["total_input_tokens"] or 0),
+                    "total_output_tokens": int(row["total_output_tokens"] or 0),
+                    "topic_query": row["topic_query"] or "",
+                    "has_main_loop": bool(row["has_main_loop"]),
+                }
+                for row in rows
+            ]
+            # 过滤顺序约定：
+            # 1) main_loop_only 先收敛“会话语义”（只保留含主 run 的 conversation）
+            # 2) include_hidden 再决定是否展示 hidden 可见性项
+            if main_loop_only:
+                items = [item for item in items if item["has_main_loop"]]
+            if include_hidden:
+                return items
+            return [item for item in items if item["last_visibility"] != "hidden"]
+
+    def get_runs_by_conversation(
+        self,
+        conversation_session_id: str,
+        limit: int = 50,
+    ) -> List[TraceSession]:
+        """获取某个会话下的 runs（每条 run_id 为 TraceSession.session_id）。"""
+        query = """
+            SELECT *
+            FROM trace_sessions
+            WHERE COALESCE(conversation_session_id, session_id) = ?
+            ORDER BY COALESCE(end_time, start_time) DESC
+            LIMIT ?
+        """
+        with self._get_connection() as conn:
+            rows = conn.execute(query, (conversation_session_id, limit)).fetchall()
+            return [self._row_to_session(row) for row in rows]
+    
+    def get_span_tree(self, session_id: str) -> List[TraceSpan]:
+        """
+        获取 session 的所有 span。
+        
+        Args:
+            session_id: session 唯一标识
+            
+        Returns:
+            TraceSpan 列表
+        """
+        with self._get_connection() as conn:
+            rows = conn.execute("""
+                SELECT * FROM trace_spans 
+                WHERE session_id = ? 
+                ORDER BY start_time
+            """, (session_id,)).fetchall()
+            
+            from .models import SpanType, SpanStatus
+            
+            return [
+                TraceSpan(
+                    span_id=row["span_id"],
+                    session_id=row["session_id"],
+                    parent_span_id=row["parent_span_id"],
+                    span_type=SpanType(row["span_type"]),
+                    name=row["name"],
+                    start_time=row["start_time"],
+                    end_time=row["end_time"],
+                    latency_ms=row["latency_ms"],
+                    status=SpanStatus(row["status"]),
+                    input_data=json.loads(row["input_json"]) if row["input_json"] else None,
+                    output_data=json.loads(row["output_json"]) if row["output_json"] else None,
+                    error=row["error"],
+                    metadata=json.loads(row["metadata_json"]) if row["metadata_json"] else {},
+                )
+                for row in rows
+            ]
+
+    def get_span_trees(self, session_ids: List[str]) -> Dict[str, List[TraceSpan]]:
+        """
+        批量获取多个 session 的 spans，减少 N 次往返查询。
+
+        Args:
+            session_ids: session_id 列表
+
+        Returns:
+            Dict[session_id, List[TraceSpan]]
+        """
+        result: Dict[str, List[TraceSpan]] = {sid: [] for sid in session_ids}
+        if not session_ids:
+            return result
+
+        placeholders = ",".join("?" for _ in session_ids)
+        query = (
+            "SELECT * FROM trace_spans "
+            f"WHERE session_id IN ({placeholders}) "
+            "ORDER BY session_id, start_time"
+        )
+        with self._get_connection() as conn:
+            rows = conn.execute(query, session_ids).fetchall()
+            from .models import SpanType, SpanStatus
+
+            for row in rows:
+                span = TraceSpan(
+                    span_id=row["span_id"],
+                    session_id=row["session_id"],
+                    parent_span_id=row["parent_span_id"],
+                    span_type=SpanType(row["span_type"]),
+                    name=row["name"],
+                    start_time=row["start_time"],
+                    end_time=row["end_time"],
+                    latency_ms=row["latency_ms"],
+                    status=SpanStatus(row["status"]),
+                    input_data=json.loads(row["input_json"]) if row["input_json"] else None,
+                    output_data=json.loads(row["output_json"]) if row["output_json"] else None,
+                    error=row["error"],
+                    metadata=json.loads(row["metadata_json"]) if row["metadata_json"] else {},
+                )
+                if span.session_id not in result:
+                    result[span.session_id] = []
+                result[span.session_id].append(span)
+        return result
+    
+    def cleanup_old_sessions(self, days: int = 7) -> int:
+        """
+        清理过期的 session。
+        
+        Args:
+            days: 保留天数
+            
+        Returns:
+            删除的 session 数量
+        """
+        import time
+        cutoff_time = time.time() - (days * 24 * 3600)
+        
+        with self._get_connection() as conn:
+            # 删除 spans
+            conn.execute("""
+                DELETE FROM trace_spans 
+                WHERE session_id IN (
+                    SELECT session_id FROM trace_sessions 
+                    WHERE start_time < ?
+                )
+            """, (cutoff_time,))
+            
+            # 删除 sessions
+            cursor = conn.execute("""
+                DELETE FROM trace_sessions WHERE start_time < ?
+            """, (cutoff_time,))
+            
+            deleted_count = cursor.rowcount
+            conn.commit()
+            
+            return deleted_count
+
+    def cleanup_sessions_by_retention(
+        self,
+        *,
+        failed_days: int = 180,
+        normal_days: int = 30,
+    ) -> int:
+        """
+        按状态分层清理过期 session。
+
+        保留策略：
+        - failed/interrupted：failed_days
+        - 其他状态（completed/running 等）：normal_days
+        """
+        import time
+
+        now = time.time()
+        failed_cutoff = now - (int(failed_days) * 24 * 3600)
+        normal_cutoff = now - (int(normal_days) * 24 * 3600)
+        with self._get_connection() as conn:
+            # 先删 span（级联在 sqlite 默认未开启，显式清理）
+            conn.execute(
+                """
+                DELETE FROM trace_spans
+                WHERE session_id IN (
+                    SELECT session_id
+                    FROM trace_sessions
+                    WHERE (status IN ('failed', 'interrupted') AND start_time < ?)
+                       OR (status NOT IN ('failed', 'interrupted') AND start_time < ?)
+                )
+                """,
+                (failed_cutoff, normal_cutoff),
+            )
+            cursor = conn.execute(
+                """
+                DELETE FROM trace_sessions
+                WHERE (status IN ('failed', 'interrupted') AND start_time < ?)
+                   OR (status NOT IN ('failed', 'interrupted') AND start_time < ?)
+                """,
+                (failed_cutoff, normal_cutoff),
+            )
+            deleted_count = int(cursor.rowcount or 0)
+            conn.commit()
+            return deleted_count
+
+    def mark_sessions_interrupted(
+        self,
+        *,
+        status_filter: str = "running",
+        start_before: float,
+        new_status: str = "interrupted",
+        terminal_reason: str = "process_crash_or_timeout",
+    ) -> int:
+        """将超时 running 会话标记为 interrupted。"""
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                UPDATE trace_sessions
+                SET status = ?, terminal_reason = ?, end_time = ?
+                WHERE status = ? AND start_time < ?
+                """,
+                (new_status, terminal_reason, time.time(), status_filter, start_before),
+            )
+            conn.commit()
+            return cursor.rowcount
+
+    def recover_orphan_sessions(self, timeout_seconds: int = 3600) -> int:
+        """恢复孤儿会话（服务启动时调用）。"""
+        cutoff = time.time() - timeout_seconds
+        return self.mark_sessions_interrupted(
+            status_filter="running",
+            start_before=cutoff,
+            new_status="interrupted",
+            terminal_reason="process_crash_or_timeout",
+        )
+
+    def get_stats(self) -> Dict[str, Any]:
+        """返回全局聚合统计，供 API/CLI 使用。"""
+        with self._get_connection() as conn:
+            row = conn.execute(
+                """
+                SELECT
+                    COUNT(*) AS total_runs,
+                    SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) AS completed,
+                    SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed,
+                    SUM(CASE WHEN status = 'interrupted' THEN 1 ELSE 0 END) AS interrupted,
+                    AVG(total_latency_ms) AS avg_latency_ms,
+                    AVG(loop_count) AS avg_steps,
+                    AVG(total_input_tokens) AS avg_tokens_in,
+                    AVG(total_output_tokens) AS avg_tokens_out
+                FROM trace_sessions
+                """
+            ).fetchone()
+            tool_row = conn.execute(
+                "SELECT AVG(tool_count) AS avg_tool_calls FROM v_session_summary"
+            ).fetchone()
+            llm_row = conn.execute(
+                """
+                SELECT AVG(cnt) AS avg_llm_calls FROM (
+                    SELECT session_id, COUNT(*) AS cnt
+                    FROM trace_spans
+                    WHERE span_type = 'llm_call'
+                    GROUP BY session_id
+                )
+                """
+            ).fetchone()
+            deg_row = conn.execute(
+                """
+                SELECT
+                    COUNT(*) AS total_llm,
+                    SUM(CASE WHEN metadata_json LIKE '%"detected": true%' THEN 1 ELSE 0 END) AS degraded
+                FROM trace_spans
+                WHERE span_type = 'llm_call'
+                """
+            ).fetchone()
+        total_runs = int((row["total_runs"] if row else 0) or 0)
+        total_llm = int((deg_row["total_llm"] if deg_row else 0) or 0)
+        degraded = int((deg_row["degraded"] if deg_row else 0) or 0)
+        return {
+            "total_sessions": total_runs,
+            "total_runs": total_runs,
+            "completed": int((row["completed"] if row else 0) or 0),
+            "failed": int((row["failed"] if row else 0) or 0),
+            "interrupted": int((row["interrupted"] if row else 0) or 0),
+            "avg_latency_ms": round(float((row["avg_latency_ms"] if row else 0.0) or 0.0), 1),
+            "avg_steps": round(float((row["avg_steps"] if row else 0.0) or 0.0), 1),
+            "avg_tokens_in": round(float((row["avg_tokens_in"] if row else 0.0) or 0.0), 0),
+            "avg_tokens_out": round(float((row["avg_tokens_out"] if row else 0.0) or 0.0), 0),
+            "avg_tool_calls": round(float((tool_row["avg_tool_calls"] if tool_row else 0.0) or 0.0), 1),
+            "avg_llm_calls": round(
+                float(0.0 if llm_row is None or llm_row["avg_llm_calls"] is None else llm_row["avg_llm_calls"]),
+                1,
+            ),
+            "degradation_rate_percent": round((degraded / total_llm) * 100, 1) if total_llm else 0.0,
+        }
+
+    @classmethod
+    def from_env(cls) -> "SqliteTraceStore":
+        """创建 SqliteTraceStore。
+
+        若设置 ``AGENTX_TRACE_DB_PATH``，使用该路径；否则 ``db_path`` 为 ``None``，
+        与无参 ``SqliteTraceStore()`` 相同，经 ``resolve_agent_workspace_config()`` 使用
+        ``traces_db_path``（见 ``docs/design-docs/trace/OB-D09-trace-workspace-bootstrap.md`` §3）。
+        """
+        db_path = os.getenv("AGENTX_TRACE_DB_PATH")
+        return cls(db_path=db_path)