简介：面向 Lojban 语言学习者与开发者的工具组合包，围绕解析器、词典检索界面与相关软件生态组织，适合希望在同一环境中体验词法解析、词典查询和 IRC 机器人服务的进阶用户。压缩包共 2000 个文件，约 44.38MB，其中 MP3 音频与 OGG 语音素材占较大比例，另含 C、JavaScript、Perl 等源码，JSON/HTML/SVG 等配置与页面资源，以及词典数据、构建脚本和 Docker 相关文件，便于按模块查阅与二次开发。已有 169 人学习下载。读者可获得一套可容器化部署的 Lojban 工具链：借助 Docker 或 podman 启动服务，配置 IRC 机器人及 websocket 端口，结合解析器、检索界面和词典数据理解 Lojban 的语法分析与查询流程；音频与多语言资源也为发音学习、词典扩充和界面本地化提供素材。整体目录覆盖源码、数据、文档与运行配置，适合作为学习 Lojban 工具实现和搭建实验环境的参考包。

1. 从散落脚本到可检索入口：livla 组合包到底解决什么

手里有一份 Lojban 语料时，最麻烦的往往不是不认识词，而是词形、词义和句法分析结果散在几个脚本里：parser 输出一份结构，词典软件另存一份释义，搜索界面又只认自己的字段。livla 这类 Lojban 工具组合的价值，是把 parser、search-interface、dictionary-software 和 HTML 外壳串成一条可本地跑通的链路，让一句 Lojban 从输入、解析、查词到页面展示不再靠手工搬运。它适合做构造语言资料整理、词典维护、语料抽查的人，也适合想拆解语言工具前后端边界的人。下面按“先看结构、再跑解析、再做索引、最后避坑”的顺序拆。

2. 拆 livla 的四个部件：parser、词典、搜索接口与 HTML 外壳怎么咬合

先别急着改代码。组合包最容易翻车的地方，是四个部件各自能跑，但字段对不上：parser 输出的是树，词典软件要的是词条，搜索界面要的是扁平 JSON，HTML 只认接口返回。拆包时我一般先把“入口”和“契约”分开看：入口决定怎么启动，契约决定后面所有改动会不会把前端带崩。livla 的标题已经把范围说得很清楚，parser 负责句法，dictionary-software 负责词条，search-interface 负责查询，HTML 负责展示。四者之间最好只通过一层中间 JSON 通信，别让前端直接依赖 parser 的原始结构。

2.1 资源目录与运行时边界

拿到组合包后，先做目录盘点，不要一上来就装依赖。常见做法是把目录按职责粗分：解析器入口、词典数据、搜索服务、静态页面、示例输入。目录名可能和下面不同，但职责边界应该能对上。先用一条只读命令看顶层结构，再决定工作目录放在哪里；不要在资源原始目录里直接生成索引和缓存，后面清理很麻烦。

# 在组合包根目录执行，只读盘点，不修改文件 for d in parser dictionary search web data examples; do if [ -d "$d" ]; then echo "[dir] $d" find "$d" -maxdepth 2 -type f | sort | head -n 20 fi done

逻辑说明：这段脚本按常见职责名探测目录，并只列两层内的文件，避免把依赖目录全部刷屏。参数说明：maxdepth 2控制深度，head -n 20控制输出量；如果资源目录名不同，把parser dictionary search web换成实际目录名即可。盘点完要确认三件事：parser 有没有可执行入口，词典数据是不是纯文本或 JSON，HTML 入口是不是静态文件。三件事确认后再建自己的工作目录，例如work/放缓存、work/index.json放倒排索引，原始目录保持只读。

提示：先固定中间层 JSON 契约，再改 parser 入口；否则前端和词典会被入口参数牵着走。

2.2 parser 的输出契约

parser 的输出不能直接丢给前端。原始语法树通常带很多内部节点、位置信息和未消费 token，前端渲染时既重又难查。我一般定义一个最小中间层：原句、规范化词序列、解析状态、错误信息、词条候选。下面是一份契约示例，字段名可以按资源实际输出调整，但层级不要轻易变。

{ "input": "mi klama le zarci", "tokens": ["mi", "klama", "le", "zarci"], "status": "ok", "tree": {"type": "sentence", "children": []}, "lookups": [ {"word": "klama", "type": "brivla", "gloss": ""}, {"word": "zarci", "type": "brivla", "gloss": ""} ], "errors": [] }

逻辑说明：input保留原句，tokens给搜索界面做词形高亮，status只允许ok、partial、error三种，tree放解析器原始树或裁剪后的树，lookups是给词典软件的查询入口，errors统一收集错误。参数说明：如果 parser 输出字段叫words或lexemes，在包装层映射到tokens；如果错误是字符串数组，包成{code, message, offset}再放入errors。这一步做完，后面换 parser 入口、换词典格式，前端都不用重写。

2.3 词典与搜索索引的咬合

dictionary-software 的核心不是“有一个词条列表”，而是“词条能被稳定归一化和查询”。Lojban 词条里常见词形、类型、释义、备注、变体、词根组合信息；如果直接把原始字段塞进搜索接口，用户搜klama和搜klam会得到完全不同的结果。常见做法是先把词条归一化成统一记录：key用小写词形，display保留原始写法，type用有限枚举，gloss存释义，aliases存变体和词根片段。索引只存key到词条 ID 的映射，查询时再回表取完整记录。这样词典软件可以独立维护词条，搜索界面只认索引，不会因为词典字段增删而崩。

# normalize_entries.py import json TYPE_MAP = { "gismu": "root", "cmavo": "particle", "brivla": "predicate", "cmene": "name", } def normalize(entry): word = (entry.get("word") or entry.get("headword") or "").strip() key = word.lower().replace("'", "h") aliases = [a.lower().replace("'", "h") for a in entry.get("aliases", [])] return { "id": entry.get("id") or key, "key": key, "display": word, "type": TYPE_MAP.get(entry.get("type", ""), entry.get("type", "unknown")), "gloss": entry.get("gloss", ""), "aliases": sorted(set(aliases)), "notes": entry.get("notes", ""), } if __name__ == "__main__": with open("dictionary/entries.json", encoding="utf-8") as f: raw = json.load(f) out = [normalize(e) for e in raw if e.get("word") or e.get("headword")] with open("work/entries.normalized.json", "w", encoding="utf-8") as f: json.dump(out, f, ensure_ascii=False, indent=2)

逻辑说明：读取原始词条，统一词形大小写和撇号写法，把类型映射成有限枚举，保留display给页面展示，aliases去重排序。参数说明：TYPE_MAP按资源实际类型扩展；replace("'", "h")是常见 Lojban 撇号归一化做法，如果资源采用其他转写规则，改成同一个函数即可。归一化后不要直接覆盖原始词典，输出到work/，保留回滚余地。

2.4 HTML 外壳与 API 边界

HTML 外壳最容易变成“什么都往里塞”的页面。我的做法是让 HTML 只做三件事：接收输入、调用搜索接口、渲染结果；解析和查词都在服务端完成。前端只认两个接口：/api/parse?q=返回中间层 JSON，/api/search?q=返回词条数组。这样静态 HTML 可以单独部署，搜索接口也能单独替换。下面这段 HTML 只保留最小结构，重点是接口边界，不是页面样式。

<!doctype html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <title>Lojban 检索</title> </head> <body> <form id="search-form"> <input id="q" name="q" placeholder="输入 Lojban 词或句子" autocomplete="off"> <button type="submit">查询</button> </form> <pre id="output"></pre> <script> const form = document.querySelector("#search-form"); const out = document.querySelector("#output"); form.addEventListener("submit", async (e) => { e.preventDefault(); const q = document.querySelector("#q").value.trim(); if (!q) return; const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`); const data = await res.json(); out.textContent = JSON.stringify(data, null, 2); }); </script> </body> </html>

逻辑说明：表单提交后只发一个fetch，把查询词编码进 URL，返回 JSON 直接展示。参数说明：encodeURIComponent必须保留，Lojban 词里可能有撇号或空格；接口地址/api/search要和后端路由一致。生产化时可以加防抖和错误提示，但边界不要变：HTML 不解析语法树，只渲染接口结果。

3. 把 parser 跑成最小闭环：一句 Lojban 从输入到 JSON 的四个检查点

parser 这一层要跑通，不是“命令不报错”就算完。至少要看到四个检查点：入口能启动、输入能进、输出能解析成 JSON、错误能定位到位置。很多组合包在这里翻车，是因为解析器输出的是调试文本，包装脚本却按 JSON 解析；或者解析器返回 0，但树里是空的。我的顺序是先用最小输入跑一次，再用一句带结构词的 Lojban 验证，最后才批量。下面按检查点写，不追求覆盖全部语法，只追求链路可复现。

3.1 环境与入口定位

先确认运行时和解析器入口。不要凭目录名猜，直接看可执行文件和示例调用。下面命令只做检查，不安装依赖。如果 parser 是脚本，确认解释器版本；如果是编译产物，确认权限和动态库；如果资源里同时有多个入口，先用示例输入最少的那个。

# 检查运行时和入口权限 python3 --version node --version 2>/dev/null || true find parser -maxdepth 2 -type f \( -name "*.py" -o -name "*.js" -o -perm -111 \) -print

逻辑说明：先看 Python 和 Node 是否存在，再找脚本和可执行文件。参数说明：2>/dev/null || true让缺少 Node 时不中断；-perm -111找可执行权限。找到入口后不要直接改源码，先写一个包装脚本，把入口参数和输出格式固定下来。包装层是后面批量、缓存和错误定位的支点，没有它，parser 一换参数就得全链路重调。

3.2 最小解析调用

下面用 Python 包装一个命令行 parser。资源里的入口名、参数名可能不同，所以脚本把命令集中在PARSER_CMD，只改这一处。输出统一成第 2 章定义的中间层，解析失败也返回 JSON，不把异常直接抛给前端。

# parse_wrap.py import json import subprocess import sys PARSER_CMD = ["python3", "parser/main.py", "--format", "json"] def parse_text(text): proc = subprocess.run( PARSER_CMD + ["--input", text], capture_output=True, text=True, timeout=10, ) if proc.returncode != 0: return { "input": text, "tokens": text.split(), "status": "error", "tree": None, "lookups": [], "errors": [{"code": "PARSER_EXIT", "message": proc.stderr.strip()[:500], "offset": None}], } try: raw = json.loads(proc.stdout) except json.JSONDecodeError: return { "input": text, "tokens": text.split(), "status": "error", "tree": None, "lookups": [], "errors": [{"code": "BAD_JSON", "message": proc.stdout[:500], "offset": None}], } return { "input": text, "tokens": raw.get("tokens", text.split()), "status": "ok" if raw.get("tree") else "partial", "tree": raw.get("tree"), "lookups": raw.get("lookups", []), "errors": raw.get("errors", []), } if __name__ == "__main__": print(json.dumps(parse_text(sys.argv[1]), ensure_ascii=False, indent=2))

逻辑说明：subprocess.run调入口，超时 10 秒，返回码非 0 时包装成PARSER_EXIT，JSON 解析失败时包装成BAD_JSON，正常时统一字段。参数说明：PARSER_CMD按实际入口改；--input和--format是示例参数，资源不支持就从标准输入传文本；timeout对批量任务要调大，交互查询保持短超时。先跑mi klama le zarci这类短句，确认tokens和tree都有内容，再跑空输入和乱码输入，看错误分支是否稳定。

3.3 解析结果校验与错误定位

parser 返回ok不代表结果可信。常见问题是树里只有根节点、token 数量和输入不一致、错误数组为空但状态是partial。我一般加一个校验函数，把“结构完整性”和“错误定位”分开看：结构完整性检查 token 是否被消费，错误定位检查 offset 是否落在原句范围内。校验失败不一定要阻断页面，但必须让搜索界面看到partial或error。

# validate_result.py def validate(result): problems = [] text = result.get("input", "") tokens = result.get("tokens", []) tree = result.get("tree") if not text.strip(): problems.append("EMPTY_INPUT") if tree is None: problems.append("NO_TREE") if len(tokens) == 0 and text.strip(): problems.append("NO_TOKENS") for err in result.get("errors", []): off = err.get("offset") if off is not None and (off < 0 or off > len(text)): problems.append("BAD_OFFSET") return problems

逻辑说明：空输入、空树、空 token、越界 offset 都算结构问题；返回问题码数组，不直接改状态。参数说明：offset如果资源用 token 序号而不是字符位置，把上界改成len(tokens)；BAD_OFFSET只记录一次也行，这里按错误条数累计。校验函数放在包装层之后，批量跑时把问题码计数，能快速看出是入口问题还是某类句子问题。

3.4 批量解析的吞吐与缓存

批量解析不要每次都重新启动进程。短句多的时候，进程启动成本会盖过解析本身。常见做法是用一个简单缓存：以原句的哈希为键，把中间层 JSON 存到本地文件；命中缓存直接返回，未命中再调 parser。缓存不解决语法错误，但能避免重复翻车。下面用标准库实现，不引入额外依赖。

# batch_parse.py import hashlib import json import os from parse_wrap import parse_text CACHE_DIR = "work/cache" os.makedirs(CACHE_DIR, exist_ok=True) def cached_parse(text): key = hashlib.sha256(text.encode("utf-8")).hexdigest()[:16] path = os.path.join(CACHE_DIR, key + ".json") if os.path.exists(path): with open(path, encoding="utf-8") as f: return json.load(f) result = parse_text(text) with open(path, "w", encoding="utf-8") as f: json.dump(result, f, ensure_ascii=False) return result if __name__ == "__main__": lines = [line.strip() for line in open("examples/sentences.txt", encoding="utf-8") if line.strip()] for line in lines[:50]: r = cached_parse(line) print(r["status"], line[:40])

逻辑说明：用原句哈希做文件名，命中直接读 JSON，未命中调包装函数再写缓存。参数说明：[:16]截短哈希，冲突概率对本地语料够低；lines[:50]先小批量验证，确认缓存目录增长正常再放开。缓存文件要放在work/，不要写回examples/；如果解析器升级，清空缓存或加版本前缀，否则旧结果会混进新链路。

4. 词典软件落地：JSON 倒排索引、查询 API 与 HTML 搜索页

词典软件这一层，小规模词条不需要一上来就上重型数据库。JSON 倒排索引的好处是透明、可 diff、方便随组合包一起走；词条规模变大后再换嵌入式存储，接口保持不变。关键是把“归一化词条”“倒排索引”“查询排序”“HTML 展示”拆开。下面用纯 Python 标准库写一条可跑通的链路：先建索引，再起一个本地 HTTP 服务，最后用 HTML 页面调接口。代码不追求生产级并发，但字段和错误处理按真实链路写。

4.1 词条归一化与索引字段

索引只存能加速查询的最小信息：key到词条 ID 的映射、别名到 ID 的映射、类型到 ID 的映射。完整释义留在entries.normalized.json，查询命中后回表取。这样词典维护者改释义不会影响索引结构，搜索界面也不会拿到半截字段。下面建一个倒排索引文件，包含by_key、by_alias、by_type和entries四个部分。

# build_index.py import json from collections import defaultdict with open("work/entries.normalized.json", encoding="utf-8") as f: entries = json.load(f) by_key = {} by_alias = defaultdict(list) by_type = defaultdict(list) entry_map = {} for e in entries: eid = e["id"] entry_map[eid] = e by_key[e["key"]] = eid by_type[e["type"]].append(eid) for alias in e.get("aliases", []): by_alias[alias].append(eid) index = { "by_key": by_key, "by_alias": dict(by_alias), "by_type": dict(by_type), "entries": entry_map, } with open("work/search-index.json", "w", encoding="utf-8") as f: json.dump(index, f, ensure_ascii=False, indent=2)

逻辑说明：by_key精确匹配主词形，by_alias支持变体和词根片段，by_type支持按类型过滤，entries存完整记录供回表。参数说明：如果同一key出现多次，后写入会覆盖，建索引前要加重复检查；aliases为空时不会写入by_alias，查询侧要容忍缺失。索引文件建议随词典版本重新生成，不要手工编辑，否则回表和索引会不一致。

4.2 查询接口与结果排序

查询接口要处理三种输入：精确词形、前缀、包含匹配。精确命中排最前，别名命中其次，前缀再次，类型过滤最后应用。下面用http.server起一个本地接口，返回统一结构{query, total, items, errors}。这段代码可以直接跑，端口冲突时改PORT。

# search_api.py import json from http.server import BaseHTTPRequestHandler, HTTPServer from urllib.parse import urlparse, parse_qs with open("work/search-index.json", encoding="utf-8") as f: INDEX = json.load(f) def search(q, type_filter=None): q = q.strip().lower() if not q: return {"query": q, "total": 0, "items": [], "errors": ["EMPTY_QUERY"]} hits = [] if q in INDEX["by_key"]: hits.append((100, INDEX["by_key"][q])) for eid in INDEX["by_alias"].get(q, []): hits.append((80, eid)) for key, eid in INDEX["by_key"].items(): if key != q and key.startswith(q): hits.append((60, eid)) seen = set() items = [] for score, eid in sorted(hits, key=lambda x: -x[0]): if eid in seen: continue seen.add(eid) entry = INDEX["entries"][eid] if type_filter and entry.get("type") != type_filter: continue items.append({"score": score, **entry}) return {"query": q, "total": len(items), "items": items[:20], "errors": []} class Handler(BaseHTTPRequestHandler): def do_GET(self): parsed = urlparse(self.path) if parsed.path != "/api/search": self.send_response(404) self.end_headers() return params = parse_qs(parsed.query) q = params.get("q", [""])[0] type_filter = params.get("type", [None])[0] body = json.dumps(search(q, type_filter), ensure_ascii=False).encode("utf-8") self.send_response(200) self.send_header("Content-Type", "application/json; charset=utf-8") self.send_header("Content-Length", str(len(body))) self.end_headers() self.wfile.write(body) if __name__ == "__main__": HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()

逻辑说明：精确命中 100 分，别名 80 分，前缀 60 分，去重后按分数排序，类型过滤在回表后执行，最多返回 20 条。参数说明：type参数可选，值要和归一化时的枚举一致；items[:20]控制返回量，前端需要分页时再加offset。这个接口只读索引文件，改词典后要重启服务或加热加载；本地调试先看/api/search?q=klama是否返回total和items。

4.3 HTML 搜索页与查询参数

HTML 页面不要只做一个输入框。至少要有查询参数同步、加载状态、空结果提示和错误提示。下面在上一个最小页面上加防抖和 URL 参数，用户刷新后还能保留查询词。前端仍然只认items和errors，不碰索引细节。

<!doctype html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <title>Lojban 词典检索</title> </head> <body> <input id="q" placeholder="词形、别名或前缀"> <select id="type"> <option value="">全部类型</option> <option value="root">root</option> <option value="predicate">predicate</option> <option value="particle">particle</option> </select> <p id="status"></p> <ul id="list"></ul> <script> const q = document.querySelector("#q"); const type = document.querySelector("#type"); const status = document.querySelector("#status"); const list = document.querySelector("#list"); let timer = null; async function run() { const text = q.value.trim(); const t = type.value; if (!text) { list.innerHTML = ""; status.textContent = ""; return; } status.textContent = "查询中"; const url = `/api/search?q=${encodeURIComponent(text)}${t ? `&type=${encodeURIComponent(t)}` : ""}`; const res = await fetch(url); const data = await res.json(); status.textContent = data.errors.length ? data.errors.join(", ") : `共 ${data.total} 条`; list.innerHTML = data.items.map(item => `<li><strong>${item.display}</strong> <em>${item.type}</em> ${item.gloss || ""}</li>` ).join(""); } q.addEventListener("input", () => { clearTimeout(timer); timer = setTimeout(run, 250); }); type.addEventListener("change", run); </script> </body> </html>

逻辑说明：输入防抖 250 毫秒，查询词和类型编码进 URL，返回后渲染display、type、gloss。参数说明：encodeURIComponent处理空格和特殊字符；type为空时不拼参数；status同时承担加载和错误提示。这个页面可以放在web/index.html，由同一个静态服务托管，接口路径保持/api/search，避免跨域。

4.4 静态托管与接口同源

HTML 和接口不同源时，浏览器会拦请求。本地调试最简单的做法是让同一个 HTTP 服务同时返回静态文件和/api/search。如果资源里已经有静态服务，就在它的路由表里加一个 API 分支；如果没有，就在搜索服务里加一个静态文件分支。不要用file://直接打开 HTML 调接口，那个坑很常见。下面给一个静态文件分支的示意，路径做白名单，避免目录穿越。

# 在 Handler.do_GET 中增加静态分支 import os from urllib.parse import unquote STATIC_ROOT = os.path.abspath("web") def serve_static(handler, path): rel = unquote(path).lstrip("/") or "index.html" full = os.path.abspath(os.path.join(STATIC_ROOT, rel)) if not full.startswith(STATIC_ROOT + os.sep) or not os.path.isfile(full): handler.send_response(404) handler.end_headers() return body = open(full, "rb").read() handler.send_response(200) handler.send_header("Content-Type", "text/html; charset=utf-8") handler.send_header("Content-Length", str(len(body))) handler.end_headers() handler.wfile.write(body)

逻辑说明：把请求路径映射到web/下，先做绝对路径归一化，再检查是否仍在静态根目录内，最后确认文件存在。参数说明：STATIC_ROOT按实际静态目录改；lstrip("/")去掉前导斜杠；startswith(STATIC_ROOT + os.sep)防止../穿越。静态分支和 API 分支共用端口，前端fetch("/api/search")就是同源请求，不需要额外配置。

5. 避坑与排查：Lojban 工具组合最常见的五类翻车

组合包的坑通常不在算法，而在边界：parser 入口参数变了，缓存还是旧格式；词典归一化改了，索引没重建；HTML 页面能打开，接口却跨域；批量任务跑到一半，单个坏输入把整批打断。下面五条是我在拆这类语言工具组合时最常遇到的翻车记录，每条按“现象 → 原因 → 解决”写，方便对照排查。

5.1 解析入口类：命令能跑但结果为空

现象：包装脚本返回status: ok，但tree是null，tokens有值，前端展示空白。原因通常是 parser 把结果输出到标准错误，标准输出只有日志；或者入口参数--format json没被识别，解析器退化成调试文本。先用原命令跑一次，分别看重定向后的 stdout 和 stderr，不要只看终端混合输出。解决是把入口命令集中到PARSER_CMD，跑PARSER_CMD + ["--input", "mi klama le zarci"]，把 stdout 存文件，确认第一字符是{；如果入口不支持--format，就在包装层把调试文本转成中间层，或者改用标准输入。包装层要保留PARSER_EXIT和BAD_JSON两个错误码，别把异常吞成空树。

5.2 解析入口类：超时设置过短

现象：短句正常，稍长句子随机返回PARSER_EXIT，错误信息是空字符串。原因是subprocess.run的timeout太短，进程被终止时还没来得及写 stderr。交互查询可以短超时，批量任务必须按语料长度调大，并且把超时单独记成TIMEOUT，不要和解析失败混在一起。解决是在包装函数里捕获TimeoutExpired，返回可识别的错误码；批量跑之前先用 50 条样本测一次 P95 耗时，把超时设为 P95 的 3 到 5 倍。超时错误要计入统计，否则你会以为 parser 不稳定。

5.3 词典索引类：归一化改了但索引没重建

现象：搜索klama有结果，搜索带撇号的变体没有结果；或者新加的词条在页面查不到。原因是归一化脚本已经改了规则，work/search-index.json还是旧文件，查询接口读的是旧索引。解决是把“归一化 → 建索引 → 启服务”串成一条命令，每次改词典都按顺序跑；索引文件加一个version字段，查询接口启动时打印版本，页面状态栏也带上版本号。调试时先看entries.normalized.json里目标词条的key和aliases，再看索引里的by_key和by_alias，最后才怀疑查询排序。不要手工改索引，手工改的索引和回表记录很容易对不上。

5.4 前端部署类：file://打开页面调接口失败

现象：双击 HTML 文件，页面能显示，输入查询后控制台报跨域或fetch失败。原因是file://协议下没有同源服务，接口请求被浏览器拦。解决是用本地 HTTP 服务托管静态页面，让页面和/api/search同源；如果静态页面和接口必须分开，就在接口侧加允许的本地来源，并且只允许本地调试地址。不要把允许来源写成通配符后长期使用。调试顺序是：先访问http://127.0.0.1:8000/api/search?q=klama看接口是否返回 JSON，再打开http://127.0.0.1:8000/看页面，最后才看前端报错。

5.5 批量任务类：一个坏输入打断整批

现象：批量解析跑到第 37 条突然退出，前面的缓存写了一半，后面的句子没跑。原因是循环里没有捕获单条异常，或者写缓存时直接覆盖原文件导致中断后文件损坏。解决是单条解析包在try/except里，失败也写一条带错误码的缓存；缓存写入先写临时文件再原子替换，避免半截 JSON。批量入口要记录已处理 ID，支持从断点继续。更稳的做法是把“解析结果”和“错误统计”分开输出，错误统计按BAD_JSON、TIMEOUT、NO_TREE计数，跑完先看计数，再看具体句子。

6. 进阶验证：用回归样本和缓存命中率给组合包上保险

链路跑通后，我会做两个小验证，不追求大而全，但能提前发现“改一处崩一片”。第一个是回归样本：固定十几条短句，覆盖正常句、空输入、乱码、带撇号词形，每次改 parser 或归一化规则都跑一遍，看状态分布有没有突变。第二个是缓存命中率：批量任务里统计命中数和未命中数，如果命中率长期很低，说明输入重复度低或缓存键设计有问题；如果命中率很高但结果仍旧慢，问题在回表或页面渲染，不在 parser。

# regression_check.py import json from collections import Counter from parse_wrap import parse_text CASES = [ "mi klama le zarci", "coi ro do", "", "%%%", "la .alis. cu klama", ] def main(): dist = Counter() for text in CASES: r = parse_text(text) dist[r["status"]] += 1 if r["status"] == "error": print("ERR", text[:20], r["errors"][:1]) print(json.dumps(dict(dist), ensure_ascii=False)) if __name__ == "__main__": main()

逻辑说明：固定样本逐条跑包装层，统计状态分布，错误样本打印第一条错误，避免刷屏。参数说明：CASES按你的语料扩充，但不要放太多长句；parse_text必须和批量任务用的是同一个包装函数，否则验证结果不代表线上链路。回归样本不要只放在笔记里，放进work/或examples/，每次改 parser 入口、归一化规则、索引字段都跑一次。从那以后我每次改组合包的接口字段，都先跑回归样本再重建索引，宁可多花两分钟，也不愿在页面空白时靠猜。希望帮到你。

本文还有配套的精品资源，点击获取