prts-terrarchive 0.2.2 → 0.2.4

package/skills/prts-investigation/SKILL.md

@@ -25,7 +25,7 @@ description: 在莱茵工作区延续或新建调查，筛选证据、整理线
 4. 及时 `update` 保存有价值的线索；同一判断更新已有 C 编号，新建省略 id、使用 client_key 暂名，后续以 created_ids 为准。引用的盒内材料会自动上板；无价值的 Agent 暂存材料可 stage/remove。
 5. 一条卡片表达一个关键点；title/summary 简短，背景和推导放 detail。只连接有意义的线索，重复判断用 merges 归并。事实标 observation，推断标 inference，未解问题标 question/unresolved。
 
-引用只用当前会话真实来源；quote 逐字复制实际返回的原文，去掉搜索高亮【】；行号必须落在已读范围。搜索命中、入架和用户收藏不等于原文已核验。验证失败时按 issues 的来源标题、clue_index 和 read_ranges 查来源或补读，不猜行号、不提交测试线索。
+引用只用当前会话真实来源；quote 逐字复制实际返回的原文，去掉搜索高亮⟦⟧；行号必须落在已读范围。搜索命中、入架和用户收藏不等于原文已核验。验证失败时按 issues 的来源标题、clue_index 和 read_ranges 查来源或补读，不猜行号、不提交测试线索。
 
 ## 发布与修订
 

package/skills/prts-investigation/references/board-guide.md

@@ -90,7 +90,7 @@ summary 用一句话写最重要的依据或结论，优先 25–60 个汉字；
 无来源的猜想不能伪装成原文证据。
 
 sources 只使用当前会话已登记的 ID。quote 必须逐字出自实际返回的文本；
-line_start/line_end 必须落在已读范围中。搜索命中不是已读原文，复制引文时不要带搜索高亮的【】。
+line_start/line_end 必须落在已读范围中。搜索命中不是已读原文，复制引文时不要带搜索高亮的⟦⟧。
 若校验失败，按 issues 中的 clue_index、source_title 和 read_ranges 定位；标题不是目标文档时先查来源目录，不能反复改行号。
 标题正确再按 read 指引补读，保留 source_id 与文档的对应关系。全半角兼容字符会还原成原文保存，其余改写不视为逐字引文。
 整批失败不会保存任何线索，也不会推进 revision。仅修正错误部分后重试，不要用“测试引文/测试”污染真实调查板。

package/skills/prts-retrieval/SKILL.md

@@ -21,6 +21,8 @@ description: 使用 PRTS.chat 本地与云端资料检索、核验并回答《
 - 情节过程、关系、动机或多资料综合：默认 `cloud_search` 发现候选；需要精确台词、说话人、行动或因果时，再用映射出的标题与行号做本地核验。
 - 云端不可用但本地足够时回退本地；工具故障不等于资料不存在。取得足够证据后停止。
 
+读取时，展示标题填写 `title`；`document_uid` 只能复制工具返回的 `doc_…` 定位，不能填写标题或自行构造。二者互斥。
+
 ## 证据和结论
 
 官方剧情原文适合支持台词、行动、场景与上下文判断；官方档案等结构化资料适合支持身份和设定；Wiki、实体资料和时间线适合概括、清单、导航与候选发现。整理性材料中带引号的句子不能自动视为核验过的原文。实质冲突时回读相关原文上下文，并说明差异。

package/skills/prts-retrieval/references/cloud-tools.md

@@ -8,6 +8,8 @@
 
 `evidence_policy="mixed"` 使用主站混合检索；`original_only` 只运行官方剧情原文向量路线。两者都不改变“最终结论应按来源层级表述”的要求。结果中的可读取标题与行号可直接交给 `corpus_read`。
 
+综合分析、人物经历、关系类问题不要设置 `options.search_intent` 或 `original_only`：它们会关闭档案、Wiki、图谱和年表。云端返回“没有可用材料”时，先去掉这两个字段用默认路线重试一次，仍无结果就改用 `corpus_search`；不要以相同参数反复调用。主站在 `single_sentence_search` 无材料时会自动改用默认路线重试一次，并在“警告”中注明；显式 `original_only` 不会被放宽。
+
 ## `cloud_inspect`
 
-只在截断、来源不清或召回异常时检查。优先查看 `selected_sources`、`answer_context`、`candidates`；`events` 和 `trace_steps` 用于诊断。通常由运行时关联最近请求，分页时原样复制整数 `next_cursor`。
+只在截断、来源不清或召回异常时检查。优先查看 `selected_sources`、`answer_context`、`candidates`；`events` 和 `trace_steps` 用于诊断。通常由运行时关联最近请求，分页时原样复制整数 `next_cursor`。不需要的过滤字段直接省略；`event_sequence_*` 从 1 开始，`event_time_*` 必须是带时区的 ISO 8601（如 `2025-01-01T08:00:00+08:00`）。

package/skills/prts-retrieval/references/local-tools.md

@@ -8,7 +8,7 @@
 - `resource_types`：两款游戏共用字段，但可选值不同。明日方舟使用 `story`、`operator_record`、`character_*`、`*_wiki` 等；终末地使用 `original_story`、`archive`、`knowledge`、`wiki`、`character_story`、`timeline`。不要跨模块套类型。
 - `content_types`：内容形式，终末地原文尤其适合用它区分对话、过场、广播、远程通讯、黑屏文字、环境对话和 SNS。
 - `collection_names`：统一的上级集合字段，可表示明日方舟活动或终末地任务/资料集合。
-- `character_names` 是资料归属；`speakers` 是亲口说话；`entity_names` 是正文或结构化关系中出现。
+- `character_names` 是资料归属；`speakers` 是亲口说话（自动展开已登记别名）；`entity_names` 是正文或结构化关系中出现。
 
 本地资料不包含云端图谱、向量候选和 Cleaner 结果；本地零命中不能推出云端也无结果。
 
@@ -16,9 +16,9 @@
 
 优先使用玩家可见的稳定定位器：
 
-- 明日方舟关卡用 `stage_code`；只有同一代号存在多篇时才加 `story_part`：`before`=行动前、`after`=行动后、`story`=纯剧情或幕间。
+- 明日方舟关卡用 `stage_code`；同一代号存在多篇时可加 `story_part`：`before`=行动前、`after`=行动后、`story`=纯剧情或幕间；省略时默认读行动前并提示其他篇。
 - 干员密录用 `character_name + record_name`；多段密录加 `segment`。
 - 角色官方资料用 `character_name + material`；双模块同名时加 `game`。
 - 整个明日方舟活动用 `activity_name + mode:"activity"`；终末地任务用 `collection_name + mode:"collection"`，可用 `content_types` 收窄表现形式。
 
-这些字段已足够时不要先搜索或拼完整标题。同名篇章或同名多合集会要求消歧：先搜索具体篇章，只在结果给出 `document_uid` 时原样复制。`document_uid` 会替代 `title`，不得同时提交两者；单篇用 `{document_uid, line}` 或 `{document_uid, mode:"document"}`，所属活动/任务通读用 `{document_uid, mode:"activity"}` 或 `{document_uid, mode:"collection"}`。不得自行选第一项，也不要把 `document_uid` 当作人物或剧情证据。搜索分页保留原条件并原样提交 `page.next_after`；全文和合集续页原样提交 `page.continuation`。around 读取的 `has_more=false` 只描述该次窗口，不能证明整篇或合集已结束。
+这些字段已足够时不要先搜索或拼完整标题。同名篇章或同名多合集会要求消歧：先搜索具体篇章，只在结果给出 `document_uid` 时原样复制。`document_uid` 会替代 `title`，不得同时提交两者；单篇用 `{document_uid, line}` 或 `{document_uid, mode:"document"}`，所属活动/任务通读用 `{document_uid, mode:"activity"}` 或 `{document_uid, mode:"collection"}`。不得自行选第一项，也不要把 `document_uid` 当作人物或剧情证据。搜索分页保留原条件并原样提交 `page.next_after`；全文和合集续页直接复制结果末尾给出的调用。around 读取的 `has_more=false` 只描述该次窗口，不能证明整篇或合集已结束。

package/skills/prts-retrieval/references/module-arknights.md

@@ -9,7 +9,7 @@
 - 整理资料：`character_wiki`、`story_wiki`、`character_activity_wiki`；确需跨 Wiki 搜索才用 `reviewed_wiki`。
 - 设定与导航：`terra_journey`、`entity_profile`、`reference`。
 
-`character_names` 是资料归属，`speakers` 是亲口说话，`entity_names` 是正文或结构化关系中出现；不同字段取交集。活动使用 `activity_names`，篇章使用 `story_names`，上级集合也可使用 `collection_names`。
+`character_names` 是资料归属，`speakers` 是亲口说话，`entity_names` 是正文或结构化关系中出现；不同字段取交集。活动或章节名（如“昨日海”）使用 `activity_names`，单关/单篇剧情名（如“鳞的记忆”）使用 `story_names`，上级集合也可使用 `collection_names`。`context_terms` 要求每个词都出现在命中行前后 3 行内，不是整篇共现，不确定时省略。
 
 常见路线：
 

package/skills/prts-retrieval/references/module-dual.md

@@ -10,6 +10,6 @@
 
 双模块检索涉及再旅者时，结果可能带 `retraveler_relations`。这是 PRTS 人工审校的关系登记，可以直接支持“某终末地再旅者登记的泰拉记忆原型是谁”这一有限结论，回答时注明资料性质。它不表示两者是同一个人物，也不能证明游戏剧情正式确认、共享记忆或其他未登记关系。用字段中的两个规范名分别检索两侧人物资料；附加字段缺失也不能反证不存在该关系。
 
-本地搜索返回的每篇资料都有 `game`。联合结果中至少检查两边是否都有命中；若出现 `CORPUS_GAME_NOT_INSTALLED` 或某侧无结果，只能给出已覆盖模块的部分结论并标明缺口。分页时保留原 `games` 和其他检索条件，并原样提交含完整 `data_version` 的 `next_after`；资料版本切换后重新搜索。
+本地搜索返回的每篇资料都有 `game`。联合结果中至少检查两边是否都有命中；若出现 `CORPUS_GAME_NOT_INSTALLED` 或某侧无结果，只能给出已覆盖模块的部分结论并标明缺口。分页时保留原 `games` 和其他检索条件，并原样提交 `next_after`（含短版本号 `data_version`）；资料版本切换后重新搜索。
 
 跨游戏推荐流程：先用完整问题联合 `cloud_search` 或窄字面联合 `corpus_search` 发现候选；再按游戏拆分读取和核验；最后区分“各自资料明示的事实”和“基于两侧事实作出的比较或推断”。

package/skills/prts-retrieval/references/module-endfield.md

@@ -2,12 +2,15 @@
 
 调用本地或云端检索时使用 `games:["endfield"]`，除非运行时上下文表明问题还涉及明日方舟。
 
+玩家询问“主线顺序”“最新主线”“1.6 主线”“丹青渡”“第二章第八进程”或某一段的前后剧情时，先用 `corpus_navigate({query:玩家给出的版本、章节或主线问法})`；省略 query 返回有序主线目录。它按来源支持的章、进程与任务层级定位，返回可直接传给 `corpus_read/corpus_search` 的参数，玩家无需知道“入丹青”等内部篇章名。最新只指当前资料覆盖的最新主线；查看返回的资料版本边界与映射状态。版本没有映射时不得推断该版本没有新增剧情。章/进程的顺序不等于任务内部全部对话碎片的先后。
+
 官方名称、原句或档案的跨语言对照使用 `corpus_i18n`，不必重新搜索目标语言剧情。已有标题/文档定位及行号时直接定位；只有原句时反查。同文可能有不同译法，必须保留来源语境；默认不请求内部文本 ID。
 
 终末地采用跨游戏统一类型，不要套用明日方舟干员资料类型：
 
 - `original_story`：官方剧情原文；可用 `content_types` 区分 `dialogue`、`cutscene`、`radio`、`remote_comm`、`black_screen`、`environment_talk`、`sns_topic`、`sns_chat`、`narration`。
 - `archive`：官方档案类资料。
+- `character_name` + `material`：**两款游戏通用**的官方角色资料直读。终末地的《管理员 / 角色档案》《佩丽卡 / 角色档案》这类，用 `character_name:"管理员"` + `material:"profile"` 直接读，不必先搜索；男女管理员正文相同时会自动选稳定的一份。
 - `knowledge`：知识与设定资料。
 - `wiki`：整理性 Wiki。
 - `character_story`：角色故事资料。

package/skills/prts-retrieval/references/tools-runtime.md

@@ -1,25 +1,35 @@
 # 当前工具契约
 
+## `corpus_navigate`
+
+终末地主线导航（明日方舟的时间位置用 `timeline_search`）。参数只有可选 `query` 和 `game:"endfield"`；省略 query 返回有序目录，不需要先知道任务名。支持“最新主线”“1.6 主线”“丹青渡”“第二章第八进程”及准确任务名。返回章/进程顺序、所属任务、前后主线，以及可直接提交给 `corpus_read` 的参数；任务元数据只展示 id/名称/类型等判别字段，来源 URL 与源文件路径保留在结构化结果中。版本映射与顺序带来源；最新仅表示当前安装资料覆盖的最新。缺少版本映射或本地正文时保留缺口提示。章/进程/任务顺序不代表任务内部所有原文碎片的严格时间顺序。目录不能充当台词证据，具体剧情仍读正文。
+
 ## `corpus_search`
 
 它是本地结构化字面检索，不接收完整研究问题。可用参数为 `query`、`games`、`resource_types`、`content_types`、`collection_names`、`character_names`、`story_names`、`activity_names`、`wiki_sections`、`entity_names`、`speakers`、`match_mode`、`context_terms`、`after`。
 
-同一数组内 OR，不同过滤字段间 AND。`query` 默认连续字面匹配；只有确需模式时才用受限 `regex`。省略 `query` 可按归属列目录；省略 `query` 且指定一个 Wiki 字段可返回完整字段。已有证据足以回答时停止；只有需要完整清单、确认零命中或当前页证据不足时才继续分页。续页保留原条件并把 `page.next_after` 原样放进 `after`；要证明搜索范围已穷尽则继续到 `page.exhausted=true`。`next_after` 含完整 `data_version`；资料版本切换后旧锚点会被拒绝，须从首屏重新搜索。
+同一数组内 OR，不同过滤字段间 AND。`query` 默认连续字面匹配；只有确需模式时才用受限 `regex`。省略 `query` 可按归属列目录；省略 `query` 且指定一个 Wiki 字段可返回完整字段。已有证据足以回答时停止；只有需要完整清单、确认零命中或当前页证据不足时才继续分页。续页保留原条件并把 `page.next_after` 原样放进 `after`；要证明搜索范围已穷尽则继续到 `page.exhausted=true`。`next_after` 带短版本号 `data_version`（前 12 位；至少 8 位前缀即可）；资料版本切换后旧锚点会被拒绝，须从首屏重新搜索。
+
+`speakers` 匹配亲口台词，会自动展开已登记别名（如 `银灰` 也匹配原文说话人 `恩希欧迪斯`）。`query` 只匹配台词正文，不含说话人名；从命中复制的 `说话人: 台词` 形式也能直接搜。命中行显示原文标点，命中片段以 `⟦⟧` 标出，引用时去掉 `⟦⟧`。目录型结果每篇附可直接执行的 `corpus_read` 调用。
 
 ## `corpus_read`
 
-- 明日方舟单篇关卡：`{stage_code:"TW-ST-1"}`；同代号存在多篇时加 `story_part:"before"|"after"|"story"`。提供 `line` 时读上下文，否则直接读全文首段。
+- 明日方舟单篇关卡：`{stage_code:"TW-ST-1"}`；同代号存在多篇且未给 `story_part` 时默认读行动前（无行动前则读幕间），结果开头说明其他篇的 `story_part`。提供 `line` 时读上下文，否则直接读全文首段。
 - 干员密录：`{character_name:"安洁莉娜", record_name:"没写收件人的包裹", segment:2}`；只有一段时可省略 `segment`。
 - 角色资料：`{character_name:"凯尔希", material:"profile"}`；`material` 支持 `profile/module/voice/skin/recruitment/potential`，双模块同名时加 `game`。
 - 明日方舟活动连续阅读：`{activity_name:"孤星", mode:"activity"}`。
-- 终末地任务连续阅读：`{collection_name:"武陵特厨", mode:"collection"}`；可加 `content_types`。
+- 终末地任务连续阅读：`{collection_name:"武陵特厨", mode:"collection"}`；可加 `content_types`。两款游戏的连续阅读是同一入口：`activity_name` 填了终末地任务名、或 `collection_name` 填了明日方舟活动名时，工具会自动改道并说明。
 - 其他资料定点上下文：`{title, line, before?, after?}`。
-- Wiki 字段：`{title, section}`。
-- 其他资料全文首段：`{title, mode:"document", max_lines?, max_chars?}`。
-- 搜索结果给出 `document_uid` 时表示标题同名：用它替代 `title`，两者不得同时提交；单篇用 `{document_uid, line}` 或 `{document_uid, mode:"document"}`。
-- 所有续读：原样提交结果的 `page.continuation`。单篇使用 `line`，活动/任务合集使用版本绑定的 `position`；可以另加 `max_lines/max_chars`。
+- Wiki 字段：`{title, section}` 或 `{document_uid, section}`；只读字段时省略 `mode`。
+- 其他资料全文首段：`{title}`（可加 `max_lines/max_chars`；`mode:"document"` 可省略）。
+- 标题不必一字不差：分隔符 `·`、空格、全半角差异和 Wiki 的“ · 第 N 篇”后缀可省略；唯一匹配时直接读取并在开头说明实际标题，多个候选或找不到时错误信息列出最接近的完整标题。
+- 搜索结果给出 `document_uid` 时表示标题同名：复制其 `doc_…` 值替代 `title`，不能把展示标题填入 `document_uid`，两者不得同时提交；单篇用 `{document_uid, line}` 或 `{document_uid, mode:"document"}`。
+- 所有续读：直接复制结果末尾给出的 `corpus_read(...)` 调用。单篇使用 `line`，活动/任务合集使用 `position`；`data_version` 为短版本号且可省略（省略时按当前版本读取），可以另加 `max_lines/max_chars`。
+- 角色资料中导出脚本写入的溯源行（数据表路径、记录 ID、解锁条件枚举）默认隐藏，行号保持原样；Wiki 的 `<字段>` 标签显示为 `字段：值` 或 `［字段］`。
 
-每次只选一种主定位方式：`title`、`document_uid`、`stage_code`（可带 `story_part`）、角色密录组合、角色资料组合、`activity_name` 或 `collection_name`。`max_lines/max_chars` 只限制输出量，不会选择读取方式；裸 `title` 不能只配这两个限制字段。
+每次只选一种主定位方式：`title`、`document_uid`、`stage_code`（可带 `story_part`）、角色密录组合、角色资料组合、`activity_name` 或 `collection_name`。`max_lines/max_chars` 只限制输出量，不会选择读取方式；裸 `title` 默认读取全文首段。
+
+直接复制导航/搜索返回的最小读取参数，不要填齐其他用途的字段。可选枚举允许空字符串，等同省略。`story_part` 依附 `stage_code`，`segment` 依附 `record_name`，`material` 依附 `character_name`；已明确唯一目标时，兼容清理已知孤立默认值并在结果中说明，真实的双重定位仍报错并列出最小重试参数。显式 `mode:"document"` 表示读取全文；误带的合法 `section` 不应用，并在结果提示。只读 Wiki 字段时保留 `section`，省略 `mode`。非默认的孤立修饰参数、非零的无效分页位置及过期版本仍严格校验。
 
 稳定定位字段已经足够时直接读取，不要先搜索标题。合集结果的每行都带所属篇章标题和篇内行号，应按它们引用。工具返回歧义时收窄条件，不能猜第一篇。新调用不要创建 cursor；旧会话已有 cursor 时才使用兼容入口。
 
@@ -29,9 +39,11 @@
 
 默认无需请求底层 ID。需要核验时才设 `include_ids:true`，返回的 `text_id` 必须当作字符串使用，后续可传 `text_ids`。同文不同译保留候选，按 references 中的篇章和中文定位消歧，不能任选第一个。每个结果最多列出 8 个引用；`reference_count` 表示总数。
 
-`alignment:"record"` 是整条角色档案，`alignment:"document"` 是档案库内容块；不保证各语言段落一一对应。引用注明工具返回的篇章、语言和中文定位，不能把中文第 N 行说成英文第 N 行。长文本按字符分块，`character_start/end` 是该语言自己的位置，不表示译文逐字符对应；续页原样提交 `page.continuation`。
+`alignment:"record"` 是整条角色档案，`alignment:"document"` 是档案库内容块；不保证各语言段落一一对应。引用注明工具返回的篇章、语言和中文定位，不能把中文第 N 行说成英文第 N 行。长文本按字符分块，`character_start/end` 是该语言自己的位置，不表示译文逐字符对应；续页直接复制结果末尾的 `corpus_i18n(...)` 调用（`after` 只需 `position/text_offset`，短 `data_version/request_hash` 用于校验，可省略）。
+
+结果以文本展示。按名称查询时，原文与所有请求语言译文完全相同的条目合并为一组，出处汇总为“共 N 处，示例”；只有译文确有不同才分成多组。
 
-`missing_localization` 表示该语言官方文本为空；`unmapped_source` 表示没有建立来源映射；`unavailable` 表示附件/语言未安装。均不能自行翻译后当成官方文本。旧资料包仍能正常搜索和阅读，但需要安装带本地化附件的版本才能使用此工具。
+`missing_localization`（显示为“该语言无对应译文”）表示该语言官方文本为空；`unmapped_source` 表示没有建立来源映射；`unavailable` 表示附件/语言未安装。均不能自行翻译后当成官方文本。旧资料包仍能正常搜索和阅读，但需要安装带本地化附件的版本才能使用此工具。
 
 ## `timeline_search`
 

package/src/cloud-projection.js

@@ -84,7 +84,22 @@ export function projectedAnchorPoints(mappings) {
   }))
 }
 
-export function projectCloudSearch(value) {
+/** 云端无材料时的恢复指引：说明路线并给出下一步，而不是返回空文本。 */
+export function emptyCloudSearchGuidance(args = {}, { routeFallback = false } = {}) {
+  const singleSentence = args?.options?.search_intent === 'single_sentence_search'
+  // 主站已自动改用默认路线仍无材料时，不再建议模型重复同一次回退。
+  const strict = !routeFallback && (singleSentence || args?.evidence_policy === 'original_only')
+  const route = singleSentence
+    ? 'options.search_intent=single_sentence_search（只检索官方原文的单句定位路线）'
+    : 'evidence_policy=original_only（只检索官方原文）'
+  return [
+    '云端检索没有返回可用材料（不代表资料中不存在）。',
+    strict ? `本次使用了 ${route}，档案、Wiki、图谱和年表均未参与。综合分析请去掉 options 和 evidence_policy，用默认 mixed 路线重试一次。` : '',
+    '也可以改用 corpus_search 以人物名、活动名或原句短片段在本地检索；不要用相同参数重复调用。',
+  ].filter(Boolean).join('\n')
+}
+
+export function projectCloudSearch(value, { args } = {}) {
   const data = value?.data || {}
   const mappings = value?.local_source_mappings || []
   const sources = addSourceAnchors(data.sources || data.selected_sources || [], anchorIndex(mappings))
@@ -105,7 +120,13 @@ export function projectCloudSearch(value) {
       `状态：${item.relation_status}。这是跨游戏关系，不是人物别名。`)
   const warnings = [...(data.errors || []),
     ...(value?.local_source_mapping_warning ? [value.local_source_mapping_warning] : [])]
-  return [answerContext.trim(), relationLines.length
+  // 只有警告或跨游戏关系、没有回答材料和原文定位时，同样视为“无材料”并给出下一步。
+  // 仅面向模型的渲染传入 args；证据板等用户侧展示不混入操作提示。
+  const guidance = args && !answerContext.trim() && !anchorLines.length
+    ? emptyCloudSearchGuidance(args, {
+      routeFallback: (data.errors || []).some((item) => item?.stage === 'route_fallback'),
+    }) : ''
+  return [answerContext.trim(), guidance, relationLines.length
     ? `## 再旅者对应关系（人工审校附属字段）\n${relationLines.join('\n')}` : '',
   anchorLines.length ? `## 可读取原文\n${anchorLines.join('\n')}` : '',
     warnings.length ? `## 警告\n${warnings.map((item) => item.message || item).join('\n')}` : '']

package/src/cloud.js

@@ -496,3 +496,27 @@ export function cloudErrorResponse(error) {
   return { contract_version: CLOUD_CONTRACT_VERSION, status: 'error',
     error: { code: 'CLOUD_INTERNAL_ERROR', message: '云端检索执行失败；详情请查看 DSH Host 日志', retryable: false } }
 }
+
+const CLOUD_RECOVERY_HINTS = Object.freeze({
+  INVALID_REQUEST: '请按提示修正或删除对应字段；不确定的可选字段直接省略，不要填空字符串、空数组或 0。',
+  TRACE_NOT_FOUND: '没有可检查的云端检索记录，请先成功调用 cloud_search。',
+  CLOUD_BUSY: '云端繁忙，可稍后重试一次，或改用 corpus_search 本地检索。',
+  CLOUD_TIMEOUT: '可稍后重试一次，或改用 corpus_search 本地检索。',
+  CLOUD_UNAVAILABLE: '云端暂不可用，请改用 corpus_search / corpus_read 本地检索。',
+})
+
+/**
+ * 工具执行层：把云端失败转换成可抛出的 Error，交由宿主标记 isError。
+ * 消息带上错误码和恢复指引；未知内部异常仍只暴露通用说明。
+ */
+export function cloudFaultError(error, toolName = 'cloud') {
+  if (error?.name === 'AbortError' || error?.code === 'CANCELLED') return error
+  const known = error instanceof CloudFault
+    || (error?.code === 'INVALID_REQUEST' && typeof error?.message === 'string')
+  const { code, message, retryable, details } = known
+    ? { code: error.code, message: error.message, retryable: Boolean(error.retryable), details: error.details }
+    : cloudErrorResponse(error).error
+  const hint = CLOUD_RECOVERY_HINTS[code] || (retryable ? '可稍后重试一次。' : '')
+  return Object.assign(new Error(`[${toolName}:${code}] ${message}${hint ? `\n${hint}` : ''}`),
+    { code, retryable, ...(details ? { details } : {}), cause: error })
+}

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,7 +23,7 @@ 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 = '查询终末地官方本地化原文。query/title/document_uid/text_ids 四选一；同文异译按来源消歧，中文行号不是译文行号。续页原样提交 page.continuation。'
+export const I18N_DESCRIPTION = '查询终末地官方本地化原文。query/title/document_uid/text_ids 四选一；同文异译按来源消歧，中文行号不是译文行号。续页原样提交返回的“续页”调用。原文与各语言译文完全相同的条目会合并为一组并汇总出处。'
 
 export const I18N_PARAMETERS = {
   type: 'object', additionalProperties: false, required: ['languages'],
@@ -40,9 +40,9 @@ export const I18N_PARAMETERS = {
     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: '原样复制 page.continuation.after' },
@@ -119,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,
@@ -254,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
@@ -319,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', '续页位置超出查询结果')
@@ -334,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 } : {}) })
@@ -349,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') }]
 }