prts-terrarchive 0.2.1 → 0.2.3

package/src/search-projection.js

@@ -18,10 +18,15 @@ const EVIDENCE_LABELS = Object.freeze({
   derived_timeline: '整理性时间线', entity_projection: '实体关联入口', catalog: '资料目录',
 })
 
+// 命中高亮用 ⟦⟧：明日方舟档案正文自身大量使用【代号】【性别】，不能再用【】。
+const HIT_OPEN = '⟦'
+const HIT_CLOSE = '⟧'
+
 function renderLine(line) {
   const marker = line.role === 'match' ? '>' : line.role === 'constraint' ? '+' : ' '
   const number = line.line == null ? '' : String(line.line).padStart(4, ' ')
-  const speaker = line.speaker ? `${line.speaker}：` : ''
+  // 与 corpus_read 的行格式一致：「说话人: 台词」。
+  const speaker = line.speaker ? `${line.speaker}: ` : ''
   return `${marker} ${number} ${speaker}${line.rendered_text ?? line.text}${line.truncated ? '（本行已截断）' : ''}`.trimEnd()
 }
 
@@ -29,18 +34,47 @@ function normalizeText(value) {
   return String(value ?? '').normalize('NFKC').replace(/\s+/gu, ' ').trim()
 }
 
+/**
+ * 在原文上高亮：匹配时按 NFKC + 小写比较（与检索一致），输出保留原文字符。
+ * 逐码点建立「归一化偏移 → 原文偏移」映射，避免全角标点被改写。
+ */
+function normalizedIndex(text) {
+  let normalized = ''
+  const starts = []
+  const ends = []
+  let offset = 0
+  let previousSpace = true
+  for (const char of text) {
+    let piece = char.normalize('NFKC').toLocaleLowerCase()
+    if (/^\s+$/u.test(piece)) {
+      piece = previousSpace ? '' : ' '
+    }
+    for (let index = 0; index < piece.length; index += 1) {
+      starts.push(offset)
+      ends.push(offset + char.length)
+    }
+    if (piece) previousSpace = piece === ' '
+    normalized += piece
+    offset += char.length
+  }
+  return { normalized, starts, ends }
+}
+
 function highlightLiteral(text, query) {
-  const needle = normalizeText(query)
+  const needle = normalizeText(query).toLocaleLowerCase()
   if (!needle) return text
-  const haystack = text.toLocaleLowerCase()
-  const loweredNeedle = needle.toLocaleLowerCase()
+  const { normalized, starts, ends } = normalizedIndex(text)
   const parts = []
   let cursor = 0
-  let offset = haystack.indexOf(loweredNeedle)
+  let offset = normalized.indexOf(needle)
   while (offset >= 0) {
-    parts.push(text.slice(cursor, offset), `【${text.slice(offset, offset + needle.length)}】`)
-    cursor = offset + needle.length
-    offset = haystack.indexOf(loweredNeedle, cursor)
+    const from = starts[offset]
+    const to = ends[offset + needle.length - 1]
+    if (from >= cursor) {
+      parts.push(text.slice(cursor, from), `${HIT_OPEN}${text.slice(from, to)}${HIT_CLOSE}`)
+      cursor = to
+    }
+    offset = normalized.indexOf(needle, offset + needle.length)
   }
   return parts.length ? `${parts.join('')}${text.slice(cursor)}` : text
 }
@@ -48,26 +82,47 @@ function highlightLiteral(text, query) {
 function highlightRegex(text, query) {
   try {
     const regex = new RegExp(query, 'giu')
-    return text.replace(regex, (matched) => `【${matched}】`)
+    // 检索按 NFKC 文本匹配；展示仍在原文上尽力高亮，匹配不上时保持原文不加标记。
+    return text.replace(regex, (matched) => matched ? `${HIT_OPEN}${matched}${HIT_CLOSE}` : matched)
   } catch {
     return text
   }
 }
 
+function speakerlessQuery(line, query) {
+  const speaker = normalizeText(line.speaker)
+  const needle = normalizeText(query)
+  if (!speaker || !needle.toLocaleLowerCase().startsWith(`${speaker.toLocaleLowerCase()}:`)) return query
+  return needle.slice(speaker.length + 1).trim() || query
+}
+
 function renderedExcerptLine(line, match, options) {
   if (line.role !== 'match' || !options.query) return line
   const renderedText = match.match_kind === 'regex'
-    ? highlightRegex(line.text, options.query) : highlightLiteral(line.text, options.query)
+    ? highlightRegex(line.text, options.query)
+    : highlightLiteral(line.text, speakerlessQuery(line, options.query))
   return renderedText === line.text ? line : { ...line, rendered_text: renderedText }
 }
 
 function renderMatch(match, options) {
+  // 目录/元数据命中没有正文行：直说"为什么命中"，别让调用方以为漏了内容。
+  if (match.line_start == null && !(match.excerpt || []).length) {
+    const locator = options.documentUid
+      ? { document_uid: options.documentUid, mode: 'document' }
+      : { title: String(options.documentTitle || ''), mode: 'document' }
+    return [`命中方式：标题/元数据命中本篇（该篇没有正文命中行）`,
+      `读取：corpus_read(${JSON.stringify(locator)})`].join('\n')
+  }
   const range = match.line_start == null ? ''
     : `命中：第 ${match.line_start === match.line_end ? match.line_start
       : `${match.line_start}-${match.line_end}`} 行`
+  // 句柄：检索结果直接给出可回读的凭据，Agent 不必先查 document_uid 再读。
+  const handle = match.citation_handle
+    ? `句柄：${match.citation_handle} · 回到这几行：corpus_read({"citation":"${match.citation_handle}"})`
+    : ''
   return [range, `证据：${EVIDENCE_LABELS[match.evidence_kind] || match.evidence_kind}`,
     ...(match.excerpt || []).map((line) => renderLine(renderedExcerptLine(line, match, options))),
-    `引用：${match.citation}`].filter(Boolean).join('\n')
+    `引用：${match.citation}`, handle].filter(Boolean).join('\n')
 }
 
 function renderSection(section) {
@@ -84,14 +139,41 @@ function renderEntitySummary(summary) {
     `引用：${summary.citation}`].filter(Boolean).join('\n')
 }
 
+const WIKI_TYPES = ['character_wiki', 'story_wiki', 'character_activity_wiki']
+const WIKI_NOTICE = '引文状态：Wiki 为整理性资料；其中引号内容未核验为当前资料包官方原文，逐字引用前请回查原文。'
+
+/** 引用资料（泰拉年表、活动时间线）里存的是原始 wikitext / JSON，展开进检索结果只会烧 token。 */
+function isSerializedDataLine(line) {
+  const text = String(line.rendered_text ?? line.text ?? '')
+  if (text.length > 240) return true
+  if (/^\s*[{[]/u.test(text)) return true
+  return /"(?:schema_version|source_location|wikitext_line|raw_wikitext)"\s*:/u.test(text)
+}
+
+function serializedReferenceBody(document, matches) {
+  const lines = matches.flatMap((match) => match.excerpt || [])
+  if (!lines.length || !lines.some(isSerializedDataLine)) return null
+  if (lines.filter(isSerializedDataLine).length < Math.ceil(lines.length / 2)) return null
+  return ['本篇为引用资料，正文是原始 wikitext / JSON，不在检索结果里展开。',
+    '查事件年代与顺序请用 timeline_search；确需原文时按已知行号读取：',
+    `corpus_read(${JSON.stringify(document.document_uid
+      ? { document_uid: document.document_uid, mode: 'document' }
+      : { title: document.title, mode: 'document' })})`].join('\n')
+}
+
 function renderDocument(document, options) {
+  const serialized = document.resource_type === 'reference'
+    ? serializedReferenceBody(document, document.matches || []) : null
   const body = document.entity_summary ? renderEntitySummary(document.entity_summary)
     : document.section_content ? renderSection(document.section_content)
-    : document.matches?.length ? document.matches.map((match) => renderMatch(match, options)).join('\n\n')
-      : document.available_sections?.length
-        ? `可用字段：${document.available_sections.join('、')}` : '资料入口'
-  const wikiNotice = ['character_wiki', 'story_wiki', 'character_activity_wiki']
-    .includes(document.resource_type)
+    : serialized ? serialized
+    : document.matches?.length ? document.matches.map((match) => renderMatch(match, {
+      ...options, documentUid: document.document_uid, documentTitle: document.title })).join('\n\n')
+      : [document.available_sections?.length ? `可用字段：${document.available_sections.join('、')}` : '',
+        `读取：corpus_read(${JSON.stringify(document.document_uid
+          ? { document_uid: document.document_uid, mode: 'document' }
+          : { title: document.title })})`].filter(Boolean).join('\n')
+  const wikiNotice = !options.sharedWikiNotice && WIKI_TYPES.includes(document.resource_type)
     ? '引文状态：Wiki 为整理性资料；其中引号内容未核验为当前资料包官方原文，逐字引用前请回查原文。'
     : ''
   const game = document.game === 'endfield' ? '终末地'
@@ -104,6 +186,46 @@ function renderDocument(document, options) {
     .filter(Boolean).join('\n')
 }
 
+/** 零命中时按实际使用的过滤条件给出具体放宽方向。 */
+export function zeroHitHints(args = {}) {
+  const has = (field) => Array.isArray(args?.[field])
+    && args[field].some((item) => typeof item === 'string' && item.trim())
+  const hints = []
+  if (has('context_terms')) {
+    hints.push('context_terms 是强约束：每个词都必须出现在命中行前后 3 行内，不是整篇共现；请先去掉 context_terms 重试。')
+  }
+  if (has('story_names')) {
+    hints.push('story_names 只匹配单关/单篇剧情名（如“鳞的记忆”）；活动或章节名（如“昨日海”）请改用 activity_names。')
+  }
+  if (has('activity_names') || has('collection_names')) {
+    hints.push('activity_names / collection_names 需与展示名完全一致；不确定时先省略 query 只按名称列目录核对。')
+  }
+  if (has('speakers')) {
+    hints.push('speakers 只匹配本人亲口台词（已自动展开已登记别名，如 银灰→恩希欧迪斯）；提及该角色的旁白或他人台词请改用 entity_names 或 query。')
+    const query = normalizeText(args?.query)
+    if (query && args.speakers.some((name) => query.includes(normalizeText(name)))) {
+      hints.push('query 只匹配台词正文，不含说话人名；按说话人找台词时请省略 query，或只写台词片段。')
+    }
+  }
+  if (has('resource_types') || has('content_types') || has('wiki_sections')) {
+    hints.push('resource_types / content_types / wiki_sections 会缩小资料类型；可先移除再看命中分布。')
+  }
+  if (args?.match_mode === 'regex') hints.push('regex 模式按受限正则匹配；可改回默认 literal 并缩短为关键短语。')
+  return hints
+}
+
+/** 本页命中的游戏分布。跨游戏命中时提醒收窄，避免同名实体（如「博士」）互相污染。 */
+function gameDistributionLine(byGame) {
+  const labels = { arknights: '明日方舟', endfield: '终末地' }
+  const parts = Object.entries(byGame || {})
+    .filter(([game, count]) => labels[game] && Number.isInteger(count) && count > 0)
+    .map(([game, count]) => `${labels[game]} ${count} 篇`)
+  if (!parts.length) return ''
+  const cross = Object.keys(byGame || {}).filter((game) => labels[game]).length > 1
+  return `命中分布（按游戏，本页）：${parts.join(' · ')}`
+    + (cross ? '。跨游戏命中，做人物向研究时请用 games 限定' : '')
+}
+
 export function projectSearch(value, options = {}) {
   const documents = value?.documents || []
   const matches = documents.reduce((total, document) => total
@@ -118,14 +240,21 @@ export function projectSearch(value, options = {}) {
     ? `扫描尚未穷尽。继续时保留本次搜索词和过滤条件，并设置 after: ${JSON.stringify(value.page.next_after)}。`
     : value?.page?.next_cursor
       ? `旧版分页尚未结束。继续时仅提交 cursor: ${JSON.stringify(value.page.next_cursor)}。` : ''
+  const distribution = gameDistributionLine(value?.by_game)
+  const hints = zeroHitHints(options.args)
+  // 覆盖率：让"没有找到"带上检查范围，成为可引用的否定证据。
+  const scopeText = Number.isInteger(value?.scope?.documents)
+    ? `本地 ${value.scope.documents} 篇 / ${Number(value.scope.lines || 0)} 行`
+    : ''
   const zero = documents.length ? '' : exhausted
-    ? '已检查完整检索范围，没有找到。请检查展示名、缩短连续字面串或移除冲突过滤条件。'
+    ? [`已检查完整检索范围${scopeText ? `（${scopeText}）` : ''}，没有找到。请检查展示名、缩短连续字面串或移除冲突过滤条件。`,
+      ...hints.map((hint) => `- ${hint}`)].join('\n')
     : value?.page?.next_after
       ? '本页没有发现命中文档，但扫描位置已经推进；这不是全库零命中。'
       : '该旧版分页链已经结束，但不能证明资料范围已经穷尽；需要完整性时请重新搜索。'
   const complete = exhausted && documents.length
     ? Number.isInteger(value.page.total_documents)
-      ? `已检查完整检索范围，共匹配 ${value.page.total_documents} 篇资料。`
+      ? `已检查完整检索范围${scopeText ? `（${scopeText}）` : ''}，共匹配 ${value.page.total_documents} 篇资料。`
       : '已扫描至当前检索范围末尾。'
     : ''
   const warnings = (value?.warnings || []).length
@@ -134,6 +263,12 @@ export function projectSearch(value, options = {}) {
     ? `## 再旅者对应关系（人工审校附属字段）\n${value.retraveler_relations.map((item) =>
       `- 终末地角色：${item.endfield_name}；泰拉记忆原型：${item.terra_memory_prototype || '未登记'}；` +
       `状态：${item.relation_status}。这是跨游戏关系，不是人物别名。`).join('\n')}` : ''
-  return [heading, warnings, relations, ...documents.map((document) => renderDocument(document, options)), zero, complete, next]
+  // 多篇 Wiki 同屏时引文提示只说一次，避免每篇重复同一句话。
+  const wikiCount = documents.filter((document) => WIKI_TYPES.includes(document.resource_type)).length
+  const sharedWikiNotice = wikiCount > 1
+  const documentOptions = sharedWikiNotice ? { ...options, sharedWikiNotice } : options
+  return [heading, distribution, sharedWikiNotice ? `${WIKI_NOTICE}（适用于下列所有 Wiki 条目）` : '',
+    warnings, relations,
+    ...documents.map((document) => renderDocument(document, documentOptions)), zero, complete, next]
     .filter(Boolean).join('\n\n')
 }

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,
   }) }]
 }