openclaw-agent-dashboard 1.0.39 → 1.0.41

package/dashboard/data/timeline_reader.py

@@ -1,7 +1,6 @@
 """
 时序数据读取器 - 将 session jsonl 解析为可视化时序步骤
 """
-import json
 import logging
 import os
 from functools import lru_cache
@@ -92,7 +91,13 @@ class TimelineStep:
 
 
 from data.config_reader import get_openclaw_root, normalize_openclaw_agent_id, agent_ids_equal
-from data.session_reader import normalize_sessions_index, resolve_session_jsonl_path
+from data.session_reader import (
+    normalize_sessions_index,
+    resolve_session_jsonl_path,
+    _load_sessions_index_file,
+)
+from data.subagent_reader import load_subagent_runs
+from utils.data_repair import parse_session_jsonl_line
 
 
 def _read_session_header_timestamp(path: Path) -> Optional[int]:
@@ -102,10 +107,10 @@ def _read_session_header_timestamp(path: Path) -> Optional[int]:
             first = f.readline()
         if not first.strip():
             return None
-        data = json.loads(first.strip())
-        if data.get('type') == 'session':
-            return _parse_timestamp(data.get('timestamp', 0))
-    except (json.JSONDecodeError, OSError, IOError):
+        envelope, _ = parse_session_jsonl_line(first.strip())
+        if envelope and envelope.get('type') == 'session':
+            return _parse_timestamp(envelope.get('timestamp', 0))
+    except (OSError, IOError):
         pass
     return None
 
@@ -260,17 +265,11 @@ def get_subagent_runs() -> Dict[str, List[Dict]]:
 
 @lru_cache(maxsize=16)
 def _get_subagent_runs_cached(mtime: float) -> Dict[str, List[Dict]]:
-    runs_file = get_openclaw_root() / "subagents" / "runs.json"
-    try:
-        with open(runs_file, 'r', encoding='utf-8') as f:
-            data = json.load(f)
-    except (json.JSONDecodeError, IOError, OSError):
-        return {}
     runs_by_agent: Dict[str, List[Dict]] = {}
-    runs = data.get('runs', {})
-    for run_id, run_info in runs.items():
+    for run_info in load_subagent_runs():
         if not isinstance(run_info, dict):
             continue
+        run_id = str(run_info.get('runId', ''))
         child_key = run_info.get('childSessionKey', '')
         if ':' in child_key:
             parts = child_key.split(':')
@@ -297,9 +296,11 @@ def _get_requester_info_for_session(agent_id: str, session_key: Optional[str]) -
     sessions_index = get_openclaw_root() / f"agents/{state_id}/sessions/sessions.json"
     if sessions_index.exists():
         try:
-            with open(sessions_index, 'r', encoding='utf-8') as f:
-                index_data = json.load(f)
-            index_map = normalize_sessions_index(index_data)
+            index_data = _load_sessions_index_file(sessions_index)
+            if not index_data:
+                index_map = {}
+            else:
+                index_map = normalize_sessions_index(index_data)
             if not session_key:
                 entries = list(index_map.items())
                 if entries:
@@ -328,14 +329,8 @@ def _get_requester_info_for_session(agent_id: str, session_key: Optional[str]) -
             session_key = runs[0].get('childSessionKey')
     if not session_key:
         return {}
-    runs_file = get_openclaw_root() / "subagents" / "runs.json"
-    if not runs_file.exists():
-        return {}
     try:
-        with open(runs_file, 'r', encoding='utf-8') as f:
-            data = json.load(f)
-        runs = data.get('runs', {})
-        for run_id, run_info in runs.items():
+        for run_info in load_subagent_runs():
             if not isinstance(run_info, dict):
                 continue
             child_key = run_info.get('childSessionKey', '')
@@ -612,10 +607,10 @@ def resolve_agent_session_jsonl(
     index_path = sessions_path / "sessions.json"
     index_map: Dict[str, Dict[str, Any]] = {}
     if index_path.exists():
-        try:
-            with open(index_path, 'r', encoding='utf-8') as f:
-                index_map = normalize_sessions_index(json.load(f))
-        except (json.JSONDecodeError, IOError):
+        raw = _load_sessions_index_file(index_path)
+        if raw:
+            index_map = normalize_sessions_index(raw)
+        else:
             index_map = {}
 
     prefix = f"agent:{state_id}:"
@@ -895,17 +890,13 @@ def _extract_subagent_steps_from_main_lines(
     for line in lines:
         if '"type":"message"' not in line and '"type": "message"' not in line:
             continue
-        try:
-            data = json.loads(line.strip())
-        except json.JSONDecodeError:
-            continue
-        if data.get('type') != 'message':
+        envelope, msg = parse_session_jsonl_line(line)
+        if envelope is None or envelope.get('type') != 'message' or msg is None:
             continue
-        msg = data.get('message', {})
         role = msg.get('role')
         if not role:
             continue
-        timestamp = _parse_timestamp(msg.get('timestamp') or data.get('timestamp', 0))
+        timestamp = _parse_timestamp(msg.get('timestamp') or envelope.get('timestamp', 0))
         duration = 0
         if last_timestamp and timestamp:
             duration = timestamp - last_timestamp
@@ -1112,21 +1103,19 @@ def _parse_session_lines(
     sender_id = requester_info.get('senderId') if requester_info else None
     sender_name = requester_info.get('senderName') if requester_info else None
     for line in lines:
-        try:
-            data = json.loads(line.strip())
-        except json.JSONDecodeError:
+        envelope, msg = parse_session_jsonl_line(line)
+        if envelope is None:
             continue
-        msg_type = data.get('type')
+        msg_type = envelope.get('type')
         if msg_type == 'session':
-            started_at = _parse_timestamp(data.get('timestamp', 0))
+            started_at = _parse_timestamp(envelope.get('timestamp', 0))
             continue
-        if msg_type != 'message':
+        if msg_type != 'message' or msg is None:
             continue
-        msg = data.get('message', {})
         role = msg.get('role')
         if not role:
             continue
-        timestamp = _parse_timestamp(msg.get('timestamp') or data.get('timestamp', 0))
+        timestamp = _parse_timestamp(msg.get('timestamp') or envelope.get('timestamp', 0))
         duration = 0
         if last_timestamp and timestamp:
             duration = timestamp - last_timestamp
@@ -1295,13 +1284,10 @@ def _line_index_of_first_user_message(path: Path) -> Optional[int]:
             for i, line in enumerate(f):
                 if '"role"' not in line or 'user' not in line:
                     continue
-                try:
-                    d = json.loads(line.strip())
-                except json.JSONDecodeError:
-                    continue
-                if d.get('type') != 'message':
+                env, msg = parse_session_jsonl_line(line)
+                if env is None or env.get('type') != 'message' or msg is None:
                     continue
-                if (d.get('message') or {}).get('role') == 'user':
+                if msg.get('role') == 'user':
                     return i
     except (OSError, IOError):
         pass

package/dashboard/main.py

@@ -13,14 +13,35 @@ import asyncio
 async def lifespan(app: FastAPI):
     """应用生命周期：启动时启动文件监听，关闭时停止"""
     loop = asyncio.get_running_loop()
+    probe_stop = None
     try:
         from watchers.file_watcher import start_file_watcher
+        from core.config_fortify import get_fortify_config
+
         start_file_watcher(loop)
+        cfg = get_fortify_config()
+        if cfg.cache_preload:
+            try:
+                from status.status_calculator import get_agents_with_status
+
+                get_agents_with_status()
+            except Exception as e:
+                from core.error_handler import record_error
+
+                record_error("unknown", str(e), "main:cache_preload", exc=e)
+        from status.cache_fp_probe import start_cache_fp_probe_background
+
+        probe_stop = start_cache_fp_probe_background()
     except Exception as e:
-        print(f"[Main] 文件监听启动失败: {e}")
+        from core.error_handler import record_error
+
+        record_error("unknown", str(e), "main:file_watcher_start", exc=e)
     yield
     try:
+        if probe_stop is not None:
+            probe_stop.set()
         from watchers.file_watcher import stop_file_watcher
+
         stop_file_watcher()
     except Exception:
         pass
@@ -47,11 +68,12 @@ app.add_middleware(
 import sys
 sys.path.append(str(Path(__file__).parent))
 
-from api import agents, subagents, websocket, performance, collaboration, agents_config, errors, timeline, chains, agent_config_api, error_analysis, debug_paths, version
+from api import agents, subagents, websocket, performance, collaboration, agents_config, errors, timeline, chains, agent_config_api, error_analysis, debug_paths, version, fortify_routes
 
 # 注册 API 路由
 app.include_router(agents.router, prefix="/api", tags=["agents"])
 app.include_router(errors.router, prefix="/api", tags=["errors"])
+app.include_router(fortify_routes.router, prefix="/api", tags=["fortify"])
 app.include_router(agents_config.router, prefix="/api", tags=["agents-config"])
 app.include_router(subagents.router, prefix="/api", tags=["subagents"])
 app.include_router(websocket.router, tags=["websocket"])

package/dashboard/mechanism_reader.py

@@ -7,7 +7,7 @@ from typing import Dict, Any, List
 
 
 from data.config_reader import get_openclaw_root, normalize_openclaw_agent_id
-from data.session_reader import normalize_sessions_index
+from data.session_reader import normalize_sessions_index, _load_sessions_index_file
 
 
 def get_agent_mechanisms(agent_id: str) -> Dict[str, Any]:
@@ -30,9 +30,8 @@ def get_agent_mechanisms(agent_id: str) -> Dict[str, Any]:
         return result
     
     try:
-        with open(sessions_index, 'r', encoding='utf-8') as f:
-            data = json.load(f)
-        if not isinstance(data, dict):
+        data = _load_sessions_index_file(sessions_index)
+        if not data:
             return result
         
         # 取最新 session 的机制信息（兼容 sessions.json 顶层或 entries 嵌套）
@@ -129,6 +128,6 @@ def get_agent_mechanisms(agent_id: str) -> Dict[str, Any]:
 
 def get_all_agents_mechanisms() -> List[Dict[str, Any]]:
     """获取所有 Agent 的机制使用情况"""
-    from .config_reader import get_agents_list
+    from data.config_reader import get_agents_list
     agents = get_agents_list()
     return [get_agent_mechanisms(a.get('id', '')) for a in agents if a.get('id')]

package/dashboard/mechanisms.py

@@ -14,14 +14,14 @@ router = APIRouter()
 @router.get("/mechanisms")
 async def get_mechanisms():
     """获取所有 Agent 的机制使用情况"""
-    from data.mechanism_reader import get_all_agents_mechanisms
+    from mechanism_reader import get_all_agents_mechanisms
     return get_all_agents_mechanisms()
 
 
 @router.get("/mechanisms/{agent_id}")
 async def get_agent_mechanisms(agent_id: str):
     """获取单个 Agent 的机制使用情况"""
-    from data.mechanism_reader import get_agent_mechanisms
+    from mechanism_reader import get_agent_mechanisms
     from data.config_reader import get_agent_config
 
     if not get_agent_config(agent_id):

package/dashboard/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+markers =
+    benchmark: 可选性能烟测（对负载敏感，默认与主套件一起跑）

package/dashboard/requirements.txt

@@ -4,3 +4,8 @@ pydantic==2.11.7
 python-multipart==0.0.20
 watchdog>=3.0.0
 tzdata
+jsonschema>=4.0.0
+psutil>=5.9.0
+pytest>=7.0.0
+pytest-asyncio>=0.23.0
+httpx>=0.27.0

package/dashboard/status/cache_fp_probe.py

@@ -0,0 +1,40 @@
+"""可选后台线程：周期性对 StatusCache 做 mtime 双验证剔除（RISK-004）。"""
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Optional
+
+_LOG = logging.getLogger("openclaw.fortify.cache_probe")
+
+
+def start_cache_fp_probe_background() -> Optional[threading.Event]:
+    """
+    若 OPENCLAW_CACHE_FP_PROBE_INTERVAL > 0，启动守护线程并返回用于停止的 Event；
+    否则返回 None。
+    """
+    from core.config_fortify import get_fortify_config
+
+    interval = get_fortify_config().cache_fp_probe_interval_sec
+    if interval <= 0:
+        return None
+
+    stop = threading.Event()
+
+    def loop() -> None:
+        from status.status_cache import get_cache
+
+        while not stop.is_set():
+            if stop.wait(timeout=interval):
+                break
+            try:
+                n = get_cache().invalidate_stale_fp_entries()
+                if n:
+                    _LOG.info("cache_fp_probe removed %s stale cache entries", n)
+            except Exception as e:
+                from core.error_handler import record_error
+
+                record_error("unknown", str(e), "cache_fp_probe", exc=e)
+
+    threading.Thread(target=loop, daemon=True, name="openclaw_cache_fp_probe").start()
+    return stop

package/dashboard/status/status_cache.py

@@ -2,113 +2,240 @@
 状态缓存 - 缓存 Agent 状态计算结果
 通过缓存减少重复的文件读取操作，提升状态计算性能
 """
+from __future__ import annotations
+
+import sys
 import threading
 import time
-from typing import Dict, Any, Optional
+from pathlib import Path
+from typing import Any, Dict, Optional
 
+try:
+    import psutil
+except ImportError:
+    psutil = None  # type: ignore
 
-class StatusCache:
-    """Agent 状态缓存（线程安全）
-    
-    功能：
-    - 缓存 Agent 状态计算结果
-    - TTL 机制自动过期
-    - 文件变更时主动失效缓存
-    - 线程安全（使用锁保护）
-    - 最大条目数限制，超出时清理最旧条目
+
+def _estimate_payload_size(data: Dict[str, Any]) -> int:
+    n = 256
+    for k, v in data.items():
+        if str(k).startswith("_"):
+            continue
+        n += sys.getsizeof(k) + sys.getsizeof(v)
+    return n
+
+
+def source_mtimes_for_agent_cache(agent_id: str) -> Dict[str, Optional[float]]:
     """
-    
-    def __init__(self, ttl_ms: int = 1000, max_size: int = 100):
-        """
-        初始化缓存
-        
-        Args:
-            ttl_ms: 缓存过期时间（毫秒），默认 1 秒
-            max_size: 最大条目数，超出时清理最旧条目，默认 100
-        """
+    用于缓存「双验证」：与状态计算强相关的源文件 mtime。
+    TTL 通过后若任一 mtime 变化则视为 miss（REQ_002-SPEC-06）。
+    """
+    from data.config_reader import get_openclaw_root, normalize_openclaw_agent_id
+
+    aid = normalize_openclaw_agent_id(agent_id)
+    root = get_openclaw_root()
+    out: Dict[str, Optional[float]] = {}
+    paths: Dict[str, Path] = {
+        "sessions_index": root / "agents" / aid / "sessions" / "sessions.json",
+        "subagent_runs": root / "subagents" / "runs.json",
+    }
+    for key, p in paths.items():
+        try:
+            out[key] = p.stat().st_mtime if p.is_file() else None
+        except OSError:
+            out[key] = None
+    return out
+
+
+class StatusCache:
+    """Agent 状态缓存（线程安全）"""
+
+    def __init__(self, ttl_ms: int = 1000, max_size: int = 100, max_memory_mb: int = 100):
         self.ttl_ms = ttl_ms
         self.max_size = max_size
+        self.max_memory_bytes = max_memory_mb * 1024 * 1024
         self._cache: Dict[str, Dict[str, Any]] = {}
         self._lock = threading.Lock()
-    
+        self._hits = 0
+        self._misses = 0
+        self._evictions = 0
+        self._fp_invalidations = 0
+        self._stale_fallback_reads = 0
+        self.preload_enabled = True
+
     def get(self, agent_id: str) -> Optional[Dict[str, Any]]:
-        """
-        获取缓存的状态
-        
-        Args:
-            agent_id: Agent ID
-            
-        Returns:
-            缓存的状态数据，未命中或已过期返回 None
-        """
         with self._lock:
             entry = self._cache.get(agent_id)
             if not entry:
+                self._misses += 1
                 return None
-            
-            # 检查是否过期
             now = time.time() * 1000
-            if now - entry['_timestamp'] > self.ttl_ms:
-                del self._cache[agent_id]
+            if now - entry["_timestamp"] > self.ttl_ms:
+                # TTL 逻辑 miss，但保留条目供 IO 降级时 get_stale_fallback（REQ_003-AC-003）
+                self._misses += 1
                 return None
-            
-            # 返回状态数据（不包含元数据）
-            return {k: v for k, v in entry.items() if not k.startswith('_')}
-    
+            from core.config_fortify import get_fortify_config
+
+            if get_fortify_config().cache_double_check:
+                fp = entry.get("_fp")
+                if fp is not None:
+                    current = source_mtimes_for_agent_cache(agent_id)
+                    if current != fp:
+                        del self._cache[agent_id]
+                        self._misses += 1
+                        self._fp_invalidations += 1
+                        return None
+            self._hits += 1
+            entry["_last_access"] = now
+            return {k: v for k, v in entry.items() if not str(k).startswith("_")}
+
+    def get_stale_fallback(self, agent_id: str) -> Optional[Dict[str, Any]]:
+        """忽略 TTL 与 mtime 双验证，返回仍驻留在缓存中的最近一条数据（降级读）。"""
+        with self._lock:
+            entry = self._cache.get(agent_id)
+            if not entry:
+                return None
+            self._stale_fallback_reads += 1
+            now = time.time() * 1000
+            entry["_last_access"] = now
+            return {k: v for k, v in entry.items() if not str(k).startswith("_")}
+
     def set(self, agent_id: str, data: Dict[str, Any]) -> None:
-        """
-        设置缓存
-        
-        Args:
-            agent_id: Agent ID
-            data: 状态数据
-        """
         with self._lock:
-            # 限制缓存大小：超出时删除最旧的条目
             if len(self._cache) >= self.max_size and agent_id not in self._cache:
-                oldest_key = min(
-                    self._cache.keys(),
-                    key=lambda k: self._cache[k].get('_timestamp', 0)
-                )
-                del self._cache[oldest_key]
-            
+                self._evict_oldest(exclude=agent_id)
+
+            now = time.time() * 1000
+            est = _estimate_payload_size(data)
+            from core.config_fortify import get_fortify_config
+
+            fp: Optional[Dict[str, Optional[float]]] = None
+            if get_fortify_config().cache_double_check:
+                fp = source_mtimes_for_agent_cache(agent_id)
             self._cache[agent_id] = {
                 **data,
-                '_timestamp': time.time() * 1000
+                "_timestamp": now,
+                "_last_access": now,
+                "_est_bytes": est,
+                **({"_fp": fp} if fp is not None else {}),
             }
-    
+            self._enforce_memory(agent_id)
+
+    def _evict_oldest(self, exclude: Optional[str] = None) -> None:
+        keys = [k for k in self._cache if k != exclude]
+        if not keys:
+            return
+        oldest_key = min(
+            keys,
+            key=lambda k: self._cache[k].get("_last_access", self._cache[k].get("_timestamp", 0)),
+        )
+        del self._cache[oldest_key]
+        self._evictions += 1
+
+    def _total_estimated_bytes(self) -> int:
+        return int(sum(self._cache[k].get("_est_bytes", 0) for k in self._cache))
+
+    def _enforce_memory(self, protect_key: Optional[str] = None) -> None:
+        while self._total_estimated_bytes() > self.max_memory_bytes and len(self._cache) > 1:
+            self._evict_oldest(exclude=protect_key)
+            if protect_key and len(self._cache) == 1:
+                break
+
     def invalidate(self, agent_id: Optional[str] = None) -> None:
-        """
-        失效缓存
-        
-        Args:
-            agent_id: 指定 Agent ID，None 表示清空所有
-        """
         with self._lock:
             if agent_id:
                 self._cache.pop(agent_id, None)
             else:
                 self._cache.clear()
-    
-    def get_stats(self) -> Dict[str, Any]:
+
+    def invalidate_stale_fp_entries(self) -> int:
         """
-        获取缓存统计信息
-        
-        Returns:
-            {'size': int, 'ttl_ms': int, 'max_size': int}
+        后台探针：对仍在 TTL 内的条目比对 mtime 指纹，不一致则剔除（RISK-004 / NFR-R-004）。
+        与 get() 内双验证逻辑一致，适用于长时间无请求时的最终一致补强。
         """
+        from core.config_fortify import get_fortify_config
+
+        if not get_fortify_config().cache_double_check:
+            return 0
+        invalidated = 0
         with self._lock:
+            agent_ids = list(self._cache.keys())
+        now_ms = time.time() * 1000
+        for agent_id in agent_ids:
+            with self._lock:
+                entry = self._cache.get(agent_id)
+                if not entry:
+                    continue
+                if now_ms - entry["_timestamp"] > self.ttl_ms:
+                    continue
+                fp = entry.get("_fp")
+                if fp is None:
+                    continue
+            current = source_mtimes_for_agent_cache(agent_id)
+            if current == fp:
+                continue
+            with self._lock:
+                entry2 = self._cache.get(agent_id)
+                if entry2 and entry2.get("_fp") == fp:
+                    del self._cache[agent_id]
+                    self._fp_invalidations += 1
+                    invalidated += 1
+        return invalidated
+
+    def get_stats(self) -> Dict[str, Any]:
+        from core.config_fortify import get_fortify_config
+
+        cfg = get_fortify_config()
+        dbl = cfg.cache_double_check
+        with self._lock:
+            total = self._hits + self._misses
+            hit_rate = (self._hits / total) if total else 0.0
+            rss_mb = None
+            if psutil:
+                try:
+                    rss_mb = round(psutil.Process().memory_info().rss / (1024 * 1024), 2)
+                except Exception:
+                    pass
             return {
-                'size': len(self._cache),
-                'ttl_ms': self.ttl_ms,
-                'max_size': self.max_size
+                "size": len(self._cache),
+                "max_size": self.max_size,
+                "memory_usage_mb": round(self._total_estimated_bytes() / (1024 * 1024), 3),
+                "memory_estimate_mb": round(self._total_estimated_bytes() / (1024 * 1024), 3),
+                "max_memory_mb": round(self.max_memory_bytes / (1024 * 1024), 2),
+                "process_rss_mb": rss_mb,
+                "hit_rate": round(hit_rate, 4),
+                "ttl_seconds": self.ttl_ms / 1000.0,
+                "preload_enabled": self.preload_enabled,
+                "cache_double_check": dbl,
+                "fp_probe_interval_sec": cfg.cache_fp_probe_interval_sec,
+                "stats": {
+                    "hits": self._hits,
+                    "misses": self._misses,
+                    "evictions": self._evictions,
+                    "fp_invalidations": self._fp_invalidations,
+                    "stale_fallback_reads": self._stale_fallback_reads,
+                },
             }
 
 
-# 全局单例
-_cache = StatusCache(ttl_ms=1000)
+_cache_instance: Optional[StatusCache] = None
 
 
 def get_cache() -> StatusCache:
-    """获取全局缓存实例"""
-    return _cache
+    global _cache_instance
+    if _cache_instance is None:
+        from core.config_fortify import get_fortify_config
+
+        c = get_fortify_config()
+        _cache_instance = StatusCache(
+            ttl_ms=c.cache_ttl_seconds * 1000,
+            max_size=c.cache_max_entries,
+            max_memory_mb=c.cache_max_memory_mb,
+        )
+        _cache_instance.preload_enabled = c.cache_preload
+    return _cache_instance
+
+
+def reset_cache_for_tests() -> None:
+    global _cache_instance
+    _cache_instance = None