报错是这么冒出来的。产品手册从 v2 换到 v3，中间插入了两页，知识库里的引用还存着页码 42，检索命中后原样返回，前端跳到 PDF 第 42 页，实际内容已经挪到第 44 页。
中间走过弯路，把「页码从 0 还是 1 开始两边不一致」当成主因，改完现象没变。
排查方向其实有限，先把可能性排一排。引用只存了页码，没有存文本锚点。另一种情况是换版后没有重建页码映射。
少数情况下是切片时页码取自目录而不是实际页。
引用里同时存页码与段落锚点
python refs.py --add-anchor接着换版后重建页码映射表
python rebuild_page_map.py --old v2.pdf --new v3.pdf前端先按锚点定位再回退页码
node pdf_goto.js --anchor 退货流程剩下的就是抽十条引用人工核对
python check_refs.py --sample 10怎么算真的好了，看的是同一批现象。抽检的引用都能定位到正确段落，页码偏差在允许范围内，换版后前端跳转不再错位。
提醒一点。页码是最脆弱的定位方式，引用里带一段原文锚点，即使换版也能靠文本重新对齐。改动前把原配置备份一份，出问题能马上回滚，这比任何技巧都实用。