foxclaw 0.1.2 → 0.1.4

package/python/tests/test_update_check.py

@@ -0,0 +1,95 @@
+"""新版本检查:默认关、版本比较、缓存 TTL、失败静默。
+
+全部离线:``_fetch_latest`` 一律用 monkeypatch 替换,不发真实网络请求。
+"""
+
+from __future__ import annotations
+
+import time
+
+from foxclaw.core import update_check as uc
+
+
+def _reset() -> None:
+    uc._inflight = False
+
+
+def test_default_disabled(monkeypatch, tmp_path):
+    """不设 FOXCLAW_UPDATE_CHECK → 不查、不写缓存、不起线程。"""
+    _reset()
+    monkeypatch.delenv("FOXCLAW_UPDATE_CHECK", raising=False)
+    monkeypatch.setenv("FOXCLAW_DATA_DIR", str(tmp_path))
+
+    assert uc.status()["enabled"] is False
+    uc.maybe_refresh()
+    assert uc._inflight is False
+    assert not (tmp_path / "update_check.json").exists()
+
+
+def test_version_compare():
+    assert uc.parse_version("0.1.10") == (0, 1, 10)
+    assert uc.parse_version("0.2.0rc1") == (0, 2, 0)
+    assert uc.parse_version("") == ()
+    assert uc.is_newer("0.1.10", "0.1.2") is True
+    assert uc.is_newer("0.1.2", "0.1.2") is False
+    assert uc.is_newer("0.1.2", "0.1.10") is False
+
+
+def test_refresh_writes_cache(monkeypatch, tmp_path):
+    _reset()
+    monkeypatch.setenv("FOXCLAW_UPDATE_CHECK", "1")
+    monkeypatch.setenv("FOXCLAW_DATA_DIR", str(tmp_path))
+    monkeypatch.setattr(uc, "_fetch_latest", lambda: "9.9.9")
+
+    uc._refresh()
+
+    st = uc.status()
+    assert st["latest"] == "9.9.9"
+    assert st["update_available"] is True
+    assert st["error"] is None
+    assert (tmp_path / "update_check.json").exists()
+
+
+def test_fresh_cache_skips_refresh(monkeypatch, tmp_path):
+    """24h 内不重复查 PyPI。"""
+    _reset()
+    monkeypatch.setenv("FOXCLAW_UPDATE_CHECK", "1")
+    monkeypatch.setenv("FOXCLAW_DATA_DIR", str(tmp_path))
+    uc._write_cache({"latest": "9.9.9", "checked_at": time.time(), "current": "0.1.2"})
+
+    calls: list[int] = []
+    monkeypatch.setattr(uc, "_fetch_latest", lambda: calls.append(1) or "9.9.9")
+    uc.maybe_refresh()
+    time.sleep(0.05)
+
+    assert calls == []
+    assert uc._inflight is False
+
+
+def test_failure_is_silent(monkeypatch, tmp_path):
+    """网络失败不抛异常,只记 error;update_available 仍为 False。"""
+    _reset()
+    monkeypatch.setenv("FOXCLAW_UPDATE_CHECK", "1")
+    monkeypatch.setenv("FOXCLAW_DATA_DIR", str(tmp_path))
+
+    def boom():
+        raise OSError("offline")
+
+    monkeypatch.setattr(uc, "_fetch_latest", boom)
+    uc._refresh()
+
+    st = uc.status()
+    assert st["update_available"] is False
+    assert "offline" in (st["error"] or "")
+
+
+def test_disabled_never_reports_update(monkeypatch, tmp_path):
+    """缓存里就算有更新的版本,没启用也不提示(默认不外呼,也不拿旧缓存骚扰)。"""
+    _reset()
+    monkeypatch.delenv("FOXCLAW_UPDATE_CHECK", raising=False)
+    monkeypatch.setenv("FOXCLAW_DATA_DIR", str(tmp_path))
+    uc._write_cache({"latest": "99.0.0", "checked_at": time.time(), "current": "0.1.2"})
+
+    st = uc.status()
+    assert st["enabled"] is False
+    assert st["update_available"] is False

package/python/tests/test_verify_evidence.py

@@ -38,8 +38,6 @@ def _agent():
     return a
 
 
-# ── ① 失败策略表 ─────────────────────────────────────────────
-
 @pytest.mark.parametrize("text,kind", [
     (TIMEOUT_TEXT, policy.TIMEOUT),
     ("(工具 shell 已被策略禁用)", policy.DENIED),
@@ -47,8 +45,8 @@ def _agent():
     ("(入参不合法:缺少必填 query)", policy.INVALID_ARGS),
     ("(联网搜索未返回结果)", policy.EMPTY),
     ("(工具 web_search 执行异常:boom)", policy.EXCEPTION),
-    ("中国未来十年的产业趋势如何", policy.OK),          # 正文含"未"不能误判
-    ("", policy.UNKNOWN),                              # 空结果不能当成功
+    ("中国未来十年的产业趋势如何", policy.OK),
+    ("", policy.UNKNOWN),
     ("一切正常", policy.OK),
 ])
 def test_classify(text, kind) -> None:
@@ -58,10 +56,8 @@ def test_classify(text, kind) -> None:
 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
@@ -70,7 +66,6 @@ def test_retry_only_for_read_only() -> None:
 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
 
@@ -84,8 +79,6 @@ def test_annotate_leaves_success_untouched() -> None:
     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
@@ -110,7 +103,6 @@ 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
 
@@ -144,14 +136,12 @@ 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 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 = []
@@ -164,9 +154,9 @@ def test_retries_read_only_once_then_gives_up(monkeypatch) -> None:
     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 len(batches) == 2
     assert "[执行策略]" in out[0] and "不要" in out[0]
-    assert agent._recovery.steps == []           # 失败的步不许存进断点
+    assert agent._recovery.steps == []
     ev = agent._evidence_list
     assert ev and ev[0]["status"] == vf.FAILED
 
@@ -178,7 +168,7 @@ def test_side_effect_failure_is_not_retried(monkeypatch) -> None:
                         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 batches == [1]
     assert "重复执行" in out[0]
 
 
@@ -189,8 +179,8 @@ def test_success_text_untouched_and_evidence_recorded(monkeypatch) -> None:
     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                           # 成功的步可复用
+    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"
@@ -206,8 +196,6 @@ def test_unverified_side_effect_tells_model_not_to_claim_done(monkeypatch) -> No
     assert agent._evidence_list[0]["status"] == vf.UNVERIFIED
 
 
-# ── ④ 证据不串台 ─────────────────────────────────────────────
-
 def test_evidence_is_per_agent() -> None:
     from foxclaw.agents.mixins import _context
 
@@ -216,7 +204,6 @@ def test_evidence_is_per_agent() -> None:
     _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) == []
 
 

package/python/tests/test_version_sync.py

@@ -1,15 +1,16 @@
 """版本号单一来源校验。
 
-版本号目前硬编码在四个地方，任何一处漏改都会造成「本地是 0.2.0、npm 上
+版本号目前硬编码在五个地方，任何一处漏改都会造成「本地是 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 包对外导出的版本
+- ``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
@@ -57,6 +58,17 @@ def test_npm_index_export_version_agrees() -> None:
     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"
@@ -69,3 +81,20 @@ def test_npm_index_export_name_agrees() -> None:
     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

@@ -11,8 +11,6 @@ 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,
@@ -20,51 +18,39 @@ def test_web_trigger():
 
     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
@@ -81,14 +67,11 @@ def test_web_trigger():
         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")

package/python/tools/build_content_lexicon.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python
+"""把外部敏感词库(如 houbb/sensitive-word)转成 ContentGuard 可挂载的词表格式。
+
+为什么要转换而不是直接挂
+──────────────────────
+`ContentGuard` 载入时会对每个词做一次 `compact()`(去空白标点、全半角归一、小写),
+但那只保证「扫描时能对上」,不保证词表本身干净:同一批词里 `敏感词`、`敏 感 词`、
+`ＳＥＮＳＩＴＩＶＥ` 会各占一条,白白撑大自动机。转换期先统一形态,词表体积和重复率
+都能压下来。
+
+输出格式就是 `FOXCLAW_CONTENT_LEXICON` 认的那一种:一行一条 `词<TAB>类别`,`#` 开头为
+注释。类别会原样出现在命中结果里,便于审计归类。
+
+词库形态
+────────
+两种都认,不用改文件:
+  * 单文件纯词列表(houbb 主词库):文件名不带中文时用 `--category`(默认 platform)。
+  * 一个文件一个类别(`政治类.txt` / `色情类.txt` / ...):中文文件名直接当类别名。
+
+哪些类别挂上去由你决定。脚本默认照单全收 —— 排除政治 / 色情 / 暴力这些大类是部署决策,
+不该由转换工具替你拍板。用 `--exclude` / `--include`(支持 `通配*`)自己取舍。
+
+用法
+────
+    # 主词库,单一类别
+    python tools/build_content_lexicon.py ../houbb/sensitive_word_dict.txt
+
+    # 分类词库,只留自己需要的
+    python tools/build_content_lexicon.py dict/*.txt --exclude 政治类,色情类 --exclude "暴力*"
+
+    # 指定类别名与输出路径,转换后自动验证能否载入
+    python tools/build_content_lexicon.py dict/垃圾广告类.txt --category ads -o ads.txt
+
+    # 挂上去用
+    # FOXCLAW_CONTENT_LEXICON=content_lexicon.txt
+
+挂上去之前先跑几天 audit
+────────────────────────
+六万条量级的词表里必然有大量双字词,直接挂 enforce 会明显影响正常对话。建议先
+置 FOXCLAW_CONTENT_GUARD_MODE=audit 观察一段时间的命中记录,确认误伤可接受再转
+enforce —— 这层是兜底,不是让产品变得不好用。
+"""
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import importlib.util
+import sys
+from collections import Counter, OrderedDict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def _load_guard_module():
+    """按文件路径载入 core/content_guard.py —— 它只依赖标准库,不必触发包的 __init__。"""
+    path = ROOT / "foxclaw" / "core" / "content_guard.py"
+    spec = importlib.util.spec_from_file_location("_foxclaw_content_guard", path)
+    if spec is None or spec.loader is None:
+        raise SystemExit(f"找不到 {path}")
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["_foxclaw_content_guard"] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _read_text(path: Path, encoding: str) -> str:
+    data = path.read_bytes()
+    for enc in ([encoding] if encoding != "auto" else ["utf-8-sig", "gb18030"]):
+        try:
+            return data.decode(enc)
+        except UnicodeDecodeError:
+            continue
+    raise SystemExit(f"{path}: 无法解码,用 --encoding 指定(试过 utf-8-sig, gb18030)")
+
+
+def _category_of(path: Path, fallback: str) -> str:
+    stem = path.stem.strip()
+    if any("\u4e00" <= ch <= "\u9fff" for ch in stem):
+        return _clean_category(stem)
+    return _clean_category(fallback)
+
+
+def _clean_category(name: str) -> str:
+    # TAB 是词与类别的分隔符,不能出现在类别里;顺手压掉换行等控制字符。
+    s = " ".join(str(name or "").split())
+    return s.replace("\t", "/") or "platform"
+
+
+def _match_any(cat: str, patterns: list[str]) -> bool:
+    return any(fnmatch.fnmatchcase(cat, p) for p in patterns)
+
+
+def _collect(paths: list[Path], args) -> tuple[OrderedDict, Counter]:
+    """返回 (词 -> [类别...], 统计)。词已 compact,类别按出现顺序去重。"""
+    words: OrderedDict[str, list[str]] = OrderedDict()
+    stats = Counter()
+    for p in paths:
+        text = _read_text(p, args.encoding)
+        default_cat = _category_of(p, args.category)
+        for line in text.splitlines():
+            s = line.strip()
+            if not s or s.startswith("#"):
+                continue
+            stats["lines"] += 1
+            word, _, cat = s.partition("\t")
+            cat = _clean_category(cat) if cat.strip() else default_cat
+            if args.include and not _match_any(cat, args.include):
+                stats["skipped_by_include"] += 1
+                continue
+            if args.exclude and _match_any(cat, args.exclude):
+                stats["skipped_by_exclude"] += 1
+                continue
+            word = args.compact(word)
+            if len(word) < args.min_len:
+                stats["skipped_too_short"] += 1
+                continue
+            if args.max_len and len(word) > args.max_len:
+                stats["skipped_too_long"] += 1
+                continue
+            cats = words.setdefault(word, [])
+            if cat not in cats:
+                if cats:
+                    stats["merged"] += 1
+                cats.append(cat)
+            else:
+                stats["duplicated"] += 1
+    return words, stats
+
+
+def _write_lexicon(path: Path, words: OrderedDict, sources: list[Path], stats: Counter) -> None:
+    counts = Counter(c for cats in words.values() for c in cats)
+    header = [
+        "# Foxclaw 内容词表 —— 由 tools/build_content_lexicon.py 生成,勿手改",
+        "# 源: " + ", ".join(p.name for p in sources),
+        "# 条数: %d" % len(words),
+        "# 类别: " + ", ".join(f"{c} {n}" for c, n in counts.most_common()),
+        "",
+    ]
+    lines = sorted((f"{w}\t{'/'.join(cats)}" for w, cats in words.items()), key=str.casefold)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(header + lines) + "\n", encoding="utf-8", newline="\n")
+
+
+def _verify(path: Path, guard_mod, sample: int) -> bool:
+    guard = guard_mod.ContentGuard(mode="enforce", lexicon_paths=[str(path)])
+    if not guard.lexicon_size:
+        return False
+    probe = [ln.split("\t")[0] for ln in path.read_text(encoding="utf-8").splitlines()
+             if ln and not ln.startswith("#")][:max(1, sample)]
+    hits = sum(1 for w in probe if guard.scan(w))
+    print(f"验证: ContentGuard 载入 {guard.lexicon_size} 条, 抽样 {hits}/{len(probe)} 命中")
+    return hits == len(probe)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="把外部敏感词库转成 FOXCLAW_CONTENT_LEXICON 可用的词表格式",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="类别筛选支持通配符,例如 --exclude '政治*'。",
+    )
+    ap.add_argument("inputs", nargs="+", type=Path, help="词库文件,可多个")
+    ap.add_argument("-o", "--output", type=Path, default=Path("content_lexicon.txt"),
+                    help="输出词表路径(默认 content_lexicon.txt)")
+    ap.add_argument("--category", default="platform",
+                    help="文件名不带中文时使用的类别名(默认 platform)")
+    ap.add_argument("--include", action="append", default=[],
+                    help="只导出匹配的类别,逗号分隔,可重复,支持通配")
+    ap.add_argument("--exclude", action="append", default=[],
+                    help="排除匹配的类别,逗号分隔,可重复,支持通配")
+    ap.add_argument("--encoding", default="auto", help="auto / utf-8 / gb18030 等,默认 auto")
+    ap.add_argument("--min-len", type=int, default=2,
+                    help="短于该长度的词丢弃(默认 2,与加载器一致)")
+    ap.add_argument("--max-len", type=int, default=0,
+                    help="长于该长度的词丢弃(默认 0 = 不限)")
+    ap.add_argument("--sample", type=int, default=5, help="转换后抽样验证条数(默认 5)")
+    ap.add_argument("--no-verify", action="store_true", help="跳过载入验证")
+    args = ap.parse_args(argv)
+
+    def _split(values: list[str]) -> list[str]:
+        out: list[str] = []
+        for v in values:
+            out.extend(x.strip() for x in v.split(",") if x.strip())
+        return out
+
+    args.include = _split(args.include)
+    args.exclude = _split(args.exclude)
+
+    missing = [str(p) for p in args.inputs if not p.is_file()]
+    if missing:
+        raise SystemExit("找不到词库文件: " + ", ".join(missing))
+
+    guard_mod = _load_guard_module()
+    args.compact = guard_mod.compact
+
+    words, stats = _collect(args.inputs, args)
+    if not words:
+        raise SystemExit("没有可导出的词 —— 检查类别筛选或 --min-len")
+
+    _write_lexicon(args.output, words, args.inputs, stats)
+
+    counts = Counter(c for cats in words.values() for c in cats)
+    print(f"读取 {len(args.inputs)} 个文件, {stats['lines']} 行")
+    print("过滤: 类别排除 %d / 不在 include %d / 过短 %d / 过长 %d / 重复 %d / 跨类别归并 %d"
+          % (stats["skipped_by_exclude"], stats["skipped_by_include"],
+             stats["skipped_too_short"], stats["skipped_too_long"],
+             stats["duplicated"], stats["merged"]))
+    print(f"输出 {len(words)} 条 → {args.output}")
+    print("类别: " + ", ".join(f"{c} {n}" for c, n in counts.most_common()))
+
+    if not args.no_verify and not _verify(args.output, guard_mod, args.sample):
+        print("警告: 载入验证未通过,词表可能不可用", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/python/tools/bundle_web.py

@@ -0,0 +1,98 @@
+"""把仓库根的 frontend/ 复制进包内 foxclaw/web/,让 wheel/sdist 带上 Web UI。
+
+为什么要复制
+------------
+`frontend/` 在仓库根、不属于任何 Python 包,`packages.find` 只收
+`foxclaw*` / `hmr*` / `hkc_*`,所以它一直进不了 wheel:`pip install` 之后
+`foxclaw serve` 首页 404,只有 API/CLI。这里在构建前把同一份产物搬进
+`foxclaw/web/`,再由 pyproject 的 `[tool.setuptools.package-data]` 带进 wheel。
+产物已 gitignore,不入版本库(源头仍是 `frontend/`)。
+
+用法
+----
+  python tools/bundle_web.py          # 复制(幂等:先清空 foxclaw/web)
+  python tools/bundle_web.py --check  # 只校验是否缺失/过期,不复制
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / "frontend"
+DST = ROOT / "foxclaw" / "web"
+
+# 与 npm/build.cjs 的跳过规则对齐:依赖、缓存、日志不进包
+SKIP_DIRS = {"node_modules", ".vite", "__pycache__", ".git"}
+SKIP_SUFFIX = {".log", ".err", ".map"}
+
+INIT = '''"""Web UI 静态资源 —— 构建期由 tools/bundle_web.py 从仓库根 frontend/ 复制。
+
+不要手改本目录:改动落在 frontend/(或改 frontend_src/ 后重新构建),再跑
+`python tools/bundle_web.py`。本目录已 gitignore,不在版本库里。
+"""
+'''
+
+
+def iter_files(root: Path):
+    """按相对路径列出要复制的文件(已排除依赖/缓存/日志)。"""
+    for p in sorted(root.rglob("*")):
+        if not p.is_file():
+            continue
+        rel = p.relative_to(root)
+        if any(part in SKIP_DIRS for part in rel.parts):
+            continue
+        if p.suffix in SKIP_SUFFIX:
+            continue
+        yield rel
+
+
+def bundle() -> int:
+    if not SRC.is_dir():
+        print(f"[bundle_web] 找不到源目录 {SRC}", file=sys.stderr)
+        return 1
+    if DST.exists():
+        shutil.rmtree(DST)
+    DST.mkdir(parents=True)
+    (DST / "__init__.py").write_text(INIT, encoding="utf-8")
+    count = 0
+    total = 0
+    for rel in iter_files(SRC):
+        target = DST / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(SRC / rel, target)
+        count += 1
+        total += target.stat().st_size
+    print(f"[bundle_web] {count} files / {total / 1024:.0f} KB -> foxclaw/web/")
+    if not (DST / "v3" / "index.html").is_file():
+        print("[bundle_web] 提示:没有 v3/index.html,首页会退回旧 deck_v2",
+              file=sys.stderr)
+    return 0
+
+
+def check() -> int:
+    if not DST.is_dir():
+        print("[bundle_web] foxclaw/web/ 不存在,构建前先跑 python tools/bundle_web.py",
+              file=sys.stderr)
+        return 1
+    missing = [str(r) for r in iter_files(SRC) if not (DST / r).is_file()]
+    if missing:
+        print(f"[bundle_web] foxclaw/web/ 已过期({len(missing)} 个文件缺失,"
+              f"如 {missing[0]}),先跑 python tools/bundle_web.py", file=sys.stderr)
+        return 1
+    print("[bundle_web] foxclaw/web/ 与 frontend/ 一致")
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="把 frontend/ 复制进包内 foxclaw/web/")
+    ap.add_argument("--check", action="store_true", help="只校验,不复制")
+    args = ap.parse_args(argv)
+    return check() if args.check else bundle()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())