prts-terrarchive 0.2.0

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

@@ -0,0 +1,34 @@
+# 双模块检索配方
+
+以下流程只在明日方舟和终末地同时启用时使用。
+
+问题已经明确属于一款游戏时，按对应模块的资料类型做单游戏检索，不必先联合搜索。已知短原句或专名用 `corpus_search`，情节、动机或多资料关系用 `cloud_search` 发现候选，精确结论再回读原文。
+
+## 比较两款游戏中的人物、组织或概念
+
+1. 把比较维度写清楚；可先联合调用默认 `cloud_search` 发现候选。
+2. 分别执行 `games:["arknights"]` 与 `games:["endfield"]` 的窄检索，使用各自模块的资料类型，不能用同一个类型数组硬套两边。
+3. 各自形成“该游戏资料明示的事实”，再做比较；共同点和差异属于综合结论，不冒充任一侧原文。
+
+## 再旅者与泰拉记忆原型
+
+1. 分别确认两个实体的规范名称和游戏归属。
+2. 对任一规范名做检索；结果带 `retraveler_relations` 时，可以将其中的对应关系表述为“PRTS 人工审校关系表登记”，无需强求游戏剧情重复证明该登记。
+3. 分别检索双方资料来回答各自身份、经历与表现；不要从登记关系外推同一人物、记忆继承方式或剧情确认程度。
+4. 没有 `retraveler_relations`，只有外观、同名或相似经历时，只能说明相似或尚未确认，不能自行建立关系或别名。
+
+## 不确定问题属于哪款游戏
+
+1. 用短专名执行联合 `corpus_search`，或用完整问题执行联合 `cloud_search`。
+2. 根据结果的 `game`、资料标题和实体路由确定归属。
+3. 归属明确后切换为单游戏范围继续，不让另一侧噪声进入后续核验。
+
+## 联合检索只返回一侧
+
+1. 检查是否出现 `CORPUS_GAME_NOT_INSTALLED`，以及过滤类型是否只属于其中一款游戏。
+2. 如果问题要求完整比较，分别使用两边合法类型再检索一次。
+3. 仍无一侧证据时明确报告缺口；不要用另一侧材料填补，也不要把零命中写成不存在。
+
+## 双侧时间或剧情对照
+
+明日方舟侧使用 `timeline_search` 或 `story`，终末地侧使用 `resource_types:["timeline"]` 或 `original_story`。先各自建立内部顺序，再比较主题或叙事结构；除非资料明确提供共同纪年关系，不把两套时间直接拼成同一绝对时间轴。

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

@@ -0,0 +1,37 @@
+# 终末地检索配方
+
+以下流程只在终末地模块启用时使用，并始终带 `games:["endfield"]`。
+
+## 任务或剧情过程
+
+1. 已知任务名且要连续阅读时，直接用 `corpus_read({collection_name:任务名, mode:"collection"})`；同名歧义时用 `collection_names` 配合 `resource_types:["original_story"]` 搜索具体篇章，再以返回的 `document_uid + mode:"collection"` 选定合集。要定位某个片段时也先按该集合搜索；只知道大概情节时先用默认 `cloud_search`。
+2. 用 `content_types` 区分对话、过场、广播、远程通讯、环境对话或 SNS，避免不同表现形式的同词混在一起。
+3. 对行动、指代、态度和因果，用命中标题与行号读取连续上下文。
+
+## 台词、广播或通讯
+
+1. 确切短句：搜索 `original_story`，并在已知表现形式时增加对应 `content_types`。
+2. 查询某人亲口表达时使用 `speakers`；只要求出现某实体时使用 `entity_names`。
+3. 只记得一句话大意时使用 `single_sentence_search`，再回读原文。
+
+## 人物综合资料
+
+1. 用 `entity_profile` 或默认云端检索建立人物和关联资料入口。
+2. 身份、经历或机构记录优先查 `archive`；角色叙事查 `character_story`；实际剧情表现查 `original_story`。
+3. 若 `knowledge/wiki` 提供概括，只按其资料等级表述；具体行动和原话回到 `original_story`。
+
+## 设定、地点或组织
+
+1. 正式名称明确时先查 `archive/knowledge/entity_profile`。
+2. 涉及多个实体关系或事件过程时用默认 `cloud_search` 建立候选，再用本地正式资料确认定义。
+3. 若结论来自剧情中的展示而不是档案定义，补读 `original_story` 上下文并区分两者。
+
+## 时间与事件顺序
+
+1. 使用 `corpus_search({games:["endfield"], resource_types:["timeline"], query:事件或实体})`；可配合 `collection_names`。
+2. 时间线只支持整理性顺序；具体事件发生方式仍查 `original_story`。
+3. 不调用明日方舟专用的 `timeline_search` 来推断终末地没有相关事件。
+
+## 查找某类资料目录
+
+省略 `query`，用一个或少量 `resource_types` 加 `character_names/collection_names` 列出入口。正式标题命中优先打开对应档案，不被普通剧情中的同词提及带走。

package/skills/prts-retrieval/references/retrieval-recipes.md

@@ -0,0 +1,39 @@
+# 明日方舟检索配方
+
+以下流程只在明日方舟模块启用时使用，并始终带 `games:["arknights"]`。
+
+## 角色与活动参与关系
+
+1. 角色→活动：省略 `query`，调用 `corpus_search({games:["arknights"], resource_types:["character_activity_wiki"], character_names:[角色]})`，从结果的 `activity_name` 整理活动。
+2. 活动→角色：省略 `query`，调用 `corpus_search({games:["arknights"], resource_types:["character_activity_wiki"], activity_names:[活动]})`，从结果的 `character_name` 整理角色。
+3. 角色×活动：省略 `query`，调用 `corpus_search({games:["arknights"], resource_types:["character_activity_wiki"], character_names:[角色], activity_names:[活动]})`；不同过滤字段取精确交集，可用于确认这对关系并读取对应辅助页。
+4. 完整清单或确认零命中时，保留原条件并原样提交 `page.next_after`，直到 `page.exhausted=true`，再按角色名或活动名去重。穷尽后仍无结果只表示当前资料版本没有该角色×活动整理记录；不得移除一个过滤条件后把任一侧的单独命中当作参与关系，也不能据此断言剧情中绝无参与。
+
+## 某角色在某活动中的作用
+
+1. 查 `story_wiki + activity_names + wiki_sections:["角色剧情概括"] + query:角色`。
+2. 需要更细过程时，查 `character_activity_wiki + character_names + activity_names + wiki_sections:["相关剧情总结"]`。
+3. 需要具体行动、说话人或因果时，以活动和角色为范围搜索 `story/operator_record`，再读取命中上下文。
+
+## 某活动的整体研究
+
+1. 默认 `cloud_search` 建立事件和人物骨架；若只需现成概括，直接读 `story_wiki` 的 `剧情总结`。
+2. 读 `关键人物` 建立人物集合，按需读取目标人物的 `角色剧情概括`。
+3. 用 `timeline_search(activity_names:[活动])` 补时间位置。
+4. 只对会影响结论的关键事件回到官方原文；用户明确要求完整顺读时才用 `corpus_read({activity_name:活动, mode:"activity"})`。
+
+## 人物关系
+
+1. 默认 `cloud_search` 搜索双方、关系和关键事件。
+2. 分别读取双方 `character_wiki` 的 `相关角色`，检查是否双向出现及叙述是否一致。
+3. 对关系起因、变化、冲突或态度，按云端映射或活动线索读取 `story/operator_record` 原文。
+
+## 台词与说话人
+
+1. 确切短句：`corpus_search({games:["arknights"], query:短句, resource_types:["story","operator_record"]})`。
+2. 查询某人亲口说的话时加 `speakers:[角色]`；查询谈及某人时才用 `entity_names`。
+3. 只记得大意时走 `single_sentence_search`，随后以返回标题和行号读取上下文。
+
+## 人物综合资料
+
+先用角色 Wiki 的 `简要介绍/详细介绍/相关活动` 建立骨架；身份和身体资料查 `character_profile`，补充经历查 `character_module/operator_record`，原话与称呼查 `character_voice/story`。只核验实际用于回答的结论。

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

@@ -0,0 +1,48 @@
+# 当前工具契约
+
+## `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`；资料版本切换后旧锚点会被拒绝，须从首屏重新搜索。
+
+## `corpus_read`
+
+- 明日方舟单篇关卡：`{stage_code:"TW-ST-1"}`；同代号存在多篇时加 `story_part:"before"|"after"|"story"`。提供 `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`。
+- 其他资料定点上下文：`{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`。
+
+每次只选一种主定位方式：`title`、`document_uid`、`stage_code`（可带 `story_part`）、角色密录组合、角色资料组合、`activity_name` 或 `collection_name`。`max_lines/max_chars` 只限制输出量，不会选择读取方式；裸 `title` 不能只配这两个限制字段。
+
+稳定定位字段已经足够时直接读取，不要先搜索标题。合集结果的每行都带所属篇章标题和篇内行号，应按它们引用。工具返回歧义时收窄条件，不能猜第一篇。新调用不要创建 cursor；旧会话已有 cursor 时才使用兼容入口。
+
+## `corpus_i18n`
+
+查询终末地官方本地化文本，不生成翻译。主定位四选一：`query`、`title`、`document_uid`、`text_ids`；必须指定 `languages`（1–4 种）。有原文定位时优先 `{title, line, languages:["EN","JP"]}` 或 `{document_uid, line, languages:["EN"]}`；仅有名称/原句时用 `{query, languages:["EN"]}`。`source_language` 默认 `CN`，外语反查可用 `EN/JP/KR` 或 `en/ja/ko`。`query` 默认精确匹配，短片段加 `match_mode:"literal"`。
+
+默认无需请求底层 ID。需要核验时才设 `include_ids:true`，返回的 `text_id` 必须当作字符串使用，后续可传 `text_ids`。同文不同译保留候选，按 references 中的篇章和中文定位消歧，不能任选第一个。每个结果最多列出 8 个引用；`reference_count` 表示总数。
+
+`alignment:"record"` 是整条角色档案，`alignment:"document"` 是档案库内容块；不保证各语言段落一一对应。引用注明工具返回的篇章、语言和中文定位，不能把中文第 N 行说成英文第 N 行。长文本按字符分块，`character_start/end` 是该语言自己的位置，不表示译文逐字符对应；续页原样提交 `page.continuation`。
+
+`missing_localization` 表示该语言官方文本为空；`unmapped_source` 表示没有建立来源映射；`unavailable` 表示附件/语言未安装。均不能自行翻译后当成官方文本。旧资料包仍能正常搜索和阅读，但需要安装带本地化附件的版本才能使用此工具。
+
+## `timeline_search`
+
+可用 `query`、`activity_names`、`entity_names`、`year_start`、`year_end`、`source_marker`、`max_results`。`entity_names` 会展开别名；不同维度取交集。`source_marker` 仅用于反查来源，不写入回答。
+
+## `cloud_search`
+
+模型可见参数只有 `query`、`games`、兼容字段 `depth`、`evidence_policy`，以及可选的 `options.search_intent="single_sentence_search"`。不要发送 channels、filters、阈值、候选预算、`quote_search` 或 `scene_search`。
+
+默认省略 `depth/options` 并使用 `evidence_policy="mixed"`。只有一句官方剧情原文的大意且措辞可能不准时使用 `single_sentence_search`；`original_only` 会切到仅官方剧情原文的向量路线。结果末尾的可读取标题与行号可直接交给 `corpus_read`。
+
+## `cloud_inspect`
+
+仅在云端结果截断、来源不清或诊断召回时使用。通常省略 `request_id`，运行时会关联最近一次云端请求；按返回的整数 `next_cursor` 分页。优先查看 `selected_sources` 或 `answer_context`，诊断时再看 `candidates/events/trace_steps`。

package/skills/prts-retrieval/references/wiki-schema.md

@@ -0,0 +1,38 @@
+# Wiki 资料结构
+
+本地 `reviewed_wiki` 不是一种同质资料，而是三类经过整理的语义骨架。优先选择窄类型，不要一开始就搜索全部 Wiki。
+
+## 规范角色页：character_wiki
+
+一名角色通常对应一页，使用 `character_names` 精确定位。
+
+- `简要介绍`：身份、阵营与核心经历的短概览，适合“这个人是谁”。
+- `相关角色`：主要人物关系及关系性质，适合关系入口；复杂关系仍需双向页面、图谱或原文交叉检查。
+- `详细介绍`：跨活动的完整经历与阶段变化，适合人物生平和动机分析。
+- `剧情高光`：重要场面及整理出处，适合发现值得回查的剧情叶片。
+- `战斗表现`：能力、战斗与战术表现；可组合官方档案、模组和原文。
+- `相关活动`：角色参加的活动及其作用，是“参加过哪些活动”的首选字段。
+- `trivia`：轶事和细节，属于整理性证据。
+- `角色点评`：综合评价，主观性最高；不得当成原文明示事实。
+
+## 活动／密录页：story_wiki
+
+使用 `activity_names` 按展示名定位；密录也沿用其故事展示名。
+
+- `剧情总结`：整部活动、主线章节或密录的结构、因果和结局。
+- `剧情高光`：重要场面和代表性表达；精确台词必须回原文。
+- `关键人物`：人物清单，适合建立后续查询集合。
+- `角色剧情概括`：逐角色说明其在该活动中的行动和作用，适合“某人在某活动做了什么”。
+- `trivia`：活动中的设定细节与轶事。
+
+## 角色×活动辅助页：character_activity_wiki
+
+它保存某一角色在某一活动中的 `相关剧情总结、相关剧情高光、相关trivia、相关角色总结`，可同时使用 `character_names` 和 `activity_names` 过滤。
+这是生成规范角色页时使用的辅助整理材料，适合补充过程或定位线索；证据地位低于规范角色页和活动页，更不能替代官方原文。
+
+## 范围与证据
+
+- Wiki 标签字段是审核或整理资料，可以直接回答概括、清单和导航问题。
+- `相关活动` 表示资料整理认定的剧情参与，不等于角色在每一篇原文中都亲自出场。
+- `剧情总结` 和 `角色剧情概括` 可能覆盖完整活动，不能套用到单一场景。
+- 用户要求逐字台词、说话人、场景细节或行号时，必须沿 Wiki 提供的活动/篇章线索回到 `story` / `operator_record` 原文。

package/src/archive-presentation.js

@@ -0,0 +1,287 @@
+/** Bounded, durable UI material records. Never include a raw remote response or host paths. */
+import { createHash } from 'node:crypto'
+import { documentUid } from './store.js'
+import { projectCloudSearch } from './cloud-projection.js'
+
+const MAX_SOURCES = 128
+const MAX_EXCERPT = 1600
+const text = (value, max = MAX_EXCERPT) => typeof value === 'string' ? value.slice(0, max) : ''
+const version = (value) => /^[a-f0-9]{64}$/u.test(value || '') ? value : undefined
+const idFor = (origin, dataVersion, identity) => `${origin}:${createHash('sha256')
+  .update(JSON.stringify([dataVersion || '', identity])).digest('hex').slice(0, 32)}`
+const localId = (dataVersion, documentId) => `document:${dataVersion}:${documentUid(documentId)}`
+const range = (start, end = start) => Number.isSafeInteger(Number(start)) && Number(start) > 0
+  && Number.isSafeInteger(Number(end)) && Number(end) >= Number(start)
+  ? { start: Number(start), end: Number(end) } : null
+const rangesFor = (values) => [...new Map(values.filter(Boolean)
+  .map((value) => [`${value.start}:${value.end}`, value])).values()].slice(0, 128)
+const locations = (ranges) => ranges.length ? {
+  lineStart: ranges[0].start, lineEnd: ranges[0].end, ranges,
+} : {}
+
+function envelope(sources, dataVersion) {
+  return { kind: 'prts-archive-sources-v1', sources: sources.slice(0, MAX_SOURCES),
+    ...(version(dataVersion) ? { data_version: dataVersion } : {}),
+    ...(sources.length > MAX_SOURCES ? { sources_truncated: true } : {}) }
+}
+
+/** Capture at execution time: later release switches cannot relabel old tool results. */
+export function rememberArchivePresentation(value, metadata) {
+  // DSH snapshots the tool value before rendering; a WeakMap/non-enumerable
+  // attachment would disappear. Renderers deliberately ignore this UI field.
+  return { ...value, presentation: metadata }
+}
+
+export function archivePresentationMeta(_args, value) {
+  if (value?.status === 'error' || value?.error) return { ...envelope([]),
+    error: text(value?.error?.message || value?.error, 600) || '资料检索未完成' }
+  return value?.presentation?.kind === 'prts-archive-sources-v1'
+    ? value.presentation : envelope([])
+}
+
+const PTC_RECEIPT_TYPE = 'prts-archive-receipt'
+const PTC_TOOLS = new Set(['corpus_search', 'corpus_read', 'timeline_search', 'cloud_search', 'cloud_inspect'])
+const MAX_RECEIPT_BYTES = 512 * 1024
+const MAX_PENDING_BYTES = 2 * 1024 * 1024
+const MAX_PENDING_CALLS = 64
+const PENDING_LIFETIME_MS = 5 * 60 * 1000
+const receiptIdentity = (value, max = 1024) => typeof value === 'string' && value.length <= max ? value : ''
+
+/** Keep the log extension as bounded as the native presentationMeta contract. */
+function boundedReceiptMeta(value) {
+  if (!value || !['prts-archive-sources-v1', 'prts-corpus-read-v1'].includes(value.kind)) return null
+  const dataVersion = version(value.data_version)
+  if (value.kind === 'prts-corpus-read-v1') {
+    const documentId = receiptIdentity(value.locator?.document_id)
+    if (!documentId || !dataVersion) return null
+    const primaryRange = range(value.line_start, value.line_end)
+    return { kind: value.kind, locator: { document_id: documentId }, data_version: dataVersion,
+      title: text(value.title, 512),
+      ...(primaryRange ? { line_start: primaryRange.start, line_end: primaryRange.end } : {}),
+      sources: (Array.isArray(value.sources) ? value.sources : []).slice(0, MAX_SOURCES).flatMap((source) => {
+        const id = receiptIdentity(source?.document_id)
+        const selected = range(source?.line_start, source?.line_end)
+        if (!id || !selected) return []
+        return [{ document_id: id, document_uid: documentUid(id), title: text(source.title, 512),
+          line_start: selected.start, line_end: selected.end }]
+      }), ...(value.sources_truncated ? { sources_truncated: true } : {}) }
+  }
+  const sources = (Array.isArray(value.sources) ? value.sources : []).slice(0, MAX_SOURCES).flatMap((source) => {
+    const id = receiptIdentity(source?.id), title = text(source?.title, 512)
+    if (!id || !title) return []
+    const selected = rangesFor((Array.isArray(source.ranges) ? source.ranges : []).slice(0, MAX_SOURCES)
+      .map((item) => range(item?.start, item?.end)))
+    const first = range(source.lineStart, source.lineEnd)
+    const sourceVersion = version(source.dataVersion)
+    const url = safeUrl(source.url)
+    return [{ id, title, kind: text(source.kind, 80),
+      origin: ['local', 'cloud', 'web'].includes(source.origin) ? source.origin : 'local',
+      state: ['found', 'read', 'cited'].includes(source.state) ? source.state : 'found',
+      excerpt: text(source.excerpt), ...(source.agentRead === true ? { agentRead: true } : {}),
+      ...(receiptIdentity(source.documentId) ? { documentId: source.documentId } : {}),
+      ...(receiptIdentity(source.documentUid, 128) ? { documentUid: source.documentUid } : {}),
+      ...(receiptIdentity(source.sourceRef) ? { sourceRef: source.sourceRef } : {}),
+      ...(sourceVersion ? { dataVersion: sourceVersion } : {}), ...(url ? { url } : {}),
+      ...locations(selected.length ? selected : first ? [first] : []),
+      ...(Array.isArray(source.readRanges) ? { readRanges: rangesFor(source.readRanges.slice(0, MAX_SOURCES)
+        .map((item) => range(item?.start, item?.end))) } : {}) }]
+  })
+  return { ...envelope(sources, dataVersion),
+    ...(value.sources_truncated ? { sources_truncated: true } : {}),
+    ...(typeof value.error === 'string' && value.error ? { error: text(value.error, 600) } : {}) }
+}
+
+/**
+ * DSH 0.1.5 omits presentationMeta on nested run_code dispatches. Observe the
+ * final, frozen value synchronously, then attach a structured ContentBlock only
+ * to tools/ptc-dispatch-log. That official seam changes the human log copy;
+ * deriveMessages ignores these events, and neither render() nor the value
+ * delivered to the running program/model is changed. No identity is inferred
+ * from the rendered prose. ContentBlock is a merge-extensible host contract.
+ */
+export function installArchivePtcReceipts(ctx, readMetadata) {
+  if (typeof ctx.on !== 'function') return false
+  let pending = new WeakMap()
+  let disposed = false
+  const drop = (state, key) => {
+    const item = state.items.get(key)
+    if (!item) return
+    state.bytes -= item.bytes
+    state.items.delete(key)
+  }
+  ctx.on('tools/result', (exec, result) => {
+    if (disposed || exec?.parent === undefined || !exec.agent || typeof exec.agent !== 'object'
+        || !PTC_TOOLS.has(exec.name)) return
+    const callId = String(exec.callId || '')
+    if (!callId || callId.length > 512) return
+    let state = pending.get(exec.agent)
+    if (state) drop(state, callId)
+    if (result?.isError || !result?.value) return
+    let meta, bytes
+    try {
+      const failed = result.value.error || result.value.status === 'error'
+      const metadata = exec.name === 'corpus_read' && !failed
+        ? readMetadata(exec.arguments, result.value)
+        : archivePresentationMeta(exec.arguments, result.value)
+      meta = boundedReceiptMeta(metadata)
+      if (!meta) return
+      bytes = Buffer.byteLength(JSON.stringify(meta), 'utf8')
+      while (bytes > MAX_RECEIPT_BYTES && meta.sources.length) {
+        meta.sources = meta.sources.slice(0, Math.floor(meta.sources.length / 2))
+        meta.sources_truncated = true
+        bytes = Buffer.byteLength(JSON.stringify(meta), 'utf8')
+      }
+    } catch {
+      // Optional UI receipts must never interfere with tool completion when
+      // a failed or replaced tool supplies no valid presentation projection.
+      return
+    }
+    if (bytes > MAX_RECEIPT_BYTES) return
+    if (!state) { state = { items: new Map(), bytes: 0 }; pending.set(exec.agent, state) }
+    const now = Date.now()
+    for (const [key, item] of state.items) if (now - item.time > PENDING_LIFETIME_MS) drop(state, key)
+    while (state.items.size >= MAX_PENDING_CALLS || state.bytes + bytes > MAX_PENDING_BYTES) {
+      const oldest = state.items.keys().next().value
+      if (oldest === undefined) break
+      drop(state, oldest)
+    }
+    state.items.set(callId, { parent: exec.parent, tool: exec.name, meta, bytes, time: now })
+    state.bytes += bytes
+  })
+  ctx.on('tools/ptc-dispatch-log', async (dispatch, next) => {
+    const content = await next()
+    if (disposed || !dispatch.agent || !PTC_TOOLS.has(dispatch.name)) return content
+    const state = pending.get(dispatch.agent)
+    const callId = String(dispatch.subCallId || '')
+    const item = state?.items.get(callId)
+    if (!item || item.parent !== dispatch.exec?.token || item.tool !== dispatch.name) return content
+    drop(state, callId)
+    if (dispatch.isError || Date.now() - item.time > PENDING_LIFETIME_MS) return content
+    return [...content, { type: PTC_RECEIPT_TYPE, version: 1, callId,
+      parentCallId: String(dispatch.exec.callId), tool: item.tool, meta: item.meta }]
+  })
+  ctx.effect?.(() => () => { disposed = true; pending = new WeakMap() }, 'prts-corpus: PTC archive receipts')
+  return true
+}
+
+function localDocumentId(store, item) {
+  if (item.document_uid) return store.getDocumentIdByUid?.(item.document_uid) || null
+  const naturalIds = store.naturalTitleIndex?.get(item.title) || []
+  const ids = naturalIds.length ? naturalIds : store.titleIndex?.get(item.title) || []
+  // Ambiguous titles must remain unlinked; choosing an arbitrary document is unsafe.
+  return ids.length === 1 ? ids[0] : null
+}
+
+export function localArchivePresentation(store, value, dataVersion = store.dataVersion) {
+  if (value?.error || value?.status === 'error') return envelope([], dataVersion)
+  const sources = (value?.documents || []).slice(0, MAX_SOURCES + 1).map((item) => {
+    const documentId = localDocumentId(store, item)
+    const ranges = rangesFor((item.matches || []).map((match) => range(match.line_start, match.line_end)))
+    const excerpt = (item.matches || []).flatMap((match) => match.excerpt || [])
+      .map((line) => `${line.speaker ? `${line.speaker}：` : ''}${text(line.text)}`).join('\n')
+      || (item.section_content?.blocks || []).map((block) => text(block.text)).join('\n')
+      || [item.entity_summary?.description, item.entity_summary?.history_summary].filter(Boolean).join('\n')
+    return { id: documentId ? localId(dataVersion, documentId)
+      : idFor('local', dataVersion, item.document_uid || [item.game, item.resource_type, item.title]),
+      title: text(item.title, 512), kind: text(item.resource_type, 80), origin: 'local', state: 'found',
+      excerpt: text(excerpt), ...(documentId ? { documentId, documentUid: documentUid(documentId) } : {}),
+      ...(version(dataVersion) ? { dataVersion } : {}), ...locations(ranges) }
+  })
+  return envelope(sources, dataVersion)
+}
+
+const PUBLIC_URL_PARAMETERS = new Set(['title', 'oldid', 'diff', 'id', 'page', 'p',
+  'doc', 'document_id', 'lang', 'section'])
+
+function safeUrl(value) {
+  try {
+    const url = new URL(value)
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) return undefined
+    for (const key of [...url.searchParams.keys()]) {
+      if (!PUBLIC_URL_PARAMETERS.has(key)) url.searchParams.delete(key)
+    }
+    return url.href.length <= 2048 ? url.href : undefined
+  } catch { return undefined }
+}
+
+/** Only returned anchors and model-visible content belong on the user's desk. */
+export function cloudArchivePresentation(value, { inspect = false, dataVersion } = {}) {
+  if (value?.error || value?.status === 'error') return envelope([])
+  const delivered = inspect ? '' : projectCloudSearch(value)
+  const remoteVersion = version(value?.data?.data_version || value?.data_version)
+  const sources = []
+  const byId = new Map()
+  const mappedDocuments = new Set()
+  const add = (source) => {
+    const previous = byId.get(source.id)
+    if (previous) {
+      previous.ranges = rangesFor([...(previous.ranges || []), ...(source.ranges || [])])
+      if (!previous.excerpt) previous.excerpt = source.excerpt
+      if (source.state === 'read') { previous.state = 'read'; previous.agentRead = true }
+      return
+    }
+    if (sources.length >= MAX_SOURCES + 1) return
+    byId.set(source.id, source); sources.push(source)
+  }
+  // Both cloud renderers explicitly deliver every suggested local anchor. Do not
+  // forward mapping excerpts: they may come from candidates hidden by Cleaner.
+  for (const mapping of (value?.local_source_mappings || []).slice(0, 200)) {
+    if (!mapping?.suggested_source_ref || !mapping.document_id || !version(dataVersion)) continue
+    mappedDocuments.add(mapping.document_id)
+    const ranges = rangesFor([range(mapping.start_line, mapping.end_line || mapping.start_line)])
+    add({ id: localId(dataVersion, mapping.document_id),
+      title: text(mapping.title || mapping.display_title, 512), kind: text(mapping.document_kind || 'source', 80),
+      origin: 'cloud', state: 'found', excerpt: '', documentId: text(mapping.document_id, 1024),
+      documentUid: text(mapping.document_uid, 128) || documentUid(mapping.document_id),
+      dataVersion, ...locations(ranges) })
+  }
+  // The inspect renderer preserves the allowlisted textual fields below. Use
+  // each original item for its opaque identity as well, so filtered null rows
+  // cannot shift that identity onto a different projected document.
+  const items = inspect ? value?.data?.items || []
+    : value?.data?.sources || value?.data?.selected_sources || []
+  for (const item of items.slice(0, 200)) {
+    if (!item || typeof item !== 'object') continue
+    const title = text(item.title || item.story_title || item.display_title, 512)
+    if (!title || (!inspect && !delivered.includes(title))) continue
+    // Titles are display text, not identities; only an exact canonical document
+    // match can establish that the mapped anchor already represents this item.
+    const excerpt = inspect
+      ? [item.content_preview, item.content, item.text, item.summary].filter((entry) => typeof entry === 'string' && entry.trim()).join('\n\n')
+      : [item.content_preview, item.content, item.text, item.summary]
+        .find((entry) => typeof entry === 'string' && entry && delivered.includes(entry)) || ''
+    // A local anchor is a pointer to a future corpus_read, not evidence that the
+    // local document was read. Keep an explicitly delivered remote body separate
+    // even when an anchor maps it to that same document: line spaces may differ.
+    if (item.document_id && mappedDocuments.has(item.document_id) && (!inspect || !excerpt.trim())) continue
+    const url = safeUrl(item.url || item.source_url)
+    const ranges = rangesFor([range(item.start_line, item.end_line || item.start_line)])
+    const identity = item.document_id || item.source_id || item.doc_id || item.story_id
+      || item.source_file || url || [item.game, item.source_type, title]
+    add({ id: idFor('cloud', remoteVersion, identity),
+      title, kind: text(item.source_type || 'cloud_source', 80), origin: 'cloud',
+      state: inspect && excerpt.trim() ? 'read' : 'found',
+      ...(inspect && excerpt.trim() ? { agentRead: true } : {}),
+      excerpt: text(excerpt), ...(url ? { url } : {}), ...locations(ranges) })
+  }
+  // Cleaner can deliver a synthesis with no resolvable individual source. Keep
+  // exactly that delivered text accessible without inventing document locators.
+  const context = value?.data?.answer_context
+  if (!sources.length && typeof context === 'string' && context.trim()) {
+    const excerpt = inspect ? context : delivered
+    add({ id: idFor('cloud', remoteVersion, excerpt), title: '云端检索摘要', kind: 'cloud_summary',
+      origin: 'cloud', state: 'read', agentRead: true, excerpt: text(excerpt) })
+  }
+  return envelope(sources, dataVersion)
+}
+
+export function timelineArchivePresentation(value) {
+  if (value?.status !== 'ok') return envelope([])
+  const events = value.mode === 'source' ? [value.event] : value.events || []
+  return envelope(events.slice(0, MAX_SOURCES + 1).filter(Boolean).map((event) => ({
+    id: idFor('local', value.data_version, event.source_marker || [event.activity_name, event.time, event.event]),
+    title: text(`${event.activity_name || event.activity_names?.join('、') || '泰拉年表'} · ${event.time || '事件'}`, 512),
+    kind: 'timeline', origin: 'local', state: 'found', excerpt: text(event.event),
+    ...(version(value.data_version) ? { dataVersion: value.data_version } : {}),
+  })), value.data_version)
+}

package/src/cloud-projection.js

@@ -0,0 +1,124 @@
+/**
+ * 云端工具的模型可见投影。语义与 agent/browser/src/context-manager.js 保持一致：
+ * cloud_search 只交付 Cleaner 的 bounded answer_context、可读本地锚点和警告；
+ * cloud_inspect 保留所请求的结构化区段，但移除内部不透明标识和空元数据。
+ */
+
+export function withoutEmptyMetadata(value) {
+  if (Array.isArray(value)) return value.map(withoutEmptyMetadata).filter((item) => item !== undefined)
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).flatMap(([key, child]) => {
+      const projected = withoutEmptyMetadata(child)
+      if (projected === undefined) return []
+      if (Array.isArray(projected) && !projected.length) return []
+      if (projected && typeof projected === 'object' && !Object.keys(projected).length) return []
+      return [[key, projected]]
+    })
+    return Object.fromEntries(entries)
+  }
+  return value === '' || value == null ? undefined : value
+}
+
+const MODEL_HIDDEN_IDENTIFIER_FIELDS = new Set([
+  'call_id', 'request_id', 'intent_id', 'round_id', 'trace_ref',
+  'evidence_id', 'candidate_id', 'document_id', 'source_ref',
+  'source_ref_prefix', 'suggested_source_ref', 'read_ref', 'run_id',
+])
+
+const ZERO_VALUE_SCORE_FIELDS = new Set([
+  'content_score', 'summary_score', 'entity_boost_score', 'ranking_score',
+])
+const DEFAULT_FALSE_FIELDS = new Set(['llm_validated', 'exact_match_privileged'])
+
+/** 删除“未执行/没有信号”的默认审计字段；非零评分和真实诊断状态继续保留。 */
+export function withoutNoSignalMetadata(value) {
+  if (Array.isArray(value)) return value.map(withoutNoSignalMetadata)
+  if (!value || typeof value !== 'object') return value
+  return Object.fromEntries(Object.entries(value).flatMap(([key, child]) => {
+    if (ZERO_VALUE_SCORE_FIELDS.has(key) && Number(child) === 0) return []
+    if (DEFAULT_FALSE_FIELDS.has(key) && child === false) return []
+    if (key === 'llm_validation' && child === 'not_checked') return []
+    return [[key, withoutNoSignalMetadata(child)]]
+  }))
+}
+
+export function withoutOpaqueIdentifiers(value) {
+  if (Array.isArray(value)) return value.map(withoutOpaqueIdentifiers)
+  if (!value || typeof value !== 'object') return value
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !MODEL_HIDDEN_IDENTIFIER_FIELDS.has(key))
+    .map(([key, child]) => [key, withoutOpaqueIdentifiers(child)]))
+}
+
+function anchorIndex(mappings) {
+  const found = new Map()
+  for (const mapping of mappings) {
+    if (!mapping.suggested_source_ref) continue
+    if (mapping.evidence_id) found.set(`evidence:${mapping.evidence_id}`, mapping.suggested_source_ref)
+    if (mapping.candidate_id) found.set(`candidate:${mapping.candidate_id}`, mapping.suggested_source_ref)
+  }
+  return found
+}
+
+function addSourceAnchors(items, anchors) {
+  return (items || []).map((item) => {
+    if (!item || typeof item !== 'object') return item
+    const copy = structuredClone(item)
+    const sourceRef = anchors.get(`evidence:${copy.evidence_id}`)
+      || anchors.get(`candidate:${copy.candidate_id}`)
+    if (sourceRef) copy.suggested_source_ref = sourceRef
+    return copy
+  })
+}
+
+export function projectedAnchorPoints(mappings) {
+  return mappings.filter((mapping) => mapping.suggested_source_ref).map((mapping) => withoutEmptyMetadata({
+    game: mapping.game,
+    title: mapping.title || mapping.display_title,
+    lines: mapping.line_range || (mapping.start_line && mapping.end_line
+      ? (Number(mapping.start_line) === Number(mapping.end_line)
+        ? `${mapping.start_line}` : `${mapping.start_line}-${mapping.end_line}`) : undefined),
+    // DSH 的短篇章 ID 是人类可读标题发生冲突时才需要的消歧信息；前端
+    // 没有该字段，保留在锚点不会暴露内部路径或 source_ref。
+    document_uid: mapping.title_ambiguous ? mapping.document_uid || undefined : undefined,
+  }))
+}
+
+export function projectCloudSearch(value) {
+  const data = value?.data || {}
+  const mappings = value?.local_source_mappings || []
+  const sources = addSourceAnchors(data.sources || data.selected_sources || [], anchorIndex(mappings))
+  let answerContext = String(data.answer_context || '')
+  for (const source of sources) {
+    if (source.evidence_id && source.title) {
+      answerContext = answerContext.replaceAll(source.evidence_id, `《${source.title}》`)
+    }
+  }
+  answerContext = answerContext
+    .replace(/\b(?:evi|ev)_[A-Za-z0-9_-]+\b/gu, '相关资料')
+    .replace(/\[(?:E|A|C|H)[1-9][0-9]*\]/gu, '')
+  const anchorLines = projectedAnchorPoints(mappings).map((anchor) =>
+    `- [${anchor.game === 'endfield' ? '终末地' : '明日方舟'}] 《${anchor.title || '原文'}》${anchor.lines ? `第 ${anchor.lines} 行` : ''}`
+      + `${anchor.document_uid ? `（读取时以 ${anchor.document_uid} 替代 title，不要同时提交二者）` : ''}`)
+  const relationLines = (value?.retraveler_relations || []).map((item) =>
+    `- 终末地角色：${item.endfield_name}；泰拉记忆原型：${item.terra_memory_prototype || '未登记'}；` +
+      `状态：${item.relation_status}。这是跨游戏关系，不是人物别名。`)
+  const warnings = [...(data.errors || []),
+    ...(value?.local_source_mapping_warning ? [value.local_source_mapping_warning] : [])]
+  return [answerContext.trim(), relationLines.length
+    ? `## 再旅者对应关系（人工审校附属字段）\n${relationLines.join('\n')}` : '',
+  anchorLines.length ? `## 可读取原文\n${anchorLines.join('\n')}` : '',
+    warnings.length ? `## 警告\n${warnings.map((item) => item.message || item).join('\n')}` : '']
+    .filter(Boolean).join('\n\n')
+}
+
+export function projectCloudInspect(value) {
+  const data = value?.data || {}
+  const mappings = value?.local_source_mappings || []
+  const items = addSourceAnchors(data.items || [], anchorIndex(mappings))
+  return withoutEmptyMetadata(withoutNoSignalMetadata(withoutOpaqueIdentifiers({ tool_name: 'cloud_inspect',
+    status: 'ok', payload: {
+      code: value?.code, anchor_points: projectedAnchorPoints(mappings), data: { ...data, items },
+      ...(value?.local_source_mapping_warning ? { warnings: [value.local_source_mapping_warning] } : {}),
+    } })))
+}