foxclaw 0.1.2 → 0.1.3

package/python/tests/test_hkc.py

@@ -35,11 +35,10 @@ def test_assemble_search_close():
         print(f"  ✓ stats: total_kus={s.get('total_kus')} embedding={s.get('embedding')!r}")
 
         svc.close()
-        svc.close()   # 幂等
+        svc.close()
         print("  ✓ close() 幂等")
     finally:
-        # 关键:close 后 4 个 SQLite 句柄全释放,才能删掉目录(此前 events.db/id_counters.db 泄漏)
-        shutil.rmtree(d)   # 不 ignore_errors:泄漏则抛 OSError → 测试失败
+        shutil.rmtree(d)
         ok_rmtree = True
     assert ok_rmtree
     print("  ✓ close 后 rmtree 成功 → H1 资源泄漏修复生效(无 WinError 32)")
@@ -51,11 +50,10 @@ def test_via_foxclawos_lazy_teardown():
     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   # 触发装配
+        hkc = os_.hkc
         assert os_._hkc_inited is True
         assert hkc is not None and hkc.available
         print("  ✓ 首次访问 os_.hkc 触发装配 available=True")
@@ -67,7 +65,7 @@ def test_via_foxclawos_lazy_teardown():
         asyncio.run(os_.aclose())
         print("  ✓ aclose() 释放浏览器 + HKC 资源")
     finally:
-        shutil.rmtree(d)   # aclose 已释放 HKC 句柄,应能删
+        shutil.rmtree(d)
     print("  ✓ teardown 后 rmtree 成功(HKC 句柄经 aclose 释放)")
 
 
@@ -79,11 +77,9 @@ def test_ability_readonly_surface():
         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])
@@ -92,9 +88,6 @@ def test_ability_readonly_surface():
             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)
@@ -116,14 +109,12 @@ def test_agent_available_abilities():
     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())
@@ -143,14 +134,11 @@ def test_ability_context_injection():
         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):
@@ -165,7 +153,6 @@ def test_ability_context_injection():
         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()))
@@ -187,7 +174,7 @@ def test_ability_as_skill_step4():
         def list_abilities(self): return ["writing_expert", "quant_analyst"]
         def compile_ability(self, k):
             if k == "quant_analyst":
-                raise RuntimeError("coverage 不足")      # 任何异常 → 证据 gate 跳过
+                raise RuntimeError("coverage 不足")
             return SimpleNamespace(ability_key=k, display_name="写作专家",
                                    domain="writing", coverage={"修辞": 0.9})
         def search(self, q, mode="hybrid", top_k=10, domain=""):
@@ -197,19 +184,16 @@ def test_ability_as_skill_step4():
     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 缺失 → 优雅返回 []")
@@ -222,7 +206,6 @@ def test_ability_skill_prune_and_concurrency():
     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"]
@@ -237,12 +220,11 @@ def test_ability_skill_prune_and_concurrency():
     reg = SkillRegistry()
     assert register_abilities_as_skills(reg, hkc) == ["ability:writing_expert"]
     assert reg.get("ability:writing_expert") is not None
-    c.ok = False                              # 知识掉了 → 不再达标
+    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():

package/python/tests/test_hkc_index_build_manager.py

@@ -24,7 +24,6 @@ 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
@@ -55,8 +54,6 @@ for _cls_name, _cls in [
     _assert_vendor_path(_cls, _cls_name)
 
 
-# ── Helpers ─────────────────────────────────────────────────────
-
 def _seed_kus(c: HKCContainer, ids: list[str]) -> None:
     """直接 put 进 store,不发出 KNOWLEDGE_CREATED 事件。
     用于构造 '库有数据但 vector 没条' 的初始状态,触发 manager 全量构建。
@@ -94,16 +91,12 @@ def _seed_and_start_build(c: HKCContainer, ids: list[str]) -> None:
     """
     _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 后台构建;
@@ -121,7 +114,6 @@ class TestStartNoIndexManagerBuildsBackground:
             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()
@@ -133,7 +125,6 @@ class TestStartNoIndexManagerBuildsBackground:
         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
@@ -145,14 +136,11 @@ class TestStartNoIndexManagerBuildsBackground:
             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)])
@@ -162,7 +150,6 @@ class TestStartWithPersistedSnapshotNoRebuild:
             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()
@@ -172,7 +159,6 @@ class TestStartWithPersistedSnapshotNoRebuild:
             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}"
@@ -182,8 +168,6 @@ class TestStartWithPersistedSnapshotNoRebuild:
             reset_container()
 
 
-# ── S3:构建中重启 → 续跑 ───────────────────────────────
-
 class TestMidBuildRestartPicksUp:
     def test_resume_after_disk_vector_partial(self, tmp_path):
         """模拟 '上次构建到一半被杀掉':磁盘 faiss 有 5 条全量,manager 看到库空
@@ -192,7 +176,6 @@ class TestMidBuildRestartPicksUp:
         但因为 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)])
@@ -202,16 +185,12 @@ class TestMidBuildRestartPicksUp:
             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",
@@ -232,10 +211,8 @@ class TestMidBuildRestartPicksUp:
             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}"
@@ -243,7 +220,6 @@ class TestMidBuildRestartPicksUp:
             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}"
             )
@@ -252,8 +228,6 @@ class TestMidBuildRestartPicksUp:
             reset_container()
 
 
-# ── S4:构建中查询 ──────────────────────────────────────────
-
 class TestSearchDuringBuild:
     def test_concurrent_search_does_not_crash(self, tmp_path):
         """manager 后台跑编码的同时,前调 c.search.search() → 不抛错;
@@ -262,13 +236,11 @@ class TestSearchDuringBuild:
         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
@@ -279,8 +251,6 @@ class TestSearchDuringBuild:
             reset_container()
 
 
-# ── 单元测:IndexBuildManager 状态机字段 ─────────────────
-
 class TestManagerStats:
     def test_stats_keys_present(self, tmp_path):
         """stats 字典字段稳定性(对外观测前端要靠这些 key)。"""
@@ -307,14 +277,11 @@ class TestManagerStats:
         )
         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):

package/python/tests/test_hkc_manifest_reuse.py

@@ -35,7 +35,6 @@ import faiss
 import numpy as np
 import pytest
 
-# ── vendor 隔离硬阻断(等价于 test_vendor_path_isolation.py 闸门 2-4) ────────
 from hkc_search.vector_search import (
     VectorIndex,
     _MANIFEST_FORMAT_VERSION,
@@ -68,8 +67,6 @@ for _cls_name, _cls in [
     _assert_vendor_path(_cls, _cls_name)
 
 
-# ── Fixtures ────────────────────────────────────────────────────────
-
 @pytest.fixture
 def stub_vector(tmp_path) -> VectorIndex:
     """已 build 3 条 KU 的 vector,save 后留磁盘文件。"""
@@ -96,23 +93,18 @@ def _ku_text(ku) -> str:
     return " ".join(parts)
 
 
-# ── M1: roundtrip(全过) ───────────────────────────────────────────
-
 class TestManifestRoundtrip:
     def test_save_load_roundtrip(self, tmp_path, stub_vector):
         """save → load 完整,数据一致(ku_ids/names/summaries/text_hashes 全部保留)。"""
         vec_path = str(tmp_path / "search_vector")
         stub_vector.save(vec_path)
-        # 落盘了 v2 manifest
         meta = pickle.loads((Path(vec_path + ".meta")).read_bytes())
         assert meta["format_version"] == _MANIFEST_FORMAT_VERSION == 2
         assert meta["ku_text_version"] == _KU_TEXT_FORMAT_VERSION == 1
-        # backend 字段以"Stub("开头(StubBackend.name 形如 "Stub(dim=384)")
         assert meta["backend"].startswith("Stub("), meta["backend"]
         assert meta["dim"] == stub_vector.dim
         assert len(meta["ku_ids"]) == 3
         assert len(meta["text_hashes"]) == 3
-        # 加载
         fresh = VectorIndex(backend=StubBackend())
         assert fresh.load(vec_path) is True
         assert fresh.size() == 3
@@ -138,13 +130,11 @@ class TestManifestRoundtrip:
         """同文本 → 同 hash(阶段 B 跨进程比对、阶段 C 续跑检测都要靠这个稳定性)。"""
         a = _hash_text("alpha 一种希腊字母")
         b = _hash_text("alpha 一种希腊字母")
-        c = _hash_text("alpha 一种希腊字母 ")   # 末尾空格,文本不同
+        c = _hash_text("alpha 一种希腊字母 ")
         assert a == b
         assert a != c
 
 
-# ── M2~M9: 8 步校验各失败路径 ───────────────────────────────────
-
 class TestManifestValidation:
     def _fresh_v2_disk(self, tmp_path) -> str:
         """构造一份合法的 v2 磁盘,返回 prefix path。"""
@@ -159,14 +149,11 @@ class TestManifestValidation:
     def test_v1_manifest_no_format_version_resets(self, tmp_path):
         """M2:旧 v1 manifest(无 format_version 字段)→ _reset。"""
         vec_path = self._fresh_v2_disk(tmp_path)
-        # 改写 meta 为 v1:仅 ku_ids/names/summaries/backend,无 format_version/dim/text_hashes
         with open(vec_path + ".meta", "wb") as f:
             pickle.dump({"ku_ids": ["X"], "names": ["x"],
                          "summaries": ["x"], "backend": "stub"}, f)
         v = VectorIndex(backend=StubBackend())
-        # 加载必失败 → 返 False
         assert v.load(vec_path) is False
-        # _reset 已清空
         assert v.size() == 0
         assert v._ku_ids == []
         assert v._text_hashes == []
@@ -224,7 +211,7 @@ class TestManifestValidation:
         vec_path = self._fresh_v2_disk(tmp_path)
         with open(vec_path + ".meta", "rb") as f:
             meta = pickle.load(f)
-        meta["text_hashes"] = meta["text_hashes"][:1]   # 只留 1 个,与 2 条 ku_ids 不一致
+        meta["text_hashes"] = meta["text_hashes"][:1]
         with open(vec_path + ".meta", "wb") as f:
             pickle.dump(meta, f)
         v = VectorIndex(backend=StubBackend())
@@ -233,8 +220,7 @@ class TestManifestValidation:
     def test_faiss_dim_mismatch_resets(self, tmp_path):
         """M8:faiss 实际维度与 meta["dim"] 不一致(切后端后常见)→ 校验失败。"""
         vec_path = self._fresh_v2_disk(tmp_path)
-        # 重建一个维度错的 faiss 文件
-        wrong_idx = faiss.IndexFlatIP(999)  # 错维度
+        wrong_idx = faiss.IndexFlatIP(999)
         wrong_idx.add(np.random.rand(2, 999).astype("float32"))
         faiss.write_index(wrong_idx, vec_path + ".faiss")
         v = VectorIndex(backend=StubBackend())
@@ -244,7 +230,6 @@ class TestManifestValidation:
     def test_faiss_ntotal_mismatch_resets(self, tmp_path):
         """M9:faiss 实际 ntotal 与 meta len(ku_ids) 不一致 → 校验失败。"""
         vec_path = self._fresh_v2_disk(tmp_path)
-        # 重建一个 ntotal=99 的 faiss(其他字段不动)
         wrong_idx = faiss.IndexFlatIP(stub_vector_dim := VectorIndex(backend=StubBackend()).dim)
         wrong_idx.add(np.random.rand(99, stub_vector_dim).astype("float32"))
         faiss.write_index(wrong_idx, vec_path + ".faiss")
@@ -266,8 +251,7 @@ class TestManifestValidation:
         v = VectorIndex(backend=StubBackend())
         kus = [ConceptKU(ku_id="KU_A", name="a", summary="a", domain="d")]
         v.build(kus)
-        # 故意破坏 invariant:删一个 text_hash
-        v._text_hashes = v._text_hashes[:0]   # 现在 _text_hashes=[] 但 _ku_ids=[KU_A]
+        v._text_hashes = v._text_hashes[:0]
         with pytest.raises(AssertionError):
             v.save(str(tmp_path / "search_vector"))
 
@@ -280,12 +264,6 @@ class TestManifestValidation:
             assert "foo msg" in str(e)
 
 
-# ── B1~B4: bm25 0 corpus 保护 ────────────────────────────────────
-# B 阶段把 BM25Index 重写为自实现倒排索引(不再包装 rank_bm25),旧私有属性
-# `_bm25` / `_ku_ids` / `_names` / `_summaries` / `_corpus` / `_rebuild_bm25`
-# 均已不存在。故断言改为验证**对外行为**(size / search),不再耦合私有结构 ——
-# 旧测试直接拼私有 list 再调私有 rebuild,是它在此次重构后失效的根因。
-
 class TestBM25EmptyCorpus:
     def test_build_empty_list(self):
         """B1:build([]) → 索引为空,search 返 []。"""
@@ -313,5 +291,4 @@ class TestBM25EmptyCorpus:
     def test_search_with_no_bm25(self):
         """B4:未 build 时 search 返 []。"""
         b = BM25Index()
-        # 不 build,直接 search
         assert b.search("anything") == []