prts-terrarchive 0.2.0 → 0.2.2

package/src/index.js

@@ -45,6 +45,7 @@ import { createSharedState } from './state.js'
 import { applyUi } from './ui.js'
 import { acquireInvestigationStore } from './investigation-store.js'
 import { mountInvestigationTools } from './investigation-tools.js'
+import { mountWebGuidance } from './web-guidance.js'
 import { attachLocalSourceMappings } from './source-map.js'
 import { projectCloudInspect, projectCloudSearch } from './cloud-projection.js'
 import { coveredRead, createEvidenceStateRegistry,
@@ -109,35 +110,15 @@ async function requireLocalCorpus(store) {
   }
 }
 
-const READ_DESCRIPTION = [
-  '读取 PRTS.chat 本地资料。明日方舟关卡用 stage_code，只有多篇时才填 story_part；干员密录用 character_name + record_name + segment；角色资料用 character_name + material。',
-  '整个明日方舟活动用 activity_name + mode=activity，终末地任务用 collection_name + mode=collection；合集续页原样提交 page.continuation 的 position。其他资料使用完整 title。',
-  '搜索结果若给出 document_uid，说明标题或合集同名：它替代 title，读取时只提交 document_uid，不得同时提交 title；单篇可配 line 或 mode=document，所属合集可配 mode=activity/collection。',
-  'line 扩大单篇原文上下文，section 读取 Wiki 字段，mode=document 分页全文。所有续页都原样提交 page.continuation；旧会话里的 cursor 仅用于兼容。',
-  '引用原文使用“《篇章名》第 N 行”；同名结果保留工具给出的 document_uid 作为唯一定位器。不要使用内部代号、路径或自造篇章名。',
-].join(' ')
+const READ_DESCRIPTION = '读取 PRTS.chat 本地资料，支持行号上下文、Wiki 字段和单篇/合集连续阅读。只选一种主定位方式；续页原样提交 page.continuation。'
 
-const SEARCH_DESCRIPTION = [
-  '像 grep 一样搜索 PRTS.chat 本地语料；命中立即返回原行及上下各一行，并按文档归并。',
-  'query 使用短实体名、篇章展示名或原句片段；也可省略 query，仅按过滤条件列出资料入口。',
-  '角色个人页用 character_wiki；活动/密录整理页用 story_wiki；角色在单个活动中的辅助整理用 character_activity_wiki。wiki_sections 可精确限定相关活动、相关角色、剧情总结、角色剧情概括等标签字段。',
-  'literal 是默认连续字面匹配；只有特殊模式才使用受限 regex。新查询的下一页保留原搜索条件，并把返回的 next_after 原样放入 after；锚点由完整资料版本、资料类型与自然标题组成，不再暴露内部 cursor。旧会话的 cursor 链仅按返回的 next_cursor 继续。',
-].join(' ')
+const SEARCH_DESCRIPTION = '搜索 PRTS.chat 本地语料，返回按文档归并的命中行及上下各一行；省略 query 可列目录。过滤数组内 OR、字段间 AND。'
 
-const TIMELINE_DESCRIPTION = [
-  '按活动名、年份及自动展开的实体别名检索活动时间线（PRTS Wiki《泰拉年表》本地投影）。',
-  '人物放 entity_names 以自动裂变别名；结果只给时间、事件正文和“年表出处”标记，把标记原样传回 source_marker 可反查完整来源。',
-].join(' ')
+const TIMELINE_DESCRIPTION = '检索明日方舟活动时间线（PRTS Wiki《泰拉年表》），返回年份、事件与可反查的出处标记。'
 
-const CLOUD_SEARCH_DESCRIPTION = [
-  '用一次自然语言请求同时查询 PRTS.chat 云端的明日方舟与终末地图谱、档案、原文、自建 Wiki 和时间线组合索引；只有用户明确限定游戏时才使用 games 收窄。',
-  '返回末尾的「## 可读取原文」列出已映射到本地篇章的完整自然语言标题与行号；有同名消歧标记时按 document_uid + line 调用，否则按 title + line。',
-].join(' ')
+const CLOUD_SEARCH_DESCRIPTION = '用自然语言检索 PRTS.chat 云端图谱、档案、原文、Wiki 和时间线。返回的「可读取原文」定位可交给 corpus_read 核验。'
 
-const CLOUD_INSPECT_DESCRIPTION = [
-  '按 section 和过滤条件读取最近一次云端检索状态（request_id 由运行时自动注入）。',
-  '用于定点读取回答材料、候选状态或诊断记录，并支持按 next_cursor 分页。',
-].join(' ')
+const CLOUD_INSPECT_DESCRIPTION = '读取最近一次云端检索的回答材料、候选或诊断记录；request_id 由运行时注入。'
 
 const TOOL_GAME_LABELS = Object.freeze({ arknights: '明日方舟', endfield: '终末地' })
 
@@ -186,34 +167,34 @@ const stringList = (description) => ({ type: 'array', items: { type: 'string' },
 const SEARCH_PARAMETERS = {
   type: 'object', additionalProperties: false,
   properties: {
-    cursor: { type: 'string', description: '仅兼容旧会话：单独提交旧 next_cursor；新搜索使用 after' },
-    query: { type: 'string', description: '短搜索词：实体名、篇章展示名、活动名或原句片段；不要直接提交整句研究问题' },
+    cursor: { type: 'string', description: '旧会话 next_cursor，单独提交；新查询用 after' },
+    query: { type: 'string', description: '短实体名、标题或原句片段；完整研究问题用 cloud_search' },
     resource_types: { type: 'array', items: { type: 'string', enum: RESOURCE_TYPES },
-      description: '资料类型；character_bundle 可一次查看角色档案、模组、语音和密录' },
+      description: '资料类型；character_bundle 聚合角色资料' },
     games: { type: 'array', items: { type: 'string', enum: ['arknights', 'endfield'] },
-      description: '可选游戏过滤；省略时在同一次调用中同时检索明日方舟与终末地' },
+      description: '游戏范围；省略时查询全部启用游戏' },
     content_types: { type: 'array', items: { type: 'string', enum: CONTENT_TYPES },
-      description: '统一内容形式，例如 dialogue、cutscene、radio、sns_chat；两款游戏使用相同参数' },
-    collection_names: stringList('上级资料集合展示名；明日方舟活动与终末地任务都使用此字段'),
-    character_names: stringList('角色展示名，如“凯尔希”'),
-    story_names: stringList('剧情篇章的展示名，如“晶簇之内”；不要填写内部 story_id 或路径'),
+      description: '内容形式' },
+    collection_names: stringList('活动或任务等上级集合展示名'),
+    character_names: stringList('资料归属角色的展示名'),
+    story_names: stringList('剧情篇章展示名'),
     activity_names: stringList('活动展示名'),
     wiki_sections: { type: 'array', items: { type: 'string', enum: WIKI_SECTION_VALUES },
-      description: 'Wiki 标签字段，可与资料类型、角色、活动和 query 组合；角色页常用相关活动/相关角色/剧情高光，活动页常用剧情总结/关键人物/角色剧情概括' },
+      description: '限定 Wiki 标签字段' },
     entity_names: stringList('只返回出现指定实体的行'),
-    speakers: stringList('结构化说话人展示名，只匹配亲口台词；适合查某人亲口说过什么'),
+    speakers: stringList('说话人展示名，仅匹配亲口台词'),
     match_mode: { type: 'string', enum: ['literal', 'regex'],
-      description: '默认 literal 连续字面匹配；除非必须，不使用受限 regex' },
+      description: '默认 literal 连续字面匹配；regex 为受限正则' },
     context_terms: { type: 'array', items: { type: 'string' },
-      description: '要求命中附近同时出现的语境词（最多 8 个）' },
+      description: '命中附近须同时出现的语境词，最多 8 个' },
     after: { type: 'object', additionalProperties: false,
-      description: '版本绑定的下一页锚点；与原 query 和过滤条件一起原样提交上次返回的 next_after',
+      description: '原样复制 page.next_after，保留原 query 和过滤条件；切版后重新搜索',
       required: ['data_version', 'resource_type', 'title', 'position'], properties: {
         data_version: { type: 'string',
-          description: '上一页所用资料包的完整 SHA-256 版本；版本切换后必须重新搜索' },
+          description: '上一页的完整 SHA-256 资料版本' },
         resource_type: { type: 'string', enum: RESOURCE_TYPES },
-        title: { type: 'string', description: '上一页扫描到的资料自然标题' },
-        position: { type: 'integer', description: '该标题在当前资料版本中的顺序位置（0..10000000）' },
+        title: { type: 'string' },
+        position: { type: 'integer' },
       } },
   },
 }
@@ -295,34 +276,34 @@ const SEARCH_OUTPUT_SCHEMA = {
 const READ_PARAMETERS = {
   type: 'object',
   properties: {
-    title: { type: 'string', description: '未使用其他定位器时，填写资料完整展示标题；不得与 document_uid 同时提交' },
+    title: { type: 'string', description: '完整展示标题；与 document_uid 互斥，须配 line、section 或 mode=document' },
     document_uid: { type: 'string',
-      description: '仅在搜索结果提示同名歧义时原样复制 doc_ 开头的稳定定位；它替代 title，不得与 title 同时提交；可配合 mode=activity/collection 选择所属合集' },
-    stage_code: { type: 'string', description: '明日方舟游戏内关卡代号，如 15-17、GT-3、TW-ST-1' },
+      description: '搜索返回的同名消歧定位，替代 title；可配合集 mode' },
+    stage_code: { type: 'string', description: '明日方舟关卡代号，如 15-17、TW-ST-1' },
     story_part: { type: 'string', enum: ['before', 'after', 'story'],
-      description: '关卡存在多篇剧情时用于消歧：before=行动前，after=行动后，story=纯剧情/幕间；单篇关卡可省略' },
+      description: '多篇时消歧：before=行动前，after=行动后，story=幕间；单篇可省略' },
     character_name: { type: 'string', description: '角色展示名；与 record_name 或 material 配合' },
-    record_name: { type: 'string', description: '明日方舟干员密录名称；多段密录再提供 segment' },
-    segment: { type: 'integer', description: '干员密录段号，如 1、2' },
+    record_name: { type: 'string', description: '干员密录名；多段时加 segment' },
+    segment: { type: 'integer', description: '密录段号，从 1 开始' },
     material: { type: 'string', enum: ['profile', 'module', 'voice', 'skin', 'recruitment', 'potential'],
-      description: '角色资料类别；profile=档案、module=模组、voice=语音、skin=时装' },
+      description: '资料类别：档案/模组/语音/时装/招聘合同/信物' },
     game: { type: 'string', enum: ['arknights', 'endfield'],
-      description: '角色资料在双模块同名时用于消歧；其他定位器不要填写' },
-    activity_name: { type: 'string', description: '明日方舟活动展示名；按活动连续阅读全部剧情' },
-    collection_name: { type: 'string', description: '终末地任务或剧情集合展示名；跨碎片连续阅读' },
+      description: '仅角色资料同名时限定游戏' },
+    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: 'around 的中心官方行号；与 mode=document 同用时表示续读起始行' },
-    position: { type: 'integer', description: '活动/任务连续阅读的下一位置；只从 page.continuation 原样复制' },
+      description: '终末地集合的内容形式过滤；续页保留' },
+    line: { type: 'integer', description: '上下文中心行号；mode=document 时为起始行' },
+    position: { type: 'integer', description: '合集续读位置，从 page.continuation 复制' },
     mode: { type: 'string', enum: ['document', 'activity', 'collection'],
-      description: '单篇全文用 document；活动用 activity；终末地任务集合用 collection。title 不会自动推断，必须配 line、section 或 mode=document；document_uid、关卡、密录和角色资料可自动推断单篇全文' },
+      description: 'document=单篇全文，activity=活动，collection=任务集合；document_uid、关卡、密录和角色资料默认单篇全文' },
     section: { type: 'string', enum: WIKI_SECTION_VALUES, description: '读取 Wiki 标签字段' },
-    before: { type: 'integer', description: 'around 前文行数，默认 3，上限 100' },
-    after: { type: 'integer', description: 'around 后文行数，默认 3，上限 100' },
-    cursor: { type: 'string', description: '仅兼容旧会话中的不透明游标；新调用应原样提交上次结果的 page.continuation' },
-    data_version: { type: 'string', description: '续页时原样提交 page.continuation.data_version，防止版本切换后混读' },
-    max_lines: { type: 'integer', description: '最多返回行数，默认 100，上限 500；只限制输出量，不能代替 line、section 或 mode' },
-    max_chars: { type: 'integer', description: '最多返回字符数，默认 12000，上限 100000；只限制输出量，不能代替 line、section 或 mode' },
+    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' },
+    max_lines: { type: 'integer', description: '输出行数上限，默认 100，最大 500' },
+    max_chars: { type: 'integer', description: '输出字符上限，默认 12000，最大 100000' },
   },
   additionalProperties: false,
 }
@@ -473,12 +454,12 @@ function readPresentationMeta(_args, value) {
 const TIMELINE_PARAMETERS = {
   type: 'object', additionalProperties: false,
   properties: {
-    query: { type: 'string', description: '可选的事件正文短语（≤200 字符）。人物应优先放入 entity_names 以自动展开别名' },
-    activity_names: { type: 'array', items: { type: 'string' }, description: '活动展示名，例如“孤星”（≤20 项）' },
-    entity_names: { type: 'array', items: { type: 'string' }, description: '角色或实体展示名；工具会用别名图鉴自动裂变后检索（≤20 项）' },
-    year_start: { type: 'integer', description: '起始年份（含）；可单独使用' },
-    year_end: { type: 'integer', description: '结束年份（含）；可单独使用' },
-    source_marker: { type: 'string', description: '反查模式：原样复制时间线结果方括号内的年表出处标记（年表出处:tle_ 开头）' },
+    query: { type: 'string', description: '事件正文短语，最多 200 字符' },
+    activity_names: { type: 'array', items: { type: 'string' }, description: '活动展示名，最多 20 项' },
+    entity_names: { type: 'array', items: { type: 'string' }, description: '实体展示名，自动展开别名，最多 20 项' },
+    year_start: { type: 'integer', description: '起始年份，含边界' },
+    year_end: { type: 'integer', description: '结束年份，含边界' },
+    source_marker: { type: 'string', description: '反查来源时复制返回的年表出处标记' },
     max_results: { type: 'integer', description: '最多返回事件数，默认 20，上限 100' },
   },
 }
@@ -486,20 +467,19 @@ const TIMELINE_PARAMETERS = {
 const CLOUD_SEARCH_PARAMETERS = {
   type: 'object', additionalProperties: false, required: ['query'],
   properties: {
-    query: { type: 'string', description: '改写为语义完整、适合向量检索的自然语言' },
+    query: { type: 'string', description: '包含主体、事件和所求关系的完整问题' },
     games: { type: 'array', items: { type: 'string', enum: ['arknights', 'endfield'] },
-      description: '可选游戏范围；省略时同一次调用同时检索明日方舟与终末地' },
+      description: '游戏范围；省略时查询全部启用游戏' },
     depth: { type: 'string', enum: ['fast', 'standard', 'deep'],
-      description: '兼容字段；不会改变云端主站的检索路由。回答深度由 Agent 自己的运行模式控制，通常省略' },
+      description: '兼容字段，不改变检索路线；通常省略' },
     evidence_policy: { type: 'string', enum: ['mixed', 'original_only'],
-      description: 'mixed=完整复用 PRTS.chat 主站检索、审核与 Cleaner；original_only=只运行官方剧情原文向量路线' },
+      description: '默认 mixed 混合检索；original_only 仅官方剧情原文' },
     options: {
       type: 'object', additionalProperties: false,
-      description: '通常省略。只有用户记得一句原文大意且措辞可能不准时，选择官方剧情单句向量路线',
       properties: {
         search_intent: {
           type: 'string', enum: ['single_sentence_search'],
-          description: '只检索官方剧情单句向量表，并执行原有 LLM 验证；其他问题使用默认主站路线',
+          description: '仅用户记得一句官方原文大意、措辞不准时使用',
         },
       },
     },
@@ -508,13 +488,12 @@ const CLOUD_SEARCH_PARAMETERS = {
 
 const CLOUD_INSPECT_PARAMETERS = {
   type: 'object', additionalProperties: false,
-  description: '查看最近一次云端检索的指定区段；request_id 由运行时自动注入',
   properties: {
     games: { type: 'array', items: { type: 'string', enum: ['arknights', 'endfield'] },
-      description: '只查看指定游戏的候选、来源或事件；省略时查看联合状态' },
+      description: '游戏过滤；省略时查看全部启用游戏' },
     section: { type: 'string', enum: ['summary', 'candidates', 'selected_sources', 'events', 'trace_steps', 'answer_context'],
       description: '默认 summary' },
-    cursor: { type: 'integer', description: '分页游标：原样复制上次返回的 next_cursor' },
+    cursor: { type: 'integer', description: '复制返回的 next_cursor' },
     limit: { type: 'integer', description: '本页条数' },
     channels: stringList('按渠道过滤（candidates/events）'),
     query_variants: stringList('按查询变体过滤'),
@@ -529,7 +508,7 @@ const CLOUD_INSPECT_PARAMETERS = {
     event_time_from: { type: 'string', description: '事件时间下界' },
     event_time_to: { type: 'string', description: '事件时间上界' },
     content_mode: { type: 'string', enum: ['none', 'preview', 'full'],
-      description: 'none 只取结构字段；preview 返回受限正文；full 返回该页完整正文' },
+      description: 'none=无正文，preview=摘要，full=本页全文' },
     content_max_chars: { type: 'integer', description: '正文字符上限' },
   },
 }
@@ -867,7 +846,7 @@ function renderCloudInspect(_args, value) {
  * @param {{
  *   releasesDir?: string,
  *   cacheShards?: number,
- *   uiSkin?: 'harness' | 'prts-agent',
+ *   uiSkin?: 'harness' | 'prts-agent' | 'endfield-aic' | 'rhine-lab',
  *   download?: { order?: ('modelscope'|'site')[], siteBaseUrl?: string },
  *   cloud?: { baseUrl?: string, game?: 'arknights' | 'endfield', userId?: string, token?: string, timeoutMs?: number, maxResponseBytes?: number },
  * }} [config]
@@ -875,7 +854,7 @@ function renderCloudInspect(_args, value) {
 export async function apply(ctx, config = {}) {
   // Cordis 传空配置时可能是 null 而非 undefined，默认参数不生效，需兜底
   config = config ?? {}
-  // 工具开关：host 常驻时只做资料管理（registerTools:false），PRTS 预设（模式）加载时才注册工具（true）
+  // Host 常驻实例只做资料管理；PRTS 或自定义 Agent 预设按需注册工具。
   const enableTools = config.registerTools !== false
   const configuredHome = process.env.DSH_HOME?.trim()
   const dshHome = resolve(configuredHome || join(homedir(), '.dsh'))
@@ -1216,9 +1195,12 @@ export async function apply(ctx, config = {}) {
     const handle = acquireInvestigationStore(investigationCtx.storageDomain)
     shared.investigations = handle.service
     investigationCtx.effect(() => () => { if (shared.investigations === handle.service) shared.investigations = null; return handle.release() }, 'prts: investigations')
-    if (enableTools) await investigationCtx.inject(['tools', 'systemPrompt'], toolCtx => mountInvestigationTools(toolCtx, handle.service))
+    if (enableTools) await investigationCtx.inject(['tools', 'systemPrompt'], toolCtx => mountInvestigationTools(toolCtx, handle.service, shared))
+  })
+  if (enableTools) await ctx.inject(['tools', 'systemPrompt'], async toolCtx => {
+    mountWebGuidance(toolCtx)
+    await mountTools(toolCtx)
   })
-  if (enableTools) await ctx.inject(['tools', 'systemPrompt'], mountTools)
 
   if (enableTools) {
     await mkdir(releasesDir, { recursive: true })

package/src/investigation-review.js

@@ -1,7 +1,7 @@
 /** Shared read model for Agent recall; browser reads never acknowledge these notices. */
 const copy = value => structuredClone(value)
 const keyOf = ({ area, board_id = '', item_id = '' }) => JSON.stringify([area, board_id, item_id])
-const metadata = ({ content, ...source }) => copy(source)
+const metadata = ({ content, fragments, ...source }) => copy(source)
 const fail = message => { throw Object.assign(new Error(message), { code: 'INVESTIGATION_NOT_FOUND' }) }
 
 export function noteUserChange(portfolio, change) {
@@ -11,9 +11,15 @@ export function noteUserChange(portfolio, change) {
   else portfolio.attention[index] = item
 }
 
+// Old tool receipts predate the explicit flag. Browser imports use reserved call IDs.
+export function receivedByAgent(source) {
+  return source.agentReceived ?? Boolean(source.agentRead || source.state === 'read'
+    || source.callId && !['user', 'user-rack', 'user-inbox', 'legacy-user'].includes(source.callId))
+}
+
 export function reviewSummary(p) {
   const pending = p?.attention || []
-  return { pending_count: pending.length, rack_count: p?.sources.filter(s => s.agentRead || p.rack.some(r => r.source_id === s.id)).length || 0,
+  return { pending_count: pending.length, rack_count: p?.sources.filter(s => receivedByAgent(s) || p.rack.some(r => r.source_id === s.id)).length || 0,
     user_saved_count: p?.rack.length || 0, changes: pending.slice(-20).map(copy),
     ...(pending.length > 20 ? { more: 'investigation_get(section="changes") 可分页读取其余提醒' } : {}) }
 }
@@ -33,19 +39,20 @@ export function inspectPortfolio(p, args, boardSummary) {
   }
   if (section === 'rack' || section === 'sources') {
     const saved = new Map(p.rack.map(item => [item.source_id, item]))
-    const rows = [...p.sources].reverse().filter(source => section === 'sources' || (saved_only ? saved.has(source.id) : source.agentRead || saved.has(source.id)))
+    // Rack pages follow first arrival: new receipts append instead of shifting page offsets.
+    const rows = (section === 'sources' ? [...p.sources].reverse() : p.sources).filter(source => section === 'sources' || (saved_only ? saved.has(source.id) : receivedByAgent(source) || saved.has(source.id)))
       .map(source => ({ ...metadata(source), saved: saved.has(source.id), ...(saved.has(source.id) ? { saved_at: saved.get(source.id).addedAt } : {}) }))
       .filter(matches)
     const result = page(rows), ids = new Set(result.items.map(item => item.id))
     return respond({ total: result.total, nextCursor: result.nextCursor, sources: result.items, rack_revision: p.rackRevision, ...reviewSummary(p),
-      guidance: '来源目录包含摘要和定位信息；用 section="source", source_id 读取已保存正文。agentRead=false 的用户资料仍需读取原文核验。' },
+      guidance: '档案架保留已交付给 Agent 的资料与手动收藏；入架不代表已读原文。目录包含摘要和定位信息，用 section="source", source_id 读取已保存正文。agentRead=false 的资料仍需原文核验。' },
     item => section === 'rack' && item.area === 'rack' && ids.has(item.item_id))
   }
   if (section === 'source') {
     const source = p.sources.find(s => s.id === source_id || s.sourceId === source_id)
     if (!source) fail('来源不存在；先读取 rack 或 sources 取得 source_id')
     return respond({ source: copy(source), saved: p.rack.some(item => item.source_id === source.id),
-      guidance: source.agentRead ? '这是已保存的工具返回正文；contentTruncated=true 时需要继续读取原文。' : '这是用户选入的材料，不代表 Agent 已核验原文；按 documentId/sourceRef/url 调用读取工具核验。' },
+      guidance: source.agentRead ? 'fragments 按阅读片段保留正文和行范围；content 为最后一次阅读。contentTruncated=true 时需要继续读取原文。' : '此资料尚未经过 Agent 原文核验；按 documentId/sourceRef/url 调用读取工具核验。' },
     item => item.area === 'rack' && item.item_id === source.id)
   }
   if (!['board', 'clues', 'report', 'inbox'].includes(section)) fail('未知调查资料 section')
@@ -66,7 +73,8 @@ export function inspectPortfolio(p, args, boardSummary) {
   if (section === 'report') {
     const report = report_version === undefined ? board.reports.at(-1) : board.reports.find(r => r.version === report_version)
     if (!report) fail('指定的调查报告尚不存在')
-    return respond({ ...identity, report: { ...copy(report), sources: report.sources.map(metadata) } })
+    const { boardSnapshot, ...published } = report
+    return respond({ ...identity, report: { ...copy(published), sources: report.sources.map(metadata) } })
   }
   if (section === 'clues') {
     const result = page(board.clues.filter(c => (!clue_id || c.id === clue_id) && matches(c)))

package/src/investigation-store.js

@@ -1,7 +1,8 @@
 /** Durable investigation portfolios, shared by Host UI and agent preset instances. */
 import { createHash, randomUUID } from 'node:crypto'
-import { z } from 'zod'
-import { inspectPortfolio, noteUserChange, reviewSummary } from './investigation-review.js'
+import { z } from '../lib/runtime/zod.js'
+import { inspectPortfolio, noteUserChange, reviewSummary, receivedByAgent } from './investigation-review.js'
+import { originalQuotation, sourceRecovery } from './investigation-validation.js'
 
 const id = z.string().min(1).max(512)
 const short = z.string().max(512)
@@ -10,8 +11,10 @@ const range = z.object({ start: z.number().int().positive(), end: z.number().int
 export const clueKinds = ['excerpt', 'finding', 'time', 'relation', 'question', 'contrast']
 const sourceSchema = z.object({
   id, sourceId: id, title: short, kind: z.string().max(80), origin: z.enum(['local', 'cloud', 'web']),
-  state: z.enum(['found', 'read']), agentRead: z.boolean(), excerpt: z.string().max(4000),
+  state: z.enum(['found', 'read']), agentRead: z.boolean(), agentReceived: z.boolean().optional(), excerpt: z.string().max(4000),
   content: z.string().max(64000).optional(), contentTruncated: z.boolean().optional(),
+  // Only trusted tool receipts populate these fragments; callers cannot import trust.
+  fragments: z.array(z.object({ content: z.string().max(64000), ranges: z.array(range).max(256), callId: short })).max(256).default([]),
   documentId: z.string().max(2048).optional(), documentUid: z.string().max(512).optional(),
   sourceRef: z.string().max(2048).optional(), dataVersion: z.string().max(128).optional(),
   url: z.string().max(4096).optional(), lineStart: z.number().int().positive().optional(),
@@ -31,18 +34,20 @@ export const clueSchema = z.object({
   userLayoutLocked: z.boolean(), mergedInto: id.optional(),
 })
 const relationSchema = z.object({ id, from: id, to: id, type: z.enum(['supports', 'contradicts', 'precedes', 'relates']), label: z.string().max(100) })
-const reportSchema = z.object({ id, version: z.number().int().positive(), title: z.string().min(1).max(180),
-  summary: z.string().max(1000), markdown: z.string().min(1).max(120000), publishedAt: z.string(), runId: id,
-  basisKnowledgeRevision: z.number().int(), clues: z.array(clueSchema).max(128), sources: z.array(sourceSchema).max(1024) })
 const inboxEntrySchema = z.object({ source_id: id, note: z.string().max(600),
   status: z.enum(['pending', 'promoted', 'removed']), addedBy: z.enum(['agent', 'user']),
   addedAt: z.string(), updatedAt: z.string(), removedBy: z.enum(['agent', 'user']).optional(), clueIds: z.array(id).max(128) })
-const boardSchema = z.object({ id, title: z.string().min(1).max(120), objective: z.string().min(1).max(2000),
+const boardStateSchema = z.object({ id, title: z.string().min(1).max(120), objective: z.string().min(1).max(2000),
   createdAt: z.string(), updatedAt: z.string(), knowledgeRevision: z.number().int().nonnegative(), layoutRevision: z.number().int().nonnegative(),
-  clues: z.array(clueSchema).max(512), relations: z.array(relationSchema).max(1024), reports: z.array(reportSchema).max(128),
+  clues: z.array(clueSchema).max(512), relations: z.array(relationSchema).max(1024),
   evidenceInbox: z.array(inboxEntrySchema).max(512).default([]), inboxRevision: z.number().int().nonnegative().default(0),
   openQuestions: z.array(z.string().max(500)).max(32), nextClue: z.number().int().positive(),
 })
+const reportSchema = z.object({ id, version: z.number().int().positive(), title: z.string().min(1).max(180),
+  summary: z.string().max(1000), markdown: z.string().min(1).max(120000), publishedAt: z.string(), runId: id,
+  basisKnowledgeRevision: z.number().int(), clues: z.array(clueSchema).max(128), sources: z.array(sourceSchema).max(4096),
+  boardSnapshot: boardStateSchema.extend({ sources: z.array(sourceSchema).max(4096) }).optional() })
+const boardSchema = boardStateSchema.extend({ reports: z.array(reportSchema).max(128) })
 const runSchema = z.object({ id, boardId: id, turnId: short, reason: z.string().max(500), startedAt: z.string(),
   status: z.enum(['running', 'completed', 'interrupted', 'error']), endedAt: z.string().optional() })
 export const portfolioSchema = z.object({ schemaVersion: z.literal(1), sessionId: id, commitSeq: z.number().int().nonnegative(),
@@ -75,7 +80,7 @@ function requireRun(portfolio, boardId, runId, turnId) {
   requireValue(run?.boardId === boardId && run.status === 'running' && run.turnId === String(turnId ?? ''), '本次运行未绑定到这块调查板，或已经结束；请重新选择调查', 'INVESTIGATION_RUN_MISMATCH')
   return run
 }
-function sourceIdentity(source) { return source.documentUid || source.documentId ? JSON.stringify([source.dataVersion || '', source.documentUid || source.documentId]) : source.url ? `url:${source.url.replace(/#.*$/, '')}` : source.sourceId || source.id }
+function sourceIdentity(source) { return source.documentUid || source.documentId ? JSON.stringify([source.dataVersion || '', source.documentUid || source.documentId]) : source.url ? `url:${source.url.replace(/#.*$/, '')}` : `id:${JSON.stringify([source.dataVersion || '', source.sourceId || source.id])}` }
 function uniqueRanges(values) {
   return [...new Map(values.filter(r => Number.isSafeInteger(r?.start) && r.start > 0 && Number.isSafeInteger(r.end) && r.end >= r.start).map(r => [`${r.start}:${r.end}`, { start: r.start, end: r.end }])).values()].slice(-256)
 }
@@ -84,7 +89,7 @@ function normalizeSource(source, alias, callId, trusted) {
   const body = bounded(source.content, 64000)
   return sourceSchema.parse({ id: alias, sourceId: bounded(source.sourceId || source.id, 512), title: bounded(source.title),
     kind: bounded(source.kind || 'source', 80), origin: ['local', 'cloud', 'web'].includes(source.origin) ? source.origin : 'local',
-    state: read ? 'read' : 'found', agentRead: read, excerpt: bounded(source.excerpt, 4000), ...(body ? { content: body } : {}),
+    state: read ? 'read' : 'found', agentRead: read, agentReceived: trusted, excerpt: bounded(source.excerpt, 4000), ...(body ? { content: body } : {}),
     contentTruncated: !!source.contentTruncated || typeof source.content === 'string' && source.content.length > 64000,
     ...Object.fromEntries(['documentId', 'documentUid', 'sourceRef', 'dataVersion'].filter(key => typeof source[key] === 'string' && source[key]).map(key => [key, bounded(source[key], key === 'dataVersion' ? 128 : key === 'documentUid' ? 512 : 2048)])),
     ...(safeUrl(source.url) ? { url: safeUrl(source.url) } : {}),
@@ -94,19 +99,40 @@ function normalizeSource(source, alias, callId, trusted) {
     callId: bounded(callId), updatedAt: now(), contentHash: hash(body || bounded(source.excerpt, 4000)),
   })
 }
+function readingFragments(source) {
+  if (!source?.agentRead) return []
+  if (source.fragments?.length) return source.fragments
+  const content = source.content || source.excerpt
+  if (!content) return []
+  // A legacy body belongs to its last read page, not to the union of past ranges.
+  const ranges = source.lineStart ? [{ start: source.lineStart, end: source.lineEnd || source.lineStart }]
+    : source.ranges?.length === 1 ? source.ranges : []
+  return [{ content, ranges, callId: source.callId }]
+}
+function mergeReadingFragments(previous, item) {
+  const fragments = [...new Map([...readingFragments(previous), ...readingFragments(item)]
+    .map(f => [hash([f.content, f.ranges]), f])).values()]
+  requireValue(fragments.length <= 256 && fragments.reduce((n, f) => n + f.content.length, 0) <= 512000,
+    '这份资料的已读片段已达保存上限；已有片段保留，本次阅读尚未保存', 'INVESTIGATION_CAPACITY')
+  return fragments
+}
+function sourceMetadata({ content, fragments, ...source }) { return clone(source) }
 function ingestSources(portfolio, incoming, callId, trusted) {
   const aliases = {}
   for (const raw of incoming.slice(0, 128)) {
     if (!raw?.title || !(raw.id || raw.sourceId)) continue
     const identity = sourceIdentity(raw)
-    const previous = portfolio.sources.find(source => sourceIdentity(source) === identity || source.sourceId === (raw.sourceId || raw.id))
+    const previous = portfolio.sources.find(source => sourceIdentity(source) === identity
+      || !raw.documentUid && !raw.documentId && !raw.url && source.dataVersion === raw.dataVersion
+        && source.sourceId === (raw.sourceId || raw.id))
     if (!previous) requireValue(portfolio.sources.length < 4096, '当前会话来源记录已满；已保存的资料不会删除', 'INVESTIGATION_CAPACITY')
     const item = normalizeSource(raw, previous?.id || `R${String(portfolio.nextSource++).padStart(4, '0')}`, callId, trusted)
+    item.fragments = mergeReadingFragments(previous, item)
     aliases[raw.sourceId || raw.id] = item.id
     if (previous) {
       // A later search hit must not turn a read source back into a summary.
       const preferOld = previous.agentRead && !item.agentRead
-      Object.assign(previous, { ...item, ...preferOld ? { state: previous.state, agentRead: true,
+      Object.assign(previous, { ...item, agentReceived: receivedByAgent(previous) || item.agentReceived, ...preferOld ? { state: previous.state, agentRead: true,
         excerpt: previous.excerpt, content: previous.content, contentTruncated: previous.contentTruncated, contentHash: previous.contentHash,
         callId: previous.callId } : {}, ranges: uniqueRanges([...previous.ranges, ...item.ranges]) })
     } else portfolio.sources.push(item)
@@ -117,19 +143,37 @@ function resolveReferences(portfolio, incoming) {
   requireValue(Array.isArray(incoming) && incoming.length <= 32, 'sources 必须是最多 32 项的来源引用列表')
   return incoming.map(raw => {
     const ref = referenceSchema.parse(raw)
-    const source = portfolio.sources.find(row => row.id === ref.source_id || row.sourceId === ref.source_id || row.documentUid === ref.source_id)
+    const direct = portfolio.sources.find(row => row.id === ref.source_id)
+    const aliases = direct ? [direct] : portfolio.sources.filter(row => row.sourceId === ref.source_id || row.documentUid === ref.source_id)
+    requireValue(aliases.length <= 1, `来源 ${ref.source_id} 对应多个数据版本，请使用来源目录中的 R 编号`, 'INVESTIGATION_SOURCE_AMBIGUOUS')
+    const source = aliases[0]
     requireValue(source, `来源 ${ref.source_id} 未在当前会话返回；用 investigation_get 的 sources 部分查看有效 ID`, 'INVESTIGATION_SOURCE_MISSING')
     if (ref.line_start || ref.line_end) {
       requireValue(ref.line_start && ref.line_end && ref.line_end >= ref.line_start, '引用行范围不完整')
-      requireValue(source.agentRead && source.ranges.some(r => r.start <= ref.line_start && r.end >= ref.line_end), '引用的行范围不在实际已读范围内', 'INVESTIGATION_SOURCE_UNREAD')
+      if (!source.agentRead || !source.ranges.some(r => r.start <= ref.line_start && r.end >= ref.line_end)) {
+        throw investigationError('INVESTIGATION_SOURCE_UNREAD', '引用的行范围不在实际已读范围内', sourceRecovery(source, ref))
+      }
+    }
+    if (ref.quote) {
+      const fragments = readingFragments(source)
+      const bodies = fragments.length ? fragments.filter(f => !ref.line_start
+        || f.ranges.some(r => r.start <= ref.line_start && r.end >= ref.line_end)).map(f => f.content)
+        : [source.content || source.excerpt]
+      let original = null
+      for (const body of bodies) {
+        original = originalQuotation(body, ref.quote)
+        if (original !== null) break
+      }
+      if (original === null) throw investigationError('INVESTIGATION_QUOTE_MISMATCH',
+        `来源 ${source.id} 的摘录不在保存的对应片段内；请读取对应原文或修正引文`, sourceRecovery(source, ref))
+      ref.quote = original
     }
-    if (ref.quote) requireValue((source.content || source.excerpt).includes(ref.quote), '摘录不在保存的返回片段内；请先读取对应原文或去掉直接引文', 'INVESTIGATION_QUOTE_MISMATCH')
     return { ...ref, source_id: source.id }
   })
 }
 function cluePatch(portfolio, board, change, actor, mapping) {
   const previous = change.id ? board.clues.find(row => row.id === change.id) : undefined
-  requireValue(!change.id || previous, `线索 ${change.id} 不存在`, 'INVESTIGATION_CLUE_MISSING')
+  requireValue(!change.id || previous, `线索 ${change.id} 不存在；新建请省略 id、使用 client_key，后续更新使用 returned created_ids`, 'INVESTIGATION_CLUE_MISSING')
   const action = change.action || 'upsert'
   if (action === 'layout') {
     requireValue(previous, '布局修改需要已有线索')
@@ -236,9 +280,19 @@ export function createInvestigationStore(storageDomain) {
           tables: { portfolios: { valueSchema: portfolioSchema } } })
         const table = domain.table('portfolios')
         if (!table.get('state')) await table.put('state', freshPortfolio(sessionId))
-        // No live run survives a process/service restart. Preserve its partial work.
-        if (table.get('state').runs.some(run => run.status === 'running')) await table.update('state', current => {
-          const next = clone(current)
+        // Upgrade provenance without discarding old tool deliveries or trusting browser imports.
+        // Receipt aliases also recover a found source later edited from the browser.
+        if (table.get('state').sources.some(source => source.agentReceived === undefined)
+          || table.get('state').runs.some(run => run.status === 'running')) await table.update('state', current => {
+          const next = portfolioSchema.parse(clone(current))
+          const delivered = new Set(Object.values(next.mutations).flatMap(({ result }) =>
+            result?.sources && !Array.isArray(result.sources) ? Object.values(result.sources) : []))
+          let upgraded = false
+          for (const source of next.sources) if (source.agentReceived === undefined) {
+            source.agentReceived = delivered.has(source.id) || receivedByAgent(source); upgraded = true
+          }
+          if (upgraded) next.rackRevision++
+          // No live run survives a process/service restart. Preserve its partial work.
           for (const run of next.runs) if (run.status === 'running') { run.status = 'interrupted'; run.endedAt = now() }
           next.commitSeq++; return next
         })
@@ -292,12 +346,12 @@ export function createInvestigationStore(storageDomain) {
         const offset = Math.max(0, Number(cursor) || 0), count = Math.min(128, Math.max(1, Number(limit) || 20))
         return { commitSeq: p.commitSeq, rackRevision: p.rackRevision, workingBoardId: working?.boardId || null, boards: rows.slice(offset, offset + count).map(b => boardSummary(b, p)), nextCursor: rows.length > offset + count ? offset + count : null }
       }
-      if (section === 'sources') return { commitSeq: p.commitSeq, sources: p.sources.slice(-Math.min(128, Number(limit) || 40)).map(({ content, ...source }) => clone(source)) }
+      if (section === 'sources') return { commitSeq: p.commitSeq, sources: p.sources.slice(-Math.min(128, Number(limit) || 40)).map(sourceMetadata) }
       const board = boardOf(p, board_id)
       if (section === 'inbox') {
         const items = pendingEvidence(board), offset = Math.max(0, Number(cursor) || 0), count = Math.min(128, Math.max(1, Number(limit) || 20))
         return { board_id: board.id, title: board.title, inbox_revision: board.inboxRevision, pending_count: items.length,
-          items: items.slice(offset, offset + count).map(item => { const { content, ...source } = p.sources.find(s => s.id === item.source_id); return { ...clone(item), source: clone(source) } }),
+          items: items.slice(offset, offset + count).map(item => { const source = p.sources.find(s => s.id === item.source_id); return { ...clone(item), source: sourceMetadata(source) } }),
           nextCursor: items.length > offset + count ? offset + count : null }
       }
       return { commitSeq: p.commitSeq, workingBoardId: working?.boardId || null, ...boardSummary(board, p), board: clone(board),
@@ -375,7 +429,18 @@ export function createInvestigationStore(storageDomain) {
         requireValue(board.knowledgeRevision === args.expected_revision, '调查内容已更新，请用 investigation_get 重读后提交', 'INVESTIGATION_CONFLICT')
         requireValue(Array.isArray(args.clues || []) && (args.clues || []).length <= 20, '每次更新最多 20 条线索')
         const mapping = {}, updated = []
-        for (const change of args.clues || []) updated.push(cluePatch(p, board, change, 'agent', mapping).id)
+        const issues = []
+        for (const [index, change] of (args.clues || []).entries()) {
+          try { updated.push(cluePatch(p, board, change, 'agent', mapping).id) }
+          catch (error) {
+            if (!error.code && !(error instanceof z.ZodError)) throw error
+            issues.push({ clue_index: index, clue: change.id || change.client_key || change.title,
+              code: error.code || 'INVALID_INVESTIGATION', message: error.message, ...error.details })
+          }
+        }
+        if (issues.length) throw investigationError(issues[0].code,
+          `本批更新未保存，revision 仍为 ${args.expected_revision}。修正以下线索后重试；不要重复提交未修正的整批正文。\n${JSON.stringify({ issues })}`,
+          { applied: false, revision: args.expected_revision, issues })
         const resolveId = value => mapping[value] || value
         requireValue(Array.isArray(args.relations || []) && (args.relations || []).length <= 32, '每次更新最多 32 条关系')
         for (const raw of args.relations || []) {
@@ -445,10 +510,13 @@ export function createInvestigationStore(storageDomain) {
         requireValue(board.knowledgeRevision === args.expected_revision, '有新线索尚未纳入报告，请重读调查后发布', 'INVESTIGATION_CONFLICT')
         requireValue(Array.isArray(args.clue_ids) && args.clue_ids.length <= 128, 'clue_ids 必须列出报告使用的线索')
         const cited = [...new Set(args.clue_ids)].map(value => { const clue = board.clues.find(c => c.id === value); requireValue(clue && !['retracted', 'superseded'].includes(clue.status), `报告引用的线索 ${value} 已不可用`); return clone(clue) })
-        const sources = p.sources.filter(s => cited.some(c => c.sources.some(ref => ref.source_id === s.id))).map(s => { const copy = clone(s); delete copy.content; return copy })
+        const sources = p.sources.filter(s => cited.some(c => c.sources.some(ref => ref.source_id === s.id))).map(sourceMetadata)
+        const boardSnapshot = boardStateSchema.parse(clone(board))
+        boardSnapshot.sources = p.sources.filter(s => board.clues.some(c => c.sources.some(ref => ref.source_id === s.id))
+          || board.evidenceInbox.some(item => item.source_id === s.id)).map(sourceMetadata)
         const report = reportSchema.parse({ id: `report-${randomUUID()}`, version: board.reports.length + 1, title: args.title,
           summary: args.summary, markdown: args.markdown, publishedAt: now(), runId: args.run_id,
-          basisKnowledgeRevision: board.knowledgeRevision, clues: cited, sources })
+          basisKnowledgeRevision: board.knowledgeRevision, clues: cited, sources, boardSnapshot })
         board.reports.push(report); board.updatedAt = now()
         return { board_id: board.id, report_id: report.id, version: report.version, title: report.title, revision: board.knowledgeRevision,
           message: '调查报告已保存到线索板中央。向用户说明结果即可，不必再次生成一份不同的全文。' }
@@ -533,7 +601,11 @@ export function createInvestigationStore(storageDomain) {
     },
     recordSources(sessionId, sources, callId) {
       if (!sources.length) return Promise.resolve()
-      const pending = mutate(sessionId, `sources:${callId}`, sources, p => ({ sources: ingestSources(p, sources, callId, true) }))
+      const pending = mutate(sessionId, `sources:${callId}`, sources, p => {
+        const aliases = ingestSources(p, sources, callId, true)
+        if (Object.keys(aliases).length) p.rackRevision++
+        return { sources: aliases }
+      })
       const previous = pendingReceipts.get(sessionId) || Promise.resolve()
       const settled = Promise.allSettled([previous, pending]).then(() => {})
       pendingReceipts.set(sessionId, settled)