[ice-wocker]

让知识库除了「能看」之外，变得「能被检索、能被程序消费、能被自动守住质量」。

为什么要做

现有站点只有「浏览」一种能力：搜索是把 163 篇正文前 6000 字塞进一个 1.6 MB 的 JSON 做全量子串扫描；没有标签、没有相关推荐、没有 RSS；产出物只有 HTML，脚本/AI 想用只能先爬。

这轮补齐的就是缺口。

检索：从「全量串扫」到「倒排索引 + BM25」

• 新增 scripts/kb.py 作为公共引擎（解析 / 分词 / 倒排索引 / 相似度 / 标签）。抽出来是因为 build_site.py、check_docs.py 都要用同一套定义，散在多处必然漂。
• 搜索改为预生成倒排索引 + BM25（k1=1.5, b=0.75），标题命中额外加权。
• 中文用「单字 + 相邻二字（bigram）」：没有分词器时，这是召回与索引体积之间最稳的折中。
• 裁掉只出现 1 篇的词（中文 bigram 的主要噪声）与超高频词：索引 3.8 MB → 1.4 MB（gzip 0.5 MB），实测检索质量零变化。
• 首屏不再拉索引（0 请求），第一次聚焦/输入才加载；单次按键只查候选集。

同一组查询在 Python 与浏览器端结果完全一致（已在 Node 里复跑验证）。

新增能力

能力	说明
相关文档	tf-idf 余弦相似度，每篇推荐 4 篇（同领域优先，不足补全库）
标签体系	自动抽取术语，新增 tags.html / tags.json
阅读体验	本页目录（TOC）、标题锚点（去重）、阅读时长、分类面包屑
机器可读导出	docs.json / graph.json / tags.json / feed.xml / sitemap.xml / robots.txt
浅色模式	prefers-color-scheme 适配

docs.json 让脚本、分析工具、AI 应用无需爬 HTML 就能消费整个库。

质量守门：新增两道 CI 检查

这是本次最重要的部分——内容维度不可靠是这个库最大的风险，163 篇（还会继续加）靠人维护必然漂移。

• check_docs.py —— 管「里面写的东西还成立吗」：必备内容槽位（概述/进展/技术/趋势/来源）、参考来源数量（≥5）、日期格式、标题重复/过长、正文过短、未来日期。按语义槽位 + 命名变体判断，不逼所有人用同一个标题（库里本来就有「核心脉络与关键里程碑」这类更贴切的写法）。
• check_site.py —— 管「构建成功但站点坏掉」：站内链接是否有效、检索索引 docId 是否越界、docs.json 指向的页面是否存在、sitemap/canonical/RSS 是否同源。构建成功 ≠ 站点可用。
• pages.yml 发布前先跑站点自检：宁可不上线，也不让坏产物出去。

check_docs.py 首次运行就发现了 9 篇的章节偏差，逐条核对后确认是命名变体而非缺陷，因此把校验改成语义槽位匹配，而不是硬性要求统一标题。

本地验证

python3 scripts/gen_index.py --check   ✅
python3 scripts/check_docs.py          ✅ 163 篇 / 9 领域 / 3973 条来源
python3 scripts/build_site.py          ✅ 174 页
python3 scripts/check_site.py          ✅
python3 scripts/check_links.py --limit 40  ✅ 死链 0

兼容性

• 未改任何 docs/ 内容，Markdown 仍是唯一真相源。
• 旧的 search.json 被 search-index.json 取代；旧页面模板已同步更新，不存在半新半旧。