prts-terrarchive 0.2.1 → 0.2.3

package/src/entity-recognizer.js

@@ -96,7 +96,7 @@ export class EntityAliasAutomaton {
         // 单字别名在普通句子中误报率过高；仅当整个输入就是该字时保留。
         if (output.length === 1 && characters.length > 1) continue
         found.push({ canonical: output.canonical, alias: output.alias, games: output.games,
-          start, end: index + 1 })
+          curated: Boolean(this.curated?.has(normalized(output.alias))), start, end: index + 1 })
       }
     }
     found.sort((left, right) => left.start - right.start
@@ -130,6 +130,7 @@ export async function prepareEntityRecognition(store, { signal } = {}) {
         }
         store._aliasGroups ||= groups
         state.automaton = new EntityAliasAutomaton(groups)
+        state.automaton.curated = store._curatedAliases || new Set()
         return state.automaton
       })
       .catch((error) => {
@@ -159,7 +160,7 @@ export function createEntityRecognizer(store) {
       if (signal?.aborted) throw cancelledError()
       const catalog = await loadEntityRelationCatalog(store)
       if (signal?.aborted) throw cancelledError()
-      return detectEntities(automaton, catalog, text)
+      return withAliasConflicts(store, detectEntities(automaton, catalog, text), text)
     }
   }
 }
@@ -186,13 +187,26 @@ function detectEntities(automaton, catalog, text) {
     relation_hints: relationHints }
 }
 
+/** 本轮问题里出现的冲突别名字面：不做实体归属，只在上下文里点出数据缺陷。 */
+function aliasConflictNotes(store, text) {
+  const conflicts = store?._aliasConflicts
+  if (!conflicts?.length) return []
+  const normalizedText = normalized(text)
+  return conflicts.filter((item) => normalizedText.includes(normalized(item.alias)))
+}
+
+function withAliasConflicts(store, result, text) {
+  const conflicts = aliasConflictNotes(store, text)
+  return conflicts.length ? { ...result, alias_conflicts: conflicts } : result
+}
+
 /** 仅在后台预热已经完成时同步识别；prompt assembly 不能等待异步 I/O。 */
 function detectPreparedEntities(store, text) {
   const state = preparedRecognizers.get(store)
   const catalog = store?._endfieldRelationCatalog
   if (!store?.loaded || !state?.automaton || state.dataVersion !== store.dataVersion
       || catalog?.dataVersion !== store.dataVersion) return null
-  return detectEntities(state.automaton, catalog.value, text)
+  return withAliasConflicts(store, detectEntities(state.automaton, catalog.value, text), text)
 }
 
 function messageText(message) {
@@ -204,8 +218,9 @@ function messageText(message) {
 function recognitionContext(result, enabledGames) {
   const aliases = new Map()
   for (const match of result.matches) {
-    const value = aliases.get(match.canonical) || { aliases: new Set(), games: new Set() }
+    const value = aliases.get(match.canonical) || { aliases: new Set(), games: new Set(), curated: false }
     value.aliases.add(match.alias)
+    if (match.curated) value.curated = true
     for (const game of match.games || []) value.games.add(game)
     aliases.set(match.canonical, value)
   }
@@ -226,19 +241,23 @@ function recognitionContext(result, enabledGames) {
   }
   const lines = [...aliases].map(([canonical, value]) => {
     const ownership = [...value.games].map((game) => GAME_LABELS[game]).filter(Boolean)
+    const basis = value.curated ? ' · 依据：人工别名表' : ''
     return `- ${promptData(canonical)} — ${ownership.length ? ownership.join(' + ') : '归属未确定'}` +
-      `（问题中命中：${[...value.aliases].map((alias) => promptData(alias)).join('、')}）`
+      `（问题中命中：${[...value.aliases].map((alias) => promptData(alias)).join('、')}${basis}）`
   })
   const enabled = enabledGames.map((game) => GAME_LABELS[game]).filter(Boolean)
   const relationLines = (result.relation_hints || []).map((hint) =>
     hint.kind === 'retraveler_memory_prototype'
       ? `- ${promptData(hint.endfield_name)}：再旅者；泰拉记忆原型=${promptData(hint.terra_memory_prototype || '未登记')}。检索词：${(Array.isArray(hint.query_terms) ? hint.query_terms : []).map((term) => promptData(term)).join('、')}。两者不是别名。`
       : `- ${promptData(hint.endfield_name)} / ${promptData(hint.arknights_name)}：仅登记外观相似；现有剧情没有关系证据，不得推断为再旅者或记忆原型。`)
+  const conflictLines = (result.alias_conflicts || []).map((item) =>
+    `- 别名冲突：${promptData(item.alias)} 同时被 ${item.canonicals.map((name) => promptData(name)).join('、')} 声明为别名。本轮已忽略该别名、不归属任何实体；需要这些实体时请直呼规范名或分别检索。`)
   return [
     '<prts:retrieval-context>',
     `当前搭载资料：${enabled.join('、') || '无'}。`,
     ...(lines.length ? ['用户问题中识别到的规范实体与游戏归属：', ...lines] : []),
     ...relationLines,
+    ...conflictLines,
     '</prts:retrieval-context>',
   ].join('\n')
 }
@@ -302,6 +321,8 @@ export function applyEntityRecognition(ctx, store, shared = null) {
   ctx.systemPrompt.context({
     name: 'prts-terrarchive:retrieval-entities',
     order: 1000,
+    // Recognized entity names are user content: never resolve {{name}} in them.
+    interpolate: false,
     text: ({ scope }) => {
       const state = turns.get(scope)
       return state?.context && hasVisibleRetrievalSkill(scope, []) ? state.context : ''

package/src/entity-routing.js

@@ -30,8 +30,11 @@ function mergeRelationCatalog(fallback, installed) {
 /** 资料包内关系表优先，插件内置表只为旧包提供最小兼容路由。 */
 export async function loadEntityRelationCatalog(store) {
   const dataVersion = store?.dataVersion ?? 'no-store'
+  const scopeFingerprint = store?.scopeFingerprint ?? null
+  const installationId = store?.installationId ?? null
   const cached = store?._endfieldRelationCatalog
-  if (cached?.dataVersion === dataVersion) return cached.value
+  if (cached?.dataVersion === dataVersion && cached.scopeFingerprint === scopeFingerprint
+      && cached.installationId === installationId) return cached.value
   let installed = {}
   try {
     const loaded = await store?.getDocumentByPath?.('config/retravelers.json')
@@ -39,7 +42,7 @@ export async function loadEntityRelationCatalog(store) {
     installed = JSON.parse((record?.lines || []).map((line) => line.text).join('\n') || '{}')
   } catch { installed = {} }
   const value = mergeRelationCatalog(await bundledRelations(), installed)
-  if (store) store._endfieldRelationCatalog = { dataVersion, value }
+  if (store) store._endfieldRelationCatalog = { dataVersion, scopeFingerprint, installationId, value }
   return value
 }
 
@@ -72,11 +75,22 @@ export function relevantRetravelerRelations(catalog, ...values) {
   }))
 }
 
-/** 仅双模块启用时，把人工审校关系作为独立附属字段挂到检索结果。 */
+/**
+ * 仅双模块启用、且本次请求本身覆盖两款游戏时，把人工审校关系作为独立附属字段挂到
+ * 检索结果。只按请求参数与命中文档标题判断相关性：命中正文里顺带出现某个名字
+ * （如语音里提到“艾雅法拉”）不代表用户在问跨游戏关系，挂上只会制造噪声。
+ */
 export async function attachRetravelerRelations(store, response, request, enabledGames) {
   if (!enabledGames?.includes('arknights') || !enabledGames?.includes('endfield')
       || response?.status === 'error' || response?.error) return response
+  const requestedGames = Array.isArray(request?.games) && request.games.length ? request.games : null
+  if (requestedGames && !(requestedGames.includes('arknights') && requestedGames.includes('endfield'))) {
+    return response
+  }
   const catalog = await loadEntityRelationCatalog(store)
-  const relations = relevantRetravelerRelations(catalog, request, response?.documents)
+  const { after: _after, cursor: _cursor, ...requestFields } = request || {}
+  const titles = (Array.isArray(response?.documents) ? response.documents : [])
+    .map((document) => document?.title).filter(Boolean)
+  const relations = relevantRetravelerRelations(catalog, requestFields, titles)
   return relations.length ? { ...response, retraveler_relations: relations } : response
 }

package/src/evidence-state.js

@@ -293,7 +293,8 @@ export function replayCoveredRead(state, requested, contract) {
     stats: { elapsed_ms: 0, scanned_documents: 0, scanned_lines: 0, returned_chars: 0,
       estimated_input_tokens: 0, truncated: hasMore, reused_local_evidence: true },
     warnings: [],
-    guidance: '该范围已在当前模型可见的上文工具结果中完整出现；这里复用已核验的本地原文，不要再次读取相同范围。',
+    guidance: '该范围已在当前模型可见的上文工具结果中完整出现；这里复用已核验的本地原文，不要再次读取相同范围。'
+      + '若上文其实已经看不到这些行（被压缩或折叠），传 reuse:false 重发本页全文。',
   }
 }
 
@@ -327,6 +328,7 @@ export function reuseReadCoverage(response, plan) {
     },
     warnings: [...(response.warnings || []), { code: 'PARTIAL_READ_REUSED',
       message: `本页已有 ${plan.reusedRanges.length} 段经过核验，本次只返回新读取行。` }],
-    guidance: '本页与当前模型可见的上文原文部分重叠；这里只返回新读取行，coverage.reused_ranges 对应旧行就在上方可见工具结果中。',
+    guidance: '本页与当前模型可见的上文原文部分重叠；这里只返回新读取行，coverage.reused_ranges 对应旧行就在上方可见工具结果中。'
+      + '若上文其实已经看不到这些行（被压缩或折叠），传 reuse:false 重发本页全文。',
   }
 }

package/src/i18n.js

@@ -1,7 +1,7 @@
 /** Official localizations: exact source identities, independent of reading coverage. */
 import { createHash } from 'node:crypto'
 import { assertCorpusVersion, corpusVersionSnapshot, documentGame, documentUid,
-  naturalDocumentTitle } from './store.js'
+  naturalDocumentTitle, DATA_VERSION_REF_PATTERN, dataVersionMatches, shortDataVersion } from './store.js'
 import { LOCALIZATION_LANGUAGES } from './localization-format.js'
 
 const PACK = 'endfield_official_game'
@@ -23,35 +23,29 @@ for (const [locale, code] of Object.entries({ 'en-us': 'EN', 'ja-jp': 'JP', 'ko-
 const fault = (code, message) => Object.assign(new Error(message), { code,
   retryable: code === 'PACKAGE_VERSION_MISMATCH' })
 
-export const I18N_DESCRIPTION = [
-  '查询终末地官方本地化文本，返回其他语言原文；不生成翻译。',
-  '已有资料时优先使用完整 title 或 document_uid，可加 line；只有原句/名称时用 query 反查，source_language 默认 CN。',
-  'languages 指定目标语言（EN 英语、JP 日语、KR 韩语、TC 繁中等）。query 默认 exact，片段用 match_mode=literal。',
-  '相同原文可能对应多个不同译文，按来源消歧。角色档案按整条记录、档案库按整篇内容块对齐，中文行号不是目标语言行号。',
-  '默认不显示内部文本 ID；仅核验时 include_ids=true，后续可用 text_ids 精确查询。续页原样提交 page.continuation。',
-].join(' ')
+export const I18N_DESCRIPTION = '查询终末地官方本地化原文。query/title/document_uid/text_ids 四选一；同文异译按来源消歧，中文行号不是译文行号。续页原样提交返回的“续页”调用。原文与各语言译文完全相同的条目会合并为一组并汇总出处。'
 
 export const I18N_PARAMETERS = {
   type: 'object', additionalProperties: false, required: ['languages'],
   properties: {
     game: { type: 'string', enum: ['endfield'], description: '当前支持终末地官方资料' },
-    query: { type: 'string', description: '名称或原句；仅有片段时使用 match_mode=literal' },
-    title: { type: 'string', description: '已有检索结果的完整篇章标题，与 query/document_uid/text_ids 四选一' },
-    document_uid: { type: 'string', description: '已有检索结果的文档定位，替代 title' },
-    line: { type: 'integer', description: '已有中文结果中的行号，只用于定位对应文本/记录' },
-    text_ids: { type: 'array', items: { type: 'string' }, description: '显式请求 ID 后可用于精确复查；普通查询不需要' },
-    source_language: { type: 'string', description: '原句的语言，默认 CN；也接受 en/ja/ko/zh-CN 等标准代码' },
+    query: { type: 'string', description: '名称或原句' },
+    title: { type: 'string', description: '已有结果的完整篇章标题' },
+    document_uid: { type: 'string', description: '已有结果的文档定位' },
+    line: { type: 'integer', description: '已有中文结果中的行号' },
+    text_ids: { type: 'array', items: { type: 'string' }, description: '返回的文本 ID 字符串，用于精确复查' },
+    source_language: { type: 'string', description: '原句语言，默认 CN；支持 en/ja/ko/zh-CN 等代码' },
     languages: { type: 'array', items: { type: 'string' }, description: '1–4 种目标语言：CN/EN/JP/KR/TC/MX/BR/FR/DE/RU/IT/ID/TH/VN' },
-    match_mode: { type: 'string', enum: ['exact', 'literal'], description: '原句精确匹配或字面量片段搜索，默认 exact' },
-    include_ids: { type: 'boolean', description: '默认 false；仅调试、核验或精确复查时返回内部文本 ID 与来源字段' },
+    match_mode: { type: 'string', enum: ['exact', 'literal'], description: '默认 exact 精确匹配；片段用 literal' },
+    include_ids: { type: 'boolean', description: '核验时返回内部 ID，默认 false' },
     max_matches: { type: 'integer', description: '每页候选数，默认 5，最多 20' },
     max_chars: { type: 'integer', description: '每页原文和译文的字符预算，默认 16000，范围 1000–48000' },
-    data_version: { type: 'string', description: '绑定已有结果的资料版本，避免混用版本' },
+    data_version: { type: 'string', description: '已有结果的资料版本（可省略；续页给出的短版本号即可）' },
     after: { type: 'object', additionalProperties: false,
-      required: ['data_version', 'request_hash', 'position', 'text_offset'],
+      required: ['position', 'text_offset'],
       properties: { data_version: { type: 'string' }, request_hash: { type: 'string' },
         position: { type: 'integer' }, text_offset: { type: 'integer' } },
-      description: '仅原样提交工具返回的续页位置；长记录会明确分块返回' },
+      description: '原样复制 page.continuation.after' },
   },
 }
 
@@ -125,14 +119,15 @@ export function normalizeI18nRequest(args) {
   request.max_matches = integer(args.max_matches ?? 5, 1, 20, 'max_matches')
   request.max_chars = integer(args.max_chars ?? 16000, 1000, 48000, 'max_chars')
   if (args.data_version !== undefined) {
-    if (typeof args.data_version !== 'string' || !/^[0-9a-f]{64}$/u.test(args.data_version)) throw fault('INVALID_REQUEST', 'data_version 必须是有效的 SHA-256')
+    if (typeof args.data_version !== 'string' || !DATA_VERSION_REF_PATTERN.test(args.data_version)) throw fault('INVALID_REQUEST', 'data_version 必须是续页给出的资料版本（至少 8 位十六进制）')
     request.data_version = args.data_version
   }
   if (args.after !== undefined) {
     const after = args.after
     if (!after || typeof after !== 'object' || Array.isArray(after)
-        || Object.keys(after).sort().join() !== 'data_version,position,request_hash,text_offset'
-        || !/^[0-9a-f]{64}$/u.test(after.data_version) || !/^[0-9a-f]{64}$/u.test(after.request_hash)) {
+        || Object.keys(after).some((key) => !['data_version', 'position', 'request_hash', 'text_offset'].includes(key))
+        || (after.data_version !== undefined && !DATA_VERSION_REF_PATTERN.test(String(after.data_version)))
+        || (after.request_hash !== undefined && !/^[0-9a-f]{8,64}$/u.test(String(after.request_hash)))) {
       throw fault('INVALID_REQUEST', 'after 必须原样使用工具返回的续页位置')
     }
     request.after = { ...after,
@@ -260,13 +255,13 @@ export async function executeI18n(store, raw, { signal, enabledGames = ['endfiel
   await store.ready()
   const snapshot = corpusVersionSnapshot(store)
   checkpoint(store, snapshot, signal)
-  if ((request.data_version && request.data_version !== snapshot.dataVersion)
-      || (request.after && request.after.data_version !== snapshot.dataVersion)) {
+  if ((request.data_version && !dataVersionMatches(request.data_version, snapshot.dataVersion))
+      || (request.after?.data_version && !dataVersionMatches(request.after.data_version, snapshot.dataVersion))) {
     throw fault('PACKAGE_VERSION_MISMATCH', '本地化查询所属资料版本已变化，请重新查询')
   }
   const { after, data_version: _version, ...identity } = request
   const requestHash = sha256(JSON.stringify(identity))
-  if (after && after.request_hash !== requestHash) throw fault('INVALID_REQUEST', '续页参数与原查询不一致')
+  if (after?.request_hash && !requestHash.startsWith(after.request_hash)) throw fault('INVALID_REQUEST', '续页参数与原查询不一致')
   const base = { game: 'endfield', data_version: snapshot.dataVersion,
     source_language: request.source_language, languages: request.languages }
   const pack = store.packs.get(PACK), meta = pack?.localization
@@ -325,6 +320,19 @@ export async function executeI18n(store, raw, { signal, enabledGames = ['endfiel
       return a[0] - b[0] || a[1] - b[1] || a[2].localeCompare(b[2], 'en', { numeric: true })
     })
   }
+  // 按名称查询时同一译名常对应上千个文本 ID（每段对话的说话人字段各一份）；原文与所有
+  // 请求语言完全一致的条目合并为一组，出处汇总到代表条目，避免逐页翻同一个译名。
+  const groupMembers = new Map()
+  if (request.query && ids.length > 1) {
+    const bySignature = new Map()
+    for (const id of ids) {
+      const signature = JSON.stringify(requestedLanguages.map((lang) => dictionaries.get(lang)?.byId.get(id) ?? null))
+      const representative = bySignature.get(signature)
+      if (representative === undefined) { bySignature.set(signature, id); groupMembers.set(id, [id]) }
+      else groupMembers.get(representative).push(id)
+    }
+    ids = [...groupMembers.keys()]
+  }
   // Preserve source/catalog order for document reads and deterministic query pages.
   let position = after?.position ?? 0, offset = after?.text_offset ?? 0
   if (position > ids.length || (position === ids.length && offset)) throw fault('INVALID_REQUEST', '续页位置超出查询结果')
@@ -340,8 +348,11 @@ export async function executeI18n(store, raw, { signal, enabledGames = ['endfiel
     const values = [sourceValue, ...Object.values(translations)]
     const maximumLength = Math.max(...requestedLanguages.map((lang) => [...(dictionaries.get(lang)?.byId.get(id) || '')].length))
     if (offset && offset >= maximumLength) throw fault('INVALID_REQUEST', '记录续页偏移超出正文')
-    const refs = entry.references.filter((ref) => !documentId || ref.document_id === documentId)
+    const members = groupMembers.get(id) || [id]
+    const refs = members.flatMap((member) => catalog.byId.get(member).references)
+      .filter((ref) => !documentId || ref.document_id === documentId)
     matches.push({ source: { language: request.source_language, ...sourceValue }, translations,
+      ...(members.length > 1 ? { merged_text_count: members.length } : {}),
       references: refs.slice(0, 8).map((ref) => publicReference(store, ref)), reference_count: refs.length,
       ...(request.include_ids ? { text_id: id, source_fields: entry.sources.slice(0, 8),
         source_field_count: entry.sources.length } : {}) })
@@ -355,11 +366,49 @@ export async function executeI18n(store, raw, { signal, enabledGames = ['endfiel
     matches, total_matches: ids.length,
     ...(request.text_ids ? { missing_text_ids: request.text_ids.filter((id) => !catalog.byId.has(id)) } : {}),
     note: '返回官方本地化原文；引用请注明语言。中文行号仅用于定位，record/document 对齐不表示跨语言逐行对应。',
-    page: { has_more: hasMore, continuation: hasMore ? { ...identity,
-      data_version: snapshot.dataVersion, after: { data_version: snapshot.dataVersion,
-        request_hash: requestHash, position, text_offset: offset } } : null } }
+    page: { has_more: hasMore, continuation: hasMore ? { ...compactIdentity(identity),
+      after: { data_version: shortDataVersion(snapshot.dataVersion),
+        request_hash: requestHash.slice(0, 12), position, text_offset: offset } } : null } }
+}
+
+/** 续页调用只保留用户实际给出的参数，默认值不重复回显。 */
+function compactIdentity(identity) {
+  const defaults = { source_language: 'CN', match_mode: 'exact', include_ids: false, max_matches: 5, max_chars: 16000 }
+  return Object.fromEntries(Object.entries(identity).filter(([key, value]) =>
+    value !== undefined && value !== null && defaults[key] !== value))
 }
 
+function renderValue(value) {
+  if (!value) return '（无）'
+  if (value.status === 'unavailable') return '（未安装该语言）'
+  if (value.status === 'missing_localization') return '（该语言无对应译文）'
+  const range = value.truncated || value.character_start
+    ? ` 〔第 ${value.character_start + 1}–${value.character_end} 字 / 共 ${value.total_characters} 字〕` : ''
+  return `${value.text}${range}`
+}
+
+/** 文本投影：与其他检索工具一致，按条目分块展示原文、译文与出处，不直接回显 JSON。 */
 export function renderI18n(_args, value) {
-  return [{ type: 'text', text: JSON.stringify(value) }]
+  if (!value || typeof value !== 'object') return [{ type: 'text', text: '[corpus_i18n:error] 无法投影本地化结果' }]
+  const lines = [`# 终末地官方本地化（${value.game_version || '版本未知'}）：${value.source_language} → ${(value.languages || []).join('/')}`]
+  if (value.status !== 'ok') {
+    lines.push(value.message || (value.status === 'not_found'
+      ? '未找到匹配原文。名称默认 exact 精确匹配整条文本；片段请设 match_mode="literal"。本工具只收录终末地官方本地化，明日方舟文本不在范围内。'
+      : value.status === 'unmapped_source' ? '该定位没有可对齐的本地化文本。' : `状态：${value.status}`))
+  }
+  if (value.total_matches) {
+    const raw = value.matches.reduce((sum, match) => sum + (match.merged_text_count || 1), 0)
+    lines.push(`共 ${value.total_matches} 组不同原文/译文${raw > value.matches.length ? `；本页 ${value.matches.length} 组合并自 ${raw} 条同文文本` : ''}。`)
+  }
+  value.matches.forEach((match, index) => {
+    lines.push('', `${index + 1}. ${match.source.language}：${renderValue(match.source)}`)
+    for (const [lang, translation] of Object.entries(match.translations || {})) lines.push(`   ${lang}：${renderValue(translation)}`)
+    const refs = (match.references || []).slice(0, 3).map((ref) => ref.citation)
+    if (refs.length) lines.push(`   出处${match.reference_count > refs.length ? `（共 ${match.reference_count} 处，示例）` : ''}：${refs.join('；')}`)
+    if (match.text_id) lines.push(`   text_id=${match.text_id}`)
+  })
+  if (value.missing_text_ids?.length) lines.push(`未找到的 text_ids：${value.missing_text_ids.join('、')}`)
+  if (value.note) lines.push('', value.note)
+  if (value.page?.has_more && value.page.continuation) lines.push(`续页：corpus_i18n(${JSON.stringify(value.page.continuation)})`)
+  return [{ type: 'text', text: lines.join('\n') }]
 }