foxclaw 0.1.0 → 0.1.2

package/python/tests/test_kee_semantic.py

@@ -0,0 +1,89 @@
+"""KEE 身份/去重:别名确定性匹配(「北平」aliases=['北京'] ↔「北京」归并)。
+别名替代向量语义近重:零模型依赖、零余弦误合并;Fact/Claim 用完整 statement 守 exact。
+无别名时退化为纯 exact,与旧版默认(关)行为一致。"""
+import sys, types
+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_kee_alias_dedup():
+    from hkc_kee.dedup import KnowledgeDeduplicator
+
+    class FakeKU:
+        def __init__(self, ku_id, ku_type, name, domain="", sources=None,
+                     aliases=None, statement=None):
+            self.ku_id = ku_id
+            self.ku_type = types.SimpleNamespace(value=ku_type)
+            self.name = name
+            self.domain = domain
+            self.sources = list(sources or [])
+            self.aliases = list(aliases or [])
+            self.statement = statement
+            self.confidence = 0.5
+
+    class FakeStore:
+        def __init__(self): self.kus = {}
+        def put(self, ku): self.kus[ku.ku_id] = ku
+        def get(self, i): return self.kus.get(i)
+        def query_all(self, limit=100000): return list(self.kus.values())
+        def redirect_relations(self, a, b): return 0
+
+    # [1] 别名正向归并:「北平」(aliases=['北京']) → 命中已有「北京」
+    store = FakeStore(); d = KnowledgeDeduplicator(store)
+    beijing = FakeKU("E1", "Entity", "北京", "", aliases=[])
+    store.put(beijing)
+    assert d.check_and_merge(beijing) is None, "首个应为新知识"
+    beiping = FakeKU("E2", "Entity", "北平", "", aliases=["北京"], sources=["EVD_A"])
+    store.put(beiping)
+    assert d.check_and_merge(beiping) == "E1", "别名应命中 canonical「北京」"
+    assert "EVD_A" in beijing.sources, "归并应把新证据并入存活 KU"
+    print("[1] 别名正向归并 OK")
+
+    # [2] 别名反向归并:已有「北平」(aliases=['北京']),新「北京」无别名 → 命中别名
+    store2 = FakeStore(); d2 = KnowledgeDeduplicator(store2)
+    beiping2 = FakeKU("E1", "Entity", "北平", "", aliases=["北京"])
+    store2.put(beiping2)
+    assert d2.check_and_merge(beiping2) is None
+    beijing2 = FakeKU("E2", "Entity", "北京", "", aliases=[])
+    store2.put(beijing2)
+    assert d2.check_and_merge(beijing2) == "E1", "新 KU 主名应命中已有 KU 的别名"
+    print("[2] 别名反向归并 OK")
+
+    # [3] 无别名 → 纯 exact:不同名不并
+    store3 = FakeStore(); d3 = KnowledgeDeduplicator(store3)
+    a = FakeKU("C1", "Concept", "value investing", "finance")
+    store3.put(a)
+    assert d3.check_and_merge(a) is None
+    b = FakeKU("C2", "Concept", "value investing strategy", "finance")
+    store3.put(b)
+    assert d3.check_and_merge(b) is None, "无别名时不同名不应归并(纯 exact)"
+    print("[3] 无别名纯 exact OK")
+
+    # [4] Fact 用完整 statement 守 exact:前 80 字符相同但完整陈述不同 → 不误并
+    store4 = FakeStore(); d4 = KnowledgeDeduplicator(store4)
+    stmt1 = "A" * 80 + "X"
+    stmt2 = "A" * 80 + "Y"
+    f1 = FakeKU("F1", "Fact", stmt1[:80], statement=stmt1)
+    store4.put(f1)
+    assert d4.check_and_merge(f1) is None
+    f2 = FakeKU("F2", "Fact", stmt2[:80], statement=stmt2)
+    store4.put(f2)
+    assert d4.check_and_merge(f2) is None, "前 80 字符相同但完整陈述不同,不应误并"
+    print("[4] Fact 完整 statement 守 exact OK")
+
+    # [5] 类型隔离:Entity 与 Concept 同名不并
+    store5 = FakeStore(); d5 = KnowledgeDeduplicator(store5)
+    ent = FakeKU("E", "Entity", "北京", "", aliases=[])
+    store5.put(ent)
+    assert d5.check_and_merge(ent) is None
+    con = FakeKU("C", "Concept", "北京", "地理")
+    store5.put(con)
+    assert d5.check_and_merge(con) is None, "Entity 与 Concept 同名不应归并(类型隔离)"
+    print("[5] 类型隔离 OK")
+
+    print("\nKEE 别名确定性去重验证通过")
+
+
+if __name__ == "__main__":
+    test_kee_alias_dedup()

package/python/tests/test_kernel.py

@@ -0,0 +1,222 @@
+"""
+内核新模块回归测试 — 覆盖 Codex 融合 + AHS 落地的全部新能力
+
+验证:
+  1. 认知调度器(意图/优先级/负载/抢占)
+  2. 进程状态机(生命周期/非法流转拦截/幂等)
+  3. 系统事件总线(发布订阅/历史)
+  4. 真值管线(执行→审计→记忆事件链)
+  5. 认知状态快照(聚合/去重/None防护)
+  6. 权限管线(四阶段 deny>ask>allow)
+  7. 断路器(连续失败开闸)+ 钩子
+  8. AHS 执行链(router→planner→composition 端到端)
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+def check(cond, msg):
+    if not cond:
+        raise AssertionError(f"✗ {msg}")
+    print(f"  ✓ {msg}")
+
+
+def test_scheduler():
+    print("\n【1】认知调度器")
+    from foxclaw.core.scheduler import CognitiveScheduler, SystemContext
+    sch = CognitiveScheduler()
+    d_reason = sch.schedule("帮我规划设计方案")
+    d_tool = sch.schedule("算一下 5+5")
+    check(d_reason.intent.category == "reasoning", "推理类意图识别")
+    check(d_tool.intent.category == "tool", "工具类意图识别")
+    check(d_reason.priority > d_tool.priority, "推理类优先级 > 工具类")
+    idle = sch.schedule("规划项目", SystemContext(active_agents=0, system_load=0.1))
+    busy = sch.schedule("规划项目", SystemContext(active_agents=4, queue_depth=3, system_load=0.8))
+    check(idle.priority > busy.priority, "高负载下优先级被压低")
+    preempt = sch.schedule("紧急规划重大项目", SystemContext(active_agents=3))
+    check(preempt.preemptible, "高优先级+Agent压力触发抢占")
+
+
+def test_process_manager():
+    print("\n【2】进程状态机")
+    from foxclaw.kernel import ProcessManager
+    pm = ProcessManager()
+    p = pm.create("任务", agent_id="finance", schedule={"priority": 0.5})
+    check(p.state == "scheduled", "创建后进入 scheduled")
+    check(pm.active_count() == 1, "活跃计数=1(create 后)")
+    pm.mark_running(p.process_id)
+    check(pm.active_count() == 1, "running 仍算活跃")
+    pm.mark_completed(p.process_id)
+    check(pm.active_count() == 0, "completed 后活跃计数归零(O(1) 增量)")
+    check(pm.get(p.process_id).state == "completed", "完整生命周期到 completed")
+    check(pm.get(p.process_id).state_history == ["created", "queued", "scheduled", "running", "completed"],
+          "状态历史完整")
+    # 幂等:已终态再标记不崩溃,且**不重复扣减**活跃计数
+    r = pm.mark_failed(p.process_id, "二次")
+    check(r is not None and r.state == "completed", "终态重复标记幂等不崩溃")
+    check(pm.active_count() == 0, "终态重复标记不重复扣减活跃计数(仍为0,不为负)")
+    # 非法流转拦截
+    p2 = pm.create("x", schedule={"priority": 0.1})
+    p2.state = "created"
+    try:
+        pm._transition(p2, "completed")
+        check(False, "非法流转应被拦")
+    except ValueError:
+        check(True, "非法流转(created→completed)被拦截")
+
+
+def test_system_bus():
+    print("\n【3】系统事件总线")
+    from foxclaw.core.system_bus import SystemBus
+    bus = SystemBus()
+    received = []
+    bus.subscribe("test.ch", lambda m: received.append(m.payload))
+    bus.publish("test.ch", {"x": 1})
+    check(received == [{"x": 1}], "发布订阅传递正确")
+    check(len(bus.history("test.ch")) == 1, "事件历史记录")
+
+
+def test_truth_pipeline():
+    print("\n【4】真值管线")
+    from foxclaw.core.system_bus import SystemBus
+    from foxclaw.core.truth_pipeline import TruthPipeline
+
+    class FakeHMR:
+        def __init__(self): self.items = []
+        def ingest(self, content, **kw): self.items.append(content)
+
+    bus = SystemBus()
+    hmr = FakeHMR()
+    tp = TruthPipeline(bus, hmr=hmr)
+    # 【P3-9】TruthPipeline.emit_execution 已删除:事件名即契约,直接经 bus 入队。
+    bus.publish("execution.completed", {"agent_id": "finance", "task": "分析预算",
+                                        "result": "预算正常", "blocked": False})
+    check(tp.last_trace is not None, "执行→审计 trace 生成")
+    check(len(hmr.items) == 1, "真值沉淀到记忆")
+    bus.publish("execution.completed", {"agent_id": "finance", "task": "危险",
+                                        "result": "x", "blocked": True})
+    check(not tp.last_memory_update.get("persisted"), "被拦截任务不沉淀记忆")
+
+
+def test_cognitive_state():
+    print("\n【5】认知状态快照")
+    from foxclaw.core.system_bus import SystemBus
+    from foxclaw.cognitive import CognitiveStateTracker
+    bus = SystemBus()
+    t = CognitiveStateTracker(bus)
+    bus.publish("execution.completed", {"task": "分析财务", "agent_id": "finance",
+                "schedule": {"intent": "reasoning", "route_hint": "agent", "priority": 0.4}})
+    s = t.snapshot()
+    check(s["active_goal"] == "分析财务", "活跃目标聚合")
+    check(s["semantic_focus"] == "reasoning", "语义焦点聚合")
+    # 去重
+    for _ in range(5):
+        bus.publish("memory.updated", {"memory_update": {"content": "同样"}})
+    check(len(t.snapshot()["activated_memories"]) == 1, "重复记忆去重")
+    # None 防护
+    class M: payload = None
+    t._on_exec(M())
+    check(True, "None payload 不崩溃")
+
+
+def test_permission():
+    print("\n【6】权限管线")
+    from foxclaw.skills import build_default_registry, SkillAdapter
+    from foxclaw.skills.permission import PermissionRules
+    reg = build_default_registry()
+    ad = SkillAdapter(reg)
+    calc = reg.get("calculator")
+    r = ad.invoke(calc, {"expression": "1+1"})
+    check(r.success, "只读 skill 放行")
+    gmail = reg.get("gmail_send")
+    r2 = ad.invoke(gmail, {"to": "x", "subject": "y", "body": "z"})
+    check(r2.status == "needs_confirmation", "发邮件未确认被拦")
+    rules = PermissionRules(deny=["gmail_send"])
+    ad2 = SkillAdapter(reg, rules=rules)
+    r3 = ad2.invoke(gmail, {"to": "x", "subject": "y", "body": "z"}, confirmed=True)
+    check(r3.status == "blocked", "deny 铁律压倒已确认")
+
+
+def test_trust_single_source():
+    """【P6】信任分级单一真源:permission 复用 SkillSpec.trust_level(),不再有第二套 dict。
+    此前 permission.TRUST_LEVEL 与 trust_level() 重复(且含死 key bundled/remote)——对 3 个合法
+    SkillKind 二者 downgrade 行为本就一致(latent,非 live bug),本次收敛为单一真源、行为不变。"""
+    print("\n【6b】信任分级单一真源(P6):permission 复用 trust_level(),删死字典")
+    from foxclaw.skills import SkillSpec
+    from foxclaw.skills import permission as perm
+    from foxclaw.skills.permission import evaluate
+    check(not hasattr(perm, "TRUST_LEVEL"), "permission.TRUST_LEVEL 死字典已删(不再双真源)")
+    # 3 个合法 kind × 两种 source:permission 的 downgrade 恒等于 (trust_level()=='low'),且行为不变
+    expect = {"local": False, "web_api": False, "mcp": True}   # behavior-preserving 基线
+    for kind, want_dg in expect.items():
+        for source in ("builtin", "user"):
+            s = SkillSpec(id=f"s_{kind}_{source}", name="t", description="d",
+                          kind=kind, side_effect="read", source=source)
+            d = evaluate(s, {})
+            check(d.trust_downgrade == (s.trust_level() == "low"),
+                  f"{kind}/{source}: downgrade 严格跟随 trust_level()(单一真源)")
+            check(d.trust_downgrade == want_dg,
+                  f"{kind}: downgrade={want_dg}(重构前后一致)")
+    print("    结论:全部合法 kind 行为不变 + 双真源分歧点已消除")
+
+
+def test_breaker_hooks():
+    print("\n【7】断路器 + 钩子")
+    from foxclaw.skills import SkillRegistry, SkillSpec, SkillAdapter
+    from foxclaw.skills.lifecycle import CircuitBreaker, HookManager
+    reg = SkillRegistry()
+    reg.register(SkillSpec(id="flaky", name="易碎", description="总失败",
+                 kind="local", side_effect="read", handler=lambda **k: (_ for _ in ()).throw(RuntimeError("boom"))))
+    ad = SkillAdapter(reg, breaker=CircuitBreaker(threshold=3))
+    for _ in range(3):
+        ad.invoke(reg.get("flaky"), {})
+    check(ad.breaker.status("flaky")["state"] == "open", "连续失败3次断路器开闸")
+    r = ad.invoke(reg.get("flaky"), {})
+    check(r.status == "circuit_open", "开闸后停止调用")
+    # 钩子
+    log = []
+    hm = HookManager()
+    hm.register("pre_skill", lambda ctx: log.append("pre"))
+    hm.register("post_skill", lambda ctx: log.append("post"))
+    reg.register(SkillSpec(id="good", name="好", description="成功",
+                 kind="local", side_effect="read", handler=lambda **k: {"ok": 1}))
+    ad2 = SkillAdapter(reg, hooks=hm)
+    ad2.invoke(reg.get("good"), {})
+    check(log == ["pre", "post"], "钩子 pre→post 顺序")
+
+
+def test_ahs_pipeline():
+    print("\n【8】AHS 执行链")
+    from foxclaw.skills import build_default_registry, SkillAdapter
+    from foxclaw.skills.pipeline import AHSPipeline, route, plan
+    reg = build_default_registry()
+    ad = SkillAdapter(reg)
+    pipe = AHSPipeline(reg, ad)
+    # router 否定词
+    r = route("不要计算", reg)
+    check(r.primary != "calculator", "否定词检测:不要计算→不选calculator")
+    # planner 拆解
+    p = plan("先算 5+5 然后再算 9*9", reg)
+    check(len(p.tasks) == 2, "planner 多步拆解")
+    # 端到端
+    res = pipe.run("帮我算一下 12*12")
+    check(res.success, "AHS 执行链端到端成功")
+
+
+def main():
+    print("=" * 60)
+    print("内核新模块回归测试")
+    print("=" * 60)
+    tests = [test_scheduler, test_process_manager, test_system_bus,
+             test_truth_pipeline, test_cognitive_state, test_permission,
+             test_breaker_hooks, test_ahs_pipeline, test_trust_single_source]
+    for t in tests:
+        t()
+    print("\n" + "=" * 60)
+    print("✓ 内核新模块全部通过")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_learning.py

@@ -0,0 +1,110 @@
+"""
+B 阶段测试 — office Agent 学习内核(学习行为操作系统)
+验证:采集 → 间隔重复(固化) → 知识图谱(连接) → 学习策略
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.learning import LearningRuntime
+
+CSV = str(Path(__file__).parent.parent / "examples" / "sample_knowledge.csv")
+
+
+def check(cond, msg):
+    if not cond:
+        raise AssertionError(f"✗ {msg}")
+    print(f"  ✓ {msg}")
+
+
+def main():
+    print("=" * 60)
+    print("B 阶段 · office Agent 学习内核(学习行为操作系统)")
+    print("=" * 60)
+
+    rt = LearningRuntime()
+    n = rt.import_csv(CSV)
+    print(f"\n采集 {n} 个知识点")
+    check(n == 8, f"采集 8 个知识点(实为 {n})")
+
+    # 1. 间隔重复:模拟几次复习
+    print("\n【固化:间隔重复】")
+    ids = list(rt.items.keys())
+    check(len(ids) >= 4, f"至少 4 个知识点可供复习(实为 {len(ids)})")
+    # 模拟:前两个记得好,第三个记不住
+    rt.review(ids[0], grade=5)  # 完美
+    rt.review(ids[0], grade=4)
+    rt.review(ids[1], grade=4)
+    rt.review(ids[2], grade=1)  # 没记住
+    rt.review(ids[2], grade=2)  # 又没记住
+    for iid in ids[:4]:
+        st = rt.review_states[iid]
+        item = rt.items[iid]
+        print(f"  掌握度 {st.mastery:.2f} | 间隔 {st.interval}天 | "
+              f"复习{st.total_reviews}次 遗忘{st.lapses}次 | {item.content[:24]}...")
+    # SM-2 的语义后果:连续答不好应累积 lapses,且掌握度被压低。
+    # 这是"间隔重复真的在起作用"的核心断言 —— 只打印 0.60/0.11 两个数字不算验证。
+    st_good, st_bad = rt.review_states[ids[0]], rt.review_states[ids[2]]
+    check(st_bad.lapses == 2, f"连错两次的知识点累积 lapses=2(实为 {st_bad.lapses})")
+    check(st_bad.mastery < st_good.mastery,
+          f"记得差的掌握度低于记得好的({st_bad.mastery:.2f} < {st_good.mastery:.2f})")
+    check(st_good.total_reviews == 2 and st_bad.total_reviews == 2,
+          "复习次数被正确累计(各 2 次)")
+
+    # 2. 知识图谱:构建连接
+    print("\n【连接:知识图谱】")
+    conn = rt.build_connections(semantic_threshold=0.5)
+    print(f"  同主题边: {conn['topic_edges']} · 语义边: {conn['semantic_edges']}")
+    g = conn["graph"]
+    print(f"  图谱: {g['items']} 节点, {g['edges']} 边, "
+          f"{g['clusters']} 个知识簇")
+    print(f"  边类型: {g['edge_types']}")
+    check(conn["topic_edges"] > 0, f"同主题连接已建立({conn['topic_edges']} 条)")
+    check(g["items"] == n, f"图谱节点数 = 知识点数({g['items']} == {n})")
+    # 结构不变式:总边数必须等于各类边之和,否则说明有一类边被漏计/重复计
+    check(g["edges"] == conn["topic_edges"] + conn["semantic_edges"],
+          f"总边数 = 同主题边 + 语义边({g['edges']} == {conn['topic_edges']}+{conn['semantic_edges']})")
+    check(g["clusters"] > 0, f"聚类非空({g['clusters']} 个知识簇)")
+
+    # 3. 连接发现:某知识点的关联
+    print("\n【连接发现】")
+    related = rt.related(ids[0])
+    base = rt.items[ids[0]].content[:20]
+    print(f"  与「{base}...」相关的知识:")
+    for r in related[:4]:
+        print(f"    [{r['edge_type']}/{r['weight']}] {r['item']['content'][:24]}... ({r['reason']})")
+    check(len(related) >= 1, f"「{base}…」找到 {len(related)} 条关联知识")
+    check(all(("edge_type" in x and "weight" in x and "item" in x) for x in related),
+          "每条关联都带 edge_type / weight / item 结构")
+
+    # 4. 综合分析
+    print("\n【综合分析】")
+    rep = rt.analyze()
+    print(f"  知识点 {rep['total_items']} · 平均掌握度 {rep['avg_mastery']}")
+    print(f"  主题掌握度: {rep['topic_mastery']}")
+    print(f"  最薄弱主题: {rep['weakest_topic']}")
+    print(f"  遗忘风险: {len(rep['forgetting_risk'])} 个高风险知识点")
+    check(rep["total_items"] == n, f"报告覆盖全部知识点({rep['total_items']} == {n})")
+    check(0 < rep["avg_mastery"] <= 1, f"平均掌握度落在 (0,1](实为 {rep['avg_mastery']})")
+    check(rep["weakest_topic"] in rep["topic_mastery"],
+          f"最薄弱主题来自主题掌握度表(weakest_topic={rep['weakest_topic']})")
+
+    # 5. 学习策略裁决
+    print("\n【学习策略裁决】")
+    for v in rep["strategy"]:
+        print(f"  [{v['action']}] {v['message']}")
+    check(len(rep["strategy"]) >= 1, f"产出 {len(rep['strategy'])} 条学习策略")
+    check(all(("action" in v and "message" in v) for v in rep["strategy"]),
+          "每条策略都含 action / message")
+
+    print("\n" + "=" * 60)
+    print("✓ B 阶段验证完成:学习内核(间隔重复 + 知识图谱)成立")
+    print("=" * 60)
+
+
+def test_learning():
+    main()
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_llm_admin.py

@@ -0,0 +1,160 @@
+"""LLM 模型管理「自定义模型填不上」回归测试。
+
+覆盖三条曾经真实踩过的坑:
+1. BASE URL 没写 /v1 → SDK 拼出 /chat/completions → 网关 404/401(用户以为"填不上")
+2. 保存了自定义模型但**没切换** → 聊天仍走 .env 旧 provider → AuthenticationError + stub
+3. provider="custom" 不在 ``_OPENAI_FAMILY`` → stream() 退化为一次性输出、工具能力静默关闭
+
+全离线:不联网、不加载嵌入模型(provider=stub 起 router)。
+"""
+import os, sys, json, tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+# ── 环境隔离:必须在 import foxclaw 之前 ──────────────────────────────
+for _k in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "DEEPSEEK_API_KEY", "GOOGLE_API_KEY",
+           "DASHSCOPE_API_KEY", "MINIMAX_API_KEY", "LLM_API_KEY", "FOXCLAW_API_KEY"):
+    os.environ.pop(_k, None)
+os.environ["HKC_EMBEDDING"] = "stub"
+os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_llmadmin_")
+os.environ["FOXCLAW_SKIP_DOTENV"] = "1"
+os.environ["FOXCLAW_PROVIDER"] = ""
+os.environ["FOXCLAW_MODEL"] = ""
+os.environ["FOXCLAW_MCP_SERVER"] = "0"
+os.environ["HF_HUB_OFFLINE"] = "1"
+os.environ["TRANSFORMERS_OFFLINE"] = "1"
+
+import pytest
+from fastapi import HTTPException
+
+from foxclaw.core.model_router import ModelRouter, normalize_base_url
+import foxclaw.api as _api
+from foxclaw.api.routes import llm_admin
+
+
+# ── 1. BASE URL 规范化 ───────────────────────────────────────────────
+
+@pytest.mark.parametrize("raw,expected", [
+    ("https://api.deepseek.com",            "https://api.deepseek.com/v1"),
+    ("https://api.deepseek.com/",           "https://api.deepseek.com/v1"),
+    ("https://api.deepseek.com/v1",         "https://api.deepseek.com/v1"),
+    ("https://api.deepseek.com/v1/",        "https://api.deepseek.com/v1"),
+    ("  https://api.openai.com/v1  ",       "https://api.openai.com/v1"),
+    ("api.deepseek.com",                    "https://api.deepseek.com/v1"),   # 漏 scheme
+    ("api.deepseek.com/v1",                 "https://api.deepseek.com/v1"),
+    # 已有非 /v1 的 path 必须原样保留(通义兼容模式 / 自建网关 /openai/v1)
+    ("https://dashscope.aliyuncs.com/compatible-mode/v1",
+     "https://dashscope.aliyuncs.com/compatible-mode/v1"),
+    ("http://localhost:11434/v1",           "http://localhost:11434/v1"),
+    ("http://127.0.0.1:8080/openai/v1",     "http://127.0.0.1:8080/openai/v1"),
+])
+def test_normalize_base_url(raw, expected):
+    assert normalize_base_url(raw) == expected
+    # 幂等:规范化两次结果不变(前端 blur + 后端保存 + router 构造都会过一遍)
+    assert normalize_base_url(expected) == expected
+
+
+@pytest.mark.parametrize("bad", ["", "   ", "ftp://example.com", "https://"])
+def test_normalize_base_url_rejects(bad):
+    with pytest.raises(ValueError):
+        normalize_base_url(bad)
+
+
+# ── 2. custom 必须被当作 openai-compatible 家族成员 ──────────────────
+
+def test_custom_is_openai_family():
+    assert "custom" in ModelRouter._OPENAI_FAMILY, \
+        "custom 漏了会让流式退化为一次性输出、工具能力静默关闭"
+    assert "custom" in ModelRouter._TOOL_PROVIDERS
+
+
+def test_custom_provider_supports_tools():
+    r = ModelRouter(provider="stub")
+    r.provider = "custom"
+    r._client = object()          # 假装已构造好(不联网)
+    assert r.supports_tools() is True
+
+
+# ── 3. stream() 必须 reload 选择(聊天主路径)─────────────────────────
+
+def test_stream_reloads_selection():
+    r = ModelRouter(provider="stub")
+    hits = []
+    r._maybe_reload_selection = lambda: hits.append(True)   # 不打真实文件
+    list(r.stream("sys", [{"role": "user", "content": "hi"}]))
+    assert hits, "stream() 未调用 _maybe_reload_selection → 切模型后流式对话不生效"
+
+
+# ── 4. 保存 / 切换端点 ───────────────────────────────────────────────
+
+@pytest.fixture()
+def fresh_store(monkeypatch):
+    """每个用例一份干净的 custom_models.json + .current_model。"""
+    d = Path(tempfile.mkdtemp(prefix="llm_admin_store_"))
+    # router 侧按 env 现算路径(_custom_models_path / _selection_path),必须一起指过来,
+    # 否则端点写 A 目录、router 读 B 目录 → 预检假失败。
+    monkeypatch.setenv("FOXCLAW_DATA_DIR", str(d))
+    monkeypatch.setattr(llm_admin, "CUSTOM_MODELS_PATH", d / "custom_models.json")
+    monkeypatch.setattr(llm_admin, "CURRENT_MODEL_PATH", d / ".current_model")
+    yield d
+
+
+def _add(name="deepseek", base="https://api.deepseek.com", key="sk-test", model="deepseek-chat"):
+    import asyncio
+    return asyncio.run(llm_admin.add_custom_model(
+        llm_admin._CustomAddReq(name=name, base_url=base, api_key=key, model=model)))
+
+
+def test_add_normalizes_base_url(fresh_store):
+    _add(base="https://api.deepseek.com")
+    saved = json.loads((fresh_store / "custom_models.json").read_text(encoding="utf-8"))
+    assert saved[0]["base_url"] == "https://api.deepseek.com/v1"
+
+    # 更新时同样规范化
+    import asyncio
+    asyncio.run(llm_admin.update_custom_model("deepseek", llm_admin._CustomUpdateReq(
+        base_url="https://api.deepseek.com")))
+    saved = json.loads((fresh_store / "custom_models.json").read_text(encoding="utf-8"))
+    assert saved[0]["base_url"] == "https://api.deepseek.com/v1"
+
+
+def test_add_rejects_bad_base_url(fresh_store):
+    with pytest.raises(HTTPException) as ei:
+        _add(base="ftp://example.com")
+    assert ei.value.status_code == 400
+
+
+def test_select_custom_takes_effect_immediately(fresh_store, monkeypatch):
+    """核心回归:保存后 point 到它必须真的把 router 切过去。"""
+    _add()
+    router = ModelRouter(provider="stub")
+
+    class _FakeOS:
+        pass
+    fake = _FakeOS()
+    fake.router = router
+    monkeypatch.setattr(_api, "_os_instance", fake, raising=False)
+
+    import asyncio
+    out = asyncio.run(llm_admin.select_model(
+        llm_admin._SelectReq(source="custom", name="deepseek")))
+
+    assert out["current"]["name"] == "deepseek"
+    assert out["runtime"]["provider"] == "custom"
+    assert out["runtime"]["model"] == "deepseek-chat"
+    assert router.provider == "custom" and router.model == "deepseek-chat"
+    # .current_model 落盘,重启后 lazy reload 仍能读到
+    cur = json.loads((fresh_store / ".current_model").read_text(encoding="utf-8"))
+    assert cur["source"] == "custom" and cur["name"] == "deepseek"
+
+
+def test_select_missing_custom_404(fresh_store):
+    import asyncio
+    with pytest.raises(HTTPException) as ei:
+        asyncio.run(llm_admin.select_model(
+            llm_admin._SelectReq(source="custom", name="nope")))
+    assert ei.value.status_code == 404
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-q"]))