foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/mcp_server.py

@@ -0,0 +1,189 @@
+"""Foxclaw 内置 MCP 服务器:把只读知识(HKC)+记忆(HMR)暴露成 MCP 工具,
+让任何 MCP 客户端(Claude Desktop/Cursor/别的 Agent)能调用个人知识与记忆。
+默认关(FOXCLAW_MCP_SERVER=1 开),挂 /api/mcp/,受 X-API-Key 鉴权。
+安全:knowledge_*/memory_recall 只读;ask_foxclaw(需再开 FOXCLAW_MCP_AGENTS)会驱动 Agent
+     并写入记忆/审计,非只读。工具名/描述中性,错误对外脱敏(不泄露内部细节/架构)。"""
+from __future__ import annotations
+import os
+import time
+import threading
+from mcp.server.fastmcp import FastMCP
+
+_MAX_TOP_K = 50
+_MAX_QUERY = 2000
+
+
+class _RateLimiter:
+    """令牌桶限流(线程安全)。防外部刷爆:读工具与 ask_foxclaw 各一桶。"""
+    def __init__(self, per_min: int):
+        self.capacity = max(1, int(per_min))
+        self.tokens = float(self.capacity)
+        self.rate = self.capacity / 60.0
+        self.last = time.monotonic()
+        self.lock = threading.Lock()
+
+    def allow(self) -> bool:
+        with self.lock:
+            now = time.monotonic()
+            self.tokens = min(self.capacity, self.tokens + (now - self.last) * self.rate)
+            self.last = now
+            if self.tokens >= 1:
+                self.tokens -= 1
+                return True
+            return False
+
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, str(default)))
+    except ValueError:
+        return default
+
+
+def _clamp_top_k(v, default: int = 5) -> int:
+    try:
+        return max(1, min(int(v), _MAX_TOP_K))
+    except Exception:
+        return default
+
+
+def _clean_query(q) -> str:
+    return (str(q or "")[:_MAX_QUERY])
+
+
+def _external_action(sid: str):
+    """给「非技能动作」(如外部驱动 Agent)做个最小 skill 替身,好走同一套权限门。
+
+    鸭子类型,只提供 permission.evaluate 真正读的字段;不 import skills 包(避免启停期的
+    包级循环)。side_effect=write + external=True 是事实描述:它确实有副作用且面向外部。
+    """
+    from types import SimpleNamespace
+    return SimpleNamespace(id=sid, kind="mcp", params={"task": {"required": True}},
+                           side_effect="write", external=True,
+                           destructive=False, read_only=False)
+
+
+def _policy_error(gate, rules, task: str) -> str | None:
+    """外部驱动动作的准入裁决。返回 None = 放行,否则返回错误码。
+
+    为什么这里要单独判:外部客户端「绕开工具直接驱动 Agent」,若不过门,宿主配的
+    deny(封杀某动作)和 ask(要求人工)对它完全无效。
+    MCP 没有交互确认通道 → 命中 ask 规则即拒,而不是放行后等一个永远不会来的确认;
+    其余常规 ask(副作用 / external)由 FOXCLAW_MCP_AGENTS=1 这道显式开关承担授权。
+    """
+    if gate is None:
+        return None
+    from foxclaw.skills.permission import ASK_RULE, MISSING_PARAMS
+    v = gate.check_action(_external_action("mcp:ask_foxclaw"), {"task": task},
+                          rules=rules, mode="strict", confirmed=False)
+    code = getattr(v.raw, "reason_code", "") or ""
+    if getattr(v, "level", "") == "deny":
+        return "blocked"
+    if code == ASK_RULE:
+        return "needs_confirmation"
+    if code == MISSING_PARAMS:
+        return "missing arguments"
+    return None
+
+
+def build_foxclaw_mcp(os_getter, expose_agents: bool = False) -> FastMCP:
+    """os_getter:无参回调,返回当前 Foxclaw 实例(惰性,启动后才有)。
+    expose_agents:另开一道开关才暴露 Agent 调度(有副作用面,默认关)。"""
+    mcp = FastMCP("Foxclaw Knowledge", stateless_http=True, streamable_http_path="/")
+    # 限流(env 可配):读工具较宽松、ask_foxclaw(驱动 LLM,贵)较紧
+    read_limiter = _RateLimiter(_env_int("FOXCLAW_MCP_RATE_READ", 120))
+    agent_limiter = _RateLimiter(_env_int("FOXCLAW_MCP_RATE_AGENT", 20))
+
+    @mcp.tool()
+    def knowledge_search(query: str, top_k: int = 5, domain: str = "") -> list:
+        """在个人知识库中检索相关知识条目(只读)。返回每条的 id/名称/摘要/类型。"""
+        if not read_limiter.allow():
+            return [{"error": "rate limited"}]
+        try:
+            hkc = getattr(os_getter(), "hkc", None)
+            if hkc is None or not getattr(hkc, "available", False):
+                return []
+            hits = hkc.client.search(_clean_query(query), mode="hybrid",
+                                     top_k=_clamp_top_k(top_k), domain=str(domain or "")[:120])
+            return [{"id": getattr(h, "ku_id", "") or getattr(h, "id", ""),
+                     "name": getattr(h, "name", ""),
+                     "summary": getattr(h, "summary", ""),
+                     "type": str(getattr(h, "ku_type", ""))}
+                    for h in (hits or [])]
+        except Exception:
+            return [{"error": "internal error"}]        # 对外脱敏:不回传 str(e)
+
+    @mcp.tool()
+    def knowledge_get(ku_id: str) -> dict:
+        """按 id 取一个知识条目的详情(只读)。"""
+        if not read_limiter.allow():
+            return {"error": "rate limited"}
+        try:
+            hkc = getattr(os_getter(), "hkc", None)
+            if hkc is None or not getattr(hkc, "available", False):
+                return {"error": "knowledge base unavailable"}
+            ku = hkc.container.graph_store.get(str(ku_id or "")[:200])
+            if ku is None:
+                return {"error": "not_found"}
+            return {"id": getattr(ku, "ku_id", ku_id), "name": getattr(ku, "name", ""),
+                    "summary": getattr(ku, "summary", ""), "type": str(getattr(ku, "ku_type", "")),
+                    "domain": getattr(ku, "domain", ""), "tags": list(getattr(ku, "tags", []) or [])}
+        except Exception:
+            return {"error": "internal error"}
+
+    @mcp.tool()
+    def memory_recall(query: str, top_k: int = 5) -> list:
+        """在个人记忆中召回相关内容(只读;仅助手层+共享层)。"""
+        if not read_limiter.allow():
+            return [{"error": "rate limited"}]
+        try:
+            hmr = getattr(os_getter(), "hmr", None)
+            if hmr is None:
+                return []
+            res = hmr.recall(query=_clean_query(query), agent_id="supervisor", top_k=_clamp_top_k(top_k))
+            return [{"id": r.get("id", ""), "content": r.get("content", ""),
+                     "type": r.get("type", "")} for r in (res or [])]
+        except Exception:
+            return [{"error": "internal error"}]
+
+    if expose_agents:
+        @mcp.tool()
+        async def ask_foxclaw(task: str, agent: str = "supervisor") -> dict:
+            """把一个任务交给 Foxclaw 的认知 Agent 处理(主管默认自动分诊到财务/行政/办公/助手)。
+            返回 {reply, dispatched_to}。
+            ⚠ 非只读:执行过程会写入个人记忆(HMR)与审计链。有副作用的**技能**调用(写/发送/支付)
+            会被内部权限门拦下需确认,MCP 无法确认→不执行;但记忆写入等内部副作用仍会发生。
+            因此这是"写能力"工具,仅在 FOXCLAW_MCP_AGENTS=1 且鉴权下暴露。"""
+            if not agent_limiter.allow():
+                return {"error": "rate limited"}
+            import asyncio as _a
+            os_ = os_getter()
+            if os_ is None:
+                return {"error": "not ready"}
+            task = _clean_query(task)
+            agent = str(agent or "supervisor")[:40]
+            if not task.strip():
+                return {"error": "missing arguments"}
+            err = _policy_error(getattr(os_, "policy_gate", None),
+                                getattr(getattr(os_, "skill_adapter", None), "rules", None),
+                                task)
+            if err:
+                return {"error": err}
+
+            def _work():
+                from foxclaw.agents.base import _suppress_memory
+                _suppress_memory.set(True)   # 外部驱动的任务不写 HMR(防污染),随上下文传到 run_task
+                return os_.scheduler.run(
+                    lambda: _a.run(os_.run(task, agent)),
+                    agent_id=agent, task=task)
+            try:
+                res = await _a.to_thread(_work)
+            except Exception:
+                return {"error": "internal error"}
+            if not isinstance(res, dict):
+                return {"reply": str(res), "dispatched_to": agent}
+            reply = (res.get("sub_result") or res.get("summary")
+                     or res.get("reply") or res.get("error") or "")
+            return {"reply": str(reply), "dispatched_to": res.get("dispatched_to", agent)}
+
+    return mcp

package/python/foxclaw/orchestration/__init__.py

@@ -0,0 +1,184 @@
+"""
+Foxclaw 主管编排子系统 — 全局态势 + 跨 Agent 编排
+主管不是领域专家,而是协调者。它的两个核心能力:
+  1. GlobalSituation:汇总三个内核状态,形成"驾驶舱视图"
+  2. CrossAgentRequest:一个 Agent 的行为触发另一个 Agent 的约束
+     (典型:行程 Agent 规划出差 → 向财务 Agent 申请差旅预算 → 财务守门人审批)
+"""
+
+from collections import deque
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Literal
+import uuid
+
+
+RequestType = Literal["budget_request", "schedule_request", "knowledge_request",
+                      "info_request"]
+RequestStatus = Literal["pending", "approved", "rejected", "needs_confirmation"]
+
+
+@dataclass
+class CrossAgentRequest:
+    """跨 Agent 请求 — 编排的基本单元。
+    一个 Agent 向另一个发起请求,目标 Agent 用自己的守门人裁决。"""
+    from_agent: str                     # 发起方
+    to_agent: str                       # 目标方
+    request_type: RequestType
+    payload: dict                       # 请求内容(金额/时间/查询等)
+    reason: str = ""
+    status: RequestStatus = "pending"
+    verdict: str = ""                   # 目标 Agent 的裁决说明
+    negotiation: list = field(default_factory=list)   # 协商回合记录(每轮:裁决 + 让步)
+    id: str = field(default_factory=lambda: f"req_{uuid.uuid4().hex[:10]}")
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class GlobalSituation:
+    """全局态势 — 主管的驾驶舱视图,汇总各内核关键指标。"""
+    finance: dict = field(default_factory=dict)     # 超支?守门人告警?
+    learning: dict = field(default_factory=dict)    # 待复习?薄弱主题?
+    itinerary: dict = field(default_factory=dict)   # 行程冲突?赶不及?
+    alerts: list = field(default_factory=list)      # 跨域汇总的高优先告警
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+class Orchestrator:
+    """主管编排引擎:汇总态势 + 路由跨 Agent 请求到目标守门人。
+
+    【P1-3】不再直接持有 agents 字典,而是持 CapabilityRegistry、按需惰性解析
+    (打断 Supervisor⇄Orchestrator 直接环:主管持有本引擎,本引擎经注册表解析 agents,
+    不再反向直接持有含主管的 agents 字典)。"""
+
+    def __init__(self, caps, auditor=None):
+        self._caps = caps               # CapabilityRegistry
+        # 【P1-3】统一治理审计(可空:standalone 无审计)。裁决事件原本**完全没有**——
+        # 跨 Agent 委派的批准/拒绝/转人工,事前无任何可观测记录。
+        self._auditor = auditor
+        # 【深审修复·长期运行泄漏】原为普通 list、只增不减且**全库从不读**——每次跨 Agent 请求
+        # append 一个 req → 无界增长。改有界 deque(保留最近 N 条供未来观测,符合本库 token_meter/
+        # HookManager 的有界日志惯例);deque.append 原子 ⇒ 并发路由也安全。
+        self.request_log: deque = deque(maxlen=1000)
+
+    @property
+    def agents(self) -> dict:
+        """按名字从注册中枢解析 agents(id -> agent 实例)。"""
+        return self._caps.get("agents") or {}
+
+    # ── 全局态势汇总(P3:通用聚合,不懂任何领域内部 API)────────────
+    def gather_situation(self) -> GlobalSituation:
+        """通用聚合各 Agent 自报的领域态势(agent.situation()),形成驾驶舱视图。
+        编排层不再直接读 finance/learning/itinerary 内核——领域知识已归属各领域 Agent。"""
+        sit = GlobalSituation()
+        alerts = []
+        for agent in self.agents.values():
+            try:
+                s = agent.situation()
+            except Exception:
+                continue
+            if not s:
+                continue
+            # 一个 Agent 可以自报**多个**领域(拓扑 5→3 后,办公学习 Agent 同时覆盖
+            # learning 与 itinerary),故 `domains: {name: status}` 与旧的单 `domain` 都收。
+            doms = s.get("domains")
+            if isinstance(doms, dict) and doms:
+                for d, st in doms.items():
+                    if d and hasattr(sit, d):       # finance/learning/itinerary
+                        setattr(sit, d, st or {})
+            else:
+                domain = s.get("domain")
+                if domain and hasattr(sit, domain):
+                    setattr(sit, domain, s.get("status", {}) or {})
+            alerts += s.get("alerts", []) or []
+        sit.alerts = sorted(alerts,
+                            key=lambda a: {"critical": 0, "warn": 1, "info": 2}
+                            .get(a.get("severity"), 3))
+        return sit
+
+    # ── 跨 Agent 请求路由(P3:通用委托,由目标 Agent 用自己的守门人裁决)──────
+    def route_request(self, req: CrossAgentRequest) -> CrossAgentRequest:
+        """把请求路由给目标 Agent,由**目标 Agent**用自己的守门人裁决(编排层不懂领域)。"""
+        target = self.agents.get(req.to_agent)
+        if target is None:
+            # 【P1-0】原为 status="approved"(默认放行)—— 那是 fail-open:发起方会拿到
+            # "已批准",但**没有任何 Agent 真的处理过这个请求**。后果是实打实的,例如
+            # 行程 Agent 向未注册的 finance 申请差旅预算,会直接拿到批准并据此下单。
+            # 与下方「裁决异常 → 转人工确认」同属一条原则:裁决权不在编排层,凡未真正
+            # 裁决过的,都不能算通过。改为 needs_confirmation 同样"不崩",只是不再说谎。
+            req.status = "needs_confirmation"
+            req.verdict = f"目标 Agent '{req.to_agent}' 不存在,无法裁决,转人工确认"
+        else:
+            try:
+                target.handle_cross_request(req)
+            except Exception as e:
+                # 守门人裁决崩溃(如畸形 payload 让解析抛错)必须 **fail-safe**:转人工确认,
+                # 绝不自动放行——对守门人而言,裁决失败时放行=fail-open,是安全隐患。
+                req.status = "needs_confirmation"
+                req.verdict = f"裁决异常,转人工确认: {e}"
+        self.request_log.append(req)
+        self._audit_verdict(req)
+        return req
+
+    def _audit_verdict(self, req: CrossAgentRequest) -> None:
+        """【P1-3】把本次裁决记入统一治理审计流(governance.decision)。
+
+        correlation_id=req.id:negotiate 的多轮裁决共用同一 req.id ⇒ 协商链可 join;
+        每次裁决的 decision_id 各自独立(由审计器生成)。审计失败绝不影响路由。"""
+        if self._auditor is None:
+            return
+        verdict = {"approved": "allow", "rejected": "deny",
+                   "needs_confirmation": "confirm"}.get(req.status, req.status)
+        self._auditor.record(
+            layer="orchestration", actor=req.from_agent,
+            action=f"cross_request:{req.request_type}->{req.to_agent}",
+            verdict=verdict, reason=req.verdict,
+            detail={"status": req.status,
+                    "negotiation_round": len(req.negotiation)},
+            correlation_id=req.id)
+
+    # ── 协商闭环:被拒 → 发起方让步 → 再裁决 ──────────────────────────
+    def negotiate(self, req: CrossAgentRequest, max_rounds: int = 3) -> CrossAgentRequest:
+        """跑协商协议。原先裁决是**终局**:财务说预算不足→rejected→到此为止,用户只拿到
+        一句"被拒绝"。现在:发起方可拿着拒绝理由降标准重来(改高铁/换酒店/减一天)。
+
+        职责边界(守 P3):**编排层只跑协议、不懂领域** ——
+          · 裁决权仍在**目标 Agent**的守门人(route_request 原样调用,不绕过)
+          · 让步逻辑仍在**发起 Agent**(agent.concede),编排层只问"你能让吗"
+
+        安全不变量:
+          · **有界**:最多 max_rounds 轮,防死循环
+          · **必须真让步**:payload 没变化就停(否则无限重复同一请求)
+          · **协商失败维持 rejected,绝不降级成 needs_confirmation** ——
+            那等于给用户开一个点穿守门人的口子。协商只能"找到守门人愿意批的方案",
+            不能"把不批变成可以批"。
+        """
+        for rnd in range(1, max(1, max_rounds) + 1):
+            self.route_request(req)
+            req.negotiation.append({"round": rnd, "status": req.status,
+                                    "verdict": req.verdict,
+                                    "payload": dict(req.payload)})
+            if req.status != "rejected":
+                break                                  # 通过/待确认 → 协商结束
+            requester = self.agents.get(req.from_agent)
+            if requester is None:
+                break
+            try:
+                revised = requester.concede(req, req.verdict)   # 问发起方:能让吗?
+            except Exception as e:
+                req.negotiation.append({"round": rnd, "concede_error": str(e)[:120]})
+                break                                  # 让步逻辑出错 → 停,维持原裁决
+            if not revised or revised == req.payload:
+                break                                  # 让无可让 / 无实质变化 → 停
+            req.negotiation[-1]["conceded_to"] = dict(revised)
+            req.payload = revised
+        return req
+
+
+__all__ = ["CrossAgentRequest", "GlobalSituation", "Orchestrator"]

package/python/foxclaw/pipeline/__init__.py

@@ -0,0 +1,23 @@
+"""
+foxclaw.pipeline —— 认知管线(Cognitive Pipeline, v2 ②)。
+
+把任务处理从"隐式直线"升级为**显式、分阶段**的认知流:
+    perceive → recall → plan → route → act → verify → reflect → persist
+每个 stage 是一等公民,操作共享的 PipelineContext,可插桩/替换(规则版⇄LLM版)/重放。
+
+Step 1(抽壳):先落 recall / act 两个 stage,把 P1-1 的统一模板 run_task 委托给管线,
+行为逐字不变;后续步骤往 stages 列表里加 verify/reflect/plan/route/perceive。
+"""
+from .cognitive_pipeline import (
+    PipelineContext, CognitivePipeline,
+    stage_perceive, stage_recall, stage_plan, stage_route, stage_act,
+    stage_verify, stage_reflect, DEFAULT_STAGES,
+)
+from .supervisor_stages import SUPERVISOR_STAGES
+
+__all__ = [
+    "PipelineContext", "CognitivePipeline",
+    "stage_perceive", "stage_recall", "stage_plan", "stage_route", "stage_act",
+    "stage_verify", "stage_reflect", "DEFAULT_STAGES",
+    "SUPERVISOR_STAGES",
+]