foxclaw 0.1.0 → 0.1.3

package/python/tests/test_llm_planner.py

@@ -0,0 +1,344 @@
+"""
+LLM 驱动规划器(P0-1)测试 —— 全离线(用 fake router,不触发真实网络)。
+
+覆盖:
+  1. 开关:FOXCLAW_LLM_PLAN / FOXCLAW_LLM_REPLAN 默认关 / 显式开
+  2. build_plan_tool:submit_plan 的 schema 含 agent 枚举 + flow 枚举
+  3. llm_plan 的 fail-safe:不支持 tools / 模型不产出 / args 解析失败 / 空输入 / 抛异常 → None
+  4. llm_plan 正常解析:flow + steps + 依赖 + 非法 agent 兜底 + 单步强制 single
+  5. SupervisorAgent._llm_plan:未开启/不支持/单步 → None;多步 → (Plan, step_routes)
+  6. llm_replan:正常产出修正计划 / 空 steps=放弃 / fail-safe → None
+  7. _dispatch_failed:blocked/failed 失败判定
+  8. _replan_and_redo:失败 → 反思 → 重执行 → 成功(含放弃短路)
+  9. sv_replan stage:无失败/未开启 短路保留原结果
+"""
+import os
+import sys
+from pathlib import Path
+
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.planning.llm_planner import (
+    llm_plan,
+    llm_plan_enabled,
+    llm_replan,
+    replan_enabled,
+    build_plan_tool,
+)
+
+
+class _FakeRouter:
+    """fake ModelRouter:只暴露 llm_plan 依赖的接口。"""
+
+    def __init__(self, is_stub=False, supports=True, result=None):
+        self.is_stub = is_stub
+        self._supports = supports
+        self._result = result
+        self.last_call = None
+
+    def supports_tools(self):
+        return self._supports and not self.is_stub
+
+    def call_tools(self, system, messages, tools, tool_choice="auto",
+                   max_tokens=1024, agent_id=""):
+        self.last_call = {"system": system, "messages": messages,
+                          "tools": tools, "tool_choice": tool_choice}
+        return self._result
+
+
+def _catalog():
+    return {"finance": "财务", "office": "办公", "admin": "行政", "assistant": "助手"}
+
+
+def _plan_args(flow="sequential", steps=()):
+    return {"id": "c1", "name": "submit_plan",
+            "args": {"flow": flow, "steps": list(steps)}}
+
+
+def test_enabled_switch():
+    print("\n【1】开关默认关 / 显式开")
+    os.environ.pop("FOXCLAW_LLM_PLAN", None)
+    assert llm_plan_enabled() is False, "默认必须关(可逆/不改变现有行为)"
+    os.environ["FOXCLAW_LLM_PLAN"] = "1"
+    assert llm_plan_enabled() is True
+    os.environ["FOXCLAW_LLM_PLAN"] = "0"
+    assert llm_plan_enabled() is False
+    os.environ.pop("FOXCLAW_LLM_PLAN", None)
+    print("  ✓ 默认关 / '1'开 / '0'关")
+
+
+def test_build_plan_tool_schema():
+    print("\n【2】submit_plan schema:agent 枚举约束")
+    tool = build_plan_tool(_catalog())
+    fn = tool["function"]
+    assert tool["type"] == "function"
+    assert fn["name"] == "submit_plan"
+    agent_enum = fn["parameters"]["properties"]["steps"]["items"]["properties"]["agent"]["enum"]
+    assert set(agent_enum) == {"finance", "office", "admin", "assistant"}, agent_enum
+    flow_enum = fn["parameters"]["properties"]["flow"]["enum"]
+    assert set(flow_enum) == {"single", "sequential", "parallel"}
+    print("  ✓ schema 含 agent 枚举 + flow 枚举")
+
+
+def test_llm_plan_failsafe():
+    print("\n【3】fail-safe:不支持/不产出/解析失败/空输入/抛异常 → None")
+    r = _FakeRouter(result={"supported": False})
+    assert llm_plan(r, "任务", _catalog()) is None
+    r2 = _FakeRouter(result={"supported": True, "tool_calls": []})
+    assert llm_plan(r2, "任务", _catalog()) is None
+    r3 = _FakeRouter(result={"supported": True, "tool_calls": [
+        {"id": "c1", "name": "submit_plan", "args": {}, "args_parse_failed": True}]})
+    assert llm_plan(r3, "任务", _catalog()) is None
+    assert llm_plan(r2, "任务", {}) is None
+    assert llm_plan(r2, "", _catalog()) is None
+
+    class _Boom:
+        def call_tools(self, *a, **k):
+            raise RuntimeError("boom")
+
+    assert llm_plan(_Boom(), "任务", _catalog()) is None
+    print("  ✓ 6 条 fail-safe 路径全部回退 None")
+
+
+def test_llm_plan_parse():
+    print("\n【4】正常解析:flow + steps + 依赖 + 非法 agent 兜底")
+    r = _FakeRouter(result={"supported": True, "tool_calls": [
+        _plan_args("sequential", [
+            {"name": "查支出", "agent": "finance", "depends_on": []},
+            {"name": "定预算", "agent": "finance", "depends_on": [0]},
+            {"name": "发邮件", "agent": "office", "depends_on": [1]},
+        ])]})
+    out = llm_plan(r, "查支出再定预算再发邮件", _catalog())
+    assert out["flow"] == "sequential"
+    assert [s["name"] for s in out["steps"]] == ["查支出", "定预算", "发邮件"]
+    assert [s["agent"] for s in out["steps"]] == ["finance", "finance", "office"]
+    assert out["steps"][1]["depends_on"] == [0]
+
+    r2 = _FakeRouter(result={"supported": True, "tool_calls": [
+        _plan_args("parallel", [{"name": "查天气", "agent": "office"}])]})
+    out2 = llm_plan(r2, "查天气", _catalog())
+    assert out2["flow"] == "single" and len(out2["steps"]) == 1
+
+    r3 = _FakeRouter(result={"supported": True, "tool_calls": [
+        _plan_args("single", [{"name": "x", "agent": "不存在的Agent"}])]})
+    out3 = llm_plan(r3, "x", _catalog())
+    assert out3["steps"][0]["agent"] == "office"
+    print("  ✓ 解析 / 单步single / 非法agent兜底 正确")
+
+
+def test_supervisor_llm_plan():
+    print("\n【5】SupervisorAgent._llm_plan:开关 + 路由链路")
+    from foxclaw.agents.agents import SupervisorAgent
+    D = type("D", (), {"AGENT_NAME": "dummy"})
+    sub = {"finance": D(), "office": D()}
+
+    os.environ.pop("FOXCLAW_LLM_PLAN", None)
+    a1 = SupervisorAgent.__new__(SupervisorAgent)
+    a1.router = _FakeRouter(result={"supported": True})
+    a1._subagents = sub
+    assert a1._llm_plan("任务") is None
+
+    os.environ["FOXCLAW_LLM_PLAN"] = "1"
+    a2 = SupervisorAgent.__new__(SupervisorAgent)
+    a2.router = _FakeRouter(result={"supported": True, "tool_calls": [
+        _plan_args("sequential", [
+            {"name": "查支出", "agent": "finance"},
+            {"name": "发邮件", "agent": "office"},
+        ])]})
+    a2._subagents = sub
+    plan, routes = a2._llm_plan("查支出再发邮件")
+    assert plan is not None and plan.flow_type == "sequential"
+    assert len(plan.tasks) == 2
+    assert routes == [("查支出", "finance"), ("发邮件", "office")]
+
+    a3 = SupervisorAgent.__new__(SupervisorAgent)
+    a3.router = _FakeRouter(result={"supported": True, "tool_calls": [
+        _plan_args("single", [{"name": "查天气", "agent": "office"}])]})
+    a3._subagents = sub
+    assert a3._llm_plan("查天气") is None
+
+    a4 = SupervisorAgent.__new__(SupervisorAgent)
+    a4.router = _FakeRouter(is_stub=True)
+    a4._subagents = sub
+    assert a4._llm_plan("任务") is None
+
+    os.environ.pop("FOXCLAW_LLM_PLAN", None)
+    print("  ✓ 开关 / 多步链路 / 单步回退 / 不支持回退 正确")
+
+
+def test_replan_enabled_switch():
+    print("\n【6】反思重规划开关")
+    os.environ.pop("FOXCLAW_LLM_REPLAN", None)
+    assert replan_enabled() is False, "默认必须关(可逆)"
+    os.environ["FOXCLAW_LLM_REPLAN"] = "1"
+    assert replan_enabled() is True
+    os.environ.pop("FOXCLAW_LLM_REPLAN", None)
+    print("  ✓ 默认关 / '1'开")
+
+
+def test_llm_replan_parse():
+    print("\n【7】llm_replan:修正计划 + 空 steps 放弃 + fail-safe")
+    prior = [{"subtask": "查支出", "agent": "finance", "output": "超时", "blocked": True},
+             {"subtask": "发邮件", "agent": "office", "output": "未执行", "blocked": False}]
+    r = _FakeRouter(result={"supported": True, "tool_calls": [
+        _plan_args("sequential", [
+            {"name": "查支出(重试)", "agent": "finance"},
+            {"name": "发邮件", "agent": "office"},
+        ])]})
+    out = llm_replan(r, "查支出再发邮件", prior, _catalog())
+    assert out is not None and [s["agent"] for s in out["steps"]] == ["finance", "office"]
+    r2 = _FakeRouter(result={"supported": True, "tool_calls": [
+        _plan_args("sequential", [])]})
+    out2 = llm_replan(r2, "任务", prior, _catalog())
+    assert out2 is not None and out2["steps"] == []
+    r3 = _FakeRouter(result={"supported": False})
+    assert llm_replan(r3, "任务", prior, _catalog()) is None
+    print("  ✓ 修正计划 / 空steps放弃 / 不支持回退 正确")
+
+
+def test_dispatch_failed():
+    print("\n【8】_dispatch_failed:失败判定")
+    from foxclaw.agents.agents import _dispatch_failed
+    assert _dispatch_failed({"result": {"dispatched_to": "multi", "blocked": True}}) is True
+    assert _dispatch_failed({"result": {"dispatched_to": "parallel",
+        "parallel_steps": [{"failed": True}]}}) is True
+    assert _dispatch_failed({"result": {"dispatched_to": "finance"}}) is False
+    assert _dispatch_failed({"result": {"dispatched_to": "multi", "blocked": False,
+        "multi_steps": [{"blocked": False}]}}) is False
+    assert _dispatch_failed(None) is False
+    print("  ✓ blocked/failed/单Agent/成功/None 判定正确")
+
+
+def test_replan_and_redo():
+    print("\n【9】_replan_and_redo:失败 → 反思 → 重执行 → 成功")
+    import asyncio
+    from foxclaw.agents.agents import SupervisorAgent
+    os.environ["FOXCLAW_LLM_REPLAN"] = "1"
+    D = type("D", (), {"AGENT_NAME": "dummy"})
+    sub = {"finance": D(), "office": D()}
+
+    router = _FakeRouter(result={"supported": True, "tool_calls": [
+        _plan_args("sequential", [
+            {"name": "查支出(重试)", "agent": "finance"},
+            {"name": "发邮件", "agent": "office"},
+        ])]})
+    a = SupervisorAgent.__new__(SupervisorAgent)
+    a.router = router
+    a._subagents = sub
+    a._think = lambda **kw: None
+
+    calls = {"n": 0}
+
+    async def fake_dispatch_multi(task, step_routes, *a2, **kw):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return {"result": {"dispatched_to": "multi", "blocked": True,
+                               "multi_steps": [{"step": 1, "subtask": "查支出",
+                                                "agent": "finance", "output": "超时",
+                                                "blocked": True}]}}
+        return {"result": {"dispatched_to": "multi", "blocked": False,
+                           "multi_steps": [{"step": 1, "subtask": "查支出(重试)",
+                                            "agent": "finance", "output": "支出=1000",
+                                            "blocked": False},
+                                           {"step": 2, "subtask": "发邮件",
+                                            "agent": "assistant", "output": "已发送",
+                                            "blocked": False}]}}
+    a._dispatch_multi = fake_dispatch_multi
+
+    failed_dr = {"result": {"dispatched_to": "multi", "blocked": True,
+                            "multi_steps": [{"step": 1, "subtask": "查支出",
+                                             "agent": "finance", "output": "超时",
+                                             "blocked": True}]}}
+    out = asyncio.run(a._replan_and_redo("查支出再发邮件", None, "sess", sub, {}, [], failed_dr))
+    assert calls["n"] == 2, f"应重执行 1 次,实际 {calls['n']}"
+    assert out["result"]["blocked"] is False
+    os.environ.pop("FOXCLAW_LLM_REPLAN", None)
+    print("  ✓ 失败触发反思 → 重执行 1 次 → 成功")
+
+
+def test_replan_gives_up():
+    print("\n【10】_replan_and_redo:模型放弃 → 不重执行,保留原结果")
+    import asyncio
+    from foxclaw.agents.agents import SupervisorAgent
+    os.environ["FOXCLAW_LLM_REPLAN"] = "1"
+    D = type("D", (), {"AGENT_NAME": "dummy"})
+    sub = {"finance": D(), "assistant": D()}
+
+    router = _FakeRouter(result={"supported": True, "tool_calls": [
+        _plan_args("sequential", [])]})
+    a = SupervisorAgent.__new__(SupervisorAgent)
+    a.router = router
+    a._subagents = sub
+    a._think = lambda **kw: None
+    called = {"n": 0}
+
+    async def fake_dispatch_multi(task, step_routes, *a2, **kw):
+        called["n"] += 1
+        return {"result": {"dispatched_to": "multi", "blocked": False}}
+
+    a._dispatch_multi = fake_dispatch_multi
+    failed_dr = {"result": {"dispatched_to": "multi", "blocked": True,
+                            "multi_steps": [{"step": 1, "subtask": "查支出",
+                                             "agent": "finance", "output": "超时",
+                                             "blocked": True}]}}
+    out = asyncio.run(a._replan_and_redo("查支出", None, "s", sub, {}, [], failed_dr))
+    assert called["n"] == 0, "放弃时不应重执行"
+    assert out is failed_dr, "放弃时保留原结果"
+    os.environ.pop("FOXCLAW_LLM_REPLAN", None)
+    print("  ✓ 放弃短路,保留原结果")
+
+
+def test_sv_replan_stage():
+    print("\n【11】sv_replan stage:短路 + 触发")
+    import asyncio
+    from types import SimpleNamespace
+    from foxclaw.pipeline.supervisor_stages import sv_replan
+
+    a1 = SimpleNamespace(_replan_enabled=lambda: True)
+    ctx1 = SimpleNamespace(extra={}, agent=a1,
+                           dispatch_result={"result": {"dispatched_to": "multi", "blocked": False}})
+    asyncio.run(sv_replan(ctx1))
+    assert ctx1.dispatch_result["result"]["blocked"] is False
+
+    a2 = SimpleNamespace(_replan_enabled=lambda: False)
+    ctx2 = SimpleNamespace(extra={}, agent=a2,
+                           dispatch_result={"result": {"dispatched_to": "multi", "blocked": True}})
+    asyncio.run(sv_replan(ctx2))
+    assert ctx2.dispatch_result["result"]["blocked"] is True
+
+    async def fake_replan(task, sched, session_id, subagents, context, memories, dr, max_rounds=2):
+        return {"result": {"dispatched_to": "multi", "blocked": False}}
+
+    a3 = SimpleNamespace(_replan_enabled=lambda: True, _replan_and_redo=fake_replan)
+    ctx3 = SimpleNamespace(extra={}, agent=a3,
+                           dispatch_result={"result": {"dispatched_to": "multi", "blocked": True}},
+                           task="t", sched=None, session_id="s", context={}, memories=[])
+    asyncio.run(sv_replan(ctx3))
+    assert ctx3.dispatch_result["result"]["blocked"] is False
+
+    print("  ✓ 无失败/未开启短路,触发路径更新结果")
+
+
+def main():
+    print("=" * 60)
+    print("LLM 驱动规划器(P0-1)")
+    print("=" * 60)
+    test_enabled_switch()
+    test_build_plan_tool_schema()
+    test_llm_plan_failsafe()
+    test_llm_plan_parse()
+    test_supervisor_llm_plan()
+    test_replan_enabled_switch()
+    test_llm_replan_parse()
+    test_dispatch_failed()
+    test_replan_and_redo()
+    test_replan_gives_up()
+    test_sv_replan_stage()
+    print("\n" + "=" * 60)
+    print("✓ P0-1 验证完成:LLM 规划 + 反思重规划,opt-in + fail-safe,规则拆解 fallback 保留")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_markdown_skills.py

@@ -0,0 +1,62 @@
+"""工具中心第3期 · SKILL.md 指令技能 端到端验证。"""
+import sys, os, tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+def test_markdown_skills():
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    _DATA = tempfile.mkdtemp(prefix="foxclaw_md_")
+    os.environ["FOXCLAW_DATA_DIR"] = _DATA
+
+    from fastapi.testclient import TestClient
+    from foxclaw.api import app
+
+    SKILL = "---\nname: 周报助手\ndescription: 教怎么写周报\ntriggers: 周报, 汇报\n---\n先列本周成果,再列风险,最后列下周计划。"
+
+    with TestClient(app) as c:
+        print("=" * 60); print("工具中心 · SKILL.md 指令技能 验证"); print("=" * 60)
+
+        r = c.post("/api/ahs/md-skills", json={"content": SKILL})
+        assert r.status_code == 409 and r.json()["detail"]["needs_ack"] is True
+        print("[1] 未确认 → 409 needs_ack OK")
+
+        r = c.post("/api/ahs/md-skills", json={"content": SKILL, "acknowledged": True})
+        assert r.status_code == 200, r.text
+        sid = r.json()["skill"]["id"]
+        metas = c.get("/api/ahs/md-skills").json()["skills"]
+        assert any(s["id"] == sid for s in metas)
+        assert all("body" not in s for s in metas)
+        print("[2] 上传(ack)+列表(不含body) OK")
+
+        r = c.get(f"/api/ahs/md-skills/{sid}")
+        assert r.status_code == 200 and "成果" in r.json()["body"]
+        print("[3] 查看含 body OK")
+
+        r = c.post("/api/ahs/md-skills", json={"content": "---\ndescription: x\n---\nbody", "acknowledged": True})
+        assert r.status_code == 400
+        print("[4] 缺 name → 400 OK")
+
+        assert c.patch(f"/api/ahs/md-skills/{sid}", json={"enabled": False}).json()["skill"]["enabled"] is False
+        assert c.patch(f"/api/ahs/md-skills/{sid}", json={"enabled": True}).status_code == 200
+        print("[5] 启停 OK")
+
+    from foxclaw import Foxclaw
+    os2 = Foxclaw(data_dir=_DATA)
+    assert os2.md_skills.get(sid) is not None, "重启后指令技能丢失(持久化)"
+    ag = os2.supervisor
+    out = ag._skill_augment("帮我写周报", [{"role": "user", "content": "帮我写周报"}])
+    assert "先列本周成果" in out[-1]["content"] and "帮我写周报" in out[-1]["content"]
+    assert sum(1 for i in range(len(out) - 1) if out[i]["role"] == out[i + 1]["role"] == "user") == 0
+    out2 = ag._skill_augment("订机票", [{"role": "user", "content": "订机票"}])
+    assert out2[0]["content"] == "订机票"
+    print("[6] 注入命中/未命中 + 持久化 round-trip OK")
+
+    with TestClient(app) as c:
+        assert c.delete(f"/api/ahs/md-skills/{sid}").status_code == 200
+        assert not any(s["id"] == sid for s in c.get("/api/ahs/md-skills").json()["skills"])
+    print("[7] 删除 OK")
+
+    print("\nSKILL.md 指令技能验证全部通过")
+
+if __name__ == "__main__":
+    test_markdown_skills()

package/python/tests/test_markdown_skills_openclaw.py

@@ -0,0 +1,66 @@
+"""工具中心第3期 · SKILL.md 指令技能 · OpenClaw 兼容段(原 test_markdown_skills [8]-[12])。
+
+独立成文件的原因:原文件单进程内 3×TestClient lifespan + 4×Foxclaw 实例 +
+两个不同 ST 模型共存,第三次 lifespan 预热阶段 torch/FAISS 必现 0xC0000005
+进程崩溃(git stash 基线对照实锤,与业务改动无关——原生库析构/重入问题)。
+进程隔离后两段各自全绿。本段自包含:不依赖前半段的 sid,自带 _DATA。
+"""
+import sys, os, tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+def test_markdown_skills_openclaw():
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    _DATA = tempfile.mkdtemp(prefix="foxclaw_oc_")
+    os.environ["FOXCLAW_DATA_DIR"] = _DATA
+
+    from fastapi.testclient import TestClient
+    from foxclaw.api import app
+
+    NO_TRIG = "---\nname: skill-vetter\nversion: 1.0.0\ndescription: Security-first skill vetting. Use before installing any skill from ClawdHub or GitHub.\n---\nCheck red flags before install."
+    with TestClient(app) as c:
+        r = c.post("/api/ahs/md-skills", json={"content": NO_TRIG, "id": "skill_vetter", "acknowledged": True})
+        assert r.status_code == 200, r.text
+        assert r.json()["skill"]["version"] == "1.0.0"
+    print("[8] 无 triggers 的 OpenClaw 技能(单.md)安装 OK")
+
+    import io as _io, zipfile as _zip, json as _json, base64 as _b64
+    _buf = _io.BytesIO()
+    with _zip.ZipFile(_buf, "w") as z:
+        z.writestr("SKILL.md", NO_TRIG)
+        z.writestr("_meta.json", _json.dumps({"slug": "skill-vetter-zip", "version": "1.0.0"}))
+    _pkg = _b64.b64encode(_buf.getvalue()).decode()
+    with TestClient(app) as c:
+        r = c.post("/api/ahs/md-skills", json={"package_b64": _pkg, "acknowledged": True})
+        assert r.status_code == 200, r.text
+        assert r.json()["skill"]["id"] == "skill-vetter-zip" and r.json()["skill"]["version"] == "1.0.0"
+        print("[9] OpenClaw zip 包上传(slug→id,version) OK")
+        _b2 = _io.BytesIO()
+        with _zip.ZipFile(_b2, "w") as z: z.writestr("readme.txt", "hi")
+        r = c.post("/api/ahs/md-skills", json={"package_b64": _b64.b64encode(_b2.getvalue()).decode(), "acknowledged": True})
+        assert r.status_code == 400
+        print("[10] zip 无 SKILL.md → 400 OK")
+
+    from foxclaw import Foxclaw
+    os3 = Foxclaw(data_dir=_DATA)
+    assert os3.md_skills.get("skill-vetter-zip") is not None
+    ag3 = os3.supervisor
+    hit = ag3._skill_augment("please vet this skill before install", [{"role": "user", "content": "please vet this skill before install"}])
+    assert "Check red flags" in hit[-1]["content"]
+    miss = ag3._skill_augment("订一张机票", [{"role": "user", "content": "订一张机票"}])
+    assert miss[0]["content"] == "订一张机票"
+    print("[11] 无 triggers 描述相关注入 + 持久化 OK")
+
+    with TestClient(app) as c:
+        r = c.patch("/api/ahs/md-skills/skill-vetter-zip", json={"triggers": ["审核", "搜索"]})
+        assert r.status_code == 200 and r.json()["skill"]["triggers"] == ["审核", "搜索"], r.text
+    os4 = Foxclaw(data_dir=_DATA)
+    ag4 = os4.supervisor
+    hit = ag4._skill_augment("帮我审核这个技能", [{"role": "user", "content": "帮我审核这个技能"}])
+    assert "Check red flags" in hit[-1]["content"]
+    print("[12] 编辑触发词 → 中文任务触发 OK")
+
+    print("\nOpenClaw 兼容验证全部通过")
+
+if __name__ == "__main__":
+    test_markdown_skills_openclaw()

package/python/tests/test_mcp_connectors.py

@@ -0,0 +1,97 @@
+"""工具中心第2期 · MCP 连接器 端到端验证(monkeypatch async 助手,不联网)。"""
+import sys, os, tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+def test_mcp_connectors():
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    os.environ["FOXCLAW_SKIP_DOTENV"] = "1"
+    os.environ["HF_HUB_OFFLINE"] = "1"
+    os.environ["TRANSFORMERS_OFFLINE"] = "1"
+    _DATA = tempfile.mkdtemp(prefix="foxclaw_mcp_")
+    os.environ["FOXCLAW_DATA_DIR"] = _DATA
+
+    from fastapi.testclient import TestClient
+    from foxclaw.api import app
+    import foxclaw.skills.mcp_client as mc
+    from types import SimpleNamespace as NS
+
+    import asyncio as _aio
+    _blocked = False
+    try:
+        _aio.run(mc._amcp_list_tools("http://127.0.0.1:9/mcp", {}, "streamable_http"))
+    except BaseException as _e:
+        _s = str(_e) + repr(getattr(_e, "exceptions", ""))
+        _blocked = ("内网" in _s) or ("127.0.0.1" in _s) or ("拒" in _s)
+    assert _blocked, "客户端 SSRF 钩子未拦截内网连接"
+    print("[SSRF] 客户端连内网被请求钩子拦截 OK")
+
+    FAKE_TOOLS = [
+        NS(name="get_time", description="读时间", inputSchema={}, annotations=NS(readOnlyHint=True, destructiveHint=None)),
+        NS(name="do_thing", description="干活", inputSchema={}, annotations=None),
+    ]
+    async def fake_list(url, headers, transport): return list(FAKE_TOOLS)
+    async def fake_call(url, headers, transport, name, args): return {"isError": False, "content": "ok:" + name, "structured": None}
+    mc._amcp_list_tools = fake_list
+    mc._amcp_call_tool = fake_call
+
+    SRV = {"id": "demo_srv", "name": "演示", "url": "https://mcp.example.com/mcp", "acknowledged": True}
+
+    with TestClient(app) as c:
+        print("=" * 60); print("工具中心 · MCP 连接器 验证"); print("=" * 60)
+
+        r = c.post("/api/ahs/mcp/servers", json=SRV)
+        assert r.status_code == 200, r.text
+        assert r.json()["tools_registered"] == 2
+        print("[1] 加服务器 + 注册 2 工具 OK")
+
+        skills = {s["id"]: s for s in c.get("/api/ahs/skills").json()["skills"]}
+        assert skills["mcp__demo_srv__get_time"]["side_effect"] == "read"
+        assert skills["mcp__demo_srv__do_thing"]["side_effect"] == "write"
+        print("[2] 工具成技能 + fail-closed(read/write) OK")
+
+        srvs = c.get("/api/ahs/mcp/servers").json()["servers"]
+        assert srvs and srvs[0]["tool_count"] == 2
+        print("[3] 服务器列表 tool_count=2 OK")
+
+        r = c.post("/api/ahs/mcp/servers", json={"id": "bad", "url": "http://127.0.0.1/mcp"})
+        assert r.status_code == 403, r.text
+        print("[4] 审核门 deny 内网(403) OK")
+
+        r = c.post("/api/ahs/mcp/servers", json={"id": "p2", "url": "https://mcp2.example.com/mcp"})
+        assert r.status_code == 409 and r.json()["detail"]["needs_ack"] is True
+        print("[5] 外部低信任需确认(409) OK")
+
+        r = c.post("/api/ahs/skills/mcp__demo_srv__get_time/test", json={"args": {}})
+        assert r.json()["status"] == "needs_confirmation", r.text
+        r = c.post("/api/ahs/skills/mcp__demo_srv__get_time/test", json={"args": {}, "confirmed": True})
+        j = r.json()
+        assert r.status_code == 200 and j["success"] is True, r.text
+        out = j["output"]
+        assert out.get("_untrusted") is True, out
+        assert "不可信" in out.get("data", {}).get("content", ""), out
+        print("[6] 测试调用 mcp 技能 + 双层 untrusted 标记(防提示注入) OK")
+
+        async def boom(url, headers, transport): raise RuntimeError("connrefused")
+        mc._amcp_list_tools = boom
+        r = c.post("/api/ahs/mcp/servers", json={"id": "err_srv", "url": "https://mcp3.example.com/mcp", "acknowledged": True})
+        assert r.status_code == 502, r.text
+        mc._amcp_list_tools = fake_list
+        print("[7] 连接失败 502 OK")
+
+        assert c.delete("/api/ahs/mcp/servers/demo_srv").status_code == 200
+        assert "mcp__demo_srv__get_time" not in {s["id"] for s in c.get("/api/ahs/skills").json()["skills"]}
+        print("[8] 移除服务器 + 技能消失 OK")
+
+    with TestClient(app) as c:
+        c.post("/api/ahs/mcp/servers", json=SRV)
+    from foxclaw import Foxclaw
+    os2 = Foxclaw(data_dir=_DATA)
+    assert any(s["id"] == "demo_srv" for s in os2.mcp_manager.servers()), "server 未持久化"
+    assert os2.skill_registry.get("mcp__demo_srv__get_time") is not None, "mcp 技能未持久化"
+    print("[9] 重启后 server + mcp 技能仍在(持久化 round-trip) OK")
+
+    print("\nMCP 连接器验证全部通过")
+
+if __name__ == "__main__":
+    test_mcp_connectors()

package/python/tests/test_mcp_guardian_discovery.py

@@ -0,0 +1,87 @@
+"""第4步 · MCP 发现阶段进守门人:主进程(内存+磁盘)不碰 headers 凭证。"""
+import sys, os, tempfile
+from pathlib import Path
+from types import SimpleNamespace as NS
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+def test_mcp_guardian_discovery():
+    os.environ["FOXCLAW_SKIP_DOTENV"] = "1"
+    os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_mcp_guardian_")
+
+    from foxclaw.skills.mcp_client import tool_to_spec
+    spec = tool_to_spec("srv", {"name": "get_time", "description": "读时间", "inputSchema": {},
+                                "annotations": {"readOnlyHint": True, "destructiveHint": None}})
+    assert spec.id == "mcp__srv__get_time" and spec.side_effect == "read" and not spec.destructive
+    spec2 = tool_to_spec("srv", {"name": "do_thing", "description": "", "inputSchema": {},
+                                 "annotations": None})
+    assert spec2.side_effect == "write"
+    print("[1] tool_to_spec 兼容 dict + fail-closed OK")
+
+    import foxclaw.kernel.sentinel as sm
+    servers = {}
+    sm._handle_mcp_register({"servers": [
+        {"id": "a", "name": "a", "url": "https://a", "headers": {"Authorization": "Bearer SECRET"},
+         "transport": "streamable_http"}]}, servers)
+    assert servers["a"]["headers"]["Authorization"] == "Bearer SECRET"
+    sm._handle_mcp_register({"servers": [
+        {"id": "a", "name": "a", "url": "https://a", "transport": "streamable_http"}]}, servers)
+    assert servers["a"]["headers"]["Authorization"] == "Bearer SECRET", "空 headers 不应覆盖守门人已有凭证"
+    print("[2] mcp_register 空 headers 保留旧凭证 OK")
+
+    import foxclaw.skills.mcp_client as mc
+    _seen = {}
+    async def fake_list(url, headers, transport):
+        _seen["headers"] = headers
+        return [NS(name="t1", description="d", inputSchema={},
+                   annotations=NS(readOnlyHint=True, destructiveHint=None))]
+    mc._amcp_list_tools = fake_list
+    out = sm._handle_mcp_list_tools({"server_id": "a"}, servers)
+    assert out["tools"][0]["name"] == "t1"
+    assert out["tools"][0]["annotations"]["readOnlyHint"] is True
+    assert _seen["headers"].get("Authorization") == "Bearer SECRET"
+    print("[3] mcp_list_tools 守门人代发现 + 序列化 + 凭证不出守门人 OK")
+
+    class FakeSentinel:
+        def __init__(self):
+            self.registered = None
+        def mcp_register(self, servers):
+            self.registered = servers
+        def mcp_list_tools(self, sid):
+            return [{"name": "t1", "description": "", "inputSchema": {}, "annotations": None}]
+
+    class FakeMgr:
+        def __init__(self):
+            self._servers = {}
+        def servers(self):
+            return [dict(s) for s in self._servers.values()]
+        def restore(self, cfg):
+            self._servers[cfg["id"]] = cfg
+
+    class FakeStore:
+        def __init__(self):
+            self.saved = None
+        def save(self, servers):
+            self.saved = servers
+
+    class FakeHost:
+        pass
+
+    host = FakeHost()
+    host.sentinel = FakeSentinel()
+    host.mcp_manager = FakeMgr()
+    host.mcp_store = FakeStore()
+
+    from foxclaw import Foxclaw
+    Foxclaw.mcp_add_server_guardian(host, {
+        "id": "srv", "name": "srv", "url": "https://srv",
+        "headers": {"X-Key": "SECRET"}, "transport": "streamable_http"})
+
+    assert "headers" not in host.mcp_manager.servers()[0], "主进程 McpManager 不应存 headers"
+    assert "headers" not in host.mcp_store.saved[0], "主进程磁盘不应存 headers"
+    assert host.sentinel.registered[-1]["headers"]["X-Key"] == "SECRET", "守门人应收到 headers"
+    print("[4] mcp_add_server_guardian:主进程内存/磁盘无 headers,守门人持 headers OK")
+
+    print("\n第4步 · MCP 发现进守门人 验证全部通过")
+
+if __name__ == "__main__":
+    test_mcp_guardian_discovery()