foxclaw 0.1.0 → 0.1.2

package/python/tests/test_event_spine.py

@@ -0,0 +1,182 @@
+"""
+统一事件脊柱(EventSpine, P0 第二项)测试 —— 全离线。
+
+覆盖:
+  1. EventSpine:发布/订阅(前缀匹配) + 投影(收到每条) + 有界历史
+  2. SystemBus 门面:退化为脊柱门面后,既有消费者零改;系统事件汇入脊柱
+  3. Harness → 脊柱转发:harness 事件汇入脊柱;高频内部信号(goal_registered)不上脊柱
+  4. Foxclaw 统一投影:harness 事件与系统事件都被**同一个投影**观测(核心统一验证)
+
+为避免加载 7s 重模型,harness embedding 用不存在的模型名 → 降级 hash(不影响事件验证)。
+"""
+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"   # harness 走 hash,快
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.kernel import EventSpine
+
+
+def test_spine_pubsub_prefix_projection():
+    print("\n【1】EventSpine:前缀订阅 + 投影 + 历史")
+    spine = EventSpine()
+    got = []
+    spine.subscribe("harness", lambda e: got.append(e.topic))   # 前缀订阅
+    allseen = []
+    spine.project(lambda e: allseen.append(e.topic))            # 投影:收到每条
+    spine.publish("harness.drift.blocked", {"x": 1})
+    spine.publish("memory.ingested", {"y": 2})
+    assert got == ["harness.drift.blocked"], "前缀 'harness' 应只命中 harness.*"
+    assert allseen == ["harness.drift.blocked", "memory.ingested"], "投影应收到每一条"
+    assert len(spine.history()) == 2 and len(spine.history("harness")) == 1
+    print("  ✓ 前缀匹配正确;投影全量;历史可按前缀过滤")
+
+
+def test_systembus_facade():
+    print("\n【2】SystemBus 门面:消费者零改 + 汇入脊柱")
+    from foxclaw.core.system_bus import SystemBus
+    spine = EventSpine()
+    seen = []
+    spine.project(lambda e: seen.append((e.topic, e.source)))
+    bus = SystemBus(spine=spine)
+    got = []
+    bus.subscribe("execution.completed", lambda m: got.append(m.payload))  # 旧式 handler(msg)
+    bus.publish("execution.completed", {"task": "t"})
+    assert got == [{"task": "t"}], "旧消费者 handler(msg) 仍收到 .payload"
+    assert ("execution.completed", "system_bus") in seen, "系统事件应汇入同一脊柱"
+    assert bus.history("execution.completed"), "history 门面可用"
+    print("  ✓ handler(msg) 兼容;系统事件经脊柱;history 正常")
+
+
+def test_harness_forwards_to_spine():
+    print("\n【3】Harness → 脊柱转发(goal_registered 不上脊柱)")
+    from foxclaw.harness.harness import Harness
+    from foxclaw.core.thought_chain import ThoughtChain
+    d = tempfile.mkdtemp(prefix="spine_h_")
+    try:
+        spine = EventSpine()
+        seen = []
+        spine.project(lambda e: seen.append(e.topic))
+        h = Harness("tester", ThoughtChain(str(Path(d) / "tc.db")),
+                    policy_path=str(Path(d) / "p.yaml"), spine=spine)
+        local = []
+        h.bus.on("harness_warn", lambda data: local.append(data))   # 本地订阅仍工作
+        h.bus.emit("harness_warn", {"a": 1})     # harness_warn 无内部自订阅,输出干净
+        h.bus.emit("goal_registered", {"g": 1})
+        assert local == [{"a": 1}], "本地订阅(向后兼容)仍收到"
+        assert "harness_warn" in seen, "harness 事件应汇入脊柱"
+        assert "goal_registered" not in seen, "高频内部信号不应上脊柱(降噪)"
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+    print("  ✓ 本地订阅兼容 + harness 汇入脊柱 + goal_registered 被过滤")
+
+
+def test_hkc_events_bridge_to_spine():
+    print("\n【3b】HKC EventBus → 脊柱桥接(知识事件不再是孤岛;memory.* 刻意不桥)")
+    from foxclaw.knowledge import bridge_hkc_events
+
+    class _FakeHKCBus:
+        def __init__(self): self._h = {}
+        def subscribe(self, ev, h): self._h.setdefault(ev, []).append(h)
+        def publish(self, d):
+            for h in self._h.get(d.get("event"), []): h(d)
+
+    spine = EventSpine()
+    seen = []
+    spine.project(lambda e: seen.append((e.topic, e.source, e.payload)))
+    bus = _FakeHKCBus()
+    assert bridge_hkc_events(bus, spine) is True
+    bus.publish({"event": "knowledge.merged", "payload": {"ku_id": "K1"}, "event_id": "EVT_1"})
+    bus.publish({"event": "conflict.detected", "payload": {"card": "C1"}})
+    bus.publish({"event": "ability.created", "payload": {"key": "A1"}})
+    assert ("knowledge.merged", "hkc", {"ku_id": "K1"}) in seen, seen
+    assert any(t == "conflict.detected" and s == "hkc" for t, s, _ in seen)
+    assert any(t == "ability.created" for t, _, _ in seen)
+    # memory.* 刻意不桥(HMR 域,转发会重复/混淆)
+    bus.publish({"event": "memory.created", "payload": {}})
+    assert not any(t == "memory.created" for t, _, _ in seen), "memory.* 不应被桥接"
+    # 降级:bus/spine 为 None → 不接线、不崩
+    assert bridge_hkc_events(None, spine) is False
+    print("  ✓ knowledge.merged/conflict/ability 桥到脊柱(source=hkc);memory.* 不桥;None 优雅降级")
+
+
+def test_unified_projection_via_foxclawos():
+    print("\n【4】Foxclaw:harness 事件与系统事件被同一投影统一观测")
+    d = tempfile.mkdtemp(prefix="spine_os_")
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        seen = []
+        os_.event_spine.project(lambda e: seen.append(e.topic))
+        # 两类来源:harness 总线 与 系统总线,都汇入 os_.event_spine
+        os_.finance.harness.bus.emit("harness_warn", {"agent": "finance"})
+        os_.system_bus.publish("execution.completed", {"task": "demo"})
+        assert "harness_warn" in seen, "harness 事件应到统一投影"
+        assert "execution.completed" in seen, "系统事件应到统一投影(修复:此前到不了)"
+        # 且二者用的是同一条脊柱实例
+        assert os_.system_bus.spine is os_.event_spine
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+    print("  ✓ harness + 系统事件汇入同一脊柱、被同一投影观测(4→1 统一成立)")
+
+
+def test_ws_projection_safe_and_bounded():
+    print("\n【5】WS 投影净化:脏/大 payload 不丢连接、不泛洪(深审修复)")
+    import json as _json
+    import foxclaw.api as api
+    # a) 净化器:非 JSON 对象 → 可序列化;超大 → 截断;正常 → 透传
+    class Weird:  # 非 JSON 可序列化
+        def __repr__(self): return "<Weird>"
+    safe = api._ws_safe_payload({"obj": Weird(), "n": 1})
+    _json.dumps(safe)   # 不应抛
+    big = api._ws_safe_payload({"blob": "x" * 10000})
+    assert big.get("_truncated") is True, "超大 payload 应被截断"
+    assert api._ws_safe_payload({"a": 1, "b": "ok"}) == {"a": 1, "b": "ok"}, "正常 payload 透传"
+    print("  ✓ 非 JSON 对象被 str 化;超大被截断;正常透传")
+
+    # b) 端到端:投影把脏事件放进队列后,队列项必须 JSON 可序列化(否则 send_json 会丢连接)
+    d = tempfile.mkdtemp(prefix="spine_ws_")
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        # 清空可能的既有队列
+        while not api._event_queue.empty():
+            api._event_queue.get_nowait()
+        api._register_spine_projection(os_)
+        os_.system_bus.publish("execution.completed",
+                               {"agent_id": "x", "task": "t", "result": Weird()})  # 脏 result
+        # 真值链会连带产生 trace/truth/memory 事件(再入 publish),全部经投影入队。
+        items = []
+        while not api._event_queue.empty():
+            items.append(api._event_queue.get_nowait())
+        assert items, "投影应把事件放进队列"
+        for it in items:
+            _json.dumps(it)   # 关键:每一项都必须能 send_json 而不抛 → 不会丢连接
+        topics = {it["event"] for it in items}
+        assert "execution.completed" in topics, f"应含 execution.completed,实得 {topics}"
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+    print("  ✓ 脏 result 事件经投影后队列项 JSON 安全(WS 不会静默丢连接)")
+
+
+def main():
+    print("=" * 60)
+    print("统一事件脊柱 · EventSpine(P0 第二项)")
+    print("=" * 60)
+    test_spine_pubsub_prefix_projection()
+    test_systembus_facade()
+    test_harness_forwards_to_spine()
+    test_hkc_events_bridge_to_spine()
+    test_unified_projection_via_foxclawos()
+    test_ws_projection_safe_and_bounded()
+    print("\n" + "=" * 60)
+    print("✓ P0-2 验证完成:脊柱 + SystemBus门面 + Harness转发 + 统一投影")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_evidence_semantic.py

@@ -0,0 +1,101 @@
+"""证据融合语义化 —— 原始复盘点名的 `search/evidence.py "规则占位"`(此前一直漏修)。
+
+修掉两个真问题:
+  ① 否定词**子串**误命中:原 ("不是","并非","no longer","not") 按子串匹配 →
+     "another"/"notebook" 里的 "not" 被命中 → 无关证据被判**矛盾**;而 confidence()
+     按矛盾数扣分(0.1/条)→ 搜索置信被**幻影矛盾**无端拉低。
+     这与 hkc_kee/kee.py 早已修过的 not⊂nothing / no⊂know 是**同一 bug 家族**,证据层漏了同步。
+  ② 相似度是**字符级**(SequenceMatcher)而非语义 → 语义等价的证据识别不出互相支持。
+
+无 ST 模型时优雅降级回字符级(不崩),故本测试对语义部分做"可用才断言"。
+"""
+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_evidence_semantic():
+    os.environ.setdefault("HF_HUB_OFFLINE", "1")
+    os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+    os.environ["FOXCLAW_EVIDENCE_MODEL"] = "all-MiniLM-L6-v2"     # 进程缓存里通常有,保证离线可测
+
+    from foxclaw.search.evidence import EvidenceFusion, _has_neg, _semantic_sim
+    from foxclaw.search.models import RawEvidence
+
+    print("=" * 60); print("证据融合语义化验证"); print("=" * 60)
+    f = EvidenceFusion()
+
+    # [1] 否定词词边界:不依赖模型,总能测(这是幻影矛盾的根因)
+    assert _has_neg("this is another way") is False, "another 里的 not 不该命中"
+    assert _has_neg("the notebook is useful") is False, "notebook 里的 not 不该命中"
+    assert _has_neg("I know this") is False, "know 里的 no 不该命中"
+    assert _has_neg("cannot proceed") is True
+    assert _has_neg("this is not good") is True
+    assert _has_neg("这个方案并非最优") is True
+    print("[1] 否定词词边界(another/notebook/know 不误命中)OK")
+
+    # [2] 幻影矛盾消失:无关句子不再被判矛盾
+    assert f._contradicts("this is another way", "this is a way") is False, "幻影矛盾"
+    assert f._contradicts("the notebook is useful", "the book is useful") is False, "幻影矛盾"
+    print("[2] 幻影矛盾消失(another/notebook 不再被判矛盾)OK")
+
+    # [3] 真矛盾仍能识别(不能因为修 bug 把功能砍了)
+    assert f._contradicts("cannot proceed", "can proceed") is True
+    assert f._contradicts("这个方案并非最优", "这个方案是最优") is True
+    print("[3] 真矛盾仍识别(cannot/并非)OK")
+
+    # [4] 幻影矛盾会拉低置信 —— 端到端证明它真的有害
+    g = f.build([
+        RawEvidence(id="e1", fact="this is another way", source="s1", origin="internal", confidence=0.9),
+        RawEvidence(id="e2", fact="this is a way", source="s2", origin="internal", confidence=0.9),
+    ])
+    assert len(g.contradictions()) == 0, f"不该有矛盾边: {g.contradictions()}"
+    assert f.confidence(g) >= 0.85, f"置信不该被幻影矛盾扣分: {f.confidence(g)}"
+    print(f"[4] 端到端:无幻影矛盾边,置信未被误扣({f.confidence(g):.2f})OK")
+
+    # ── 语义部分:模型可用才断言,否则优雅跳过(降级路径本身已由 [1]-[4] 覆盖)──
+    if _semantic_sim("a", "a") is None:
+        print("[skip] ST 模型未缓存 → 语义部分跳过(已回退字符级,不崩)")
+        print("\n证据融合语义化验证通过(降级路径)")
+        # 两种运行方式都要正确退出(M7):
+        #   · 被 pytest 收集 → pytest.skip 是标准做法;让测试显式"跳过"而非崩溃。
+        #   · 被 run_all.py 当脚本直跑 → pytest.skip 抛 Skipped 会让脚本非零退出,
+        #     反而把「跳过」变成「失败」。故按 __name__ 区分。
+        if __name__ != "__main__":
+            import pytest
+            pytest.skip("ST 模型未缓存 → 语义部分跳过(降级路径已由 [1]-[4] 覆盖)",
+                        allow_module_level=True)
+        import sys as _sys
+        _sys.exit(0)
+
+    # [5] 语义相似:近义高、无关低(字符级做不到这点)
+    close = f._similarity("the plan is good", "the plan is nice")
+    far = f._similarity("the plan is good", "the stock market crashed")
+    assert close > 0.6 > far, f"近义应>0.6>无关: {close:.3f} vs {far:.3f}"
+    assert f._similarity("hello world", "hello world") >= 0.99
+    print(f"[5] 语义相似(近义 {close:.2f} > 0.6 > 无关 {far:.2f})OK")
+
+    # [6] 语义等价的证据 → 建立 supports 边(原字符级识别不出)
+    g2 = f.build([
+        RawEvidence(id="a", fact="it will rain today", source="s1", origin="internal", confidence=0.8),
+        RawEvidence(id="b", fact="rain is expected today", source="s2", origin="external", confidence=0.8),
+    ])
+    sup = [e for e in g2.edges if e.relation == "supports"]
+    assert sup, "语义等价的证据应互相支持(字符级识别不出)"
+    print("[6] 语义等价证据建立 supports 边 OK")
+
+    # [7] 阈值仍成立(换成余弦后 support=0.6 / dup=0.92 依然分得开——实测:近义 0.80~0.91、
+    #     无关 0.02、相同 1.00),且完全相同的证据仍被去重
+    g3 = f.build([
+        RawEvidence(id="x", fact="hello world", source="s1", origin="internal", confidence=0.8),
+        RawEvidence(id="y", fact="hello world", source="s2", origin="internal", confidence=0.8),
+    ])
+    assert len(g3.nodes) == 1, f"完全相同应去重: {list(g3.nodes)}"
+    print("[7] 阈值在余弦下仍成立 + 相同证据去重 OK")
+
+    print("\n证据融合语义化验证全部通过")
+
+
+if __name__ == "__main__":
+    test_evidence_semantic()

package/python/tests/test_evidence_sse.py

@@ -0,0 +1,97 @@
+"""/api/chat/stream 的命名 SSE 事件:`event: evidence`(执行凭据)与正文 delta 分离。
+
+锁住的契约:
+  · 工具轮每步的核验结论 + 凭据以**命名事件**整块送出,不拼进正文(否则复制/落库被污染);
+  · 没有工具步的纯对话不产生 evidence 事件(不能凭空生成"凭据",前端也不闪空面板);
+  · 前端拿到的是一个数组:`[{tool,status,reason,evidence:[{kind,ref,label,...}]}]`。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+EVIDENCE = [
+    {"tool": "web_search", "kind": "ok", "status": "verified", "reason": "",
+     "evidence": [{"kind": "url", "ref": "https://example.com/a", "label": "example.com",
+                   "source": "web_search", "at": 0}]},
+    {"tool": "send_mail", "kind": "ok", "status": "unverified",
+     "reason": "该工具未声明可观察的后置条件", "evidence": []},
+]
+
+
+def _parse(body: str) -> tuple[list, str]:
+    """拆 SSE:返回 (evidence 事件载荷列表, 正文 delta 拼接)。"""
+    ev_payloads, delta_text = [], ""
+    for b in [x for x in body.split("\n\n") if x.strip()]:
+        name, data = "message", None
+        for line in b.splitlines():
+            if line.startswith("event: "):
+                name = line[7:].strip()
+            elif line.startswith("data: "):
+                data = line[6:].strip()
+        if data is None:
+            continue
+        ev = json.loads(data)
+        if name == "evidence":
+            ev_payloads.append(ev)
+        elif "delta" in ev:
+            delta_text += ev["delta"]
+    return ev_payloads, delta_text
+
+
+def test_chat_stream_evidence_event_contract():
+    # ISOLATION_GUARD:依赖 import 期固化的单例(路由配置/限流器),须独立进程跑。
+    if "foxclaw.api" in sys.modules:
+        import pytest
+        pytest.skip("需独立进程运行(模块级单例已固化),请用 tests/run_all.py")
+    os.environ.setdefault("FOXCLAW_DATA_DIR", tempfile.mkdtemp(prefix="foxclaw_ev_"))
+
+    from fastapi.testclient import TestClient
+    from foxclaw.agents.base import CognitiveAgent
+    from foxclaw.api import app
+
+    seen: dict = {}
+
+    def _fake_stream(self, task, stop_event=None, images=None, history=None,
+                     attachments=None, on_thinking=None, on_evidence=None):
+        seen["has_cb"] = on_evidence is not None
+        if task == "plain":
+            yield "纯对话,没有动用工具。"      # 无工具步:不上报任何证据
+            return
+        yield "已完成。"                       # 正文先出
+        if on_evidence is not None:           # 证据后出(与真实实现一致:答案之后上报)
+            on_evidence(EVIDENCE)
+
+    original = CognitiveAgent.stream_reply
+    CognitiveAgent.stream_reply = _fake_stream
+    try:
+        with TestClient(app) as c:
+            with_tools = c.post("/api/chat/stream", json={"task": "use-tools", "agent_id": "supervisor"})
+            plain = c.post("/api/chat/stream", json={"task": "plain", "agent_id": "supervisor"})
+            assert with_tools.status_code == 200 and plain.status_code == 200
+            body, plain_body = with_tools.text, plain.text
+    finally:
+        CognitiveAgent.stream_reply = original
+
+    assert seen.get("has_cb") is True, "端点必须把 on_evidence 传给 Agent"
+
+    ev_payloads, delta_text = _parse(body)
+    assert "event: evidence" in body, "证据必须以命名事件送出"
+    assert len(ev_payloads) == 1, "一轮只上报一次"
+    items = ev_payloads[0]["evidence"]
+    assert [i["tool"] for i in items] == ["web_search", "send_mail"]
+    assert [i["status"] for i in items] == ["verified", "unverified"]
+    assert items[0]["evidence"][0]["ref"] == "https://example.com/a"
+    # 凭据不得混进正文——正文是答案,不是证据仓库
+    assert "example.com" not in delta_text
+    assert delta_text.strip() == "已完成。"
+
+    # 纯对话:没有 evidence 事件,正文照常
+    assert "event: evidence" not in plain_body
+    assert "纯对话" in plain_body

package/python/tests/test_file_ingest.py

@@ -0,0 +1,146 @@
+"""
+文件摄入打通交互层：docx/xlsx 加载器 + KDE 后缀分派 + 上传路由格式门。
+
+离线可跑：加载器是确定性纯解析（无 LLM）；KDE 分派用假抽取器验证
+「新后缀 → loader → chunker → packager → KU」链路，不调真实模型。
+真实 LLM 抽取质量不在离线回归内（与 test_hkc 一致哲学）。
+"""
+import os, sys, tempfile
+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_file_ingest():
+    # 离线 + stub，确定性
+    for k in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "DEEPSEEK_API_KEY"):
+        os.environ.pop(k, None)
+    os.environ["HKC_EMBEDDING"] = "stub"
+    os.environ["HF_HUB_OFFLINE"] = "1"
+    os.environ["TRANSFORMERS_OFFLINE"] = "1"
+
+    from docx import Document
+    from openpyxl import Workbook
+    from hkc_kde.loaders.office_loader import DocxLoader, XlsxLoader
+    from hkc_kde.chunker import Chunker
+    from hkc_kde.models import ExtractionResult, RawExtraction
+
+    print("=" * 60); print("文件摄入（docx/xlsx）打通验证"); print("=" * 60)
+
+    TMP = Path(tempfile.mkdtemp(prefix="foxclaw_fileingest_"))
+
+    def _make_docx() -> Path:
+        p = TMP / "sample.docx"
+        doc = Document()
+        doc.add_heading("第一章 引言", level=1)
+        doc.add_paragraph("Foxclaw 是一个认知代理操作系统，由五个 Agent 组成。")
+        # 表格夹在第一章内、第二章之前——用于验证按 body 顺序归章（而非全塞末章）
+        t = doc.add_table(rows=2, cols=2)
+        t.rows[0].cells[0].text = "字段"; t.rows[0].cells[1].text = "取值"
+        t.rows[1].cells[0].text = "版本"; t.rows[1].cells[1].text = "v1.6"
+        doc.add_heading("第二章 架构", level=1)
+        doc.add_paragraph("知识核心负责长期记忆的沉淀与演化。")
+        doc.save(str(p))
+        return p
+
+    def _make_xlsx() -> Path:
+        p = TMP / "sample.xlsx"
+        wb = Workbook()
+        ws = wb.active; ws.title = "财务"
+        ws.append(["科目", "金额"]); ws.append(["收入", 100]); ws.append(["支出", 40])
+        ws2 = wb.create_sheet("备注")
+        ws2.append(["说明", "季度汇总"])
+        wb.save(str(p)); wb.close()
+        return p
+
+    # [1] DocxLoader：标题切章 + 表格行入文
+    pd = DocxLoader().load(str(_make_docx()))
+    assert pd.doc_type == "DOCX", pd.doc_type
+    titles = [c.title for c in pd.chapters]
+    assert "第一章 引言" in titles and "第二章 架构" in titles, titles
+    alltext = "\n".join(s.content for c in pd.chapters for s in c.sections)
+    assert "五个 Agent" in alltext, "正文段落丢失"
+    assert "版本 | v1.6" in alltext, "表格行未转文本"
+    # 表格按 body 顺序归入它出现的章节（第一章），不该被塞到末章
+    ch1 = [c for c in pd.chapters if c.title == "第一章 引言"][0]
+    ch2 = [c for c in pd.chapters if c.title == "第二章 架构"][0]
+    assert any("版本 | v1.6" in s.content for s in ch1.sections), "表格未归到出现位置的第一章"
+    assert not any("版本" in s.content for s in ch2.sections), "表格错误归到末章第二章"
+    print(f"[1] DocxLoader（{len(pd.chapters)} 章，标题切分 + 表格按序归章）OK")
+
+    # [2] XlsxLoader：每表一章 + 行合并
+    px = XlsxLoader().load(str(_make_xlsx()))
+    assert px.doc_type == "XLSX", px.doc_type
+    sheet_titles = [c.title for c in px.chapters]
+    assert "财务" in sheet_titles and "备注" in sheet_titles, sheet_titles
+    xtext = "\n".join(s.content for c in px.chapters for s in c.sections)
+    assert "收入 | 100" in xtext and "季度汇总" in xtext, xtext
+    print(f"[2] XlsxLoader（{len(px.chapters)} 表→章，行合并）OK")
+
+    # [3] 加载器输出可被 Chunker 消费（loader→chunker 接线）
+    chunks = Chunker().chunk(pd)
+    assert chunks and any("Agent" in ch.content for ch in chunks), "docx 未切出有效 chunk"
+    print(f"[3] Chunker 消费 docx（{len(chunks)} chunk）OK")
+
+    # [4] KDE 后缀分派端到端：假抽取器把 chunk 变 KU，证明 .docx/.xlsx 走通全链路
+    def _build_kde():
+        from hkc_core.utils.id_gen import IDGenerator
+        from hkc_core.graph.sqlite_store import SQLiteGraphStore
+        from hkc_kep.event_bus import EventBus
+        from hkc_kde.kde import KnowledgeDigestEngine
+        d = Path(tempfile.mkdtemp(prefix="foxclaw_kde_"))
+        store = SQLiteGraphStore(str(d / "hkc.db"))
+        bus = EventBus(str(d / "events.db"))
+        idg = IDGenerator(str(d / "id.db"))
+        return KnowledgeDigestEngine(store, bus, idg, provider="anthropic")
+
+    class _FakeExtractor:
+        """每个 chunk 抽出一个实体，捕获收到的 chunk 供断言。"""
+        def __init__(self): self.seen = []
+        def extract(self, chunks, progress_cb=None):
+            self.seen = list(chunks)
+            doc_id = chunks[0].doc_id if chunks else ""
+            raw = RawExtraction(entities=[{"name": "Foxclaw", "type": "Person"}])
+            return ExtractionResult(doc_id=doc_id, source=doc_id, items=[raw])
+
+    for suffix, maker in ((".docx", _make_docx), (".xlsx", _make_xlsx)):
+        kde = _build_kde()
+        fake = _FakeExtractor(); kde.extractor = fake
+        kus = kde.ingest_file(str(maker()), source=f"user{suffix}")
+        assert fake.seen, f"{suffix}: 抽取器未收到 chunk（分派断裂）"
+        assert kus, f"{suffix}: 未写入任何 KU"
+    print("[4] KDE 分派 .docx/.xlsx → loader → chunker → KU 全链路 OK")
+
+    # [5] 不支持的格式明确报错（不静默产空）
+    kde = _build_kde()
+    bad = TMP / "x.pptx"; bad.write_bytes(b"PK\x03\x04not really")
+    try:
+        kde.ingest_file(str(bad))
+        raise AssertionError("应对 .pptx 抛不支持错误")
+    except ValueError as e:
+        assert ".pptx" in str(e) or "不支持" in str(e), str(e)
+    print("[5] 不支持格式（.pptx）明确 ValueError OK")
+
+    # [6] 上传路由格式门：TestClient 走 Foxclaw app 挂载的 /knowledge/ingest/file
+    from fastapi.testclient import TestClient
+    from foxclaw.api import app
+    with TestClient(app) as c:
+        # 不支持后缀 → 415（后缀检查在读文件前，无需 LLM）
+        r = c.post("/knowledge/ingest/file",
+                   files={"file": ("bad.pptx", b"x", "application/octet-stream")})
+        assert r.status_code == 415, (r.status_code, r.text)
+        assert ".docx" in r.text and ".xlsx" in r.text, "415 提示未含新格式"
+        # 支持的 docx 上传 → 200（stub 抽取 0 KU，但格式门放行、链路不崩）
+        with open(_make_docx(), "rb") as fh:
+            r2 = c.post("/knowledge/ingest/file",
+                        files={"file": ("sample.docx", fh.read(),
+                               "application/vnd.openxmlformats-officedocument.wordprocessingml.document")},
+                        data={"domain": "test"})
+        assert r2.status_code == 200, (r2.status_code, r2.text)
+    print("[6] 上传路由格式门（.pptx→415；.docx→200）OK")
+
+    print("\n文件摄入（docx/xlsx）验证全部通过")
+
+
+if __name__ == "__main__":
+    test_file_ingest()