foxclaw 0.1.0 → 0.1.3

package/python/tests/test_verify_evidence.py

@@ -0,0 +1,212 @@
+"""三个薄点:失败策略表 / 执行后核验 / 执行证据。
+
+锁住的行为(对应审核报告里「静默假成功」那一类):
+  ① 失败文本能归类成明确类型,而不是"模型自己看着办";
+  ② 只有**只读**工具会自动重试一次 —— 有副作用的动作重试等于重复扣款/重复发消息;
+  ③ 每步都有核验结论:有凭据=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)
+    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,100 @@
+"""版本号单一来源校验。
+
+版本号目前硬编码在五个地方，任何一处漏改都会造成「本地是 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 包对外导出的版本
+- ``frontend_src/package.json`` 的 ``version``     —— 前端构建工程版本
+
+本测试只做「五处必须相等」，不校验具体数值，发版时改哪一处都不用动它。
+"""
+
+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_frontend_package_version_agrees() -> None:
+    """frontend_src/package.json 与 PyPI 侧版本一致。
+
+    这个工程是 ``private`` 的构建工程,不发布,版本号曾长期停在 3.0.0
+    (Vue3 渲染层代号),与后端 0.1.2 对不上,容易误读成产品版本。
+    """
+    data = json.loads(
+        (REPO_ROOT / "frontend_src" / "package.json").read_text(encoding="utf-8"))
+    assert data["version"] == _project_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"]
+
+
+def test_frontend_does_not_hardcode_version() -> None:
+    """顶部栏版本号必须来自后端,不能在 Vue 里写死。
+
+    2026-11-10:左上角硬编码 ``v3.0``,而后端已发到 0.1.2,用户看到的版本
+    与仓库/PyPI 对不上。取值链路是 ``stores/system.js`` 请求
+    ``/api/system/info``,TopBar 只读 ``system.version``。
+    """
+    topbar = (REPO_ROOT / "frontend_src" / "src" / "components" / "TopBar.vue").read_text(
+        encoding="utf-8")
+    assert not re.search(r"\bv\d+\.\d+", topbar), "TopBar.vue 里出现了硬编码版本号"
+    assert "system.version" in topbar, "TopBar.vue 应从 system store 读 version"
+
+    store = (REPO_ROOT / "frontend_src" / "src" / "stores" / "system.js").read_text(
+        encoding="utf-8")
+    assert "/system/info" in store, "system store 应从 /api/system/info 取 version"

package/python/tests/test_web_trigger.py

@@ -0,0 +1,82 @@
+"""联网触发判定:个人数据问题绝不联网,外部世界问题正常联网。
+
+背景(链路追踪抓出来的真 bug):原先纯时间词(今天/本月/最近…)也算触发,而 Foxclaw 的
+领域(个人财务/行程/学习)天生满是时间词 → 「分析一下本月支出」这类**问自己账本**的任务
+被误判为需联网,白跑 ~22s 的付费深度搜索。错搜代价远大于漏搜,故改为:
+个人数据否决 > 外部话题触发 > 纯时间词不触发。
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+import pytest
+
+def test_web_trigger():
+    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)
+
+    personal = ["分析一下本月支出", "本月餐饮花了多少", "今天的行程安排",
+                "本周要复习什么知识点", "账户余额还剩多少", "这个月消费记录"]
+    for q in personal:
+        assert needs_search(q) is False, f"个人数据不该联网: {q}"
+    print(f"[1] 个人数据不联网({len(personal)} 例,含「本月支出」这类原 bug 用例)OK")
+
+    assert needs_search("本月支出多少钱") is False, "个人数据否决应压过话题触发"
+    assert needs_search("我的预算还剩多少钱") is False
+    print("[2] 个人数据否决压过话题触发(「本月支出多少钱」不联网)OK")
+
+    external = ["今天天气怎么样", "最新的AI新闻", "iPhone现在多少钱",
+                "特斯拉股价", "python最新版本", "美元汇率"]
+    for q in external:
+        assert needs_search(q) is True, f"外部话题应联网: {q}"
+    print(f"[3] 外部话题正常联网({len(external)} 例)OK")
+
+    assert needs_search("我的股票现在多少钱") is True, "「我的」过宽会误杀真实联网需求"
+    print("[4] 「我的股票现在多少钱」仍联网(个人标记不能放「我的」这类过宽词)OK")
+
+    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")
+
+    for q in ["你好", "帮我写个函数", ""]:
+        assert needs_search(q) is False, q
+    print("[6] 闲聊/编码/空串 不联网 OK")
+
+    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")
+
+    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")
+
+    for q in ["查一下最新的本月支出", "查一下最新的预算结余", "今天的行程 最新 查一下"]:
+        t, sid = _route_target(q)
+        assert t == "self", f"私人数据不得自动发给外部技能: {q} → {t}/{sid}"
+    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,30 @@
+"""检查磁盘 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,38 @@
+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
+}
+
+$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,13 @@
+# mypy 类型错误棘轮基线。只允许下降。
+# 2026-11-10 复核:mypy 2.4.1 / Python 3.12(.venv,依赖按 requirements.txt)→ 0 errors。
+# 历史:673(2.4.0 / 3.14 旧依赖)→ 655(cli.py 不再用 **dict 展开调 uvicorn.run)
+#      → 645(playwright_driver 收进 _require_page;_policy 用 np.float64)
+#      → 408(api/app.py 改名 bootstrap.py,解掉 101 条「子模块名遮蔽 app 变量」;
+#             路由层经 os_instance() 取共享实例,消掉 104 条 Optional 属性访问;
+#             PolicyMixin 声明宿主注入状态;-33;model_router 补 Any/Optional 注解)。
+#      → 152(基准校准;此后按批真修:httpx kwargs 类型化 / named_stage 装修饰器、
+#             None 默认字段 Optional 化、tracing+守门人句柄窄化、Literal 收窄、
+#             max/min key 改 lambda、坐标与脏输入窄化)。
+#      → 0(2026-11-10:余量清空。修法一律是真修——Optional 注解、局部变量窄化、
+#             cast(Literal)、诚实返回类型;未新增 type: ignore,未放宽 mypy 配置)
+0