@baimingtao/lbs-agent 1.0.0

package/runtime/orchestration/background_review.py

@@ -0,0 +1,470 @@
+"""
+Background Review — 后台自改进系统。
+
+对标 Hermes background_review.py。功能：
+- 在主会话空闲时，后台线程扫描最近的会话历史
+- 分析常见错误/失败模式（工具失败、迭代耗尽、验证不通过）
+- 生成改进建议并写入长期记忆
+- 可被 Cron 定时触发
+- 线程安全、不阻塞主循环
+"""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# ── 数据结构 ───────────────────────────────────────
+
+@dataclass
+class ReviewFinding:
+    """单条审查发现。"""
+    category: str       # tool_failure | iteration_exhausted | verification_failed | stall | other
+    severity: str       # info | warning | error
+    description: str
+    agent_name: str = ""
+    session_id: str = ""
+    suggestion: str = ""
+    timestamp: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "category": self.category,
+            "severity": self.severity,
+            "description": self.description,
+            "agent_name": self.agent_name,
+            "session_id": self.session_id,
+            "suggestion": self.suggestion,
+            "timestamp": self.timestamp,
+        }
+
+
+@dataclass
+class ReviewReport:
+    """后台审查报告。"""
+    timestamp: str = ""
+    sessions_scanned: int = 0
+    findings: list[ReviewFinding] = field(default_factory=list)
+    suggestions_written: int = 0
+    summary: str = ""
+
+    def to_dict(self) -> dict:
+        from collections import Counter
+        cat_counts = Counter(f.category for f in self.findings)
+        return {
+            "timestamp": self.timestamp,
+            "sessions_scanned": self.sessions_scanned,
+            "findings_count": len(self.findings),
+            "findings_by_category": dict(cat_counts),
+            "suggestions_written": self.suggestions_written,
+            "summary": self.summary,
+            "findings": [f.to_dict() for f in self.findings[:20]],
+        }
+
+
+# ── 配置 ───────────────────────────────────────────
+
+DEFAULT_REVIEW_INTERVAL_HOURS = 6
+DEFAULT_MAX_SESSIONS_TO_SCAN = 10
+DEFAULT_MIN_IDLE_MINUTES = 5
+
+_bg_thread: Optional[threading.Thread] = None
+_bg_stop_event = threading.Event()
+_last_review: Optional[datetime] = None
+_review_lock = threading.Lock()
+
+
+def get_interval_hours() -> int:
+    return DEFAULT_REVIEW_INTERVAL_HOURS
+
+def get_max_sessions() -> int:
+    return DEFAULT_MAX_SESSIONS_TO_SCAN
+
+def is_idle(min_idle_minutes: float = DEFAULT_MIN_IDLE_MINUTES) -> bool:
+    """检查系统是否空闲（没有活跃的 agent 运行）。"""
+    # Simple heuristic: check if there are any active sessions in the last N minutes
+    try:
+        from config.state_root import resolve_state_root
+        project_root = Path(__file__).resolve().parents[2]
+        state_root = resolve_state_root(project_root)
+        sessions_dir = Path(state_root) / "sessions"
+        if not sessions_dir.exists():
+            return True
+        cutoff = datetime.now() - timedelta(minutes=min_idle_minutes)
+        for p in sessions_dir.glob("*.json"):
+            try:
+                mtime = datetime.fromtimestamp(p.stat().st_mtime)
+                if mtime > cutoff:
+                    return False  # Recent activity
+            except Exception:
+                pass
+        return True
+    except Exception:
+        return True
+
+import os
+
+def should_run_now(now: datetime | None = None) -> bool:
+    """检查是否应该运行后台审查。"""
+    global _last_review
+    if _last_review is None:
+        return True
+    interval = timedelta(hours=get_interval_hours())
+    return (now or datetime.now()) - _last_review >= interval
+
+
+# ── 核心扫描逻辑 ───────────────────────────────────
+
+def analyze_session(session_data: dict) -> list[ReviewFinding]:
+    """分析单个会话，提取问题模式。
+
+    Args:
+        session_data: 会话数据（包含 messages / steps / result）
+
+    Returns:
+        审查发现列表
+    """
+    findings: list[ReviewFinding] = []
+    session_id = session_data.get("session_id", session_data.get("id", ""))
+    agent_name = session_data.get("agent_name", "")
+    timestamp = session_data.get("timestamp", session_data.get("created_at", ""))
+
+    # 1. 检查工具失败模式
+    messages = session_data.get("messages", [])
+    tool_errors = 0
+    for msg in messages:
+        if isinstance(msg, dict):
+            content = str(msg.get("content", ""))
+            if "[ERROR]" in content or "Traceback" in content:
+                tool_errors += 1
+    if tool_errors > 3:
+        findings.append(ReviewFinding(
+            category="tool_failure",
+            severity="warning" if tool_errors < 10 else "error",
+            description=f"Session had {tool_errors} tool errors",
+            agent_name=agent_name,
+            session_id=session_id,
+            suggestion="检查工具配置或增加错误恢复策略",
+            timestamp=timestamp,
+        ))
+
+    # 2. 检查迭代耗尽
+    result = session_data.get("result", {})
+    if isinstance(result, dict):
+        iterations = result.get("iterations", 0)
+        max_iter = result.get("max_iterations", 0)
+        if max_iter and iterations >= max_iter:
+            findings.append(ReviewFinding(
+                category="iteration_exhausted",
+                severity="warning",
+                description=f"Session exhausted all {max_iter} iterations without completing",
+                agent_name=agent_name,
+                session_id=session_id,
+                suggestion="考虑增加 max_iterations 或优化工具调用策略",
+                timestamp=timestamp,
+            ))
+
+        # 3. 检查验证失败
+        if result.get("error") == "stalled":
+            findings.append(ReviewFinding(
+                category="stall",
+                severity="warning",
+                description="Session stalled — repeated identical tool calls detected",
+                agent_name=agent_name,
+                session_id=session_id,
+                suggestion="工具护栏可能需要调整，或增加更多工具选项",
+                timestamp=timestamp,
+            ))
+
+        # 4. 检查最终失败
+        if not result.get("success", True):
+            findings.append(ReviewFinding(
+                category="verification_failed",
+                severity="error",
+                description=f"Session failed: {result.get('error', 'unknown')}",
+                agent_name=agent_name,
+                session_id=session_id,
+                suggestion="检查验证规则是否过于严格，或工具能力是否不足",
+                timestamp=timestamp,
+            ))
+
+    # 5. 基于 run_trace 的深度分析
+    run_trace = session_data.get("run_trace") or []
+    _analyze_run_trace(run_trace, agent_name, session_id, timestamp, findings)
+
+    # 6. 基于 usage_summary 的成本分析
+    usage = session_data.get("usage_summary") or {}
+    _analyze_usage(usage, agent_name, session_id, timestamp, findings)
+
+    # 7. 基于 model_attempts 的 token 分析
+    model_attempts = session_data.get("model_attempts") or []
+    _analyze_model_attempts(model_attempts, agent_name, session_id, timestamp, findings)
+
+    return findings
+
+
+def _analyze_run_trace(run_trace, agent_name, session_id, timestamp, findings):
+    """从 run_trace 事件序列中提取结构性问题。"""
+    for event in run_trace:
+        if not isinstance(event, dict):
+            continue
+        phase = event.get("phase", "")
+        transition = event.get("transition", "")
+        metadata = event.get("metadata") or {}
+
+        # guardrail 拒绝 — 检查 guardrail evidence 或 policy.allowed=False
+        if phase == "tool_execution" and transition == "failed":
+            guard = metadata.get("guardrail") or {}
+            policy = metadata.get("policy") or {}
+            if guard.get("action") == "deny" or (policy.get("allowed") is False and metadata.get("success") is False):
+                reason = guard.get("reason") or policy.get("reason") or "unknown"
+                findings.append(ReviewFinding(
+                    category="guardrail_denial",
+                    severity="warning",
+                    description=f"Tool '{metadata.get('tool', '?')}' denied by guardrail: {reason}",
+                    agent_name=agent_name,
+                    session_id=session_id,
+                    suggestion="检查 agent guardrail 配置是否与任务需求匹配",
+                    timestamp=timestamp,
+                ))
+
+        # 上下文压缩频繁
+        if phase == "context_preflight" and metadata.get("compressed"):
+            findings.append(ReviewFinding(
+                category="context_compression",
+                severity="info",
+                description="Context was compressed during this session",
+                agent_name=agent_name,
+                session_id=session_id,
+                suggestion="考虑增大 context_max_chars 或减少历史消息",
+                timestamp=timestamp,
+            ))
+
+
+def _analyze_usage(usage, agent_name, session_id, timestamp, findings):
+    """从 usage_summary 检测成本/用量异常。"""
+    if not usage:
+        return
+    cost_str = str(usage.get("total_cost_usd", "0"))
+    try:
+        cost = float(cost_str)
+    except (ValueError, TypeError):
+        cost = 0.0
+    if cost > 1.0:
+        findings.append(ReviewFinding(
+            category="high_cost",
+            severity="warning" if cost < 5.0 else "error",
+            description=f"Session cost ${cost:.2f} exceeds threshold",
+            agent_name=agent_name,
+            session_id=session_id,
+            suggestion="检查 prompt 长度、迭代次数或考虑切换更经济模型",
+            timestamp=timestamp,
+        ))
+
+
+def _analyze_model_attempts(model_attempts, agent_name, session_id, timestamp, findings):
+    """从 model_attempts 检测单次调用 token 异常。"""
+    HIGH_TOKEN_THRESHOLD = 100_000
+    for attempt in model_attempts:
+        if not isinstance(attempt, dict):
+            continue
+        input_tokens = int(attempt.get("input_tokens", 0) or 0)
+        if input_tokens > HIGH_TOKEN_THRESHOLD:
+            findings.append(ReviewFinding(
+                category="high_token_usage",
+                severity="warning",
+                description=f"Single LLM call consumed {input_tokens:,} input tokens (model={attempt.get('model', '?')})",
+                agent_name=agent_name,
+                session_id=session_id,
+                suggestion="考虑上下文压缩、prompt 精简或增大 context 压缩频率",
+                timestamp=timestamp,
+            ))
+            break  # one finding per session is enough
+
+
+def scan_recent_sessions(project_root: Path | None = None) -> ReviewReport:
+    """扫描最近的会话历史，提取改进信号。
+
+    Args:
+        project_root: 项目根目录
+
+    Returns:
+        ReviewReport
+    """
+    if project_root is None:
+        project_root = Path(__file__).resolve().parents[2]
+
+    report = ReviewReport(timestamp=datetime.now().isoformat())
+
+    # Load sessions
+    from config.state_root import resolve_state_root
+    state_root = resolve_state_root(project_root)
+    sessions_dir = Path(state_root) / "sessions"
+    if not sessions_dir.exists():
+        report.summary = "No sessions directory found"
+        return report
+
+    # Get most recent sessions
+    session_files = sorted(sessions_dir.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+    session_files = session_files[:get_max_sessions()]
+
+    for sf in session_files:
+        try:
+            data = json.loads(sf.read_text(encoding="utf-8"))
+            report.sessions_scanned += 1
+            findings = analyze_session(data)
+            report.findings.extend(findings)
+        except Exception as e:
+            logger.debug(f"Background review: failed to parse {sf.name}: {e}")
+
+    # Deduplicate findings by category+description
+    seen = set()
+    unique = []
+    for f in report.findings:
+        key = (f.category, f.description)
+        if key not in seen:
+            seen.add(key)
+            unique.append(f)
+    report.findings = unique
+
+    report.summary = (
+        f"Scanned {report.sessions_scanned} sessions, "
+        f"found {len(report.findings)} unique findings."
+    )
+
+    return report
+
+
+def write_findings_to_memory(report: ReviewReport) -> int:
+    """将审查发现写入长期记忆。
+
+    Args:
+        report: 审查报告
+
+    Returns:
+        写入的建议数
+    """
+    if not report.findings:
+        return 0
+
+    try:
+        from runtime.memory.long_term import LongTermMemory
+        from config.state_root import resolve_state_root
+        state_root = resolve_state_root(project_root)
+        ltm = LongTermMemory(Path(state_root) / "memory.db")
+
+        count = 0
+        for finding in report.findings:
+            ltm.store(
+                key=f"bg_review_{finding.category}_{datetime.now().strftime('%Y%m%d_%H%M%S')}_{count}",
+                value=json.dumps(finding.to_dict(), ensure_ascii=False),
+                namespace="background_review",
+            )
+            count += 1
+
+        return count
+    except Exception as e:
+        logger.warning(f"Background review: failed to write to memory: {e}")
+        return 0
+
+
+def run_review(project_root: Path | None = None) -> ReviewReport:
+    """执行一次后台审查。
+
+    Args:
+        project_root: 项目根目录
+
+    Returns:
+        ReviewReport
+    """
+    global _last_review
+
+    with _review_lock:
+        logger.info("Background review: scanning sessions...")
+        report = scan_recent_sessions(project_root)
+        report.suggestions_written = write_findings_to_memory(report)
+        _last_review = datetime.now()
+        logger.info(f"Background review: {report.summary}")
+        return report
+
+
+# ── 后台线程 ───────────────────────────────────────
+
+def _run_review_loop(project_root: Path | None = None, stop_event: threading.Event | None = None):
+    """后台审查循环（供线程调用）。"""
+    if stop_event is None:
+        stop_event = _bg_stop_event
+
+    while not stop_event.is_set():
+        try:
+            if is_idle() and should_run_now():
+                run_review(project_root)
+        except Exception as e:
+            logger.error(f"Background review thread error: {e}")
+
+        # Wait for next interval check (check every 5 minutes)
+        stop_event.wait(300)
+
+
+def spawn_background_review_thread(project_root: Path | None = None) -> threading.Thread:
+    """启动后台审查线程。
+
+    Args:
+        project_root: 项目根目录
+
+    Returns:
+        Thread 实例
+    """
+    global _bg_thread, _bg_stop_event
+
+    if _bg_thread and _bg_thread.is_alive():
+        logger.debug("Background review thread already running")
+        return _bg_thread
+
+    _bg_stop_event = threading.Event()
+    _bg_thread = threading.Thread(
+        target=_run_review_loop,
+        args=(project_root, _bg_stop_event),
+        name="lbs-bg-review",
+        daemon=True,
+    )
+    _bg_thread.start()
+    logger.info("Background review thread started")
+    return _bg_thread
+
+
+def stop_background_review_thread():
+    """停止后台审查线程。"""
+    global _bg_thread, _bg_stop_event
+    if _bg_thread and _bg_thread.is_alive():
+        _bg_stop_event.set()
+        _bg_thread.join(timeout=5)
+    _bg_thread = None
+
+
+def summarize_background_review_actions(report: ReviewReport) -> str:
+    """生成人类可读的审查摘要。
+
+    Args:
+        report: 审查报告
+
+    Returns:
+        摘要文本
+    """
+    lines = [
+        f"后台审查报告 ({report.timestamp})",
+        f"扫描会话: {report.sessions_scanned}",
+        f"发现问题: {len(report.findings)}",
+    ]
+    for f in report.findings[:10]:
+        lines.append(f"  [{f.severity}] {f.category}: {f.description}")
+        if f.suggestion:
+            lines.append(f"    建议: {f.suggestion}")
+    return "\n".join(lines)

package/runtime/orchestration/display.py

@@ -0,0 +1,206 @@
+"""
+Display — 格式化输出、颜色、标题生成。
+
+对标 LBS display.py，精简实现：
+  1. Colors — ANSI 颜色码（Windows 兼容）
+  2. format_title — 从任务文本生成简短标题
+  3. format_step — 格式化迭代步骤输出
+  4. format_result — 格式化最终结果
+  5. Spinner — 简易加载动画
+  6. print_box — 框线输出
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import threading
+import time
+from typing import Optional
+
+
+# ── ANSI 颜色 ──────────────────────────────────────
+
+class Colors:
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+    GRAY = "\033[90m"
+
+    # Windows 兼容
+    _enabled: Optional[bool] = None
+
+    @classmethod
+    def _check(cls) -> bool:
+        if cls._enabled is None:
+            # Windows 10+ 支持 ANSI，但需要启用
+            if sys.platform == "win32":
+                try:
+                    import ctypes
+                    kernel32 = ctypes.windll.kernel32
+                    kernel32.SetConsoleMode(kernel32.GetStdHandle(-11), 7)
+                    cls._enabled = True
+                except Exception:
+                    cls._enabled = False
+            else:
+                cls._enabled = sys.stdout.isatty()
+        return cls._enabled
+
+    @classmethod
+    def wrap(cls, text: str, color: str) -> str:
+        if cls._check():
+            return f"{color}{text}{cls.RESET}"
+        return text
+
+
+def color(text: str, c: str) -> str:
+    """快捷函数：给文本加颜色。"""
+    return Colors.wrap(text, c)
+
+def green(text: str) -> str:
+    return Colors.wrap(text, Colors.GREEN)
+
+def red(text: str) -> str:
+    return Colors.wrap(text, Colors.RED)
+
+def yellow(text: str) -> str:
+    return Colors.wrap(text, Colors.YELLOW)
+
+def cyan(text: str) -> str:
+    return Colors.wrap(text, Colors.CYAN)
+
+def gray(text: str) -> str:
+    return Colors.wrap(text, Colors.GRAY)
+
+def bold(text: str) -> str:
+    return Colors.wrap(text, Colors.BOLD)
+
+
+# ── 标题生成 ────────────────────────────────────────
+
+def format_title(task: str, max_len: int = 50) -> str:
+    """从任务文本生成简短标题。
+
+    规则：
+      1. 取第一行
+      2. 截断到 max_len
+      3. 去掉标点和特殊字符
+    """
+    if not task:
+        return "(no task)"
+    first_line = task.split("\n")[0].strip()
+    # 去掉 markdown 标记
+    first_line = re.sub(r"[*_`#>]", "", first_line)
+    if len(first_line) > max_len:
+        first_line = first_line[:max_len - 3] + "..."
+    return first_line
+
+
+# ── 格式化输出 ──────────────────────────────────────
+
+def print_box(title: str, content: str = "", color_str: str = ""):
+    """框线输出。"""
+    width = 60
+    if color_str:
+        title = color(title, color_str)
+    print(f"\n{'=' * width}")
+    if title:
+        print(f"  {title}")
+    if content:
+        print()
+        for line in content.split("\n"):
+            print(f"  {line}")
+    print(f"{'=' * width}\n")
+
+
+def format_step_header(iteration: int, max_iterations: int, phase: str = "") -> str:
+    """格式化迭代步骤标题。"""
+    phase_str = f" [{phase}]" if phase else ""
+    return f"--- 迭代 {iteration}/{max_iterations}{phase_str} ---"
+
+
+def format_tool_call(name: str, args: dict, max_preview: int = 100) -> str:
+    """格式化工具调用显示。"""
+    import json
+    args_str = json.dumps(args, ensure_ascii=False)[:max_preview]
+    return f"  {cyan('[工具]')} {bold(name)}({args_str})"
+
+
+def format_tool_result(result: str, success: bool, max_preview: int = 200) -> str:
+    """格式化工具结果显示。"""
+    preview = result[:max_preview]
+    if success:
+        return f"  {green('[结果]')} {preview}"
+    else:
+        return f"  {red('[错误]')} {preview}"
+
+
+def format_thought(content: str, max_preview: int = 300) -> str:
+    """格式化 LLM 思考输出。"""
+    preview = content[:max_preview]
+    return f"  {gray('[思考]')} {preview}"
+
+
+def format_result_summary(
+    success: bool,
+    iterations: int,
+    tool_calls: int,
+    duration: float,
+    model: str = "",
+    error: str = "",
+) -> str:
+    """格式化最终结果摘要。"""
+    status = green("✓ 成功") if success else red("✗ 失败")
+    lines = [f"  结果: {status}"]
+    lines.append(f"  迭代: {iterations}  工具调用: {tool_calls}  耗时: {duration:.1f}s")
+    if model:
+        lines.append(f"  模型: {model}")
+    if error:
+        lines.append(f"  {red('错误')}: {error[:200]}")
+    return "\n".join(lines)
+
+
+# ── Spinner ────────────────────────────────────────
+
+class Spinner:
+    """简易加载动画（后台线程）。"""
+
+    _FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+    def __init__(self, message: str = ""):
+        self._message = message
+        self._thread: Optional[threading.Thread] = None
+        self._running = False
+
+    def start(self):
+        if not Colors._check():
+            return  # 不支持 ANSI 就不显示 spinner
+        self._running = True
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+
+    def stop(self, final_message: str = ""):
+        self._running = False
+        if self._thread:
+            self._thread.join(timeout=1)
+        # 清除 spinner 行
+        if Colors._check():
+            sys.stdout.write("\r" + " " * (len(self._message) + 10) + "\r")
+            sys.stdout.flush()
+        if final_message:
+            print(final_message)
+
+    def _spin(self):
+        i = 0
+        while self._running:
+            frame = self._FRAMES[i % len(self._FRAMES)]
+            sys.stdout.write(f"\r{cyan(frame)} {self._message}")
+            sys.stdout.flush()
+            time.sleep(0.1)
+            i += 1