prts-terrarchive 0.2.2 → 0.2.3

package/src/read-args.js

@@ -0,0 +1,86 @@
+import { dropEmptyPlaceholders } from './tool-args.js'
+
+const ZERO_FIELDS = ['line', 'start_line', 'segment', 'position', 'max_lines', 'max_chars']
+
+/**
+ * 句柄 citation：检索结果发出去的"重新取用"凭据，形如 doc_xxxxxxxxxxxxxxxx#L123
+ * 或 doc_xxxxxxxxxxxxxxxx#L120-L135。它把"标题可能同名、抓不到 document_uid"的两跳
+ * 缩成一步，Agent 复制粘贴即可回到原文。
+ * @returns {{documentUid: string, startLine: number, endLine: number} | null}
+ */
+export function parseCitation(value) {
+  const match = String(value ?? '').trim()
+    .match(/^(doc_[A-Za-z0-9_-]{16})#L([1-9][0-9]*)(?:-L?([1-9][0-9]*))?$/u)
+  if (!match) return null
+  const startLine = Number(match[2])
+  const endLine = match[3] === undefined ? startLine : Number(match[3])
+  if (endLine < startLine) return null
+  return { documentUid: match[1], startLine, endLine }
+}
+
+/** 把篇章定位与行号区间拼成句柄，供检索结果回显。 */
+export function formatCitation(documentUid, startLine, endLine = startLine) {
+  if (!documentUid || !Number.isInteger(startLine)) return ''
+  return `${documentUid}#L${startLine === endLine ? startLine : `${startLine}-${endLine}`}`
+}
+
+/** Independent anchors, never inferred from an optional modifier alone. */
+export function readTargets(args) {
+  return [
+    ['title', ['title']], ['document_uid', ['document_uid']], ['stage_code', ['stage_code']],
+    ['record_name', ['character_name', 'record_name']],
+    ['material', ['character_name', 'material']],
+    ['activity_name', ['activity_name']], ['collection_name', ['collection_name']],
+  ].filter(([key]) => args[key] !== undefined && (key !== 'material' || args.character_name !== undefined))
+    .map(([key, keys]) => ({ key, args: Object.fromEntries(keys.filter((name) => args[name] !== undefined)
+      .map((name) => [name, args[name]])) }))
+}
+
+/** Keep every real target and pagination credential. Only known orphan defaults are compatible fillers. */
+export function normalizeReadArguments(raw, { sections = [] } = {}) {
+  const args = dropEmptyPlaceholders(raw, { zeroFields: ZERO_FIELDS })
+  if (!args || typeof args !== 'object' || Array.isArray(args)) return { args, guidance: '' }
+  const notes = []
+  if (args.line === undefined) {
+    if (args.before === 0) delete args.before
+    if (args.after === 0) delete args.after
+  }
+  if (readTargets(args).length === 1 && args.cursor === undefined) {
+    const ignored = []
+    const removeDefault = (key, matches) => {
+      if (!matches || args[key] === undefined) return
+      ignored.push(key)
+      delete args[key]
+    }
+    // 表单式调用会把所有可选字段一并填上（""、0、默认值）。附属参数只要没有对应主定位，
+    // 就不表达任何意图：一律忽略并说明，不报错——报错只会让调用方在同一处反复试。
+    removeDefault('story_part', args.stage_code === undefined)
+    removeDefault('segment', args.record_name === undefined)
+    removeDefault('material', args.character_name === undefined)
+    removeDefault('start_line', args.mode !== 'document' && !(args.mode === undefined
+      && args.line === undefined && args.section === undefined))
+    removeDefault('game', !(args.character_name !== undefined && args.material !== undefined)
+      && ['arknights', 'endfield'].includes(args.game))
+    if (ignored.length) notes.push(`参数适配：已忽略没有对应定位信息的默认附属参数 ${ignored.join('、')}；未改变目标文档。`)
+    if (args.mode === 'document' && sections.includes(args.section)) {
+      notes.push(`读取方式：mode=document 已明确选择全文，未应用 section=${args.section}。如只读取该字段，请省略 mode，保留 title 或 document_uid 与 section。`)
+      delete args.section
+    }
+  }
+  return { args, guidance: notes.join('\n') }
+}
+
+/** Concrete conflicting targets and independently executable retries; never choose a target for the caller. */
+export function readTargetError(args) {
+  const targets = readTargets(args)
+  if (!targets.length) return '缺少主定位信息：请提供 title、document_uid、stage_code、character_name+record_name、character_name+material、activity_name 或 collection_name 中的一种。story_part、segment、material 单独出现不能定位资料。'
+  const examples = targets.map(({ key, args: target }) => ({ ...target,
+    mode: key === 'activity_name' ? 'activity' : key === 'collection_name' ? 'collection' : 'document' }))
+  const titleUidHint = args.title !== undefined && args.document_uid !== undefined
+    ? 'document_uid 会替代 title，不要同时提交二者。' : ''
+  return `必须且只能提供一种定位方式；实际冲突：${targets.map(({ args: target }) => Object.keys(target).join('+')).join(' 与 ')}。请选择目标后仅提交其中一组：${examples.map((example) => JSON.stringify(example)).join(' 或 ')}。${titleUidHint}附属参数不能代替主定位信息。`
+}
+
+export function withReadGuidance(value, guidance) {
+  return guidance ? { ...value, guidance: [value.guidance, guidance].filter(Boolean).join('\n') } : value
+}

package/src/read.js

@@ -14,7 +14,7 @@ import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
 import { assertCorpusVersion, corpusVersionSnapshot, computeLinesIntegrity,
   documentGame, documentUid, naturalDocumentTitle,
   operatorRecordSegment, publicCharacterMaterial, publicStoryPart,
-  publicStoryStageCode } from './store.js'
+  publicStoryStageCode, shortDataVersion } from './store.js'
 import { WIKI_SECTION_VALUES, wikiSectionRanges } from './wiki.js'
 
 export const CONTRACT_VERSION = 'prts-corpus-tools-v1'
@@ -404,7 +404,17 @@ export async function executeRead(store, rawArgs, runtime) {
         throw error
       }
       if (found === null) {
-        throw new ContractError('DOCUMENT_NOT_FOUND', '本地资料包中找不到该完整标题对应的文档')
+        const loose = store.looseTitleMatches?.(normalized.locator.display_title) ?? []
+        const candidates = loose.length > 1
+          ? loose.map((documentId) => store.documents.get(documentId)?.document)
+            .filter(Boolean).map((document) => naturalDocumentTitle(document))
+          : store.suggestTitles?.(normalized.locator.display_title, 5) ?? []
+        const unique = [...new Set(candidates)].slice(0, 8)
+        const endfieldTip = unique.some((title) => title.startsWith('终末地 · '))
+          ? '终末地同一任务的多段对话可改用 {"collection_name":"任务名","mode":"collection"} 连续阅读。' : ''
+        throw new ContractError('DOCUMENT_NOT_FOUND', unique.length
+          ? `本地资料包中找不到标题“${normalized.locator.display_title}”。最接近的完整标题：${unique.map((title) => `“${title}”`).join('、')}；请改用其一作为 title 重试。${endfieldTip}`
+          : `本地资料包中找不到标题“${normalized.locator.display_title}”；请先用 corpus_search 按关键词或 activity_names 列目录，再复制返回的完整标题。`)
       }
     } else {
       const sourceRef = normalized.locator.source_ref
@@ -466,7 +476,10 @@ export async function executeRead(store, rawArgs, runtime) {
       }
       const ranges = wikiSectionRanges(record, [selection.section])
       if (!ranges.length) {
-        throw new ContractError('DOCUMENT_NOT_FOUND', `Wiki 文档“${document.display_title}”没有字段“${selection.section}”`)
+        const available = [...new Set(wikiSectionRanges(record).map((range) => range.name))]
+        throw new ContractError('DOCUMENT_NOT_FOUND', `Wiki 文档“${document.display_title}”没有字段“${selection.section}”；`
+          + (available.length ? `可用字段：${available.join('、')}。` : '该文档没有可单独读取的标签字段，')
+          + '也可省略 section 并设置 mode="document" 读取全文。')
       }
       if (ranges.length > 1) {
         throw new ContractError('DOCUMENT_AMBIGUOUS',
@@ -883,10 +896,25 @@ export function readableRenderedLine(line, marker = 'L') {
     const escaped = speaker.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')
     text = text.replace(new RegExp(`^${escaped}\\s*[：:]\\s*`, 'u'), '')
   }
+  if (line.line_type === 'knowledge') text = readableWikiMarkup(text)
   return `${marker}${line.line_number} ${line.line_type || ''} ${speaker ? `${speaker}: ` : ''}${text}`
     .replace(/\s+$/u, '')
 }
 
+/**
+ * Wiki 资料用 <字段名>…</字段名> 分段；直接展示标签既占篇幅又像 HTML 残留。
+ * 只改写整行的字段标记，正文中的尖括号保持原样。
+ */
+function readableWikiMarkup(text) {
+  const trimmed = text.trim()
+  const inline = /^<([^<>/\s][^<>]{0,40})>([\s\S]*)<\/\1>$/u.exec(trimmed)
+  if (inline) return `${inline[1]}：${inline[2].trim()}`
+  const open = /^<([^<>/\s][^<>]{0,40})>$/u.exec(trimmed)
+  if (open) return `［${open[1]}］`
+  if (/^<\/[^<>]{1,40}>$/u.test(trimmed)) return ''
+  return text
+}
+
 function publicLine(line) {
   const speaker = String(line.speaker_raw || '').trim()
   let text = String(line.text || '')
@@ -927,7 +955,7 @@ export function projectReadPublic(value) {
       returned_lines: Number(value.page?.returned_lines || value.primary.lines?.length || 0),
       has_more: hasMore,
       continuation: hasMore && Number.isInteger(nextLine) && nextLine > 0
-        ? { ...shortLocator, mode: 'document', line: nextLine,
+        ? { ...shortLocator, mode: 'document', start_line: nextLine,
             ...(dataVersion ? { data_version: dataVersion } : {}) }
         : null,
     } }
@@ -1004,7 +1032,7 @@ export function projectReadPublic(value) {
     page: { returned_lines: Number(value.page?.returned || lines.length),
       has_more: Boolean(value.page?.has_more),
       continuation: value.page?.has_more
-        ? { ...continuationLocator, mode: 'document', line: Number(value.selection?.line_end) + 1,
+        ? { ...continuationLocator, mode: 'document', start_line: Number(value.selection?.line_end) + 1,
             data_version: String(value.data_version || '') }
         : null },
   }
@@ -1024,6 +1052,7 @@ export function renderRead(_args, value) {
   }
   const projected = projectReadPublic(value)
   const parts = []
+  if (projected.guidance) parts.push(projected.guidance)
   if (projected.primary) {
     const primary = projected.primary
     parts.push(`# ${primary.title}`)
@@ -1050,13 +1079,14 @@ export function renderRead(_args, value) {
         } else {
           groupEnd = line.line
         }
-        parts.push(readableRenderedLine({ line_number: line.line, line_type: line.line_type,
-          speaker_raw: line.speaker, text: line.text }))
+        const rendered = readableRenderedLine({ line_number: line.line, line_type: line.line_type,
+          speaker_raw: line.speaker, text: line.text })
+        parts.push(line.source_line_id ? `${rendered}〔${line.source_line_id}〕` : rendered)
       }
       finishGroup()
       if (primary.text) parts.push(primary.text)
       if (projected.page.has_more && projected.page.continuation) {
-        parts.push(`继续阅读：corpus_read(${JSON.stringify(projected.page.continuation)})`)
+        parts.push(`继续阅读：corpus_read(${JSON.stringify(compactContinuation(projected.page.continuation))})`)
       }
       return [{ type: 'text', text: parts.join('\n') }]
     }
@@ -1071,27 +1101,48 @@ export function renderRead(_args, value) {
           : `${range.line_start}-${range.line_end}`).join('、')
       parts.push(`复用上文：第 ${ranges} 行已在上方可见工具结果中；本次只展示尚未覆盖的行。`)
     }
+    let hiddenProvenance = 0
     for (const line of primary.lines || []) {
-      parts.push(readableRenderedLine({ line_number: line.line, line_type: line.line_type,
-        speaker_raw: line.speaker, text: line.text }))
+      if (primary.kind === 'local_document' && isProvenanceLine(line)) { hiddenProvenance += 1; continue }
+      const rendered = readableRenderedLine({ line_number: line.line, line_type: line.line_type,
+        speaker_raw: line.speaker, text: line.text })
+      // 溯源行号（终末地是 dlg_e12m5_6 这类对话 ID）跟着正文一起给出去，
+      // 引用才能被读者回查到具体那一句，而不只是一串行号。
+      parts.push(line.source_line_id ? `${rendered}〔${line.source_line_id}〕` : rendered)
     }
     if (primary.text) parts.push(primary.text)
+    if (hiddenProvenance) parts.push(`（已省略 ${hiddenProvenance} 行数据来源元信息，行号保持原样。）`)
     parts.push(`引用：${primary.citation}`)
     if (projected.page.has_more && projected.page.continuation) {
-      const next = projected.page.continuation
-      parts.push(`继续阅读《${primary.title}》，从第 ${next.line} 行开始。`)
+      const next = compactContinuation(projected.page.continuation)
+      parts.push(`继续阅读《${primary.title}》，从第 ${next.start_line} 行开始。`)
       if (next.stage_code && next.story_part) {
         parts.push(`调用：corpus_read(${JSON.stringify({ stage_code: next.stage_code,
-          story_part: next.story_part, mode: 'document', line: next.line,
+          story_part: next.story_part, mode: 'document', start_line: next.start_line,
           data_version: next.data_version })})`)
       } else if (next.record_name || next.material) {
-        parts.push(`调用：corpus_read(${JSON.stringify(next)})`)
+        parts.push(`调用：corpus_read(${JSON.stringify({ ...next, mode: 'document' })})`)
       } else {
         parts.push(`调用：corpus_read(${JSON.stringify({ title: String(next.title || ''),
-          mode: 'document', line: next.line, data_version: next.data_version })})`)
+          mode: 'document', start_line: next.start_line, data_version: next.data_version })})`)
       }
     }
     return [{ type: 'text', text: parts.join('\n') }]
   }
   return [{ type: 'text', text: '[corpus_read:error] 无法投影读取结果' }]
 }
+
+/** 续读调用只展示短版本号；index.js 接受 ≥8 位前缀并在执行前还原为完整版本。 */
+function compactContinuation(continuation) {
+  if (!continuation?.data_version) return continuation
+  return { ...continuation, data_version: shortDataVersion(continuation.data_version) }
+}
+
+/**
+ * 干员/角色资料由导出脚本写入的溯源行（数据表路径、记录 ID、解锁条件枚举）：
+ * 对阅读与引用都没有价值，却占档案约三成篇幅。只在非剧情、非 Wiki 资料中隐藏。
+ */
+const PROVENANCE_LINE = /^(?:角色 ?ID|来源|来源记录|解锁条件)[：:]\s*\S/u
+function isProvenanceLine(line) {
+  return !line.speaker && line.line_type !== 'dialogue' && PROVENANCE_LINE.test(String(line.text || '').trim())
+}

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')
 }