foxclaw 0.1.0 → 0.1.2

package/python/tests/test_planner.py

@@ -0,0 +1,95 @@
+"""
+统一规划原语(P1-2:三个 Planner 合并)测试 —— 全离线。
+
+覆盖:
+  1. 共享原语:is_negated / split_on / keyword_hits(否定开关)
+  2. trigger_route 引擎:否定过滤、打分、兜底、near-ties→needs_composition、确定性平局
+  3. 三处委托同一引擎(单一真源):
+     · AHS pipeline.route 否定生效(不选被否定的 skill)
+     · search QueryPlanner._decompose 用共享拆分
+     · 主管关键词命中走 keyword_hits
+  4. 结构:pipeline 不再持有本地 _negated/_split_on(已删除,证明去重)
+"""
+import os, sys
+from pathlib import Path
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.planning import planner as P
+
+
+def test_primitives():
+    print("\n【1】共享原语:否定 / 拆分 / 关键词命中")
+    assert P.is_negated("不要计算这个", "计算") is True
+    assert P.is_negated("请计算这个", "计算") is False
+    assert P.split_on("查北京，查上海、查广州", P.LIST_SEPS) == ["查北京", "查上海", "查广州"]
+    assert P.split_on("先做A 然后 做B", P.SPLIT_MARKERS) == ["先做A", "做B"]
+    assert P.keyword_hits("分析财务收支", ["财务", "收支", "行程"]) == 2
+    assert P.keyword_hits("不要分析财务", ["财务"], negation=True) == 0
+    assert P.keyword_hits("不要分析财务", ["财务"], negation=False) == 1
+    print("  ✓ is_negated / split_on / keyword_hits(否定开关) 均正确")
+
+
+def test_trigger_route_engine():
+    print("\n【2】trigger_route 引擎:否定/打分/兜底/near-ties/确定性")
+    C = P.ScoredCandidate
+    cands = [
+        C("calculator", ["计算", "算"], "四则运算 计算器"),
+        C("web", ["搜索", "查"], "联网 搜索 网页"),
+        C("email", ["发邮件", "email"], "发送 邮件"),
+    ]
+    # 否定:"不要计算" → calculator 触发被否定 → 不选它
+    r = P.trigger_route("不要计算一下", cands)
+    assert r.primary != "calculator", f"否定应排除 calculator,实得 {r.primary}"
+    # 命中:"帮我搜索北京" → web
+    r2 = P.trigger_route("帮我搜索北京", cands)
+    assert r2.primary == "web" and r2.confidence >= 0.15
+    # 兜底:完全不相关 → 用最后一个候选兜底,低置信
+    r3 = P.trigger_route("xyzzy 无关内容", cands)
+    assert r3.primary == cands[-1].id and r3.confidence < 0.15
+    # 确定性:空候选
+    assert P.trigger_route("x", []).primary is None
+    print(f"  ✓ 否定排除 / 命中选中 / 兜底(={r3.primary}) / 空候选")
+
+
+def test_three_sites_delegate():
+    print("\n【3】三处委托同一引擎(单一真源)")
+    # AHS
+    from foxclaw.skills import build_default_registry
+    from foxclaw.skills.pipeline import route, plan
+    reg = build_default_registry()
+    assert route("不要计算", reg).primary != "calculator", "AHS route 否定生效"
+    assert len(plan("先算 5+5 然后再算 9*9", reg).tasks) == 2, "AHS plan 拆解"
+    # search
+    from foxclaw.search.planner import QueryPlanner
+    sub = QueryPlanner()._decompose("查A，查B、查C")
+    assert len(sub) == 3, "search 拆解走共享原语"
+    # supervisor(用引擎的 keyword_hits;此处直接验证原语等价)
+    assert P.keyword_hits("买基金理财", ["理财", "基金", "收支"]) == 2
+    print("  ✓ AHS / search / 主管 三处均由 foxclaw.planning 单一真源驱动")
+
+
+def test_dedup_structural():
+    print("\n【4】结构去重:pipeline 不再持有本地 _negated/_split_on")
+    import foxclaw.skills.pipeline as pipe
+    assert not hasattr(pipe, "_negated"), "pipeline 应删除本地 _negated(改用共享)"
+    assert not hasattr(pipe, "_split_on"), "pipeline 应删除本地 _split_on(改用共享)"
+    assert not hasattr(pipe, "_NEGATIONS"), "pipeline 应删除本地 _NEGATIONS 常量"
+    print("  ✓ pipeline 的重复否定/拆分实现已删除,收敛到 foxclaw.planning")
+
+
+def main():
+    print("=" * 60)
+    print("统一规划原语 · 三个 Planner 合并(P1-2)")
+    print("=" * 60)
+    test_primitives()
+    test_trigger_route_engine()
+    test_three_sites_delegate()
+    test_dedup_structural()
+    print("\n" + "=" * 60)
+    print("✓ P1-2 验证完成:一个规划引擎,主管/AHS/search 三处委托")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_policy_gate.py

@@ -0,0 +1,109 @@
+"""
+统一准入门(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:                          # 假 HarnessResult
+    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:                          # 假 PermissionDecision
+    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))
+        # 发邮件是副作用 skill → 需确认 → 经 PolicyGate 发 policy.decision.confirm
+        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_reasoner.py

@@ -0,0 +1,185 @@
+"""
+领域认知化(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
+    # data_path 显式隔离:默认落在 policy 同目录(系统 Temp),会与其他测试共用一份数据文件
+    p = FinanceRuntime(policy_path=tempfile.mktemp(suffix=".yaml"),
+                       data_path=tempfile.mktemp(suffix=".json")).policy
+    # 显式锁定本测试的前提阈值(200,模糊带 [140,200)),**不依赖产品默认值** ——
+    # 默认阈值是给用户按自己实际调的可调项,不该让调它就牵动这些验证推理逻辑的测试。
+    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())
+    # 小额(规则内)→ approve
+    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, "应有假设"
+    # 大额(>阈值)→ confirm,证据=large_purchase_check
+    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):   # 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
+    # 无 runtime → 无情境证据(向后兼容;裁决相同)
+    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()   # large_purchase_check 阈值 200;模糊带 [140,200)
+    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)
+
+    # 1. 规则触发(680>200)→ 规则权威,LLM 绝不被调
+    llm = _MockLLM("APPROVE"); rv = mk(llm).reason((txn(680), 5000))
+    assert rv.decision == "confirm" and rv.source == "rules" and llm.calls == 0
+
+    # 2. 模糊(150∈[140,200))+ LLM 说 CONFIRM → confirm, source=llm
+    llm = _MockLLM("CONFIRM"); rv = mk(llm).reason((txn(150), 5000))
+    assert rv.decision == "confirm" and rv.source == "llm" and llm.calls == 1
+
+    # 3. 模糊 + LLM 说 APPROVE → approve, source=llm
+    llm = _MockLLM("APPROVE"); rv = mk(llm).reason((txn(150), 5000))
+    assert rv.decision == "approve" and rv.source == "llm"
+
+    # 4. LLM 出错/超时 → confirm(fail-safe),绝不自动放行
+    llm = _MockLLM(raises=True); rv = mk(llm).reason((txn(150), 5000))
+    assert rv.decision == "confirm" and rv.source == "llm_failsafe"
+
+    # 5. 【核心不变量】LLM 乱回(含"拒绝"/REJECT/含糊)→ **绝不 reject**,fail-safe confirm
+    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"
+
+    # 6. 明显安全(50<140)→ 规则批准,LLM 不调(省成本)
+    llm = _MockLLM("CONFIRM"); rv = mk(llm).reason((txn(50), 5000))
+    assert rv.decision == "approve" and rv.source == "rules" and llm.calls == 0
+
+    # 7. 默认关(llm_enabled=False)→ 全走规则,LLM 不调(behavior-preserving)
+    llm = _MockLLM("CONFIRM"); rv = mk(llm, enabled=False).reason((txn(150), 5000))
+    assert rv.decision == "approve" and rv.source == "rules" and llm.calls == 0
+
+    # 8. is_stub(无真实模型)→ 视为不可用,不调 LLM
+    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 上
+        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()

package/python/tests/test_release_check.py

@@ -0,0 +1,263 @@
+"""发布前校验脚本(tools/release_check.py)的规则测试。
+
+锁住三件事:
+1. 四处版本号必须一致 —— 只改一处的发布物会让用户装到对不上的版本;
+2. tag 必须指向本次版本 —— 发布不可撤回,yank 也仍占号;
+3. 产物里不能有 .env / docs/internal / 运行期数据,缺 vendor 只算提示(占位包现状)。
+
+脚本放在 tools/ 不在包里,故按文件路径加载;测试只构造最小归档,不跑真构建(秒级)。
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import shutil
+import sys
+import tarfile
+import zipfile
+from pathlib import Path
+
+import pytest
+
+REPO = Path(__file__).resolve().parents[1]
+
+
+def _load():
+    spec = importlib.util.spec_from_file_location(
+        "release_check", REPO / "tools" / "release_check.py")
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["release_check"] = mod      # dataclass 需要能按模块名回查,否则 exec 时炸
+    spec.loader.exec_module(mod)
+    return mod
+
+
+rc = _load()
+
+
+# ── 造最小产物 ────────────────────────────────────────────
+
+def _wheel(dist: Path, version="0.1.0", name="foxclaw", extra=(),
+           description=True) -> Path:
+    p = dist / f"{name}-{version}-py3-none-any.whl"
+    body = ("\n\n" + "long description body. " * 12) if description else ""
+    with zipfile.ZipFile(p, "w") as z:
+        z.writestr(f"{name}/__init__.py", "__version__ = '0.1.0'\n")
+        z.writestr(f"{name}/cli.py", "def main(): pass\n")
+        z.writestr(f"{name}-{version}.dist-info/METADATA",
+                   f"Name: {name}\nVersion: {version}{body}\n")
+        for e in extra:
+            z.writestr(e, "x")
+    return p
+
+
+def _sdist(dist: Path, version="0.1.0", name="foxclaw", extra=()) -> Path:
+    p = dist / f"{name}-{version}.tar.gz"
+    with tarfile.open(p, "w:gz") as t:
+        for arc in (f"{name}-{version}/foxclaw/cli.py",
+                    f"{name}-{version}/PKG-INFO", *extra):
+            data = b"x"
+            info = tarfile.TarInfo(arc)
+            info.size = len(data)
+            t.addfile(info, io.BytesIO(data))
+    return p
+
+
+def _tgz(dist: Path, version="0.1.0", name="foxclaw", pkg=None, extra=()) -> Path:
+    p = dist / f"{name}-{version}.tgz"
+    payload = json.dumps(pkg if pkg is not None else
+                         {"name": name, "version": version}).encode()
+    with tarfile.open(p, "w:gz") as t:
+        for arc, data in (("package/package.json", payload),
+                          ("package/index.js", b"export default {}"),
+                          *[(e, b"x") for e in extra]):
+            info = tarfile.TarInfo(arc)
+            info.size = len(data)
+            t.addfile(info, io.BytesIO(data))
+    return p
+
+
+def _mini_repo(root: Path, version: str, npm_version: str) -> Path:
+    """只含四处版本来源的最小仓库,用来测"漏改一处"。"""
+    (root / "foxclaw").mkdir(parents=True)
+    (root / "npm").mkdir()
+    (root / "pyproject.toml").write_text(
+        f'[project]\nname = "foxclaw"\nversion = "{version}"\n', encoding="utf-8")
+    (root / "foxclaw" / "__init__.py").write_text(
+        f'__version__ = "{version}"\n', encoding="utf-8")
+    (root / "npm" / "package.json").write_text(
+        json.dumps({"name": "foxclaw", "version": npm_version}), encoding="utf-8")
+    (root / "npm" / "index.js").write_text(
+        f'export const version = "{npm_version}";\n', encoding="utf-8")
+    return root
+
+
+# ── 版本与 tag ────────────────────────────────────────────
+
+def test_repo_versions_are_consistent():
+    """真仓库当前状态:四处一致,无 error。"""
+    assert [i for i in rc.check_versions(REPO) if i.level == "error"] == []
+
+
+def test_single_missed_source_is_an_error(tmp_path):
+    root = _mini_repo(tmp_path, "0.2.0", npm_version="0.1.0")
+    errs = [i for i in rc.check_versions(root) if i.level == "error"]
+    assert errs and any("npm" in i.msg for i in errs), errs
+
+
+def test_unreadable_source_is_an_error(tmp_path):
+    root = _mini_repo(tmp_path, "0.1.0", "0.1.0")
+    (root / "npm" / "index.js").write_text("// 没有导出\n", encoding="utf-8")
+    assert any(i.code == "unreadable" for i in rc.check_versions(root))
+
+
+@pytest.mark.parametrize("tag", ["v0.1.0", "0.1.0"])
+def test_tag_matching_version_passes(tag):
+    assert rc.check_tag(tag, "0.1.0") == []
+
+
+@pytest.mark.parametrize("tag", ["v0.2.0", "v0.1.0-rc1"])
+def test_tag_drift_is_an_error(tag):
+    errs = rc.check_tag(tag, "0.1.0")
+    assert errs and errs[0].code == "tag_mismatch"
+
+
+def test_empty_tag_is_skipped():
+    assert rc.check_tag("", "0.1.0") == []
+
+
+# ── 项目页正文(long_description)────────────────────────────
+
+def test_repo_declares_readme():
+    """真仓库必须声明正文:0.1.1 在 PyPI 上的项目页就是空白的,这就是回归点。"""
+    assert [i for i in rc.check_metadata(REPO) if i.level == "error"] == []
+    assert rc.readme_target(REPO).endswith(".md")
+
+
+def test_missing_readme_is_error(tmp_path):
+    root = _mini_repo(tmp_path, "0.1.0", "0.1.0")
+    assert any(i.code == "no_readme" for i in rc.check_metadata(root))
+
+
+def test_short_readme_is_error(tmp_path):
+    root = _mini_repo(tmp_path, "0.1.0", "0.1.0")
+    (root / "pyproject.toml").write_text(
+        '[project]\nname = "foxclaw"\nversion = "0.1.0"\nreadme = "README.md"\n',
+        encoding="utf-8")
+    (root / "README.md").write_text("短\n", encoding="utf-8")
+    assert any(i.code == "readme_too_short" for i in rc.check_metadata(root))
+
+
+def test_readme_pointing_to_missing_file_is_error(tmp_path):
+    root = _mini_repo(tmp_path, "0.1.0", "0.1.0")
+    (root / "pyproject.toml").write_text(
+        '[project]\nname = "foxclaw"\nversion = "0.1.0"\nreadme = "NOPE.md"\n',
+        encoding="utf-8")
+    assert any(i.code == "readme_missing" for i in rc.check_metadata(root))
+
+
+# ── 归档内容 ──────────────────────────────────────────────
+
+@pytest.mark.parametrize("entry", [
+    "foxclaw/.env",
+    "foxclaw/.env.local",
+    "foxclaw-0.1.0/docs/internal/secret.md",
+    "foxclaw/foxclaw_data/sessions.db",
+    "foxclaw/old.zip",
+    "foxclaw/__pycache__/x.pyc",
+    "foxclaw/.venv/lib/x.py",
+])
+def test_forbidden_entries_detected(entry):
+    assert rc.forbidden_entry(entry), entry
+
+
+@pytest.mark.parametrize("entry", [
+    "foxclaw/.env.example",     # 模板必须能进包
+    "foxclaw/cli.py",
+    "foxclaw/vendor/hmr/hmr/__init__.py",
+])
+def test_allowed_entries_pass(entry):
+    assert rc.forbidden_entry(entry) is None
+
+
+# ── dist / npm ────────────────────────────────────────────
+
+def test_check_dist_passes_with_vendor_warning_only(tmp_path):
+    dist = tmp_path / "dist"
+    dist.mkdir()
+    _wheel(dist)
+    _sdist(dist)
+    issues = rc.check_dist(dist, "foxclaw", "0.1.0")
+    assert [i for i in issues if i.level == "error"] == []
+    assert any(i.code == "no_vendor" for i in issues), "缺 vendor 应显式提示"
+
+
+def test_check_dist_flags_missing_wheel(tmp_path):
+    dist = tmp_path / "dist"
+    dist.mkdir()
+    _sdist(dist)
+    assert any(i.code == "wheel_count" for i in rc.check_dist(dist, "foxclaw", "0.1.0"))
+
+
+def test_check_dist_flags_version_drift_in_filename(tmp_path):
+    dist = tmp_path / "dist"
+    dist.mkdir()
+    _wheel(dist, version="0.2.0")
+    _sdist(dist, version="0.1.0")
+    codes = {i.code for i in rc.check_dist(dist, "foxclaw", "0.1.0")}
+    assert "wheel_name" in codes or "meta_mismatch" in codes, codes
+
+
+def test_check_dist_flags_secret_inside_archive(tmp_path):
+    dist = tmp_path / "dist"
+    dist.mkdir()
+    _wheel(dist, extra=(".env",))
+    _sdist(dist)
+    msgs = [i.msg for i in rc.check_dist(dist, "foxclaw", "0.1.0")
+            if i.code == "forbidden_entry"]
+    assert msgs and any(".env" in m for m in msgs), msgs
+
+
+def test_check_dist_flags_empty_long_description(tmp_path):
+    dist = tmp_path / "dist"
+    dist.mkdir()
+    _wheel(dist, description=False)
+    _sdist(dist)
+    codes = {i.code for i in rc.check_dist(dist, "foxclaw", "0.1.0")}
+    assert "no_long_description" in codes, codes
+
+
+def test_check_dist_missing_dir_is_error(tmp_path):
+    assert any(i.code == "no_dist"
+               for i in rc.check_dist(tmp_path / "nope", "foxclaw", "0.1.0"))
+
+
+def test_npm_tgz_ok(tmp_path):
+    assert rc.check_npm_tgz(_tgz(tmp_path), "foxclaw", "0.1.0") == []
+
+
+def test_npm_tgz_name_drift_detected(tmp_path):
+    tgz = _tgz(tmp_path, pkg={"name": "foxclaw", "version": "0.2.0"})
+    codes = {i.code for i in rc.check_npm_tgz(tgz, "foxclaw", "0.1.0")}
+    assert "npm_meta" in codes, codes
+
+
+def test_npm_tgz_filename_drift_detected(tmp_path):
+    tgz = _tgz(tmp_path, version="0.2.0")
+    assert any(i.code == "npm_name" for i in rc.check_npm_tgz(tgz, "foxclaw", "0.1.0"))
+
+
+def test_run_end_to_end(tmp_path):
+    """run() 串起来:真仓库 + 构造的 dist/tgz,无 tag 也应通过。"""
+    dist = tmp_path / "dist"
+    dist.mkdir()
+    issues = rc.run(REPO, tag="", dist=dist, npm_tgz=None)
+    assert any(i.level == "error" for i in issues), "空 dist 应报错"
+    # 版本号跟着仓库走:写死 0.1.0 会在每次改版本时假红
+    version = rc.collect_versions(REPO)["pyproject.toml:project.version"]
+    _wheel(dist, version=version)
+    _sdist(dist, version=version)
+    tgz = _tgz(dist, version=version)
+    assert [i for i in rc.run(REPO, f"v{version}", dist, tgz) if i.level == "error"] == []
+    shutil.rmtree(dist)