prts-terrarchive 0.2.2 → 0.2.3

package/src/search.js

@@ -3,7 +3,8 @@ import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
 import { deflateRawSync, inflateRawSync } from 'node:zlib'
 import { activityMatches, aliasesFor } from './timeline.js'
 import { assertCorpusVersion, corpusVersionSnapshot,
-  DOCUMENT_ORDERING_VERSION, documentGame, documentUid, naturalDocumentTitle } from './store.js'
+  DOCUMENT_ORDERING_VERSION, documentGame, documentUid, naturalDocumentTitle,
+  DATA_VERSION_REF_PATTERN, dataVersionMatches, shortDataVersion } from './store.js'
 import { projectSearch } from './search-projection.js'
 import { wikiActivityName, wikiActivityRanges, wikiCharacterName, wikiDocumentRole,
   wikiSectionAt, wikiSectionRanges } from './wiki.js'
@@ -51,7 +52,14 @@ const SEARCH_POLICY_FINGERPRINT = createHash('sha256').update(JSON.stringify({
   matchingPolicyVersion: MATCHING_POLICY_VERSION,
 })).digest('base64url').slice(0, 16)
 const FILTER_LIMIT = 16
-const DATA_VERSION_PATTERN = /^[0-9a-f]{64}$/
+// The high word identifies the installed pack set; the low word retains the
+// candidate ordinal. Keep these bit assignments fixed across plugin releases.
+const PAGE_SCOPE_PACKS = Object.freeze(['official_game', 'endfield_official_game',
+  'reviewed_wiki', 'terra_journey', 'endfield_reviewed_knowledge', 'entities', 'references'])
+const PAGE_POSITION_STRIDE = 2 ** 32
+const MAX_CANDIDATE_POSITION = 10_000_000
+const MAX_PAGE_POSITION = (2 ** PAGE_SCOPE_PACKS.length) * PAGE_POSITION_STRIDE
+  + MAX_CANDIDATE_POSITION
 /** 过滤单项最长 512 码点：与上述项数上限共同保证压缩游标可被重新解码。 */
 const FILTER_ITEM_LIMIT = 512
 /**
@@ -231,14 +239,14 @@ function normalizedRequest(raw = {}) {
     const resourceType = normalizeText(raw.after.resource_type)
     const title = normalizeText(raw.after.title)
     const position = raw.after.position
-    if (typeof dataVersion !== 'string' || !DATA_VERSION_PATTERN.test(dataVersion)
+    if (typeof dataVersion !== 'string' || !DATA_VERSION_REF_PATTERN.test(dataVersion)
         || !resourceType || !title || !Number.isSafeInteger(position) || position < 0
-        || position > 10_000_000
+        || position > MAX_PAGE_POSITION || position % PAGE_POSITION_STRIDE > MAX_CANDIDATE_POSITION
         || Object.keys(raw.after).some((key) => ![
           'data_version', 'resource_type', 'title', 'position',
         ].includes(key))) {
       throw Object.assign(new Error(
-        'after 必须包含且只能包含 64 位小写 data_version、resource_type、title 和 0..10000000 的安全整数 position'),
+        'after 必须包含且只能包含 data_version（续页给出的版本，至少 8 位）、resource_type、title 和续页给出的安全整数 position'),
         { code: 'INVALID_REQUEST' })
     }
     after = { data_version: dataVersion, resource_type: resourceType, title, position }
@@ -307,17 +315,46 @@ function withoutAfter(request) {
   return searchRequest
 }
 
+function pageScopeMask(store) {
+  if (!store.scopeFingerprint) return null
+  if (!(store.packs instanceof Map)
+      || [...store.packs.keys()].some((id) => !PAGE_SCOPE_PACKS.includes(id))) {
+    throw Object.assign(new Error('无法识别当前安装范围，请重新安装资料包'),
+      { code: 'PAGE_ANCHOR_INVALID' })
+  }
+  return PAGE_SCOPE_PACKS.reduce((mask, id, index) =>
+    mask + (store.packs.has(id) ? 2 ** index : 0), 0)
+}
+
+function encodePagePosition(store, ordinal) {
+  const mask = pageScopeMask(store)
+  return mask === null ? ordinal : (mask + 1) * PAGE_POSITION_STRIDE + ordinal
+}
+
+function decodePagePosition(store, position) {
+  const mask = pageScopeMask(store)
+  const encodedMask = Math.floor(position / PAGE_POSITION_STRIDE) - 1
+  const ordinal = position % PAGE_POSITION_STRIDE
+  if ((mask === null ? encodedMask !== -1 : encodedMask !== mask)
+      || ordinal > MAX_CANDIDATE_POSITION) {
+    throw Object.assign(new Error('分页锚点绑定的安装范围已经变化，请重新搜索'),
+      { code: 'PAGE_ANCHOR_MISMATCH' })
+  }
+  return ordinal
+}
+
 async function checkpointAfterTitle(store, after, request, { signal, deadline } = {}) {
   assertSearchActive(signal, deadline, '分页锚点校验')
-  if (after.data_version !== store.dataVersion) {
+  if (!dataVersionMatches(after.data_version, store.dataVersion)) {
     throw Object.assign(new Error('分页锚点绑定到另一个资料版本，请重新搜索'),
       { code: 'PAGE_ANCHOR_VERSION_MISMATCH', retryable: false })
   }
+  const position = decodePagePosition(store, after.position)
   const regex = request.match_mode === 'regex'
     ? new RegExp(safeRegex(request.query).source, 'iu') : null
   const candidates = await candidateDocumentIds(store, request, regex, { signal, deadline })
   assertSearchActive(signal, deadline, '分页锚点校验')
-  const documentId = candidates[after.position]
+  const documentId = candidates[position]
   const location = documentId ? store.documents.get(documentId) : null
   if (!location) throw Object.assign(new Error('找不到分页锚点，请重新搜索'),
     { code: 'PAGE_ANCHOR_NOT_FOUND' })
@@ -326,7 +363,7 @@ async function checkpointAfterTitle(store, after, request, { signal, deadline }
     throw Object.assign(new Error('分页锚点与当前资料版本不匹配，请重新搜索'),
       { code: 'PAGE_ANCHOR_MISMATCH' })
   }
-  return { nextCandidateIndex: after.position + 1, matchedDocumentsSoFar: 0,
+  return { nextCandidateIndex: position + 1, matchedDocumentsSoFar: 0,
     matchedCountKnown: false }
 }
 
@@ -352,8 +389,8 @@ async function exposeTitleContinuation(store, result, { signal, deadline } = {})
     const document = documentId ? store.documents.get(documentId)?.document : null
     if (!document) throw Object.assign(new Error('无法生成下一页的标题锚点'),
       { code: 'PAGE_ANCHOR_INVALID' })
-    nextAfter = { data_version: store.dataVersion, resource_type: publicResourceType(document),
-      title: naturalDocumentTitle(document), position: anchorOrdinal }
+    nextAfter = { data_version: shortDataVersion(store.dataVersion), resource_type: publicResourceType(document),
+      title: naturalDocumentTitle(document), position: encodePagePosition(store, anchorOrdinal) }
   }
   return { ...result, page: { ...page, next_after: nextAfter } }
 }
@@ -401,7 +438,8 @@ function validCursorSignature(body, received, secret, bytes = 32) {
 }
 
 async function encodeOffsetCursor(store, request, offset) {
-  const payload = [3, cursorVersionTag(store.dataVersion), offset, compactCursorRequest(request)]
+  const payload = [3, cursorVersionTag(store.dataVersion), offset,
+    compactCursorRequest(request), store.scopeFingerprint ?? null]
   const compressed = deflateRawSync(Buffer.from(JSON.stringify(payload)), { level: 9 })
   const encoded = compressed.toString('base64url')
   const body = `s3.${encoded}`
@@ -413,7 +451,7 @@ async function encodeOffsetCursor(store, request, offset) {
 async function encodeScanCursor(store, request, nextCandidateIndex, matchedDocumentsSoFar) {
   const payload = [4, cursorVersionTag(store.dataVersion), DOCUMENT_ORDERING_VERSION,
     SEARCH_POLICY_FINGERPRINT, nextCandidateIndex, matchedDocumentsSoFar,
-    compactCursorRequest(request)]
+    compactCursorRequest(request), store.scopeFingerprint ?? null]
   const compressed = deflateRawSync(Buffer.from(JSON.stringify(payload)), { level: 9 })
   const encoded = compressed.toString('base64url')
   const body = `s4.${encoded}`
@@ -423,6 +461,13 @@ async function encodeScanCursor(store, request, nextCandidateIndex, matchedDocum
   return `${body}.${signature}`
 }
 
+function assertCursorScope(store, scope) {
+  if ((scope ?? null) !== (store.scopeFingerprint ?? null)) {
+    throw Object.assign(new Error('cursor 绑定的安装范围已经变化，请重新搜索'),
+      { code: 'CURSOR_VERSION_MISMATCH' })
+  }
+}
+
 async function decodeCursor(store, cursor) {
   if (String(cursor).length > CURSOR_MAX_LENGTH) {
     throw Object.assign(new Error('cursor 超过长度上限'), { code: 'CURSOR_INVALID' })
@@ -450,6 +495,7 @@ async function decodeCursor(store, cursor) {
       throw Object.assign(new Error('cursor 绑定到另一个资料版本'),
         { code: 'CURSOR_VERSION_MISMATCH' })
     }
+    assertCursorScope(store, value[7])
     if (value[2] !== DOCUMENT_ORDERING_VERSION || value[3] !== SEARCH_POLICY_FINGERPRINT) {
       throw Object.assign(new Error('cursor 绑定的排序或搜索策略已经变化，请重新搜索'),
         { code: 'CURSOR_POLICY_MISMATCH' })
@@ -477,6 +523,7 @@ async function decodeCursor(store, cursor) {
       { code: value?.[1] !== cursorVersionTag(store.dataVersion)
         ? 'CURSOR_VERSION_MISMATCH' : 'CURSOR_INVALID' })
     }
+    assertCursorScope(store, value[4])
     return { kind: 'legacy', request, offset: value[2] }
   }
 
@@ -496,6 +543,7 @@ async function decodeCursor(store, cursor) {
       || !Number.isInteger(value.offset) || value.offset < 0) {
     throw Object.assign(new Error('cursor 内容无效'), { code: 'CURSOR_INVALID' })
   }
+  assertCursorScope(store, value.scope_fingerprint)
   return { kind: 'legacy', request: value.request, offset: value.offset }
 }
 
@@ -520,7 +568,53 @@ function documentMatches(document, speakers, filters) {
     if (!filters.activity_names.some((name) => activityMatches(activity, name, { exact }))) return false
   }
   if (filters.wiki_sections.length && !wikiRole) return false
-  return !filters.speakers.length || filters.speakers.some((speaker) => speakers.includes(speaker))
+  return !filters.speakers.length || speakers.some((speaker) => speakerAllowed(filters, speaker))
+}
+
+/**
+ * speakers 过滤按别名组匹配：请求「银灰」也命中原文说话人「恩希欧迪斯」。
+ * 展开结果挂在不可枚举属性上，游标编码仍只保存用户原始输入。
+ */
+const SPEAKER_ALIASES = Symbol('speakerAliases')
+const SPEAKER_CANONICALS = Symbol('speakerCanonicals')
+
+async function expandSpeakerAliases(store, request) {
+  const speakers = request?.filters?.speakers || []
+  if (!speakers.length) return request
+  let groups = []
+  try { groups = await aliasesFor(store, speakers) } catch { groups = [] }
+  const names = new Set(speakers)
+  const canonicals = new Set()
+  for (const group of groups) {
+    if (group.aliases.length > 1 || group.games.length) canonicals.add(normalizeText(group.canonical))
+    for (const alias of group.aliases) {
+      const value = normalizeText(alias)
+      if (!value) continue
+      names.add(value)
+      // 原文说话人常只写名不写姓：「恩希欧迪斯·希瓦艾什」→「恩希欧迪斯」。
+      const given = value.split(/[·・•]/u)[0].trim()
+      if (given && given !== value && [...given].length >= 2) names.add(given)
+    }
+  }
+  Object.defineProperty(request.filters, SPEAKER_ALIASES, { value: names, enumerable: false })
+  Object.defineProperty(request.filters, SPEAKER_CANONICALS, { value: canonicals, enumerable: false })
+  return request
+}
+
+/** 行级兜底：资料包已把说话人链接到实体时，按实体规范名匹配。 */
+function speakerOccurrenceAllowed(filters, line) {
+  const canonicals = filters[SPEAKER_CANONICALS]
+  if (!canonicals?.size) return false
+  return (line.entity_occurrences ?? []).some((item) => item.evidence_kind === 'speaker'
+    && canonicals.has(normalizeText(item.canonical_name)))
+}
+
+function speakerAllowed(filters, speaker) {
+  if (!filters.speakers.length) return true
+  const value = normalizeText(speaker)
+  if (!value) return false
+  return (filters[SPEAKER_ALIASES] || filters.speakers).has?.(value)
+    ?? filters.speakers.includes(value)
 }
 
 function needsWikiActivityHydration(document) {
@@ -572,6 +666,29 @@ function lineContent(line) {
     ? text.slice(prefix.length).trimStart() : text
 }
 
+/** 展示用正文：只去掉说话人前缀，保留原文全角标点与空白，便于逐字复制引用。 */
+function displayLineContent(line) {
+  const text = String(line.text ?? '').trim()
+  const speaker = String(line.speaker_raw ?? '').trim()
+  if (line.line_type !== 'dialogue' || !speaker) return text
+  const escaped = speaker.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')
+  return text.replace(new RegExp(`^${escaped}\\s*[：:]\\s*`, 'u'), '')
+}
+
+/**
+ * 用户常把搜索结果中的「说话人: 台词」整行复制回来搜索；台词正文不含说话人，
+ * 因此当 query 以本行说话人加冒号开头时，剥掉前缀再匹配正文。
+ */
+function speakerlessQuery(line, query) {
+  const speaker = normalizeText(line.speaker_raw)
+  if (!query || !speaker || line.line_type !== 'dialogue') return null
+  const lowered = query.toLowerCase()
+  const prefix = `${speaker.toLowerCase()}:`
+  if (!lowered.startsWith(prefix)) return null
+  const rest = query.slice(prefix.length).trim()
+  return rest || null
+}
+
 function matchesText(text, query, mode, regex) {
   if (!query) return true
   if (mode === 'regex') return regex.test(normalizeText(text))
@@ -638,18 +755,24 @@ function entityOccurrence(record, line, entityGroups, queryPresent, queryRange =
 
 function lineMatch(record, index, request, regex, entityGroups, bounds = null) {
   const line = record.lines[index]
-  if (request.filters.speakers.length && !request.filters.speakers.includes(line.speaker_raw)) return null
+  if (!speakerAllowed(request.filters, line.speaker_raw)
+      && !speakerOccurrenceAllowed(request.filters, line)) return null
   const content = lineContent(line)
-  if (!matchesText(content, request.query, request.match_mode, regex)) return null
+  let query = request.query
+  if (!matchesText(content, query, request.match_mode, regex)) {
+    const stripped = request.match_mode === 'regex' ? null : speakerlessQuery(line, query)
+    if (!stripped || !matchesText(content, stripped, request.match_mode, regex)) return null
+    query = stripped
+  }
   let start = null
   let end = null
-  if (request.query) {
+  if (query) {
     if (regex) {
       const match = new RegExp(regex.source, regex.flags).exec(normalizeText(content))
       if (match) { start = match.index; end = match.index + match[0].length }
     } else {
       const haystack = normalizeText(content).toLowerCase()
-      const needle = request.query.toLowerCase()
+      const needle = query.toLowerCase()
       start = haystack.indexOf(needle)
       // 区间终点必须用归一化后 needle 的长度：toLocaleLowerCase 可能改变长度
       // （如土耳其语 İ → i̇），用原 query 长度会让实体邻近度判定错位。
@@ -742,7 +865,7 @@ function isExactOfficialArchiveTitle(document, request) {
 }
 
 function lineAllowed(line, filters) {
-  return !filters.speakers.length || filters.speakers.includes(line.speaker_raw)
+  return speakerAllowed(filters, line.speaker_raw) || speakerOccurrenceAllowed(filters, line)
 }
 
 function readableAnchor(record, filters, ranges = null) {
@@ -845,7 +968,7 @@ function excerpt(record, item, bounds = null) {
     item.passage_end + PREVIEW_OPTIONS.after_lines)
   let truncated = false
   const lines = record.lines.slice(start - 1, end).map((line) => {
-    const raw = String(lineContent(line) || '')
+    const raw = displayLineContent(line)
     const text = [...raw].length > PREVIEW_OPTIONS.max_chars_per_line
       ? `${[...raw].slice(0, PREVIEW_OPTIONS.max_chars_per_line).join('')}…` : raw
     if (text !== raw) truncated = true
@@ -1003,6 +1126,8 @@ async function executeLegacySearch(store, request, offset,
             citation: titleOnly ? `《${title}》`
               : sectionName ? `《${title}》Wiki·${sectionName}`
               : `《${title}》第 ${lineStart === lineEnd ? lineStart : `${lineStart}-${lineEnd}`} 行`,
+            ...(titleOnly || sectionName ? {}
+              : { citation_handle: `${documentUid(metadata.document_id)}#L${lineStart}` }),
           })
           returnedChars += shown.characters
         }
@@ -1017,6 +1142,7 @@ async function executeLegacySearch(store, request, offset,
     assertSearchActive(signal, deadline, '分页游标生成')
     return {
       result_kind: resultKind, documents,
+      by_game: gameDistribution(documents),
       page: { returned_documents: documents.length,
         total_relation: 'unknown', has_more: hasMore, exhausted: false,
         next_cursor: nextCursor },
@@ -1095,6 +1221,19 @@ async function candidateDocumentIds(store, request, regex, { signal, deadline }
     indexed = await store.findDocumentsByShortLiteral?.(request.query,
       { signal, deadline, packIds: scopedPackIds }) ?? null
   }
+  // 「说话人: 台词」整行复制搜索：倒排里没有说话人前缀，另按冒号后的台词补一次候选。
+  const colon = request.query.indexOf(':')
+  const spoken = colon > 0 ? request.query.slice(colon + 1).trim() : ''
+  if (indexed !== null && spoken && [...request.query.slice(0, colon)].length <= FILTER_ITEM_LIMIT) {
+    const spokenNgrams = ngramsFor(spoken)
+    let extra = spokenNgrams.length && indexedLookup
+      ? await indexedLookup.call(store, spokenNgrams, { signal, deadline, packIds: scopedPackIds }) : null
+    if (extra === null && spokenNgrams.length && [...spokenNgrams[0]].length < 3) {
+      extra = await store.findDocumentsByShortLiteral?.(spoken,
+        { signal, deadline, packIds: scopedPackIds }) ?? null
+    }
+    indexed = extra === null ? null : [...new Set([...indexed, ...extra])]
+  }
   assertSearchActive(signal, deadline, '候选文档发现')
   if (indexed === null) return prioritizeOfficialTitle(scopedIds)
   return prioritizeOfficialTitle(
@@ -1352,6 +1491,8 @@ function buildPublicDocument(store, group, resultKind, request, budget = Infinit
         citation: titleOnly ? `《${title}》`
           : sectionName ? `《${title}》Wiki·${sectionName}`
           : `《${title}》第 ${lineStart === lineEnd ? lineStart : `${lineStart}-${lineEnd}`} 行`,
+        ...(titleOnly || sectionName ? {}
+          : { citation_handle: `${documentUid(metadata.document_id)}#L${lineStart}` }),
       })
       characters += shownCharacters
     }
@@ -1359,6 +1500,17 @@ function buildPublicDocument(store, group, resultKind, request, budget = Infinit
   return { document: result, characters, reasons }
 }
 
+/** 本页命中的游戏分布：同名实体跨游戏时，让调用方一眼看出该收窄 games。 */
+function gameDistribution(documents) {
+  const counts = {}
+  for (const document of documents) {
+    const game = document?.game
+    if (game !== 'arknights' && game !== 'endfield') continue
+    counts[game] = (counts[game] || 0) + 1
+  }
+  return counts
+}
+
 async function executeScanSearch(store, request, checkpoint,
   { signal, requestId = null, deadline = Date.now() + SEARCH_TIMEOUT_MS } = {}) {
   const started = Date.now()
@@ -1433,6 +1585,9 @@ async function executeScanSearch(store, request, checkpoint,
     return {
       result_kind: resultKind,
       documents,
+      by_game: gameDistribution(documents),
+      // 本次检索覆盖的本地资料规模：零命中时据此说明"检查了多少篇/行"。
+      ...(typeof store.corpusTotals === 'function' ? { scope: store.corpusTotals() } : {}),
       page: {
         returned_documents: documents.length,
         ...(exhausted && countKnown ? { total_documents: matchedDocuments } : {}),
@@ -1464,7 +1619,7 @@ export async function executeSearch(store, raw,
     snapshot = corpusVersionSnapshot(store)
     deadline = Date.now() + SEARCH_TIMEOUT_MS
     assertSearchActive(signal, deadline)
-    const normalized = normalizedRequest(raw)
+    const normalized = await expandSpeakerAliases(store, normalizedRequest(raw))
     const attachCorpusWarnings = (value, request) => {
       assertCorpusVersion(store, snapshot)
       if (value?.status === 'error' || !(store.packs instanceof Map)) return value
@@ -1480,6 +1635,7 @@ export async function executeSearch(store, raw,
     if (normalized.cursor) {
       assertSearchActive(signal, deadline, '分页游标校验')
       const decoded = await decodeCursor(store, normalized.cursor)
+      await expandSpeakerAliases(store, decoded.request)
       assertSearchActive(signal, deadline, '分页游标校验')
       const requestedGames = decoded.request.filters?.games?.length
         ? decoded.request.filters.games : ['arknights', 'endfield']
@@ -1517,6 +1673,6 @@ export async function executeSearch(store, raw,
 export function renderSearch(args, value) {
   if (value?.error) return [{ type: 'text', text: `[corpus_search:error] ${value.error.code}: ${value.error.message}` }]
   return [{ type: 'text', text: projectSearch(value, {
-    query: normalizeText(args?.query),
+    query: normalizeText(args?.query), args,
   }) }]
 }

package/src/store.js

@@ -294,6 +294,34 @@ function characterMaterialKey(game, characterName, material) {
   return `${String(game || '')}\0${normalizedLookupText(characterName)}\0${String(material || '')}`
 }
 
+/** 标题宽松比较键：NFKC、小写、去空白与常见间隔符。 */
+export function looseTitleKey(value) {
+  return String(value ?? '').normalize('NFKC').toLowerCase()
+    .replace(/[\s·・•‧∙⋅_\-—–]+/gu, '')
+}
+
+function sharedBigrams(left, right) {
+  const grams = (text) => {
+    const chars = [...text]
+    if (chars.length < 2) return new Set(chars)
+    return new Set(chars.slice(1).map((char, index) => chars[index] + char))
+  }
+  const a = grams(left)
+  const b = grams(right)
+  if (!a.size || !b.size) return 0
+  let shared = 0
+  for (const gram of a) if (b.has(gram)) shared += 1
+  return shared / a.size
+}
+
+function isSubsequence(needle, haystack) {
+  const chars = [...needle]
+  if (chars.length < 2) return false
+  let index = 0
+  for (const char of haystack) if (char === chars[index]) index += 1
+  return index === chars.length
+}
+
 function naturalDocumentTitleBase(document = {}, { includeOperatorRecordSegment = true } = {}) {
   const displayTitle = publicMetadataText(document.display_title)
   if (documentGame(document) === 'endfield' && document.game) return displayTitle
@@ -449,6 +477,8 @@ export class CorpusStore {
     this._loaded = false
     this.releaseId = null
     this.dataVersion = null
+    this.installationId = null
+    this.scopeFingerprint = null
     /** @type {Map<string, { packId: string, shardPath: string, index: number }>} */
     this.documents = new Map()
     /** @type {string[]} 全局稳定 document_ordinal → document_id。 */
@@ -535,6 +565,8 @@ export class CorpusStore {
     this._loaded = false
     this.releaseId = null
     this.dataVersion = null
+    this.installationId = null
+    this.scopeFingerprint = null
     this.documents.clear()
     this.documentOrder = []
     this.prefixIndex.clear()
@@ -560,6 +592,7 @@ export class CorpusStore {
     this.unstableChars = null
     this._timelineRows = null
     this._aliasGroups = null
+    this._looseTitleIndex = null
   }
 
   async _init(generation) {
@@ -568,7 +601,7 @@ export class CorpusStore {
     // Store 是 Host 权限下的持久文件入口。每次装载都先验证 release id、声明的
     // 全部 pack、资源路径/尺寸/哈希与符号链接，再读取任何压缩内容。
     const validated = await validateLocalRelease(this.releasesDir, releaseId,
-      { verifyHashes: true, details: true })
+      { verifyHashes: true, details: true, allowPartial: true })
     const { manifest: releaseManifest, packManifests, releaseDir } = validated
     if (current.data_version != null && current.data_version !== releaseManifest.data_version) {
       throw new Error('CorpusStore: current.json data_version does not match release-manifest')
@@ -594,7 +627,8 @@ export class CorpusStore {
     }
     const stableChars = new Set()
 
-    const entries = releaseManifest.packs.map((descriptor) => ({
+    const installedPackIds = validated.installedPackIds ?? releaseManifest.packs.map((pack) => pack.pack_id)
+    const entries = releaseManifest.packs.filter((pack) => installedPackIds.includes(pack.pack_id)).map((descriptor) => ({
       name: descriptor.pack_id,
       manifestPath: descriptor.manifest_path,
     })).sort(packOrder)
@@ -742,6 +776,9 @@ export class CorpusStore {
     if (generation !== this._generation) return false
     this.releaseId = next.releaseId
     this.dataVersion = next.dataVersion
+    this.installationId = current.installation_id ?? null
+    this.scopeFingerprint = sha256(JSON.stringify([next.dataVersion, [...installedPackIds].sort()]))
+    this._looseTitleIndex = null
     this.documents = next.documents
     this.documentOrder = next.documentOrder
     this.prefixIndex = next.prefixIndex
@@ -899,6 +936,26 @@ export class CorpusStore {
     return bytes
   }
 
+  /**
+   * 本地资料包规模：可检索的篇数与行数。零命中时用它说明"检查了多大的范围"，
+   * 让"没有找到"成为可引用的否定证据。按资料版本缓存，切版自动失效。
+   * @returns {{documents: number, lines: number}}
+   */
+  corpusTotals() {
+    if (this._corpusTotals?.dataVersion === this.dataVersion) return this._corpusTotals.value
+    let documents = 0
+    let lines = 0
+    for (const entry of this.documents.values()) {
+      const document = entry?.document
+      if (!document) continue
+      documents += 1
+      lines += Number(document.line_count || 0)
+    }
+    const value = { documents, lines }
+    this._corpusTotals = { dataVersion: this.dataVersion, value }
+    return value
+  }
+
   /**
    * 按 document_id 取完整文档记录。
    * @returns {Promise<{ record: object, packId: string } | null>}
@@ -996,7 +1053,64 @@ export class CorpusStore {
         `标题“${normalized}”对应 ${documentIds.length} 篇资料；请使用 corpus_search 返回的带资料类型完整标题`,
       ), { code: 'DOCUMENT_AMBIGUOUS' })
     }
-    return documentIds.length ? this.getDocument(documentIds[0]) : null
+    if (documentIds.length) return this.getDocument(documentIds[0])
+    // 宽松回退：忽略空白、间隔号（· ・ •）、斜杠两侧空格、全半角与大小写差异，
+    // 以及角色×活动 Wiki 的内部「第 N 篇」序号；唯一命中才直接返回。
+    const loose = this.looseTitleMatches(normalized)
+    if (loose.length === 1) return this.getDocument(loose[0])
+    return null
+  }
+
+  /** 宽松标题索引：loose key → document_id[]，按资料版本惰性构建。 */
+  looseTitleIndex() {
+    if (this._looseTitleIndex?.version === this.dataVersion) return this._looseTitleIndex.index
+    const index = new Map()
+    const add = (title, documentId) => {
+      const key = looseTitleKey(title)
+      if (!key) return
+      const ids = index.get(key) ?? []
+      if (!ids.includes(documentId)) ids.push(documentId)
+      index.set(key, ids)
+    }
+    for (const [title, ids] of this.naturalTitleIndex) {
+      for (const documentId of ids) {
+        add(title, documentId)
+        const withoutSequence = title.replace(/\s*·\s*第\s*\d+\s*篇$/u, '')
+        if (withoutSequence !== title) add(withoutSequence, documentId)
+      }
+    }
+    for (const [title, ids] of this.titleIndex) for (const documentId of ids) add(title, documentId)
+    this._looseTitleIndex = { version: this.dataVersion, index }
+    return index
+  }
+
+  looseTitleMatches(title) {
+    const key = looseTitleKey(title)
+    return key ? [...(this.looseTitleIndex().get(key) ?? [])] : []
+  }
+
+  /** 读取失败时给出最接近的完整标题候选（最多 limit 条）。 */
+  suggestTitles(title, limit = 5) {
+    const key = looseTitleKey(title)
+    if (!key) return []
+    const scored = []
+    for (const [candidateTitle, ids] of this.naturalTitleIndex) {
+      if (!ids.some((documentId) => this.isPreferredNaturalDocument?.(documentId) !== false)) continue
+      const candidate = looseTitleKey(candidateTitle)
+      let score = 0
+      if (candidate === key) score = 100
+      else if (candidate.includes(key)) score = 80 - Math.min(40, candidate.length - key.length)
+      else if (key.includes(candidate) && candidate.length >= 2) score = 60 - Math.min(40, key.length - candidate.length)
+      else if (isSubsequence(key, candidate)) score = 70 - Math.min(40, candidate.length - key.length)
+      else {
+        const shared = sharedBigrams(key, candidate)
+        if (shared >= 0.6) score = Math.round(shared * 50) - Math.min(20, Math.abs(candidate.length - key.length))
+      }
+      if (score > 0) scored.push({ title: candidateTitle, score })
+    }
+    return scored.sort((left, right) => right.score - left.score
+      || left.title.length - right.title.length || left.title.localeCompare(right.title, 'zh-CN'))
+      .slice(0, limit).map((item) => item.title)
   }
 
   /** 搜索结果若无法仅靠自然标题/合集名稳定回读，就公开短 document_uid。 */
@@ -1567,3 +1681,13 @@ export class CorpusStore {
     return matches
   }
 }
+
+/** 模型可见的资料版本引用：续页只需前 12 位；校验时接受 ≥8 位前缀。 */
+export const DATA_VERSION_REF_PATTERN = /^[0-9a-f]{8,64}$/u
+export function shortDataVersion(value) {
+  return String(value || '').slice(0, 12)
+}
+export function dataVersionMatches(given, actual) {
+  return typeof given === 'string' && DATA_VERSION_REF_PATTERN.test(given)
+    && typeof actual === 'string' && actual.startsWith(given)
+}