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

.github/workflows/ci.yml

@@ -33,13 +33,10 @@ jobs:
       # 而不是等合并后 Pages 发布挂掉。
       - name: Build site
         run: python3 scripts/build_site.py
-      - name: Assert output
-        run: |
-          test -f site/index.html
-          test -f site/search.json
-          pages=$(find site -name '*.html' | wc -l)
-          echo "生成 HTML 页面数: $pages"
-          test "$pages" -gt 160
+      # 站点自检：站内引用、canonical/sitemap 一致性、检索链路完整性。
+      # 这一步专门用来接住「构建成功但页面/搜索坏掉」这类静默故障。
+      - name: Check site output
+        run: python3 scripts/check_site.py
 
   links:
     name: 外链可达性检查

.github/workflows/pages.yml

@@ -8,6 +8,7 @@ on:
     paths:
       - 'docs/**'
       - 'scripts/build_site.py'
+      - 'scripts/check_site.py'
       - '.github/workflows/pages.yml'
   workflow_dispatch:
 
@@ -31,6 +32,9 @@ jobs:
           python-version: '3.12'
       - name: Build static site
         run: python3 scripts/build_site.py
+      # 发布前先自检：宁可不上线，也不要让「搜索坏了 / 导航 404」的产物出去
+      - name: Check site output
+        run: python3 scripts/check_site.py
       - uses: actions/configure-pages@v5
       - uses: actions/upload-pages-artifact@v3
         with:

README.md

@@ -20,6 +20,19 @@
 > 站点由 `scripts/build_site.py` 从 `docs/` 渲染生成（零依赖、纯静态），
 > 合并进 `main` 后自动发布。`docs/` 的 Markdown 始终是唯一真相源。
 
+## 检索是怎么做的
+
+首屏不加载任何索引。第一次在搜索框里输入时，才去拉
+`search-index.json`（文档元数据 + 分片清单）和 8 个倒排分片。
+
+- 索引是**倒排**的：词 -> 文档 id 列表，按词哈希分成 8 片
+- 中文用 2~4 字滑窗切词，拉丁词整体保留；只出现一次的 n-gram 不入索引
+- 合计约 845 KB（gzip 后约 300 KB），比早期「把每篇正文前 6000 字塞进单个 JSON」
+  的方案（gzip 后约 600 KB、且每次按键都要全量子串扫描）更小也更快
+
+改动检索链路时请同时跑 `scripts/check_site.py`——它会校验索引声明的每个分片
+都存在、索引里的每个 url 都能落到真实页面。
+
 ## 目录
 
 ### 一、人工智能（AI）（46 篇）