foxclaw 0.1.0 → 0.1.3

package/python/tests/test_search.py

@@ -0,0 +1,194 @@
+"""
+认知搜索内核(HSR 融入)测试 —— 全离线,不联网(external_ports=[])。
+
+覆盖:
+  1. 空源检索:无 HMR / 无知识 / 无外部端口 → 返回 SearchResult,迭代有上限,不死循环
+  2. 内部记忆证据:假 HMR recall → 证据图含 MEMORY 来源节点
+  3. 知识端口边界:HKCReadPort(client=None) 永远返回 [](降级不报错)
+  4. 经 Foxclaw 惰性 search_runtime + aclose teardown
+
+联网(百度)与真实 HKC 检索不在离线回归内;这里验证 HSR 的编排/融合/迭代/降级契约。
+"""
+import sys, tempfile, shutil, asyncio
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.search import SearchRuntime, HKCReadPort, SourceType
+
+
+class FakeHMR:
+    """假 HMR:recall 返回两条记忆,验证内部记忆证据能进证据图。"""
+    def recall(self, query, agent_id=None, top_k=5):
+        return [
+            {"id": "m1", "content": f"关于「{query}」的历史记忆一", "confidence": 0.7},
+            {"id": "m2", "content": f"关于「{query}」的历史记忆二", "confidence": 0.6},
+        ]
+
+
+def test_empty_sources_terminates():
+    print("\n【1】空源检索:不死循环 + 迭代有上限")
+    rt = SearchRuntime(hmr=None, knowledge_port=None, external_ports=[])
+    r = rt.search("任意查询", agent_id="finance")
+    assert r.iterations <= 5, f"迭代应有上限,实际 {r.iterations}"
+    assert isinstance(r.trace, list) and r.trace
+    assert 0.0 <= r.confidence <= 1.0
+    print(f"  ✓ 返回 SearchResult: iterations={r.iterations} confidence={r.confidence:.2f} "
+          f"trace={len(r.trace)}条")
+
+
+def test_memory_evidence():
+    print("\n【2】内部记忆证据进证据图(MEMORY 来源)")
+    rt = SearchRuntime(hmr=FakeHMR(), knowledge_port=None, external_ports=[])
+    r = rt.search("分析活字印刷的历史", agent_id="office")
+    nodes = list(r.graph.nodes.values())
+    mem = [n for n in nodes if n.source == SourceType.MEMORY]
+    assert len(mem) >= 1, "假 HMR 的记忆应作为证据进图"
+    print(f"  ✓ 证据图 {len(nodes)} 节点,其中 MEMORY 来源 {len(mem)} 个")
+    print(f"    样例: {mem[0].fact[:30]!r} conf={mem[0].confidence:.2f}")
+
+
+def test_hkc_port_degrades():
+    print("\n【3】知识端口降级:HKCReadPort(client=None) 返回 []")
+    port = HKCReadPort(client=None)
+    assert port.available is False
+    assert port.query("任意", top_k=5) == []
+    print("  ✓ client=None 时 available=False 且 query 返回 [](不报错)")
+
+
+def test_via_foxclawos_lazy():
+    print("\n【4】经 Foxclaw 惰性 search_runtime + aclose")
+    d = tempfile.mkdtemp(prefix="hsr_os_")
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        assert "search_runtime" not in os_.capabilities._caps, "未访问前不该构造"
+        rt = os_.search_runtime
+        assert rt is not None and os_.search_runtime is rt, "应缓存同一实例"
+        rt.external_ports = []
+        r = rt.search("测试查询", agent_id="supervisor")
+        assert r.confidence is not None
+        print(f"  ✓ 惰性构造成功,search 返回 confidence={r.confidence:.2f}")
+        asyncio.run(os_.aclose())
+        print("  ✓ aclose() 释放(含惰性装配过的 HKC)")
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+class _NS:
+    """简易命名空间对象(带属性)。"""
+    def __init__(self, **kw): self.__dict__.update(kw)
+
+
+class FakeThoughtChain:
+    def search_nodes(self, keyword, agent_id=None, limit=20):
+        if "预算" in keyword or "风险" in keyword:
+            return [_NS(id="t1", agent_id="finance", content="评估本月预算风险偏高")]
+        return []
+
+
+class FakeRegistry:
+    def catalog(self):
+        return [{"name": "gmail_send", "triggers": ["发邮件", "email"],
+                 "kind": "mcp", "side_effect": "external"}]
+
+
+def test_agent_port_all_subsources():
+    print("\n【5】AgentSourcePort:四类子源全连通")
+    from foxclaw.search import AgentSourcePort
+    finance = _NS(
+        transactions=[_NS(entity="星巴克咖啡", amount=35, category="餐饮", tags=["coffee"])],
+        budgets=[_NS(category="餐饮", monthly_limit=800)], entities={})
+    learning = _NS(items={"k1": _NS(content="活字印刷术由毕昇发明", topic="历史", tags=[])})
+    itinerary = _NS(waypoints=[_NS(name="首都机场", address="北京朝阳", city="北京", start_time="09:00")])
+    agents = {"finance": _NS(get_status=lambda: {"role": "理财风控", "status": "idle"})}
+
+    class HMRStub:
+        def recall(self, query, agent_id=None, top_k=5):
+            return [{"id": "m1", "content": f"{agent_id}记得关于{query}的事"}]
+
+    port = AgentSourcePort(agents=agents, finance_runtime=finance, learning_runtime=learning,
+                           itinerary_runtime=itinerary, thought_chain=FakeThoughtChain(),
+                           skill_registry=FakeRegistry(), hmr=HMRStub())
+    assert port.available
+    from foxclaw.search import SourceType
+
+    def origins(q):
+        return {e.origin for e in port.query(q, top_k=8)}
+
+    assert any("finance:transaction" in o for o in origins("星巴克")), "财务交易应连通"
+    assert any("learning" in o for o in origins("活字印刷")), "学习知识应连通"
+    assert any("itinerary" in o for o in origins("首都机场")), "行程点应连通"
+    assert any("thoughtchain" in o for o in origins("预算风险")), "推理链应连通"
+    assert any("capability:skill" in o for o in origins("发邮件")), "能力目录应连通"
+    assert any(":hmr:" in o for o in origins("任意")), "各Agent记忆应连通"
+    evs = port.query("星巴克", top_k=8)
+    assert all(e.source == SourceType.AGENT for e in evs)
+    print("  ✓ 财务/学习/行程/推理链/能力/各Agent记忆 六路均连通,来源标记 AGENT")
+
+
+def test_bidirectional_and_internal_only():
+    print("\n【6】双向:Agent 调用内部搜索(internal_only,不联网)")
+    d = tempfile.mkdtemp(prefix="hsr_bi_")
+    try:
+        from foxclaw import Foxclaw
+        from foxclaw.search import SourceType
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        from foxclaw.finance.models import Transaction
+        os_.finance_runtime.add_transaction(
+            Transaction(entity="蔚来汽车", amount=-260000, category="购车",
+                        account="alipay", timestamp="2026-05-01T10:00:00"),
+            run_gatekeeper=False)
+        _ = os_.search_runtime
+        res = os_.finance.search_internal("蔚来汽车")
+        assert res is not None, "search_internal 应返回 SearchResult"
+        agent_ev = [n for n in res.graph.nodes.values() if n.source == SourceType.AGENT]
+        assert any("蔚来" in n.fact for n in agent_ev), "应从财务内核检索到该交易"
+        assert all(n.source != SourceType.WEB for n in res.graph.nodes.values())
+        print(f"  ✓ os_.finance.search_internal('蔚来汽车') → AGENT证据 {len(agent_ev)} 条,无联网")
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_internal_source_isolation():
+    print("\n【7】深审修复:内部单源抛异常被隔离(不掀翻整个 search)")
+    class _BoomPort:
+        def query(self, text, top_k=5): raise RuntimeError("内部源炸了")
+    class _OKKnow:
+        def query(self, text, top_k=5):
+            from foxclaw.search import SourceType
+            from foxclaw.search.models import RawEvidence
+            return [RawEvidence(id="k1", fact=f"知识:{text}", source=SourceType.KNOWLEDGE,
+                                origin="hkc:k1", confidence=0.7)]
+    rt = SearchRuntime(hmr=FakeHMR(), knowledge_port=_OKKnow(),
+                       agent_port=_BoomPort(), external_ports=[])
+    r = rt.search("测试查询", agent_id="finance", internal_only=True)
+    facts = [n.fact for n in r.graph.nodes.values()]
+    assert any("知识" in f for f in facts), "知识源应仍返回(不受 agent 源崩溃影响)"
+    assert any("记忆" in f for f in facts), "记忆源应仍返回"
+    print(f"  ✓ agent 源抛异常被隔离,其它源正常:{len(r.graph.nodes)} 节点")
+    rt2 = SearchRuntime(hmr=None, knowledge_port=_BoomPort(),
+                        agent_port=_BoomPort(), external_ports=[])
+    r2 = rt2.search("测试", internal_only=True)
+    assert len(r2.graph.nodes) == 0 and 0.0 <= r2.confidence <= 1.0
+    print("  ✓ 全源崩溃 → search 不崩、返回空图(与 external 隔离对称)")
+
+
+def main():
+    print("=" * 60)
+    print("认知搜索内核 · HSR 融入(全离线,不联网)")
+    print("=" * 60)
+    test_empty_sources_terminates()
+    test_memory_evidence()
+    test_hkc_port_degrades()
+    test_via_foxclawos_lazy()
+    test_agent_port_all_subsources()
+    test_bidirectional_and_internal_only()
+    test_internal_source_isolation()
+    print("\n" + "=" * 60)
+    print("✓ HSR 融入验证完成:编排/证据融合/迭代上限/端口降级/惰性teardown")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_secrets.py

@@ -0,0 +1,153 @@
+"""本地密钥存储:keyring 优先、base64 回退、改名/删除不留孤儿。
+
+不碰真 OS 凭据库(测试机器上可能没有后端,也可能有用户真实数据),
+用 fake 替换 `secrets._keyring`。
+"""
+
+import pytest
+
+from foxclaw.core import secrets
+
+
+class _FakeKeyring:
+    def __init__(self):
+        self.store = {}
+
+    def set_password(self, service, user, value):
+        self.store[(service, user)] = value
+
+    def get_password(self, service, user):
+        return self.store.get((service, user))
+
+    def delete_password(self, service, user):
+        if (service, user) not in self.store:
+            raise KeyError(user)
+        del self.store[(service, user)]
+
+
+@pytest.fixture
+def fake_kr(monkeypatch):
+    kr = _FakeKeyring()
+    monkeypatch.setattr(secrets, "_keyring", lambda: kr)
+    return kr
+
+
+@pytest.fixture
+def no_kr(monkeypatch):
+    monkeypatch.setattr(secrets, "_keyring", lambda: None)
+
+
+def test_store_takes_over_when_keyring_available(fake_kr):
+    assert secrets.store("m1", "sk-abc") is True
+    assert fake_kr.store[(secrets.SERVICE, "m1")] == "sk-abc"
+
+
+def test_store_reports_failure_without_keyring(no_kr):
+    assert secrets.store("m1", "sk-abc") is False
+
+
+def test_load_prefers_keyring_over_legacy_ciphertext(fake_kr):
+    fake_kr.store[(secrets.SERVICE, "m1")] = "sk-new"
+    assert secrets.load("m1", secrets.obf("sk-old")) == "sk-new"
+
+
+def test_load_falls_back_to_legacy_ciphertext(no_kr):
+    assert secrets.load("m1", secrets.obf("sk-old")) == "sk-old"
+
+
+def test_load_returns_empty_when_nothing_stored(no_kr):
+    assert secrets.load("m1") == ""
+
+
+def test_rename_moves_credential(fake_kr):
+    """改名不搬迁 → load(新名) 取不到,key 静默丢失。"""
+    secrets.store("old", "sk-abc")
+    assert secrets.rename("old", "new") is True
+    assert secrets.load("new") == "sk-abc"
+    assert fake_kr.get_password(secrets.SERVICE, "old") is None
+
+
+def test_rename_without_source_is_noop(fake_kr):
+    assert secrets.rename("missing", "new") is False
+
+
+def test_delete_is_idempotent(fake_kr):
+    secrets.store("m1", "sk-abc")
+    secrets.delete("m1")
+    secrets.delete("m1")
+    assert secrets.load("m1") == ""
+
+
+def test_delete_without_keyring_does_not_raise(no_kr):
+    secrets.delete("m1")
+
+
+def test_save_key_keeps_only_marker_when_keyring_available(fake_kr):
+    """有 OS 凭据库时,JSON 里不能再有任何可还原的密文。"""
+    from foxclaw.api.routes.llm_admin import _save_key
+
+    fields = _save_key("m1", "  sk-abc  ")
+    assert fields == {"api_key_kr": True, "api_key_obf": ""}
+    assert fake_kr.store[(secrets.SERVICE, "m1")] == "sk-abc"
+
+
+def test_save_key_falls_back_to_ciphertext(no_kr):
+    from foxclaw.api.routes.llm_admin import _save_key
+
+    fields = _save_key("m1", "sk-abc")
+    assert fields["api_key_kr"] is False
+    assert secrets.deobf(fields["api_key_obf"]) == "sk-abc"
+
+
+def test_save_key_empty_input_clears_both(no_kr):
+    from foxclaw.api.routes.llm_admin import _save_key
+
+    assert _save_key("m1", "") == {"api_key_kr": False, "api_key_obf": ""}
+
+
+@pytest.mark.parametrize("record,expected", [
+    ({"api_key_kr": True, "api_key_obf": ""}, True),
+    ({"api_key_kr": False, "api_key_obf": "c2stYWJj"}, True),
+    ({"api_key": "sk-legacy"}, True),
+    ({"api_key_kr": False, "api_key_obf": ""}, False),
+    ({}, False),
+])
+def test_has_key(record, expected):
+    from foxclaw.api.routes.llm_admin import _has_key
+
+    assert _has_key(record) is expected
+
+
+def test_obf_is_reversible(no_kr):
+    """base64 只是混淆,不要在任何地方当加密用 —— 这条测试的作用是钉住这一点。"""
+    import base64
+
+    assert secrets.deobf(secrets.obf("sk-secret")) == "sk-secret"
+    assert base64.b64decode(secrets.obf("sk-secret")).decode() == "sk-secret"
+
+
+def test_backend_probe_is_cached(monkeypatch):
+    import sys
+    import types
+
+    calls = []
+
+    class _Fail:
+        pass
+
+    fake = types.ModuleType("keyring")
+    fake.get_keyring = lambda: calls.append(1) or _Fail()
+    backends = types.ModuleType("keyring.backends")
+    fail_mod = types.ModuleType("keyring.backends.fail")
+    fail_mod.Keyring = _Fail
+    monkeypatch.setitem(sys.modules, "keyring", fake)
+    monkeypatch.setitem(sys.modules, "keyring.backends", backends)
+    monkeypatch.setitem(sys.modules, "keyring.backends.fail", fail_mod)
+
+    secrets.reset_probe()
+    try:
+        assert secrets.available() is False
+        secrets.available()
+        assert len(calls) == 1
+    finally:
+        secrets.reset_probe()

package/python/tests/test_semantic.py

@@ -0,0 +1,69 @@
+"""真语义检索 + KEE 语义化验证。用 HMR 已缓存的 all-MiniLM-L6-v2 证明机制(离线可用);
+模型未缓存则优雅跳过(退出0,不 FAIL)——真机上装了多语言模型即走真语义,否则 auto/keyword 降级。"""
+import os, sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+sys.path.insert(0, str(Path(__file__).parent.parent / "vendor" / "hkc"))
+
+def test_semantic():
+    os.environ.setdefault("HF_HUB_OFFLINE", "1")
+    os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+
+    MODEL = "all-MiniLM-L6-v2"
+    from hkc_search.embedding_backends import get_st_model
+
+    print("=" * 60); print("真语义检索 + KEE 语义化验证"); print("=" * 60)
+
+    from hkc_kee.kee import _SimpleEmbedder as _SE
+    assert _SE._has_neg("this is a badge") is False, "badge 误命中否定"
+    assert _SE._has_neg("I know this") is False, "know 误命中否定"
+    assert _SE._has_neg("this is not good") is True
+    assert _SE._has_neg("cannot proceed") is True
+    assert _SE._has_neg("这个方案不好") is True
+    print("[0] KEE 否定词词边界(badge/know 不误命中) OK")
+
+    from hkc_kee.kee import KnowledgeEvolutionEngine
+    class _Bus:
+        def subscribe(self, *a, **k): pass
+    class _Store: pass
+    class _Gen: pass
+    eng = KnowledgeEvolutionEngine(_Store(), _Bus(), _Gen())
+    assert abs(eng.similarity_threshold - 0.30) < 1e-9, "默认阈值应 0.30(与既有硬编码一致)"
+    eng2 = KnowledgeEvolutionEngine(_Store(), _Bus(), _Gen(), similarity_threshold=0.90)
+    assert abs(eng2.similarity_threshold - 0.90) < 1e-9, "阈值应可经构造参数配置"
+    print("[0b] KEE 语义方向阈值接线(默认 0.30 / 可配置) OK")
+
+    m = get_st_model(MODEL)
+    if m is None:
+        print("[skip] all-MiniLM 未缓存,跳过真语义验证(生产靠 auto/keyword 降级兜底)")
+        if __name__ != "__main__":
+            import pytest
+            pytest.skip("all-MiniLM 未缓存 → 真语义验证跳过(auto/keyword 降级兜底)",
+                        allow_module_level=True)
+        sys.exit(0)
+
+    assert get_st_model(MODEL) is m, "同名应共享同一实例(单例)"
+    print("[1] get_st_model 同名单例 OK")
+
+    import numpy as np
+    from hkc_search.embedding_backends import LocalSTBackend
+    b = LocalSTBackend(model_name=MODEL)
+    va, vb, vc = b.encode(["I am very happy today", "Feeling great today", "The stock market crashed"])
+    sim_close = float(np.dot(va, vb)); sim_far = float(np.dot(va, vc))
+    assert sim_close > sim_far, f"相近应更高: {sim_close} vs {sim_far}"
+    print(f"[2] LocalST 真余弦:相近({sim_close:.2f}) > 无关({sim_far:.2f}) OK")
+
+    from hkc_kee.kee import _SimpleEmbedder
+    _SimpleEmbedder._MODEL_NAME = MODEL
+    emb = _SimpleEmbedder()
+    s_same = emb.score("this plan is good", "this plan is nice")
+    s_unrel = emb.score("this plan is good", "it will rain tomorrow")
+    s_contra = emb.score("this plan is good", "this plan is not good")
+    assert s_same > s_unrel, f"相近应 > 无关: {s_same} vs {s_unrel}"
+    assert s_contra < s_same, f"矛盾应 < 同向: {s_contra} vs {s_same}"
+    print(f"[3] KEE score:同向({s_same:.2f}) > 无关({s_unrel:.2f}),矛盾({s_contra:.2f})<同向 OK")
+
+    print("\n真语义检索 + KEE 语义化验证通过")
+
+if __name__ == "__main__":
+    test_semantic()

package/python/tests/test_sessions.py

@@ -0,0 +1,90 @@
+"""
+会话存储回归测试(全离线)。
+
+覆盖:建/列/读/追加/改名/删、标题自动提炼、按更新时间倒序、
+列表不含 messages(负载)、路径穿越防护、并发追加(对话跑在后台线程)。
+"""
+import sys, tempfile, shutil, threading
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.core.sessions import SessionStore, derive_title
+import pytest
+
+
+@pytest.fixture()
+def store():
+    d = tempfile.mkdtemp(prefix="sess_")
+    try:
+        yield SessionStore(Path(d) / "sessions")
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_create_list_get(store):
+    s = store.create()
+    assert s["id"] and s["title"] == "新会话" and s["message_count"] == 0
+    assert [x["id"] for x in store.list()] == [s["id"]]
+    assert store.get(s["id"])["messages"] == []
+
+
+def test_append_and_title_derivation(store):
+    s = store.create()
+    assert store.append(s["id"], "user", "帮我分析本月支出情况。还有别的")
+    assert store.append(s["id"], "assistant", "好的,本月支出如下…")
+    d = store.get(s["id"])
+    assert len(d["messages"]) == 2
+    assert d["messages"][0]["role"] == "user"
+    assert d["title"] == "帮我分析本月支出情况"
+
+
+def test_append_rejects_bad_role_and_missing_session(store):
+    s = store.create()
+    assert store.append(s["id"], "system", "x") is False
+    assert store.append(s["id"], "user", "") is False
+    assert store.append("deadbeef1234", "user", "x") is False
+
+
+def test_list_is_light_and_sorted(store):
+    a = store.create(); store.append(a["id"], "user", "第一个会话")
+    b = store.create(); store.append(b["id"], "user", "第二个会话")
+    lst = store.list()
+    assert lst[0]["id"] == b["id"], "应按 updated_at 倒序"
+    assert "messages" not in lst[0], "列表不得带 messages(负载)"
+    assert lst[0]["message_count"] == 1 and lst[0]["last"] == "第二个会话"
+
+
+def test_rename_and_delete(store):
+    s = store.create()
+    assert store.rename(s["id"], "季度复盘")
+    assert store.get(s["id"])["title"] == "季度复盘"
+    assert store.delete(s["id"])
+    assert store.get(s["id"]) is None
+    assert store.delete(s["id"]) is False
+
+
+def test_path_traversal_blocked(store):
+    """id 只允许安全字符,杜绝 ../ 路径穿越。"""
+    assert store.get("../../etc/passwd") is None
+    assert store.delete("../../x") is False
+    assert store.append("../../x", "user", "hi") is False
+
+
+def test_concurrent_append_no_loss(store):
+    """对话跑在后台线程,追加必须线程安全、不丢消息。"""
+    s = store.create()
+    def w(i):
+        store.append(s["id"], "user", f"消息{i}")
+    ts = [threading.Thread(target=w, args=(i,)) for i in range(20)]
+    [t.start() for t in ts]; [t.join() for t in ts]
+    assert len(store.get(s["id"])["messages"]) == 20
+
+
+def test_derive_title():
+    assert derive_title("你好呀！今天天气") == "你好呀"
+    assert derive_title("") == "新会话"
+    assert len(derive_title("长" * 100)) <= 24
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])