retrieval.md

# Retrieval and evidence

The Core reads existing SQLite vectors and text; it never creates document vectors. A compatible supplied query representation or inherited query encoder feeds the vector adapter. Runtime FTS5 indexes existing record text, with uncovered Markdown paragraphs searchable as lexical evidence only. Markdown character offsets preserve CRLF. Contiguous existing offset ranges are merged to avoid duplicate lexical copies across vector chunk boundaries.

Chinese literal terms/bigrams supplement unicode61. English FTS BM25 and literal coverage are candidates, not probabilities. Separate ranked lists combine using RRF(k=60). Exact text duplicates and >=80% overlapping source ranges are collapsed before optional rerank. L2 scores retain lower-is-better; dot/cosine higher-is-better; fusion higher-is-better. `score_metadata` states direction and type at each stage.

Each hit includes book-bound evidence ID, existing record ID or `md:start:end`, source metadata/locator, heading path when available, score fields, excerpt range and truncation flag. Missing page mapping is never synthesized. `read-entry` expands evidence; `read-markdown` uses one-based lines or unique headings. Printed PDF labels and zero-based physical page indices are separate.

Default limits: vector30, lexical30, candidates40, final6, result16000 characters, per-hit3000. Max tool results are 64000 characters, 20 hits; images have independent 12M-pixel/8MB budgets. Retrieval settings are JSON under book runtime `config.json`. No LLM API is needed to plan queries: literal terms are generated locally; Agents can pass structured hints/keywords.

When query encoding fails, nonstrict search returns `retrieval_status=lexical_fallback`, `semantic_search_used=false`, and the actual failure category. Verified encoder compatibility is reported separately from operational availability. Strict search propagates encoder and reranker failures. Empty evidence is reported as empty hits with source fallback advice; the client must avoid unsupported answers.

All indexes/caches stay in runtime directories. First prepare is locked; readers also take the short sidecar lock so Windows atomic replacement works. No query-vector cache is currently retained: questions are encoded again on repeated cloud queries. This avoids cross-model or provider-version cache reuse. The lexical fingerprint includes DB and raw Markdown hashes plus implementation version; source caches bind original hash.

原文 SHA-256：ee1bb3514b362e20bbaf60b53a2afb482802d6701f3da2d78e5103127f63a1b1