foxclaw 0.1.0 → 0.1.2

package/python/tests/test_url_policy.py

@@ -0,0 +1,53 @@
+"""浏览器导航 URL 准入策略(SSRF / 本地文件读取防护)。
+
+背景:`ActionExecutor._do_navigate` 原本把模型给的字符串直接交给 driver,
+`file://` 可读本机文件、`javascript:` 可在页面上下文执行、内网地址可作探测跳板。
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from foxclaw.browser.action.url_policy import validate_navigate_url
+
+
+@pytest.mark.parametrize("url", [
+    "file:///C:/Windows/win.ini",
+    "javascript:alert(1)",
+    "data:text/html,<script>alert(1)</script>",
+    "blob:https://example.com/uuid",
+    "ftp://example.com/x",
+])
+def test_rejects_non_http_schemes(url: str) -> None:
+    with pytest.raises(ValueError):
+        validate_navigate_url(url)
+
+
+@pytest.mark.parametrize("url", [
+    "http://127.0.0.1:8000/api/ahs/run",
+    "http://localhost/admin",
+    "http://[::1]:9000/",
+    "http://169.254.169.254/latest/meta-data/",
+    "http://10.0.0.5/",
+    "http://192.168.1.1/",
+])
+def test_rejects_internal_targets(url: str) -> None:
+    with pytest.raises(ValueError):
+        validate_navigate_url(url)
+
+
+def test_allows_public_url() -> None:
+    assert validate_navigate_url("https://example.com/a?b=1") == "https://example.com/a?b=1"
+
+
+def test_allow_private_escape_hatch(monkeypatch) -> None:
+    assert validate_navigate_url("http://127.0.0.1:8000/", allow_private=True) \
+        == "http://127.0.0.1:8000/"
+    monkeypatch.setenv("FOXCLAW_BROWSER_ALLOW_PRIVATE", "1")
+    assert validate_navigate_url("http://192.168.1.10/") == "http://192.168.1.10/"
+
+
+def test_rejects_empty_and_missing_host() -> None:
+    for bad in ("", "   ", "http://"):
+        with pytest.raises(ValueError):
+            validate_navigate_url(bad)

package/python/tests/test_verify_evidence.py

@@ -0,0 +1,225 @@
+"""三个薄点:失败策略表 / 执行后核验 / 执行证据。
+
+锁住的行为(对应审核报告里「静默假成功」那一类):
+  ① 失败文本能归类成明确类型,而不是"模型自己看着办";
+  ② 只有**只读**工具会自动重试一次 —— 有副作用的动作重试等于重复扣款/重复发消息;
+  ③ 每步都有核验结论:有凭据=verified,没后置条件=unverified,失败=failed,**空结果不算成功**;
+  ④ 证据只从真实返回里抽 URL / 磁盘上存在的文件,认不出的路径不冒充证据;
+  ⑤ 这些结论挂到会话槽并由 `_run_tool_calls` 记账,不上屏到用户正文;
+  ⑥ 成功结果的回注文本一个字都不改(否则会污染既有工具轮行为)。
+"""
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+from foxclaw.agents.mixins import tool_exec
+from foxclaw.core import failure_policy as policy
+from foxclaw.core import tools as core_tools
+from foxclaw.core import verify as vf
+
+TIMEOUT_TEXT = "(工具 web_search 超过 45s 未返回,已跳过以免拖住整轮)"
+
+
+class _Rec:
+    def __init__(self):
+        self.steps: list = []
+
+    def record_step(self, tid, step):
+        self.steps.append((tid, step))
+
+
+def _agent():
+    a = types.SimpleNamespace()
+    a._recovery = _Rec()
+    a._session_id = "sess_test"
+    return a
+
+
+# ── ① 失败策略表 ─────────────────────────────────────────────
+
+@pytest.mark.parametrize("text,kind", [
+    (TIMEOUT_TEXT, policy.TIMEOUT),
+    ("(工具 shell 已被策略禁用)", policy.DENIED),
+    ("(联网搜索未配置,已降级)", policy.NOT_CONFIGURED),
+    ("(入参不合法:缺少必填 query)", policy.INVALID_ARGS),
+    ("(联网搜索未返回结果)", policy.EMPTY),
+    ("(工具 web_search 执行异常:boom)", policy.EXCEPTION),
+    ("中国未来十年的产业趋势如何", policy.OK),          # 正文含"未"不能误判
+    ("", policy.UNKNOWN),                              # 空结果不能当成功
+    ("一切正常", policy.OK),
+])
+def test_classify(text, kind) -> None:
+    assert policy.classify(text) == kind
+
+
+def test_retry_only_for_read_only() -> None:
+    read = policy.decide(TIMEOUT_TEXT, capability={"read_only": True}, attempt=1)
+    assert read.action == policy.RETRY
+    # 第二次还失败 → 不再重试,交人
+    assert policy.decide(TIMEOUT_TEXT, capability={"read_only": True}, attempt=2).action \
+        == policy.HAND_TO_HUMAN
+    # 有副作用:第一次就不许自动重试
+    write = policy.decide(TIMEOUT_TEXT, capability={"read_only": False}, attempt=1)
+    assert write.action == policy.HAND_TO_HUMAN
+    assert "重复执行" in write.hint
+
+
+def test_decide_never_optimistic() -> None:
+    assert policy.decide("(联网搜索未配置)").action == policy.DEGRADE
+    assert policy.decide("(工具 x 已被策略禁用)").action == policy.STOP
+    # 形如失败但聊不归类 → 保守交人,不乐观当成功
+    assert policy.decide("(看不懂的回注").kind == policy.UNKNOWN
+    assert policy.decide("(看不懂的回注").action == policy.HAND_TO_HUMAN
+
+
+def test_annotate_leaves_success_untouched() -> None:
+    d = policy.decide("搜索到的正文", capability={"read_only": True})
+    assert policy.annotate("搜索到的正文", d) == "搜索到的正文"
+    out = policy.annotate(TIMEOUT_TEXT, policy.decide(TIMEOUT_TEXT, capability={"read_only": True},
+                                                     attempt=2))
+    assert out.startswith(TIMEOUT_TEXT)
+    assert "[执行策略]" in out
+
+
+# ── ② 执行后核验 ─────────────────────────────────────────────
+
+def test_failure_is_failed_not_verified() -> None:
+    v = vf.verify("web_search", {}, TIMEOUT_TEXT, {"read_only": True})
+    assert v.status == vf.FAILED
+    assert v.reason.startswith("失败类型")
+
+
+def test_empty_result_is_not_success() -> None:
+    v = vf.verify("web_search", {}, "", {"read_only": True})
+    assert v.status == vf.FAILED
+
+
+def test_read_tool_with_payload_is_verified(tmp_path) -> None:
+    p = tmp_path / "report.md"
+    p.write_text("x", encoding="utf-8")
+    v = vf.verify("read_file", {}, f"见 {p}", {"read_only": True})
+    assert v.status == vf.VERIFIED
+    assert [e.kind for e in v.evidence] == ["file"]
+    assert v.evidence[0].ref == str(p)
+
+
+def test_side_effect_without_postcondition_is_unverified() -> None:
+    v = vf.verify("send_mail", {}, "已发送", {"read_only": False})
+    assert v.status == vf.UNVERIFIED
+    assert "后置条件" in v.reason
+    # 只读工具拿到内容就算这一步发生过(内容可信度归污点层)
+    assert vf.verify("recall_memory", {}, "【召回的相关记忆】\n- a", {"read_only": True}).status \
+        == vf.VERIFIED
+
+
+def test_web_search_without_source_is_unverified() -> None:
+    v = vf.verify("web_search", {}, "【联网搜索结果】据行业报告……", {"read_only": True})
+    assert v.status == vf.UNVERIFIED
+    assert "来源" in v.reason
+    v2 = vf.verify("web_search", {}, "【联网搜索结果】见 https://example.com/a", {"read_only": True})
+    assert v2.status == vf.VERIFIED
+    assert v2.evidence[0].label == "example.com"
+
+
+def test_evidence_only_counts_real_paths(tmp_path) -> None:
+    ghost = "C:/definitely/not/here/x.md"
+    assert vf.extract_evidence("read_file", f"读了 {ghost}") == []
+    real = tmp_path / "a.md"
+    real.write_text("x", encoding="utf-8")
+    ev = vf.extract_evidence("read_file", f"读了 {real}")
+    assert [e.ref for e in ev] == [str(real)]
+
+
+def test_evidence_dedup_and_cap() -> None:
+    text = " ".join([f"https://example.com/{i}" for i in range(20)]) + " https://example.com/1"
+    ev = vf.extract_evidence("web_search", text)
+    assert len(ev) == vf.MAX_EVIDENCE
+    assert len({e.ref for e in ev}) == vf.MAX_EVIDENCE
+
+
+def test_note_for_model() -> None:
+    ok = vf.Verification(vf.VERIFIED)
+    assert vf.note_for_model(ok) == ""
+    un_read = vf.Verification(vf.UNVERIFIED, "无来源")
+    assert vf.note_for_model(un_read, read_only=True) == ""      # 只读不训话,免得污染上下文
+    assert "不要断言" in vf.note_for_model(un_read, read_only=False)
+    bad = vf.Verification(vf.FAILED, "失败类型:timeout")
+    assert "不要向用户声称" in vf.note_for_model(bad)
+
+
+# ── ③ 接进工具轮 ─────────────────────────────────────────────
+
+def test_retries_read_only_once_then_gives_up(monkeypatch) -> None:
+    agent = _agent()
+    batches: list = []
+
+    def fake_batch(a, calls):
+        batches.append([c["name"] for c in calls])
+        return [TIMEOUT_TEXT] * len(calls)
+
+    monkeypatch.setattr(tool_exec, "_run_tools_batch", fake_batch)
+    monkeypatch.setattr(core_tools, "tool_capability", lambda n: {"read_only": True})
+    out = tool_exec._run_tool_calls(agent, [{"name": "web_search", "args": {"q": "x"}}])
+
+    assert len(batches) == 2                     # 第一次 + 自动重试一次
+    assert "[执行策略]" in out[0] and "不要" in out[0]
+    assert agent._recovery.steps == []           # 失败的步不许存进断点
+    ev = agent._evidence_list
+    assert ev and ev[0]["status"] == vf.FAILED
+
+
+def test_side_effect_failure_is_not_retried(monkeypatch) -> None:
+    agent = _agent()
+    batches: list = []
+    monkeypatch.setattr(tool_exec, "_run_tools_batch",
+                        lambda a, calls: (batches.append(len(calls)), [TIMEOUT_TEXT] * len(calls))[1])
+    monkeypatch.setattr(core_tools, "tool_capability", lambda n: {"read_only": False})
+    out = tool_exec._run_tool_calls(agent, [{"name": "send_mail", "args": {}}])
+    assert batches == [1]                        # 一次,不重试
+    assert "重复执行" in out[0]
+
+
+def test_success_text_untouched_and_evidence_recorded(monkeypatch) -> None:
+    agent = _agent()
+    monkeypatch.setattr(tool_exec, "_run_tools_batch",
+                        lambda a, calls: ["【联网搜索结果】结论 https://example.com/a"] * len(calls))
+    monkeypatch.setattr(core_tools, "tool_capability", lambda n: {"read_only": True})
+    out = tool_exec._run_tool_calls(agent, [{"name": "web_search", "args": {"q": "x"}}])
+
+    assert out[0] == "【联网搜索结果】结论 https://example.com/a"      # 成功文本不被改
+    assert len(agent._recovery.steps) == 1                           # 成功的步可复用
+    ev = agent._evidence_list[0]
+    assert ev["status"] == vf.VERIFIED
+    assert ev["evidence"][0]["ref"] == "https://example.com/a"
+
+
+def test_unverified_side_effect_tells_model_not_to_claim_done(monkeypatch) -> None:
+    agent = _agent()
+    monkeypatch.setattr(tool_exec, "_run_tools_batch", lambda a, calls: ["已发送"] * len(calls))
+    monkeypatch.setattr(core_tools, "tool_capability", lambda n: {"read_only": False})
+    out = tool_exec._run_tool_calls(agent, [{"name": "send_mail", "args": {}}])
+    assert out[0].startswith("已发送")
+    assert "不要断言" in out[0]
+    assert agent._evidence_list[0]["status"] == vf.UNVERIFIED
+
+
+# ── ④ 证据不串台 ─────────────────────────────────────────────
+
+def test_evidence_is_per_agent() -> None:
+    from foxclaw.agents.mixins import _context
+
+    a, b = _agent(), _agent()
+    _context._evidence_reset(a)
+    _context._evidence_reset(b)
+    _context._evidence_add(a, {"tool": "x", "status": "verified"})
+    assert _context._evidence_take(a) and not _context._evidence_take(b)
+    # take 之后清空:下一轮不会重复上报上一轮的证据
+    assert _context._evidence_take(a) == []
+
+
+def test_verify_never_raises_on_weird_input() -> None:
+    assert vf.verify("web_search", {}, "(((", None).status == vf.FAILED
+    assert vf.verify("unknown_tool", None, "ok", None).status == vf.UNVERIFIED

package/python/tests/test_version_sync.py

@@ -0,0 +1,71 @@
+"""版本号单一来源校验。
+
+版本号目前硬编码在四个地方，任何一处漏改都会造成「本地是 0.2.0、npm 上
+还是 0.1.0」这类对外不一致（`npm/index.js` 的 version 是发布物里用户
+`import` 直接读到的值，最容易漏）：
+
+- ``pyproject.toml`` 的 ``project.version``      —— PyPI 包版本
+- ``foxclaw/__init__.py`` 的 ``__version__`` —— 运行时 ``foxclaw --version``
+- ``npm/package.json`` 的 ``version``             —— npm 包版本
+- ``npm/index.js`` 的 ``export const version``    —— npm 包对外导出的版本
+
+本测试只做「四处必须相等」，不校验具体数值，发版时改哪一处都不用动它。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from pathlib import Path
+
+from foxclaw import __version__
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+NPM_DIR = REPO_ROOT / "npm"
+
+
+def _project_version() -> str:
+    with (REPO_ROOT / "pyproject.toml").open("rb") as fh:
+        return tomllib.load(fh)["project"]["version"]
+
+
+def _project_name() -> str:
+    with (REPO_ROOT / "pyproject.toml").open("rb") as fh:
+        return tomllib.load(fh)["project"]["name"]
+
+
+def _npm_package() -> dict:
+    return json.loads((NPM_DIR / "package.json").read_text(encoding="utf-8"))
+
+
+def test_python_versions_agree() -> None:
+    """pyproject 与运行时 __version__ 一致。"""
+    assert __version__ == _project_version()
+
+
+def test_npm_package_version_agrees() -> None:
+    """npm/package.json 与 PyPI 侧版本一致。"""
+    assert _npm_package()["version"] == _project_version()
+
+
+def test_npm_index_export_version_agrees() -> None:
+    """npm/index.js 导出值（发布物对外可见）与 package.json 一致。"""
+    source = (NPM_DIR / "index.js").read_text(encoding="utf-8")
+    match = re.search(r'export\s+const\s+version\s*=\s*["\']([^"\']+)["\']', source)
+    assert match, "npm/index.js 里找不到 `export const version = \"...\"`"
+    assert match.group(1) == _npm_package()["version"]
+
+
+def test_package_names_are_foxclaw() -> None:
+    """PyPI 与 npm 两侧包名必须同名，且为 foxclaw。"""
+    assert _project_name() == "foxclaw"
+    assert _npm_package()["name"] == _project_name()
+
+
+def test_npm_index_export_name_agrees() -> None:
+    """npm/index.js 导出的 name 与 package.json 一致。"""
+    source = (NPM_DIR / "index.js").read_text(encoding="utf-8")
+    match = re.search(r'export\s+const\s+name\s*=\s*["\']([^"\']+)["\']', source)
+    assert match, "npm/index.js 里找不到 `export const name = \"...\"`"
+    assert match.group(1) == _npm_package()["name"]

package/python/tests/test_web_trigger.py

@@ -0,0 +1,99 @@
+"""联网触发判定:个人数据问题绝不联网,外部世界问题正常联网。
+
+背景(链路追踪抓出来的真 bug):原先纯时间词(今天/本月/最近…)也算触发,而 Foxclaw 的
+领域(个人财务/行程/学习)天生满是时间词 → 「分析一下本月支出」这类**问自己账本**的任务
+被误判为需联网,白跑 ~22s 的付费深度搜索。错搜代价远大于漏搜,故改为:
+个人数据否决 > 外部话题触发 > 纯时间词不触发。
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+import pytest
+
+def test_web_trigger():
+    # ISOLATION_GUARD:本用例依赖 import 时固化的模块级单例(网关/限流器/路由配置按 env 在 import 时定型),单进程全量跑会被前序用例污染 →
+    # 假红。全量请用 tests/run_all.py(每文件独立子进程)。
+    if "foxclaw.core.web_search" in sys.modules:
+        pytest.skip("需独立进程运行(模块级单例已固化),请用 tests/run_all.py")
+    from foxclaw.core.web_search import (needs_search, TOPIC_TRIGGERS,
+                                        TIME_WORDS)
+
+    print("=" * 60); print("联网触发判定验证"); print("=" * 60)
+
+    # [1] 个人数据 → 绝不联网(答案在本地领域内核里,不在网上)
+    personal = ["分析一下本月支出", "本月餐饮花了多少", "今天的行程安排",
+                "本周要复习什么知识点", "账户余额还剩多少", "这个月消费记录"]
+    for q in personal:
+        assert needs_search(q) is False, f"个人数据不该联网: {q}"
+    print(f"[1] 个人数据不联网({len(personal)} 例,含「本月支出」这类原 bug 用例)OK")
+
+    # [2] 个人数据 + 话题词 → 仍不联网(否决优先级最高)
+    #     「本月支出多少钱」含话题词「多少钱」,但问的是自己的账 → 必须否决
+    assert needs_search("本月支出多少钱") is False, "个人数据否决应压过话题触发"
+    assert needs_search("我的预算还剩多少钱") is False
+    print("[2] 个人数据否决压过话题触发(「本月支出多少钱」不联网)OK")
+
+    # [3] 外部世界话题 → 正常联网(不能因为修 bug 把真需求也砍了)
+    external = ["今天天气怎么样", "最新的AI新闻", "iPhone现在多少钱",
+                "特斯拉股价", "python最新版本", "美元汇率"]
+    for q in external:
+        assert needs_search(q) is True, f"外部话题应联网: {q}"
+    print(f"[3] 外部话题正常联网({len(external)} 例)OK")
+
+    # [4] 「我的」不算个人标记 —— 「我的股票现在多少钱」是真要联网的
+    assert needs_search("我的股票现在多少钱") is True, "「我的」过宽会误杀真实联网需求"
+    print("[4] 「我的股票现在多少钱」仍联网(个人标记不能放「我的」这类过宽词)OK")
+
+    # [5] 纯时间词不触发(本 bug 的核心)
+    for q in ["现在几点", "最近怎么样", "今天", "本月"]:
+        assert needs_search(q) is False, f"纯时间词不该单独触发: {q}"
+    assert not (set(TIME_WORDS) & set(TOPIC_TRIGGERS)), "时间词不得混入话题触发表(否则 bug 复发)"
+    print(f"[5] 纯时间词不单独触发({len(TIME_WORDS)} 个时间词与话题表零交集)OK")
+
+    # [6] 闲聊/编码 → 不联网
+    for q in ["你好", "帮我写个函数", ""]:
+        assert needs_search(q) is False, q
+    print("[6] 闲聊/编码/空串 不联网 OK")
+
+    # [7] 英文词边界仍生效(旧修复不能退化:now⊄knowledge, current⊄concurrent)
+    assert needs_search("knowledge base") is False, "now 不该子串命中 knowledge"
+    assert needs_search("concurrent tasks") is False, "current 不该子串命中 concurrent"
+    assert needs_search("latest news") is True
+    print("[7] 英文词边界不退化(knowledge/concurrent 不误命中)OK")
+
+    # [8] 【防复发·跨路径】个人数据保护必须是**单一真源**,所有"要不要发到外部"的路径都得遵守。
+    #     真实教训:这条保护原先只写在 needs_search 里;技能派发默认开启后,
+    #     「查一下最新的本月支出」经**技能路由**照样把私人财务问题发去 external 的 web_search
+    #     —— 同一个 bug 从没设防的旁路回来了,还多了数据外泄。
+    from foxclaw.core.web_search import is_personal_query
+    from foxclaw.pipeline import stage_route
+    from foxclaw.pipeline.cognitive_pipeline import PipelineContext
+    from foxclaw.skills import build_default_registry
+
+    assert is_personal_query("查一下最新的本月支出") is True
+    assert is_personal_query("查一下最新新闻") is False
+
+    _reg = build_default_registry()
+    class _A: pass
+    def _route_target(task):
+        a = _A(); a.skill_registry = _reg
+        ctx = PipelineContext(agent=a, task=task)
+        stage_route(ctx)
+        return ctx.route["target"], ctx.route.get("skill_id")
+
+    # 私人数据 + 足够高的置信 → 仍不得路由到 **external** 技能(否则就是外泄)
+    for q in ["查一下最新的本月支出", "查一下最新的预算结余", "今天的行程 最新 查一下"]:
+        t, sid = _route_target(q)
+        assert t == "self", f"私人数据不得自动发给外部技能: {q} → {t}/{sid}"
+    # 但真实的外部问题照常走技能(不能因为修 bug 把功能砍了)
+    t, sid = _route_target("查一下最新新闻")
+    assert (t, sid) == ("skill", "web_search"), (t, sid)
+    # 本地只读技能不受影响
+    t, sid = _route_target("帮我计算 (12+8)*5")
+    assert (t, sid) == ("skill", "calculator"), (t, sid)
+    print("[8] 跨路径防复发:技能路由也遵守个人数据保护(不外泄)+ 不误伤真实外部需求 OK")
+
+    print("\n联网触发判定验证全部通过")
+
+if __name__ == "__main__":
+    test_web_trigger()

package/python/tools/check_faiss_type.py

@@ -0,0 +1,31 @@
+"""检查磁盘 faiss 索引的类型和 ntotal(不依赖服务进程)"""
+import sys
+import os
+from pathlib import Path
+
+# 默认路径:仓库根下的运行数据目录,可用第一个命令行参数覆盖
+faiss_path = str(Path(__file__).resolve().parents[1] / "foxclaw_data" / "hkc" / "search_vector.faiss")
+if len(sys.argv) > 1:
+    faiss_path = sys.argv[1]
+
+if not os.path.exists(faiss_path):
+    print(f"NOT_FOUND: {faiss_path}")
+    sys.exit(1)
+
+try:
+    import faiss
+except ImportError:
+    print("faiss-cpu not installed (try: pip install faiss-cpu)")
+    sys.exit(1)
+
+print(f"path: {faiss_path}")
+print(f"size: {os.path.getsize(faiss_path)} bytes")
+
+idx = faiss.read_index(faiss_path)
+print(f"type : {type(idx).__name__}")
+print(f"ntotal: {idx.ntotal}")
+print(f"dim  : {idx.d}")
+if hasattr(idx, "nlist"):
+    print(f"nlist: {idx.nlist}")
+if hasattr(idx, "metric_type"):
+    print(f"metric: {idx.metric_type}")

package/python/tools/check_log.ps1

@@ -0,0 +1,46 @@
+# tools/check_log.ps1
+# 检查 uvicorn 日志中是否有 IVF 升级关键字(行扫描 + FileShare.ReadWrite 兼容锁文件)。
+# 用法:
+#   powershell -NoProfile -File tools\check_log.ps1            # 查 stdout(uvicorn.log)
+#   powershell -NoProfile -File tools\check_log.ps1 err        # 查 stderr(uvicorn.err.log)
+#   powershell -NoProfile -File tools\check_log.ps1 err grep   # 仅 grep 'VectorIndex 升级' 行
+param(
+    [ValidateSet("stdout","err")] $which = "stdout",
+    [switch] $grep
+)
+$ErrorActionPreference = "Continue"
+
+$logDir = Join-Path (Split-Path -Parent $PSScriptRoot) "foxclaw_data"
+$log    = if ($which -eq "err") { "$logDir\uvicorn.err.log" } else { "$logDir\uvicorn.log" }
+
+if (-not (Test-Path $log)) {
+    Write-Host "[NOT FOUND] $log"
+    exit 1
+}
+
+# 用 [System.IO.File]::Open + FileShare.ReadWrite 兼容 python 文件正在写入的日志
+# (PowerShell 5.1 Get-Content 在 UTF-8 + 文件被锁场景会返空,见 review [2])
+$fs = [System.IO.File]::Open($log, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileShare]::ReadWrite)
+$reader = New-Object System.IO.StreamReader($fs, [System.Text.Encoding]::UTF8)
+$content = $reader.ReadToEnd()
+$reader.Close()
+$fs.Close()
+
+if ($grep) {
+    foreach ($line in ($content -split "`n")) {
+        if ($line -match "VectorIndex 升级|VectorIndex 升级失败") {
+            Write-Host $line
+        }
+    }
+    return
+}
+
+Write-Host "log file: $log (size=$($content.Length))"
+Write-Host ("has_VectorIndex="     + $content.Contains("VectorIndex"))
+Write-Host ("has_IVF="             + $content.Contains("IVF"))
+Write-Host ("has_upgrade_zh="      + $content.Contains("升级"))
+Write-Host ("has_IndexFlat="       + $content.Contains("IndexFlat"))
+Write-Host ("has_IndexIVF="        + $content.Contains("IndexIVF"))
+Write-Host "--- last 1500 chars ---"
+$start = [Math]::Max(0, $content.Length - 1500)
+Write-Host $content.Substring($start)

package/python/tools/ivf_status.py

@@ -0,0 +1,72 @@
+"""检查 vector 索引状态 + 距离自动升级还差多少。
+
+用法:
+    python tools/ivf_status.py
+
+输出:
+    vector_size, bm25_size, index_state, pending_ops
+    距 HKC_VECTOR_IVF_THRESHOLD 阈值还差多少 KU
+    下次升级触发时日志关键词
+
+可调环境变量:
+    HKC_VECTOR_IVF_THRESHOLD  默认 10000(对应 .env 里的设定)
+    HKC_STATS_URL              默认 http://127.0.0.1:8000/stats
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+
+THRESHOLD  = int(os.environ.get("HKC_VECTOR_IVF_THRESHOLD", "10000"))
+STATS_URL  = os.environ.get("HKC_STATS_URL", "http://127.0.0.1:8000/stats")
+UPGRADE_KEYWORD = "VectorIndex 升级: Flat → IVF"
+
+
+def fetch_stats(url: str) -> dict:
+    with urllib.request.urlopen(url, timeout=5) as r:
+        return json.loads(r.read())
+
+
+def main() -> int:
+    try:
+        s = fetch_stats(STATS_URL)
+    except Exception as e:
+        print(f"[ERROR] 拉 {STATS_URL} 失败: {e}")
+        return 1
+
+    vs       = s.get("vector_size", 0)
+    bs       = s.get("bm25_size", 0)
+    ib       = s.get("index_build", {}) or {}
+    state    = ib.get("index_state", "?")
+    pending  = s.get("pending_ops", 0)
+    task_id  = ib.get("task_id", "-")
+
+    remaining = max(0, THRESHOLD - vs)
+    pct       = min(100.0, vs / THRESHOLD * 100) if THRESHOLD > 0 else 100.0
+
+    print("=" * 50)
+    print(f"vector_size  : {vs}")
+    print(f"bm25_size    : {bs}")
+    print(f"index_state  : {state}    task_id={task_id}")
+    print(f"pending_ops  : {pending}")
+    print(f"threshold    : {THRESHOLD}")
+    print(f"progress     : {pct:5.1f}%  (距升级还差 {remaining} KU)")
+    print("=" * 50)
+
+    if THRESHOLD <= 0:
+        print("阶段: Flat (升级禁用,env HKC_VECTOR_IVF_THRESHOLD=0)")
+    elif vs < THRESHOLD:
+        print(f"阶段: Flat (IndexFlatIP, O(N) 暴力精确)")
+        print(f"下次 vector_size 跨过 {THRESHOLD} 时 append_ku 会触发升级")
+        print(f"触发后看日志:    grep '{UPGRADE_KEYWORD}' <foxclaw.log>")
+    else:
+        print(f"阶段: IVF (IndexIVFFlat, O(√N) 倒排)")
+        print(f"升级日志关键词:  '{UPGRADE_KEYWORD}'")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/python/tools/mypy_baseline.txt

@@ -0,0 +1,5 @@
+# mypy 类型错误棘轮基线。只允许下降。
+# 2026-11-09 实测:mypy 2.4.0 / Python 3.14.5 下 673 errors in 90 files。
+# 注意:CI 跑在 Python 3.12 上,若首次因解释器差异导致数字略有不同,
+# 先在 CI 同版本下跑一次 `python tools/mypy_ratchet.py --update` 校准基线。
+673