auto-agent-kit 0.1.0__py3-none-any.whl

auto_agent_kit/__init__.py

@@ -0,0 +1,18 @@
+"""AutoAgentKit — 生产级 AI Agent 工具包"""
+__version__ = "0.1.0"
+
+from auto_agent_kit.core.plan_mode import PlanMode
+from auto_agent_kit.core.error_reflection import ErrorReflection, ErrorCategory, RecoveryStrategy
+from auto_agent_kit.core.tool_router import ToolRouter, ToolPhase
+from auto_agent_kit.core.dashboard import Dashboard
+from auto_agent_kit.core.access_control import AccessControl, PermissionLevel
+from auto_agent_kit.core.mcp_server import MCPServer
+
+__all__ = [
+    "PlanMode",
+    "ErrorReflection", "ErrorCategory", "RecoveryStrategy",
+    "ToolRouter", "ToolPhase",
+    "Dashboard",
+    "AccessControl", "PermissionLevel",
+    "MCPServer",
+]

auto_agent_kit/core/__init__.py

@@ -0,0 +1 @@
+"""AutoAgentKit 核心模块"""

auto_agent_kit/core/access_control.py

@@ -0,0 +1,202 @@
+"""AccessControl — 访问控制模块
+
+4 级权限策略 + 操作审批。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any, Optional
+
+
+class PermissionLevel(Enum):
+    """权限等级"""
+    SAFE = auto()  # 安全操作 — 自动允许
+    NORMAL = auto()  # 普通操作 — 自动允许，记录日志
+    SENSITIVE = auto()  # 敏感操作 — 需要审批
+    DANGEROUS = auto()  # 危险操作 — 需要审批 + 二次确认
+
+
+class OperationType(Enum):
+    """操作类型"""
+    READ = auto()
+    WRITE = auto()
+    DELETE = auto()
+    EXECUTE = auto()
+    NETWORK = auto()
+    CONFIG = auto()
+    ADMIN = auto()
+
+
+# 操作类型 → 默认权限等级
+DEFAULT_LEVELS: dict[OperationType, PermissionLevel] = {
+    OperationType.READ: PermissionLevel.SAFE,
+    OperationType.WRITE: PermissionLevel.NORMAL,
+    OperationType.DELETE: PermissionLevel.DANGEROUS,
+    OperationType.EXECUTE: PermissionLevel.SENSITIVE,
+    OperationType.NETWORK: PermissionLevel.NORMAL,
+    OperationType.CONFIG: PermissionLevel.SENSITIVE,
+    OperationType.ADMIN: PermissionLevel.DANGEROUS,
+}
+
+
+@dataclass
+class AccessRule:
+    """访问规则"""
+    pattern: str  # 路径/命令模式，支持 * 通配符
+    level: PermissionLevel
+    operation: Optional[OperationType] = None
+
+
+@dataclass
+class AccessLog:
+    """访问日志"""
+    timestamp: float
+    operation: str
+    level: PermissionLevel
+    granted: bool
+    reason: str = ""
+
+
+class AccessControl:
+    """访问控制 — 4 级权限策略"""
+
+    def __init__(self):
+        self._rules: list[AccessRule] = []
+        self._logs: list[AccessLog] = []
+        self._max_logs: int = 1000
+        self._pending_approvals: list[dict] = []
+
+    def add_rule(self, pattern: str, level: PermissionLevel,
+                 operation: Optional[OperationType] = None):
+        """添加访问规则"""
+        self._rules.append(AccessRule(pattern=pattern, level=level, operation=operation))
+
+    def add_default_rules(self):
+        """添加默认规则"""
+        # 安全操作
+        self.add_rule("read:*", PermissionLevel.SAFE, OperationType.READ)
+        self.add_rule("list:*", PermissionLevel.SAFE, OperationType.READ)
+        self.add_rule("search:*", PermissionLevel.SAFE, OperationType.READ)
+
+        # 普通操作
+        self.add_rule("write:workspace/*", PermissionLevel.NORMAL, OperationType.WRITE)
+        self.add_rule("write:memory/*", PermissionLevel.NORMAL, OperationType.WRITE)
+        self.add_rule("network:fetch:*", PermissionLevel.NORMAL, OperationType.NETWORK)
+
+        # 敏感操作
+        self.add_rule("execute:python*", PermissionLevel.SENSITIVE, OperationType.EXECUTE)
+        self.add_rule("write:config/*", PermissionLevel.SENSITIVE, OperationType.WRITE)
+        self.add_rule("network:send:*", PermissionLevel.SENSITIVE, OperationType.NETWORK)
+
+        # 危险操作
+        self.add_rule("delete:*", PermissionLevel.DANGEROUS, OperationType.DELETE)
+        self.add_rule("execute:rm*", PermissionLevel.DANGEROUS, OperationType.EXECUTE)
+        self.add_rule("execute:format*", PermissionLevel.DANGEROUS, OperationType.EXECUTE)
+        self.add_rule("config:system:*", PermissionLevel.DANGEROUS, OperationType.CONFIG)
+
+    def check(self, operation: str, op_type: Optional[OperationType] = None) -> dict:
+        """检查操作权限"""
+        # 查找匹配规则
+        matched_rule = None
+        for rule in self._rules:
+            if self._match_pattern(rule.pattern, operation):
+                if op_type is None or rule.operation is None or rule.operation == op_type:
+                    matched_rule = rule
+                    break
+
+        level = matched_rule.level if matched_rule else PermissionLevel.SENSITIVE
+
+        import time
+        result = {
+            "operation": operation,
+            "level": level.name,
+            "granted": False,
+            "needs_approval": level in (PermissionLevel.SENSITIVE, PermissionLevel.DANGEROUS),
+            "matched_rule": matched_rule.pattern if matched_rule else None,
+        }
+
+        # SAFE 和 NORMAL 自动允许
+        if level == PermissionLevel.SAFE:
+            result["granted"] = True
+        elif level == PermissionLevel.NORMAL:
+            result["granted"] = True
+
+        self._log(operation, level, result["granted"])
+        return result
+
+    def request_approval(self, operation: str, reason: str = "") -> dict:
+        """请求审批"""
+        import time
+        approval = {
+            "id": f"app_{int(time.time())}_{len(self._pending_approvals)}",
+            "operation": operation,
+            "reason": reason,
+            "timestamp": time.time(),
+            "status": "pending",
+        }
+        self._pending_approvals.append(approval)
+        return approval
+
+    def approve(self, approval_id: str) -> bool:
+        """批准操作"""
+        for a in self._pending_approvals:
+            if a["id"] == approval_id and a["status"] == "pending":
+                a["status"] = "approved"
+                self._log(a["operation"], PermissionLevel.SENSITIVE, True, "approved")
+                return True
+        return False
+
+    def reject(self, approval_id: str) -> bool:
+        """拒绝操作"""
+        for a in self._pending_approvals:
+            if a["id"] == approval_id and a["status"] == "pending":
+                a["status"] = "rejected"
+                self._log(a["operation"], PermissionLevel.SENSITIVE, False, "rejected")
+                return True
+        return False
+
+    def get_pending_approvals(self) -> list[dict]:
+        """获取待审批列表"""
+        return [a for a in self._pending_approvals if a["status"] == "pending"]
+
+    def get_logs(self, limit: int = 50) -> list[dict]:
+        """获取访问日志"""
+        return [
+            {"timestamp": l.timestamp, "operation": l.operation,
+             "level": l.level.name, "granted": l.granted, "reason": l.reason}
+            for l in self._logs[-limit:]
+        ]
+
+    def get_stats(self) -> dict:
+        """获取统计"""
+        total = len(self._logs)
+        granted = sum(1 for l in self._logs if l.granted)
+        return {
+            "total_checks": total,
+            "granted": granted,
+            "denied": total - granted,
+            "rules_count": len(self._rules),
+            "pending_approvals": len(self.get_pending_approvals()),
+        }
+
+    def _log(self, operation: str, level: PermissionLevel, granted: bool, reason: str = ""):
+        import time
+        self._logs.append(AccessLog(
+            timestamp=time.time(),
+            operation=operation,
+            level=level,
+            granted=granted,
+            reason=reason,
+        ))
+        if len(self._logs) > self._max_logs:
+            self._logs = self._logs[-self._max_logs:]
+
+    @staticmethod
+    def _match_pattern(pattern: str, operation: str) -> bool:
+        """简单的通配符匹配"""
+        if pattern.endswith("*"):
+            prefix = pattern[:-1]
+            return operation.startswith(prefix)
+        return pattern == operation

auto_agent_kit/core/dashboard.py

@@ -0,0 +1,145 @@
+"""Dashboard — 仪表板
+
+实时监控 Agent 运行指标。
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class MetricPoint:
+    """单个指标数据点"""
+    timestamp: float
+    value: float
+    label: str = ""
+
+
+@dataclass
+class MetricSeries:
+    """指标时间序列"""
+    name: str
+    points: list[MetricPoint] = field(default_factory=list)
+    max_points: int = 1000
+
+    def add(self, value: float, label: str = ""):
+        self.points.append(MetricPoint(timestamp=time.time(), value=value, label=label))
+        if len(self.points) > self.max_points:
+            self.points = self.points[-self.max_points:]
+
+    @property
+    def last(self) -> Optional[float]:
+        return self.points[-1].value if self.points else None
+
+    @property
+    def avg(self) -> float:
+        if not self.points:
+            return 0.0
+        return sum(p.value for p in self.points) / len(self.points)
+
+    @property
+    def min(self) -> float:
+        return min(p.value for p in self.points) if self.points else 0.0
+
+    @property
+    def max(self) -> float:
+        return max(p.value for p in self.points) if self.points else 0.0
+
+
+class Dashboard:
+    """仪表板 — 实时监控 Agent 运行指标"""
+
+    def __init__(self, max_series_points: int = 1000):
+        self._series: dict[str, MetricSeries] = {}
+        self._events: list[dict] = []
+        self._max_events: int = 500
+        self._max_series_points = max_series_points
+        self._started_at: float = time.time()
+
+    def _get_series(self, name: str) -> MetricSeries:
+        if name not in self._series:
+            self._series[name] = MetricSeries(name=name, max_points=self._max_series_points)
+        return self._series[name]
+
+    def record(self, metric: str, value: float, label: str = ""):
+        """记录一个指标值"""
+        self._get_series(metric).add(value, label)
+
+    def record_event(self, event_type: str, data: Optional[dict] = None):
+        """记录一个事件"""
+        self._events.append({
+            "timestamp": time.time(),
+            "type": event_type,
+            "data": data or {},
+        })
+        if len(self._events) > self._max_events:
+            self._events = self._events[-self._max_events:]
+
+    def record_tool_call(self, tool_name: str, success: bool, duration_ms: float):
+        """记录工具调用"""
+        self.record(f"tool.{tool_name}.duration", duration_ms)
+        self.record("tool.calls", 1)
+        if not success:
+            self.record("tool.errors", 1)
+        self.record_event("tool_call", {
+            "tool": tool_name,
+            "success": success,
+            "duration_ms": duration_ms,
+        })
+
+    def get_metric(self, name: str) -> Optional[MetricSeries]:
+        """获取指标序列"""
+        return self._series.get(name)
+
+    def get_snapshot(self) -> dict:
+        """获取当前快照"""
+        uptime = time.time() - self._started_at
+        snapshot = {
+            "uptime_seconds": uptime,
+            "uptime_formatted": self._format_duration(uptime),
+            "metrics": {},
+            "recent_events": self._events[-20:],
+        }
+        for name, series in self._series.items():
+            snapshot["metrics"][name] = {
+                "last": series.last,
+                "avg": series.avg,
+                "min": series.min,
+                "max": series.max,
+                "count": len(series.points),
+            }
+        return snapshot
+
+    def get_summary(self) -> str:
+        """获取文本摘要"""
+        s = self.get_snapshot()
+        lines = [f"📊 Dashboard — 运行 {s['uptime_formatted']}"]
+        for name, m in s["metrics"].items():
+            lines.append(f"  {name}: last={m['last']:.2f} avg={m['avg']:.2f} count={m['count']}")
+        return "\n".join(lines)
+
+    def to_json(self, path: str):
+        """导出到 JSON 文件"""
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(self.get_snapshot(), f, ensure_ascii=False, indent=2)
+
+    def reset(self):
+        """重置所有指标"""
+        self._series.clear()
+        self._events.clear()
+        self._started_at = time.time()
+
+    @staticmethod
+    def _format_duration(seconds: float) -> str:
+        hours = int(seconds // 3600)
+        minutes = int((seconds % 3600) // 60)
+        secs = int(seconds % 60)
+        if hours > 0:
+            return f"{hours}h{minutes}m{secs}s"
+        elif minutes > 0:
+            return f"{minutes}m{secs}s"
+        return f"{secs}s"

auto_agent_kit/core/error_reflection.py

@@ -0,0 +1,210 @@
+"""ErrorReflection — 错误反射模块
+
+工具失败自动分类（20+类型），精确恢复策略。
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class ErrorCategory(Enum):
+    """错误分类（20+ 类型）"""
+    # 认证/授权
+    AUTH_INVALID = "auth_invalid"
+    AUTH_EXPIRED = "auth_expired"
+    PERMISSION_DENIED = "permission_denied"
+    # 计费/配额
+    BILLING_ERROR = "billing_error"
+    RATE_LIMIT = "rate_limit"
+    QUOTA_EXCEEDED = "quota_exceeded"
+    # 网络/超时
+    TIMEOUT = "timeout"
+    NETWORK_ERROR = "network_error"
+    DNS_FAILURE = "dns_failure"
+    CONNECTION_REFUSED = "connection_refused"
+    # 服务端
+    SERVER_ERROR = "server_error"  # 5xx
+    SERVICE_UNAVAILABLE = "service_unavailable"
+    # 客户端
+    BAD_REQUEST = "bad_request"  # 4xx
+    NOT_FOUND = "not_found"
+    VALIDATION_ERROR = "validation_error"
+    # 数据
+    PARSE_ERROR = "parse_error"
+    ENCODING_ERROR = "encoding_error"
+    DATA_INTEGRITY = "data_integrity"
+    # 上下文
+    CONTEXT_OVERFLOW = "context_overflow"
+    CONTENT_FILTER = "content_filter"
+    # 系统
+    RESOURCE_EXHAUSTED = "resource_exhausted"
+    INTERNAL_ERROR = "internal_error"
+    UNKNOWN = "unknown"
+
+
+class RecoveryStrategy(Enum):
+    """恢复策略"""
+    RETRY = "retry"  # 直接重试
+    EXPONENTIAL_BACKOFF = "exponential_backoff"  # 指数退避重试
+    ROTATE_CREDENTIAL = "rotate_credential"  # 轮换凭证
+    COMPRESS_CONTEXT = "compress_context"  # 压缩上下文
+    FALLBACK_MODEL = "fallback_model"  # 切换备用模型
+    FALLBACK_PROVIDER = "fallback_provider"  # 切换备用提供商
+    DEGRADE = "degrade"  # 降级返回部分结果
+    ABORT = "abort"  # 放弃
+    RETRY_WITH_DELAY = "retry_with_delay"  # 延迟后重试
+    CLEAR_CACHE = "clear_cache"  # 清除缓存
+
+
+@dataclass
+class ErrorRecord:
+    """错误记录"""
+    timestamp: float = field(default_factory=time.time)
+    category: ErrorCategory = ErrorCategory.UNKNOWN
+    message: str = ""
+    source: str = ""
+    context: dict[str, Any] = field(default_factory=dict)
+    recovery_used: Optional[RecoveryStrategy] = None
+    recovered: bool = False
+
+
+class ErrorReflection:
+    """错误反射 — 自动分类错误并选择恢复策略"""
+
+    # 错误 → 恢复策略映射
+    STRATEGY_MAP: dict[ErrorCategory, RecoveryStrategy] = {
+        ErrorCategory.AUTH_INVALID: RecoveryStrategy.ROTATE_CREDENTIAL,
+        ErrorCategory.AUTH_EXPIRED: RecoveryStrategy.ROTATE_CREDENTIAL,
+        ErrorCategory.PERMISSION_DENIED: RecoveryStrategy.ABORT,
+        ErrorCategory.BILLING_ERROR: RecoveryStrategy.ABORT,
+        ErrorCategory.RATE_LIMIT: RecoveryStrategy.EXPONENTIAL_BACKOFF,
+        ErrorCategory.QUOTA_EXCEEDED: RecoveryStrategy.FALLBACK_PROVIDER,
+        ErrorCategory.TIMEOUT: RecoveryStrategy.EXPONENTIAL_BACKOFF,
+        ErrorCategory.NETWORK_ERROR: RecoveryStrategy.RETRY,
+        ErrorCategory.DNS_FAILURE: RecoveryStrategy.RETRY_WITH_DELAY,
+        ErrorCategory.CONNECTION_REFUSED: RecoveryStrategy.RETRY_WITH_DELAY,
+        ErrorCategory.SERVER_ERROR: RecoveryStrategy.EXPONENTIAL_BACKOFF,
+        ErrorCategory.SERVICE_UNAVAILABLE: RecoveryStrategy.FALLBACK_PROVIDER,
+        ErrorCategory.BAD_REQUEST: RecoveryStrategy.ABORT,
+        ErrorCategory.NOT_FOUND: RecoveryStrategy.ABORT,
+        ErrorCategory.VALIDATION_ERROR: RecoveryStrategy.ABORT,
+        ErrorCategory.PARSE_ERROR: RecoveryStrategy.RETRY,
+        ErrorCategory.ENCODING_ERROR: RecoveryStrategy.RETRY,
+        ErrorCategory.DATA_INTEGRITY: RecoveryStrategy.ABORT,
+        ErrorCategory.CONTEXT_OVERFLOW: RecoveryStrategy.COMPRESS_CONTEXT,
+        ErrorCategory.CONTENT_FILTER: RecoveryStrategy.DEGRADE,
+        ErrorCategory.RESOURCE_EXHAUSTED: RecoveryStrategy.FALLBACK_MODEL,
+        ErrorCategory.INTERNAL_ERROR: RecoveryStrategy.RETRY,
+        ErrorCategory.UNKNOWN: RecoveryStrategy.RETRY,
+    }
+
+    # 关键词 → 错误分类映射
+    KEYWORD_MAP: list[tuple[list[str], ErrorCategory]] = [
+        (["rate limit", "too many requests", "429"], ErrorCategory.RATE_LIMIT),
+        (["timeout", "timed out", "deadline exceeded"], ErrorCategory.TIMEOUT),
+        (["auth", "unauthorized", "401", "403", "api key"], ErrorCategory.AUTH_INVALID),
+        (["expired", "token expired"], ErrorCategory.AUTH_EXPIRED),
+        (["permission", "forbidden", "not allowed"], ErrorCategory.PERMISSION_DENIED),
+        (["billing", "quota", "insufficient"], ErrorCategory.BILLING_ERROR),
+        (["context length", "context window", "token limit"], ErrorCategory.CONTEXT_OVERFLOW),
+        (["content filter", "content policy", "safety"], ErrorCategory.CONTENT_FILTER),
+        (["not found", "404"], ErrorCategory.NOT_FOUND),
+        (["server error", "500", "502", "503"], ErrorCategory.SERVER_ERROR),
+        (["connection refused", "econnrefused"], ErrorCategory.CONNECTION_REFUSED),
+        (["dns", "enotfound", "getaddrinfo"], ErrorCategory.DNS_FAILURE),
+        (["parse", "json decode", "unexpected token"], ErrorCategory.PARSE_ERROR),
+        (["encoding", "unicode", "utf"], ErrorCategory.ENCODING_ERROR),
+        (["validation", "invalid"], ErrorCategory.VALIDATION_ERROR),
+        (["resource exhausted", "memory", "disk"], ErrorCategory.RESOURCE_EXHAUSTED),
+    ]
+
+    def __init__(self, max_retries: int = 3):
+        self.max_retries = max_retries
+        self.history: list[ErrorRecord] = []
+        self._consecutive_failures: dict[str, int] = {}
+
+    def classify(self, error: Exception | str, source: str = "") -> ErrorCategory:
+        """分类错误"""
+        msg = str(error).lower()
+        for keywords, category in self.KEYWORD_MAP:
+            if any(kw in msg for kw in keywords):
+                return category
+        return ErrorCategory.UNKNOWN
+
+    def get_strategy(self, category: ErrorCategory) -> RecoveryStrategy:
+        """获取恢复策略"""
+        return self.STRATEGY_MAP.get(category, RecoveryStrategy.RETRY)
+
+    def classify_and_recover(
+        self,
+        error: Exception | str,
+        source: str = "",
+        context: Optional[dict] = None,
+    ) -> dict:
+        """分类错误并返回恢复建议"""
+        category = self.classify(error, source)
+        strategy = self.get_strategy(category)
+
+        record = ErrorRecord(
+            category=category,
+            message=str(error),
+            source=source,
+            context=context or {},
+            recovery_used=strategy,
+        )
+        self.history.append(record)
+
+        # 追踪连续失败
+        key = f"{source}:{category.value}"
+        self._consecutive_failures[key] = self._consecutive_failures.get(key, 0) + 1
+        consecutive = self._consecutive_failures[key]
+
+        # 连续失败升级策略
+        if consecutive >= 3 and strategy in (RecoveryStrategy.RETRY, RecoveryStrategy.EXPONENTIAL_BACKOFF):
+            upgraded = RecoveryStrategy.FALLBACK_PROVIDER
+            record.recovery_used = upgraded
+            return {
+                "category": category.value,
+                "strategy": upgraded.value,
+                "consecutive_failures": consecutive,
+                "message": str(error),
+                "upgraded": True,
+            }
+
+        return {
+            "category": category.value,
+            "strategy": strategy.value,
+            "consecutive_failures": consecutive,
+            "message": str(error),
+            "upgraded": False,
+        }
+
+    def report_recovery(self, success: bool, error_ref: Optional[str] = None):
+        """报告恢复结果"""
+        if self.history:
+            self.history[-1].recovered = success
+            if success:
+                key = f"{self.history[-1].source}:{self.history[-1].category.value}"
+                self._consecutive_failures[key] = 0
+
+    def get_stats(self) -> dict:
+        """获取错误统计"""
+        total = len(self.history)
+        if total == 0:
+            return {"total": 0}
+        by_category: dict[str, int] = {}
+        recovered = 0
+        for r in self.history:
+            by_category[r.category.value] = by_category.get(r.category.value, 0) + 1
+            if r.recovered:
+                recovered += 1
+        return {
+            "total": total,
+            "by_category": by_category,
+            "recovered": recovered,
+            "recovery_rate": recovered / total if total > 0 else 0,
+        }