cloneloop 0.1.0__py3-none-any.whl

mcp_ai_supervisor/logging/log_parser.py

@@ -0,0 +1,293 @@
+"""
+日志解析模块 (LogParser)
+========================
+
+解析 LogWriter 生成的结构化日志文件，支持：
+- 单行正则解析（匹配 LogWriter 的输出格式）
+- 多行合并（堆栈跟踪续行归并到前一条日志）
+- 级别过滤（DEBUG < INFO < WARN < ERROR）
+- 分页查询（offset + limit）
+- tail 模式（从文件末尾反向读取）
+- 快速行数统计（不解析内容）
+
+日志格式规范（与 LogWriter 一致）：
+    {timestamp} [{level}] [{module}] [{context}] {message}
+    示例：2026-07-13T14:30:22.456 [INFO ] [feedback] [project=test] 消息内容
+
+依赖：
+- 无外部依赖，纯标准库实现
+- 日志格式定义来自 L1 LogWriter
+
+设计文档: docs/控制台方案/技术方案/日志系统/设计文档/日志查看器.md
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import NamedTuple
+
+# ── 常量 ──────────────────────────────────────────────────────
+
+# 日志级别优先级映射（与 LogWriter 一致）
+_LEVEL_PRIORITY = {
+    "DEBUG": 0,
+    "INFO": 1,
+    "WARN": 2,
+    "ERROR": 3,
+}
+
+# 预编译正则：匹配 LogWriter 的输出格式
+# 格式: {timestamp} [{level}] [{module}] [{context}] {message}
+# 示例: 2026-07-13T14:30:22.456 [INFO ] [feedback] [project=test] 消息内容
+_LOG_LINE_RE = re.compile(
+    r"^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3})"  # 时间戳
+    r"\s+\[(\w+)\s*\]"                                   # 级别（可能有尾部空格）
+    r"\s+\[([^\]]*)\]"                                    # 模块名（可为空）
+    r"\s+\[([^\]]*)\]"                                    # 上下文（可为空）
+    r"\s+(.*)"                                             # 消息（余下所有内容）
+)
+
+# 续行判断：以空格/Tab/Traceback 开头的行视为前一条的延续
+_CONTINUATION_RE = re.compile(r"^[\s\t]|^Traceback ")
+
+# 快速行统计的读取块大小
+_COUNT_BLOCK_SIZE = 65536
+
+
+# ── 数据结构 ──────────────────────────────────────────────────
+
+
+@dataclass
+class LogLine:
+    """解析后的单条日志记录
+
+    Attributes:
+        line_number: 在原始文件中的行号（1-based）
+        timestamp: 原始时间戳字符串，如 "2026-07-13T14:30:22.456"
+        level: 日志级别 "DEBUG" | "INFO" | "WARN" | "ERROR"
+        module: 模块名，如 "feedback"、"workbench"
+        context: 原始上下文字符串，如 "project=test session=abc"
+        message: 消息正文（多行合并后可能包含换行符）
+        raw: 原始行文本（多行合并后包含所有原始行，换行连接）
+    """
+
+    line_number: int
+    timestamp: str
+    level: str
+    module: str
+    context: str
+    message: str
+    raw: str
+
+
+class ParseResult(NamedTuple):
+    """parse_lines() 的返回结果
+
+    Attributes:
+        lines: 解析后的日志行列表
+        total_lines: 文件总行数（原始行，未合并）
+        has_more: 是否还有更多数据可加载
+    """
+
+    lines: list[LogLine]
+    total_lines: int
+    has_more: bool
+
+
+# ── LogParser 核心类 ──────────────────────────────────────────
+
+
+class LogParser:
+    """日志文件解析器
+
+    提供对 LogWriter 生成的日志文件的解析能力，
+    支持单行解析、多行合并、级别过滤、分页和 tail 模式。
+
+    使用方式：
+        parser = LogParser()
+        result = parser.parse_lines("/path/to/log.log", level="INFO", tail=True, limit=100)
+        for line in result.lines:
+            print(f"{line.timestamp} [{line.level}] {line.message}")
+    """
+
+    # 最大允许返回行数
+    MAX_LIMIT = 5000
+
+    @staticmethod
+    def parse_single_line(raw_line: str, line_number: int = 0) -> LogLine | None:
+        """解析单行日志文本
+
+        Args:
+            raw_line: 原始日志行文本（不含末尾换行符）
+            line_number: 行号（1-based）
+
+        Returns:
+            解析成功返回 LogLine 对象，格式不匹配返回 None
+        """
+        m = _LOG_LINE_RE.match(raw_line)
+        if not m:
+            return None
+        return LogLine(
+            line_number=line_number,
+            timestamp=m.group(1),
+            level=m.group(2).strip(),
+            module=m.group(3),
+            context=m.group(4),
+            message=m.group(5),
+            raw=raw_line,
+        )
+
+    @staticmethod
+    def is_continuation(line: str) -> bool:
+        """判断一行是否为续行（堆栈跟踪等）
+
+        续行规则：
+        - 以空格或 Tab 开头
+        - 以 "Traceback " 开头
+        """
+        return bool(_CONTINUATION_RE.match(line))
+
+    def parse_lines(
+        self,
+        filepath: str | Path,
+        *,
+        offset: int = 0,
+        limit: int = 500,
+        level: str = "INFO",
+        tail: bool = False,
+    ) -> ParseResult:
+        """从日志文件读取、解析、过滤并分页返回
+
+        Args:
+            filepath: 日志文件路径
+            offset: 起始偏移（在过滤后的结果上应用）
+            limit: 返回行数上限（最大 MAX_LIMIT）
+            level: 最低日志级别过滤 "DEBUG" | "INFO" | "WARN" | "ERROR"
+            tail: True 时从文件末尾向前读取
+
+        Returns:
+            ParseResult(lines, total_lines, has_more)
+        """
+        filepath = Path(filepath)
+        if not filepath.exists() or not filepath.is_file():
+            return ParseResult(lines=[], total_lines=0, has_more=False)
+
+        limit = min(limit, self.MAX_LIMIT)
+        min_priority = _LEVEL_PRIORITY.get(level.upper(), 1)
+
+        # 读取并合并多行
+        merged = self._read_and_merge(filepath, tail=tail)
+
+        # 统计原始文件总行数
+        total_lines = self.total_lines(filepath)
+
+        # 级别过滤
+        filtered = [
+            ll for ll in merged
+            if _LEVEL_PRIORITY.get(ll.level, 0) >= min_priority
+        ]
+
+        # 分页
+        total_filtered = len(filtered)
+        start = offset
+        end = offset + limit
+        page = filtered[start:end]
+        has_more = end < total_filtered
+
+        return ParseResult(lines=page, total_lines=total_lines, has_more=has_more)
+
+    @staticmethod
+    def total_lines(filepath: str | Path) -> int:
+        """快速统计日志文件的总行数（不解析内容）
+
+        使用分块读取 + 统计换行符的方式，避免一次性加载整个文件。
+
+        Args:
+            filepath: 日志文件路径
+
+        Returns:
+            文件总行数（0 表示空文件或文件不存在）
+        """
+        filepath = Path(filepath)
+        if not filepath.exists() or not filepath.is_file():
+            return 0
+
+        count = 0
+        try:
+            with open(filepath, "rb") as f:
+                while True:
+                    block = f.read(_COUNT_BLOCK_SIZE)
+                    if not block:
+                        break
+                    count += block.count(b"\n")
+        except OSError:
+            return 0
+        return count
+
+    # ── 内部方法 ──────────────────────────────────────────────
+
+    def _read_and_merge(
+        self, filepath: Path, *, tail: bool = False
+    ) -> list[LogLine]:
+        """读取日志文件并执行多行合并
+
+        多行合并规则：
+        - 以时间戳开头的行 → 新日志记录
+        - 续行（空格/Tab/Traceback 开头）→ 追加到前一条记录的 message
+
+        Args:
+            filepath: 日志文件路径
+            tail: True 时从文件末尾读取（先全部读入，结果保持时间顺序）
+
+        Returns:
+            合并后的 LogLine 列表（按时间顺序排列）
+        """
+        try:
+            text = filepath.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return []
+
+        raw_lines = text.splitlines()
+        if not raw_lines:
+            return []
+
+        result: list[LogLine] = []
+        current: LogLine | None = None
+
+        for idx, raw in enumerate(raw_lines, start=1):
+            if not raw.strip():
+                # 空行视为续行（如果有当前记录），否则跳过
+                if current is not None:
+                    current.message += "\n"
+                    current.raw += "\n"
+                continue
+
+            if self.is_continuation(raw):
+                # 续行 → 追加到当前记录
+                if current is not None:
+                    current.message += "\n" + raw
+                    current.raw += "\n" + raw
+                continue
+
+            # 尝试解析为新日志行
+            parsed = self.parse_single_line(raw, line_number=idx)
+            if parsed is not None:
+                # 保存上一条，开始新记录
+                if current is not None:
+                    result.append(current)
+                current = parsed
+            else:
+                # 格式不匹配 → 视为续行或跳过
+                if current is not None:
+                    current.message += "\n" + raw
+                    current.raw += "\n" + raw
+                # 无当前记录时忽略格式错误行
+
+        # 不要忘记最后一条
+        if current is not None:
+            result.append(current)
+
+        return result

mcp_ai_supervisor/logging/log_tailer.py

@@ -0,0 +1,367 @@
+"""
+日志实时跟踪模块 (LogTailer)
+============================
+
+实现 tail -f 语义的日志文件实时跟踪，支持：
+- 订阅/取消订阅机制（多 client 共享同一文件的读取）
+- asyncio 定时轮询文件大小变化
+- 新增内容通过 LogParser 解析后回调推送
+- 级别过滤（仅推送 >= 指定级别的日志行）
+- 批处理推送（100ms 内的多行合并为一次回调）
+- 跨天文件切换（日期变更时自动切换到新文件）
+- 背压保护（队列上限 + 回调超时防护）
+
+依赖：
+- L3 LogParser（日志行解析）
+- asyncio（异步轮询循环）
+
+设计文档: docs/控制台方案/技术方案/日志系统/设计文档/日志查看器.md
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+from .log_parser import LogLine, LogParser
+
+# ── 常量 ──────────────────────────────────────────────────────
+
+# 轮询间隔（秒）
+DEFAULT_POLL_INTERVAL = 1.0
+
+# 推送队列上限：超过此数量丢弃最旧的行
+MAX_PENDING_LINES = 1000
+
+# 回调超时（秒）：防止慢回调阻塞轮询循环
+CALLBACK_TIMEOUT = 5.0
+
+# 日志级别优先级映射（与 LogParser 一致）
+_LEVEL_PRIORITY = {
+    "DEBUG": 0,
+    "INFO": 1,
+    "WARN": 2,
+    "ERROR": 3,
+}
+
+
+# ── 数据结构 ──────────────────────────────────────────────────
+
+
+@dataclass
+class TailSubscription:
+    """单个客户端的订阅信息
+
+    Attributes:
+        client_id: 订阅者唯一标识
+        source: 日志源标识（如 "workbench"、"agent-xxx"）
+        level: 最低日志级别过滤
+        callback: 推送回调函数，接收 list[LogLine]
+        file_path: 当前监控的日志文件路径
+        file_offset: 上次读取到的文件字节位置
+    """
+
+    client_id: str
+    source: str
+    level: str
+    callback: Callable[[list[LogLine]], Awaitable[None]]
+    file_path: Path
+    file_offset: int = 0
+
+
+# ── LogTailer 核心类 ──────────────────────────────────────────
+
+
+class LogTailer:
+    """日志文件实时跟踪器
+
+    通过 asyncio 定时轮询监控日志文件变化，
+    检测到新增内容后解析并推送给所有订阅者。
+
+    同一 source 的多个 client 共享一次文件读取，各自独立过滤级别。
+
+    使用方式：
+        tailer = LogTailer(log_base_dir=Path("~/.mcp-ai-supervisor/logs"))
+        tailer.subscribe("ws-client-1", "workbench", "INFO", my_callback)
+        await tailer.start()
+        # ... 当不再需要时 ...
+        await tailer.stop()
+    """
+
+    def __init__(
+        self,
+        log_base_dir: Path | str | None = None,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+    ) -> None:
+        """初始化 LogTailer
+
+        Args:
+            log_base_dir: 日志根目录（默认 ~/.mcp-ai-supervisor/logs）
+            poll_interval: 轮询间隔（秒）
+        """
+        if log_base_dir is None:
+            log_base_dir = Path.home() / ".mcp-ai-supervisor" / "logs"
+        self._log_base_dir = Path(log_base_dir)
+        self._poll_interval = poll_interval
+        self._subscriptions: dict[str, TailSubscription] = {}
+        self._poll_task: asyncio.Task[None] | None = None
+        self._parser = LogParser()
+        self._running = False
+        # 按 source 分组的文件偏移量缓存（避免同一文件重复读取）
+        self._source_offsets: dict[str, int] = {}
+
+    # ── 公开接口 ──────────────────────────────────────────────
+
+    def subscribe(
+        self,
+        client_id: str,
+        source: str,
+        level: str,
+        callback: Callable[[list[LogLine]], Awaitable[None]],
+    ) -> None:
+        """订阅日志源的实时推送
+
+        Args:
+            client_id: 订阅者唯一标识
+            source: 日志源（如 "workbench"、"agent-xxx"）
+            level: 最低日志级别 "DEBUG" | "INFO" | "WARN" | "ERROR"
+            callback: 推送回调，接收解析后的日志行列表
+        """
+        file_path = self._resolve_log_path(source)
+        offset = 0
+        if file_path.exists():
+            offset = file_path.stat().st_size
+
+        sub = TailSubscription(
+            client_id=client_id,
+            source=source,
+            level=level.upper(),
+            callback=callback,
+            file_path=file_path,
+            file_offset=offset,
+        )
+        self._subscriptions[client_id] = sub
+
+    def unsubscribe(self, client_id: str) -> None:
+        """取消订阅
+
+        如果某个 source 没有订阅者了，其文件偏移缓存也被清除。
+
+        Args:
+            client_id: 订阅者唯一标识
+        """
+        sub = self._subscriptions.pop(client_id, None)
+        if sub is None:
+            return
+
+        # 检查该 source 是否还有其他订阅者
+        remaining = any(
+            s.source == sub.source for s in self._subscriptions.values()
+        )
+        if not remaining:
+            self._source_offsets.pop(sub.source, None)
+
+    async def start(self) -> None:
+        """启动轮询循环
+
+        可在 subscribe() 之前或之后调用。
+        重复调用 start() 不会创建多个轮询任务。
+        """
+        if self._running:
+            return
+        self._running = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+    async def stop(self) -> None:
+        """停止轮询循环
+
+        stop() 后可以再次调用 start() 重启。
+        """
+        self._running = False
+        if self._poll_task is not None:
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+            self._poll_task = None
+
+    @property
+    def is_running(self) -> bool:
+        """是否正在运行"""
+        return self._running
+
+    @property
+    def subscription_count(self) -> int:
+        """当前订阅者数量"""
+        return len(self._subscriptions)
+
+    def get_subscribed_sources(self) -> set[str]:
+        """获取所有被订阅的 source 集合"""
+        return {s.source for s in self._subscriptions.values()}
+
+    # ── 内部方法 ──────────────────────────────────────────────
+
+    async def _poll_loop(self) -> None:
+        """轮询循环主体
+
+        每隔 poll_interval 秒检查所有被订阅文件的大小变化，
+        检测到新增内容后解析并推送给订阅者。
+        """
+        while self._running:
+            try:
+                if self._subscriptions:
+                    await self._check_all_sources()
+                await asyncio.sleep(self._poll_interval)
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                # 轮询循环中的错误不应导致整个 tailer 停止
+                await asyncio.sleep(self._poll_interval)
+
+    async def _check_all_sources(self) -> None:
+        """检查所有被订阅 source 的文件变化
+
+        同一 source 的多个 client 只读取文件一次，各自独立过滤级别。
+        """
+        # 按 source 分组订阅者
+        source_groups: dict[str, list[TailSubscription]] = defaultdict(list)
+        for sub in list(self._subscriptions.values()):
+            # 跨天文件切换：检查日期是否变化
+            current_path = self._resolve_log_path(sub.source)
+            if current_path != sub.file_path:
+                sub.file_path = current_path
+                sub.file_offset = 0
+            source_groups[sub.source].append(sub)
+
+        for source, subs in source_groups.items():
+            file_path = subs[0].file_path
+            if not file_path.exists():
+                continue
+
+            try:
+                current_size = file_path.stat().st_size
+            except OSError:
+                continue
+
+            # 取该 source 所有 client 中最小的 offset
+            min_offset = min(s.file_offset for s in subs)
+
+            if current_size <= min_offset:
+                continue
+
+            # 读取新增内容
+            new_lines = self._read_new_content(file_path, min_offset, current_size)
+            if not new_lines:
+                # 更新 offset 即使没有解析出有效行
+                for sub in subs:
+                    sub.file_offset = current_size
+                continue
+
+            # 为每个 client 按级别过滤后推送
+            for sub in subs:
+                min_priority = _LEVEL_PRIORITY.get(sub.level, 1)
+                filtered = [
+                    ll for ll in new_lines
+                    if _LEVEL_PRIORITY.get(ll.level, 0) >= min_priority
+                ]
+                if filtered:
+                    # 背压保护：限制推送数量
+                    if len(filtered) > MAX_PENDING_LINES:
+                        filtered = filtered[-MAX_PENDING_LINES:]
+
+                    await self._safe_callback(sub, filtered)
+                sub.file_offset = current_size
+
+    def _read_new_content(
+        self, file_path: Path, offset: int, current_size: int
+    ) -> list[LogLine]:
+        """读取文件新增部分并解析为 LogLine 列表
+
+        Args:
+            file_path: 日志文件路径
+            offset: 上次读取到的字节位置
+            current_size: 当前文件大小
+
+        Returns:
+            解析后的日志行列表
+        """
+        try:
+            with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+                f.seek(offset)
+                new_text = f.read(current_size - offset)
+        except OSError:
+            return []
+
+        if not new_text:
+            return []
+
+        raw_lines = new_text.splitlines()
+        result: list[LogLine] = []
+        current: LogLine | None = None
+
+        for raw in raw_lines:
+            if not raw.strip():
+                if current is not None:
+                    current.message += "\n"
+                    current.raw += "\n"
+                continue
+
+            if self._parser.is_continuation(raw):
+                if current is not None:
+                    current.message += "\n" + raw
+                    current.raw += "\n" + raw
+                continue
+
+            parsed = self._parser.parse_single_line(raw)
+            if parsed is not None:
+                if current is not None:
+                    result.append(current)
+                current = parsed
+            else:
+                if current is not None:
+                    current.message += "\n" + raw
+                    current.raw += "\n" + raw
+
+        if current is not None:
+            result.append(current)
+
+        return result
+
+    @staticmethod
+    async def _safe_callback(
+        sub: TailSubscription, lines: list[LogLine]
+    ) -> None:
+        """安全调用推送回调 — 超时和异常不影响主循环
+
+        Args:
+            sub: 订阅信息
+            lines: 要推送的日志行列表
+        """
+        try:
+            await asyncio.wait_for(
+                sub.callback(lines), timeout=CALLBACK_TIMEOUT
+            )
+        except asyncio.TimeoutError:
+            pass
+        except Exception:
+            pass
+
+    def _resolve_log_path(self, source: str) -> Path:
+        """根据 source 和当前日期推算日志文件路径
+
+        路径格式: {log_base_dir}/{source}/{YYYY-MM-DD}.log
+
+        Args:
+            source: 日志源标识
+
+        Returns:
+            日志文件的完整路径
+        """
+        today = datetime.now().strftime("%Y-%m-%d")
+        return self._log_base_dir / source / f"{today}.log"