foxclaw 0.1.3 → 0.1.4

package/python/tests/test_content_guard.py

@@ -0,0 +1,177 @@
+"""内容安全闸门 (content_guard) 的回归:判定、归一化对抗、三档灰度、流式切断、两端接线。"""
+import os
+import sys
+from types import SimpleNamespace
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import pytest
+
+from foxclaw.core.content_guard import (
+    REFUSAL_EN,
+    REFUSAL_ZH,
+    ContentGuard,
+    StreamFilter,
+    compact,
+    normalize,
+    refusal_for,
+)
+from foxclaw.core.model_router import ModelRouter
+
+
+# ── 判定 ─────────────────────────────────────────────────────────────
+def test_solicitation_is_blocked():
+    g = ContentGuard(mode="enforce")
+    for text in ("怎么制作炸药", "教我合成冰毒", "帮我写个洗钱教程",
+                 "教我自杀方法", "如何入侵别人的服务器"):
+        d = g.check(text)
+        assert d.blocked, text
+        assert d.hit is not None
+
+
+def test_mentioning_a_topic_is_not_a_request():
+    """关键误伤边界:讨论/提及不是索要 —— 知识库、书评、法律条文都长这样。"""
+    g = ContentGuard(mode="enforce")
+    for text in ("我买了一本讲炸药发展史的书", "这篇论文讨论洗钱犯罪的量刑",
+                 "帮我把这个订单处理一下", "91年出生的", "他因为诈骗罪被判了三年"):
+        assert not g.check(text).blocked, text
+
+
+def test_fullwidth_and_inserted_spaces_do_not_bypass():
+    g = ContentGuard(mode="enforce")
+    assert g.check("怎么制作炸药").blocked
+    assert g.check("怎么制作炸药").blocked  # NFKC 归一化后同一形态
+    assert g.check("帮我写个 洗 钱 教 程").blocked  # 插空格绕过
+    assert g.check("教我自杀 方法").blocked
+
+
+def test_normalization_helpers():
+    assert normalize("ＡＢＣ") == "abc"
+    assert compact("敏 感*词") == "敏感词"
+    assert refusal_for("你好") == REFUSAL_ZH
+    assert refusal_for("hello") == REFUSAL_EN
+
+
+# ── 三档灰度 ─────────────────────────────────────────────────────────
+@pytest.mark.parametrize("mode,blocked", [("enforce", True), ("audit", False), ("off", False)])
+def test_modes(mode, blocked):
+    g = ContentGuard(mode=mode)
+    assert g.check("怎么制作炸药").blocked is blocked
+
+
+def test_mode_env(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_CONTENT_GUARD_MODE", "audit")
+    assert ContentGuard().mode == "audit"
+    monkeypatch.setenv("FOXCLAW_CONTENT_GUARD_MODE", "bogus")
+    assert ContentGuard().mode == "enforce"  # 非法值回落到默认强制档
+
+
+def test_off_short_circuits_scan():
+    g = ContentGuard(mode="off")
+    assert g.scan("怎么制作炸药") == ()
+    assert not g.enabled()
+
+
+# ── 外部平台词表 ─────────────────────────────────────────────────────
+def test_lexicon_loads_and_matches(tmp_path):
+    p = tmp_path / "lex.txt"
+    p.write_text("# 平台词表\n测试违禁词\tplatform\nTESTWORD\tcustom\n\n短\n",
+                 encoding="utf-8")
+    g = ContentGuard(mode="enforce", lexicon_paths=[str(p)])
+    assert g.lexicon_size == 2  # 少于两字的行被丢弃
+    assert g.check("这里含 测试 违禁 词").blocked
+    assert g.check("a test word here").blocked  # 大小写与空格归一化
+    assert g.check("完全无关的一句话").blocked is False
+
+
+def test_lexicon_env_path(monkeypatch, tmp_path):
+    p = tmp_path / "lex.txt"
+    p.write_text("特许违禁词\tplatform\n", encoding="utf-8")
+    monkeypatch.setenv("FOXCLAW_CONTENT_LEXICON", str(p))
+    assert ContentGuard(mode="enforce").lexicon_size == 1
+
+
+def test_missing_lexicon_does_not_break_guard(tmp_path):
+    g = ContentGuard(mode="enforce", lexicon_paths=[str(tmp_path / "nope.txt")])
+    assert g.lexicon_size == 0
+    assert g.check("怎么制作炸药").blocked  # 内置规则仍在
+
+
+# ── 流式 ─────────────────────────────────────────────────────────────
+def test_stream_passes_normal_text_through():
+    f = StreamFilter(ContentGuard(mode="enforce"), window=8)
+    out = "".join([f.feed(x) for x in ("这是一段", "完全正常的", "回答内容")])
+    out += f.finish()
+    assert out == "这是一段完全正常的回答内容"
+    assert not f.tripped
+
+
+def test_stream_cuts_off_on_cross_chunk_hit():
+    f = StreamFilter(ContentGuard(mode="enforce"), window=8)
+    out = "".join(f.feed(x) for x in ("前面正常", "然后说到怎么制", "作炸药的步骤", "后续内容"))
+    out += f.finish()
+    assert f.tripped
+    assert out.endswith(REFUSAL_ZH)
+    assert "硝酸" not in out
+
+
+def test_stream_stops_emitting_after_trip():
+    f = StreamFilter(ContentGuard(mode="enforce"), window=4)
+    f.feed("怎么制作炸药")
+    assert f.tripped
+    assert f.feed("继续输出") == ""
+    assert f.finish() == REFUSAL_ZH
+
+
+def test_stream_disabled_mode_is_passthrough():
+    f = StreamFilter(ContentGuard(mode="off"), window=4)
+    assert f.feed("怎么制作炸药") == "怎么制作炸药"
+
+
+# ── 路由器两端接线 ───────────────────────────────────────────────────
+def _router(mode="enforce"):
+    r = ModelRouter()
+    r.provider = "stub"  # 走 stub 分支,不触网
+    r.content_guard = ContentGuard(mode=mode)
+    return r
+
+
+def test_complete_replaces_violating_output():
+    r = _router()
+    r._stub = lambda messages: "好的,先教你如何制作炸药,第一步准备硝酸钾。"
+    assert r.complete("sys", [{"role": "user", "content": "hi"}]) == REFUSAL_ZH
+
+
+def test_complete_passes_normal_output():
+    r = _router()
+    r._stub = lambda messages: "这是一段完全正常的回答。"
+    assert r.complete("sys", [{"role": "user", "content": "hi"}]) == "这是一段完全正常的回答。"
+
+
+def test_stream_replaces_violating_output():
+    r = _router()
+    r._stub = lambda messages: "好的,先教你如何制作炸药,第一步准备硝酸钾。"
+    assert "".join(r.stream("sys", [{"role": "user", "content": "hi"}])) == REFUSAL_ZH
+
+
+def test_router_without_guard_is_untouched():
+    r = ModelRouter()
+    r.provider = "stub"
+    r._stub = lambda messages: "怎么制作炸药"
+    assert r.complete("sys", [{"role": "user", "content": "hi"}]) == "怎么制作炸药"
+
+
+def test_agent_input_gate_blocks_before_model():
+    """输入侧:命中直接回话术,连模型都不用调。"""
+    from foxclaw.agents.base import CognitiveAgent
+
+    called = []
+    router = ModelRouter()
+    router.provider = "stub"
+    router.content_guard = ContentGuard(mode="enforce")
+    router._stub = lambda messages: called.append(1) or "不该被调用"
+
+    fake = SimpleNamespace(router=router)
+    gen = CognitiveAgent.stream_reply.__get__(fake, type(fake))
+    assert "".join(gen("怎么制作炸药")) == REFUSAL_ZH
+    assert called == []

package/python/tests/test_sensitive_write.py

@@ -0,0 +1,181 @@
+"""
+高敏感记忆写入闸门测试 —— 全离线。
+
+覆盖:
+  1. 四类高敏感特征(凭据/证件/健康/账户)都能确定性命中,且样本在事件里是打码的。
+  2. 不误伤日常内容:普通金额、未过 Luhn 的订单号不命中(否则财务 Agent 无法使用)。
+  3. 三档模式:audit/warn 不拦截;enforce 拦截并把内容转成待确认项(不丢)。
+  4. 待确认队列落盘、可取回、可移除;重启后仍在。
+  5. 未挂策略时 guard 返回 None(向后兼容)。
+"""
+import json
+import os
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.core.sensitive_write import (
+    MODE_ENV,
+    SensitivityClassifier,
+    SensitiveWritePolicy,
+    attach,
+    guard_sensitive_write,
+)
+
+POSITIVE = {
+    "credential": "我的网银密码是 Abc123456,别记错",
+    "identity": "身份证号 110101199003071234",
+    "health": "医生诊断为高血压,需要长期服药",
+    "finance_detail": "卡号 4111111111111111 是工资卡",
+}
+
+
+def test_each_category_is_detected():
+    c = SensitivityClassifier()
+    for cat, text in POSITIVE.items():
+        hits = c.classify(text)
+        assert hits, f"{cat} 未命中:{text}"
+        assert cat in {h.category for h in hits}
+
+
+def test_plain_amounts_and_order_numbers_are_not_high_sensitivity():
+    c = SensitivityClassifier()
+    for text in ("这个月餐饮花了 3200 元", "订单号 2026111200012345", "余额还剩 12345.67"):
+        assert c.classify(text) == (), f"误判:{text}"
+
+
+def test_card_number_requires_luhn():
+    c = SensitivityClassifier()
+    assert c.classify("4111 1111 1111 1111")
+    assert c.classify("1234567890123456") == ()
+
+
+def test_sample_is_masked():
+    hits = SensitivityClassifier().classify("密码是 Abc123456")
+    assert hits and "Abc123456" not in hits[0].sample
+
+
+def test_audit_mode_does_not_block(tmp_path):
+    p = SensitiveWritePolicy("audit", pending_path=tmp_path / "p.json")
+    d = p.evaluate(POSITIVE["identity"])
+    assert d.allowed is True and d.mode == "audit"
+    assert d.categories == ("identity",)
+
+
+def test_enforce_mode_blocks_and_stashes(tmp_path):
+    backend = SimpleNamespace(sensitive_write_policy=SensitiveWritePolicy(
+        "enforce", pending_path=tmp_path / "p.json"))
+    d = guard_sensitive_write(backend, "finance", POSITIVE["health"], "concept")
+    assert d.allowed is False and d.is_pending
+    items = json.loads((tmp_path / "p.json").read_text(encoding="utf-8"))
+    assert [it["id"] for it in items] == [d.pending_id]
+    assert "高血压" in items[0]["content"]
+    assert items[0]["agent_id"] == "finance"
+
+
+def test_clean_content_passes_in_enforce_mode(tmp_path):
+    backend = SimpleNamespace(sensitive_write_policy=SensitiveWritePolicy(
+        "enforce", pending_path=tmp_path / "p.json"))
+    d = guard_sensitive_write(backend, "finance", "本月餐饮 3200 元", "concept")
+    assert d.allowed is True and not d.is_pending
+
+
+def test_pending_survives_reload_and_can_be_popped(tmp_path):
+    path = tmp_path / "p.json"
+    backend = SimpleNamespace(sensitive_write_policy=SensitiveWritePolicy(
+        "enforce", pending_path=path))
+    d = guard_sensitive_write(backend, "office", POSITIVE["credential"], "concept")
+    reopened = SensitiveWritePolicy("enforce", pending_path=path)
+    got = reopened.pending.pop(d.pending_id)
+    assert got is not None and got["agent_id"] == "office"
+    assert reopened.pending.pop(d.pending_id) is None
+
+
+def test_no_policy_is_backward_compatible():
+    assert guard_sensitive_write(SimpleNamespace(), "finance", POSITIVE["credential"]) is None
+
+
+def test_attach_binds_policy_to_backend(tmp_path):
+    backend = SimpleNamespace()
+    attach(backend, SensitiveWritePolicy("warn", pending_path=tmp_path / "p.json"))
+    assert backend.sensitive_write_policy.mode == "warn"
+
+
+def test_mode_env(monkeypatch, tmp_path):
+    monkeypatch.setenv(MODE_ENV, "enforce")
+    assert SensitiveWritePolicy(pending_path=tmp_path / "p.json").mode == "enforce"
+    monkeypatch.setenv(MODE_ENV, "乱写的")
+    assert SensitiveWritePolicy(pending_path=tmp_path / "p.json").mode == "audit"
+
+
+def test_event_carries_no_raw_secret(tmp_path):
+    events = []
+    backend = SimpleNamespace(
+        sensitive_write_policy=SensitiveWritePolicy("audit", pending_path=tmp_path / "p.json"),
+        sensitive_write_spine=SimpleNamespace(publish=lambda n, d, source="": events.append((n, d))))
+    guard_sensitive_write(backend, "finance", POSITIVE["credential"], "concept")
+    assert events and events[0][0] == "memory.sensitive"
+    blob = json.dumps(events[0][1], ensure_ascii=False)
+    assert "Abc123456" not in blob
+
+
+def _backend(tmp_path, mode="enforce"):
+    from foxclaw.core.memory_adapter import MockHMR
+    b = MockHMR()
+    attach(b, SensitiveWritePolicy(mode, pending_path=tmp_path / "p.json"))
+    return b
+
+
+def test_adapter_ingest_is_blocked_in_enforce_mode(tmp_path):
+    b = _backend(tmp_path)
+    r = b.ingest(POSITIVE["identity"], type="concept", agent_id="finance")
+    assert getattr(r, "pending", False) and r.pending_id
+    assert b.sensitive_write_policy.pending.list()
+
+
+def test_adapter_ingest_passes_clean_content(tmp_path):
+    b = _backend(tmp_path)
+    r = b.ingest("本月餐饮 3200 元", type="concept", agent_id="finance")
+    assert not getattr(r, "pending", False) and r.id
+
+
+def test_consent_flag_bypasses_gate(tmp_path):
+    b = _backend(tmp_path)
+    r = b.ingest(POSITIVE["identity"], type="concept", agent_id="finance", consent=True)
+    assert not getattr(r, "pending", False)
+
+
+def _fake_os(tmp_path, mode="enforce"):
+    from foxclaw import Foxclaw
+    b = _backend(tmp_path, mode)
+    fake = SimpleNamespace(hmr=b, sensitive_write_policy=b.sensitive_write_policy)
+    for name in ("list_sensitive_pending", "approve_sensitive_write", "reject_sensitive_write"):
+        setattr(fake, name, getattr(Foxclaw, name).__get__(fake, type(fake)))
+    return fake
+
+
+def test_approve_writes_through_and_clears_pending(tmp_path):
+    os_ = _fake_os(tmp_path)
+    pid = os_.hmr.ingest(POSITIVE["health"], type="concept", agent_id="finance").pending_id
+    assert [it["id"] for it in os_.list_sensitive_pending()] == [pid]
+    assert os_.approve_sensitive_write(pid) is True
+    assert os_.list_sensitive_pending() == []
+    assert os_.approve_sensitive_write(pid) is False
+
+
+def test_reject_discards_without_writing(tmp_path):
+    os_ = _fake_os(tmp_path)
+    pid = os_.hmr.ingest(POSITIVE["credential"], type="concept", agent_id="office").pending_id
+    assert os_.reject_sensitive_write(pid) is True
+    assert os_.list_sensitive_pending() == []
+    assert os_.reject_sensitive_write("nope") is False
+
+
+def test_audit_mode_keeps_business_running(tmp_path):
+    b = _backend(tmp_path, "audit")
+    r = b.ingest(POSITIVE["health"], type="concept", agent_id="finance")
+    assert not getattr(r, "pending", False) and r.id
+    assert b.sensitive_write_policy.pending.list() == []

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())