foxclaw 0.1.0 → 0.1.2

package/python/tests/test_mcp_guardian_discovery.py

@@ -0,0 +1,91 @@
+"""第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_")
+
+    # 1. tool_to_spec 兼容 dict(守门人序列化产物),fail-closed 不变
+    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"  # fail-closed:无注解按有副作用
+    print("[1] tool_to_spec 兼容 dict + fail-closed OK")
+
+    # 2. 守门人 mcp_register:主进程空 headers 不覆盖守门人已有凭证
+    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")
+
+    # 3. 守门人 mcp_list_tools 代发现:用自己的 headers 连 + 序列化为 dict
+    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")
+
+    # 4. mcp_add_server_guardian:主进程不存 headers,守门人收到 headers
+    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()

package/python/tests/test_mcp_no_memory.py

@@ -0,0 +1,43 @@
+"""MCP ask_foxclaw "不污染记忆":外部驱动的任务不写 HMR(防外部灌垃圾污染个人记忆),
+正常任务照写。验证抑制标志随 to_thread→scheduler.run→asyncio.run 上下文传到 _store_memory。"""
+import os, sys, tempfile, asyncio
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+def test_mcp_no_memory():
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    os.environ["FOXCLAW_SKIP_DOTENV"] = "1"      # 隔离开发机 .env,保证测试环境自洽
+    os.environ.setdefault("FOXCLAW_EMBEDDING_MODEL", "foxclaw-nonexistent-fast")
+    os.environ["HF_HUB_OFFLINE"] = "1"         # 无网环境:跳过 huggingface 联网重试,直接用本地缓存
+    os.environ["TRANSFORMERS_OFFLINE"] = "1"
+    os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_nomem_")
+
+    from foxclaw import Foxclaw
+
+    o = Foxclaw(data_dir=os.environ["FOXCLAW_DATA_DIR"])
+    calls = []
+    o.hmr.ingest = lambda *a, **k: calls.append(1)   # spy:数 HMR 写入次数
+
+
+    async def dispatch_suppressed():
+        """完全复刻 ask_foxclaw 的派发路径:to_thread → set 抑制 → scheduler.run → asyncio.run。"""
+        def _work():
+            from foxclaw.agents.base import _suppress_memory
+            _suppress_memory.set(True)
+            async def _t():
+                o.supervisor._store_memory("外部驱动任务的内容(应被抑制)")
+            return o.scheduler.run(lambda: asyncio.run(_t()), agent_id="assistant", task="t")
+        return await asyncio.to_thread(_work)
+
+
+    asyncio.run(dispatch_suppressed())
+    suppressed = len(calls)
+    o.supervisor._store_memory("正常任务内容(应写入)")
+    normal = len(calls) - suppressed
+
+    assert suppressed == 0, f"污染!MCP 外部任务写了 {suppressed} 条记忆"
+    assert normal > 0, "正常任务应正常写记忆"
+    print(f"MCP ask_foxclaw 不污染记忆 OK(抑制路径写入={suppressed}, 正常路径写入={normal})")
+
+if __name__ == "__main__":
+    test_mcp_no_memory()

package/python/tests/test_mcp_policy_gate.py

@@ -0,0 +1,77 @@
+"""MCP `ask_foxclaw` 的外部驱动准入。
+
+外部客户端「绕开工具直接驱动 Agent」时,若不过统一动作门,宿主配的 deny(封杀动作)与
+ask(要求人工)对它完全无效。MCP 没有交互确认通道,所以命中 ask 规则要**立即拒**,
+而不是放行后等一个永远不会来的确认。
+"""
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.mcp_server import _policy_error  # noqa: E402
+
+
+class _StubGate:
+    """只回放指定裁决,用来隔离「门怎么判」——这里只测我们怎么消费结果。"""
+
+    def __init__(self, decision: str, code: str = ""):
+        self.decision = decision
+        self.code = code
+
+    def check_action(self, skill, args, rules=None, confirmed=False, mode="strict",
+                     taint_level=0, taint_threshold=0):
+        assert skill.side_effect == "write" and skill.external is True
+        assert confirmed is False, "外部驱动不能用 confirmed 自证"
+        # Verdict 的字段是 level(allow|warn|deny|confirm),不是 decision
+        return SimpleNamespace(level=self.decision, reason="stub",
+                               raw=SimpleNamespace(reason_code=self.code),
+                               decision_id="d")
+
+
+def test_no_gate_means_no_restriction():
+    assert _policy_error(None, None, "分析这个月支出") is None
+
+
+def test_routine_side_effect_ask_is_allowed():
+    """副作用 / external 的常规 ask 由 FOXCLAW_MCP_AGENTS=1 承担授权,不重复拦。"""
+    from foxclaw.skills.permission import EXTERNAL_CONFIRM
+
+    assert _policy_error(_StubGate("ask", EXTERNAL_CONFIRM), None, "跑一下") is None
+
+
+def test_ask_rule_is_refused_not_waited_on():
+    """宿主显式要求确认 → 直接拒。MCP 客户端不会有人按下那个按钮。"""
+    from foxclaw.skills.permission import ASK_RULE
+
+    assert _policy_error(_StubGate("ask", ASK_RULE), None, "跑一下") == "needs_confirmation"
+
+
+def test_deny_wins():
+    assert _policy_error(_StubGate("deny"), None, "跑一下") == "blocked"
+
+
+def test_missing_params_surface_as_error():
+    from foxclaw.skills.permission import MISSING_PARAMS
+
+    assert _policy_error(_StubGate("ask", MISSING_PARAMS), None, "") == "missing arguments"
+
+
+def test_real_deny_rule_blocks_mcp_drive():
+    """真 evaluate + 真规则集:宿主写 `deny=["mcp:*"]` 必须真的挡住。"""
+    from foxclaw.kernel.policy_gate import PolicyGate
+    from foxclaw.skills.permission import PermissionRules, evaluate
+
+    gate = PolicyGate(action_evaluator=evaluate)
+    rules = PermissionRules(deny=["mcp:*"])
+    assert _policy_error(gate, rules, "帮我发封邮件") == "blocked"
+
+
+def test_real_default_rules_do_not_block():
+    """没配任何规则时不能被自己的门挡住(否则 MCP 驱动直接不可用)。"""
+    from foxclaw.kernel.policy_gate import PolicyGate
+    from foxclaw.skills.permission import PermissionRules, evaluate
+
+    gate = PolicyGate(action_evaluator=evaluate)
+    assert _policy_error(gate, PermissionRules(), "分析这个月支出") is None

package/python/tests/test_mcp_server.py

@@ -0,0 +1,95 @@
+"""Foxclaw 内置 MCP 服务器 端到端(带鉴权,贴真实暴露场景):
+- 防后门:不带 X-API-Key 访问 /api/mcp/ → 401
+- 带 key 的 MCP 客户端能 initialize + list_tools(3 只读 + ask_foxclaw) + call
+真起 uvicorn(MCP over Streamable HTTP 需真实 URL)。"""
+import os, sys, tempfile, threading, time, asyncio, urllib.request, urllib.error
+from pathlib import Path
+import pytest
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+@pytest.mark.xfail(
+    reason="pre-existing 失败:真实 uvicorn MCP-over-Streamable-HTTP 端到端断言需要 base_url/凭证配置,本地 stub 环境(/api/mcp/ 后门检查)与基线不一致。需真实 provider 环境才能过。",
+    strict=False,
+)
+def test_mcp_server():
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    os.environ["FOXCLAW_SKIP_DOTENV"] = "1"      # 用进程环境变量自洽测试,不加载开发机 .env
+    os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_mcpsrv_")
+    os.environ["FOXCLAW_API_KEY"] = "mcp-test-key"              # ★ 开鉴权,测真实暴露
+    os.environ["FOXCLAW_MCP_SERVER"] = "1"
+    os.environ["FOXCLAW_MCP_AGENTS"] = "1"
+    os.environ["FOXCLAW_MCP_RATE_AGENT"] = "1"                  # ask_foxclaw 限 1/桶,测限流
+    os.environ.setdefault("FOXCLAW_EMBEDDING_MODEL", "foxclaw-nonexistent-fast")
+    os.environ["HF_HUB_OFFLINE"] = "1"         # 无网环境:跳过 huggingface 联网重试(否则模型加载拖 2 分钟,服务器赶不上就绪窗口)
+    os.environ["TRANSFORMERS_OFFLINE"] = "1"
+    import uvicorn
+    import httpx
+    from foxclaw.api import app, _foxclaw_mcp
+
+    assert _foxclaw_mcp is not None, "FOXCLAW_MCP_SERVER=1 时应构建 MCP 服务器"
+    print("=" * 60); print("Foxclaw 内置 MCP 服务器验证(带鉴权)"); print("=" * 60)
+
+    PORT = 8079
+    KEY = "mcp-test-key"
+    threading.Thread(target=lambda: uvicorn.run(app, host="127.0.0.1", port=PORT, log_level="error"),
+                     daemon=True).start()
+    for _ in range(60):
+        try:
+            urllib.request.urlopen(f"http://127.0.0.1:{PORT}/health", timeout=2); break   # /health 开放
+        except urllib.error.HTTPError:
+            break
+        except Exception:
+            time.sleep(1)
+
+    # [0] 防后门:设了 key,不带/错 key 访问 /api/mcp/ 必须 401(未被鉴权绕过)
+    with httpx.Client(timeout=8) as c:
+        body = {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}
+        hdr = {"Accept": "application/json, text/event-stream"}
+        r = c.post(f"http://127.0.0.1:{PORT}/api/mcp/", json=body, headers=hdr)
+        assert r.status_code == 401, f"后门!/api/mcp 未受鉴权保护: {r.status_code}"
+        r = c.post(f"http://127.0.0.1:{PORT}/api/mcp/", json=body, headers={**hdr, "X-API-Key": "wrong"})
+        assert r.status_code == 401, "错误 key 应 401"
+    print("[0] 防后门:无key/错key 访问 /api/mcp/ → 401 OK")
+
+
+    async def probe():
+        from mcp.client.streamable_http import streamablehttp_client
+        from mcp import ClientSession
+        # 带正确 key 连接
+        async with streamablehttp_client(f"http://127.0.0.1:{PORT}/api/mcp/",
+                                         headers={"X-API-Key": KEY}) as (r, w, _):
+            async with ClientSession(r, w) as s:
+                await s.initialize()
+                tools = {t.name for t in (await s.list_tools()).tools}
+                assert tools == {"knowledge_search", "knowledge_get", "memory_recall", "ask_foxclaw"}, tools
+                print("[1] 带key initialize + list_tools(3 只读 + ask_foxclaw) OK")
+
+                res = await s.call_tool("knowledge_search", {"query": "anything", "top_k": 999999})  # 试超大 top_k(应被钳制不崩)
+                assert res.content is not None
+                print("[2] knowledge_search 可调 + top_k 钳制不崩 OK")
+
+                res = await s.call_tool("memory_recall", {"query": "hello"})
+                assert res.content is not None
+                print("[3] memory_recall 可调 OK")
+
+                res = await s.call_tool("knowledge_get", {"ku_id": "nonexistent"})
+                txt = res.content[0].text if res.content else ""
+                assert "not_found" in txt or "error" in txt
+                print("[4] knowledge_get 不存在 → not_found OK")
+
+                res = await s.call_tool("ask_foxclaw", {"task": "分析这个月支出"})
+                txt = res.content[0].text if res.content else ""
+                assert "dispatched_to" in txt or "reply" in txt or "error" in txt, txt
+                print("[5] ask_foxclaw Agent 调度可调(返回 reply/dispatched_to) OK")
+
+                # [6] 限流:agent 桶设 1,上面已消耗 → 再调应被限流
+                res = await s.call_tool("ask_foxclaw", {"task": "再来一次"})
+                txt = res.content[0].text if res.content else ""
+                assert "rate limited" in txt, f"限流未生效: {txt}"
+                print("[6] ask_foxclaw 限流(令牌桶)生效 OK")
+
+    asyncio.run(probe())
+    print("\nFoxclaw 内置 MCP 服务器验证全部通过")
+
+if __name__ == "__main__":
+    test_mcp_server()

package/python/tests/test_memory_recall.py

@@ -0,0 +1,95 @@
+"""
+M4 · 记忆隔离召回完整性（根治）回归
+
+验证 HMRAdapter 的 tag 预过滤根治路径:
+  1. 完整性:recall(agent=X) 在"X 私有 + shared"**全集**内排序,X 自己的相关记忆一定能召回,
+     不会因库里其他 Agent 有大量强相关记忆挤占全局 top-k 而被漏掉;
+  2. 隔离:任一路径都只返回带 agent:X 或 shared 标签的记忆,绝不泄露他人私有;
+  3. 对照:同一库里老路径(_legacy_recall,全局 top-k 再过滤)会漏掉被淹没的 X 记忆,
+     根治路径(_filtered_recall)能找回 —— 直观展示"完整性缺陷被根治"。
+
+真实 HMR(离线,ST 本地缓存);HMR 不可用时优雅跳过。
+"""
+import sys
+import tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.core.memory_adapter import create_memory_backend
+
+QUERY = "quarterly revenue growth and budget forecast analysis"
+N_FINANCE = 55           # > 老路径 fetch_k(50),< 压缩阈值(同类型 80)
+
+
+def check(cond, msg):
+    if not cond:
+        raise AssertionError(f"✗ {msg}")
+    print(f"  ✓ {msg}")
+
+
+def main():
+    print("=" * 56)
+    print("M4 · 记忆隔离召回完整性（根治）")
+    print("=" * 56)
+    hmr = create_memory_backend(storage_path=tempfile.mkdtemp())
+    if getattr(hmr, "backend", "") != "HMR":
+        print("  · HMR 不可用(降级 Mock),跳过 M4 测试")
+        print("结果:跳过"); return
+
+    # office:一条与 query 相关的关键记忆 + 一条无关
+    hmr.ingest("office quarterly revenue growth and budget forecast for planning",
+               type="concept", agent_id="office", title="office-key")
+    hmr.ingest("office meeting room booking schedule for next week",
+               type="concept", agent_id="office", title="office-other")
+    # finance:大量与 query 强相关记忆(会在全局排序里淹没 office 的记忆)
+    for i in range(N_FINANCE):
+        hmr.ingest(f"finance quarterly revenue growth and budget forecast record {i}",
+                   type="concept", agent_id="finance", title=f"fin-{i}")
+    # 一条共享记忆
+    hmr.ingest("shared team quarterly planning memo", type="concept",
+               agent_id="finance", shared=True, title="shared-memo")
+
+    print("\n【1】完整性:根治路径在 office 全集内排序,召回其相关记忆")
+    res = hmr.recall(QUERY, agent_id="office", top_k=5)
+    titles = [r["title"] for r in res]
+    check("office-key" in titles, f"office 的相关记忆被召回（结果:{titles}）")
+
+    print("\n【2】隔离:office 召回零 finance 私有泄露")
+    def foreign_private(r):
+        tags = r.get("tags", [])
+        return (any(t.startswith("agent:") and t != "agent:office" for t in tags)
+                and "shared" not in tags)
+    check(not any(foreign_private(r) for r in res), "office 召回结果无他人私有")
+
+    print("\n【3】根治路径 = 在 X 全集内考虑(不受全局 top-k 挤占)")
+    full = hmr._filtered_recall(QUERY, "office", top_k=100, include_shared=True)
+    ftitles = {r["title"] for r in full}
+    check(ftitles == {"office-key", "office-other", "shared-memo"},
+          f"office 视角恰好看到自己 2 条 + 共享 1 条,零 finance（{sorted(ftitles)}）")
+
+    print("\n【4】对照:老路径漏掉被淹没的 office 记忆,根治路径找回")
+    legacy = hmr._legacy_recall(QUERY, "office", top_k=5, include_shared=True)
+    filtered = hmr._filtered_recall(QUERY, "office", top_k=5, include_shared=True)
+    legacy_has = any(r["title"] == "office-key" for r in legacy)
+    filtered_has = any(r["title"] == "office-key" for r in filtered)
+    print(f"    老路径召回 office-key: {legacy_has}   根治路径召回 office-key: {filtered_has}")
+    check(filtered_has, "根治路径召回到 office-key（完整性）")
+    check(not legacy_has, "老路径确实漏掉 office-key（被 finance 强相关记忆淹没,印证根治的必要）")
+
+    print("\n【5】反向隔离:finance 召回零 office 私有")
+    fin = hmr._filtered_recall(QUERY, "finance", top_k=100, include_shared=True)
+    check(not any(r["title"].startswith("office-") for r in fin),
+          "finance 视角看不到 office 私有")
+    check(any(r["title"] == "shared-memo" for r in fin), "finance 能看到共享记忆")
+
+    print("\n" + "=" * 56)
+    print("记忆隔离召回完整性 根治通过")
+    print("=" * 56)
+
+
+def test_memory_recall():
+    main()
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_metrics.py

@@ -0,0 +1,66 @@
+"""ops 监控:请求/LLM 指标(计数/错误率/延迟分位)+ 深度健康 + Prometheus 文本。"""
+import os, sys, tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+import pytest
+
+
+def test_metrics():
+    # ISOLATION_GUARD:本用例依赖 import 时固化的模块级单例(网关/限流器/路由配置按 env 在 import 时定型),单进程全量跑会被前序用例污染 →
+    # 假红。全量请用 tests/run_all.py(每文件独立子进程)。
+    if "foxclaw.api" in sys.modules:
+        pytest.skip("需独立进程运行(模块级单例已固化),请用 tests/run_all.py")
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    os.environ.setdefault("FOXCLAW_EMBEDDING_MODEL", "foxclaw-nonexistent-fast")
+    os.environ["HKC_EMBEDDING"] = "stub"
+    os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_metrics_")
+
+    from fastapi.testclient import TestClient
+    from foxclaw.api import app
+
+    print("=" * 60); print("ops 监控验证"); print("=" * 60)
+
+    with TestClient(app) as c:
+        # 产生一些请求 + 一次任务(触发 LLM 埋点,stub)
+        c.get("/api/status"); c.get("/api/ahs/skills"); c.get("/health")
+        c.post("/api/task", json={"task": "测试", "agent_id": "supervisor"})
+
+        # [1] 深度健康:逐子系统(开放路径,探针无需鉴权;不泄露 provider 名)
+        hd = c.get("/health/ready")
+        assert hd.status_code == 200, hd.status_code
+        j = hd.json()
+        assert j["status"] in ("ok", "degraded") and "hmr" in j["components"] and "router" in j["components"], j
+        assert j["components"]["router"] in ("ok", "stub", "down"), "router 不应泄露 provider 名"
+        print(f"[1] /health/ready 深度健康({j['status']},{len(j['components'])} 组件,router 不泄露) OK")
+
+        # [2] JSON metrics:端点延迟分位 + 错误率
+        m = c.get("/api/metrics").json()
+        assert "uptime_s" in m and m["endpoints"], m
+        ep = next(k for k in m["endpoints"] if "status" in k)
+        st = m["endpoints"][ep]
+        assert st["count"] >= 1 and "p95_ms" in st and "error_rate" in st and "avg_ms" in st, st
+        print(f"[2] /api/metrics 端点(p50={st['p50_ms']} p95={st['p95_ms']} err={st['error_rate']}) OK")
+
+        # [3] LLM 埋点(stub 也计入调用量)
+        assert m["llm"], f"LLM 指标应非空: {m['llm']}"
+        print(f"[3] LLM 埋点({list(m['llm'])}) OK")
+
+        # [4] Prometheus 文本格式
+        p = c.get("/metrics")
+        assert p.status_code == 200 and "foxclaw_requests_total" in p.text and "foxclaw_llm_calls_total" in p.text
+        print("[4] /metrics Prometheus 文本 OK")
+
+        # [5] 未匹配路由(404)不撑爆 key:20 个不同 404 路径 → 只 1 个 "unmatched" key
+        for i in range(20):
+            c.get(f"/api/does-not-exist/random-{i}")
+        m2 = c.get("/api/metrics").json()
+        rand_keys = [k for k in m2["endpoints"] if "random-" in k]
+        assert len(rand_keys) == 0, f"404 路径不该各自成 key(内存DoS): {rand_keys[:3]}"
+        assert any("unmatched" in k for k in m2["endpoints"]), "应有 unmatched 汇总 key"
+        print("[5] 404 路径归入 unmatched(防指标 key 内存 DoS) OK")
+
+    print("\nops 监控验证全部通过")
+
+
+if __name__ == "__main__":
+    test_metrics()

package/python/tests/test_multi_chain.py

@@ -0,0 +1,102 @@
+"""智能体层深化:多步跨 Agent 由「排队跑」升级为「真链式」——后一步能看到前序步骤结果。
+
+原缺口:_dispatch_multi 每步都只拿到同一份原始 context,等于 N 个互不相干的任务顺序执行
+(「查本月餐饮花了多少,再据此定预算」的第 2 步拿不到第 1 步的数字)。
+"""
+import os, sys, asyncio, tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+def test_multi_chain():
+    os.environ["HKC_EMBEDDING"] = "stub"
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_chain_")
+
+    from foxclaw.agents.agents import _with_prior, PRIOR_MAX_STEPS, PRIOR_MAX_CHARS
+
+    print("=" * 60); print("多步跨 Agent 链式协作验证"); print("=" * 60)
+
+    # [1] 无前序 → 原样返回(第 1 步不该有前言)
+    assert _with_prior("查餐饮支出", []) == "查餐饮支出"
+    print("[1] 首步无前序上下文(原样)OK")
+
+    # [2] 有前序 → 并进任务文本
+    t = _with_prior("据此定预算", [{"step": 1, "agent": "finance", "output": "餐饮 1200 元"}])
+    assert "据此定预算" in t and "餐饮 1200 元" in t and "第1步(finance)" in t, t
+    print("[2] 前序结果并进下一步任务文本 OK")
+
+    # [3] 步数封顶:只带最近 N 步(防长链把提示词滚爆)
+    many = [{"step": i, "agent": "a", "output": f"out{i}"} for i in range(1, 9)]
+    t3 = _with_prior("x", many)
+    assert "out8" in t3 and "out6" in t3 and "out5" not in t3, t3
+    assert t3.count("第") - 1 == PRIOR_MAX_STEPS or t3.count("步(") == PRIOR_MAX_STEPS, t3
+    print(f"[3] 只带最近 {PRIOR_MAX_STEPS} 步(更早的不注入)OK")
+
+    # [4] 单步字符封顶
+    t4 = _with_prior("x", [{"step": 1, "agent": "a", "output": "y" * 900}])
+    assert "y" * PRIOR_MAX_CHARS in t4 and "y" * (PRIOR_MAX_CHARS + 1) not in t4
+    print(f"[4] 单步输出截断到 {PRIOR_MAX_CHARS} 字符 OK")
+
+    # ── 集成:直接驱动 _dispatch_multi,看子 Agent 真实收到了什么 ──
+    from foxclaw import Foxclaw
+
+    # 注意:Foxclaw 的 data_dir 是**构造参数**(默认 ./foxclaw_data),不读 FOXCLAW_DATA_DIR
+    # ——env 是 api.py 读了再传进来的。测试必须显式传临时目录,否则会写进真实用户记忆库。
+    os_ = Foxclaw(data_dir=os.environ["FOXCLAW_DATA_DIR"])
+    sup = os_.supervisor
+
+
+    class StubAgent:
+        """记录真实收到的 task 文本与 context。"""
+        def __init__(self, name, reply): self.name = name; self.reply = reply; self.seen = []
+        async def run_task(self, task, context=None):
+            self.seen.append({"task": task, "context": context or {}})
+            return {"result": self.reply}
+
+
+    fin = StubAgent("finance", "本月餐饮 1200 元")
+    adm = StubAgent("admin", "已按 1200 元安排下周预算")
+    subs = {"finance": fin, "admin": adm}
+    sched = sup._schedule_for("t", subs) if hasattr(sup, "_schedule_for") else None
+    if sched is None:                       # 兼容:直接拿一个 schedule 对象
+        from foxclaw.core.scheduler import SystemContext
+        sched = sup._scheduler.schedule("t", SystemContext(active_agents=0, queue_depth=0, system_load=0.1))
+
+    routes = [("查本月餐饮支出", "finance"), ("据此安排下周预算", "admin")]
+    out = asyncio.run(sup._dispatch_multi("查餐饮并定预算", routes, sched, "sess1", subs, {}, []))
+
+    # [5] 第 1 步不带前序;第 2 步**收到了**第 1 步的输出 → 链真的接上了
+    s1, s2 = fin.seen[0]["task"], adm.seen[0]["task"]
+    assert "前序步骤结果" not in s1, f"首步不该有前序前言: {s1}"
+    assert "本月餐饮 1200 元" in s2, f"第2步应看到第1步结果,实际: {s2}"
+    assert "据此安排下周预算" in s2
+    print("[5] 第2步真实收到第1步输出(链式成立)OK")
+
+    # [6] context 里也有结构化 prior_steps(两手准备)
+    ps = adm.seen[0]["context"].get("prior_steps")
+    assert ps and ps[0]["agent"] == "finance" and "1200" in ps[0]["output"], ps
+    assert fin.seen[0]["context"].get("prior_steps") == [], "首步 prior 应为空"
+    print("[6] context.prior_steps 结构化传递 OK")
+
+    # [7] 展示用 subtask 保留原始文本(不被前序前言污染 UI)
+    steps = out["result"]["multi_steps"]
+    assert steps[1]["subtask"] == "据此安排下周预算", steps[1]["subtask"]
+    assert "前序步骤结果" not in steps[1]["subtask"]
+    assert out["result"]["dispatched_to"] == "multi" and len(steps) == 2
+    print("[7] UI 展示的 subtask 仍是原始文本(未被污染)OK")
+
+    # [8] 【长期运行】入链的输出必须截断:prior 会被复制进**每个**后续步骤的 context,
+    #     不截断则长链 + 大输出会滚成可观的内存/拷贝开销(渲染本就只用 300 字符)。
+    big = StubAgent("finance", "X" * 5000)
+    subs2 = {"finance": big, "admin": StubAgent("admin", "ok")}
+    asyncio.run(sup._dispatch_multi("t", [("查", "finance"), ("用", "admin")],
+                                    sched, "s2", subs2, {}, []))
+    ps = subs2["admin"].seen[0]["context"]["prior_steps"]
+    assert len(ps[0]["output"]) <= PRIOR_MAX_CHARS, f"入链输出未截断: {len(ps[0]['output'])}"
+    assert len(subs2["admin"].seen[0]["task"]) < 2000, "任务文本不该被前序大输出撑爆"
+    print(f"[8] 大输出入链自动截断({len(ps[0]['output'])} ≤ {PRIOR_MAX_CHARS} 字符)OK")
+
+    print("\n多步跨 Agent 链式协作验证全部通过")
+
+if __name__ == "__main__":
+    test_multi_chain()