scripts/build_vector_index.py
Rama main · réplica de lectura del repositorio original.
#!/usr/bin/env python3
"""
Build vector index for x-knowledge-base semantic search.
Reads search_index.json, embeds each card's title + summary,
and saves vectors to vector_index.json in BOOKMARKS_DIR.
Usage:
python3 scripts/build_vector_index.py
python3 scripts/build_vector_index.py --incremental # skip already-embedded cards
python3 scripts/build_vector_index.py --dry-run # show what would be done
Requires:
EMBEDDING_PROVIDER=gemini|openai|ollama
+ corresponding API key (see .env.example)
"""
from __future__ import annotations
import argparse
import hashlib
import json
import math
import os
import re
import sys
from datetime import datetime, timezone
from pathlib import Path
# Allow running from scripts/ directory or skill root
sys.path.insert(0, str(Path(__file__).resolve().parent))
import xkb_paths
import xkb_console
# 這支腳本的輸出有 emoji，而它會被人在 Windows 主控台直接叫起來。
# 不轉的話，工作做完了卻死在回報那一行的 print。
xkb_console.use_utf8()
_SKILL_DIR = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(_SKILL_DIR))
from tools.embedding_providers import get_provider
WORKSPACE_DIR = xkb_paths.WORKSPACE
BOOKMARKS_DIR = xkb_paths.BOOKMARKS_DIR
INDEX_FILE = xkb_paths.INDEX_FILE
VECTOR_FILE = xkb_paths.VECTOR_FILE
# wiki/memory 的向量另外存一份小檔。召回時只需要這 ~1,900 個向量，
# 但它們混在 8,000 多個卡片向量裡，載入整個 62MB 檔案要 5.4 秒——
# 而召回是每句話都要跑的。分開存之後只需要載入十分之一。
SEMANTIC_FILE = BOOKMARKS_DIR / "semantic_index.json"
# 卡片向量另存一份。它不像 wiki/記憶檔那樣要整份掃過——
# 卡片是先由 gbrain 挑出候選，我們只需要驗證那幾張的相關度，
# 所以讀取端用 seek 取單筆，不必把整份載進來。
CARDS_FILE = BOOKMARKS_DIR / "cards_index.json"
# ── Text extraction ───────────────────────────────────────────────────────────
def _resolve_md_path(item: dict) -> Path | None:
"""索引項路徑解析：relative_path 是相對 workspace（如 memory/cards/x.md），
舊程式誤用 BOOKMARKS_DIR 拼接導致永遠讀不到卡片（2026-07-14 修正）。"""
abs_path = item.get("path") or ""
if abs_path and Path(abs_path).exists():
return Path(abs_path)
rel = item.get("relative_path") or ""
if not rel:
return None
for base in (WORKSPACE_DIR, BOOKMARKS_DIR):
p = base / rel
if p.exists():
return p
return None
def _extract_key_points_from_md(md_path: Path) -> str:
"""Extract the 關鍵論點/三個重點 section from a card markdown file.
（2026-07-14：新版 9-section 卡片段落名為「關鍵論點」，一併支援舊名）"""
if not md_path.exists():
return ""
try:
content = md_path.read_text(encoding="utf-8")
m = re.search(
r'##\s+[^\n]*(?:關鍵論點|三個重點)[^\n]*\n(.+?)(?=\n##|\Z)',
content, re.DOTALL
)
if m:
text = re.sub(r'^[\-\*\•]\s*', '', m.group(1).strip(), flags=re.MULTILINE)
return text.strip()
except Exception:
pass
return ""
def _extract_key_point_list(md_path: Path) -> list[str]:
"""論點級 embedding（TODOS 2026-07-13）：回傳「三個重點」逐條列表，
每條將單獨成向量（鍵 relpath#kpN），召回粒度從卡片級升到論點級。"""
text = _extract_key_points_from_md(md_path)
if not text:
return []
points = [ln.strip() for ln in text.splitlines() if len(ln.strip()) >= 10]
return points[:5]
def extract_card_text(item: dict) -> str:
"""Build embeddable text from a search index item.
Uses title + summary (already extracted by build_search_index.sh).
Falls back to reading the .md file if summary is empty.
"""
title = (item.get("title") or "").strip()
summary = (item.get("summary") or "").strip()
key_points = ""
md_path = _resolve_md_path(item)
if md_path:
if not summary:
summary = _extract_summary_from_md(md_path)
key_points = _extract_key_points_from_md(md_path)
parts = [p for p in [title, summary, key_points] if p]
return ". ".join(parts)[:900] # cap at 900 chars (expanded for key points)
def _extract_summary_from_md(md_path: Path) -> str:
if not md_path.exists():
return ""
try:
content = md_path.read_text(encoding="utf-8", errors="ignore")
except OSError:
return ""
# New format: ## 📝 一句話摘要 / Old format: ## 摘要
for pattern in [
r"##\s+[^\n]*一句[話话]摘要\s*\n(.+?)(?=\n##|\Z)",
r"##\s+摘要\s*\n(.+?)(?=\n##|\Z)",
]:
m = re.search(pattern, content, re.DOTALL)
if m:
text = m.group(1).strip().replace("\n", " ")
text = re.sub(r"\s+", " ", text)
return text[:300]
return ""
# ── Cosine similarity (pure Python, no numpy) ─────────────────────────────────
def cosine_similarity(a: list, b: list) -> float:
dot = sum(x * y for x, y in zip(a, b))
norm_a = math.sqrt(sum(x * x for x in a))
norm_b = math.sqrt(sum(y * y for y in b))
denom = norm_a * norm_b
return dot / denom if denom > 1e-9 else 0.0
# ── Load / save ───────────────────────────────────────────────────────────────
def load_vector_index(path: Path) -> dict:
if path.exists():
try:
return json.loads(path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError):
pass
return {"meta": {}, "vectors": {}}
def save_vector_index(data: dict, path: Path) -> None:
path.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
# ── Wiki sections ─────────────────────────────────────────────────────────────
# 一段太短的內容嵌入後幾乎沒有訊息量，只會製造假命中
MIN_SECTION_CHARS = 80
# 一段太長會把主題稀釋掉，超過就截斷
MAX_SECTION_CHARS = 4000
def _chunks(header: str, body: str) -> list[tuple[str, str]]:
"""Split one section into as many vectors as it needs.
A section longer than MAX_SECTION_CHARS used to be truncated, so the tail
was written to the wiki and then silently dropped from the index — 56
sections were losing their endings that way. Anything past the cap now
becomes its own vector instead.
The first chunk is byte-for-byte what truncation produced, so every vector
already in the index keeps its hash and nothing is re-embedded to catch up;
only the previously discarded remainder is new.
"""
room = MAX_SECTION_CHARS - len(header)
if room <= 0 or len(body) <= room:
return [("", f"{header}{body}"[:MAX_SECTION_CHARS])]
out = [("", f"{header}{body}"[:MAX_SECTION_CHARS])]
start = room
index = 2
while start < len(body):
end = min(start + room, len(body))
if end < len(body):
# Prefer a line break near the end of the window so a chunk does
# not begin mid-sentence. Deterministic, so hashes stay stable.
split = body.rfind("\n", start + int(room * 0.8), end)
if split > start:
end = split
out.append((f"@{index}", header + body[start:end].strip()))
start = end
index += 1
return out
def knowledge_section_docs() -> list[tuple[str, str, str]]:
"""把 wiki 主題頁與記憶檔切段，每段一個向量。回傳 [(key, text, hash)]。
為什麼要做這件事：向量索引原本只涵蓋卡片。wiki——也就是使用者自己消化過、
訊號密度最高的那一層——完全沒有語意搜尋，只能靠字串比對撈。
中文沒有空格，字串比對本來就弱，於是「我們之前怎麼處理碳盤查的」會撈回
一堆只命中「之前」「怎麼」「處理」的無關結果。那不是門檻調不好，
是那一層根本沒有語意能力。
切到「段」而不是整頁：一頁 680K 的主題頁嵌成單一向量，等於什麼都不像。
"""
sources: list[tuple[Path, str]] = []
if xkb_paths.WIKI_TOPICS_DIR.exists():
sources += [(p, "wiki/topics") for p in sorted(xkb_paths.WIKI_TOPICS_DIR.glob("*.md"))]
# 記憶檔也要語意化：hard trigger（「我們之前怎麼…」）查的就是這一層，
# 而它原本同樣只有字串比對，靠功能詞就能命中。
if xkb_paths.DATA_DIR.exists():
sources += [(p, "memory") for p in sorted(xkb_paths.DATA_DIR.glob("*.md"))]
if xkb_paths.MEMORY_MD.exists():
sources.append((xkb_paths.MEMORY_MD, "memory"))
docs: list[tuple[str, str, str]] = []
for path, prefix in sources:
try:
content = path.read_text(encoding="utf-8")
except OSError:
continue
content = re.sub(r"^---\n.*?\n---\n", "", content, flags=re.DOTALL)
title = path.stem
section = ""
buffer: list[str] = []
# A heading can repeat inside one file — memory/2026-05-09.md has
# "教訓" fifteen times. Every copy produced the same key, so each
# run kept a vector for the last of them and re-embedded the rest:
# about a hundred sections that could never go incremental, paying
# for an embedding every day. Later occurrences get a suffix; the
# first keeps the original key so existing vectors stay valid.
seen_keys: dict[str, int] = {}
def flush(section_name: str, lines: list[str]) -> None:
body = "\n".join(lines).strip()
if len(body) < MIN_SECTION_CHARS:
return
key = f"{prefix}/{path.name}#{section_name or 'intro'}"
occurrence = seen_keys.get(key, 0) + 1
seen_keys[key] = occurrence
if occurrence > 1:
key = f"{key}~{occurrence}"
for suffix, text in _chunks(f"{title} — {section_name}\n", body):
docs.append((key + suffix, text,
hashlib.md5(text.encode("utf-8")).hexdigest()[:12]))
for line in content.splitlines():
if re.match(r"^#{1,3} .+", line):
flush(section, buffer)
section = re.sub(r"^#{1,3} ", "", line).strip()
buffer = []
else:
buffer.append(line)
flush(section, buffer)
return docs
def write_semantic_index(vectors: dict[str, list[float]], path: Path) -> None:
"""寫出 <path>.bin（float32 單位向量）與 <path>（keys + dims 的 JSON）。"""
import array
keys = sorted(vectors)
dims = len(vectors[keys[0]])
packed = array.array("f")
for key in keys:
vec = vectors[key]
norm = math.sqrt(sum(x * x for x in vec)) or 1.0
packed.extend(x / norm for x in vec)
payload = packed.tobytes()
path.with_suffix(".bin").write_bytes(payload)
# 記下位元組序、每個浮點數幾個位元組、總筆數：
# 這三項任何一項對不上，切片出來的向量就是錯的，而且不會拋錯——
# 只會安靜地變成空向量或錯位資料，讀取端據此驗證後才敢用。
path.write_text(json.dumps({
"dims": dims,
"keys": keys,
"count": len(keys),
"normalized": True,
"byteorder": sys.byteorder,
"itemsize": packed.itemsize,
"bytes": len(payload),
}, ensure_ascii=False), encoding="utf-8")
# ── Main ──────────────────────────────────────────────────────────────────────
def main() -> int:
parser = argparse.ArgumentParser(description="Build vector index for x-knowledge-base")
parser.add_argument("--incremental", action="store_true",
help="Skip cards already in vector_index.json")
parser.add_argument("--dry-run", action="store_true",
help="Show what would be done without calling embedding API")
parser.add_argument("--batch-size", type=int, default=50)
parser.add_argument("--index-file", default=str(INDEX_FILE))
parser.add_argument("--vector-file", default=str(VECTOR_FILE))
parser.add_argument("--env-file", help="dotenv file for credentials/config (process environment wins)")
args = parser.parse_args()
index_path = Path(args.index_file)
vector_path = Path(args.vector_file)
# Load search index
if not index_path.exists():
print(f"❌ search_index.json not found: {index_path}", file=sys.stderr)
return 1
raw = json.loads(index_path.read_text(encoding="utf-8"))
# BM25 全文索引：跟向量索引同源，但**不依賴 embedding**。放在所有提早
# return（dry-run / 沒東西要嵌入 / 憑證失敗）之前——不然索引缺了、又剛好
# 沒有卡片變動，排程就永遠不重建它，BM25 腿靜默熄燈。
# 一支腳本裡建一次，就不必在 6 支排程腳本裡各加一行、各自漂移。
if not args.dry_run:
fts_db = xkb_paths.BOOKMARKS_DIR / "fts_index.db"
try:
# 嚴格大於：同一秒重生的 index（1 秒 mtime 解析度）要能觸發重建。
fresh = (fts_db.exists()
and fts_db.stat().st_mtime > index_path.stat().st_mtime)
except OSError:
fresh = False
# build_fts_index 沒有 incremental：整包重讀、重斷詞、重建 FTS5、optimize、
# 原子換檔。卡片沒動就不必每個 tick 都做一遍。mtime 比不到獨立改動的
# wiki／memory 檔——那些靠每日全量管線補。
if not fresh:
try:
import build_fts_index
build_fts_index.build(index_path)
if not fts_db.exists():
raise RuntimeError("build_fts_index 跑完但 fts_index.db 不存在")
except Exception as e: # noqa: BLE001
# cron 把 stderr 丟掉，光印警告等於靜默。走 xkb_failures，健檢
# （純 Python、不經 LLM）才看得到 BM25 索引連續建不起來。
print(f"⚠️ BM25 索引沒建成（向量索引不受影響）：{e}", file=sys.stderr)
try:
import xkb_failures
xkb_failures.note("bm25 index build", e)
except Exception: # noqa: BLE001
pass
items = raw.get("items", raw) if isinstance(raw, dict) else raw
print(f"📚 Loaded {len(items)} cards from {index_path}")
# Load existing vectors (for incremental mode)
existing = load_vector_index(vector_path)
existing_vectors: dict = existing.get("vectors", {})
# Determine which cards to embed
existing_hashes: dict = existing.get("text_hashes", {})
to_embed = []
# 這一次「看過」的每一個鍵，不管有沒有排進佇列。清理要靠它，不能靠
# queued_keys：增量模式只是跳過『排進佇列』，來源一樣每個都走過。
# 把兩者混為一談，就會把沒變動的段落當成消失了而刪掉。
enumerated_keys: set[str] = set()
# wiki 段落：把消化過的那一層也納入語意搜尋
for wiki_key, wiki_text, wiki_hash in knowledge_section_docs():
enumerated_keys.add(wiki_key)
if not (args.incremental and wiki_key in existing_vectors
and existing_hashes.get(wiki_key) == wiki_hash):
to_embed.append((wiki_key, wiki_text, wiki_hash))
print(f"📖 Wiki/memory sections queued: {len(to_embed)}")
for item in items:
key = item.get("relative_path") or item.get("path") or ""
card_text = extract_card_text(item)
if not card_text.strip():
print(f" ⚠️ No text for: {key}")
continue
text_hash = hashlib.md5(card_text.encode("utf-8")).hexdigest()[:12]
md_path = _resolve_md_path(item)
if md_path is not None:
enumerated_keys.add(key)
# md_path 是 None 時只是不把這份文件算成「走過」——它列不出論點鍵，
# 算成走過的話既有的 #kpN 會全被當成消失而刪掉，下次路徑正常了再
# 全部重新付費嵌入。但**要不要重新嵌入**還是交給下面的 hash 判斷：
# 上一版在這裡 continue，於是卡片內文改了、markdown 暫時找不到，
# 它就永遠停在舊向量上。
if not (args.incremental and key in existing_vectors and existing_hashes.get(key) == text_hash):
to_embed.append((key, card_text, text_hash))
# 論點級 embedding（TODOS 2026-07-13）：每條「關鍵論點」單獨成向量
if md_path:
title = (item.get("title") or "").strip()
for pi, point in enumerate(_extract_key_point_list(md_path), 1):
pkey = f"{key}#kp{pi}"
enumerated_keys.add(pkey)
ptext = (f"{title}. {point}" if title else point)[:500]
phash = hashlib.md5(ptext.encode("utf-8")).hexdigest()[:12]
if args.incremental and pkey in existing_vectors and existing_hashes.get(pkey) == phash:
continue
to_embed.append((pkey, ptext, phash))
# Alias for downstream use
texts = [t for _, t, _ in to_embed]
# 集合建一次就好。原本寫在生成式的條件裡，於是每一個既有鍵都重建一次
# 一萬多個元素的集合——完整重跑時是一萬多次。
queued_keys = {entry[0] for entry in to_embed}
# 死鍵：這次走過的文件底下，索引裡有、但內容已經不存在的鍵。
# 跟列舉放在一起算，因為它就是列舉的產物；放到下面去算，會落在
# 「沒東西要嵌入就提早結束」的後面，而那正是平常的狀態。
examined_docs = {key.split("#", 1)[0] for key in enumerated_keys}
stale_keys = [key for key in existing_vectors
if key.split("#", 1)[0] in examined_docs
and key not in enumerated_keys]
skipped = sum(1 for k in existing_vectors if k not in queued_keys)
print(f"🔢 To embed: {len(to_embed)} | Skipped (incremental): {skipped}")
if args.dry_run:
print("\n[dry-run] First 3 cards that would be embedded:")
for key, text, _text_hash in to_embed[:3]:
print(f" {key}")
print(f" → \"{text[:80]}...\"")
return 0
# 分區檔不完整就不能提早結束：一旦 semantic_index.bin 或 cards_index.bin
# 被刪掉或寫到一半，之後每一次增量執行都會「沒有新東西」然後離開，
# 而召回永遠停在慢的 JSON 路徑上——安靜地、永久地。
#
# write_semantic_index 會寫兩個檔（.json 的鍵表與 .bin 的向量），兩個都要在。
def _partition_ok(path: Path) -> bool:
return path.exists() and path.with_suffix(".bin").exists()
# 要問寫入端「你會寫到哪」，不是問常數。下面寫檔時是看
# XKB_SEMANTIC_INDEX / XKB_CARDS_INDEX 的，測試與備援路徑都會設它們；
# 檢查常數等於在別的地方確認「檔案還在」，然後對真正在用的那份一無所知。
_semantic_target = Path(os.getenv("XKB_SEMANTIC_INDEX", str(SEMANTIC_FILE)))
_cards_target = Path(os.getenv("XKB_CARDS_INDEX", str(CARDS_FILE)))
_partitions_ok = _partition_ok(_semantic_target) and _partition_ok(_cards_target)
if stale_keys:
print(f"🧹 {len(stale_keys)} 個索引鍵已經沒有對應內容，這一輪清掉")
if not to_embed and _partitions_ok and not stale_keys:
print("✅ Nothing to embed.")
return 0
if not to_embed:
# 為什麼還要往下走，要說對。只有死鍵要清的時候說「分區索引檔不完整」
# 是假的，而假的理由會讓下一個人去修一個不存在的問題。
print("沒有新內容要嵌入，但分區索引檔不完整——從既有向量重新寫出。"
if not _partitions_ok else
"沒有新內容要嵌入，只清掉死鍵之後重新寫出。")
# 沒有東西要嵌入就不要去要嵌入服務。純粹「清死鍵」的那一輪也會走到
# 這裡，於是憑證不在時整支以 1 收場、而且一個死鍵都沒清掉——
# 前一天它還只是安靜地印 Nothing to embed。
provider = None
if to_embed:
try:
provider = get_provider(env_file=args.env_file)
print(f"🤖 Provider: {provider.__class__.__name__} / model: {getattr(provider, 'model', '?')}")
except (EnvironmentError, ValueError) as e:
print(f"❌ {e}", file=sys.stderr)
return 1
# Embed in batches
keys = [k for k, _, _ in to_embed]
hashes = [h for _, _, h in to_embed]
vectors_list = []
batch_size = args.batch_size
total = len(texts)
for i in range(0, total, batch_size):
batch_texts = texts[i:i + batch_size]
batch_keys = keys[i:i + batch_size]
print(f" Embedding {i+1}–{min(i+batch_size, total)}/{total}...", end=" ", flush=True)
try:
batch_vecs = provider.embed_batch(batch_texts, batch_size=batch_size)
vectors_list.extend(zip(batch_keys, batch_vecs))
print("✓")
except Exception as e:
print(f"\n❌ Failed at batch {i//batch_size + 1}: {e}", file=sys.stderr)
return 1
# Merge with existing vectors and hashes
new_vectors = dict(existing_vectors)
new_hashes = dict(existing_hashes)
for (key, vec), h in zip(vectors_list, hashes):
new_vectors[key] = vec
new_hashes[key] = h
# 索引原本只增不減。標題改名、記憶檔刪掉、卡片的關鍵論點從五條變三條——
# 舊向量就永遠留著，照樣參與排序，然後顯示空白。實測 2,262 個 wiki 鍵
# 裡有 80 個指向已經不存在的段落。
#
# 但「這次沒產生」不等於「不存在了」：增量執行本來就只看有變動的東西。
# 安全的規則是：只清掉「這次有檢查過來源、而這次沒有產生」的鍵。沒被
# 看過的來源，它的鍵一個都不動。
# 清理沒有對應內容的索引鍵。這一段我寫錯過三次，每次都是同一個混淆的
# 不同面向：
#
# 一 用 queued_keys 推出「檢查過的來源」。增量模式下，文件只要有一塊
# 變了就算檢查過，於是它其他沒變的塊全被刪——改過的卡片會在論點鍵
# 與卡片鍵之間永遠振盪，每晚重新付費嵌入。
# 二 改成只在完整重建時清理。但每一條排程都帶 --incremental，於是清理
# 從此不會執行。我把破壞性 bug 修成了一個關掉的功能。
# 三 規則終於對了，卻放在「沒東西要嵌入就提早結束」的後面——而那正是
# 平常的狀態。連跑三次，一次都沒清到。
#
# 真正的分辨是：**列舉 ≠ 排進佇列**。兩種模式都會走過每一個來源，
# --incremental 只是跳過「把沒變的排進佇列」。所以要問「這次走到了哪些
# 鍵」，而那個問題兩種模式的答案一樣好——這條規則因此不需要看模式，
# 那正是它對的跡象。stale_keys 在上面列舉處算好，這裡只執行。
#
# 限定在「這次走過的文件」之內，順帶關掉另一個風險：卡片鍵只來自
# --index-file，拿一份不完整的索引跑完整重建，沒走過的文件一根寒毛都不會動。
#
# 已知殘留：整頁被刪除時它一個段落都不會被列舉，於是它的鍵留著。
# 這是安全的方向——寧可留著也不要誤刪。
for key in stale_keys:
new_vectors.pop(key, None)
new_hashes.pop(key, None)
# Save
output = {
"meta": {
"provider": (provider.__class__.__name__.replace("Provider", "").lower()
if provider is not None
else existing.get("meta", {}).get("provider", "")),
"model": (getattr(provider, "model", "") if provider is not None
else existing.get("meta", {}).get("model", "")),
"dims": len(vectors_list[0][1]) if vectors_list else existing.get("meta", {}).get("dims", 0),
"total": len(new_vectors),
"point_vectors": sum(1 for k in new_vectors if "#kp" in k),
"built_at": datetime.now(timezone.utc).isoformat(),
},
"vectors": new_vectors,
"text_hashes": new_hashes,
}
save_vector_index(output, vector_path)
# 另存召回用的索引，二進位格式。
# 存 JSON 的話 1,868 個 3072 維向量要 76MB，光 json.loads 就要 5 秒——
# 而召回是每句話都要跑的。float32 打包後只有 23MB，載入約 0.1 秒。
# 順便先做單位化，查詢時只要點積，不必每次算平方根。
semantic_vectors = {
k: v for k, v in output.get("vectors", {}).items()
if (k.startswith("wiki/topics/") or k.startswith("memory/"))
and not k.startswith("memory/cards/")
}
if semantic_vectors:
semantic_path = Path(os.getenv("XKB_SEMANTIC_INDEX", str(SEMANTIC_FILE)))
write_semantic_index(semantic_vectors, semantic_path)
print(f"✅ Saved {len(semantic_vectors)} semantic vectors → {semantic_path.with_suffix('.bin')}")
card_vectors = {k: v for k, v in output.get("vectors", {}).items()
if k not in semantic_vectors}
if card_vectors:
cards_path = Path(os.getenv("XKB_CARDS_INDEX", str(CARDS_FILE)))
write_semantic_index(card_vectors, cards_path)
print(f"✅ Saved {len(card_vectors)} card vectors → {cards_path.with_suffix('.bin')}")
print(f"\n✅ Saved {len(new_vectors)} vectors → {vector_path}")
print(f" Provider : {output['meta']['provider']} / {output['meta']['model']}")
print(f" Dims : {output['meta']['dims']}")
return 0
import xkb_usage # noqa: E402 — 量測誰在跑，見 scripts/xkb_usage.py
if __name__ == "__main__":
xkb_usage.record(__file__)
raise SystemExit(main())