skillpool 4.3.0__py3-none-any.whl

skillpool/paradigm/override.py

@@ -0,0 +1,285 @@
+"""
+EmergencyOverride — 紧急降权协议。
+
+当检测到安全事件、资源耗尽或不可恢复错误时，
+EmergencyOverride 可以紧急降权 Agent 的 trust_level，
+或完全禁止特定 Skill 的执行。
+
+降权协议:
+  1. 检测触发条件（安全事件/资源耗尽/不可恢复错误）
+  2. 评估降权级别（trust_level 降低幅度）
+  3. 执行降权（修改 gate_file + 通知 TelemetryBridge）
+  4. 记录降权事件（审计日志）
+  5. 恢复机制（手动或超时后自动恢复）
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import StrEnum
+from pathlib import Path
+from typing import Optional
+
+from skillpool.config import get_data_dir
+from skillpool.telemetry import TelemetryBridge
+
+logger = logging.getLogger(__name__)
+
+
+class OverrideTrigger(StrEnum):
+    SECURITY_EVENT = "security_event"
+    RESOURCE_EXHAUSTION = "resource_exhaustion"
+    UNRECOVERABLE_ERROR = "unrecoverable_error"
+    MANUAL = "manual"
+
+
+class OverrideLevel(StrEnum):
+    WARN = "warn"  # 降低 trust_level 1 级
+    DEGRADE = "degrade"  # 降低 trust_level 2 级
+    QUARANTINE = "quarantine"  # trust_level → 0，禁止执行
+    KILL = "kill"  # 完全禁止，需要人工恢复
+
+
+@dataclass
+class OverrideEvent:
+    """降权事件记录。"""
+
+    trigger: OverrideTrigger
+    level: OverrideLevel
+    target_skill: str = ""
+    target_agent: str = ""
+    original_trust: int = 3
+    new_trust: int = 0
+    reason: str = ""
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    expires_at: Optional[str] = None  # None = 需人工恢复
+
+
+@dataclass
+class GateFile:
+    """Gate file — 单个 Skill 的门禁状态文件。
+
+    格式:
+    {
+      "skill_id": "S05a",
+      "trust_level": 3,
+      "blocked": false,
+      "override_history": [...]
+    }
+    """
+
+    skill_id: str
+    trust_level: int = 3
+    blocked: bool = False
+    override_history: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "skill_id": self.skill_id,
+            "trust_level": self.trust_level,
+            "blocked": self.blocked,
+            "override_history": self.override_history,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> GateFile:
+        return cls(
+            skill_id=data.get("skill_id", ""),
+            trust_level=data.get("trust_level", 3),
+            blocked=data.get("blocked", False),
+            override_history=data.get("override_history", []),
+        )
+
+
+class EmergencyOverride:
+    """紧急降权管理器。
+
+    Usage:
+        eo = EmergencyOverride(telemetry=bridge, gate_dir=Path("~/.skillpool/gates"))
+        event = eo.override(
+            trigger="security_event",
+            level="quarantine",
+            target_skill="S05a",
+            reason="SQL injection detected",
+        )
+        # 检查是否被降权
+        is_blocked = eo.is_blocked("S05a")
+        # 恢复
+        eo.restore("S05a")
+    """
+
+    def __init__(
+        self,
+        telemetry: Optional[TelemetryBridge] = None,
+        gate_dir: Optional[Path] = None,
+    ):
+        self.telemetry = telemetry
+        self.gate_dir = gate_dir or get_data_dir() / "gates"
+        self.gate_dir.mkdir(parents=True, exist_ok=True)
+        self._overrides: dict[str, OverrideEvent] = {}  # skill_id → latest event
+
+    def override(
+        self,
+        trigger: OverrideTrigger | str,
+        level: OverrideLevel | str,
+        target_skill: str,
+        target_agent: str = "",
+        reason: str = "",
+        current_trust: int = 3,
+        ttl_seconds: Optional[int] = None,
+    ) -> OverrideEvent:
+        """执行紧急降权。
+
+        Args:
+            trigger: 触发原因
+            level: 降权级别
+            target_skill: 目标 Skill ID
+            target_agent: 目标 Agent 名称
+            reason: 降权原因描述
+            current_trust: 当前 trust_level
+            ttl_seconds: 自动恢复时间（None = 需人工恢复）
+        """
+        trig = OverrideTrigger(trigger) if isinstance(trigger, str) else trigger
+        lvl = OverrideLevel(level) if isinstance(level, str) else level
+
+        # 计算新的 trust_level
+        new_trust = self._compute_new_trust(current_trust, lvl)
+
+        # 计算过期时间
+        expires_at = None
+        if ttl_seconds:
+            from datetime import timedelta
+
+            expires_at = (datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds)).isoformat()
+
+        event = OverrideEvent(
+            trigger=trig,
+            level=lvl,
+            target_skill=target_skill,
+            target_agent=target_agent,
+            original_trust=current_trust,
+            new_trust=new_trust,
+            reason=reason,
+            expires_at=expires_at,
+        )
+
+        # 更新 gate file — 只有 KILL 设 blocked=True, QUARANTINE 只降 trust
+        blocked = lvl == OverrideLevel.KILL
+        self._update_gate_file(target_skill, new_trust, blocked, event)
+
+        # 记录
+        self._overrides[target_skill] = event
+
+        # 发射遥测
+        if self.telemetry:
+            self.telemetry.emit(
+                event_type="emergency_override",
+                skill_id=target_skill,
+                channel="hook",
+                payload={
+                    "trigger": str(trig),
+                    "level": str(lvl),
+                    "new_trust": new_trust,
+                    "reason": reason,
+                },
+            )
+
+        return event
+
+    def is_blocked(self, skill_id: str) -> bool:
+        """检查 Skill 是否被降权/禁止。"""
+        gate = self._read_gate_file(skill_id)
+        if gate:
+            return gate.blocked or gate.trust_level == 0
+        return False
+
+    def get_trust_level(self, skill_id: str) -> int:
+        """获取 Skill 当前 trust_level（可能已被降权）。"""
+        gate = self._read_gate_file(skill_id)
+        if gate:
+            return gate.trust_level
+        return 3  # 默认
+
+    def restore(self, skill_id: str, trust_level: int = 3) -> bool:
+        """恢复 Skill 的 trust_level。"""
+        gate = self._read_gate_file(skill_id)
+        if not gate:
+            return False
+
+        gate.trust_level = trust_level
+        gate.blocked = False
+        self._write_gate_file(gate)
+
+        # 清除内存记录
+        self._overrides.pop(skill_id, None)
+
+        # 发射遥测
+        if self.telemetry:
+            self.telemetry.emit(
+                event_type="override_restored",
+                skill_id=skill_id,
+                channel="hook",
+                payload={"restored_trust": trust_level},
+            )
+
+        return True
+
+    def check_expired(self) -> list[str]:
+        """检查并自动恢复过期的降权。返回恢复的 skill_id 列表。"""
+        now = datetime.now(timezone.utc)
+        restored = []
+
+        for skill_id, event in list(self._overrides.items()):
+            if event.expires_at:
+                expires = datetime.fromisoformat(event.expires_at)
+                if now >= expires:
+                    self.restore(skill_id, event.original_trust)
+                    restored.append(skill_id)
+
+        return restored
+
+    def _compute_new_trust(self, current: int, level: OverrideLevel) -> int:
+        """根据降权级别计算新的 trust_level。"""
+        if level == OverrideLevel.WARN:
+            return max(current - 1, 0)
+        elif level == OverrideLevel.DEGRADE:
+            return max(current - 2, 0)
+        elif level == OverrideLevel.QUARANTINE:
+            return 0
+        elif level == OverrideLevel.KILL:
+            return 0
+        return current
+
+    def _update_gate_file(self, skill_id: str, trust: int, blocked: bool, event: OverrideEvent) -> None:
+        """更新 gate file。"""
+        gate = self._read_gate_file(skill_id) or GateFile(skill_id=skill_id)
+        gate.trust_level = trust
+        gate.blocked = blocked
+        gate.override_history.append(
+            {
+                "trigger": str(event.trigger),
+                "level": str(event.level),
+                "new_trust": event.new_trust,
+                "reason": event.reason,
+                "timestamp": event.timestamp,
+            }
+        )
+        self._write_gate_file(gate)
+
+    def _read_gate_file(self, skill_id: str) -> Optional[GateFile]:
+        """读取 gate file。"""
+        path = self.gate_dir / f"{skill_id}.json"
+        if path.exists():
+            try:
+                return GateFile.from_dict(json.loads(path.read_text()))
+            except Exception as e:
+                logger.warning("Failed to read gate file for %s: %s", skill_id, e)
+        return None
+
+    def _write_gate_file(self, gate: GateFile) -> None:
+        """写入 gate file。"""
+        path = self.gate_dir / f"{gate.skill_id}.json"
+        path.write_text(json.dumps(gate.to_dict(), indent=2, ensure_ascii=False))

skillpool/profile.py

@@ -0,0 +1,94 @@
+"""Agent capability profiles for skill matching and execution gating."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class AgentCapabilityProfile:
+    """Describes an agent's capabilities used to determine skill compatibility.
+
+    Attributes:
+        name: Unique identifier for the profile.
+        required_capabilities: Set of capability strings the agent possesses.
+        context_window: Maximum context window size in tokens.
+        trust_level: Trust level (1-3), higher = more privileged.
+        supported_paradigms: Set of paradigm strings the agent supports.
+    """
+
+    name: str
+    required_capabilities: set[str] = field(default_factory=set)
+    context_window: int = 128000
+    trust_level: int = 1
+    supported_paradigms: set[str] = field(default_factory=set)
+
+    def can_execute(self, skill_requirements: dict) -> tuple[bool, str]:
+        """Check whether this profile satisfies the given skill requirements.
+
+        Args:
+            skill_requirements: Dict with optional keys:
+                - 'required_capabilities': set[str] of capabilities needed
+                - 'min_trust_level': int minimum trust level
+                - 'paradigm': str paradigm the skill belongs to
+
+        Returns:
+            (True, 'ok') if all requirements are met,
+            (False, 'missing: <detail>') otherwise.
+        """
+        # Check required capabilities
+        required_caps = skill_requirements.get("required_capabilities", set())
+        if isinstance(required_caps, (list, tuple)):
+            required_caps = set(required_caps)
+        missing_caps = required_caps - self.required_capabilities
+        if missing_caps:
+            return (False, f"missing: capabilities {sorted(missing_caps)}")
+
+        # Check minimum trust level
+        min_trust = skill_requirements.get("min_trust_level", 0)
+        if min_trust > self.trust_level:
+            return (False, f"missing: trust_level {min_trust} > {self.trust_level}")
+
+        # Check paradigm support
+        paradigm = skill_requirements.get("paradigm")
+        if paradigm and paradigm not in self.supported_paradigms:
+            return (False, f"missing: paradigm '{paradigm}'")
+
+        return (True, "ok")
+
+
+# ---------------------------------------------------------------------------
+# Preset profiles
+# ---------------------------------------------------------------------------
+
+CLAUDE_CODE_PROFILE = AgentCapabilityProfile(
+    name="claude-code",
+    required_capabilities={"bash", "file_system", "python", "web_search"},
+    context_window=200000,
+    trust_level=3,
+    supported_paradigms={"review", "code", "planning", "4d", "docsdd", "sdd", "bdd", "tdd"},
+)
+
+CODEX_PROFILE = AgentCapabilityProfile(
+    name="codex",
+    required_capabilities={"bash", "file_system", "python"},
+    context_window=128000,
+    trust_level=2,
+    supported_paradigms={"code", "test", "4d", "sdd", "bdd", "tdd"},
+)
+
+HERMES_PROFILE = AgentCapabilityProfile(
+    name="hermes",
+    required_capabilities={"file_system", "web_search"},
+    context_window=32000,
+    trust_level=1,
+    supported_paradigms={"research", "planning", "4d", "docsdd"},
+)
+
+OPENCLAW_PROFILE = AgentCapabilityProfile(
+    name="openclaw",
+    required_capabilities={"bash", "file_system", "python", "web_search"},
+    context_window=128000,
+    trust_level=2,
+    supported_paradigms={"review", "code", "test", "planning", "4d", "docsdd", "sdd", "bdd", "tdd"},
+)

skillpool/quality.py

@@ -0,0 +1,254 @@
+"""SkillPool Quality Profiler — 4-dimension scoring with auto-calculation and calibration."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from skillpool.csdf import CSDFDocument
+
+# Default weights for overall score computation
+DEFAULT_WEIGHTS: dict[str, float] = {
+    "completeness": 0.30,
+    "accuracy": 0.30,
+    "usability": 0.20,
+    "maintainability": 0.20,
+}
+
+# Calibration offsets applied to raw dimension scores
+CALIBRATION_OFFSETS: dict[str, float] = {
+    "completeness": 0.0,
+    "accuracy": -0.05,
+    "usability": 0.0,
+    "maintainability": 0.0,
+}
+
+
+def _compute_overall(
+    completeness: float,
+    accuracy: float,
+    usability: float,
+    maintainability: float,
+    weights: dict[str, float],
+) -> float:
+    """Compute weighted overall score from dimension scores."""
+    return round(
+        completeness * weights.get("completeness", 0.0)
+        + accuracy * weights.get("accuracy", 0.0)
+        + usability * weights.get("usability", 0.0)
+        + maintainability * weights.get("maintainability", 0.0),
+        4,
+    )
+
+
+@dataclass
+class QualityProfile:
+    """Quality profile for a skill, containing 4 dimension scores and an overall score."""
+
+    name: str = ""
+    completeness: float = 0.0
+    accuracy: float = 0.0
+    usability: float = 0.0
+    maintainability: float = 0.0
+    overall: float = 0.0
+    weights: dict[str, float] = field(default_factory=lambda: dict(DEFAULT_WEIGHTS))
+
+    def __post_init__(self) -> None:
+        """Auto-calculate overall score if not explicitly provided."""
+        # If overall is 0.0 and any dimension is non-zero, recalculate
+        if self.overall == 0.0 and any([self.completeness, self.accuracy, self.usability, self.maintainability]):
+            self.overall = _compute_overall(
+                self.completeness,
+                self.accuracy,
+                self.usability,
+                self.maintainability,
+                self.weights,
+            )
+
+    @classmethod
+    def from_document(
+        cls,
+        doc: CSDFDocument,
+        weights: dict[str, float] | None = None,
+    ) -> QualityProfile:
+        """Create a QualityProfile from a CSDFDocument, using its dimensions dict."""
+        w = weights or dict(DEFAULT_WEIGHTS)
+        dims = doc.dimensions
+        completeness = dims.get("completeness", 0.0)
+        accuracy = dims.get("accuracy", 0.0)
+        usability = dims.get("usability", 0.0)
+        maintainability = dims.get("maintainability", 0.0)
+        overall = _compute_overall(completeness, accuracy, usability, maintainability, w)
+        return cls(
+            name=doc.name,
+            completeness=completeness,
+            accuracy=accuracy,
+            usability=usability,
+            maintainability=maintainability,
+            overall=overall,
+            weights=w,
+        )
+
+    @classmethod
+    def from_scores(
+        cls,
+        name: str,
+        completeness: float = 0.0,
+        accuracy: float = 0.0,
+        usability: float = 0.0,
+        maintainability: float = 0.0,
+        weights: dict[str, float] | None = None,
+    ) -> QualityProfile:
+        """Create a QualityProfile from explicit dimension scores."""
+        w = weights or dict(DEFAULT_WEIGHTS)
+        overall = _compute_overall(completeness, accuracy, usability, maintainability, w)
+        return cls(
+            name=name,
+            completeness=completeness,
+            accuracy=accuracy,
+            usability=usability,
+            maintainability=maintainability,
+            overall=overall,
+            weights=w,
+        )
+
+    def compare(self, other: QualityProfile) -> dict[str, float]:
+        """Compare this profile with another, returning dimension deltas."""
+        return {
+            "completeness": round(self.completeness - other.completeness, 4),
+            "accuracy": round(self.accuracy - other.accuracy, 4),
+            "usability": round(self.usability - other.usability, 4),
+            "maintainability": round(self.maintainability - other.maintainability, 4),
+            "overall": round(self.overall - other.overall, 4),
+        }
+
+
+class QualityProfiler:
+    """Profiles a CSDFDocument to produce a QualityProfile with auto-calculated scores."""
+
+    def __init__(
+        self,
+        weights: dict[str, float] | None = None,
+        calibration_offsets: dict[str, float] | None = None,
+    ) -> None:
+        self.weights = weights or dict(DEFAULT_WEIGHTS)
+        self.calibration_offsets = calibration_offsets or dict(CALIBRATION_OFFSETS)
+
+    def profile(self, doc: CSDFDocument) -> QualityProfile:
+        """Profile a CSDFDocument and return a QualityProfile with computed scores."""
+        # Use document dimensions if present, otherwise auto-calculate
+        dims = doc.dimensions
+        if dims:
+            completeness = dims.get("completeness", _score_completeness(doc))
+            accuracy = dims.get("accuracy", _score_accuracy(doc))
+            usability = dims.get("usability", _score_usability(doc))
+            maintainability = dims.get("maintainability", _score_maintainability(doc))
+        else:
+            completeness = _score_completeness(doc)
+            accuracy = _score_accuracy(doc)
+            usability = _score_usability(doc)
+            maintainability = _score_maintainability(doc)
+
+        # Apply calibration offsets
+        completeness = max(0.0, min(1.0, completeness + self.calibration_offsets.get("completeness", 0.0)))
+        accuracy = max(0.0, min(1.0, accuracy + self.calibration_offsets.get("accuracy", 0.0)))
+        usability = max(0.0, min(1.0, usability + self.calibration_offsets.get("usability", 0.0)))
+        maintainability = max(0.0, min(1.0, maintainability + self.calibration_offsets.get("maintainability", 0.0)))
+
+        overall = _compute_overall(
+            completeness,
+            accuracy,
+            usability,
+            maintainability,
+            self.weights,
+        )
+
+        return QualityProfile(
+            name=doc.name,
+            completeness=round(completeness, 4),
+            accuracy=round(accuracy, 4),
+            usability=round(usability, 4),
+            maintainability=round(maintainability, 4),
+            overall=overall,
+            weights=self.weights,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Auto-scoring helpers — compute dimension scores from document content
+# ---------------------------------------------------------------------------
+
+
+def _score_completeness(doc: CSDFDocument) -> float:
+    """Score completeness based on presence of key fields and content."""
+    score = 0.0
+    if doc.name:
+        score += 0.25
+    if doc.description:
+        score += 0.25
+    if doc.triggers:
+        score += 0.25
+    if doc.body:
+        score += 0.25
+    return round(min(score, 1.0), 4)
+
+
+def _score_accuracy(doc: CSDFDocument) -> float:
+    """Score accuracy based on references and content indicators."""
+    score = 0.0
+    if doc.references:
+        score += min(len(doc.references) * 0.25, 0.5)
+    if doc.body:
+        code_indicators = len(re.findall(r"```", doc.body))
+        if code_indicators >= 2:
+            score += 0.3
+        elif code_indicators >= 1:
+            score += 0.15
+        tech_terms = len(re.findall(r"\b(API|function|class|method|parameter|return)\b", doc.body, re.IGNORECASE))
+        if tech_terms >= 3:
+            score += 0.2
+        elif tech_terms >= 1:
+            score += 0.1
+    return round(min(score, 1.0), 4)
+
+
+def _score_usability(doc: CSDFDocument) -> float:
+    """Score usability based on structure and readability indicators."""
+    score = 0.0
+    if doc.body:
+        headers = len(re.findall(r"^#{1,6}\s+", doc.body, re.MULTILINE))
+        if headers >= 3:
+            score += 0.3
+        elif headers >= 1:
+            score += 0.15
+        lists = len(re.findall(r"^[\s]*[-*+]\s+", doc.body, re.MULTILINE))
+        if lists >= 3:
+            score += 0.2
+        elif lists >= 1:
+            score += 0.1
+        word_count = len(doc.body.split())
+        if 50 <= word_count <= 2000:
+            score += 0.3
+        elif word_count > 0:
+            score += 0.15
+    if doc.triggers:
+        score += 0.1
+    return round(min(score, 1.0), 4)
+
+
+def _score_maintainability(doc: CSDFDocument) -> float:
+    """Score maintainability based on version info and content organization."""
+    score = 0.0
+    if doc.version and re.match(r"^\d+\.\d+\.\d+", doc.version):
+        score += 0.3
+    if doc.description:
+        score += 0.2
+    if doc.body:
+        paragraphs = [p for p in doc.body.split("\n\n") if p.strip()]
+        if paragraphs:
+            avg_len = sum(len(p) for p in paragraphs) / len(paragraphs)
+            if avg_len < 200:
+                score += 0.20
+            elif avg_len < 400:
+                score += 0.10
+    return round(min(score, 1.0), 4)