foxclaw 0.1.0 → 0.1.3

package/python/tests/test_policy_gate.py

@@ -0,0 +1,108 @@
+"""
+统一准入门(PolicyGate, v2 ① Step4)测试 —— 全离线。
+
+覆盖:
+  1. 推理准入归一化:Harness PASS/WARN/BLOCK → Verdict allow/warn/deny(raw 透传同一 HarnessResult)
+  2. 动作准入归一化:permission allow/ask/deny → Verdict allow/confirm/deny(raw 透传);
+     非 allow 发统一 policy.decision.* 事件,allow 不发(降噪)
+  3. 真实集成:经 Foxclaw,技能路径(副作用 skill 需确认)发出 policy.decision 事件
+"""
+import os, sys, asyncio, tempfile, shutil
+from pathlib import Path
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ["FOXCLAW_EMBEDDING_MODEL"] = "foxclaw-nonexistent-fast"
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.kernel import PolicyGate
+
+
+class _HR:
+    def __init__(self, blocked=False, warned=False, reason=""):
+        self._b, self._w, self.reason = blocked, warned, reason
+    @property
+    def is_blocked(self): return self._b
+    @property
+    def is_warned(self): return self._w
+
+
+class _Harness:
+    def __init__(self, hr): self.hr = hr; self.calls = 0
+    def check(self, node): self.calls += 1; return self.hr
+
+
+class _PD:
+    def __init__(self, decision, reason=""):
+        self.decision, self.stage, self.reason, self.trust_downgrade = decision, 2, reason, False
+
+
+class _CapSpine:
+    def __init__(self): self.events = []
+    def publish(self, topic, payload=None, source="", **kw): self.events.append(topic)
+
+
+class _Skill:
+    id = "gmail_send"
+
+
+def test_reasoning_normalization():
+    print("\n【1】推理准入归一化(Harness → Verdict;raw 透传)")
+    gate = PolicyGate()
+    h = _Harness(_HR())
+    v = gate.check_reasoning(h, None)
+    assert v.level == "allow" and v.allowed and v.raw is h.hr and h.calls == 1
+    v = gate.check_reasoning(_Harness(_HR(warned=True)), None)
+    assert v.level == "warn" and v.allowed
+    v = gate.check_reasoning(_Harness(_HR(blocked=True, reason="越界")), None)
+    assert v.level == "deny" and not v.allowed and v.reason == "越界"
+    print("  ✓ PASS→allow / WARN→warn / BLOCK→deny;raw 仍是同一 HarnessResult(行为一致)")
+
+
+def test_action_normalization_and_event():
+    print("\n【2】动作准入归一化 + 非 allow 发 policy.decision")
+    for decision, level, event in [("allow", "allow", None),
+                                    ("ask", "confirm", "policy.decision.confirm"),
+                                    ("deny", "deny", "policy.decision.deny")]:
+        spine = _CapSpine()
+        pd = _PD(decision, reason=f"r-{decision}")
+        gate = PolicyGate(spine=spine, action_evaluator=lambda *a, _pd=pd, **k: _pd)
+        v = gate.check_action(_Skill(), {})
+        assert v.level == level and v.raw is pd, f"{decision}→{v.level}"
+        assert v.allowed == (decision == "allow")
+        assert spine.events == ([event] if event else []), (decision, spine.events)
+    print("  ✓ allow(不发) / ask→confirm(发) / deny(发);raw 透传 PermissionDecision")
+
+
+def test_integration_skill_path():
+    print("\n【3】真实集成:技能路径经统一门,副作用 skill 发 policy.decision")
+    d = tempfile.mkdtemp(prefix="pg_")
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        seen = []
+        os_.event_spine.project(lambda e: seen.append(e.topic))
+        os_.supervisor.use_skill("帮我发邮件给客户",
+                                args={"to": "a@b.com", "subject": "x", "body": "y"})
+        assert any(t.startswith("policy.decision") for t in seen), \
+            f"技能准入应发 policy.decision,实得 {[t for t in seen if 'policy' in t]}"
+        assert os_.capabilities.get("policy_gate") is os_.policy_gate
+        print(f"  ✓ use_skill(副作用)→ 发 {[t for t in seen if t.startswith('policy')]}")
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def main():
+    print("=" * 60)
+    print("统一准入门 · PolicyGate(v2 ① Step4)")
+    print("=" * 60)
+    test_reasoning_normalization()
+    test_action_normalization_and_event()
+    test_integration_skill_path()
+    print("\n" + "=" * 60)
+    print("✓ Step4 验证完成:两个门统一到 Verdict 词汇 + 一个接口 + 统一审计")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_profile.py

@@ -0,0 +1,67 @@
+"""称呼(user profile)存取:round-trip、改一次不留旧条目、可清空、不误删别的偏好。
+
+用 stub 宿主直接测 mixin,不初始化 Agent / API(那条路径由 test_api 覆盖)。
+"""
+
+from __future__ import annotations
+
+from foxclaw.agents.mixins.preference import PreferenceMixin
+
+
+class _Stub(PreferenceMixin):
+    AGENT_ID = "stub"
+
+    def __init__(self):
+        self.items: list[dict] = []
+        self._seq = 0
+
+    def _store_memory(self, content, mem_type="concept", **kwargs):
+        self._seq += 1
+        self.items.insert(0, {"id": f"m{self._seq}", "content": content})
+
+    def list_preferences(self, limit=50):
+        return self.items[:limit]
+
+    def delete_preference(self, pref_id):
+        before = len(self.items)
+        self.items = [p for p in self.items if p["id"] != pref_id]
+        return len(self.items) < before
+
+
+def test_nickname_roundtrip():
+    s = _Stub()
+    assert s.get_nickname() == ""
+    assert s.set_nickname("  snow  ") == "snow"
+    assert s.get_nickname() == "snow"
+
+
+def test_set_nickname_replaces_old():
+    """改称呼不能留下两条互相矛盾的偏好。"""
+    s = _Stub()
+    s.set_nickname("snow")
+    s.set_nickname("snow2")
+    assert [s._nick_of(p["content"]) for p in s.items] == ["snow2"]
+    assert s.get_nickname() == "snow2"
+
+
+def test_clear_nickname():
+    s = _Stub()
+    s.set_nickname("snow")
+    assert s.set_nickname("") == ""
+    assert s.get_nickname() == ""
+    assert s.items == []
+
+
+def test_other_preferences_untouched():
+    s = _Stub()
+    s.remember_preference("回答尽量简短")
+    s.set_nickname("snow")
+    contents = [p["content"] for p in s.items]
+    assert "用户偏好:回答尽量简短" in contents
+    assert "用户偏好:称呼我为 snow" in contents
+
+
+def test_nickname_truncated():
+    s = _Stub()
+    long = "x" * 60
+    assert s.set_nickname(long) == long[:24]

package/python/tests/test_readme_claims.py

@@ -0,0 +1,163 @@
+"""README 与仓库实际的一致性巡检。
+
+README 里的结构和数字曾经长期漂移:目录注释写「五智能体」而实际三个、
+写「76 个测试文件」而实际 110、写「77 个依赖」而实际 96 条。
+这类不一致第一眼就被识破,所以把可机器核对的部分钉在这里:
+改了代码不改文档,这个文件会红。
+
+刻意不钉的东西:测试文件个数、代码行数、依赖条目数——它们每次提交都在变,
+写进 README 就是下一个「76」。需要真实数字时用命令现取,不抄文档。
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+README_EN = ROOT / "README.md"
+README_CN = ROOT / "README_CN.md"
+
+HKC_ROUTES = ROOT / "vendor" / "hkc" / "hkc_api" / "routes" / "knowledge.py"
+KDE = ROOT / "vendor" / "hkc" / "hkc_kde" / "kde.py"
+CHUNKER = ROOT / "vendor" / "hkc" / "hkc_kde" / "chunker.py"
+EXTRACTOR = ROOT / "vendor" / "hkc" / "hkc_kde" / "extractor.py"
+
+
+@pytest.fixture(scope="module")
+def docs() -> dict[str, str]:
+    return {p.name: p.read_text(encoding="utf-8") for p in (README_EN, README_CN)}
+
+
+def _num(path: Path, pattern: str) -> int:
+    m = re.search(pattern, path.read_text(encoding="utf-8"), re.M)
+    assert m, f"{path.relative_to(ROOT)} 中找不到模式 {pattern!r}"
+    return int(m.group(1))
+
+
+def test_agents_are_three(docs: dict[str, str]) -> None:
+    impl = sorted(
+        p.stem
+        for p in (ROOT / "foxclaw" / "agents" / "impl").glob("*.py")
+        if not p.stem.startswith("_")
+    )
+    assert impl == ["finance", "office", "supervisor"], f"实际智能体实现: {impl}"
+
+    for name, text in docs.items():
+        assert "五智能体" not in text, f"{name} 仍写着五智能体"
+        assert "五个智能体" not in text, f"{name} 仍写着五个智能体"
+        assert "five agents" not in text.lower(), f"{name} 仍写着 five agents"
+
+    assert "Three agents" in docs["README.md"]
+    assert "三个智能体" in docs["README_CN.md"]
+
+
+def test_channels_are_four() -> None:
+    for adapter in ("weixin", "feishu", "telegram", "discord"):
+        assert (ROOT / "foxclaw" / "channels" / f"{adapter}.py").exists(), adapter
+    assert (ROOT / "foxclaw" / "channels" / "dispatcher.py").exists()
+
+    text = README_EN.read_text(encoding="utf-8")
+    for brand in ("WeChat", "Feishu", "Telegram", "Discord"):
+        assert brand in text, brand
+
+
+def test_runtime_governance_modules_exist() -> None:
+    for rel in (
+        "foxclaw/core/idempotency.py",
+        "foxclaw/core/recovery.py",
+        "foxclaw/harness/loop_detection.py",
+        "foxclaw/core/compaction.py",
+        "foxclaw/core/steering_queue.py",
+        "docs/GOVERNANCE.md",
+    ):
+        assert (ROOT / rel).exists(), rel
+
+
+def test_ingest_limits_match_docs(docs: dict[str, str]) -> None:
+    upload_mb = _num(HKC_ROUTES, r"MAX_UPLOAD_BYTES\s*=\s*(\d+)\s*\*\s*1024\s*\*\s*1024")
+    assert upload_mb == 20, f"单文件上传上限已变为 {upload_mb}MB,README 写的 20MB 要改"
+
+    assert _num(HKC_ROUTES, r"MAX_INGEST_CHARS\s*=\s*([\d_]+)") == 2_000_000
+    assert _num(KDE, r"DEFAULT_MAX_CHUNKS_PER_DOC\s*=\s*(\d+)") == 800
+    assert _num(EXTRACTOR, r'"HKC_EXTRACT_MAX_TOKENS",\s*"(\d+)"') == 8192
+
+    for name, text in docs.items():
+        assert "20 MB" in text or "20MB" in text, name
+        assert "2,000,000" in text, name
+        assert "800" in text, name
+        assert "8192" in text, name
+
+
+def test_chunk_geometry_matches_docs(docs: dict[str, str]) -> None:
+    max_tokens = _num(CHUNKER, r"^MAX_TOKENS\s*=\s*(\d+)")
+    overlap_tokens = _num(CHUNKER, r"^OVERLAP_TOKENS\s*=\s*(\d+)")
+    m = re.search(r"^CHARS_PER_TOKEN\s*=\s*([\d.]+)", CHUNKER.read_text(encoding="utf-8"), re.M)
+    assert m, "chunker.py 中找不到 CHARS_PER_TOKEN"
+    chars_per_token = float(m.group(1))
+
+    max_chars = int(max_tokens * chars_per_token)
+    overlap_chars = int(overlap_tokens * chars_per_token)
+    step = max_chars - overlap_chars
+
+    assert (max_chars, overlap_chars, step) == (1792, 224, 1568), (
+        f"分块几何已变为 {max_chars}/{overlap_chars}/{step},README 写的 1792/224/1568 要改"
+    )
+    for name, text in docs.items():
+        for value in ("1792", "224", "1568"):
+            assert value in text, f"{name} 未出现 {value}"
+
+
+def test_supported_formats_match_docs(docs: dict[str, str]) -> None:
+    src = HKC_ROUTES.read_text(encoding="utf-8")
+    m = re.search(r"ALLOWED_SUFFIXES\s*=\s*\((.*?)\)", src, re.S)
+    assert m, "knowledge.py 中找不到 ALLOWED_SUFFIXES"
+    suffixes = re.findall(r'"(\.\w+)"', m.group(1))
+    assert len(suffixes) == 10, f"支持格式已变为 {suffixes}"
+
+    for name, text in docs.items():
+        for suffix in suffixes:
+            assert suffix in text, f"{name} 未列出支持格式 {suffix}"
+
+
+def test_relative_links_exist(docs: dict[str, str]) -> None:
+    for name, text in docs.items():
+        for target in re.findall(r"\]\(([^)#:]+)\)", text):
+            if target.startswith(("http", "mailto")):
+                continue
+            assert (ROOT / target).exists(), f"{name} 的链接指向不存在的 {target}"
+
+
+def test_directory_tree_paths_exist() -> None:
+    for rel in (
+        "foxclaw/core",
+        "foxclaw/kernel",
+        "foxclaw/pipeline",
+        "foxclaw/planning",
+        "foxclaw/cognitive",
+        "foxclaw/knowledge",
+        "foxclaw/agents",
+        "foxclaw/harness",
+        "foxclaw/finance",
+        "foxclaw/learning",
+        "foxclaw/itinerary",
+        "foxclaw/channels",
+        "foxclaw/skills",
+        "foxclaw/search",
+        "foxclaw/browser",
+        "foxclaw/capability",
+        "foxclaw/governance",
+        "vendor/hmr",
+        "vendor/hkc",
+        "examples",
+        "tests",
+        "docs",
+    ):
+        assert (ROOT / rel).is_dir(), f"目录树列出的 {rel} 不存在"
+
+
+def test_referenced_skills_exist(docs: dict[str, str]) -> None:
+    for skill in ("general-assistant", "schedule-itinerary"):
+        assert (ROOT / "skills" / skill).is_dir(), skill
+        assert skill in docs["README_CN.md"], skill

package/python/tests/test_reasoner.py

@@ -0,0 +1,170 @@
+"""
+领域认知化(v2 ③ Step1:DomainReasoner + 财务守门人形式化)测试 —— 全离线。
+
+覆盖:
+  1. DomainReasoner 基座:reason() 按序 observe→hypothesize→gather_evidence→arbitrate
+  2. FinanceGatekeeperReasoner:小额→approve、大额→confirm、低余额→reject(freeze);
+     裁决与原守门人逐字一致 + 显式证据链(source=rules) + 假设
+  3. 真实路径:orchestrator.route_request 走认知化守门人,req 附证据链(可审计)
+"""
+import os, sys, asyncio, tempfile, shutil
+from pathlib import Path
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ["FOXCLAW_EMBEDDING_MODEL"] = "foxclaw-nonexistent-fast"
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.cognitive.reasoner import DomainReasoner, ReasonedVerdict, Evidence
+
+
+def test_reasoner_base_order():
+    print("\n【1】DomainReasoner 基座:四步按序执行")
+    order = []
+    class R(DomainReasoner):
+        def observe(self, s): order.append("observe"); return {"x": s}
+        def hypothesize(self, o): order.append("hypothesize"); return ["h"]
+        def gather_evidence(self, s, o): order.append("evidence"); return [Evidence("f", "d")]
+        def arbitrate(self, s, o, h, e):
+            order.append("arbitrate")
+            return ReasonedVerdict("approve", "ok", e, h, "rules")
+    rv = R().reason(42)
+    assert order == ["observe", "hypothesize", "evidence", "arbitrate"], order
+    assert rv.decision == "approve" and rv.hypotheses == ["h"] and len(rv.evidence) == 1
+    print("  ✓ observe→hypothesize→gather_evidence→arbitrate;证据链随裁决返回")
+
+
+def _policy():
+    from foxclaw.finance import FinanceRuntime
+    p = FinanceRuntime(policy_path=tempfile.mktemp(suffix=".yaml"),
+                       data_path=tempfile.mktemp(suffix=".json")).policy
+    for r in p.rules:
+        if r.id == "large_purchase_check":
+            r.threshold = 200.0
+            r.condition = "单笔支出 > 200"
+    return p
+
+
+def test_finance_gatekeeper_reasoner():
+    print("\n【2】财务守门人认知化:裁决逐字一致 + 证据链 + 假设")
+    from foxclaw.finance.reasoner import FinanceGatekeeperReasoner
+    from foxclaw.finance.models import Transaction
+    r = FinanceGatekeeperReasoner(_policy())
+    rv = r.reason((Transaction(amount=-150, category="travel", entity="高铁", account="default"), 5000))
+    assert rv.decision == "approve" and rv.rationale == "财务批准:travel 预算 150 在规则内"
+    assert rv.source == "rules" and any(e.factor == "rules_clear" for e in rv.evidence)
+    assert rv.hypotheses, "应有假设"
+    rv2 = r.reason((Transaction(amount=-680, category="travel", entity="酒店", account="default"), 5000))
+    assert rv2.decision == "confirm" and any(e.factor == "large_purchase_check" for e in rv2.evidence)
+    print(f"  ✓ 小额→approve(证据 rules_clear);大额→confirm(证据 large_purchase_check;假设={rv2.hypotheses})")
+
+
+def test_context_evidence_no_decision_change():
+    print("\n【2b】Step2:情境证据(历史/预算/频率)丰满证据链,但**决策不变**")
+    from foxclaw.finance import FinanceRuntime
+    from foxclaw.finance.reasoner import FinanceGatekeeperReasoner
+    from foxclaw.finance.models import Transaction
+    rt = FinanceRuntime(policy_path=tempfile.mktemp(suffix=".yaml"),
+                        data_path=tempfile.mktemp(suffix=".json"))
+    rt.set_budget("travel", 3000); rt.set_balance("default", 5000)
+    for _ in range(3):
+        rt.add_transaction(Transaction(amount=-100, category="travel", entity="高铁",
+                                       account="default"), run_gatekeeper=False)
+    r = FinanceGatekeeperReasoner(rt.policy, runtime=rt)
+    rv = r.reason((Transaction(amount=-150, category="travel", entity="高铁",
+                               account="default"), 5000))
+    assert rv.decision == "approve", "规则内 → 决策仍是 approve(情境证据不改裁决)"
+    factors = {e.factor for e in rv.evidence}
+    assert {"history_category", "budget_remaining", "entity_frequency"} <= factors, factors
+    rv0 = FinanceGatekeeperReasoner(rt.policy).reason(
+        (Transaction(amount=-150, category="travel", entity="高铁", account="default"), 5000))
+    assert not ({"history_category", "budget_remaining", "entity_frequency"}
+                & {e.factor for e in rv0.evidence})
+    assert rv0.decision == rv.decision == "approve"
+    print(f"  ✓ 决策 approve 不变;证据链含 {sorted(factors & {'history_category','budget_remaining','entity_frequency'})}")
+
+
+class _MockLLM:
+    def __init__(self, resp="APPROVE", raises=False):
+        self.resp, self.raises, self.calls, self.is_stub = resp, raises, 0, False
+    def complete(self, system, messages, max_tokens=2048, agent_id=""):
+        self.calls += 1
+        if self.raises:
+            raise RuntimeError("llm down")
+        return self.resp
+
+
+def test_llm_arbitration_safety():
+    print("\n【2c】Step3:LLM 裁决的安全不变量(只增强模糊、只能 approve→confirm、永不 reject)")
+    from foxclaw.finance.reasoner import FinanceGatekeeperReasoner
+    from foxclaw.finance.models import Transaction
+    policy = _policy()
+    def txn(amt): return Transaction(amount=-amt, category="travel", entity="高铁", account="default")
+    def mk(llm, enabled=True): return FinanceGatekeeperReasoner(policy, llm=llm, llm_enabled=enabled)
+
+    llm = _MockLLM("APPROVE"); rv = mk(llm).reason((txn(680), 5000))
+    assert rv.decision == "confirm" and rv.source == "rules" and llm.calls == 0
+
+    llm = _MockLLM("CONFIRM"); rv = mk(llm).reason((txn(150), 5000))
+    assert rv.decision == "confirm" and rv.source == "llm" and llm.calls == 1
+
+    llm = _MockLLM("APPROVE"); rv = mk(llm).reason((txn(150), 5000))
+    assert rv.decision == "approve" and rv.source == "llm"
+
+    llm = _MockLLM(raises=True); rv = mk(llm).reason((txn(150), 5000))
+    assert rv.decision == "confirm" and rv.source == "llm_failsafe"
+
+    for bad in ["REJECT", "让我拒绝这笔", "不确定", "yes maybe"]:
+        llm = _MockLLM(bad); rv = mk(llm).reason((txn(150), 5000))
+        assert rv.decision == "confirm" and rv.source == "llm_failsafe", (bad, rv.decision)
+        assert rv.decision != "reject", "LLM 永远不能产生 reject"
+
+    llm = _MockLLM("CONFIRM"); rv = mk(llm).reason((txn(50), 5000))
+    assert rv.decision == "approve" and rv.source == "rules" and llm.calls == 0
+
+    llm = _MockLLM("CONFIRM"); rv = mk(llm, enabled=False).reason((txn(150), 5000))
+    assert rv.decision == "approve" and rv.source == "rules" and llm.calls == 0
+
+    stub = _MockLLM("CONFIRM"); stub.is_stub = True
+    rv = FinanceGatekeeperReasoner(policy, llm=stub, llm_enabled=True).reason((txn(150), 5000))
+    assert rv.source == "rules" and stub.calls == 0
+    print("  ✓ 规则权威不问LLM · 模糊只 approve/confirm · 出错/乱回 fail-safe confirm · "
+          "永不 reject · 明显安全/默认关/stub 不调")
+
+
+def test_real_path_evidence():
+    print("\n【3】真实路径:认知化守门人 + req 附证据链")
+    d = tempfile.mkdtemp(prefix="reasoner_")
+    try:
+        from foxclaw import Foxclaw
+        from foxclaw.orchestration import CrossAgentRequest
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        os_.finance_runtime.set_balance("default", 5000)
+        req = os_.orchestrator.route_request(CrossAgentRequest(
+            from_agent="admin", to_agent="finance", request_type="budget_request",
+            payload={"amount": 680, "category": "travel", "entity": "酒店", "account": "default"},
+            reason="大额"))
+        assert req.status == "needs_confirmation", req.status
+        assert hasattr(req, "evidence") and req.evidence, "守门人应附证据链"
+        assert req.reason_source == "rules"
+        print(f"  ✓ status={req.status}(裁决不变);evidence={req.evidence};source={req.reason_source}")
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def main():
+    print("=" * 60)
+    print("领域认知化 · DomainReasoner + 财务守门人(v2 ③ Step1)")
+    print("=" * 60)
+    test_reasoner_base_order()
+    test_finance_gatekeeper_reasoner()
+    test_context_evidence_no_decision_change()
+    test_llm_arbitration_safety()
+    test_real_path_evidence()
+    print("\n" + "=" * 60)
+    print("✓ Step1 验证完成:观察→假设→证据→裁决 形式化;规则实现、裁决不变、证据链可审计")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()