foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/governance/middleware.py

@@ -0,0 +1,184 @@
+"""
+框架无关治理中间件的实现。
+
+只依赖治理内核(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
+
+from ..harness.harness import Harness
+from ..harness.loop_detection import ToolLoopDetector
+from ..core.thought_chain import ThoughtChain, ThoughtNode
+
+
+@dataclass
+class GovResult:
+    """一步治理判定的结果(框架无关,不泄露 Foxclaw 内部类型)。"""
+    status: str                      # PASS / WARN / BLOCK
+    blocked: bool
+    warned: bool
+    delta: float
+    dimension: str                   # 主导漂移维度 semantic/tool/scope
+    reason: Optional[str]
+    node_id: str
+    scores: dict = field(default_factory=dict)   # 各维度分 semantic/tool/scope
+    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, policy_path: str = None,
+                 embedding_model: str = 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 []))
+        # shadow_rounds<=0:中间件默认**即时按默认阈值判定**(warn 0.15 / block 0.25),
+        # 不做"拿第一个样本自校准"(那会让首步逃逸并用单样本污染阈值)。想用真实分布
+        # 校准的调用方,显式传 shadow_rounds>0 走观测期。
+        if shadow_rounds <= 0:
+            self.harness._shadow_mode = False
+        self._loop = ToolLoopDetector()
+        self._blocked_count = 0
+
+    # ── 核心:观测一步 ────────────────────────────────────────
+    def observe(self, content: str, tool: str = None, entities=None,
+                node_type: str = 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=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, 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, entities=None):
+    """装饰器:把一个工具函数包成"调用前先过 Harness"。
+
+    命中越权/跑题/范围蔓延 → 抛 GovernanceBlocked,函数不执行。同步/异步函数都支持。
+
+        gov = GovernanceSession(goal=..., allowed_tools={"read"})
+        @governed(gov)
+        def delete_row(...): ...     # 调用即被拦(delete 不在 read 允许集)
+    """
+    def _check(name):
+        # 工具装饰器只对"这个工具授权了吗"负责 → semantic=False 只按 tool/scope 判定
+        # (语义是 observe() 的职责;工具名对目标的语义距离是噪声,跨语言时更会饱和,
+        # 不能作为工具授权依据)。这样中间件语言无关、行为确定、审计不被语义噪声污染。
+        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,72 @@
+"""Harness 基础设施：contextvar 分槽 + 工具类别白名单 + 结果/基线数据类。"""
+import contextvars
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+from ..core.thought_chain import HarnessStatus
+
+
+# 目标基线是**每任务**语义(register_goal 每次任务设一次),却存在 Harness 实例上——
+# 并发顶层任务打同一 Agent 的 harness 时会互相覆盖,导致 check 对着错误的目标算漂移。
+# 与 base.py 同构:放进单个 module 级 contextvar 承载的 dict、按实例 token 分槽。
+# 累积学习态(weights/_policy/_delta_history/_run_count/_shadow_mode)仍留在实例上——
+# 那本就该按 Agent 累积,且同步 check 内无 await,协作调度下读改写原子安全。
+_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,359 @@
+"""Harness Policy 学习 + 影子观察 + 阈值校准 + 持久化（mixin）。
+
+拆分自 harness.py：`Harness` 主类继承本 mixin，通过 `self.weights/_policy/_lock`
+等实例状态协同工作。纯搬移、零行为变更。
+"""
+import os
+
+import numpy as np
+import yaml
+from datetime import datetime, timezone
+
+from ..core.thought_chain import ThoughtNode
+from ._base import HarnessResult
+
+
+class PolicyMixin:
+    # ── 学习规则的 action 编译 / 应用 ─────────────────────────
+
+    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):
+                    # 多条 restrict 取最严(最小)上限
+                    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)
+
+    # ── Policy 学习(P0-1:影子验证 + 回滚 + 边界)────────────────
+
+    # 【P0-1 边界】可生成影子规则的维度。semantic 可学但**仅权重级**(不生成规则——
+    # 原 increase_semantic_threshold 规则本就无规则级应用,判定行为不变);
+    # 不在 weights 里的未知维度 → 只记录不学习(fail-closed,防未来新维度被默认自学)。
+    _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
+
+        # ── 边界:未知维度 fail-closed,只记录不学习(权重也不动)──
+        if dim not in self.weights:
+            self._record_history("skip", "",
+                                 note=f"未知维度 '{dim}' 禁止自学习(fail-closed)")
+            self._save_policy()
+            return
+
+        # ── 规则级:tool/scope 生成影子候选;semantic 仅权重级 ──
+        if dim in self._LEARNABLE_RULE_DIMS:
+            new_rule = {
+                "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,
+                # 影子账本:observations=适用次数;would_block=若生效会多拦;
+                # would_pass=若生效会多放。三者是 promote/discard 的全部证据。
+                "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 → 影子观察")
+            # 不 _reindex_learned_actions —— 影子规则**不得**影响判定
+            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", ""),
+            })
+
+        # 更新权重：触发截断的维度权重 +δ
+        # 必须**先把新权重算完整再整体赋值**,不能"原地 +0.05 再归一化":
+        # 后者会让 self.weights 出现「各维之和 = 1.05」的瞬时中间态,而此刻若有人读到它
+        # (get_policy_summary / policy_updated 的监听者),拿到的就是未归一化的错值。
+        # 实测:同一份 summary 持有的 weights 引用会被读出 0.35,而稍后再取是 0.333 —— 正是
+        # 这个中间态被观察到。
+        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
+
+            # 双轨:把该规则的 action 应用到 scores 副本,用**同一套权重与阈值**判定
+            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 ""
+            # 与 _is_penalized_tool 同语义:**仅当前工具命中 pattern 才抬分**。
+            # 若不看匹配、凡 tool 分非零就抬,会把「毫不相干工具的场景」误记成
+            # would_block —— 影子证据完全失真,好规则会被冤判成误伤 discard。
+            if pat and tool_name and (tool_name == pat or pat in tool_name):
+                scores["tool"] = 1.0
+        elif atype == "restrict_scope":
+            # 与 check() 里 restrict_scope 的判定同构:新增实体超限则抬 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)
+        # 会多拦很多(可能误伤)→ 不 promote
+        if wb / max(obs, 1) > 0.3:
+            return False
+        # 几乎不改变判定 → promote 没意义
+        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=float)
+        if arr.size == 0:
+            # 空历史(理论上不会发生,因调用前每次 check 都 append)→ 用默认阈值,避免 nan
+            self._shadow_mode = False
+            return
+        mean = float(arr.mean())
+        std = float(arr.std())
+        p90 = float(np.percentile(arr, 90))
+        # BLOCK 阈值取"高分位 / 均值+1.5σ"的较大者,再留 10% 余量,
+        # 保证正常任务(集中在均值附近)不被误拦
+        block = max(p90, mean + 1.5 * std) * 1.10
+        # WARN 阈值取 block 的 0.8 倍,给出渐进预警区
+        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),
+        })
+
+    # ── Policy 持久化 ──────────────────────────────────────
+
+    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 {}
+        # 默认 Policy 骨架（格式从第一天锁定）
+        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)