foxclaw 0.1.0 → 0.1.2

package/python/tests/test_hkc.py

@@ -0,0 +1,286 @@
+"""
+知识核心(HKC 融入)测试 —— 全离线,embedding=stub,不需 LLM。
+
+覆盖:
+  1. init_hkc 同进程装配 → available;空库混合检索返回 [];stats 有 data_dir
+  2. H1 资源修复:close() 后能 rmtree 数据目录(无 Windows WinError 32)——
+     即 event_bus/id_gen/graph_store/synthesis 四个 SQLite 句柄全部释放
+  3. close() 幂等
+  4. 经 Foxclaw 惰性装配:未访问 .hkc 前不开句柄;访问后装配;aclose() 释放后可删目录
+
+摄入(ingest)需真实 LLM,不在离线回归内跑;这里只验证融合层的装配/降级/资源契约。
+"""
+import sys, tempfile, shutil, asyncio
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.knowledge import init_hkc
+
+
+def test_assemble_search_close():
+    print("\n【1】init_hkc 装配 + 空库检索 + stats + close 后可删目录(H1)")
+    d = tempfile.mkdtemp(prefix="hkc_test_")
+    ok_rmtree = False
+    try:
+        svc = init_hkc(d, api_key=None)
+        assert svc is not None and svc.available, "依赖已装,HKC 应装配成功"
+        print("  ✓ 同进程装配成功 available=True")
+
+        hits = svc.client.search("任意不存在的查询", mode="hybrid", top_k=5)
+        assert isinstance(hits, list) and len(hits) == 0
+        print(f"  ✓ 空库混合检索返回空: {hits}")
+
+        s = svc.stats()
+        assert "data_dir" in s and "total_kus" in s
+        print(f"  ✓ stats: total_kus={s.get('total_kus')} embedding={s.get('embedding')!r}")
+
+        svc.close()
+        svc.close()   # 幂等
+        print("  ✓ close() 幂等")
+    finally:
+        # 关键:close 后 4 个 SQLite 句柄全释放,才能删掉目录(此前 events.db/id_counters.db 泄漏)
+        shutil.rmtree(d)   # 不 ignore_errors:泄漏则抛 OSError → 测试失败
+        ok_rmtree = True
+    assert ok_rmtree
+    print("  ✓ close 后 rmtree 成功 → H1 资源泄漏修复生效(无 WinError 32)")
+
+
+def test_via_foxclawos_lazy_teardown():
+    print("\n【2】经 Foxclaw 惰性装配 + aclose teardown 全链路")
+    d = tempfile.mkdtemp(prefix="hkc_os_")
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        # 惰性:未访问 .hkc 前不该装配(不开句柄)
+        assert os_._hkc_service is None and os_._hkc_inited is False
+        print("  ✓ 构造 OS 后未装配 HKC(惰性,未开 db 句柄)")
+
+        hkc = os_.hkc   # 触发装配
+        assert os_._hkc_inited is True
+        assert hkc is not None and hkc.available
+        print("  ✓ 首次访问 os_.hkc 触发装配 available=True")
+
+        hits = hkc.client.search("空库查询", top_k=3)
+        assert hits == []
+        print("  ✓ 经 DirectClient 检索空库返回 []")
+
+        asyncio.run(os_.aclose())
+        print("  ✓ aclose() 释放浏览器 + HKC 资源")
+    finally:
+        shutil.rmtree(d)   # aclose 已释放 HKC 句柄,应能删
+    print("  ✓ teardown 后 rmtree 成功(HKC 句柄经 aclose 释放)")
+
+
+def test_ability_readonly_surface():
+    print("\n【3】第2档 Step1:ACE 能力只读面(list/compile 证据 gate/neighbors)——无 LLM")
+    d = tempfile.mkdtemp(prefix="hkc_abil_")
+    svc = None
+    try:
+        svc = init_hkc(d, api_key=None)
+        assert svc is not None and svc.available
+        from hkc_sdk.exceptions import HKCInsufficientCoverage, HKCNotFoundError
+        # list_abilities:返回 taxonomy 里定义的能力 key(静态,无需摄入)
+        keys = svc.client.list_abilities()
+        assert isinstance(keys, list) and len(keys) > 0, f"应有内置能力定义,实得 {keys}"
+        print(f"  ✓ list_abilities 返回 {len(keys)} 个能力: {keys[:4]}...")
+        # compile_ability:空知识库 → 覆盖不足 → 证据 gate(抛 HKCInsufficientCoverage,带 missing/coverage)
+        gated = False
+        try:
+            svc.client.compile_ability(keys[0])
+        except HKCInsufficientCoverage as e:
+            gated = True
+            assert hasattr(e, "missing_skills") and hasattr(e, "coverage")
+        assert gated, "空知识库编译能力应被证据 gate 拦(覆盖不足)"
+        print("  ✓ 空库 compile_ability 被证据 gate 拦(覆盖不足→能力不予授予)")
+        # neighbors:不存在 KU → SDK 抛 HKCNotFoundError(契约)。注:/api/knowledge/ku/{id}/neighbors
+        # 端点已在 V3 接口清理删除(前端零用 + HKC router 的 /knowledge/ku/{id}/neighbors 有等价),
+        # 此处只验 SDK 层契约;SDK neighbors 仍被 ACE 能力/图查询内部使用,保留测试。
+        raised = False
+        try:
+            svc.client.neighbors("KU_nonexistent", max_depth=2, top_k=10)
+        except HKCNotFoundError:
+            raised = True
+        assert raised, "不存在 KU 应抛 HKCNotFoundError(SDK 契约)"
+        print("  ✓ neighbors(不存在 KU) 抛 HKCNotFoundError(SDK 契约;API 端点已删,见 V3 清理)")
+    finally:
+        if svc is not None:
+            svc.close()
+        shutil.rmtree(d, ignore_errors=True)
+    print("  ✓ 只读能力面成立:枚举 + 证据 gate + 图邻域(全无 LLM/零成本)")
+
+
+def test_agent_available_abilities():
+    print("\n【4】第2档 Step2:Agent.available_abilities() 证据驱动自省(只读,不改执行)")
+    d = tempfile.mkdtemp(prefix="hkc_selfintro_")
+    os_ = None
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        # 空知识库:所有能力都应 sufficient=False(证据 gate:没知识不予授予)
+        abils = os_.finance.available_abilities()
+        assert isinstance(abils, list) and len(abils) > 0, f"应枚举出能力,实得 {abils}"
+        assert all(a["sufficient"] is False for a in abils), \
+            f"空库→全部证据 gate 拦(sufficient=False),实得 {[a['sufficient'] for a in abils]}"
+        assert all("missing_skills" in a for a in abils), "未达标应附 missing_skills"
+        print(f"  ✓ 空库自省:{len(abils)} 个能力全 sufficient=False(证据 gate)")
+        # 各 Agent 看到一致(知识全局共享)
+        assert len(os_.office.available_abilities()) == len(abils)
+        print("  ✓ 各 Agent 一致(HKC 知识全局共享)")
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+    print("  ✓ 能力自省成立:证据驱动、只读、无 LLM")
+
+
+def test_ability_context_injection():
+    print("\n【5】第2档 Step3:能力→上下文注入(opt-in;默认关不改行为;fail-safe)")
+    from types import SimpleNamespace
+    d = tempfile.mkdtemp(prefix="hkc_inject_")
+    os_ = None
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        ag = os_.finance
+        base = [{"role": "user", "content": "原始问题"}]
+
+        # (a) 默认关:不注入(行为逐字不变)
+        assert ag._ability_augment("帮我做写作专家分析", list(base)) == base
+
+        # (b) 启用但无达标能力(真实空 HKC)→ no-op
+        ag.ABILITY_AUGMENT = True
+        assert ag._ability_augment("帮我做写作专家分析", list(base)) == base
+
+        # (c) 启用 + 注册假 HKC(有达标能力 + 检索命中)→ 注入知识上下文到 messages 前
+        class _C:
+            def list_abilities(self): return ["writing_expert"]
+            def compile_ability(self, k):
+                return SimpleNamespace(ability_key=k, display_name="写作专家",
+                                       domain="writing", coverage={"修辞": 0.9}, skills=[])
+            def search(self, q, mode="hybrid", top_k=10, domain=""):
+                return [SimpleNamespace(name="修辞", summary="比喻与排比",
+                                        ku_id="K1", score=0.9, ku_type="Concept")]
+        os_.capabilities.register("hkc", SimpleNamespace(available=True, client=_C()))
+        out = ag._ability_augment("帮我做写作专家风格分析", list(base))
+        assert len(out) == 2 and "能力知识增强" in out[0]["content"] and "修辞" in out[0]["content"]
+        assert out[1] == base[0], "原消息应保留在注入内容之后"
+        print("  ✓ 默认关不注入;空库 no-op;启用+达标+命中→注入知识上下文")
+
+        # (d) fail-safe:能力增强内部异常(search 抛错)→ 原样返回,不影响主流程
+        class _Cbad(_C):
+            def search(self, *a, **k): raise RuntimeError("boom")
+        os_.capabilities.register("hkc", SimpleNamespace(available=True, client=_Cbad()))
+        assert ag._ability_augment("帮我做写作专家分析", list(base)) == base
+        print("  ✓ 增强内部异常 → fail-safe 原样返回(不影响主流程)")
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+    print("  ✓ 能力上下文注入成立:opt-in、匹配、fail-safe、默认行为不变")
+
+
+def test_ability_as_skill_step4():
+    print("\n【6】第2档 Step4:能力→SkillRegistry(证据 gate + read 经 PolicyGate + 可路由)")
+    from types import SimpleNamespace
+    from foxclaw.knowledge import register_abilities_as_skills
+    from foxclaw.skills import SkillRegistry, SkillAdapter
+
+    class _C:
+        def list_abilities(self): return ["writing_expert", "quant_analyst"]
+        def compile_ability(self, k):
+            if k == "quant_analyst":
+                raise RuntimeError("coverage 不足")      # 任何异常 → 证据 gate 跳过
+            return SimpleNamespace(ability_key=k, display_name="写作专家",
+                                   domain="writing", coverage={"修辞": 0.9})
+        def search(self, q, mode="hybrid", top_k=10, domain=""):
+            return [SimpleNamespace(name="修辞", summary="比喻与排比",
+                                    ku_id="K1", score=0.9, ku_type="Concept")]
+
+    hkc = SimpleNamespace(available=True, client=_C())
+    reg = SkillRegistry()
+    ids = register_abilities_as_skills(reg, hkc)
+    # 证据 gate:只注册达标的 writing_expert;覆盖不足的 quant_analyst 不注册
+    assert ids == ["ability:writing_expert"], ids
+    assert reg.get("ability:quant_analyst") is None, "覆盖不足→不注册(证据 gate)"
+    spec = reg.get("ability:writing_expert")
+    assert spec is not None and spec.side_effect == "read", "能力 skill 为 read(无外部副作用)"
+
+    # 经 SkillAdapter(→PolicyGate 四阶段)调用:read → 放行 → handler 返回 domain 内知识
+    res = SkillAdapter(reg).invoke(spec, {"query": "写作风格"})
+    assert res.success and res.output.get("ability") == "writing_expert", res.to_dict()
+    assert res.output["knowledge"] and res.output["knowledge"][0]["name"] == "修辞"
+    print("  ✓ 证据 gate:达标能力注册为 read skill、覆盖不足不注册;经 PolicyGate 放行返回知识")
+
+    # 降级:HKC 不可用 / registry 缺失 → 不注册、不崩
+    assert register_abilities_as_skills(SkillRegistry(), None) == []
+    assert register_abilities_as_skills(None, hkc) == []
+    print("  ✓ HKC 不可用/registry 缺失 → 优雅返回 []")
+
+
+def test_ability_skill_prune_and_concurrency():
+    print("\n【7】深审修复:ability skill 陈旧清理(re-sync)+ SkillRegistry 线程安全")
+    import threading
+    from types import SimpleNamespace
+    from foxclaw.knowledge import register_abilities_as_skills
+    from foxclaw.skills import SkillRegistry, SkillSpec
+
+    # (a) 陈旧清理:先达标注册 → 知识掉了不再达标 → re-sync 移除陈旧 ability skill
+    class _Cdrop:
+        def __init__(self): self.ok = True
+        def list_abilities(self): return ["writing_expert"]
+        def compile_ability(self, k):
+            if not self.ok:
+                raise RuntimeError("coverage 掉了")
+            return SimpleNamespace(ability_key=k, display_name="写作专家",
+                                   domain="writing", coverage={})
+        def search(self, *a, **k): return []
+    c = _Cdrop()
+    hkc = SimpleNamespace(available=True, client=c)
+    reg = SkillRegistry()
+    assert register_abilities_as_skills(reg, hkc) == ["ability:writing_expert"]
+    assert reg.get("ability:writing_expert") is not None
+    c.ok = False                              # 知识掉了 → 不再达标
+    assert register_abilities_as_skills(reg, hkc) == []
+    assert reg.get("ability:writing_expert") is None, "陈旧 ability skill 应在 re-sync 时被移除"
+    print("  ✓ re-sync:覆盖掉了的 ability skill 被清理(不残留)")
+
+    # (b) 线程安全:并发 register + match/all/catalog 无 "dict changed size" 异常
+    reg2 = SkillRegistry()
+    errs = []
+    def reg_worker():
+        try:
+            for i in range(400):
+                reg2.register(SkillSpec(id=f"s{i % 20}", name="x", description="",
+                                        kind="local", triggers=["x"]))
+        except Exception as e:
+            errs.append(repr(e))
+    def read_worker():
+        try:
+            for _ in range(400):
+                reg2.match("任意任务 x"); reg2.all(); reg2.catalog()
+        except Exception as e:
+            errs.append(repr(e))
+    ts = [threading.Thread(target=reg_worker) for _ in range(3)] + \
+         [threading.Thread(target=read_worker) for _ in range(3)]
+    for t in ts: t.start()
+    for t in ts: t.join()
+    assert not errs, f"并发 register/match 应无异常,实得 {errs[:2]}"
+    print("  ✓ 6 线程并发 register/match/all/catalog 无异常(SkillRegistry 加锁生效)")
+
+
+def main():
+    print("=" * 60)
+    print("知识核心 · HKC 融入(全离线,embedding=stub)")
+    print("=" * 60)
+    test_assemble_search_close()
+    test_via_foxclawos_lazy_teardown()
+    test_ability_readonly_surface()
+    test_agent_available_abilities()
+    test_ability_context_injection()
+    test_ability_as_skill_step4()
+    test_ability_skill_prune_and_concurrency()
+    print("\n" + "=" * 60)
+    print("✓ HKC 融入验证完成:装配/检索/stats + H1 资源修复 + 惰性/teardown")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_hkc_index_build_manager.py

@@ -0,0 +1,339 @@
+"""
+HKC 后台索引构建测试(阶段 C 提交)。
+
+覆盖范围:
+  S1  无索引启动 + 库有数据 → assemble 立即返;manager 后台编码;
+      等 join 后 vector_size == source_total,index_state=ready。
+  S2  旧快照启动(磁盘 faiss 完整覆盖库) → assemble 立即返;
+      manager.start() 返 None(无需构建);vector_size == 磁盘中数。
+  S3  构建中重启 → 续跑(落盘 faiss 删光,manager 仍从空开始;但状态机重启后
+      state 仍为上次 cancelled/ready,这是 next.start() 决策依据)
+  S4  构建中查询:manager 跑后台编码的同时,前端调 c.search.search()
+      → 不抛错;能拿到当前 partial 结果。
+
+设计原则(同 P0/P1/P2):
+  - 不 mock:真 SQLite + 真 faiss + StubBackend + 真 HKCContainer + 真 IndexBuildManager。
+  - vendor 隔离硬阻断:模块级解析后立即自检 __file__,不是 vendor 就 RuntimeError。
+  - 不依赖网络 / 真实模型 / 真实数据目录;全程 tmp_path。
+  - 每个测试独立 tmp_path;HKCContainer init/reset 严格 try/finally。
+"""
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+
+# ── vendor 隔离硬阻断 ────────────────────────────────────────────
+from hkc_search.index_build_manager import IndexBuildManager, _BUILD_STATES
+from hkc_search.vector_search import VectorIndex
+from hkc_search.embedding_backends import StubBackend
+from hkc_api.container import HKCContainer, init_container, reset_container
+from hkc_core.graph.sqlite_store import SQLiteGraphStore
+from hkc_core.models.ku import ConceptKU
+
+_VENDOR_ROOT = Path(__file__).resolve().parents[1] / "vendor" / "hkc"
+
+
+def _assert_vendor_path(obj, name: str) -> None:
+    mod = obj.__module__
+    f = getattr(sys.modules[mod], "__file__", "") or ""
+    assert str(Path(f).resolve()).startswith(str(_VENDOR_ROOT.resolve())), (
+        f"vendor isolation failed: {name}.__module__={mod!r} __file__={f!r} "
+        f"not under vendor/hkc. Test is running against wrong HKC copy."
+    )
+
+
+for _cls_name, _cls in [
+    ("IndexBuildManager", IndexBuildManager),
+    ("VectorIndex",        VectorIndex),
+    ("StubBackend",         StubBackend),
+    ("HKCContainer",        HKCContainer),
+    ("SQLiteGraphStore",    SQLiteGraphStore),
+    ("ConceptKU",           ConceptKU),
+]:
+    _assert_vendor_path(_cls, _cls_name)
+
+
+# ── Helpers ─────────────────────────────────────────────────────
+
+def _seed_kus(c: HKCContainer, ids: list[str]) -> None:
+    """直接 put 进 store,不发出 KNOWLEDGE_CREATED 事件。
+    用于构造 '库有数据但 vector 没条' 的初始状态,触发 manager 全量构建。
+    """
+    for i, ku_id in enumerate(ids):
+        ku = ConceptKU(
+            ku_id=ku_id,
+            name=f"ku_{i}",
+            summary=f"ku {i} 的描述是若干中文文字以填充文本",
+            domain="d",
+        )
+        c.graph_store.put(ku)
+
+
+def _wait_idle(c: HKCContainer, timeout: float = 30.0) -> dict:
+    """等 manager 跑完一轮变成 ready/failed/cancelled,返 snapshot。timeout 内的 poll。"""
+    deadline = time.time() + timeout
+    mgr = c.index_build_manager
+    last_state = None
+    while time.time() < deadline:
+        s = mgr.stats()
+        if s["index_state"] in ("ready", "failed", "cancelled", "idle"):
+            return s
+        last_state = s
+        time.sleep(0.05)
+    raise AssertionError(
+        f"等超时 {timeout}s;最后状态: {last_state}"
+    )
+
+
+def _seed_and_start_build(c: HKCContainer, ids: list[str]) -> None:
+    """init_container 在装配期会扫描库。此时若库空,manager 会立即 idle;
+    seed KU 后必须显式再 start() 触发 full build(在已加载的 vector 上 append)。
+    装配时已自动 start 过一次(空库 → idle),这次手动 start 触发增量构建。
+    """
+    _seed_kus(c, ids)
+    r = c.index_build_manager.start()
+    # size>0 不应返 None(已加载的 faiss 有数据但库无相同数据时可能返 None;此测试场景是库空)
+    # 这里 size=0 + source>0 → 必起构建 → start 返 task_id
+    assert r is not None, (
+        f"_seed_and_start_build 应触发新构建,但 start() 返 None。"
+        f"当前 stats: {c.index_build_manager.stats()}"
+    )
+
+
+# ── S1:无索引启动,manager 后台跑全量构建 ───────────────────
+
+class TestStartNoIndexManagerBuildsBackground:
+    def test_assemble_returns_fast_manager_builds_then_ready(self, tmp_path):
+        """库有 5 KU 但磁盘无索引 → seed + start → manager 后台构建;
+        join 后 vector_size == source_total 且 state=ready。"""
+        data_dir = str(tmp_path)
+        c = init_container(data_dir=data_dir, embedding_kind="stub")
+        try:
+            _seed_and_start_build(c, [f"KU_S1_{i}" for i in range(5)])
+            mgr = c.index_build_manager
+            assert mgr is not None
+            final = _wait_idle(c, timeout=30)
+            assert final["index_state"] == "ready", (
+                f"应在 ready,实际 {final}"
+            )
+            assert final["source_total"] == 5, final
+            assert final["ready"] == 5, final
+            assert final["failed"] == 0, final
+            # 内存索引真存在
+            assert c.search.vector.size() == 5
+        finally:
+            c.close()
+            reset_container()
+
+    def test_assemble_does_not_block_when_manager_builds(self, tmp_path):
+        """关键不变量:装配本身**不阻塞**全量 encode。
+        装配返回(manager 已 start)再 seed → 整体构建必须由 manager 后台承担。"""
+        data_dir = str(tmp_path)
+        c = init_container(data_dir=data_dir, embedding_kind="stub")
+        try:
+            # 装配已经返回(库空,manager 立即 idle)。seed + 重 start 让它编码。
+            _seed_and_start_build(c, [f"KU_FAST_{i}" for i in range(2)])
+            s = c.index_build_manager.stats()
+            assert s["index_state"] in _BUILD_STATES
+            final = _wait_idle(c, timeout=10)
+            assert final["index_state"] == "ready"
+            assert final["ready"] == 2
+        finally:
+            c.close()
+            reset_container()
+
+
+# ── S2:旧快照启动(磁盘 faiss 已完整) → 不重起构建 ──────────
+
+class TestStartWithPersistedSnapshotNoRebuild:
+    def test_manager_skips_when_disk_snapshot_covers_source(self, tmp_path):
+        """先启动一次让 manager 构建完 → close;重启 → manager 看到 faiss 已非空
+        → start() 返 None,不再构建。"""
+        data_dir = str(tmp_path)
+        # 第一轮:seed + start → manager 构建 → 落盘
+        c = init_container(data_dir=data_dir, embedding_kind="stub")
+        try:
+            _seed_and_start_build(c, [f"KU_S2A_{i}" for i in range(4)])
+            _wait_idle(c, timeout=20)
+            assert c.search.vector.size() == 4
+        finally:
+            c.close()
+            reset_container()
+
+        # 第二轮:simulate 重启 —— 装配后,manager.start() 应返 None (已有快照)
+        c2 = init_container(data_dir=data_dir, embedding_kind="stub")
+        try:
+            s = c2.index_build_manager.stats()
+            assert s["index_state"] == "ready", (
+                f"已有磁盘快照时 manager 应跳过,实际 {s}"
+            )
+            assert s["vector_size"] == 4, (
+                f"vector_size 应从磁盘恢复,实际 {s}"
+            )
+            # 显式再调 start() 也返 None(幂等)
+            r = c2.index_build_manager.start()
+            assert r is None, (
+                f"已有快照时 start() 应返 None,实际 {r!r}"
+            )
+        finally:
+            c2.close()
+            reset_container()
+
+
+# ── S3:构建中重启 → 续跑 ───────────────────────────────
+
+class TestMidBuildRestartPicksUp:
+    def test_resume_after_disk_vector_partial(self, tmp_path):
+        """模拟 '上次构建到一半被杀掉':磁盘 faiss 有 5 条全量,manager 看到库空
+        就不重跑(构不了啥)。验证 restart 链路:装配→加载 faiss→manager 跳过。
+        真正的「mid-build 续跑」语义由 state.json + vector 缺漏检测;
+        但因为 manager 的 start() 总是基于「当前 vector vs 当前库」做决策,
+        磁盘有 5 条 + 库 5 条相同 → 跳过(等价于 S2 的 happy path)。"""
+        data_dir = str(tmp_path)
+        # 第一轮:build 5 条 → save → close
+        c = init_container(data_dir=data_dir, embedding_kind="stub")
+        try:
+            _seed_and_start_build(c, [f"KU_S3_{i}" for i in range(5)])
+            _wait_idle(c, timeout=20)
+            assert c.search.vector.size() == 5
+        finally:
+            c.close()
+            reset_container()
+
+        # 模拟"上次只跑了部分,faiss 是部分加载的" — 删 vector 文件(变 0 条)
+        # manager 装配时会 _load_persisted_index_and_bm25 → load 失败(因为已被我们删)→ 0 条
+        # 然后 manager.start() 看到 size=0 < source=5 → 起新构建
+        vec_path = tmp_path / "search_vector"
+        if (vec_path.with_suffix(".faiss")).exists():
+            (vec_path.with_suffix(".faiss")).unlink()
+        if (vec_path.with_suffix(".meta")).exists():
+            (vec_path.with_suffix(".meta")).unlink()
+
+        # 写 state.json 模拟"上次未完成",确认 manager.start 决策时能读到历史
+        import json as _json
+        state = {
+            "task_id": "build-deadbeef",
+            "index_version": "v-stale",
+            "state": "building",
+            "source_total": 5,
+            "scanned": 3,
+            "ready": 3,
+            "failed": 0,
+            "failures": [],
+            "started_at": "2025-01-01T00:00:00+00:00",
+            "finished_at": None,
+            "last_checkpoint_at": "2025-01-01T00:00:01+00:00",
+            "error_summary": "",
+        }
+        (tmp_path / IndexBuildManager.STATE_FILE).write_text(
+            _json.dumps(state, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+        # 第二轮:重启
+        c2 = init_container(data_dir=data_dir, embedding_kind="stub")
+        try:
+            # 装配已自动 start → 应启构建(因为 faiss 已删)
+            final = _wait_idle(c2, timeout=30)
+            assert final["index_state"] == "ready", (
+                f"重启后应到 ready,实际 {final}"
+            )
+            assert c2.search.vector.size() == 5, (
+                f"重启后 vector_size 应=5,实际 {c2.search.vector.size()}"
+            )
+            # 跑出了新 task_id(不是历史的 deadbeef)
+            assert final["task_id"] != "build-deadbeef", (
+                f"应起新 task_id,实际仍用历史的 {final['task_id']!r}"
+            )
+        finally:
+            c2.close()
+            reset_container()
+
+
+# ── S4:构建中查询 ──────────────────────────────────────────
+
+class TestSearchDuringBuild:
+    def test_concurrent_search_does_not_crash(self, tmp_path):
+        """manager 后台跑编码的同时,前调 c.search.search() → 不抛错;
+        任何阶段拿到的是 partial 但应是合法 SearchResult 列表。"""
+        data_dir = str(tmp_path)
+        c = init_container(data_dir=data_dir, embedding_kind="stub")
+        try:
+            _seed_and_start_build(c, [f"KU_S4_{i}" for i in range(6)])
+            # 不等;立即并发调 search
+            results = c.search.search("ku_1 描述", mode="hybrid", top_k=3)
+            assert isinstance(results, list)
+            for r in results:
+                assert hasattr(r, "ku_id")
+                assert hasattr(r, "score")
+            # 等构建完再做一次 search 确认 6 条都被 indexed
+            final = _wait_idle(c, timeout=30)
+            assert final["index_state"] == "ready"
+            assert c.search.vector.size() == 6
+            results2 = c.search.search("ku_2", mode="bm25", top_k=2)
+            assert isinstance(results2, list)
+        finally:
+            c.close()
+            reset_container()
+
+
+# ── 单元测:IndexBuildManager 状态机字段 ─────────────────
+
+class TestManagerStats:
+    def test_stats_keys_present(self, tmp_path):
+        """stats 字典字段稳定性(对外观测前端要靠这些 key)。"""
+        mgr = IndexBuildManager(
+            data_dir=str(tmp_path),
+            hybrid_search=_FakeHybrid(),
+            graph_store=_FakeEmptyGraphStore(),
+        )
+        s = mgr.stats()
+        for k in (
+            "index_state", "index_version", "task_id", "source_total",
+            "scanned", "ready", "pending", "failed",
+            "started_at", "finished_at", "last_checkpoint_at",
+            "error_summary", "failures_preview", "vector_size",
+        ):
+            assert k in s, f"stats 缺字段 {k}, got {sorted(s.keys())}"
+
+    def test_idle_start_no_kus_yields_ready(self, tmp_path):
+        """空 store + 空 faiss → start 起线程跑,扫描后 source_total=0 → 立即 ready。"""
+        mgr = IndexBuildManager(
+            data_dir=str(tmp_path),
+            hybrid_search=_FakeHybrid(),
+            graph_store=_FakeEmptyGraphStore(),
+        )
+        mgr.start()
+        mgr.join(timeout=5)
+        # 空 store 扫描到 0 条 → 直接 _mark_ready
+        s = mgr.stats()
+        assert s["index_state"] in ("ready", "cancelled", "failed"), s
+        assert s["source_total"] == 0, s
+
+
+# ── Fakes(单元测用) ─────────────────────────────────────
+
+class _FakeHybrid:
+    """空 hybrid:vector_size=0,_ku_ids 空列表,_lock 是 RLock,vector 假实例。"""
+    def __init__(self):
+        import threading as _t
+        self._lock = _t.RLock()
+        self.vector = _FakeVector()
+
+
+class _FakeVector:
+    def __init__(self):
+        self._ku_ids: list = []
+    def size(self): return len(self._ku_ids)
+    def save(self, path): pass
+    def append_bulk(self, kus):
+        with _FakeVector._lock:
+            self._ku_ids.extend(k.ku_id for k in kus)
+    _lock = __import__("threading").RLock()
+
+
+class _FakeEmptyGraphStore:
+    def query_all(self, limit=99999999):
+        return []