# 本地搜索改进

> OINK 1.4.0 的中英混合查询、技术标识符、小节结果与命令面板范围限定。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

> [!NOTE] OINK 1.4.0 已接受
> 负责人：OINK 维护者。受影响契约：[Shell](/zh/docs/design/shell/#search-actions-and-runtime)。
> 本文描述的搜索行为随 OINK 1.4.0 发布。

## 证据与范围 {#scope}

此前 CJK 路径要求整条查询连续出现在同一字段中。英文使用 Lunr，两者都只返回页面链接，
没有小节上下文。保留每语言一个本地索引、现有命令、输入法组字、排除规则、关键词权重和
正数页面加权。不引入词典、服务、账号、外部可执行程序、配置键或额外构建步骤。

## 已接受的行为 {#behavior}

按空白及拉丁文字与 CJK 边界拆分查询，保留 `shared_buffers`、`pg_basebackup`、
`--baseURL` 和 `/pg/data` 等技术标识符。关键词可以分布在不同索引字段中。优先返回
包含全部关键词的页面，其中连续短语优先；仅当没有页面覆盖全部词时，显示明确标注
覆盖数量的部分匹配。在这些层级内部应用页面加权。通过已内置的 Lunr 保留英文词干
匹配和有界的拼写回退。

每页只显示一条结果，选取最相关小节及摘要。直接读取渲染后的标题 ID，不重新推导 slug。
保留语言和部署子路径。正文只存储一次，小节边界使用 UTF-8 字节偏移。
heading 和 summary 范围保留标题锚点，不隐式收录全文。

在现有面板中增加带标签的原生单选组，可选择全站或当前顶层内容栏目。
默认全站，命令与页面操作继续可用。播报结果数量和部分匹配覆盖率，保留键盘选中、
焦点约束及输入法组字期间延迟查询的行为。

## 兼容性与检查 {#checks}

现有页面元数据与范围配置继续有效。小节是新增索引元数据；引擎仍接受没有小节的旧索引。
主题归属检查包括 `check-search.py`、搜索引擎与运行时测试以及面板检查。
站点归属检查包括双语真实内容查询预期、根路径及子路径锚点验证、浏览器键盘、组字、
栏目限定、响应式、深浅色和 axe 检查。
在相同真实语料上比较改造前后的结果与延迟，记录页面和小节数量、工具版本、预热和重复次数、
原始及 gzip 字节数。每语言保持在 2 MiB 原始、512 KiB gzip 预算内。
合成案例覆盖易混淆标识符，以及重复、Unicode、显式和含特殊字符的标题 ID。

## 决策与验收 {#decisions}

2026-10-25：记录最小设计后完成本地实现。行为现由 Shell 契约、搜索与命令面板指南负责。
主题检查覆盖四种索引范围、真实 UTF-8 小节偏移、多语言及子路径 ID、旧索引兼容、加权和
按根栏目缓存的对话框。站点维护 `tests/search/queries.json` 和
`scripts/check-search-corpus.mjs`，根路径与子路径集成构建均执行 summary 查询门禁。

固定文档源码 `ab2747a` 每语言包含 149 页、1,321 个标题。43 条查询包含两条摘要范围的
负向案例。预期页面进入前五的数量分别为：英文摘要 7/7 → 7/7、中文摘要 2/7 → 7/7、
英文全文 10/10 → 10/10、中文全文 6/17 → 17/17。这是人工选定的回归预期，不是通用相关性评分。真实语料没有同时包含 `连接池 超时` 的页面，该项特意检查有标记的
部分匹配；主题合成案例检查完整匹配。

固定摘要索引的原始体积为 185,183/184,281 字节，gzip 为 39,529/43,208 字节
（英文/中文），均在预算内。全文诊断索引原始体积为 1,640,294/1,516,283 字节，
gzip 为 536,971/578,674 字节，超过 gzip 预算。维护中的站点保留 summary 范围；
包含全部历史研究正文的配置不能通过预算要求，实现也不会静默截断这些内容。

浏览器验收覆盖中英文、390/1440 px、深浅色、真实锚点跳转、可见且可播报的部分匹配、
原生范围选择、博客与书籍根栏目、组字和命令保留。本地验收制品目录为
`/Users/vonng/tmp/oink-search-20261025/`，保存准确命令、JSON 计时、日志与截图。
这些带日期的测量仅针对当时语料；已接受的行为随 1.4.0 发布。

2026-10-26：修复索引读取时的跨输出上下文污染，增加多输出归属检查，
完成此前失败路由的无障碍与文件树复验。

2026-10-26：根据视觉反馈优化面板。两个范围选项改为紧凑的分段样式，保留原生单选组的
键盘行为与 44 px 点击区域；收紧桌面面板和列表间距，减淡选中背景，将实时状态与
键盘提示合并为统一底栏。

2026-10-26：对抗性审查修正了规范化匹配后的摘要与高亮偏移，区分标题 ID、数据属性与
脚本字符串，并将英文拼写回退限制在当前栏目。回归覆盖兼容字符、组合字符、短代码标题
以及结果文本中的 HTML 字面内容。

---

反链：

- [决策](/zh/docs/design/decisions/)