perf(cite): cbeta_id 索引消除全表扫描;置信度恒为 1.00 时不再逐行标注

[xr843]

Summary

两项独立的小改进,共同点是都在修正"实测暴露、但没人报告过"的问题。

1. cite 不再全表扫描。 parallels 表除 FTS 外没有任何索引,cite 的 WHERE cbeta_id = ?1 COLLATE NOCASE 因此扫描全部 908,620 行——实测端到端 2.34 s。现在建 (cbeta_id COLLATE NOCASE, juan_num, id) 索引;COLLATE NOCASE 不可省,BINARY 索引服务不了该比较的等值查找,实测只能退化成索引扫描。

索引是对已下载产物的本地优化,不进 schema.sql:那是兼容性校验的参照物(所有已下载的数据文件都没有这个索引,把它列进去会让"缺索引"看起来像"数据不兼容"),而且该文件会被 Python 导出管线逐字执行,索引若在 schema 里会在 908,620 行插入之前建立、显著拖慢导出。

两条创建路径:安装/更新时在候选文件上建好(失败传播并触发候选清理,不发布半成品);已有数据在首次 cite 时补建(失败一律静默退回全表扫描)。提示只在索引真的建成之后才打印。

实测:首次 cite 0.632 s(含建索引,数据目录 +17.2 MB)→ 之后 0.001 s,约 632 倍。有无索引的输出 diff 完全一致。

2. 恒为 1.0 的置信度标签不再逐行输出。 全库 908,620 行的 confidence 都是 1.0,于是每行末尾的 [MITRA 1.00] 不携带任何信息。现在标签只在能显示出非 1.00 的数字时才出现;判据是格式化后的字符串而非原始浮点,避免 0.9951 这类值"显示成 [MITRA 1.00] 却又被当作有信息量"的自相矛盾。--json 的 confidence 字段与 query.rs 里按置信度排序的逻辑一律未动(后者现在是空转,但对未来有真实分数的数据是正确的)。

一个在审查中发现并修掉的严重缺陷

懒建索引让查询路径第一次向活跃数据库写入——此前 parallel/texts/cite 全都只读打开。这两件事各自没问题,合起来不安全:

数据库是 rollback-journal 模式。17 MB 的 CREATE INDEX 打在 588 MB 文件上会超出默认 2 MB 页缓存 → 溢出 → 同步日志并写 magic header → 日志变"热"。进程若在该窗口死亡(Ctrl-C、agent 超时、OOM、断电),热日志留在磁盘,而只读连接无法回滚它。后果链已被复现:所有查询 exit 1 并报"dataset incompatibility";data update 无效(替换只 rename 主文件,从不碰 -journal);随后旧日志会被重放进刚下载的新库,造成 database disk image is malformed;data clean 同样无效(清理逻辑只匹配候选/下载临时文件的 sidecar)。唯一出路是手动 rm data.sqlite-journal,而工具里没有任何提示。

三项修复:

• 只读打开遇热日志时自愈——以 SQLITE_OPEN_READ_WRITE(不带 CREATE)重开让 SQLite 自己回滚,再转回只读。代码从不自己删日志;不带 CREATE 意味着自愈不会凭空造出空库。判据不是"重开是否成功"而是"重开后能否真的读一次"——SQLite 在内核拒绝 O_RDWR 时会静默降级为只读并返回成功(sqlite3.c 的 unixOpen),只看 open 会把真正只读的安装一并吞掉。真只读安装仍得到原有错误。
• 把 sidecar 清理延伸到活跃路径(clean_data、install_candidate 替换前后),使 data clean / data update 成为真正的恢复手段,且永不把新库发布到一份外来日志之下。该函数是 pub(super),"只在这两处删"由模块系统强制——查询打开路径上不存在任何 sidecar 删除。
• 改掉误导性文案,不再声称数据不兼容,也不再建议重下 183 MB。

Verification

rustup run 1.95.0 cargo test --all --locked        # MSRV,229 passed
rustup run 1.96.0 cargo fmt --all --check          # 通过
rustup run 1.96.0 cargo clippy --all-targets --locked -- -D warnings   # 0 警告

本机默认 stable 为 1.88,低于 MSRV 1.95,故用 rustup run 指定工具链;MSRV 检查用的正是 1.95.0。

真实数据验证(588 MB / 908,620 行 / 1016 部 Taishō):

场景	结果
首次 cite(含建索引)	0.632 s,+17.2 MB
第二次 cite	0.001 s(约 632 倍)
有无索引输出 diff	完全一致
真实输出中 [MITRA 出现次数	0
只读目录	静默降级,退出码 0
真实缓存	全程未被写入(大小不变、无 .lock 残留)

并发经实测:6 个 parallel 读进程在建索引期间并发,全部退出 0、stderr 干净。

Checklist

• The change is focused and contains no credentials, generated datasets, build artifacts, or public vulnerability details.
• I added or updated tests for behavior changes, or explained why tests are not applicable.
• cargo +stable fmt --all --check passes.(以 1.96.0 代 stable,理由见上)
• cargo +stable clippy --all-targets --locked -- -D warnings passes.(同上)
• cargo +stable test --all --locked passes.(同上)
• cargo +1.95.0 test --all --locked passes when the change affects Rust code or dependencies.
• Relevant Python and shell checks from CONTRIBUTING.md pass.(normalize.rs 与 data-pipeline 均未改动,归一化 Rust/Python 一致性契约未受影响)
• Documentation and the unreleased changelog entry are updated when user-visible behavior changes.
• Dependency changes include the intended Cargo.lock update and retain the MSRV.(未新增任何依赖,Cargo.toml/Cargo.lock 未改动)
• Data changes comply with DATA_LICENSE; code changes are acceptable under MIT OR Apache-2.0.

已知遗留(建议另开 issue,均不阻塞)

1. update_data_publishes_without_the_previous_datasets_journal 分不清替换前/后两个清理调用点(删掉任一仍绿)。
2. 只读目录路径(SQLITE_IOERR_DELETE)无自动化测试——那是自愈真正改写主库的唯一分支,目前只有手工验证。
3. is_hot_journal_error 的字符串兜底比需要的宽(rusqlite 无条件启用扩展码,只比 extended_code 即可);今日不会误触发,但安全性依赖注释约定。
4. 未设 busy_timeout:两进程同时撞上热日志时,失败方会打印"当前数据不可写"的诊断(瞬态,重跑即好)。
5. fojin data status 走读写路径,真只读 + 热日志时仍抛原始英文错误(非回归;危险的一半已由 sidecar 清理闭合)。
6. texts 仍是全表扫描(约 0.9 s)。本轮明确排除:加索引要付 +34 MB 而只省 0.8 s,而它真正的病因是把全部分组取回 Rust 再按归一化标题过滤——预聚合小表才是根治,但那需要重新导出数据。
7. examples/claude/commands/parallel.md 指示 agent 向用户展示 confidence,而该值全库恒为 1.0——与本次从人类输出去掉标签的初衷不一致。