foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/governance/middleware.py

@@ -0,0 +1,176 @@
+"""
+框架无关治理中间件的实现。
+
+只依赖治理内核(Harness + ThoughtChain + ToolLoopDetector),不碰 Foxclaw 其余部分。
+对外只暴露两个概念:
+  · GovernanceSession —— 一次带目标基线的治理会话:observe(每步) + audit(取审计链)+ 循环检测;
+  · governed          —— 把某个工具函数包成"调用前先过 Harness"的装饰器(同步/异步都支持)。
+"""
+from __future__ import annotations
+
+import asyncio
+import functools
+import tempfile
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional, cast
+
+from ..harness.harness import Harness
+from ..harness.loop_detection import ToolLoopDetector
+from ..core.thought_chain import NodeType, ThoughtChain, ThoughtNode
+
+
+@dataclass
+class GovResult:
+    """一步治理判定的结果(框架无关,不泄露 Foxclaw 内部类型)。"""
+    status: str
+    blocked: bool
+    warned: bool
+    delta: float
+    dimension: str
+    reason: Optional[str]
+    node_id: str
+    scores: dict = field(default_factory=dict)
+    loop: Optional[dict] = None
+
+    @property
+    def tool_violation(self) -> bool:
+        """工具越权(与语言/语义无关的确定性信号)。"""
+        return self.scores.get("tool", 0) >= 1.0
+
+    @property
+    def scope_violation(self) -> bool:
+        """范围蔓延越上限(确定性信号)。"""
+        return self.scores.get("scope", 0) >= 1.0
+
+    def to_dict(self) -> dict:
+        return {"status": self.status, "blocked": self.blocked, "warned": self.warned,
+                "delta": round(self.delta, 4), "dimension": self.dimension,
+                "reason": self.reason, "node_id": self.node_id,
+                "scores": {k: round(v, 4) for k, v in self.scores.items()},
+                "loop": self.loop}
+
+
+class GovernanceBlocked(Exception):
+    """被治理层拦截时抛出(供 governed 装饰器/框架回调使用)。"""
+    def __init__(self, result: GovResult):
+        self.result = result
+        super().__init__(f"governance blocked: {result.reason}")
+
+
+class GovernanceSession:
+    """一次治理会话:注册目标基线,之后每步 observe 都过三维漂移 + 循环检测,并落审计链。
+
+    参数:
+      goal          —— 任务目标(语义漂移的基线);
+      allowed_tools —— 允许的工具类别集合(如 {"read","finance"});越类别即工具越权;
+      entities      —— 基线实体集(范围蔓延的参照);
+      agent_id      —— 审计归属标识;
+      shadow_rounds —— 观测期轮数(前 N 步只观测不拦截,用真实分布校准阈值);默认 0=即时判定;
+      db_path       —— 审计链落盘路径;默认临时文件(会话级)。
+
+    线程/进程无关:不启动任何后台线程,不联网;语义向量用本地缓存模型,缺失自动降级哈希嵌入。
+    """
+
+    def __init__(self, goal: str, allowed_tools=None, entities=None,
+                 agent_id: str = "agent", shadow_rounds: int = 0,
+                 db_path: str | None = None, policy_path: str | None = None,
+                 embedding_model: str | None = None):
+        self.agent_id = agent_id
+        self._session_id = f"gov_{uuid.uuid4().hex[:10]}"
+        self.thought_chain = ThoughtChain(
+            db_path=db_path or tempfile.mktemp(suffix=".gov.db"))
+        self.harness = Harness(
+            agent_id=agent_id, thought_chain=self.thought_chain,
+            policy_path=policy_path or tempfile.mktemp(suffix=".gov.yaml"),
+            shadow_rounds=shadow_rounds, embedding_model=embedding_model)
+        self.harness.register_goal(
+            goal_text=goal,
+            allowed_tool_categories=set(allowed_tools or {"read"}),
+            baseline_entities=set(entities or []))
+        if shadow_rounds <= 0:
+            self.harness._shadow_mode = False
+        self._loop = ToolLoopDetector()
+        self._blocked_count = 0
+
+    def observe(self, content: str, tool: str | None = None, entities=None,
+                node_type: str | None = None, conf: float = 0.9,
+                semantic: bool = True) -> GovResult:
+        """观测一个推理/工具步骤,返回治理判定。不抛异常(判定在结果里)。
+
+        semantic=False:只按工具/范围维度判定(语义置 0)。用于纯"工具授权"检查——
+        工具调用串对目标的语义距离是噪声。"""
+        node = ThoughtNode.create(
+            session_id=self._session_id, agent_id=self.agent_id,
+            type=cast(NodeType, node_type or ("tool_intent" if tool else "reasoning")),
+            content=content, conf=conf, tool_name=tool, entities=entities or [])
+        self.thought_chain.add_node(node)
+        r = self.harness.check(node, ignore_semantic=not semantic)
+        loop_warn = None
+        if tool:
+            lv = self._loop.record(tool, {"content": content})
+            if lv.stuck:
+                loop_warn = lv.to_dict()
+        if r.is_blocked:
+            self._blocked_count += 1
+        return GovResult(status=r.status, blocked=r.is_blocked, warned=r.is_warned,
+                         delta=r.delta, dimension=r.dominant_dim, reason=r.reason,
+                         node_id=node.id, scores=dict(r.scores), loop=loop_warn)
+
+    def guard(self, content: str, tool: str | None = None, entities=None) -> GovResult:
+        """与 observe 相同,但被 BLOCK 时**抛 GovernanceBlocked**(fail-closed 风格)。"""
+        r = self.observe(content, tool=tool, entities=entities)
+        if r.blocked:
+            raise GovernanceBlocked(r)
+        return r
+
+    def audit(self) -> list[dict]:
+        """取回本会话的完整可审计推理链(带每步 Harness 判定)。"""
+        return [n.to_dict() for n in
+                self.thought_chain.get_chain(self._session_id, self.agent_id)]
+
+    def summary(self) -> dict:
+        """治理摘要:总步数/拦截数/漂移趋势(供框架侧上报)。"""
+        s = self.thought_chain.get_summary(self.agent_id)
+        s["blocked_this_session"] = self._blocked_count
+        s["shadow_mode"] = self.harness.is_shadow_mode
+        return s
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+def governed(session: GovernanceSession, tool_name: str | None = None, entities=None):
+    """装饰器:把一个工具函数包成"调用前先过 Harness"。
+
+    命中越权/跑题/范围蔓延 → 抛 GovernanceBlocked,函数不执行。同步/异步函数都支持。
+
+        gov = GovernanceSession(goal=..., allowed_tools={"read"})
+        @governed(gov)
+        def delete_row(...): ...     # 调用即被拦(delete 不在 read 允许集)
+    """
+    def _check(name):
+        r = session.observe(f"tool call: {name}", tool=name, entities=entities,
+                            semantic=False)
+        if r.blocked or r.tool_violation or r.scope_violation:
+            raise GovernanceBlocked(r)
+
+    def deco(fn):
+        name = tool_name or getattr(fn, "__name__", "tool")
+
+        if asyncio.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def awrapper(*a, **kw):
+                _check(name)
+                return await fn(*a, **kw)
+            return awrapper
+
+        @functools.wraps(fn)
+        def wrapper(*a, **kw):
+            _check(name)
+            return fn(*a, **kw)
+        return wrapper
+    return deco

package/python/foxclaw/harness/__init__.py

@@ -0,0 +1,17 @@
+"""Foxclaw — Harness: 跨层约束-校准机制"""
+from .harness import (
+    Harness,
+    HarnessResult,
+    GoalBaseline,
+    SemanticDrift,
+    ToolIntentDrift,
+    ScopeCreepDrift,
+    HarnessEventBus,
+    TOOL_CATEGORIES,
+)
+
+__all__ = [
+    "Harness", "HarnessResult", "GoalBaseline",
+    "SemanticDrift", "ToolIntentDrift", "ScopeCreepDrift",
+    "HarnessEventBus", "TOOL_CATEGORIES",
+]

package/python/foxclaw/harness/_base.py

@@ -0,0 +1,66 @@
+"""Harness 基础设施：contextvar 分槽 + 工具类别白名单 + 结果/基线数据类。"""
+import contextvars
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+from ..core.thought_chain import HarnessStatus
+
+
+_harness_ctx: contextvars.ContextVar = contextvars.ContextVar(
+    "foxclaw_harness_ctx", default=None)
+
+
+def _harness_ctx_get(token: str):
+    return (_harness_ctx.get() or {}).get(token)
+
+
+def _harness_ctx_set(token: str, baseline):
+    d = dict(_harness_ctx.get() or {})
+    d[token] = baseline
+    _harness_ctx.set(d)
+
+
+TOOL_CATEGORIES: dict[str, set[str]] = {
+    "read":    {"read_file", "search", "fetch", "list", "get", "query"},
+    "write":   {"write_file", "create", "update", "save", "append"},
+    "delete":  {"delete", "remove", "drop", "clear", "reset"},
+    "exec":    {"run_code", "shell", "subprocess", "execute"},
+    "network": {"http_get", "http_post", "scrape", "download"},
+    "calendar": {"add_event", "get_schedule", "update_event"},
+    "finance": {"get_balance", "add_transaction", "generate_report"},
+}
+
+
+@dataclass
+class HarnessResult:
+    status: HarnessStatus
+    delta: float
+    dominant_dim: str
+    scores: dict
+    reason: Optional[str] = None
+
+    @property
+    def is_blocked(self) -> bool:
+        return self.status == "BLOCK"
+
+    @property
+    def is_warned(self) -> bool:
+        return self.status == "WARN"
+
+
+@dataclass
+class GoalBaseline:
+    """目标基线 — 在接口层注册，后续所有层的校验参照此基线"""
+    goal_text: str
+    allowed_tool_categories: set[str]
+    baseline_entities: set[str]
+    goal_embedding: Optional[np.ndarray] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "goal_text": self.goal_text,
+            "allowed_tool_categories": list(self.allowed_tool_categories),
+            "baseline_entities": list(self.baseline_entities),
+        }

package/python/foxclaw/harness/_policy.py

@@ -0,0 +1,340 @@
+"""Harness Policy 学习 + 影子观察 + 阈值校准 + 持久化（mixin）。
+
+拆分自 harness.py：`Harness` 主类继承本 mixin，通过 `self.weights/_policy/_lock`
+等实例状态协同工作。纯搬移、零行为变更。
+"""
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
+
+import numpy as np
+import yaml
+
+from ..core.thought_chain import ThoughtNode
+from ._base import HarnessResult
+
+if TYPE_CHECKING:
+    from .event_bus import HarnessEventBus
+
+
+class PolicyMixin:
+    agent_id: str
+    bus: "HarnessEventBus"
+    policy_path: Path
+    weights: dict[str, float]
+    promote_min_obs: int
+    _policy: dict
+    _baseline: Any
+    _delta_history: list[float]
+
+
+    def _reindex_learned_actions(self):
+        """把 self._policy['rules'] 里已学习的 action 编译成 check() 用得上的结构。
+
+        使自学习从「权重级」升级到「规则级」:BLOCK 时 _generate_policy_action 生成的
+        penalize_tool / restrict_scope 不再只是躺在 YAML 里的意图,而是被这里编译、
+        并在 check() 里真正改变判定。加载 policy 时 + 每次新学到规则后都会重建。
+        """
+        penalized: set[str] = set()
+        scope_limit: int | None = None
+        for rule in self._policy.get("rules", []):
+            action = rule.get("action") or {}
+            atype = action.get("type")
+            if atype == "penalize_tool":
+                pat = action.get("tool_pattern")
+                if pat:
+                    penalized.add(pat)
+            elif atype == "restrict_scope":
+                lim = action.get("entity_expansion_limit")
+                if isinstance(lim, int):
+                    scope_limit = lim if scope_limit is None else min(scope_limit, lim)
+        self._penalized_tools = penalized
+        self._scope_limit = scope_limit
+
+    def _is_penalized_tool(self, tool_name: str) -> bool:
+        """工具名是否命中已学习的 penalize_tool 规则(与 ToolIntentDrift 一致的子串匹配)。"""
+        if not tool_name or not self._penalized_tools:
+            return False
+        return any(tool_name == p or p in tool_name for p in self._penalized_tools)
+
+
+    _LEARNABLE_RULE_DIMS = frozenset({"tool", "scope"})
+
+    def _trigger_policy_learning(self, node: ThoughtNode, result: HarnessResult):
+        """BLOCK 事件 → 规则候选进 **shadow_rules(不生效)** → 影子观察 → promote/discard。
+
+        【P0-1】原为「BLOCK → 规则直接写 rules + reindex → 下次 check 立即生效」——
+        在线无验证学习是真实风险(一次偶发 BLOCK 就永久改变判定)。改后:
+          · 规则级:候选进 shadow_rules,观察 N 次达标才 promote(生效)/discard;
+          · 权重级:保持现状(触发维度 +0.05 归一化)——文稿只影子化规则级,权重微调风险低;
+          · 边界:semantic 仅权重级不生成规则;未知维度连权重都不学,只记录。
+        """
+        dim = result.dominant_dim
+
+        if dim not in self.weights:
+            self._record_history("skip", "",
+                                 note=f"未知维度 '{dim}' 禁止自学习(fail-closed)")
+            self._save_policy()
+            return
+
+        if dim in self._LEARNABLE_RULE_DIMS:
+            new_rule: dict[str, Any] = {
+                "id": f"rule_{node.id}",
+                "trigger": {
+                    "harness_status": "BLOCK",
+                    "dominant_dim": dim,
+                    "delta_threshold": round(result.delta, 3),
+                },
+                "action": self._generate_policy_action(node, result),
+                "created_at": datetime.now(timezone.utc).isoformat(),
+                "source": "harness_learned",
+                "agent_id": self.agent_id,
+                "shadow": {
+                    "created_at": datetime.now(timezone.utc).isoformat(),
+                    "observations": 0, "would_block": 0, "would_pass": 0,
+                    "status": "observing",
+                },
+            }
+            self._policy.setdefault("shadow_rules", []).append(new_rule)
+            self._record_history("propose", new_rule["id"],
+                                 note=f"{dim} 维度 BLOCK → 影子观察")
+            self.bus.emit("shadow_rule_proposed", {
+                "agent_id": self.agent_id, "rule_id": new_rule["id"],
+                "dominant_dim": dim,
+                "action_type": new_rule["action"].get("type", ""),
+            })
+
+        bumped = dict(self.weights)
+        bumped[dim] = min(bumped[dim] + 0.05, 0.8)
+        total = sum(bumped.values())
+        self.weights = {k: v / total for k, v in bumped.items()}
+
+        self._save_policy()
+        self.bus.emit("policy_updated", {
+            "agent_id": self.agent_id,
+            "rule_id": "",
+            "dominant_dim": dim,
+            "new_weights": dict(self.weights),
+        })
+
+
+    def _observe_shadow_rules(self, node: ThoughtNode, result: HarnessResult,
+                              real_scores: dict):
+        """对观察中的影子规则做双轨计数,达标后 promote/discard。锁内调用。
+
+        适用性:当前场景的 dominant_dim 与规则 trigger.dominant_dim 相同。
+        (trigger.delta_threshold 仅记录生成时的漂移强度,不作匹配条件——否则
+        observations 几乎无法积累,影子机制会失去意义。)
+
+        落盘节流:promote/discard 立即 save;普通计数每 10 次 save 一次(进程崩溃
+        最多丢 9 次观察计数,可接受)——否则「有影子规则时每次 check 都写 YAML」,
+        一次任务几十次 check 就是几十次磁盘写。
+        """
+        need_save = False
+        for rule in list(self._policy.get("shadow_rules", [])):
+            sh = rule.get("shadow") or {}
+            if sh.get("status") != "observing":
+                continue
+            trig = rule.get("trigger") or {}
+            if trig.get("dominant_dim") != result.dominant_dim:
+                continue
+
+            sh["observations"] = sh.get("observations", 0) + 1
+
+            shadow_status = self._status_with_action(rule, node, real_scores)
+            real_blocked = result.is_blocked
+            shadow_blocked = shadow_status == "BLOCK"
+            if shadow_blocked and not real_blocked:
+                sh["would_block"] = sh.get("would_block", 0) + 1
+            elif not shadow_blocked and real_blocked:
+                sh["would_pass"] = sh.get("would_pass", 0) + 1
+
+            verdict = self._should_promote(sh)
+            if verdict is True:
+                self._promote_rule(rule)
+                need_save = True
+            elif verdict is False:
+                self._discard_rule(rule, "影子证据不达标")
+                need_save = True
+            elif sh["observations"] % 10 == 0:
+                need_save = True
+        if need_save:
+            self._save_policy()
+
+    def _status_with_action(self, rule: dict, node: ThoughtNode,
+                            real_scores: dict) -> str:
+        """模拟应用单条影子规则的 action,给出「若它生效」的判定(复用同一权重/阈值)。"""
+        scores = dict(real_scores)
+        action = rule.get("action") or {}
+        atype = action.get("type")
+        if atype == "penalize_tool":
+            pat = action.get("tool_pattern", "")
+            tool_name = getattr(node, "tool_name", "") or ""
+            if pat and tool_name and (tool_name == pat or pat in tool_name):
+                scores["tool"] = 1.0
+        elif atype == "restrict_scope":
+            lim = action.get("entity_expansion_limit")
+            baseline = self._baseline
+            if isinstance(lim, int) and baseline is not None and baseline.baseline_entities:
+                new_entities = set(node.entities) - baseline.baseline_entities
+                if len(new_entities) > lim:
+                    scores["scope"] = 1.0
+        delta = sum(self.weights[k] * v for k, v in scores.items())
+        if delta > self._block_threshold:
+            return "BLOCK"
+        if delta > self._warn_threshold:
+            return "WARN"
+        return "PASS"
+
+    def _should_promote(self, sh: dict):
+        """影子证据判定(文稿第四步):True=promote / False=discard / None=继续观察。"""
+        obs = sh.get("observations", 0)
+        if obs < self.promote_min_obs:
+            return None
+        wb, wp = sh.get("would_block", 0), sh.get("would_pass", 0)
+        if wb / max(obs, 1) > 0.3:
+            return False
+        if wb == 0 and wp == 0:
+            return False
+        return True
+
+    def _promote_rule(self, rule: dict):
+        """影子 → 生效:移入 rules、重建索引、记 history、发事件。"""
+        rule.get("shadow", {})["status"] = "promoted"
+        self._policy.setdefault("shadow_rules", []).remove(rule)
+        rule.pop("shadow", None)
+        self._policy.setdefault("rules", []).append(rule)
+        self._reindex_learned_actions()
+        self._record_history("promote", rule["id"],
+                             note=f"观察达标升迁(维度 {rule.get('trigger', {}).get('dominant_dim', '?')})")
+        self.bus.emit("shadow_rule_promoted", {
+            "agent_id": self.agent_id, "rule_id": rule["id"],
+            "dominant_dim": rule.get("trigger", {}).get("dominant_dim", ""),
+        })
+
+    def _discard_rule(self, rule: dict, why: str):
+        """影子证据不达标:标记 discarded(保留供审计回放,不再参与双轨评估)。"""
+        sh = rule.get("shadow") or {}
+        sh["status"] = "discarded"
+        self._record_history("discard", rule.get("id", ""), note=why)
+        self.bus.emit("shadow_rule_discarded", {
+            "agent_id": self.agent_id, "rule_id": rule.get("id", ""),
+            "reason": why,
+            "observations": sh.get("observations", 0),
+            "would_block": sh.get("would_block", 0),
+            "would_pass": sh.get("would_pass", 0),
+        })
+
+    def rollback(self, rule_id: str) -> bool:
+        """【P0-1 回滚】把一条已生效规则撤出生效集(误 promote 的后悔药)。
+
+        规则从 rules 移回 shadow_rules 并标记 rolled_back(不再生效、保留可审计),
+        重建索引 + 记 history + 发事件。找不到返回 False。"""
+        for rule in list(self._policy.get("rules", [])):
+            if rule.get("id") != rule_id:
+                continue
+            self._policy["rules"].remove(rule)
+            rule["shadow"] = {
+                "created_at": rule.get("created_at", ""),
+                "observations": 0, "would_block": 0, "would_pass": 0,
+                "status": "rolled_back",
+            }
+            self._policy.setdefault("shadow_rules", []).append(rule)
+            self._reindex_learned_actions()
+            self._record_history("rollback", rule_id, note="人工/自动回滚")
+            self._save_policy()
+            self.bus.emit("shadow_rule_rolled_back", {
+                "agent_id": self.agent_id, "rule_id": rule_id,
+            })
+            return True
+        return False
+
+    def _record_history(self, event: str, rule_id: str, note: str = ""):
+        """policy YAML 的 history 段(文稿第六步):propose/promote/discard/rollback/skip 全轨迹。
+        有界保留最近 500 条(与库内有界日志惯例一致)。"""
+        hist = self._policy.setdefault("history", [])
+        hist.append({
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "event": event, "rule_id": rule_id,
+            "version": self._policy.get("version", 1),
+            "note": note[:200],
+        })
+        if len(hist) > 500:
+            del hist[:-500]
+
+    def _generate_policy_action(self, node: ThoughtNode, result: HarnessResult) -> dict:
+        """生成结构化策略动作,随 learned rule 持久化到 policy 文件。
+
+        自学习现在**两级都生效**:
+          · 权重级 —— _trigger_policy_learning 里对触发维度 +0.05 并归一化,影响后续 delta;
+          · 规则级 —— 本函数生成的 action 由 _reindex_learned_actions 编译,并在 check() 里应用:
+              - penalize_tool     → 命中工具的 tool 分被抬到 1.0(即便类别本在允许集里);
+              - restrict_scope    → 新增实体数超过 entity_expansion_limit 时 scope 分抬到 1.0。
+            (increase_semantic_threshold 仍主要靠权重级体现,未单列规则应用。)
+        因此这些 action 不再只是"意图记录"——penalize_tool / restrict_scope 会真正改变判定。
+        """
+        dim = result.dominant_dim
+        if dim == "tool" and node.tool_name:
+            return {
+                "type": "penalize_tool",
+                "tool_pattern": node.tool_name,
+                "weight_delta": -0.3,
+            }
+        elif dim == "scope":
+            return {
+                "type": "restrict_scope",
+                "entity_expansion_limit": 2,
+            }
+        else:
+            return {
+                "type": "increase_semantic_threshold",
+                "delta": -0.05,
+            }
+
+
+    def _calibrate_thresholds(self):
+        """Shadow mode 结束 — 用真实 Δ 分布校准阈值。
+        关键:阈值要设在"正常任务分布"之上,这样正常任务通过,
+        只有真正离群的(如完全跑题)才被拦截。
+        否则用中位数附近的分位数会拦掉一半正常流量。
+        """
+        arr = np.array(sorted(self._delta_history), dtype=np.float64)
+        if arr.size == 0:
+            self._shadow_mode = False
+            return
+        mean = float(arr.mean())
+        std = float(arr.std())
+        p90 = float(np.percentile(arr, 90))
+        block = max(p90, mean + 1.5 * std) * 1.10
+        warn = block * 0.8
+        self._block_threshold = max(block, 0.25)
+        self._warn_threshold = max(warn, 0.18)
+        self._shadow_mode = False
+        self.bus.emit("shadow_calibrated", {
+            "agent_id": self.agent_id,
+            "warn_threshold": self._warn_threshold,
+            "block_threshold": self._block_threshold,
+            "sample_size": len(arr),
+            "mean": round(mean, 3),
+            "std": round(std, 3),
+        })
+
+
+    def _load_policy(self) -> dict:
+        if self.policy_path.exists():
+            with open(self.policy_path, encoding="utf-8") as f:
+                return yaml.safe_load(f) or {}
+        return {
+            "version": 1,
+            "agent_id": self.agent_id,
+            "rules": [],
+            "created_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+    def _save_policy(self):
+        os.makedirs(self.policy_path.parent, exist_ok=True)
+        self._policy["version"] = self._policy.get("version", 1) + 1
+        self._policy["updated_at"] = datetime.now(timezone.utc).isoformat()
+        with open(self.policy_path, "w", encoding="utf-8") as f:
+            yaml.dump(self._policy, f, allow_unicode=True, sort_keys=False)

package/python/foxclaw/harness/drift.py

@@ -0,0 +1,77 @@
+"""Harness 三个检测维度：语义距离 / 工具意图 / 范围蔓延。"""
+import hashlib
+
+import numpy as np
+from sklearn.metrics.pairwise import cosine_similarity
+
+from ._base import TOOL_CATEGORIES
+
+
+class SemanticDrift:
+    """维度一：语义距离。优先 sentence-transformers,不可用则降级 n-gram 哈希嵌入。"""
+
+    DIM = 256
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
+        from ..capability.embedding_service import get_text_embedder
+        self._model = get_text_embedder(model_name)
+        self._mode = "transformer" if self._model is not None else "hash"
+
+    @property
+    def mode(self) -> str:
+        return self._mode
+
+    def _encode(self, text: str) -> np.ndarray:
+        if self._mode == "transformer":
+            return self._model.encode(text)
+        return self._hash_embed(text)
+
+    def _hash_embed(self, text: str) -> np.ndarray:
+        """字符 3-gram 哈希到固定维向量。余弦相似度数学真实,只是不带语义模型。"""
+        vec = np.zeros(self.DIM, dtype=np.float32)
+        text = (text or "").lower().strip()
+        if not text:
+            return vec
+        grams = [text[i:i+3] for i in range(max(len(text) - 2, 1))]
+        for g in grams:
+            h = int(hashlib.md5(g.encode("utf-8")).hexdigest(), 16)
+            idx = h % self.DIM
+            sign = 1.0 if (h // self.DIM) % 2 == 0 else -1.0
+            vec[idx] += sign
+        norm = np.linalg.norm(vec)
+        return vec / norm if norm > 0 else vec
+
+    def encode(self, text: str) -> np.ndarray:
+        """把文本编码成向量(纯函数,无副作用)。每任务基线自持此向量,并发安全。"""
+        return self._encode(text)
+
+    def score(self, content: str, baseline_vec: np.ndarray) -> float:
+        """内容相对**每任务基线向量**的语义漂移。baseline_vec 由调用方(check)显式传入,
+        不再用共享的实例级基线 → 并发顶层任务的语义基线互不覆盖。"""
+        if baseline_vec is None:
+            return 0.0
+        node_vec = self._encode(content)
+        sim = cosine_similarity([baseline_vec], [node_vec])[0][0]
+        return float(min(1.0, max(0.0, 1.0 - sim)))
+
+
+class ToolIntentDrift:
+    """维度二：工具意图"""
+
+    def score(self, tool_name: str, allowed_categories: set[str]) -> float:
+        if not tool_name:
+            return 0.0
+        for cat, patterns in TOOL_CATEGORIES.items():
+            if any(tool_name.startswith(p) or p in tool_name for p in patterns):
+                return 0.0 if cat in allowed_categories else 1.0
+        return 0.3
+
+
+class ScopeCreepDrift:
+    """维度三：范围蔓延"""
+
+    def score(self, node_entities: set[str], baseline_entities: set[str]) -> float:
+        if not baseline_entities:
+            return 0.0
+        new_entities = node_entities - baseline_entities
+        return min(len(new_entities) / max(len(baseline_entities), 1), 1.0)