foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/learning/spaced_repetition.py

@@ -0,0 +1,91 @@
+"""
+Foxclaw 学习子系统 — 间隔重复引擎(固化层)
+实现 SM-2 算法(Anki 核心算法的经典版本)。
+核心思想:学习是时间连续系统——追踪每个知识点的记忆强度随时间衰减,
+在最佳时机安排复习,让"越用越熟"变成可计算的机制。
+"""
+
+from datetime import datetime, timedelta
+from .models import ReviewState
+
+
+class SpacedRepetition:
+    """SM-2 间隔重复算法。
+
+    评分 grade(0~5):
+      0-2 = 没记住(算 lapse,重置间隔)
+      3   = 勉强记住
+      4   = 记住了
+      5   = 完美回忆
+    """
+
+    @staticmethod
+    def review(state: ReviewState, grade: int) -> ReviewState:
+        """根据本次回忆质量,更新间隔重复状态。返回更新后的 state。"""
+        grade = max(0, min(5, int(grade)))
+        now = datetime.now()
+        state.total_reviews += 1
+        state.last_review = now.isoformat()
+
+        if grade < 3:
+            state.repetitions = 0
+            state.interval = 1
+            state.lapses += 1
+        else:
+            if state.repetitions == 0:
+                state.interval = 1
+            elif state.repetitions == 1:
+                state.interval = 6
+            else:
+                state.interval = round(state.interval * state.ease_factor)
+            state.repetitions += 1
+
+        ef = state.ease_factor + (0.1 - (5 - grade) * (0.08 + (5 - grade) * 0.02))
+        state.ease_factor = max(1.3, round(ef, 3))
+
+        state.due_date = (now + timedelta(days=state.interval)).isoformat()
+        return state
+
+    @staticmethod
+    def due_items(states: list) -> list:
+        """返回所有到期需复习的状态,按掌握度升序(最弱的先复习)。"""
+        due = [s for s in states if s.is_due]
+        return sorted(due, key=lambda s: s.mastery)
+
+    @staticmethod
+    def forgetting_risk(states: list, horizon_days: int = 3) -> list:
+        """遗忘风险检测(对应财务异常检测):
+        即将到期且掌握度低的知识点 = 高遗忘风险。"""
+        risky = []
+        for s in states:
+            if s.days_until_due <= horizon_days and s.mastery < 0.5:
+                risky.append({
+                    "item_id": s.item_id,
+                    "mastery": s.mastery,
+                    "days_until_due": s.days_until_due,
+                    "lapses": s.lapses,
+                    "risk": round((1 - s.mastery) * (1 if s.is_due else 0.6), 3),
+                    "reason": f"掌握度仅 {s.mastery},"
+                              + ("已到期" if s.is_due else f"{s.days_until_due} 天内到期"),
+                })
+        return sorted(risky, key=lambda x: -x["risk"])
+
+    @staticmethod
+    def learning_load(states: list, days: int = 7) -> dict:
+        """学习负荷(对应财务烧钱速度):未来 N 天的复习量。"""
+        from collections import defaultdict
+        by_day: defaultdict[int, int] = defaultdict(int)
+        for s in states:
+            d = s.days_until_due
+            if 0 <= d <= days:
+                by_day[d] += 1
+            elif d < 0:
+                by_day[0] += 1
+        total_due = sum(by_day.values())
+        return {
+            "window_days": days,
+            "total_due": total_due,
+            "daily_avg": round(total_due / days, 1),
+            "by_day": dict(sorted(by_day.items())),
+            "overdue": sum(1 for s in states if s.is_due),
+        }

package/python/foxclaw/mcp_server.py

@@ -0,0 +1,188 @@
+"""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="/")
+    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"}]
+
+    @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)
+                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,167 @@
+"""
+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 = ""
+    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
+        self._auditor = auditor
+        self.request_log: deque = deque(maxlen=1000)
+
+    @property
+    def agents(self) -> dict:
+        """按名字从注册中枢解析 agents(id -> agent 实例)。"""
+        return self._caps.get("agents") or {}
+
+    def gather_situation(self) -> GlobalSituation:
+        """通用聚合各 Agent 自报的领域态势(agent.situation()),形成驾驶舱视图。
+        编排层不再直接读 finance/learning/itinerary 内核——领域知识已归属各领域 Agent。"""
+        sit = GlobalSituation()
+        alerts: list[dict] = []
+        for agent in self.agents.values():
+            try:
+                s = agent.situation()
+            except Exception:
+                continue
+            if not s:
+                continue
+            doms = s.get("domains")
+            if isinstance(doms, dict) and doms:
+                for d, st in doms.items():
+                    if d and hasattr(sit, d):
+                        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
+
+    def route_request(self, req: CrossAgentRequest) -> CrossAgentRequest:
+        """把请求路由给目标 Agent,由**目标 Agent**用自己的守门人裁决(编排层不懂领域)。"""
+        target = self.agents.get(req.to_agent)
+        if target is None:
+            req.status = "needs_confirmation"
+            req.verdict = f"目标 Agent '{req.to_agent}' 不存在,无法裁决,转人工确认"
+        else:
+            try:
+                target.handle_cross_request(req)
+            except Exception as e:
+                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",
+]