prts-terrarchive 0.2.2 → 0.2.3

package/src/index.js

@@ -30,17 +30,21 @@ import { createHash } from 'node:crypto'
 import { mkdir, realpath } from 'node:fs/promises'
 import { assertCorpusVersion, corpusVersionSnapshot,
   CorpusStore, documentGame, documentUid, naturalDocumentTitle, publicStoryStageCode,
-  publicStoryPart } from './store.js'
+  publicStoryPart, DATA_VERSION_REF_PATTERN, dataVersionMatches } from './store.js'
 import { readCurrentReleasePointer } from './installer.js'
 import { watchCurrentRelease } from './release-watch.js'
 import { END_FIELD_STORY_CONTENT_TYPES, executeRead, readContractFromCursor,
   normalizeReadRequest, projectReadPublic, renderRead } from './read.js'
 import { executeSearch, renderSearch } from './search.js'
+import { executeNavigation, NAVIGATION_DESCRIPTION, NAVIGATION_PARAMETERS, renderNavigation } from './navigation.js'
 import { executeI18n, I18N_DESCRIPTION, I18N_PARAMETERS, I18N_OUTPUT_SCHEMA, renderI18n } from './i18n.js'
 import { executeTimelineSearch, renderTimeline } from './timeline.js'
 import { AnonymousSessionProvider, CloudRetrievalClient, StaticTokenProvider,
   createAgentCloudClientRegistry,
-  cloudErrorResponse, readOrCreateClientId } from './cloud.js'
+  cloudFaultError, readOrCreateClientId } from './cloud.js'
+import { dropEmptyPlaceholders } from './tool-args.js'
+import { formatCitation, normalizeReadArguments, parseCitation, readTargets,
+  readTargetError, withReadGuidance } from './read-args.js'
 import { createSharedState } from './state.js'
 import { applyUi } from './ui.js'
 import { acquireInvestigationStore } from './investigation-store.js'
@@ -66,7 +70,6 @@ const storesByDirectory = new Map()
 
 const LOCAL_CORPUS_MISSING_MESSAGE =
   '本地数据包暂未安装，请提醒用户前往“设置 → 插件 → PRTS 语料”安装。'
-const DATA_VERSION_PATTERN = /^[0-9a-f]{64}$/
 
 function sameFilesystemPath(left, right) {
   return process.platform === 'win32'
@@ -110,9 +113,9 @@ async function requireLocalCorpus(store) {
   }
 }
 
-const READ_DESCRIPTION = '读取 PRTS.chat 本地资料，支持行号上下文、Wiki 字段和单篇/合集连续阅读。只选一种主定位方式；续页原样提交 page.continuation。'
+const READ_DESCRIPTION = '读取 PRTS.chat 本地资料，支持行号上下文、Wiki 字段和单篇/合集连续阅读。只选一种主定位方式；续页原样提交 page.continuation。最小 UID 全文调用：{"document_uid":"检索返回的 doc_ 定位","mode":"document"}；不要填写不适用的附属参数。'
 
-const SEARCH_DESCRIPTION = '搜索 PRTS.chat 本地语料，返回按文档归并的命中行及上下各一行；省略 query 可列目录。过滤数组内 OR、字段间 AND。'
+const SEARCH_DESCRIPTION = '搜索 PRTS.chat 本地语料，返回按文档归并的命中行及上下各一行；省略 query 可列目录。过滤数组内 OR、字段间 AND。终末地版本、最新主线与章节顺序先用 corpus_navigate 定位。'
 
 const TIMELINE_DESCRIPTION = '检索明日方舟活动时间线（PRTS Wiki《泰拉年表》），返回年份、事件与可反查的出处标记。'
 
@@ -177,16 +180,16 @@ const SEARCH_PARAMETERS = {
       description: '内容形式' },
     collection_names: stringList('活动或任务等上级集合展示名'),
     character_names: stringList('资料归属角色的展示名'),
-    story_names: stringList('剧情篇章展示名'),
-    activity_names: stringList('活动展示名'),
+    story_names: stringList('单关/单篇剧情名，如“鳞的记忆”；活动名不要填这里，改用 activity_names'),
+    activity_names: stringList('活动或主线章节名，如“昨日海”'),
     wiki_sections: { type: 'array', items: { type: 'string', enum: WIKI_SECTION_VALUES },
       description: '限定 Wiki 标签字段' },
     entity_names: stringList('只返回出现指定实体的行'),
-    speakers: stringList('说话人展示名，仅匹配亲口台词'),
+    speakers: stringList('说话人展示名，仅匹配亲口台词；自动展开已登记别名'),
     match_mode: { type: 'string', enum: ['literal', 'regex'],
       description: '默认 literal 连续字面匹配；regex 为受限正则' },
     context_terms: { type: 'array', items: { type: 'string' },
-      description: '命中附近须同时出现的语境词，最多 8 个' },
+      description: '强约束：每个词都须出现在命中行前后 3 行内（非整篇共现），最多 8 个；不确定时省略' },
     after: { type: 'object', additionalProperties: false,
       description: '原样复制 page.next_after，保留原 query 和过滤条件；切版后重新搜索',
       required: ['data_version', 'resource_type', 'title', 'position'], properties: {
@@ -224,6 +227,7 @@ const SEARCH_OUTPUT_SCHEMA = {
             line_start: { type: 'integer' }, line_end: { type: 'integer' },
             match_kind: { type: 'string' }, evidence_kind: { type: 'string' },
             citation: { type: 'string' },
+            citation_handle: { type: 'string' },
             excerpt: { type: 'array', items: { type: 'object', additionalProperties: false,
               required: ['line', 'role', 'line_type', 'speaker', 'text', 'truncated'],
               properties: { line: { type: 'integer' },
@@ -259,6 +263,13 @@ const SEARCH_OUTPUT_SCHEMA = {
           } }, { type: 'null' }] } } },
     truncated: { type: 'boolean' },
     truncation_reasons: { type: 'array', items: { type: 'string' } },
+    scope: { type: 'object', additionalProperties: false,
+      required: ['documents', 'lines'], properties: {
+        documents: { type: 'integer' }, lines: { type: 'integer' },
+      } },
+    by_game: { type: 'object', additionalProperties: false, properties: {
+      arknights: { type: 'integer' }, endfield: { type: 'integer' },
+    } },
     warnings: { type: 'array', items: { type: 'object', additionalProperties: false,
       required: ['code', 'game', 'message'], properties: {
         code: { type: 'string' }, game: { type: 'string', enum: ['arknights', 'endfield'] },
@@ -276,34 +287,39 @@ const SEARCH_OUTPUT_SCHEMA = {
 const READ_PARAMETERS = {
   type: 'object',
   properties: {
-    title: { type: 'string', description: '完整展示标题；与 document_uid 互斥，须配 line、section 或 mode=document' },
+    title: { type: 'string', description: '展示标题（可省略分隔符与 Wiki 序号后缀，找不到会列出候选）；与 document_uid 互斥；可配 line、section 或 mode=document，单独提供时从第 1 行读全文' },
     document_uid: { type: 'string',
-      description: '搜索返回的同名消歧定位，替代 title；可配合集 mode' },
+      description: '仅复制搜索返回的 doc_ 开头同名消歧定位，替代 title；不能填展示标题，标题请用 title；可配合集 mode' },
     stage_code: { type: 'string', description: '明日方舟关卡代号，如 15-17、TW-ST-1' },
-    story_part: { type: 'string', enum: ['before', 'after', 'story'],
-      description: '多篇时消歧：before=行动前，after=行动后，story=幕间；单篇可省略' },
+    story_part: { type: 'string', enum: ['', 'before', 'after', 'story'],
+      description: '空或省略=不适用；依赖 stage_code，多篇时消歧：before=行动前，after=行动后，story=幕间；单篇可省略' },
     character_name: { type: 'string', description: '角色展示名；与 record_name 或 material 配合' },
-    record_name: { type: 'string', description: '干员密录名；多段时加 segment' },
-    segment: { type: 'integer', description: '密录段号，从 1 开始' },
-    material: { type: 'string', enum: ['profile', 'module', 'voice', 'skin', 'recruitment', 'potential'],
-      description: '资料类别：档案/模组/语音/时装/招聘合同/信物' },
-    game: { type: 'string', enum: ['arknights', 'endfield'],
-      description: '仅角色资料同名时限定游戏' },
+    record_name: { type: 'string', description: '干员密录名；须配 character_name，多段时加 segment' },
+    segment: { type: 'integer', description: '依赖 record_name 的密录段号，从 1 开始；其他定位请省略' },
+    material: { type: 'string', enum: ['', 'profile', 'module', 'voice', 'skin', 'recruitment', 'potential'],
+      description: '空或省略=不适用；依赖 character_name，读官方角色资料：档案/模组/语音/时装/招聘合同/信物。两款游戏通用（终末地如 {"character_name":"管理员","material":"profile"}）；活动、组织等实体资料用搜索返回的 title 读取' },
+    game: { type: 'string', enum: ['', 'arknights', 'endfield'],
+      description: '空或省略=不适用；依赖 character_name+material，仅角色资料同名时限定游戏' },
     activity_name: { type: 'string', description: '明日方舟活动展示名，配 mode=activity' },
     collection_name: { type: 'string', description: '终末地任务集合展示名，配 mode=collection' },
     content_types: { type: 'array', items: { type: 'string', enum: END_FIELD_STORY_CONTENT_TYPES },
       description: '终末地集合的内容形式过滤；续页保留' },
-    line: { type: 'integer', description: '上下文中心行号；mode=document 时为起始行' },
+    line: { type: 'integer', description: '上下文中心行号（around 模式，默认前后各 3 行）；mode=document 不接受 line，连续读取请用 start_line' },
+    start_line: { type: 'integer', description: '连续读取的起始行号，仅配 mode=document；page.continuation 里的续页参数就是它' },
     position: { type: 'integer', description: '合集续读位置，从 page.continuation 复制' },
-    mode: { type: 'string', enum: ['document', 'activity', 'collection'],
-      description: 'document=单篇全文，activity=活动，collection=任务集合；document_uid、关卡、密录和角色资料默认单篇全文' },
-    section: { type: 'string', enum: WIKI_SECTION_VALUES, description: '读取 Wiki 标签字段' },
+    mode: { type: 'string', enum: ['', 'document', 'activity', 'collection'],
+      description: '空或省略=不适用；document=单篇全文，activity=活动，collection=任务集合；document_uid、关卡、密录和角色资料默认单篇全文；显式 mode=document 全文优先于合法 section，并返回提示' },
+    section: { type: 'string', enum: ['', ...WIKI_SECTION_VALUES], description: '空或省略=不适用；配 title 或 document_uid 读取 Wiki 标签字段；并非每篇都有全部字段，不确定时用 mode=document；显式全文优先于合法 section，并返回提示' },
     before: { type: 'integer', description: '前文行数，默认 3，上限 100' },
     after: { type: 'integer', description: '后文行数，默认 3，上限 100' },
     cursor: { type: 'string', description: '仅兼容旧会话游标' },
-    data_version: { type: 'string', description: '续页复制 page.continuation.data_version' },
+    data_version: { type: 'string', description: '续页调用给出的短版本号；可省略' },
     max_lines: { type: 'integer', description: '输出行数上限，默认 100，最大 500' },
     max_chars: { type: 'integer', description: '输出字符上限，默认 12000，最大 100000' },
+    citation: { type: 'string',
+      description: '检索结果给出的「句柄」，形如 doc_xxxxxxxxxxxxxxxx#L123 或 #L120-135；与 title/document_uid/line 等定位参数互斥，用于回到原文某几行' },
+    reuse: { type: 'boolean',
+      description: '默认 true：跳过"上文已可见"的行，只返回新增行。长会话或上文被压缩/折叠后看不到原文时传 false，强制重发本页全文' },
   },
   additionalProperties: false,
 }
@@ -369,7 +385,8 @@ const READ_OUTPUT_SCHEMA = {
             activity_name: { type: 'string' }, collection_name: { type: 'string' },
             content_types: { type: 'array', items: { type: 'string', enum: END_FIELD_STORY_CONTENT_TYPES } },
             mode: { type: 'string', enum: ['document', 'activity', 'collection'] },
-            line: { type: 'integer' }, position: { type: 'integer' }, data_version: { type: 'string' },
+            start_line: { type: 'integer' }, position: { type: 'integer' },
+            data_version: { type: 'string' },
           } }, { type: 'null' }] } } },
   },
 }
@@ -383,7 +400,7 @@ function projectReadToolValue(response, store) {
         && store.requiresDocumentUid?.(response.document?.document_id)) {
       projected.page.continuation = {
         document_uid: documentUid(response.document.document_id), mode: 'document',
-        line: continuation.line, data_version: continuation.data_version,
+        start_line: continuation.start_line, data_version: continuation.data_version,
       }
     }
     const uniqueStage = continuation.stage_code && continuation.story_part
@@ -396,7 +413,7 @@ function projectReadToolValue(response, store) {
         && (continuation.stage_code || continuation.record_name || continuation.material)
         && !uniqueStage && !uniqueRecord && !uniqueMaterial) {
       projected.page.continuation = {
-        title: projected.primary.title, mode: 'document', line: continuation.line,
+        title: projected.primary.title, mode: 'document', start_line: continuation.start_line,
         data_version: continuation.data_version,
       }
     }
@@ -473,19 +490,48 @@ const CLOUD_SEARCH_PARAMETERS = {
     depth: { type: 'string', enum: ['fast', 'standard', 'deep'],
       description: '兼容字段，不改变检索路线；通常省略' },
     evidence_policy: { type: 'string', enum: ['mixed', 'original_only'],
-      description: '默认 mixed 混合检索；original_only 仅官方剧情原文' },
+      description: '默认 mixed 混合检索，通常省略；original_only 仅检索官方剧情原文' },
     options: {
       type: 'object', additionalProperties: false,
       properties: {
         search_intent: {
           type: 'string', enum: ['single_sentence_search'],
-          description: '仅用户记得一句官方原文大意、措辞不准时使用',
+          description: '仅用于凭记忆找某一句官方原文出处；会关闭档案/Wiki/图谱/年表，只检索原文。综合分析、人物关系等问题不要填写',
         },
       },
     },
   },
 }
 
+// 与后端 models/schemas.py SourceType、models/retrieval.py CandidateStatus 保持一致。
+const CLOUD_SOURCE_TYPES = ['entity_profile', 'entity_attachment', 'graph_entity', 'graph_relation',
+  'graph_event', 'csv_archive', 'csv_activity', 'csv_record', 'vector_original', 'vector_scene',
+  'vector_wiki', 'entity_attribute', 'travel_notes', 'classic_hit', 'timeline']
+const CLOUD_CANDIDATE_STATUSES = ['retrieved', 'kept', 'filtered', 'discarded', 'error']
+
+// 从 1 开始计数的整数字段：0 只可能是占位，按“省略”处理。
+const TIMELINE_ZERO_FIELDS = ['max_results']
+const CLOUD_INSPECT_ZERO_FIELDS = ['limit', 'event_sequence_from', 'event_sequence_to', 'content_max_chars']
+
+// 只接受最无歧义的形式（T 分隔、Z 或 ±HH:MM 时区），避免本地放行而后端 422。
+const AWARE_ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/u
+
+/** cloud_inspect 本地预检：把后端 422 会拒绝的常见误用提前转成可执行的提示。 */
+function validateCloudInspectArgs(args) {
+  for (const field of ['event_time_from', 'event_time_to']) {
+    if (args[field] !== undefined && !AWARE_ISO_DATETIME.test(String(args[field]).trim())) {
+      throw Object.assign(new Error(`${field} 必须是带时区的 ISO 8601 时间，例如 2025-01-01T08:00:00+08:00；不需要按时间过滤时请省略该字段`),
+        { code: 'INVALID_REQUEST', retryable: false })
+    }
+  }
+  for (const field of ['event_sequence_from', 'event_sequence_to', 'limit', 'cursor', 'content_max_chars']) {
+    if (args[field] !== undefined && (!Number.isInteger(args[field]) || args[field] < (field === 'cursor' ? 0 : 1))) {
+      throw Object.assign(new Error(`${field} 必须是${field === 'cursor' ? '非负' : '正'}整数；不需要时请省略该字段`),
+        { code: 'INVALID_REQUEST', retryable: false })
+    }
+  }
+}
+
 const CLOUD_INSPECT_PARAMETERS = {
   type: 'object', additionalProperties: false,
   properties: {
@@ -493,38 +539,76 @@ const CLOUD_INSPECT_PARAMETERS = {
       description: '游戏过滤；省略时查看全部启用游戏' },
     section: { type: 'string', enum: ['summary', 'candidates', 'selected_sources', 'events', 'trace_steps', 'answer_context'],
       description: '默认 summary' },
-    cursor: { type: 'integer', description: '复制返回的 next_cursor' },
-    limit: { type: 'integer', description: '本页条数' },
-    channels: stringList('按渠道过滤（candidates/events）'),
-    query_variants: stringList('按查询变体过滤'),
-    retrievers: stringList('按检索器过滤'),
-    source_types: { type: 'array', items: { type: 'string' }, description: '按来源类型过滤' },
-    statuses: { type: 'array', items: { type: 'string' }, description: '按候选状态过滤' },
-    stages: stringList('按处理阶段过滤'),
-    candidate_ids: stringList('按候选 ID 精确过滤'),
-    evidence_ids: stringList('按证据 ID 精确过滤'),
-    event_sequence_from: { type: 'integer', description: '事件序号下界（含）' },
-    event_sequence_to: { type: 'integer', description: '事件序号上界（含）' },
-    event_time_from: { type: 'string', description: '事件时间下界' },
-    event_time_to: { type: 'string', description: '事件时间上界' },
+    cursor: { type: 'integer', description: '续页时复制返回的 next_cursor；首页省略' },
+    limit: { type: 'integer', description: '本页条数 1–200；通常省略' },
+    channels: stringList('按渠道过滤（candidates/events）；通常省略'),
+    query_variants: stringList('按查询变体过滤；通常省略'),
+    retrievers: stringList('按检索器过滤；通常省略'),
+    source_types: { type: 'array', items: { type: 'string', enum: CLOUD_SOURCE_TYPES },
+      description: '按来源类型过滤；通常省略' },
+    statuses: { type: 'array', items: { type: 'string', enum: CLOUD_CANDIDATE_STATUSES },
+      description: '按候选状态过滤；通常省略' },
+    stages: stringList('按处理阶段过滤；通常省略'),
+    event_sequence_from: { type: 'integer', description: '仅 section=events：事件序号下界（含），从 1 开始' },
+    event_sequence_to: { type: 'integer', description: '仅 section=events：事件序号上界（含），从 1 开始' },
+    event_time_from: { type: 'string', description: '仅 section=events：带时区的 ISO 8601 时间，如 2025-01-01T08:00:00+08:00' },
+    event_time_to: { type: 'string', description: '仅 section=events：带时区的 ISO 8601 时间' },
     content_mode: { type: 'string', enum: ['none', 'preview', 'full'],
-      description: 'none=无正文，preview=摘要，full=本页全文' },
-    content_max_chars: { type: 'integer', description: '正文字符上限' },
+      description: 'none=无正文，preview=摘要（默认），full=本页全文' },
+    content_max_chars: { type: 'integer', description: '正文字符上限 100–100000；通常省略' },
   },
 }
 
 /** ---- 模型扁平参数 → 版本化 wire contract ---- */
 
 /** corpus_read：将模型使用的自然定位器转换为版本化读取契约。 */
+/** modelReadToContract 推断出的默认值说明；契约对象本身不允许携带额外字段。 */
+const contractNotes = new WeakMap()
+
+function withContractNote(contract, notes) {
+  if (notes.length) contractNotes.set(contract, notes.join('\n'))
+  return contract
+}
+
+/**
+ * 明日方舟“活动”（activity_name）与终末地“任务集合”（collection_name）是同一种连续
+ * 阅读入口，只是两款游戏的叫法不同。字段填反时，若名称只在另一款游戏中存在，就按
+ * 实际资料改道并说明，而不是报“找不到”。
+ */
+function streamExists(lookup) {
+  try { return lookup().length > 0 } catch { return true }
+}
+function rerouteStreamLocator(args, store, enabledGames, notes) {
+  const swap = (from, to, mode, game) => {
+    const name = String(args[from] ?? '').trim()
+    if (!name || args[to] !== undefined || args.document_uid !== undefined || !enabledGames.includes(game)) return null
+    const own = from === 'activity_name'
+      ? enabledGames.includes('arknights') && streamExists(() => store.activityStoryDocuments({ activityName: name }))
+      : enabledGames.includes('endfield') && streamExists(() => store.endfieldCollectionDocuments({ collectionName: name }))
+    if (own) return null
+    const other = to === 'collection_name'
+      ? streamExists(() => store.endfieldCollectionDocuments({ collectionName: name }))
+      : streamExists(() => store.activityStoryDocuments({ activityName: name }))
+    if (!other) return null
+    const { [from]: _drop, ...rest } = args
+    notes.push(`定位改道：“${name}”是${game === 'endfield' ? '终末地任务集合' : '明日方舟活动'}，已按 ${to}+mode="${mode}" 读取。`)
+    return { ...rest, [to]: name, ...(args.mode !== undefined ? { mode } : {}) }
+  }
+  return swap('activity_name', 'collection_name', 'collection', 'endfield')
+    || swap('collection_name', 'activity_name', 'activity', 'arknights')
+    || args
+}
+
 async function modelReadToContract(args = {}, store, enabledGames = ['arknights', 'endfield']) {
+  const notes = []
   if (!args || typeof args !== 'object' || Array.isArray(args)) {
     throw Object.assign(new Error('读取参数必须是对象'), { code: 'INVALID_REQUEST' })
   }
   let expectedDataVersion
   if (args.data_version !== undefined) {
     expectedDataVersion = String(args.data_version)
-    if (!DATA_VERSION_PATTERN.test(expectedDataVersion)) {
-      throw Object.assign(new Error('data_version 必须是续页结果给出的 64 位小写 SHA-256'),
+    if (!DATA_VERSION_REF_PATTERN.test(expectedDataVersion)) {
+      throw Object.assign(new Error('data_version 必须是续页结果给出的资料版本（至少 8 位小写十六进制，可省略）'),
         { code: 'INVALID_REQUEST' })
     }
   }
@@ -590,24 +674,66 @@ async function modelReadToContract(args = {}, store, enabledGames = ['arknights'
   }
   const allowed = new Set(['title', 'document_uid', 'stage_code', 'story_part', 'character_name', 'record_name',
     'segment', 'material', 'game', 'activity_name', 'collection_name', 'content_types',
-    'line', 'position', 'mode', 'section', 'before', 'after', 'max_lines', 'max_chars',
-    'data_version'])
+    'line', 'start_line', 'position', 'mode', 'section', 'before', 'after', 'max_lines', 'max_chars',
+    'reuse', 'citation', 'data_version'])
   if (Object.keys(args).some((key) => !allowed.has(key))) {
     throw Object.assign(new Error('corpus_read 包含不支持的参数'), { code: 'INVALID_REQUEST' })
   }
+  args = rerouteStreamLocator(args, store, enabledGames, notes)
+
+  // 句柄是检索结果发出的重新取用凭据：展开成 document_uid + 起始行 + 行数，
+  // 不让 Agent 为了拿 uid 先跑一次搜索。
+  if (args.citation !== undefined) {
+    const parsed = parseCitation(args.citation)
+    if (!parsed) {
+      throw Object.assign(new Error(
+        'citation 格式应为 doc_<16位定位>#L<行号> 或 doc_<16位定位>#L<起始行>-<结束行>；请原样复制检索结果里的「句柄」。',
+      ), { code: 'INVALID_REQUEST' })
+    }
+    const conflicts = ['title', 'document_uid', 'line', 'start_line', 'stage_code', 'story_part',
+      'activity_name', 'collection_name', 'character_name', 'record_name', 'material']
+      .filter((key) => args[key] !== undefined)
+    if (conflicts.length) {
+      throw Object.assign(new Error(
+        `citation 已包含篇章与行号，不能再与 ${conflicts.join('、')} 同时提交。`,
+      ), { code: 'INVALID_REQUEST' })
+    }
+    delete args.citation
+    args.document_uid = parsed.documentUid
+    args.mode = 'document'
+    args.start_line = parsed.startLine
+    args.max_lines = parsed.endLine - parsed.startLine + 1
+  }
 
   const hasTitle = args.title !== undefined
   const hasDocumentUid = args.document_uid !== undefined
-  const hasStageLocator = args.stage_code !== undefined || args.story_part !== undefined
-  const hasRecordLocator = args.record_name !== undefined || args.segment !== undefined
-  const hasMaterialLocator = args.material !== undefined
+  const hasStageLocator = args.stage_code !== undefined
+  const hasRecordLocator = args.record_name !== undefined
+  const hasMaterialLocator = args.character_name !== undefined && args.material !== undefined
   const hasActivityLocator = args.activity_name !== undefined
   const hasCollectionLocator = args.collection_name !== undefined
-  const locatorCount = [hasTitle, hasDocumentUid, hasStageLocator, hasRecordLocator, hasMaterialLocator,
-    hasActivityLocator, hasCollectionLocator].filter(Boolean).length
+  const locatorCount = readTargets(args).length
   if (locatorCount !== 1) {
+    throw Object.assign(new Error(readTargetError(args)), { code: 'INVALID_REQUEST' })
+  }
+  if (args.story_part !== undefined && !hasStageLocator) {
+    throw Object.assign(new Error('附属参数 story_part 依赖 stage_code；关卡读取请仅提交 {"stage_code":"15-17","story_part":"after"}，其他定位请省略 story_part'),
+      { code: 'INVALID_REQUEST' })
+  }
+  if (args.segment !== undefined && !hasRecordLocator) {
+    throw Object.assign(new Error('附属参数 segment 依赖 record_name；密录读取请仅提交 {"character_name":"角色名","record_name":"密录名","segment":1}，其他定位请省略 segment'),
+      { code: 'INVALID_REQUEST' })
+  }
+  if (args.material !== undefined && args.character_name === undefined) {
+    throw Object.assign(new Error('附属参数 material 依赖 character_name；角色资料读取请仅提交 {"character_name":"角色名","material":"profile"}，其他定位请省略 material'),
+      { code: 'INVALID_REQUEST' })
+  }
+  // Validate before either the single-document or collection lookup, so a
+  // display title in this field is not mistaken for missing corpus data.
+  if (hasDocumentUid && (typeof args.document_uid !== 'string'
+      || !/^doc_[A-Za-z0-9_-]{16}$/u.test(args.document_uid.trim()))) {
     throw Object.assign(new Error(
-      '必须且只能提供一种定位方式：title、document_uid、stage_code、角色密录、角色资料、activity_name 或 collection_name；document_uid 会替代 title，不要同时提交二者',
+      'document_uid 必须是检索结果返回的 doc_ 定位（doc_ 后为 16 位字母、数字、_ 或 -），不能填写展示标题；展示标题请改填 title，例如 {"title":"完整展示标题","mode":"document"}。不要同时提交 title 和 document_uid。',
     ), { code: 'INVALID_REQUEST' })
   }
   if (args.character_name !== undefined && !hasRecordLocator && !hasMaterialLocator) {
@@ -638,8 +764,11 @@ async function modelReadToContract(args = {}, store, enabledGames = ['arknights'
     const expectedMode = hasActivityLocator ? 'activity'
       : hasCollectionLocator ? 'collection' : args.mode
     if (args.mode !== undefined && args.mode !== expectedMode) {
-      throw Object.assign(new Error(`${hasActivityLocator ? 'activity_name' : 'collection_name'} 必须使用 mode="${expectedMode}"`),
-        { code: 'INVALID_REQUEST' })
+      if (uidStreamMode || args.mode !== (expectedMode === 'activity' ? 'collection' : 'activity')) {
+        throw Object.assign(new Error(`${hasActivityLocator ? 'activity_name' : 'collection_name'} 必须使用 mode="${expectedMode}"`),
+          { code: 'INVALID_REQUEST' })
+      }
+      notes.push(`读取方式：${hasActivityLocator ? 'activity_name' : 'collection_name'} 对应 mode="${expectedMode}"，已自动改用。`)
     }
     if (args.line !== undefined || args.section !== undefined || args.before !== undefined
         || args.after !== undefined) {
@@ -680,7 +809,7 @@ async function modelReadToContract(args = {}, store, enabledGames = ['arknights'
     } catch (error) {
       throw Object.assign(new Error(error.message), { code: error.code || 'DOCUMENT_AMBIGUOUS' })
     }
-    return {
+    return withContractNote({
       locator: hasDocumentUid ? { document_uid: String(args.document_uid).trim() }
         : { [hasActivityLocator ? 'activity_name' : 'collection_name']: name },
       selection: { mode: expectedMode, cursor: null,
@@ -689,7 +818,7 @@ async function modelReadToContract(args = {}, store, enabledGames = ['arknights'
       ...(expectedDataVersion ? { expected_data_version: expectedDataVersion } : {}),
       limits: { ...(args.max_lines !== undefined ? { max_lines: args.max_lines } : {}),
         ...(args.max_chars !== undefined ? { max_chars: args.max_chars } : {}) },
-    }
+    }, notes)
   }
 
   let locator
@@ -716,8 +845,35 @@ async function modelReadToContract(args = {}, store, enabledGames = ['arknights'
     try {
       record = await store.getDocumentByStoryStage(stageCode, storyPart)
     } catch (error) {
-      throw Object.assign(new Error(error.message),
-        { code: error.code || 'DOCUMENT_AMBIGUOUS' })
+      // 同一关卡有行动前/行动后两篇时，未指定 story_part 默认先读行动前，
+      // 并提示另一篇的读法，而不是直接报错让调用方重试。
+      let fallback = null
+      if (!storyPart && error.code === 'DOCUMENT_AMBIGUOUS') {
+        for (const part of ['before', 'story', 'after']) {
+          try {
+            fallback = await store.getDocumentByStoryStage(stageCode, part)
+          } catch {
+            fallback = null
+          }
+          if (fallback) {
+            const others = []
+            for (const other of ['before', 'after', 'story'].filter((item) => item !== part)) {
+              try {
+                if (await store.getDocumentByStoryStage(stageCode, other)) others.push(other)
+              } catch { /* 其余部分仍有歧义时不提示 */ }
+            }
+            const labels = { before: '行动前', after: '行动后', story: '纯剧情/幕间' }
+            notes.push(`关卡定位：${stageCode} 有多篇剧情，未指定 story_part，已默认读取${labels[part]}。`
+              + (others.length ? `另有${others.map((item) => `${labels[item]}（story_part="${item}"）`).join('、')}。` : ''))
+            break
+          }
+        }
+      }
+      if (!fallback) {
+        throw Object.assign(new Error(error.message),
+          { code: error.code || 'DOCUMENT_AMBIGUOUS' })
+      }
+      record = fallback
     }
     if (!record) {
       const partLabel = storyPart
@@ -783,15 +939,24 @@ async function modelReadToContract(args = {}, store, enabledGames = ['arknights'
     if (!title) throw Object.assign(new Error('title 不能为空'), { code: 'INVALID_REQUEST' })
     const record = await store.getDocumentByTitle(title)
     requireEnabled(record)
+    if (record) {
+      const resolvedTitle = naturalDocumentTitle(record.record.document)
+      const exact = (store.naturalTitleIndex?.get(title)?.length || store.titleIndex?.get(title)?.length)
+      if (!exact && resolvedTitle && resolvedTitle !== title) {
+        notes.push(`标题匹配：未找到完全一致的标题，已按宽松匹配读取《${resolvedTitle}》。`)
+      }
+    }
     locator = { display_title: title }
   }
   const section = String(args.section ?? '').trim()
-  if (section && !hasTitle) {
-    throw Object.assign(new Error('section 只能与 title 定位器一起使用'), { code: 'INVALID_REQUEST' })
+  if (section && !hasTitle && !hasDocumentUid) {
+    throw Object.assign(new Error('section 只能与 title 或 document_uid 定位器一起使用'), { code: 'INVALID_REQUEST' })
   }
   const naturalDocumentLocator = hasDocumentUid || hasStageLocator || hasRecordLocator || hasMaterialLocator
+  // 只给 title 时默认从头读全文（受 max_lines/max_chars 限制并给出续页），
+  // 与关卡/密录/角色资料等其他直达定位保持一致。
   const mode = args.mode || (section ? 'section' : Number.isInteger(args.line) ? 'around'
-    : naturalDocumentLocator ? 'document' : '')
+    : naturalDocumentLocator || hasTitle ? 'document' : '')
   if (!mode) throw Object.assign(new Error(
     '请提供 line、section 或 mode="document"；max_lines/max_chars 只限制输出量，不能代替读取方式',
   ), { code: 'INVALID_REQUEST' })
@@ -808,34 +973,42 @@ async function modelReadToContract(args = {}, store, enabledGames = ['arknights'
   if (section && mode !== 'section') {
     throw Object.assign(new Error('section 只能与 mode=section 一起使用'), { code: 'INVALID_REQUEST' })
   }
+  // line 只表示"中心行"（around ±3）。它与全文起点共用过同一字段，导致照着续读提示
+  // 传 line 时落回 ±3 窗口、永远前进不到下一页；这里把歧义变成显式失败。
+  // 例外：line=1 与"从第 1 行读起"同义，是客户端补齐默认值时常见的无害占位，放行。
+  if (mode === 'document' && args.line !== undefined && Number(args.line) > 1) {
+    throw Object.assign(new Error(
+      'mode="document" 不接受 line（line 是上下文中心行号，around 模式默认前后各 3 行）。'
+      + `连续读取请改用 start_line，例如 ${JSON.stringify({ start_line: args.line, mode: 'document' })}。`,
+    ), { code: 'INVALID_REQUEST' })
+  }
+  if (mode !== 'document' && args.start_line !== undefined) {
+    throw Object.assign(new Error(
+      'start_line 只用于 mode="document" 的连续读取；查看某一行上下文请改用 line（around 模式）。',
+    ), { code: 'INVALID_REQUEST' })
+  }
   const selection = mode === 'document'
-    ? { mode, cursor: null, ...(args.line !== undefined ? { start_line: args.line } : {}) }
+    ? { mode, cursor: null, ...(args.start_line !== undefined ? { start_line: args.start_line } : {}) }
     : mode === 'section'
           ? { mode, section }
         : { mode: 'around', center_line: args.line,
           ...(args.before !== undefined ? { before_lines: args.before } : {}),
           ...(args.after !== undefined ? { after_lines: args.after } : {}) }
-  return {
+  return withContractNote({
     locator, selection,
     ...(expectedDataVersion ? { expected_data_version: expectedDataVersion } : {}),
     limits: { ...(args.max_lines !== undefined ? { max_lines: args.max_lines } : {}),
       ...(args.max_chars !== undefined ? { max_chars: args.max_chars } : {}) },
-  }
+  }, notes)
 }
 
 /** ---- 云端渲染（output.render 用，压缩为模型可读文本） ---- */
 
-function renderCloudSearch(_args, value) {
-  if (value.status === 'error') {
-    return [{ type: 'text', text: `[cloud_search:error] ${value.error.code}: ${value.error.message}` }]
-  }
-  return [{ type: 'text', text: projectCloudSearch(value) }]
+function renderCloudSearch(args, value) {
+  return [{ type: 'text', text: projectCloudSearch(value, { args }) }]
 }
 
 function renderCloudInspect(_args, value) {
-  if (value.status === 'error') {
-    return [{ type: 'text', text: `[cloud_inspect:error] ${value.error.code}: ${value.error.message}` }]
-  }
   return [{ type: 'text', text: JSON.stringify(projectCloudInspect(value)) }]
 }
 
@@ -936,6 +1109,25 @@ export async function apply(ctx, config = {}) {
     installArchivePtcReceipts(toolCtx, readPresentationMeta)
     // Host 的 preset 准入已经完成初始化；工具挂载不再触发下载或全量扫描。
     applyEntityRecognition(toolCtx, store, shared)
+    tools.register({
+      name: 'corpus_navigate',
+      description: NAVIGATION_DESCRIPTION,
+      parameters: NAVIGATION_PARAMETERS,
+      output: { schema: { type: 'object', additionalProperties: true }, render: renderNavigation },
+      timeoutMs: 60_000,
+      isConcurrencySafe: () => true,
+      presentCall: (args) => ({ card: 'generic', kind: 'search',
+        title: `终末地主线导航 · ${compactToolTitle(args?.query || '主线目录')}` }),
+      execute: async (rawArgs, exec) => {
+        await requireLocalCorpus(store)
+        const response = await executeNavigation(store, dropEmptyPlaceholders(rawArgs), {
+          signal: exec?.signal, allowedGames: shared.effective().enabledGames,
+        })
+        if (response.error) throw Object.assign(new Error(response.error.message), response.error)
+        return response
+      },
+    })
+
     tools.register({
       name: 'corpus_search',
       description: SEARCH_DESCRIPTION,
@@ -945,10 +1137,11 @@ export async function apply(ctx, config = {}) {
       isConcurrencySafe: () => true,
       presentCall: (args) => searchCallView('PRTS 本地资料', args,
         shared.effective().enabledGames),
-      execute: async (args, exec) => {
+      execute: async (rawArgs, exec) => {
         await requireLocalCorpus(store)
+        const args = dropEmptyPlaceholders(rawArgs)
         const snapshot = corpusVersionSnapshot(store)
-        const evidenceState = evidenceStates.forExecution(exec, store.dataVersion)
+        const evidenceState = evidenceStates.forExecution(exec, store.scopeFingerprint ?? store.dataVersion)
         const completedSearchCalls = evidenceState.completedSearchCalls
         const callId = String(exec?.callId || '')
         // 先做对象校验再做幂等哈希：JSON.stringify(undefined) 返回 undefined，
@@ -971,10 +1164,9 @@ export async function apply(ctx, config = {}) {
         const requestHash = createHash('sha256').update(JSON.stringify(scopedArgs)).digest('hex')
         if (callId && completedSearchCalls.has(callId)) {
           const cached = completedSearchCalls.get(callId)
-          if (cached.requestHash !== requestHash) return {
-            contract_version: 'prts-corpus-tools-v1', status: 'error', request_id: callId,
-            data_version: store.dataVersion ?? null,
-            error: { code: 'INVALID_REQUEST', message: 'callId 已绑定到另一个搜索请求', retryable: false },
+          if (cached.requestHash !== requestHash) {
+            throw Object.assign(new Error('callId 已绑定到另一个搜索请求'),
+              { code: 'INVALID_REQUEST', retryable: false })
           }
           assertCorpusVersion(store, snapshot)
           const replay = structuredClone(cached.response)
@@ -1010,23 +1202,29 @@ export async function apply(ctx, config = {}) {
       // 模型调用顺序独占执行并逐个提交结果。
       isConcurrencySafe: () => false,
       presentCall: (args) => readCallView(args, shared.effective().enabledGames),
-      execute: async (args, exec) => {
+      execute: async (rawArgs, exec) => {
         await requireLocalCorpus(store)
+        let { args, guidance: argumentGuidance } = normalizeReadArguments(rawArgs,
+          { sections: WIKI_SECTION_VALUES })
         const snapshot = corpusVersionSnapshot(store)
-        const evidenceState = evidenceStates.forExecution(exec, store.dataVersion)
+        const evidenceState = evidenceStates.forExecution(exec, store.scopeFingerprint ?? store.dataVersion)
         let contract
         try {
           contract = await modelReadToContract(args, store, shared.effective().enabledGames)
           assertCorpusVersion(store, snapshot)
+          const inferred = contractNotes.get(contract)
+          if (inferred) argumentGuidance = [argumentGuidance, inferred].filter(Boolean).join('\n')
         } catch (error) {
           assertCorpusVersion(store, snapshot)
           throw Object.assign(new Error(error.message),
             { code: error.code || 'INVALID_REQUEST', retryable: error.retryable ?? false })
         }
-        if (contract.expected_data_version !== undefined
-            && contract.expected_data_version !== store.dataVersion) {
-          throw Object.assign(new Error('续页所属资料版本与当前激活版本不一致，请重新读取'),
-            { code: 'PACKAGE_VERSION_MISMATCH', retryable: true })
+        if (contract.expected_data_version !== undefined) {
+          if (!dataVersionMatches(contract.expected_data_version, store.dataVersion)) {
+            throw Object.assign(new Error('续页所属资料版本与当前激活版本不一致，请重新读取'),
+              { code: 'PACKAGE_VERSION_MISMATCH', retryable: true })
+          }
+          contract.expected_data_version = store.dataVersion
         }
         // 证据覆盖按 Harness Agent 隔离；模型不感知 intent_id。
         contract.intent_id = evidenceState.intentId
@@ -1034,12 +1232,14 @@ export async function apply(ctx, config = {}) {
         normalizeReadRequest(contract)
         const requested = await resolveReadWindow(store, contract)
         assertCorpusVersion(store, snapshot)
-        const visibleResults = visibleToolResults(exec?.agent)
+        // reuse:false 时不参与"上文已可见"的判定：宿主 surface 与模型实际收到的内容
+        // 一旦不一致（外部压缩、跨请求折叠），去重就会静默少给行，宁可重发。
+        const visibleResults = args.reuse === false ? new Map() : visibleToolResults(exec?.agent)
         if (coveredRead(evidenceState, requested, visibleResults)) {
           const replay = replayCoveredRead(evidenceState, requested, contract)
           if (replay) {
             assertCorpusVersion(store, snapshot)
-            return projectReadToolValue(replay, store)
+            return withReadGuidance(projectReadToolValue(replay, store), argumentGuidance)
           }
         }
         const response = await executeRead(store, contract, { signal: exec?.signal })
@@ -1051,7 +1251,7 @@ export async function apply(ctx, config = {}) {
         }, visibleResults) : null
         const delivered = reuseReadCoverage(response, coveragePlan)
         rememberRead(evidenceState, delivered, { callId: String(exec?.callId || ''), store })
-        return projectReadToolValue(delivered, store)
+        return withReadGuidance(projectReadToolValue(delivered, store), argumentGuidance)
       },
     })
 
@@ -1090,7 +1290,8 @@ export async function apply(ctx, config = {}) {
           throw Object.assign(new Error('明日方舟资料当前未启用'), { code: 'INVALID_REQUEST' })
         }
         const snapshot = corpusVersionSnapshot(store)
-        const response = await executeTimelineSearch(store, args, { signal: exec?.signal })
+        const response = await executeTimelineSearch(store,
+          dropEmptyPlaceholders(args, { zeroFields: TIMELINE_ZERO_FIELDS }), { signal: exec?.signal })
         assertCorpusVersion(store, snapshot)
         return rememberArchivePresentation(response, timelineArchivePresentation(response))
       },
@@ -1124,9 +1325,10 @@ export async function apply(ctx, config = {}) {
         timeoutMs: 180_000,
         isConcurrencySafe: () => true,
         presentCall: (args) => searchCallView('PRTS 云端资料', args, c.enabledGames),
-        execute: async (args, exec) => {
+        execute: async (rawArgs, exec) => {
           try {
-            const evidenceState = evidenceStates.forExecution(exec, store.dataVersion)
+            const args = dropEmptyPlaceholders(rawArgs)
+            const evidenceState = evidenceStates.forExecution(exec, store.scopeFingerprint ?? store.dataVersion)
             const cloud = cloudClients.forExecution(exec)
             await cloud.capabilities({ signal: exec?.signal })
             const requestedGames = Array.isArray(args.games) ? args.games : c.enabledGames
@@ -1142,7 +1344,8 @@ export async function apply(ctx, config = {}) {
             rememberCloudMappings(evidenceState, enriched)
             return rememberArchivePresentation(enriched, cloudArchivePresentation(enriched, { dataVersion }))
           } catch (error) {
-            return cloudErrorResponse(error)
+            // 抛出交给宿主标记 isError，让 Agent 明确知道本次调用失败。
+            throw cloudFaultError(error, 'cloud_search')
           }
         },
       })
@@ -1158,9 +1361,11 @@ export async function apply(ctx, config = {}) {
         presentCall: (args) => ({ card: 'generic',
           title: `查看 PRTS 云端检索详情 · ${presentedGames(args, c.enabledGames)}`,
           kind: 'read', rawInput: compactToolTitle(args?.section || 'summary') }),
-        execute: async (args, exec) => {
+        execute: async (rawArgs, exec) => {
           try {
-            const evidenceState = evidenceStates.forExecution(exec, store.dataVersion)
+            const args = dropEmptyPlaceholders(rawArgs, { zeroFields: CLOUD_INSPECT_ZERO_FIELDS })
+            validateCloudInspectArgs(args)
+            const evidenceState = evidenceStates.forExecution(exec, store.scopeFingerprint ?? store.dataVersion)
             const cloud = cloudClients.forExecution(exec)
             await cloud.capabilities({ signal: exec?.signal })
             const payload = { ...args,
@@ -1173,7 +1378,7 @@ export async function apply(ctx, config = {}) {
               inspect: true, dataVersion: store.dataVersion,
             }))
           } catch (error) {
-            return cloudErrorResponse(error)
+            throw cloudFaultError(error, 'cloud_inspect')
           }
         },
       })
@@ -1211,7 +1416,8 @@ export async function apply(ctx, config = {}) {
           storeEntry.releaseTimer = null
           try {
             const pointer = await readCurrentReleasePointer(releasesDir)
-            if (store.loaded && store.releaseId === pointer.release_id) return
+            if (store.loaded && store.releaseId === pointer.release_id
+                && store.installationId === (pointer.installation_id ?? null)) return
           } catch { /* 让 ready() 输出真实指针错误 */ }
           store.reset()
           prepareEntityRecognition(store).catch((error) => {