foxclaw 0.1.0 → 0.1.2

package/python/tests/test_secrets.py

@@ -0,0 +1,159 @@
+"""本地密钥存储: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")
+
+
+# ── 写入侧:JSON 里放什么 ─────────────────────────────────────
+
+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),     # 存 keyring
+    ({"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        # Fail 后端等同「没有可用凭据库」
+        secrets.available()
+        assert len(calls) == 1                     # 探测结果被缓存,不反复 import
+    finally:
+        secrets.reset_probe()

package/python/tests/test_semantic.py

@@ -0,0 +1,78 @@
+"""真语义检索 + 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"   # HMR 在用,进程缓存里通常有;保证离线可测
+    from hkc_search.embedding_backends import get_st_model
+
+    print("=" * 60); print("真语义检索 + KEE 语义化验证"); print("=" * 60)
+
+    # [0] 否定词不再子串误命中(不依赖模型,总能测):badge⊅bad-word, know⊅no-word
+    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")
+
+    # [0b] 语义方向阈值接线:默认 0.30(与既有硬编码一致,behavior-preserving)+ 可经构造参数配置
+    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 降级兜底)")
+        # 两种运行方式都要正确退出(M7):
+        #   · 被 pytest 收集 → pytest.skip(allow_module_level) 是标准做法
+        #   · 被 run_all.py 当脚本直跑 → pytest.skip 抛 Skipped 会让脚本非零退出,
+        #     反而把「跳过」变成「失败」。故按 __name__ 区分。
+        if __name__ != "__main__":
+            import pytest
+            pytest.skip("all-MiniLM 未缓存 → 真语义验证跳过(auto/keyword 降级兜底)",
+                        allow_module_level=True)
+        sys.exit(0)
+
+    # 1) 共享缓存单例:同名只加载一次
+    assert get_st_model(MODEL) is m, "同名应共享同一实例(单例)"
+    print("[1] get_st_model 同名单例 OK")
+
+    # 2) LocalSTBackend 真余弦:相近 > 无关
+    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")
+
+    # 3) KEE _SimpleEmbedder 语义方向(指向缓存模型)
+    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,91 @@
+"""
+会话存储回归测试(全离线)。
+
+覆盖:建/列/读/追加/改名/删、标题自动提炼、按更新时间倒序、
+列表不含 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"])

package/python/tests/test_settings.py

@@ -0,0 +1,281 @@
+"""配置校验(core/settings.py)的行为测试。
+
+立这些档的目的是让"配置错时的提示"本身成为被测试的对象:它比崩溃更容易腐坏 ——
+提示错了没人会发现,只会让用户在错误的方向上改。
+"""
+import json
+
+import pytest
+
+from foxclaw import cli
+from foxclaw.core import settings
+
+
+@pytest.fixture(autouse=True)
+def _reset_warned(monkeypatch):
+    # _warned 是进程级的"只喊一次"账本,测试之间必须清,否则 get_safe 的日志断言会串
+    monkeypatch.setattr(settings, "_warned", set())
+
+
+# ── 类型化读取 ───────────────────────────────────────────────────────────
+def test_get_int_reads_value(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_PORT", "9001")
+    assert settings.get_int("FOXCLAW_PORT") == 9001
+
+
+def test_get_int_blank_means_default(monkeypatch):
+    # `.env` 里写 `FOXCLAW_PORT=` 曾经会 int("") 崩掉;空串按未设置处理
+    monkeypatch.setenv("FOXCLAW_PORT", "   ")
+    assert settings.get_int("FOXCLAW_PORT") == 8000
+
+
+def test_get_int_unset_means_default(monkeypatch):
+    monkeypatch.delenv("FOXCLAW_PORT", raising=False)
+    assert settings.get_int("FOXCLAW_PORT") == 8000
+
+
+def test_get_int_bad_value_names_variable_and_caller(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_PORT", "80oo")
+    with pytest.raises(settings.ConfigError) as ei:
+        settings.get_int("FOXCLAW_PORT")
+    msg = str(ei.value)
+    assert "FOXCLAW_PORT" in msg and "80oo" in msg
+    assert "期望" in msg and "8000" in msg
+    # 调用点必须是本测试文件,否则用户还是不知道该去哪改
+    assert "test_settings.py" in msg
+
+
+def test_get_int_below_min(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_GATEWAY_RATE", "-5")
+    with pytest.raises(settings.ConfigError):
+        settings.get_int("FOXCLAW_GATEWAY_RATE")
+
+
+def test_fractional_timeout_allowed(monkeypatch):
+    # 工具超时可以小于 1 秒(tests/test_tool_parallel.py 就用 0.3 模拟慢工具)
+    monkeypatch.setenv("FOXCLAW_TOOL_TIMEOUT", "0.3")
+    assert settings.get_float("FOXCLAW_TOOL_TIMEOUT") == pytest.approx(0.3)
+
+
+def test_get_float_accepts_int_text(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_LLM_COOLDOWN", "30")
+    assert settings.get_float("FOXCLAW_LLM_COOLDOWN") == 30.0
+
+
+def test_get_safe_degrades_and_warns_once(monkeypatch, caplog):
+    monkeypatch.setenv("FOXCLAW_TRACE_SLOW_MS", "慢")
+    with caplog.at_level("WARNING", logger="foxclaw.config"):
+        assert settings.get_safe("FOXCLAW_TRACE_SLOW_MS") == 1000.0
+        assert settings.get_safe("FOXCLAW_TRACE_SLOW_MS") == 1000.0   # 第二次不重复喊
+    assert sum("FOXCLAW_TRACE_SLOW_MS" in r.message for r in caplog.records) == 1
+
+
+def test_get_safe_unknown_name_returns_default(monkeypatch):
+    monkeypatch.setenv("SOME_UNDECLARED_KNOB", "abc")
+    assert settings.get_safe("SOME_UNDECLARED_KNOB", "dflt") == "abc"    # str 恒可解析
+    assert settings.get_safe("NOT_SET_AT_ALL_X", 7) == 7
+
+
+# ── check():一次汇总所有问题 ─────────────────────────────────────────────
+def _clean(monkeypatch, *keys):
+    """清掉一组变量,避免宿主机上真实存在的键干扰断言。"""
+    for k in keys:
+        monkeypatch.delenv(k, raising=False)
+
+
+def test_check_flags_type_error_without_raising(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_PORT", "80oo")
+    issues = settings.check({"FOXCLAW_PORT": "80oo", "DEEPSEEK_API_KEY": "x"})
+    errs = [i for i in issues if i.level == "error"]
+    assert len(errs) == 1 and errs[0].code == "type" and errs[0].name == "FOXCLAW_PORT"
+    # 提示不该与消息重复(Exception 里已写"期望")
+    assert errs[0].hint == ""
+
+
+def test_check_collects_multiple_errors(monkeypatch):
+    env = {"FOXCLAW_PORT": "x", "FOXCLAW_GATEWAY_RATE": "y",
+           "DEEPSEEK_API_KEY": "k"}
+    names = {i.name for i in settings.check(env) if i.level == "error"}
+    assert {"FOXCLAW_PORT", "FOXCLAW_GATEWAY_RATE"} <= names
+
+
+def test_check_choice_error(monkeypatch):
+    issues = settings.check({"LLM_PROVIDER": "deepsek", "DEEPSEEK_API_KEY": "k"})
+    codes = {(i.code, i.name) for i in issues if i.level == "error"}
+    assert ("choice", "LLM_PROVIDER") in codes
+
+
+def test_check_clean_env_has_no_error():
+    assert [i for i in settings.check({"DEEPSEEK_API_KEY": "k"}) if i.level == "error"] == []
+
+
+def test_check_secret_value_is_masked_in_message():
+    # 密钥写错时不能把原文打进日志/终端
+    issues = settings.check({"LLM_PROVIDER": "openai", "OPENAI_API_KEY": " sk-live-1234567890 "})
+    msg = " ".join(i.message for i in issues)
+    assert "sk-live-1234567890" not in msg
+
+
+# ── 语义检查:选了 provider 却没 key ────────────────────────────────────
+def test_provider_without_key_is_error():
+    issues = settings.check({"LLM_PROVIDER": "deepseek", "ANTHROPIC_API_KEY": ""})
+    hit = [i for i in issues if i.code == "provider_key"]
+    assert hit and hit[0].level == "error" and hit[0].name == "DEEPSEEK_API_KEY"
+
+
+def test_provider_with_key_is_fine():
+    issues = settings.check({"LLM_PROVIDER": "deepseek", "DEEPSEEK_API_KEY": "k"})
+    assert not [i for i in issues if i.code == "provider_key"]
+
+
+def test_legacy_provider_name_also_checked():
+    issues = settings.check({"FOXCLAW_PROVIDER": "openai"})
+    assert [i for i in issues if i.code == "provider_key"]
+
+
+def test_no_key_at_all_is_warn_not_error():
+    issues = settings.check({})
+    hit = [i for i in issues if i.code == "no_llm"]
+    assert hit and hit[0].level == "warn"
+
+
+# ── 未知键:拼错的键必须被点名 + 给出正确写法 ────────────────────────────
+def test_typo_key_is_flagged_with_suggestion():
+    issues = settings.check({"DEEPSEEK_API_KEY": "k", "FOXCLAW_TOOL_TIMEOUTS": "60"})
+    hit = [i for i in issues if i.name == "FOXCLAW_TOOL_TIMEOUTS"]
+    assert hit and hit[0].code == "unknown_key"
+    assert "FOXCLAW_TOOL_TIMEOUT" in hit[0].hint
+
+
+def test_known_key_is_not_flagged():
+    issues = settings.check({"FOXCLAW_TOOL_TIMEOUT": "60", "DEEPSEEK_API_KEY": "k"})
+    assert not [i for i in issues if i.name == "FOXCLAW_TOOL_TIMEOUT"]
+
+
+def test_system_env_vars_are_not_flagged():
+    # 不是我们的命名空间就不该管(PATH/HOME 之类)
+    issues = settings.check({"PATH": "/usr/bin", "DEEPSEEK_API_KEY": "k"})
+    assert not [i for i in issues if i.name == "PATH"]
+
+
+def test_known_keys_covers_real_usage():
+    known = settings.known_keys()
+    for name in ("FOXCLAW_PORT", "FOXCLAW_TOOL_TIMEOUT", "DEEPSEEK_API_KEY",
+                 "FOXCLAW_CHANNEL_SIGNING_SECRET"):
+        assert name in known
+    assert "NOT_A_REAL_KEY_NAME" not in known
+
+
+# ── 组合矛盾 ────────────────────────────────────────────────────────────
+def test_signing_key_id_without_secret_warns():
+    issues = settings.check({"DEEPSEEK_API_KEY": "k",
+                             "FOXCLAW_CHANNEL_SIGNING_KEY_ID": "k2"})
+    assert [i for i in issues if i.code == "signing_pair"]
+
+
+def test_short_signing_secret_warns():
+    issues = settings.check({"DEEPSEEK_API_KEY": "k",
+                             "FOXCLAW_CHANNEL_SIGNING_SECRET": "short"})
+    assert [i for i in issues if i.code == "weak_secret"]
+
+
+def test_open_cors_without_api_key_warns():
+    issues = settings.check({"DEEPSEEK_API_KEY": "k", "FOXCLAW_CORS_ORIGINS": "*"})
+    assert [i for i in issues if i.code == "open_cors"]
+
+
+def test_gateway_off_with_api_key_warns():
+    issues = settings.check({"DEEPSEEK_API_KEY": "k", "FOXCLAW_API_KEY": "s3cret",
+                             "FOXCLAW_GATEWAY": "0"})
+    assert [i for i in issues if i.code == "gateway_off"]
+
+
+# ── 输出 / 脱敏 ─────────────────────────────────────────────────────────
+@pytest.mark.parametrize("value,expect", [("", "(空)"), ("abcd", "****"),
+                                          ("sk-1234567890", "sk******90")])
+def test_mask(value, expect):
+    assert settings.mask(value) == expect
+
+
+def test_is_secret_heuristics():
+    assert settings.is_secret("DEEPSEEK_API_KEY")
+    assert settings.is_secret("SOME_TOKEN_X")
+    assert settings.is_secret("AMAP_JS_SCODE")
+    assert not settings.is_secret("FOXCLAW_PORT")
+
+
+def test_format_issues_counts_and_limit():
+    issues = [settings.Issue("error", "type", f"K{i}", "m") for i in range(5)]
+    out = settings.format_issues(issues, limit=2)
+    assert "5 个错误" in out and "另有 3 条" in out
+
+
+def test_format_issues_clean():
+    assert "通过" in settings.format_issues([])
+
+
+def test_fatal_issues_only_type_and_choice():
+    issues = [settings.Issue("error", "type", "A", "m"),
+              settings.Issue("error", "provider_key", "B", "m"),
+              settings.Issue("warn", "type", "C", "m")]
+    assert [i.name for i in settings.fatal_issues(issues)] == ["A"]
+
+
+# ── CLI ─────────────────────────────────────────────────────────────────
+def test_cli_config_check_exit_code_on_error(monkeypatch, capsys):
+    monkeypatch.setenv("FOXCLAW_PORT", "80oo")
+    assert cli.main(["config", "check"]) == 1
+    out = capsys.readouterr().out
+    assert "FOXCLAW_PORT" in out and "80oo" in out
+
+
+def test_cli_config_check_clean_exit_zero(monkeypatch, capsys):
+    monkeypatch.setenv("DEEPSEEK_API_KEY", "k")
+    monkeypatch.delenv("FOXCLAW_PORT", raising=False)
+    assert cli.main(["config", "check"]) == 0
+    assert "配置检查" in capsys.readouterr().out
+
+
+def test_cli_config_check_json(monkeypatch, capsys):
+    monkeypatch.setenv("FOXCLAW_PORT", "80oo")
+    cli.main(["config", "check", "--json"])
+    data = json.loads(capsys.readouterr().out)
+    assert isinstance(data, list) and data[0]["name"] == "FOXCLAW_PORT"
+
+
+def test_cli_config_without_action_is_usage_error(capsys):
+    assert cli.main(["config"]) == 2
+    assert "config check" in capsys.readouterr().out
+
+
+def test_cli_config_show_masks_secrets(monkeypatch, capsys):
+    monkeypatch.setenv("DEEPSEEK_API_KEY", "sk-abcdef123456")
+    cli.main(["config", "show"])
+    out = capsys.readouterr().out
+    assert "sk-abcdef123456" not in out and "DEEPSEEK_API_KEY" in out
+
+
+def test_cli_config_show_reveal(monkeypatch, capsys):
+    monkeypatch.setenv("DEEPSEEK_API_KEY", "sk-abcdef123456")
+    cli.main(["config", "show", "--reveal"])
+    assert "sk-abcdef123456" in capsys.readouterr().out
+
+
+def test_serve_aborts_before_starting_on_bad_type(monkeypatch):
+    # 关键:拦在 uvicorn 之前 —— 否则用户看到的是 40 行 traceback 里的 int()
+    monkeypatch.setenv("FOXCLAW_PORT", "80oo")
+    args = cli.build_parser().parse_args(["serve"])
+    assert cli._cmd_serve(args) == 2
+
+
+def test_serve_semantic_warning_does_not_block(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_CORS_ORIGINS", "*")
+    monkeypatch.setenv("DEEPSEEK_API_KEY", "k")
+    args = cli.build_parser().parse_args(["serve"])
+    # 走到 uvicorn.run 之前就返回,说明没有 fatal(用假 uvicorn 防止真的起服务)
+    import sys
+    import types
+    fake = types.ModuleType("uvicorn")
+    fake.run = lambda *a, **k: None
+    monkeypatch.setitem(sys.modules, "uvicorn", fake)
+    assert cli._cmd_serve(args) == 0