代理会话搜索契约¶

AiVaultSearchRequest、AiVaultSearchResponse、AiVaultSearchHit 和 AiVaultSearchStatus 定义在 src/shared/ai-vault-search-types.ts 中，并由 src/shared/ai-vault-search-contract.ts 验证。

搜索与分页¶

• 每行超过 3,072 个字符的工具输出不会被索引，也不可搜索；用户和助手文本会完整索引。
• 在保留期清理期间未决的页面游标会被拒绝一次，作为 stale-cursor；客户端重新发出第 1 页。
• 不支持跨长消息块边界的短语匹配。

aiVault.searchSessions(request) 接受 query、可选 scope （conversation 或 all，默认 all）、freshness（indexed 或 wait-until-current，默认 indexed）、limit、不透明 cursor、filters， 以及 debug（默认 false）。会话范围会搜索用户和助手文本。 过滤器接受 agents、scopePaths、ISO since，以及 sort（relevance 或 newest）。路径指执行主机，并且对没有 Git 的文件夹也有效。 旧版 tier 和 refresh 字段会被接受并丢弃；它们不会改变 默认值。限制使用引擎的解析器：默认 20，整数被限制在 1–100 之间，小数使用默认值。长查询会到达引擎，以便它 可以报告截断而不是验证失败。

结果包含 kind: 'results'、hits、page: { cursor, hasMore }、 generation、truncated: { candidates, snippets, query, freshness }，以及 durationMs。snippets 是一个计数；其他截断字段是布尔值。 durationMs 测量引擎搜索，不包括任何协调等待。 debug: true 会添加 debug: { route, repairedTerms?, plannerReport }；报告 包含 route、可选 repairedTerms，以及 scope。诊断信息永远不会 出现在顶层。状态永远不会附加到搜索结果上。

一个游标属于一个查询、一个主机的索引代，以及一个不透明持久化 索引实例。查询、范围、过滤器和排序必须保持不变；页面 大小可以改变。推进代的写入可以使其失效，包括 保留期清理。清除或重建数据库会使其失效，即使 新代计数器匹配。被拒绝的游标会产生 { kind: 'stale-cursor', generation, expectedGeneration? }，并且 客户端丢弃它并发出没有游标的第 1 页。重用该被拒绝的游标 会继续失败；没有服务器端游标确认状态。 格式错误的游标和用于不同查询的游标会产生 { kind: 'malformed-cursor' }。代检查也会在检索期间索引变化时拒绝第一页。代是栅栏，而不是保留的快照： 客户端不能要求主机重建之前的代。

页面仅按主机划分。排序是本地于该主机的查询。客户端在 更改主机时必须丢弃游标。所有计算机搜索、合并排序、 按主机聚合结果，以及合并游标推迟到单独的 PR。 该后续工作必须在暴露合并结果列表之前定义代栅栏、页面大小变化、不可用 主机，以及有界并行检索。

执行主机路由¶

搜索和状态寻址一个执行主机：local、ssh:<target>，或 runtime:<environmentId>。省略主机表示此桌面的本地索引。 无效 ID 和 all 会被拒绝；两者都不能将请求扩展到其它主机。

• local 通过桌面 IPC 搜索这台机器的索引。
• ssh:<target> 只询问该中继会话，不询问其他任何内容。
• runtime:<environmentId> 通过其 RPC 询问该配对运行时。配对 运行时只为自己回答，并且从不通过另一个桌面转发。

每个命中可能携带 executionHostId。桌面会用其寻址的主机 为远程答案盖章，而不是信任该主机返回的 ID。 本地答案和较旧主机可能省略归属。

证据与暴露¶

每个命中携带 agent、会话 ID、标题、cwd、branch、更新时间、消息 计数、score、source，以及 evidence。证据包含 snippet、role，以及 timestamp； 对于没有文本证据的仅操作员匹配，它为 null。片段匹配 使用 [[ 和 ]] 标记。来源存在性为 present、unverifiable，或 missing；当前引擎发出前两个。失去联系不能证明 来源缺失。

redactForTransport(hit, transport) 是暴露策略：

cwd、标题、片段，以及其他命中元数据对配对客户端保持可见。 片段按索引状态跨越经过身份验证的传输；此契约不对 转录内容应用可观察性脱敏器。缺失的 Codex home 会被 省略。恢复命令重用转录读取器存储的命令， 由侧边栏的 buildAiVaultResumeCommand 构造；此层不 构造命令或执行它们。运行时使用其经过身份验证的 clientKind 上下文来区分配对客户端与同机 RPC，从不 使用请求提供的本地性标志。接收的远程客户端也应用 相同的暴露函数。

状态、新鲜度与可用性¶

aiVault.searchStatus() 返回 enabled、phase（idle、indexing、current、 degraded，或 closed）、filesIndexed、filesDue、filesFailed、degradedRoots （root 和 reason）、lastReconcileAt、lastSweepCompletedAt，以及 generation。 时间为自 epoch 以来的毫秒数或 null。这些是索引器的观察； 已索引的行不是新的文件系统验证。降级根目录的 root 和 原始 reason 都可能包含主机文件系统路径。桌面 IPC 和同机运行时 RPC 接收完整诊断； 中继和配对客户端对于每个降级根目录只接收固定原因 "Source root could not be verified."。数组长度保留计数。

wait-until-current 在搜索前调用 service.reconcile()。适配器使用 indexer.reconcile({ full: false })。五秒后，端点仍会执行搜索，并在结果上设置 truncated.freshness: true。它不会取消主机的协调。在截止时间前完成会使该标志保持 false；截止时间前发生的协调错误会传播。索引器的有界近期扫描并不保证整个历史语料库都已被扫描。

搜索不可用是一个值： { kind: 'unavailable', reason: 'disabled' | 'not-ready' | 'no-service' }。 没有已注册的服务会返回 no-service。无服务时的状态具有 enabled: false、phase: 'idle'、计数和 generation 均为零、空的 degraded roots 以及空时间戳。这是表示服务缺失的哨兵值，并非声称索引为空且最新。已注册服务可能报告 disabled 或 not-ready。

边界与兼容性¶

• 桌面端：通过 preload 使用 aiVault:searchSessions 和 aiVault:searchStatus。
• 运行时和中继：aiVault.searchSessions 和 aiVault.searchStatus。
• CLI：orca search 通过运行时 RPC 调用两者，仅针对由 --environment / --pairing-code 选择的主机，且不针对其他主机。它复用 createSessionSearchClient，因此旧主机的拒绝会以 unavailable/no-service 而非错误到达调用方，并且不需要新的能力。 在 Orca SSH 终端中，转发的 CLI 默认使用控制它的 Orca 运行时的索引。--path 过滤该索引；它不会选择 SSH 主机。 --environment / --pairing-code 可以显式选择已配对的运行时。
• 桌面 preload 可选择地接受执行主机作用域作为独立的路由参数。它精确指向该主机；连接缺失时绝不会回退到本地索引。Web preload 指向其自身配对的运行时，对 all 和任何其他主机都以 unavailable/no-service 而非错误作答。

请求和响应在从另一进程接收处进行解析。现有中继 JSON-RPC 请求/响应帧不需要新的流操作码。遵循现有中继方法探测模式，旧主机的显式 -32601 拒绝（或运行时 method_not_found）在客户端映射为 unavailable/no-service；状态使用上述服务缺失哨兵。传输失败、认证错误和无效载荷仍然是错误。未知请求字段会被移除，以保持线上兼容性。

进程本地的 setSessionSearchService(service | null) 注册表将这些端点连接到 PR 3b 安装的生产服务。桌面索引运行在 scanner 子进程中；orcad 和 SSH 中继注册它们自己的进程内服务。仅注册不会授予同意。

桌面索引控制（PR8）¶

设置 → Agent Session History 控制此桌面端持久化的 aiVaultSearch { enabled, historyDays } 策略。即使选择了另一个执行主机，它仍保持本地。配对客户端无法通过此界面授予同意或清除索引；在没有独立的主机同意机制时，SSH 中继注册保持禁用。

aiVault.clearSearchIndex() 是一个无参数的、仅限桌面的 preload 操作，基于 aiVault:clearSearchIndex。它指向本地 scanner 子进程，而不是所选的远程主机。子进程现有的交互式请求通道通过 SessionSearchInstance.clear() 执行 searchClear：关闭索引器和数据库句柄，删除 SQLite 数据库及 sidecars，然后仅在同意仍启用时重建。错误会传播到设置窗格。此操作从不删除原始转录。没有新的运行时或中继方法。不透明游标还携带持久数据库标识：清除会创建新标识，因此清除前或旧版游标会返回 stale-cursor，即使重建后的数字 generation 恰好匹配。重新打开同一数据库会保留其标识。

禁用会关闭索引器并保留索引副本；清除会删除副本。更改保留期会复用现有的关闭并构建策略应用流程。设置窗格仅在启用且可见时读取状态，仅轮询观察到的索引阶段，并在完成或出错时停止。打开窗格、更改策略或按刷新会获取新的观察。索引器自身的调度不依赖于窗格。