Skip to content

fix(site): 跨领域导航 404(线上真实故障)+ 检索索引改倒排 - #3

Closed
ice-wocker wants to merge 1 commit into
mainfrom
npc/site-polish
Closed

ice-wocker wants to merge 1 commit into
mainfrom
npc/site-polish

Conversation

@ice-wocker

Copy link
Copy Markdown
Owner

站点可用性修补。核心是修一个线上真实 404,再把检索链路整个换掉。

1. 修线上真实故障:跨领域的「上一篇 / 下一篇」全是 404

站点按领域分目录(ai/、hardware/…),但上下篇是按全局顺序取的。
相邻两篇属于不同领域时,生成的 href 只写了文件名,浏览器会在当前目录里找——直接 404。

实测线上(不是推断):

https://ice-wocker.github.io/frontier-knowledge-base/ai/video-generation-and-world-models.html
  「先进封装 →」 → ai/advanced-packaging.html  → HTTP 404

全站共 16 条这样的跨领域导航。scripts/check_site.py 就是被这个 bug 逼出来的。

现在跨领域会生成 ../<领域>/<文件名>.html。

2. 检索:1.6 MB 的无索引大 JSON → 倒排 + 8 个分片

旧实现把每篇正文前 6000 字塞进 search.json:

旧 新
索引体积 1563 KB(gzip 599 KB) 845 KB(gzip ~300 KB)
结构 无倒排,线性扫描 倒排:词 → 文档 id
首屏加载 立即拉 600 KB 零加载,第一次输入才拉
每次按键 163 条 × 6 KB 子串扫描 只查候选集
  • 中文 2~4 字滑窗切词,拉丁词整体保留
  • 只出现一次的 n-gram 不入索引——中文滑窗产生的生僻组合占了旧索引的大头,对检索零贡献,砍掉后体积直接腰斩
  • 按词哈希分 8 片(不能用内置 hash():它每进程加盐,构建与校验会不一致)

3. 元数据与可访问性

  • 补 canonical / og:image / og:url / theme-color / favicon / touch icon / manifest / sitemap / robots / RSS
  • 文档页加 Article 结构化数据 + rel=prev/next
  • 跳转主内容链接、focus 可见轮廓、移动端领域导航可横滚、prefers-reduced-motion、打印样式

4. 新增 scripts/check_site.py,接进 CI 与发布流程

它专接「构建成功但站点坏掉」这类静默故障:

  • 页面引用的站内文件是否真的存在
  • canonical / sitemap / og:url 是否同一个地址
  • 索引声明的分片是否都在、索引指向的页面是否都真实存在
  • head 里的资源是否都有产物

发布流程也加了这一步:宁可不上线,也不让坏产物出去。

验证

python3 scripts/build_site.py     # 173 页
python3 scripts/check_site.py     # 全部通过
python3 scripts/gen_index.py --check   # INDEX.md 最新

站点可用性修补:修掉一个线上真实 404,并把检索链路整个换掉。

1) 跨领域的「上一篇 / 下一篇」全是 404(线上真实故障)
   站点按领域分目录,上下篇却按全局顺序取。相邻两篇属于不同领域时,
   href 只写了文件名,浏览器在当前目录里找不到,直接 404。
   实测 ai/video-generation-and-world-models.html 的「先进封装 →」
   指向 ai/advanced-packaging.html,全站共 16 条。
   现在跨领域会生成 ../<领域>/<文件名>.html。

2) 检索:单个 1.6 MB 无索引大 JSON -> 倒排 + 8 个分片
   旧实现把每篇正文前 6000 字塞进 search.json(1.6 MB / gzip 600 KB),
   且没有倒排,每次按键都要对 163 条 × 6 KB 做子串扫描。
   现在按词建倒排、哈希分 8 片,合计 845 KB(gzip ~300 KB),
   且首屏零加载:第一次输入才拉。
   中文用 2~4 字滑窗切词;只出现一次的 n-gram 不入索引——它们占了旧索引
   的大头却对检索没有贡献。

3) 元数据与可访问性
   补 canonical / og:image / og:url / theme-color / favicon / touch icon /
   manifest / sitemap / robots / RSS;文档页加 Article 结构化数据与
   rel=prev/next;跳转主内容、focus 可见轮廓、移动端导航可横滚、打印样式。

4) 新增 scripts/check_site.py 并接进 CI 与发布流程
   专接「构建成功但站点坏掉」:站内引用是否存在、canonical/sitemap/og
   是否同一地址、索引声明的分片是否都在、索引指向的页面是否真实存在。
   上面那个跨领域 404 就是它发现的。发布前也跑一遍。
@ice-wocker

Copy link
Copy Markdown
Owner Author

已确认被 main 的演进覆盖,故关闭:两边 165 篇文档一字不差;跨领域导航/上一篇下一篇、倒排索引+BM25、每周外链检查,main 上都有(且更新)。这个分支与 main 没有共同祖先,GitHub 无法直接合并;生成器两边走了不同架构,如需其中某段逻辑请 cherry-pick 单文件。

@ice-wocker ice-wocker closed this Oct 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant