@baimingtao/lbs-agent 1.0.0

package/runtime/orchestration/tool_guardrails.py

@@ -0,0 +1,249 @@
+"""
+Tool Guardrails — 工具护栏控制器。
+
+对标 Hermes tool_guardrails.py。提供：
+- 重复调用检测（同一工具 + 相同参数连续调用）
+- 失败计数 + halt 阈值（连续失败超限则停止）
+- 幂等工具豁免（read_file 等只读工具不限制重复）
+- per-turn reset（每轮迭代重置计数）
+
+设计原则：
+- before_call → 返回 ToolGuardrailDecision（allow / deny / halt）
+- after_call → 记录结果（成功/失败），更新计数
+- halt → 主循环应停止执行
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# ── 幂等工具（只读，允许重复调用） ──────────────────
+IDEMPOTENT_TOOLS = frozenset({
+    "read_file", "search_files", "web_search", "list_files",
+    "skills_list", "skill_view", "session_search", "models",
+    "status", "inspect", "vision_analyze",
+})
+
+# ── 默认配置 ───────────────────────────────────────
+DEFAULT_MAX_REPEAT = 3       # 同一工具+参数最多重复调用次数
+DEFAULT_MAX_FAILURES = 5     # 单轮最多连续失败次数
+DEFAULT_MAX_TOOL_CALLS = 30  # 单轮最多工具调用总次数
+
+
+@dataclass
+class ToolCallSignature:
+    """工具调用的规范签名（用于去重）。"""
+    tool_name: str
+    args_hash: str
+
+    @classmethod
+    def from_call(cls, tool_name: str, args: dict | None) -> "ToolCallSignature":
+        """从调用参数生成签名。"""
+        canonical = _canonical_args(args)
+        return cls(
+            tool_name=tool_name,
+            args_hash=_sha256(canonical),
+        )
+
+
+@dataclass
+class ToolGuardrailDecision:
+    """护栏决策。"""
+    allow: bool = True
+    reason: str = ""
+    action: str = "allow"  # allow | deny | halt
+
+    def allows_execution(self) -> bool:
+        return self.allow
+
+    def should_halt(self) -> bool:
+        return self.action == "halt"
+
+
+@dataclass
+class ToolCallGuardrailConfig:
+    """护栏配置。"""
+    max_repeat: int = DEFAULT_MAX_REPEAT
+    max_failures: int = DEFAULT_MAX_FAILURES
+    max_tool_calls: int = DEFAULT_MAX_TOOL_CALLS
+    idempotent_tools: frozenset = field(default_factory=lambda: IDEMPOTENT_TOOLS)
+
+    @classmethod
+    def from_mapping(cls, data: dict | None) -> "ToolCallGuardrailConfig":
+        if not data:
+            return cls()
+        return cls(
+            max_repeat=data.get("max_repeat", DEFAULT_MAX_REPEAT),
+            max_failures=data.get("max_failures", DEFAULT_MAX_FAILURES),
+            max_tool_calls=data.get("max_tool_calls", DEFAULT_MAX_TOOL_CALLS),
+        )
+
+
+class ToolCallGuardrailController:
+    """工具护栏控制器。
+
+    使用方式：
+        controller = ToolCallGuardrailController(config)
+        
+        # 每轮开始
+        controller.reset_for_turn()
+        
+        # 工具调用前
+        decision = controller.before_call("write_file", {"path": "x.py"})
+        if not decision.allows_execution():
+            # 跳过或停止
+            ...
+        
+        # 工具调用后
+        controller.after_call("write_file", result="success", error="")
+    """
+
+    def __init__(self, config: ToolCallGuardrailConfig | None = None):
+        self.config = config or ToolCallGuardrailConfig()
+        self._call_history: list[ToolCallSignature] = []
+        self._failure_count = 0
+        self._total_calls = 0
+        self._halt_decision: Optional[ToolGuardrailDecision] = None
+
+    def reset_for_turn(self) -> None:
+        """每轮迭代开始时重置。"""
+        self._call_history.clear()
+        self._failure_count = 0
+        self._total_calls = 0
+        self._halt_decision = None
+
+    def halt_decision(self) -> ToolGuardrailDecision | None:
+        """返回当前 halt 决策（如果有）。"""
+        return self._halt_decision
+
+    def before_call(self, tool_name: str, args: dict | None) -> ToolGuardrailDecision:
+        """工具调用前检查。
+
+        Returns:
+            ToolGuardrailDecision: allow / deny / halt
+        """
+        # 如果已经 halt，继续 halt
+        if self._halt_decision:
+            return self._halt_decision
+
+        # 检查总调用次数
+        if self._total_calls >= self.config.max_tool_calls:
+            self._halt_decision = ToolGuardrailDecision(
+                allow=False,
+                reason=f"工具调用总数超限 ({self._total_calls}/{self.config.max_tool_calls})",
+                action="halt",
+            )
+            logger.warning(f"ToolGuardrail HALT: {self._halt_decision.reason}")
+            return self._halt_decision
+
+        # 检查连续失败
+        if self._failure_count >= self.config.max_failures:
+            self._halt_decision = ToolGuardrailDecision(
+                allow=False,
+                reason=f"连续失败次数超限 ({self._failure_count}/{self.config.max_failures})",
+                action="halt",
+            )
+            logger.warning(f"ToolGuardrail HALT: {self._halt_decision.reason}")
+            return self._halt_decision
+
+        # 幂等工具跳过重复检测
+        if self._is_idempotent(tool_name):
+            self._total_calls += 1
+            return ToolGuardrailDecision(allow=True)
+
+        # 重复调用检测
+        sig = ToolCallSignature.from_call(tool_name, args)
+        repeat_count = sum(1 for s in self._call_history if s.tool_name == sig.tool_name and s.args_hash == sig.args_hash)
+
+        if repeat_count >= self.config.max_repeat:
+            reason = f"重复调用 {tool_name}({repeat_count + 1}次，参数相同)"
+            logger.info(f"ToolGuardrail DENY: {reason}")
+            return ToolGuardrailDecision(
+                allow=False,
+                reason=reason,
+                action="deny",
+            )
+
+        # 记录调用
+        self._call_history.append(sig)
+        self._total_calls += 1
+        return ToolGuardrailDecision(allow=True)
+
+    def after_call(self, tool_name: str, result: str | None, error: str = "") -> None:
+        """工具调用后记录结果。"""
+        success, reason = classify_tool_failure(tool_name, result, error)
+        if success:
+            self._failure_count = 0  # 成功则重置失败计数
+        else:
+            self._failure_count += 1
+            logger.info(f"ToolGuardrail: {tool_name} failed ({self._failure_count}/{self.config.max_failures}): {reason}")
+
+    def _is_idempotent(self, tool_name: str) -> bool:
+        """判断工具是否幂等（只读）。"""
+        return tool_name in self.config.idempotent_tools
+
+    def stats(self) -> dict:
+        """返回当前统计。"""
+        return {
+            "total_calls": self._total_calls,
+            "failure_count": self._failure_count,
+            "unique_signatures": len(set(
+                (s.tool_name, s.args_hash) for s in self._call_history
+            )),
+            "halted": self._halt_decision is not None,
+        }
+
+
+# ── 辅助函数 ───────────────────────────────────────
+
+def classify_tool_failure(tool_name: str, result: str | None, error: str = "") -> tuple[bool, str]:
+    """分类工具调用是否失败。
+
+    Returns:
+        (success: bool, reason: str)
+    """
+    if error:
+        return False, f"error: {error[:100]}"
+    if result is None:
+        return False, "result is None"
+    if isinstance(result, str):
+        lower = result.lower()
+        if lower.startswith("error") or lower.startswith("exception"):
+            return False, f"result starts with error: {result[:100]}"
+        if "traceback" in lower and "error" in lower:
+            return False, "result contains traceback"
+    return True, "ok"
+
+
+def toolguard_synthetic_result(decision: ToolGuardrailDecision) -> str:
+    """为被拒绝的调用生成合成结果（让 LLM 看到拒绝原因）。"""
+    return f"[GUARDRAIL] 工具调用被拒绝: {decision.reason}"
+
+
+def toolguard_failure_hint(tool_name: str, failure_count: int) -> str:
+    """为连续失败的工具生成恢复提示。"""
+    if failure_count >= 3:
+        return f"工具 {tool_name} 已连续失败 {failure_count} 次，请尝试不同方法或参数。"
+    if failure_count >= 2:
+        return f"工具 {tool_name} 已失败 {failure_count} 次，请检查参数。"
+    return ""
+
+
+def _canonical_args(args: dict | None) -> str:
+    """规范化参数字典为字符串。"""
+    if not args:
+        return "{}"
+    try:
+        import json
+        return json.dumps(args, sort_keys=True, ensure_ascii=False, default=str)
+    except Exception:
+        return str(sorted(args.items()))
+
+
+def _sha256(text: str) -> str:
+    """计算 SHA256 摘要。"""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]

package/runtime/orchestration/tracer.py

@@ -0,0 +1,403 @@
+"""AgentTracer — Agent 可观测性引擎。
+
+零侵入 hook 模式：不改变现有调用链，只 hook 已有事件点。
+
+数据流：
+  AgentLoop._trace() ─→ AgentTracer.on_trace()
+  model_attempts.append() ─→ AgentTracer.on_model_attempt()
+  CompressionResult ─→ AgentTracer.on_compression()
+  RetryEngine.stats ─→ AgentTracer.on_retry_stats()
+
+导出：
+  .timeline() → JSON 时序列表（给外部工具看）
+  .summary() → 人类可读统计
+  .save(path) → 导出 .json 文件
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+
+# ── 数据类 ──
+
+@dataclass
+class StepRecord:
+    """单轮迭代的汇总记录。"""
+    iteration: int = 0
+    duration_ms: float = 0.0
+    llm_calls: int = 0
+    tool_calls: int = 0
+    model: str = ""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    input_chars: int = 0
+    output_chars: int = 0
+    compressed: bool = False
+    error: str = ""
+
+
+@dataclass
+class TimelineEntry:
+    """时序事件。兼容 RunTraceEvent 格式，额外带 token/耗时。"""
+    at: str = ""
+    phase: str = ""
+    transition: str = ""
+    iteration: int = 0
+    agent: str = ""
+    message: str = ""
+    duration_ms: float = 0.0
+    tokens_in: int = 0
+    tokens_out: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "at": self.at,
+            "phase": self.phase,
+            "transition": self.transition,
+            "iteration": self.iteration,
+            "agent": self.agent,
+            "message": self.message,
+            "duration_ms": round(self.duration_ms, 1),
+            "tokens_in": self.tokens_in,
+            "tokens_out": self.tokens_out,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class ModelCost:
+    """单模型的费用统计。"""
+    model: str = ""
+    calls: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_duration_ms: float = 0.0
+    success: int = 0
+    error: int = 0
+    estimated_cost: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class TracerSnapshot:
+    """快照报告（任一时刻的完整状态）。"""
+    agent_name: str = ""
+    started_at: str = ""
+    elapsed_seconds: float = 0.0
+    iterations: int = 0
+    tool_calls: int = 0
+    llm_calls: int = 0
+    total_input_tokens: int = 0
+    total_output_tokens: int = 0
+    total_duration_ms: float = 0.0
+    estimated_cost: float = 0.0
+    errors: int = 0
+    retries: int = 0
+    fallbacks: int = 0
+    degrades: int = 0
+    compressions: int = 0
+    circuit_state: str = "closed"
+    status: str = ""
+
+
+# ── 定价表（常用模型，单位：$/M tokens）──
+
+_MODEL_PRICING: dict[str, tuple[float, float]] = {
+    # (input_cost_per_M, output_cost_per_M)
+    "gpt-4o": (2.50, 10.00),
+    "gpt-4o-mini": (0.15, 0.60),
+    "gpt-4.1": (2.00, 8.00),
+    "gpt-4.1-mini": (0.40, 1.60),
+    "gpt-4.1-nano": (0.10, 0.40),
+    "claude-sonnet-4": (3.00, 15.00),
+    "claude-3.5-haiku": (0.80, 4.00),
+    "claude-opus-4": (15.00, 75.00),
+    "deepseek-v4": (0.14, 0.28),
+    "deepseek-v4-flash": (0.07, 0.14),
+    "deepseek-r1": (0.55, 2.19),
+    "deepseek-coder-v2": (0.15, 0.60),
+    "gemini-2.0-flash": (0.10, 0.40),
+    "gemini-2.0-pro": (2.00, 8.00),
+}
+
+
+def _estimate_cost(model: str, input_tokens: int, output_tokens: int) -> float:
+    """估算调用费用（美元）。"""
+    model_key = model.strip().lower()
+    # Try exact match first, then substring
+    pricing = _MODEL_PRICING.get(model_key)
+    if pricing is None:
+        # Try partial match — prefer longer (more specific) key
+        matches = []
+        for key, price in _MODEL_PRICING.items():
+            if key in model_key or model_key in key:
+                matches.append((len(key), price))
+        if matches:
+            matches.sort(key=lambda x: x[0], reverse=True)
+            pricing = matches[0][1]
+    if pricing is None:
+        return 0.0
+    in_cost, out_cost = pricing
+    return (input_tokens * in_cost / 1_000_000) + (output_tokens * out_cost / 1_000_000)
+
+
+# ── 主类 ──
+
+class AgentTracer:
+    """Agent 可观测性引擎。每 AgentLoop 一个实例。"""
+
+    def __init__(self, agent_name: str = ""):
+        self.agent_name = agent_name
+        self._start = time.time()
+        self._start_iso = datetime.now(timezone.utc).isoformat()
+
+        # 时序列表
+        self._timeline: list[TimelineEntry] = []
+
+        # 按迭代统计
+        self._steps: dict[int, StepRecord] = {}
+
+        # 按模型统计
+        self._model_costs: dict[str, ModelCost] = {}
+
+        # 汇总
+        self._compression_count = 0
+        self._error_count = 0
+        self._retry_count = 0
+        self._fallback_count = 0
+        self._degrade_count = 0
+        self._tool_call_count = 0
+        self._llm_call_count = 0
+        self._circuit_state = "closed"
+        self._status = "running"
+
+    # ── Hook 入口 ──
+
+    def on_trace(self, phase: str, transition: str, iteration: int = 0,
+                 message: str = "", metadata: dict[str, Any] = None,
+                 duration_ms: float = 0.0,
+                 tokens_in: int = 0, tokens_out: int = 0) -> None:
+        """从 RunTraceEvent 接入。"""
+        entry = TimelineEntry(
+            at=datetime.now(timezone.utc).isoformat(),
+            phase=phase,
+            transition=transition,
+            iteration=iteration,
+            agent=self.agent_name,
+            message=message,
+            duration_ms=duration_ms,
+            tokens_in=tokens_in,
+            tokens_out=tokens_out,
+            metadata=metadata or {},
+        )
+        self._timeline.append(entry)
+
+        # 同步更新 step 统计
+        step = self._steps.setdefault(iteration, StepRecord(iteration=iteration))
+        step.duration_ms += duration_ms
+        step.input_tokens += tokens_in
+        step.output_tokens += tokens_out
+        step.input_chars += int(metadata.get("before_chars", 0) or 0) if isinstance(metadata, dict) else 0
+
+        if transition == "error" or transition == "failed":
+            step.error = message
+
+    def on_model_attempt(self, model: str, status: str, duration_ms: float = 0.0,
+                         input_tokens: int = 0, output_tokens: int = 0,
+                         error: str = "", iteration: int = 0) -> None:
+        """从 model_attempts.append() 接入。"""
+        self._llm_call_count += 1
+
+        if model not in self._model_costs:
+            self._model_costs[model] = ModelCost(model=model)
+        mc = self._model_costs[model]
+        mc.calls += 1
+        mc.input_tokens += input_tokens
+        mc.output_tokens += output_tokens
+        mc.total_duration_ms += duration_ms
+        mc.estimated_cost += _estimate_cost(model, input_tokens, output_tokens)
+
+        if status == "success":
+            mc.success += 1
+        else:
+            mc.error += 1
+            self._error_count += 1
+
+        # 更新 step
+        step = self._steps.setdefault(iteration, StepRecord(iteration=iteration))
+        step.llm_calls += 1
+        step.model = model or step.model
+        step.duration_ms += duration_ms
+        step.input_tokens += input_tokens
+        step.output_tokens += output_tokens
+
+        # 加到 timeline
+        transition = "llm_response" if status == "success" else "llm_error"
+        self.on_trace(
+            phase="llm_call", transition=transition,
+            iteration=iteration,
+            message=f"{model}: {status}" + (f" ({error[:60]})" if error else ""),
+            duration_ms=duration_ms,
+            tokens_in=input_tokens, tokens_out=output_tokens,
+        )
+
+    def on_tool_exec(self, tool_name: str, success: bool, duration_ms: float = 0.0,
+                     input_chars: int = 0, output_chars: int = 0,
+                     error: str = "", iteration: int = 0) -> None:
+        """从 ToolCallExecutor 接入。"""
+        self._tool_call_count += 1
+        step = self._steps.setdefault(iteration, StepRecord(iteration=iteration))
+        step.tool_calls += 1
+        step.duration_ms += duration_ms
+
+        transition = "tool_result" if success else "tool_error"
+        msg = f"{tool_name}: {'ok' if success else 'fail'}"
+        if error:
+            msg += f" ({error[:60]})"
+        self.on_trace(
+            phase="tool_execution", transition=transition,
+            iteration=iteration, message=msg,
+            duration_ms=duration_ms,
+            metadata={"tool": tool_name, "success": success, "input_chars": input_chars, "output_chars": output_chars},
+        )
+
+    def on_compression(self, before_chars: int, after_chars: int,
+                       dropped: int, method: str = "none",
+                       warnings: list[str] = None) -> None:
+        """从 CompressionResult 接入。"""
+        self._compression_count += 1
+        self.on_trace(
+            phase="context_preflight", transition="compressed",
+            message=f"{method}: {before_chars}→{after_chars} chars, dropped {dropped} msgs",
+            metadata={
+                "before_chars": before_chars, "after_chars": after_chars,
+                "dropped": dropped, "method": method,
+                "warnings": warnings or [],
+            },
+        )
+
+    def on_retry(self, reason: str, attempt: int, delay: float = 0.0,
+                 fallback: bool = False, degrade: bool = False) -> None:
+        """从 RetryEngine 接入。"""
+        if fallback:
+            self._fallback_count += 1
+        elif degrade:
+            self._degrade_count += 1
+        else:
+            self._retry_count += 1
+        self.on_trace(
+            phase="retry", transition="backoff" if not fallback and not degrade else ("fallback" if fallback else "degrade"),
+            message=f"{reason} (attempt={attempt}, delay={delay:.1f}s)",
+            metadata={"reason": reason, "attempt": attempt, "delay": delay, "fallback": fallback, "degrade": degrade},
+        )
+
+    def on_circuit(self, state: str) -> None:
+        """熔断器状态变更。"""
+        self._circuit_state = state
+        self.on_trace(
+            phase="circuit_breaker", transition=state,
+            message=f"circuit → {state}",
+        )
+
+    def set_status(self, status: str) -> None:
+        """AgentLoop 状态变更。"""
+        self._status = status
+
+    # ── 导出 ──
+
+    def timeline(self) -> list[dict[str, Any]]:
+        """完整时序列表（JSON 友好）。"""
+        return [e.to_dict() for e in self._timeline]
+
+    def steps(self) -> list[dict[str, Any]]:
+        """按迭代汇总。"""
+        return [asdict(s) for s in sorted(self._steps.values(), key=lambda x: x.iteration)]
+
+    def model_costs(self) -> list[dict[str, Any]]:
+        """按模型费用。"""
+        return [mc.to_dict() for mc in self._model_costs.values()]
+
+    def snapshot(self) -> TracerSnapshot:
+        """当前快照。"""
+        elapsed = time.time() - self._start
+        total_input = sum(mc.input_tokens for mc in self._model_costs.values())
+        total_output = sum(mc.output_tokens for mc in self._model_costs.values())
+        total_cost = sum(mc.estimated_cost for mc in self._model_costs.values())
+        total_dur = sum(mc.total_duration_ms for mc in self._model_costs.values())
+        max_iter = max(self._steps.keys()) if self._steps else 0
+
+        return TracerSnapshot(
+            agent_name=self.agent_name,
+            started_at=self._start_iso,
+            elapsed_seconds=round(elapsed, 3),
+            iterations=max_iter,
+            tool_calls=self._tool_call_count,
+            llm_calls=self._llm_call_count,
+            total_input_tokens=total_input,
+            total_output_tokens=total_output,
+            total_duration_ms=round(total_dur, 1),
+            estimated_cost=round(total_cost, 4),
+            errors=self._error_count,
+            retries=self._retry_count,
+            fallbacks=self._fallback_count,
+            degrades=self._degrade_count,
+            compressions=self._compression_count,
+            circuit_state=self._circuit_state,
+            status=self._status,
+        )
+
+    def summary_text(self) -> str:
+        """人类可读摘要。"""
+        s = self.snapshot()
+        lines = [
+            f"Agent: {s.agent_name}",
+            f"Status: {s.status}",
+            f"Elapsed: {s.elapsed_seconds:.1f}s",
+            f"Iterations: {s.iterations}",
+            f"LLM calls: {s.llm_calls}  |  Tool calls: {s.tool_calls}",
+            f"Tokens: {s.total_input_tokens:,} in / {s.total_output_tokens:,} out",
+            f"Est cost: ${s.estimated_cost:.4f}",
+            f"Errors: {s.errors}  |  Retries: {s.retries}  |  Fallbacks: {s.fallbacks}",
+            f"Degrades: {s.degrades}  |  Compressions: {s.compressions}",
+            f"Circuit: {s.circuit_state}",
+        ]
+        if self._model_costs:
+            lines.append("")
+            lines.append("Models:")
+            for mc in sorted(self._model_costs.values(), key=lambda m: m.calls, reverse=True):
+                lines.append(
+                    f"  {mc.model}: {mc.calls} calls, "
+                    f"{mc.input_tokens:,} in / {mc.output_tokens:,} out, "
+                    f"${mc.estimated_cost:.4f}"
+                )
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """完整数据导出（JSON 友好）。"""
+        return {
+            "agent_name": self.agent_name,
+            "started_at": self._start_iso,
+            "elapsed_seconds": round(time.time() - self._start, 1),
+            "snapshot": asdict(self.snapshot()),
+            "timeline": self.timeline(),
+            "steps": self.steps(),
+            "model_costs": self.model_costs(),
+        }
+
+    def save(self, path: str | None = None) -> str:
+        """导出为 .json 文件。"""
+        if path is None:
+            ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+            path = f"trace_{self.agent_name}_{ts}.json"
+        data = self.to_dict()
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2, default=str)
+        return path

package/runtime/orchestration/verification/__init__.py

@@ -0,0 +1,14 @@
+"""Verification layer — 工具/Worker/压缩/最终回答验收。"""
+
+from .completion import CompletionVerifier, VerificationOutcome
+from .tool_result import ToolResultVerifier
+from .worker_result import WorkerResultVerifier
+from .task_acceptance import TaskAcceptanceVerifier
+
+__all__ = [
+    "CompletionVerifier",
+    "VerificationOutcome",
+    "ToolResultVerifier",
+    "WorkerResultVerifier",
+    "TaskAcceptanceVerifier",
+]