foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/skills/lifecycle.py

@@ -0,0 +1,252 @@
+"""
+横切机制:断路器 + 生命周期钩子 —— AHS FRAMEWORK.md 的代码落地。
+
+  CircuitBreaker  每个 skill 独立计数,连续失败 N 次 → OPEN → 停止重试 → 降级
+  HookManager     pre_skill/post_skill/on_error/session_start/session_end +
+                  agent_start(别名 pre_reasoning,可注入 additionalContext)/
+                  agent_end(别名 task_complete,只读)——认知管线 run_task 触发(E2)
+                  超时受限、容错、可审计;hook 是顾问不是控制器
+                  (例外:pre_skill 显式返回 deny 可阻断)
+
+对应 docs/internal/HARNESS_STANDARD.md 第二期(稳健性)。
+"""
+from __future__ import annotations
+import time
+import fnmatch
+import threading
+from collections import deque
+from dataclasses import dataclass
+from typing import Callable, Optional, Literal
+
+from .hooks_spec import HookEvent
+
+
+CircuitState = Literal["closed", "open", "half_open"]
+
+
+@dataclass
+class _BreakerEntry:
+    failures: int = 0
+    state: CircuitState = "closed"
+    opened_at: float = 0.0
+    probe_in_flight: bool = False
+    probe_started_at: float = 0.0
+    probe_successes: int = 0
+
+
+class CircuitBreaker:
+    """每个 skill 独立的断路器。标准三态机:closed / open / half_open。
+
+    - closed:正常放行。连续失败 ≥ threshold → 转 open
+    - open:停止调用。冷却 cooldown 秒后 → 转 half_open
+    - half_open:只放行 ONE 个探针请求(其余仍拒绝);
+        探针成功累计达 recovery_threshold → 转 closed(恢复);
+        任一探针失败 → 转回 open,重新计冷却
+    """
+
+    def __init__(self, threshold: int = 3, cooldown: float = 30.0,
+                 recovery_threshold: int = 1, probe_timeout: float = 60.0):
+        self.threshold = threshold
+        self.cooldown = cooldown
+        self.recovery_threshold = max(1, recovery_threshold)
+        self.probe_timeout = probe_timeout
+        self._entries: dict[str, _BreakerEntry] = {}
+        self._lock = threading.RLock()
+
+    def _get(self, sid: str) -> _BreakerEntry:
+        if sid not in self._entries:
+            self._entries[sid] = _BreakerEntry()
+        return self._entries[sid]
+
+    def allow(self, sid: str) -> bool:
+        """该 skill 现在是否允许调用。
+
+        closed → True;open(冷却中)→ False;
+        open(冷却满)→ 转 half_open 并放行这一个探针;
+        half_open → 仅当没有探针在飞时放行一个,否则 False。
+        """
+        with self._lock:
+            e = self._get(sid)
+            if e.state == "closed":
+                return True
+            if e.state == "open":
+                if time.time() - e.opened_at >= self.cooldown:
+                    e.state = "half_open"
+                    e.probe_in_flight = True
+                    e.probe_started_at = time.time()
+                    e.probe_successes = 0
+                    return True
+                return False
+            if e.state == "half_open":
+                if e.probe_in_flight:
+                    if time.time() - e.probe_started_at >= self.probe_timeout:
+                        e.probe_in_flight = False
+                    else:
+                        return False
+                e.probe_in_flight = True
+                e.probe_started_at = time.time()
+                return True
+            return False
+
+    def record_success(self, sid: str):
+        with self._lock:
+            e = self._get(sid)
+            if e.state == "half_open":
+                e.probe_in_flight = False
+                e.probe_successes += 1
+                if e.probe_successes >= self.recovery_threshold:
+                    e.state = "closed"
+                    e.failures = 0
+                    e.probe_successes = 0
+            else:
+                e.failures = 0
+                e.state = "closed"
+
+    def record_failure(self, sid: str):
+        with self._lock:
+            e = self._get(sid)
+            if e.state == "half_open":
+                e.state = "open"
+                e.opened_at = time.time()
+                e.probe_in_flight = False
+                e.probe_successes = 0
+                return
+            e.failures += 1
+            if e.failures >= self.threshold:
+                e.state = "open"
+                e.opened_at = time.time()
+
+    def status(self, sid: str) -> dict:
+        with self._lock:
+            e = self._get(sid)
+            state = e.state
+            if e.state == "open" and time.time() - e.opened_at >= self.cooldown:
+                state = "half_open"
+            return {"state": state, "failures": e.failures,
+                    "threshold": self.threshold,
+                    "probe_successes": e.probe_successes,
+                    "recovery_threshold": self.recovery_threshold}
+
+    def is_open(self, sid: str) -> bool:
+        """只读查询:该 skill 当前是否处于「阻止调用」状态。
+
+        【P4-0】原实现写的是 `state == "open" and not self.allow(sid)` —— 但 allow() 在
+        「open 且冷却已满」时会**副作用性地**转入 half_open 并占掉唯一的探针名额。于是
+        「只想看一眼断路器开着没」的监控代码会意外消耗掉恢复探测机会,把真正该放行的探针
+        挡在外面。这里改成纯读,不做任何状态迁移。
+
+        语义:open 且冷却未满 → 阻止;open 且冷却已满 → 视作「下次调用会被放行」,不计为打开;
+        half_open 仅当探针在飞且未超时时计入。
+        """
+        with self._lock:
+            e = self._get(sid)
+            if e.state == "open":
+                return (time.time() - e.opened_at) < self.cooldown
+            if e.state == "half_open":
+                return e.probe_in_flight and (time.time() - e.probe_started_at) < self.probe_timeout
+            return False
+
+
+@dataclass
+class Hook:
+    event: HookEvent
+    matcher: str
+    handler: Callable
+    name: str = ""
+
+    def matches(self, skill_id: str) -> bool:
+        return fnmatch.fnmatch(skill_id or "", self.matcher)
+
+
+@dataclass
+class HookResult:
+    blocked: bool = False
+    reason: str = ""
+    modified_args: Optional[dict] = None
+    additional_context: Optional[str] = None
+
+
+class HookManager:
+    """生命周期钩子管理。钩子超时受限、容错、可审计。
+
+    规则(对齐 FRAMEWORK.md):
+    - 超时受限:单个 hook 超过 timeout 视为出错(不阻塞链路)
+    - 容错:hook 失败不中断 skill 链(顾问不是控制器)
+    - 例外:pre_skill 显式返回 {block:True} 可阻断(这是它被授予的权力)
+    - 可审计:每次 hook 执行记录到 audit_log
+    """
+
+    def __init__(self, timeout: float = 10.0, audit_limit: int = 2000):
+        self.timeout = timeout
+        self._hooks: list[Hook] = []
+        self.audit_log: deque = deque(maxlen=max(100, audit_limit))
+
+    def register(self, event: HookEvent, handler: Callable,
+                 matcher: str = "*", name: str = ""):
+        from .hooks_spec import normalize_hook, is_valid_hook
+        norm = normalize_hook(event)
+        if not is_valid_hook(norm):
+            self.audit_log.append({
+                "event": event, "hook": name or getattr(handler, "__name__", "?"),
+                "matcher": matcher, "duration_ms": 0, "timed_out": False,
+                "error": f"未知钩子点「{event}」,该钩子永不触发(请检查拼写)",
+            })
+        self._hooks.append(Hook(norm, matcher, handler, name or handler.__name__))
+
+    def _run_one(self, hook: Hook, ctx: dict) -> dict:
+        """执行单个 hook,计时 + 容错。返回 hook 的返回值(dict)或 {}。"""
+        t0 = time.time()
+        outcome, err = {}, None
+        try:
+            ret = hook.handler(ctx)
+            if isinstance(ret, dict):
+                outcome = ret
+        except Exception as e:
+            err = str(e)
+        dt = time.time() - t0
+        timed_out = dt > self.timeout
+        self.audit_log.append({
+            "event": hook.event, "hook": hook.name, "matcher": hook.matcher,
+            "duration_ms": round(dt * 1000, 1), "timed_out": timed_out,
+            "error": err,
+        })
+        return {} if err else outcome
+
+    def fire(self, event: HookEvent, skill_id: str = "", ctx: dict | None = None) -> HookResult:
+        """触发某事件的所有匹配 hook。仅 before_tool_call(原 pre_skill)的 block 生效;
+        CONTEXT_HOOKS(pre_reasoning/agent_start)返回的 additional_context 会被收集拼接。
+
+        【P4-3】⚠ ctx 是**浅拷贝**(dict(...)),不是深拷贝。hook 不得原地修改 ctx 里的嵌套
+        dict(如 ctx["args"]["x"])——那会连带改掉调用方的原对象。要改参数请用返回值
+        `{"modified_args": {...}}` 整块替换(仅 before_tool_call 生效)。此处刻意不做 deepcopy,
+        以免每次工具调用都付深拷贝开销;约束靠本注释 + 钩子约定维持。
+        """
+        from .hooks_spec import (normalize_hook, BLOCKING_HOOKS, TOOL_SCOPED_HOOKS,
+                                 CONTEXT_HOOKS)
+        event = normalize_hook(event)
+        ctx = dict(ctx or {}, event=event, skill_id=skill_id)
+        result = HookResult()
+        ctx_parts = []
+        for hook in self._hooks:
+            if hook.event != event:
+                continue
+            if event in TOOL_SCOPED_HOOKS and not hook.matches(skill_id):
+                continue
+            out = self._run_one(hook, ctx)
+            if event in BLOCKING_HOOKS:
+                if out.get("block"):
+                    result.blocked = True
+                    result.reason = out.get("reason", f"被 {event} 钩子阻断")
+                    return result
+                if out.get("modified_args") is not None:
+                    result.modified_args = out["modified_args"]
+            if event in CONTEXT_HOOKS:
+                inj = out.get("additional_context") or out.get("additionalContext")
+                if inj:
+                    ctx_parts.append(str(inj))
+        if ctx_parts:
+            result.additional_context = "\n".join(ctx_parts)
+        return result
+
+    def recent_audit(self, n: int = 20) -> list:
+        return list(self.audit_log)[-n:]

package/python/foxclaw/skills/markdown_skill.py

@@ -0,0 +1,175 @@
+"""SKILL.md 指令技能:注入 Agent 提示词的 markdown 指令(非可调用工具)。无代码执行。"""
+from __future__ import annotations
+import re
+import threading
+from dataclasses import dataclass, field, asdict
+import yaml
+from typing import Any
+
+
+@dataclass
+class MarkdownSkill:
+    id: str
+    name: str
+    description: str
+    triggers: list = field(default_factory=list)
+    body: str = ""
+    enabled: bool = True
+    source: str = "user"
+    version: str = ""
+    builtin: bool = False
+
+    def to_dict(self) -> dict:
+        d = asdict(self); d["trust"] = "low"; return d
+
+    def to_meta(self) -> dict:
+        d = self.to_dict(); d.pop("body", None); return d
+
+
+def _slug(s: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", (s or "").lower()).strip("_") or "skill"
+
+
+def parse_skill_md(text: str, id: str | None = None) -> MarkdownSkill:
+    """解析 SKILL.md(--- yaml frontmatter --- + 正文)。缺 name/description → ValueError。"""
+    text = (text or "").lstrip("").strip()
+    m = re.match(r"^---\s*\n(.*?)\n---\s*\n?(.*)$", text, re.DOTALL)
+    if not m:
+        raise ValueError("缺少 --- frontmatter ---")
+    try:
+        fm = yaml.safe_load(m.group(1)) or {}
+    except Exception as e:
+        raise ValueError(f"frontmatter 非法 YAML: {e}")
+    if not isinstance(fm, dict):
+        raise ValueError("frontmatter 需为键值对")
+    name = str(fm.get("name") or "").strip()
+    desc = str(fm.get("description") or "").strip()
+    if not name or not desc:
+        raise ValueError("SKILL.md 必须含 name 和 description")
+    trig = fm.get("triggers") or []
+    if isinstance(trig, str):
+        trig = [t.strip() for t in trig.split(",") if t.strip()]
+    trig = [str(t) for t in trig]
+    builtin = bool(fm.get("builtin", False))
+    return MarkdownSkill(id=id or _slug(name), name=name, description=desc,
+                         triggers=trig, body=m.group(2).strip(),
+                         source="builtin" if builtin else "user",
+                         version=str(fm.get("version") or "").strip(),
+                         builtin=builtin)
+
+
+def load_builtin_dir(reg: MarkdownSkillRegistry, root) -> list:
+    """加载随包分发的指令技能:`<root>/<name>/SKILL.md` 中 **frontmatter 标了 builtin: true** 的。
+
+    为什么只认 builtin 标记:仓库 `skills/` 下还有 `execution-contract` 之类的**开发者文档**,
+    全量注入会把每轮 prompt 撑肿。显式标记 = 只把"真给模型执行的指令"注入。
+    用户已安装的同 id 技能优先(不覆盖),内置只是缺省值。
+    """
+    from pathlib import Path
+    loaded: list[Any] = []
+    try:
+        base = Path(root)
+        if not base.is_dir():
+            return loaded
+        for p in sorted(base.glob("*/SKILL.md")):
+            try:
+                s = parse_skill_md(p.read_text(encoding="utf-8", errors="replace"))
+            except Exception:
+                continue
+            if not s.builtin or reg.get(s.id) is not None:
+                continue
+            reg.register(s)
+            loaded.append(s.id)
+    except Exception:
+        pass
+    return loaded
+
+
+class MarkdownSkillRegistry:
+    def __init__(self):
+        self._skills = {}
+        self._lock = threading.RLock()
+        self.policy = None
+
+    def register(self, s: MarkdownSkill):
+        with self._lock:
+            self._skills[s.id] = s
+
+    def unregister(self, sid: str) -> bool:
+        with self._lock:
+            return self._skills.pop(sid, None) is not None
+
+    def get(self, sid: str):
+        with self._lock:
+            return self._skills.get(sid)
+
+    def all(self) -> list:
+        with self._lock:
+            return list(self._skills.values())
+
+    def catalog(self) -> list:
+        return [s.to_meta() for s in self.all()]
+
+    def match(self, task: str) -> list:
+        """有 triggers → 按 triggers(子串);无 triggers(原味 OpenClaw)→ 按 name+description 描述相关。"""
+        t_raw = task or ""
+        t_low = t_raw.lower()
+        out = []
+        pol = self.policy
+        for s in self.all():
+            if not s.enabled:
+                continue
+            if pol is not None and pol.is_blocked(s.id):
+                continue
+            if s.triggers:
+                if any(k.lower() in t_low for k in s.triggers):
+                    out.append(s)
+            elif _desc_relevant(s, t_low, t_raw):
+                out.append(s)
+        return out
+
+
+_ASCII_WORD = re.compile(r"[a-z0-9]{3,}")
+_CJK_RUN = re.compile(r"[一-鿿]{2,}")
+
+
+def _desc_relevant(skill, t_low: str, t_raw: str) -> bool:
+    """无 triggers 时:技能 name+description 与任务是否关键词重叠。
+    ASCII 词按词边界(避免 knowledge⊃now 式误命中);中文按 2-gram 子串。"""
+    blob = f"{skill.name} {skill.description}"
+    for w in set(_ASCII_WORD.findall(blob.lower())):
+        if re.search(rf"\b{re.escape(w)}\b", t_low):
+            return True
+    for run in _CJK_RUN.findall(blob):
+        for i in range(len(run) - 1):
+            if run[i:i + 2] in t_raw:
+                return True
+    return False
+
+
+def extract_skill_package(zip_bytes: bytes, max_uncompressed: int = 2_000_000):
+    """从 OpenClaw 包(zip)按名读取 SKILL.md(+可选 _meta.json)。
+    仅按名 read,不 extractall → 无 zip-slip;累计解压超上限 → 防 zip bomb。
+    返回 (skill_md_text, meta_dict)。找不到 SKILL.md → ValueError。"""
+    import io
+    import json as _json
+    import zipfile
+    try:
+        zf = zipfile.ZipFile(io.BytesIO(zip_bytes))
+    except Exception as e:
+        raise ValueError(f"不是合法 zip: {e}")
+    total = sum(i.file_size for i in zf.infolist())
+    if total > max_uncompressed:
+        raise ValueError(f"解压体积超上限({total} > {max_uncompressed})")
+    skill_name = next((n for n in zf.namelist() if n.lower().endswith("skill.md")), None)
+    if not skill_name:
+        raise ValueError("包内未找到 SKILL.md")
+    skill_md = zf.read(skill_name).decode("utf-8", "replace")
+    meta: dict[str, Any] = {}
+    meta_name = next((n for n in zf.namelist() if n.lower().endswith("_meta.json")), None)
+    if meta_name:
+        try:
+            meta = _json.loads(zf.read(meta_name).decode("utf-8", "replace")) or {}
+        except Exception:
+            meta = {}
+    return skill_md, meta

package/python/foxclaw/skills/markdown_store.py

@@ -0,0 +1,39 @@
+"""SKILL.md 指令技能持久化。<data_dir>/markdown_skills.json。"""
+from __future__ import annotations
+import json
+import threading
+from pathlib import Path
+from dataclasses import fields as _fields
+
+from .markdown_skill import MarkdownSkill, MarkdownSkillRegistry
+
+
+class MarkdownStore:
+    def __init__(self, data_dir):
+        self._path = Path(data_dir) / "markdown_skills.json"
+        self._lock = threading.Lock()
+
+    def load(self, reg: MarkdownSkillRegistry):
+        if not self._path.exists():
+            return
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+        except Exception:
+            return
+        allowed = {f.name for f in _fields(MarkdownSkill)}
+        for d in data.get("skills", []):
+            try:
+                reg.register(MarkdownSkill(**{k: v for k, v in d.items() if k in allowed}))
+            except Exception:
+                continue
+
+    def save(self, reg: MarkdownSkillRegistry):
+        with self._lock:
+            payload = {"skills": [s.to_dict() for s in reg.all()]}
+            try:
+                self._path.parent.mkdir(parents=True, exist_ok=True)
+                tmp = self._path.with_suffix(".tmp")
+                tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=1), encoding="utf-8")
+                tmp.replace(self._path)
+            except Exception:
+                pass

package/python/foxclaw/skills/mcp_client.py

@@ -0,0 +1,184 @@
+"""MCP 连接器(HTTP Streamable/SSE 远程)。mcp SDK 是 async,本模块用后台事件循环线程
+把它桥成同步,供 SkillAdapter(sync,跨请求/后台线程)调用。按需连接:每次开→用→关。
+仅远程传输,无本地代码执行。"""
+from __future__ import annotations
+import asyncio
+import threading
+from contextlib import asynccontextmanager
+
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.client.sse import sse_client
+
+
+class _Bridge:
+    def __init__(self):
+        self._loop = asyncio.new_event_loop()
+        t = threading.Thread(target=self._run, daemon=True, name="mcp-loop")
+        t.start()
+
+    def _run(self):
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def run(self, coro, timeout: float = 35):
+        fut = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        try:
+            return fut.result(timeout=timeout)
+        except BaseException:
+            fut.cancel()
+            raise
+
+
+_bridge = None
+_bridge_lock = threading.Lock()
+
+
+def _get_bridge() -> _Bridge:
+    global _bridge
+    with _bridge_lock:
+        if _bridge is None:
+            _bridge = _Bridge()
+        return _bridge
+
+
+async def _ssrf_request_hook(request):
+    """httpx 请求钩子:对每个即将发出的请求(初始 + 重定向 follow-up)校验 host。
+    堵 redirect-SSRF + DNS 重绑定 + 配置漂移(恶意 server 把你导去内网/云元数据)。"""
+    from .review import _is_internal_host
+    host = (request.url.host or "").lower()
+    if await asyncio.to_thread(_is_internal_host, host):
+        raise RuntimeError(f"MCP 连接被拒:目标解析到内网/本地/元数据地址({host})")
+
+
+def _safe_httpx_factory(headers=None, timeout=None, auth=None):
+    import httpx
+    return httpx.AsyncClient(
+        headers=headers,
+        timeout=timeout if timeout is not None else httpx.Timeout(30.0),
+        auth=auth,
+        follow_redirects=True,
+        event_hooks={"request": [_ssrf_request_hook]},
+    )
+
+
+@asynccontextmanager
+async def _connect(url, headers, transport):
+    if transport == "sse":
+        async with sse_client(url, headers=headers, httpx_client_factory=_safe_httpx_factory) as (read, write):
+            async with ClientSession(read, write) as s:
+                await s.initialize()
+                yield s
+    else:
+        async with streamablehttp_client(url, headers=headers, httpx_client_factory=_safe_httpx_factory) as (read, write, _):
+            async with ClientSession(read, write) as s:
+                await s.initialize()
+                yield s
+
+
+async def _amcp_list_tools(url, headers, transport):
+    async with _connect(url, headers, transport) as s:
+        return list((await s.list_tools()).tools)
+
+
+async def _amcp_call_tool(url, headers, transport, name, args):
+    async with _connect(url, headers, transport) as s:
+        r = await s.call_tool(name, args or {})
+        text = "".join(getattr(c, "text", "") for c in (r.content or []))
+        return {"isError": bool(getattr(r, "isError", False)), "content": text,
+                "structured": getattr(r, "structuredContent", None)}
+
+
+def _norm(cfg: dict) -> dict:
+    return {"id": cfg["id"], "name": cfg.get("name") or cfg["id"], "url": cfg["url"],
+            "headers": dict(cfg.get("headers") or {}),
+            "transport": cfg.get("transport") or "streamable_http"}
+
+
+def _get(tool, key, default=None):
+    """兼容 dict(守门人序列化后) 与 mcp.types.Tool 对象(直连回退路径)。"""
+    return tool.get(key, default) if isinstance(tool, dict) else getattr(tool, key, default)
+
+
+def tool_to_spec(server_id: str, tool):
+    from . import SideEffect, SkillSpec
+    ann = _get(tool, "annotations", None)
+    if isinstance(ann, dict):
+        ro = ann.get("readOnlyHint")
+        de = ann.get("destructiveHint")
+    else:
+        ro = getattr(ann, "readOnlyHint", None) if ann else None
+        de = getattr(ann, "destructiveHint", None) if ann else None
+    se: SideEffect
+    if ro is True:
+        se, destr = "read", False
+    elif de is True:
+        se, destr = "write", True
+    else:
+        se, destr = "write", False
+    tname = _get(tool, "name", "") or ""
+    return SkillSpec(
+        id=f"mcp__{server_id}__{tname}", name=tname,
+        description=_get(tool, "description", "") or "", kind="mcp",
+        mcp_server=server_id, mcp_tool=tname, side_effect=se, destructive=destr,
+        external=True, params=_get(tool, "inputSchema", {}) or {},
+        triggers=[tname], source="user",
+    )
+
+
+class _ClientProxy:
+    def __init__(self, mgr, sid):
+        self._mgr, self._sid = mgr, sid
+
+    def call_tool(self, tool, args):
+        cfg = self._mgr._servers.get(self._sid)
+        if not cfg:
+            raise RuntimeError(f"MCP server {self._sid} 未登记")
+        from foxclaw.core.tracing import span as _span, current_traceparent
+        with _span("mcp.call_tool", server=self._sid, tool=str(tool)):
+            headers = dict(cfg["headers"] or {})
+            tp = current_traceparent()
+            if tp:
+                headers["traceparent"] = tp
+            out = _get_bridge().run(_amcp_call_tool(cfg["url"], headers, cfg["transport"], tool, args or {}))
+        if out.get("isError"):
+            raise RuntimeError(out.get("content") or "MCP 工具返回错误")
+        return out
+
+
+class McpManager:
+    """服务器配置 + 连接。实现 .get(id) 供 SkillAdapter.mcp_clients 用。"""
+    def __init__(self):
+        self._servers: dict = {}
+        self._lock = threading.RLock()
+
+    def restore(self, cfg: dict):
+        with self._lock:
+            self._servers[cfg["id"]] = _norm(cfg)
+
+    def add_server(self, cfg: dict):
+        c = _norm(cfg)
+        tools = _get_bridge().run(_amcp_list_tools(c["url"], c["headers"], c["transport"]))
+        with self._lock:
+            self._servers[c["id"]] = c
+        return tools
+
+    def list_tools(self, sid: str):
+        with self._lock:
+            c = self._servers.get(sid)
+        if not c:
+            raise KeyError(sid)
+        return _get_bridge().run(_amcp_list_tools(c["url"], c["headers"], c["transport"]))
+
+    def remove_server(self, sid: str) -> bool:
+        with self._lock:
+            return self._servers.pop(sid, None) is not None
+
+    def servers(self) -> list:
+        with self._lock:
+            return [dict(c) for c in self._servers.values()]
+
+    def get(self, sid: str):
+        with self._lock:
+            has = sid in self._servers
+        return _ClientProxy(self, sid) if has else None

package/python/foxclaw/skills/mcp_store.py

@@ -0,0 +1,40 @@
+"""MCP server 配置持久化。文件 <data_dir>/mcp_servers.json。
+
+【P-Muse·第4步·安全边界】守门人模式(FOXCLAW_GUARDIAN=1)下,主进程只把
+非敏感元数据(id/name/url/transport)写进这里,headers 凭证只在守门人进程。
+回退路径(FOXCLAW_GUARDIAN=0,进程内直连)没有守门人保护,headers 会连同配置
+一起落盘——save 检测到 headers 非空时会打印告警,避免"静默落盘凭证"。
+"""
+from __future__ import annotations
+import json
+import sys
+import threading
+from pathlib import Path
+
+
+class McpStore:
+    def __init__(self, data_dir):
+        self._path = Path(data_dir) / "mcp_servers.json"
+        self._lock = threading.Lock()
+
+    def load(self) -> list:
+        if not self._path.exists():
+            return []
+        try:
+            return json.loads(self._path.read_text(encoding="utf-8")).get("servers", [])
+        except Exception:
+            return []
+
+    def save(self, servers: list):
+        with self._lock:
+            try:
+                if any(dict(s.get("headers") or {}) for s in servers):
+                    print("[McpStore] ⚠ 检测到 headers 凭证,将明文落盘到 "
+                          f"{self._path.name}(当前为回退路径/未启用守门人)。",
+                          file=sys.stderr, flush=True)
+                self._path.parent.mkdir(parents=True, exist_ok=True)
+                tmp = self._path.with_suffix(".tmp")
+                tmp.write_text(json.dumps({"servers": servers}, ensure_ascii=False, indent=1), encoding="utf-8")
+                tmp.replace(self._path)
+            except Exception:
+                pass