foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/core/failure_policy.py

@@ -0,0 +1,151 @@
+"""失败策略表:把「工具失败了」映射成「下一步做什么」。
+
+病根:工具轮的失败此前只有两种归宿——原样回注给模型,或直接丢掉。于是「超时了该重试
+一次还是放弃」「没配搜索服务该降级还是换参数」全靠模型临场发挥;而模型最常见的反应是
+**换个说法把没做成的事说成做成了**(静默假成功)。这张表把那类决策从模型手里拿走:
+错误特征 → 动作,查表即得,和 recover 层「由策略表决定,不猜」同一原则。
+
+设计取舍:
+- **按文本特征分类,不按异常类型**。工具跑在守护线程里(见 agents/mixins/tool_exec),
+  跨线程、跨工具之后剩下的只有一句回注文本;异常类型在这里已经丢失。
+- **只有只读工具才自动重试**。写/发送/支付类动作重试一次 = 可能重复扣款、重复发消息;
+  这类一律交人。
+- 分类是**启发式**的,因此:匹配不到 → 当作未知失败(不重试、交人),绝不乐观当成功。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# ── 失败类型 ────────────────────────────────────────────────────────────
+OK = "ok"
+TIMEOUT = "timeout"                    # 单工具硬超时(工具轮主动放弃)
+TRANSIENT = "transient"                # 网络抖动/限流/5xx —— 重试有意义
+NOT_CONFIGURED = "not_configured"      # 没配 key/服务 —— 重试一万次也没用
+EMPTY = "empty"                        # 调通了但没内容(搜不到/没召回)
+INVALID_ARGS = "invalid_args"          # 模型给的参数不合法 —— 让模型自己改
+DENIED = "denied"                      # 策略禁用/未知工具 —— 不许绕过
+NEEDS_HUMAN = "needs_human"            # 红线动作需确认 —— 只能人来做
+EXCEPTION = "exception"                # 工具内部抛异常
+UNKNOWN = "unknown"                    # 认不出来:保守(不重试、交人)
+
+#: 动作
+NONE = "none"
+RETRY = "retry"                        # 自动再试一次(仅只读)
+REPARAM = "reparam"                    # 让模型换参数/换查询词
+DEGRADE = "degrade"                    # 降级如实告知,不重试
+HAND_TO_HUMAN = "hand_to_human"        # 交人
+STOP = "stop"                          # 终止,不许再试
+
+#: 特征表。**顺序敏感**:先命中先返回。顺序上的两个坑都踩过:
+#:   · "未返回结果"(empty)不能先被 "未返回"(timeout) 吃掉;
+#:   · "不合法"(invalid_args)要在 "拒绝"(denied) 之前,否则参数错误被当成越权。
+_RULES: tuple[tuple[str, tuple[str, ...]], ...] = (
+    (DENIED, ("已被策略禁用", "被权限策略拒绝", "未知工具")),
+    (NEEDS_HUMAN, ("需确认的动作", "需要你确认", "请用户确认", "只能由你亲自确认")),
+    (INVALID_ARGS, ("入参不合法", "缺少必填", "类型应为")),
+    (TIMEOUT, ("超过", "超时", "timed out", "timeout")),
+    (NOT_CONFIGURED, ("未配置", "not configured", "未设置", "缺少 api", "缺少 key")),
+    (EMPTY, ("未返回结果", "未召回到", "no result", "未命中", "没有找到")),
+    (TRANSIENT, ("网络", "连接失败", "connection", "502", "503", "504", "429", "rate limit")),
+    (EXCEPTION, ("执行异常",)),
+)
+
+#: 类型 → (动作, 是否可重试, 给模型的一句硬提示)。提示写进回注文本,模型没法装作没看见。
+_ACTIONS: dict[str, tuple[str, bool, str]] = {
+    TIMEOUT: (RETRY, True,
+              "这一步超时未完成,已自动重试一次仍有问题。请如实说明这一步没做成,不要编造结果。"),
+    TRANSIENT: (RETRY, True,
+                "这次失败像是临时的网络/服务问题,已自动重试一次。若仍失败,如实说明当前无法获取。"),
+    EXCEPTION: (RETRY, True,
+                "工具内部异常,已自动重试一次。若仍失败,如实说明该步骤未能执行。"),
+    EMPTY: (REPARAM, False,
+            "调用成功但没有拿到内容。可以换一个更具体的查询词或放宽条件再试一次;"
+            "仍为空就如实回答「没有查到」,不要用常识补全成确定结论。"),
+    INVALID_ARGS: (REPARAM, False,
+                   "参数不合法,这一步没有执行。请按工具声明修正参数后再调用;"
+                   "不要把失败当成已完成。"),
+    NOT_CONFIGURED: (DEGRADE, False,
+                     "该能力当前未配置(服务/密钥缺失),不是暂时故障,重试无用。"
+                     "请告知用户这项能力暂不可用,不要假装查到了。"),
+    NEEDS_HUMAN: (HAND_TO_HUMAN, False,
+                  "这是需要用户确认的动作,我没有执行。把要做的操作拟成草稿交用户确认。"),
+    DENIED: (STOP, False, "该工具被策略禁止,不要换个名字或换个参数再试。"),
+    UNKNOWN: (HAND_TO_HUMAN, False,
+              "这一步的结果不可信(无法判定成功还是失败)。不要向用户断言它已完成。"),
+    OK: (NONE, False, ""),
+}
+
+
+@dataclass(frozen=True)
+class Decision:
+    """一次失败判定:类型 → 动作 + 给模型看的提示。"""
+
+    kind: str
+    action: str
+    retryable: bool
+    hint: str
+
+    @property
+    def is_ok(self) -> bool:
+        return self.kind == OK
+
+    def to_dict(self) -> dict:
+        return {"kind": self.kind, "action": self.action,
+                "retryable": self.retryable, "hint": self.hint}
+
+
+#: 失败回注的形态标记。工具执行侧的失败文本统一以 "(" 开头(见 tool_exec 的兜底),
+#: 另有少数异常文本不带括号。**不能**用"含 未/失败 就算失败"这种宽松判据:
+#: 搜索正文里"未来""失败案例"都会误伤,把成功结果标成失败。
+_FAILURE_MARKERS = ("执行异常", "入参不合法", "被权限策略拒绝", "缺少必填")
+
+
+def looks_like_failure(text: str) -> bool:
+    t = (text or "").strip()
+    if not t:
+        return True
+    return t.startswith("(") or any(m in t for m in _FAILURE_MARKERS)
+
+
+def classify(text: str) -> str:
+    """把回注文本归类:``ok`` / 具体失败类型 / ``unknown``(认不出来,保守交人)。"""
+    t = (text or "").strip()
+    if not t:
+        return UNKNOWN                      # 空结果:不能当成功,也不确定成因
+    if not looks_like_failure(t):
+        return OK
+    low = t.lower()
+    for kind, needles in _RULES:
+        if any(n in low for n in needles):
+            return kind
+    return UNKNOWN
+
+
+def decide(text: str, tool: str = "", capability: dict | None = None,
+           attempt: int = 1, max_attempts: int = 2) -> Decision:
+    """查表得到动作。
+
+    ``attempt`` 是**已尝试次数**(第一次调用传 1)。可重试类型在 ``attempt < max_attempts``
+    时给 ``retry``;只读工具才真的会被重试 —— 这里只判定,是否执行由调用方决定,
+    因为"这个工具能不能安全重复执行"属于能力声明(capability),不是文本语义。
+    """
+    kind = classify(text)
+    action, retryable, hint = _ACTIONS.get(kind, _ACTIONS[UNKNOWN])
+    read_only = bool((capability or {}).get("read_only"))
+    if action == RETRY and (not read_only or attempt >= max_attempts):
+        action = HAND_TO_HUMAN
+        if not read_only:
+            hint = ("这一步有副作用,重试可能重复执行,因此没有自动重试。"
+                    "请如实说明它没有完成。")
+    return Decision(kind=kind, action=action, retryable=retryable, hint=hint)
+
+
+def annotate(text: str, decision: Decision) -> str:
+    """把动作提示拼到回注文本后面(仅失败时;成功文本一个字都不改)。
+
+    为什么要拼在文本里而不是另走一路:回注给模型的是**纯文本**,多一条通道意味着
+    模型可能只读到其中一条;拼在末尾让"结果"和"该怎么对待这个结果"不可分割。
+    """
+    if decision.is_ok or not decision.hint:
+        return text or ""
+    return f"{text or ''}\n[执行策略] {decision.hint}"

package/python/foxclaw/core/gateway.py

@@ -0,0 +1,85 @@
+"""
+统一 API 网关限流(gateway.py)
+
+把散落在各处(MCP、/chat/stream)的单点限流收敛成一层**统一网关**:
+  · per-client 令牌桶——突发限流(每分钟额度,允许瞬时打满桶)
+  · 固定窗口配额——持续限流(每小时总额度)
+  · 空闲客户端淘汰——防攻击者轮换 key/IP 把 per-client 字典撑爆内存(与 metrics「unmatched」同款教训)
+
+client 身份 = X-API-Key(有则)否则来源 IP。线程安全(单锁,check 内无 await/无阻塞 I/O)。
+默认宽松:本地单用户近乎无感;对外暴露时经环境变量收紧。
+"""
+from __future__ import annotations
+
+import time
+import threading
+
+
+class Gateway:
+    def __init__(self, rate_per_min: int = 600, quota_per_hour: int = 20000,
+                 max_clients: int = 4096):
+        self.rate = max(1, int(rate_per_min))
+        self.capacity = float(self.rate)               # 桶容量 = 每分钟额度(允许突发到满桶)
+        self.refill = self.capacity / 60.0             # 令牌/秒
+        self.quota = max(1, int(quota_per_hour))
+        self.max_clients = max(64, int(max_clients))
+        self._lock = threading.Lock()
+        self._buckets: dict = {}    # client -> [tokens, last_ts]
+        self._quota: dict = {}      # client -> [count, window_start]
+        self._seen: dict = {}       # client -> last_ts(用于空闲淘汰)
+        self.rejected = 0           # 累计拒绝数(可观测)
+
+    def check(self, client: str):
+        """判定一次请求。返回 (allowed: bool, retry_after: int, reason: str)。
+        reason ∈ {'', 'rate', 'quota'}。allowed=False 时 retry_after 为建议重试秒数。"""
+        now = time.time()
+        with self._lock:
+            self._evict_locked(now)
+            self._seen[client] = now
+
+            # ① 配额(固定 1 小时窗口)
+            q = self._quota.get(client)
+            if q is None or now - q[1] >= 3600.0:
+                q = [0, now]
+                self._quota[client] = q
+            if q[0] >= self.quota:
+                self.rejected += 1
+                return False, int(3600.0 - (now - q[1])) + 1, "quota"
+
+            # ② 令牌桶(突发限流)
+            b = self._buckets.get(client)
+            if b is None:
+                b = [self.capacity, now]
+                self._buckets[client] = b
+            b[0] = min(self.capacity, b[0] + (now - b[1]) * self.refill)
+            b[1] = now
+            if b[0] < 1.0:
+                self.rejected += 1
+                return False, int((1.0 - b[0]) / self.refill) + 1, "rate"
+
+            # 放行:扣 1 令牌 + 计 1 配额
+            b[0] -= 1.0
+            q[0] += 1
+            return True, 0, ""
+
+    def _evict_locked(self, now: float):
+        """超过 max_clients 时淘汰最久未见的一批(降到 ~90%)。必须在锁内调用。"""
+        if len(self._seen) <= self.max_clients:
+            return
+        n_drop = len(self._seen) - self.max_clients + max(1, self.max_clients // 10)
+        # 按 last_ts 升序取最旧的 n_drop 个
+        victims = sorted(self._seen.items(), key=lambda kv: kv[1])[:n_drop]
+        for c, _ in victims:
+            self._seen.pop(c, None)
+            self._buckets.pop(c, None)
+            self._quota.pop(c, None)
+
+    def stats(self) -> dict:
+        with self._lock:
+            return {
+                "tracked_clients": len(self._seen),
+                "rate_per_min": self.rate,
+                "quota_per_hour": self.quota,
+                "max_clients": self.max_clients,
+                "rejected_total": self.rejected,
+            }

package/python/foxclaw/core/governance_audit.py

@@ -0,0 +1,175 @@
+"""
+治理决策统一审计(P1-2 基础 / P3-4 decision_id)。
+
+系统的裁决点分散在四层,各说各话:
+  · Harness(推理漂移:语义/工具/范围)—— emit harness_pass/warn/block
+  · Permission(动作权限:deny>ask>allow 四阶段)—— 经 PolicyGate emit policy.decision.*
+  · Orchestrator(跨 Agent 委派裁决)—— 原本**无任何事件**
+  · SkillAdapter(执行终态:成功/失败/断路器/封杀)—— 原本**无任何事件**
+
+本模块提供一条**统一治理审计流**,不改变任何裁决行为,只做记录:
+
+  事件通道:脊柱广播 `governance.decision`(不在 WS 静音列表 → 前端可见)
+  落盘通道:{data_dir}/audit/governance.jsonl(环形缓冲之外的持久样本)
+
+每条记录带 **decision_id**(本次裁决的唯一 ID)与 **correlation_id**(跨层关联键):
+  · permission 裁决生成 decision_id → 同一 SkillAdapter.invoke 的执行审计用它做
+    correlation_id ⇒ 「谁批准的这个动作、执行结果如何」可join
+  · Orchestrator 用 req.id 做 correlation_id ⇒ 多轮协商的历次裁决串成一条链
+
+verdict 词汇(两类,查询时注意区分):
+  · 裁决类:allow / warn / deny / confirm(与 PolicyGate 归一词汇一致)
+  · 执行类:success / failed(SkillAdapter 的执行终态)
+
+记录策略(防止高频正常路径淹没审计流):
+  · harness / permission 层只记**非 allow**(warn/deny/confirm)——PASS 是每步推理的常态
+  · orchestration 层全量(跨 Agent 委派本来就低频)
+  · skill 层全量(执行审计是 P2-0 的核心价值;一次任务仅个位数调用)
+
+与 shared_write 审计(audit_sink.py)的关系:那是「记忆写入准入」专项,这是「治理裁决」
+总流;两者并存、各自落盘,互不替代。
+
+开关:FOXCLAW_GOVERNANCE_AUDIT=0 关闭(默认开;每条 <500 字节,量级可忽略)。
+审计一律 fail-safe:任何记录异常都静默吞掉,绝不影响裁决主流程(与闸门同约束)。
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import audit_chain
+
+ENV_SWITCH = "FOXCLAW_GOVERNANCE_AUDIT"
+TOPIC = "governance.decision"
+
+# verdict 合法取值(文档用,不做硬校验——审计不该因词汇笔误崩掉主流程)
+VERDICTS_RULING = ("allow", "warn", "deny", "confirm")   # 裁决类
+VERDICTS_EXECUTION = ("success", "failed")               # 执行类
+
+# 已知层名(同上,仅文档)
+LAYERS = ("harness", "permission", "orchestration", "skill")
+
+
+def new_decision_id() -> str:
+    """生成一次治理裁决的唯一 ID。短 hex 够用(单机审计,非全局唯一约束)。"""
+    return f"dec_{uuid.uuid4().hex[:12]}"
+
+
+class GovernanceAuditor:
+    """统一治理审计记录器:发脊柱事件 + 可选 JSONL 落盘。
+
+    线程安全:记录可能来自任意 Agent 的任意线程(事件脊柱 handler 在锁外执行,
+    但 invoke/route_request 本身可被并发调用)——落盘用进程内锁串行。
+    多进程部署(FOXCLAW_ALLOW_INSECURE 的多 worker)不在本机开发场景内,从略。
+    """
+
+    def __init__(self, spine=None, sink_path: Path | None = None):
+        self._spine = spine
+        self._path = Path(sink_path) if sink_path else None
+        self._lock = threading.Lock()
+        # 链尾 hash:首次落盘时从文件尾部补齐(重启后接着上一条链,而不是重开 GENESIS)
+        self._last_hash: str | None = None
+
+    @property
+    def path(self) -> Path | None:
+        return self._path
+
+    def record(self, *, layer: str, actor: str, action: str, verdict: str,
+               reason: str = "", detail: dict | None = None,
+               decision_id: str | None = None,
+               correlation_id: str | None = None) -> str:
+        """记录一条治理裁决/执行审计,返回 decision_id(显式传入则原样返回)。
+
+        全参数关键字化:调用点必须写明每个字段是什么,避免位置参数错位造成
+        「审计记错层」这种难以察觉的污染。
+        """
+        did = decision_id or new_decision_id()
+        rec = {
+            "decision_id": did,
+            "correlation_id": correlation_id or "",
+            "layer": layer,
+            "actor": actor,
+            "action": action,
+            "verdict": verdict,
+            "reason": (reason or "")[:200],          # 理由截断,防巨型异常串灌爆审计
+            "detail": detail or {},
+            "ts": datetime.now(timezone.utc).isoformat(),
+        }
+        self._emit(rec)
+        self._persist(rec)
+        return did
+
+    # ── 内部:两个通道,各自独立 fail-safe ─────────────────────
+
+    def _emit(self, rec: dict) -> None:
+        if self._spine is None:
+            return
+        try:
+            self._spine.publish(TOPIC, dict(rec), source="governance_audit",
+                                correlation_id=rec["correlation_id"] or None)
+        except Exception:
+            pass
+
+    def _persist(self, rec: dict) -> None:
+        """落盘时接哈希链(见 core/audit_chain.py):改一行/删中间一行都能被 verify 发现。
+
+        事件通道仍发**不带链字段**的原始 rec —— 前端只关心裁决内容,而链是落盘证据;
+        两个通道内容不同是有意的,别拿 WS 事件当真伪校验的依据。
+        """
+        if self._path is None:
+            return
+        try:
+            with self._lock:
+                self._path.parent.mkdir(parents=True, exist_ok=True)
+                if self._last_hash is None:
+                    self._last_hash = audit_chain.tail_hash(self._path)
+                chained = audit_chain.link(rec, self._last_hash)
+                with open(self._path, "a", encoding="utf-8") as f:
+                    f.write(json.dumps(chained, ensure_ascii=False) + "\n")
+                self._last_hash = chained["hash"]
+        except Exception:
+            pass
+
+    def read(self, limit: int = 200) -> list:
+        """读落盘记录(新→旧),坏行跳过。供工具/测试/未来 API 用。"""
+        if self._path is None or not self._path.exists():
+            return []
+        out = []
+        try:
+            with open(self._path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        out.append(json.loads(line))
+                    except Exception:
+                        continue
+        except Exception:
+            return []
+        return out[-limit:][::-1]
+
+    def verify(self) -> tuple:
+        """校验落盘链 → (ok, 条数, 问题)。无落盘时视为通过。
+
+        用法:`python -m foxclaw.core.audit_chain {data_dir}/audit/governance.jsonl`。
+        """
+        if self._path is None:
+            return True, 0, ""
+        return audit_chain.verify(self._path)
+
+
+def attach(spine, data_dir) -> GovernanceAuditor | None:
+    """装配工厂:FOXCLAW_GOVERNANCE_AUDIT=0 时返回 None(各层按 None 跳过记录)。
+
+    落盘到 {data_dir}/audit/governance.jsonl(该目录已被 .gitignore 覆盖)。
+    spine 为 None 时仍可落盘(standalone/测试场景),只是没有事件通道。
+    """
+    if os.environ.get(ENV_SWITCH, "1") == "0":
+        return None
+    sink = Path(data_dir) / "audit" / "governance.jsonl" if data_dir else None
+    return GovernanceAuditor(spine=spine, sink_path=sink)