[RFC] 检索面统一：/search 升级为 Context 组装面（Agent auto-recall 能力增强）

[t0saki]

目标：把「预算 / 用途 / 档位 / 重写」四组正交能力收敛进唯一的复合检索面 /search，让 agent auto-recall 场景一次调用拿到「装配好、可直接注入」的 Context 包。/find 保持为稳定的检索原语不动；/recall 收敛为同一实现上的薄预设入口。心智模型与「Data in, Context out」对齐——/find 回答「有哪些相关内容」，/search 回答「给我装配好一份能直接使用的上下文」，/recall 是后者在 coding-agent auto-recall 场景下的默认值预设。

关联：RFC #3330 Session 上下文优化（token 预算估算器共享、turn_id 锚定去重时钟等协调项）；实验分支 feat/auto-recall-v2（本提案的原型验证素材）。

---

1. 现状盘点（main 实测）

main 上现有三个检索端点，能力矩阵如下：

维度	/find	/search	/recall（v1，自 v0.4.9）
定位	无状态语义检索原语	find + session	memory 专用组装召回
请求模型	FindRequest	≡ FindRequest 仅多 session_id	完全异构：quotas / max_chars / min_score / peer_scope / render(bool)
LLM 参与	rerank（配置了才有）	rerank + IntentAnalyzer 多查询扇出	零 LLM
LLM 保险丝	—	无：IntentAnalyzer 直调、无独立超时	—
查询时文件读	0（abstract 来自向量 payload）	0	命中后逐条串行回读全文
检索范围	memories + resources + skills	同 find	仅 memories（四类记忆分桶）
预算模型	limit 条数	limit 条数	max_chars 字符预算 + full→summary→uri 降级
返回	平铺列表	平铺列表 + query_plan	entries + rendered + stats 组装包

四个关键事实（源码位置见附录）：

1. search 名不副实：无 image 且 session 上下文为空时，/search ≡ /find。不带 session_id 调用时永远落入此分支。
2. rerank 不是 search 专属：检索模式仅由「是否配置 rerank client」决定（hierarchical_retriever.py）；配置项 default_search_mode 存在但未接线（死配置）。
3. recall 是纯机械组装：v1 /recall 无任何 LLM 参与，本质是分桶 /find + 预算渲染——type_quota_recall.py 是「一份实现、两个入口」（REST 与 MCP 工具都直调它），组装逻辑本就架在 find 之上。
4. 消费方极少：REST /recall 的生产消费方仅限官方插件族；SDK 与 CLI 从未暴露过 recall，端点处置自由度很高。

1.1 实验分支验证了什么

我们曾在实验分支（feat/auto-recall-v2）上尝试过另一条路径：继续增强 /recall。原型已全部跑通、实测数据良好，但代价也暴露无遗：它在 /recall 内部造出了与 /search 平行的第二条 session/LLM 处理链路——这恰好反证了这些能力的正确归宿是 /search 本身。原型成果转化为本提案的设计素材：

原型能力	实测结论	在本提案中的归宿
session 感知查询扩展（一次有界 IntentAnalyzer，≤3 查询、超时熔断、fail-closed）	intent ~2s；10s 熔断充裕	L1 query_expansion（§3.2）
服务端 digest 重写（query_planner 回退主 vlm）	7–11s @300–500 token	L3 rewrite（§3.2）
exclude_uris 跨轮去重（≤200）	端到端验证通过	L2 无状态去重原语
compact 渲染（summary 优先、events 外零文件读）	注入体积 7–9k → ~1.2k 字符	并入 detail 档位模型（§3.4）
逐条读全文并行化（Semaphore(8)，排序确定性保持）	N×RTT → ~1×RTT	组装内核改进，随 PR 落地
default_search_mode 接线（"fast" 跳过 rerank）	已接通	卫生项，随 PR 落地

2. 问题陈述：为什么要合并

1. search 的「更强大接口」定位从未兑现，与 find 几乎同构。
2. 组装能力困在 memory 域：/recall 是唯一有预算渲染的端点，但只识别四种记忆类型；「coding 场景需要更多 resources/skills」这类用途配比需求在 API 面上无处表达。
3. 继续加强 recall 会制造第二条 LLM 路径（实验分支的教训）：同一个「意图理解」概念在同一 router 中出现两份实现（search 的无保险丝直调版 vs recall 的有界熔断版）。收敛至 /search 既保证路径唯一，还让旧链路顺带获得熔断保护。
4. 档位概念混乱：v1 的 "summary" 档混用两种数据源（events 正文 # Summary 段落 vs 索引自带 abstract）；render 是布尔值，调用方必须读源码才能理解降级语义。
5. 消费方接入成本高：插件要实现「/recall 失败回落 /find」双协议；文档要反复解释三个端点边界。

反方向验证（已做过的思想实验）：把组装逻辑退回客户端、只留 find/search 原语，是技术倒退——HTTP 调用 ×15–25、查询扩展 LLM 调用被分桶放大 ×3–4、N 份客户端实现漂移（vikingbot 与服务端移植版之间已出现 3 处语义分歧）。服务端单份组装实现的价值毋庸置疑，本提案改变的只是入口形态。

3. 新设计

定位前提：两种消费模型。 同一套 OV 存储上并存两类消费方：接管型（vikingbot——OV 输出什么模型就看到什么，session 子系统是其引擎，#3330 属该范畴）与旁挂型（Claude Code / Codex / OpenCode / pi 等 harness 自管上下文窗口，OV 只在固定注入点提供受预算封顶的补充块）。本提案的统一检索面服务于旁挂型契约：响应必须是无状态渲染块、预算由客户端申报、去重必须 opt-in、不做 Context Delta / 注入回执等接管型概念（§5）。

目标：G1 /search 成为唯一复合检索面，不传新参数时行为与 main 基本一致；G2 recall v1 全部能力 + 原型增强能力均可经 /search 参数表达；G3 组装能力泛化至 resources/skills 域；G4 档位模型对齐 ContextLevel 三级阶梯，任何档位 URI 必须在场；G5 session/LLM 路径唯一化（有界、fail-closed，废弃无保险丝直调）。

非目标：console/前端改动；跨类型 rerank 与召回命中率遥测闭环（后续观察项）；插件侧能力（客户端压缩、TTL 去重旋钮族等——与端点选型正交，独立演进）。

3.1 端点布局

端点	处置	角色
POST /api/v1/search/find	不动	检索原语：一次向量检索、零 LLM、零文件读
POST /api/v1/search/search	扩展	唯一复合面：mode="list"（默认，≡今日 search）/ mode="context"（吸收 recall）
POST /api/v1/search/recall	保留为薄预设入口	auto-recall 预设：同一实现、仅默认值差异 + v1 字段别名过渡
MCP recall 工具	保留工具名	面向 agent 的语义化入口，后端与 /recall 同 profile

「薄」的不变式（严防再次变厚）：① 无独占参数——/recall 的每个参数必须在 search context 中存在且语义一致，差异仅允许在默认值；② 无业务分支——recall handler 出现业务 if 即视为违规；③ 兼容钉——显式同参时两入口响应逐字节一致（单测钉死）；④ 职责仅为「叠默认值 + v1 别名翻译」后透传给与 mode="context" 相同的编排函数。

两套默认值只差在 auto-recall 场景真正需要不同的四处：

参数	search mode="context"	/recall	差异理由
purpose	null（quota-free 纯分数）	"coding"	每轮注入需配额采样保住 preferences/entities 不被高分 events 挤掉
dedup_turns	0	5（带 session_id 时）	跨轮重复注入只发生在 auto-recall；入口即记账信号——statusline 探测、agentic 查询走 search/MCP，天然不污染账本
score_threshold	0.1	0.35	被动注入无人工审阅，需要更高质量地板
预算参数	仅 max_tokens（默认 1600）	同；另接受 v1 max_chars 别名折算	旧插件零动作过渡

v1 别名（仅 /recall 接受，deprecated）：max_chars、min_score（→score_threshold）、render:bool（→固定 detail 档）、v1 quotas 键。命中别名时响应附 Deprecation header + 服务端 warning 日志；下一个 minor 拆除别名（不是拆端点）。

3.2 SearchRequest 参数分层

四层组织，每层独立、默认关闭、优雅降级：

L0 检索域——现有参数全部保留、语义不变（query, image_url, target_uri, context_type, limit, score_threshold, filter, tags, since/until, level, …）。

L1 查询理解（session-aware）：

参数	类型/默认	语义
session_id	str?（已有）	会话上下文来源
query_expansion	"off" | "auto"，默认 "auto"	auto = 有 session 上下文时做一次有界 IntentAnalyzer 扩展（≤3 查询、超时熔断、失败退化原查询）

默认 "auto" 是为兼容旧 search 语义（携带 session 即触发分析），核心改变是换成有界实现并删除无保险丝直调路径。扩展查询数受 ≤3 约束属微小语义变更，记入 CHANGELOG。

L2 上下文组装（仅 mode="context" 生效）：

参数	类型/默认	语义
mode	"list" | "context"，默认 "list"	context = 服务端组装 Context 包
max_tokens	int，默认 1600（≈ v1 6500 字符 /4）	唯一预算参数，服务端 CJK 感知启发式记账（见下）
quotas	Dict[str,int]?，默认不启用	显式传入启用分桶配额采样；键泛化为 events/entities/preferences/experiences/resources/skills
purpose	"chat" | "coding" | null，默认 null	用途预设：启用配额采样并提供配比与预算比例默认值，显式参数可逐项覆盖
detail	"auto" | "abstract" | "overview" | "full"，默认 "auto"	每条目档位上限（§3.4）；auto = 预算驱动先广后深
dedup_turns	int，默认 0	>0 且带 session_id 时启用服务端记账去重：本次返回的 URI 在该 session 后续 N 轮内冷却
exclude_uris	List[str] ≤200	无状态去重原语；可与 dedup_turns 并用（并集过滤）
peer_scope / other_peer_penalty	同 recall v1	peer 记忆参与度

预算单位：为什么是 max_tokens 而不是 max_chars。现行预算按 len() 字符计费，但同样 6500 字符，纯英文 ≈1.6k token、纯中文 ≈9.7k token，失真可达 6 倍——中文部署下注入成本被悄悄放大数倍。提案将 CC 插件已验证的 CJK 感知估算器（codepoint ≥ 0x3000 记 1.5 token/字符，其余 chars/4；线性单遍、无 tokenizer 依赖，中文误差 ±10–20%）上移服务端，max_tokens 成为组装内核唯一计价单位；max_chars 仅在 /recall 作别名在边界折算（max_tokens = max_chars/4，同传时 tokens 优先）。启发式 ±15% 的误差远胜纯字符预算的 ±500%。竞品对照：未见任何同类系统实现 token 计价预算（有按条目数、按结构上限的），这将是 OV 独有优势且随上移惠及全部 harness。协调项：#3330 的 retained_message_token_budget 需同一估算器——沉淀为服务端共享工具函数，避免「N token」出现两套算法。

去重：服务端 session 记账为主路径。auto-capture 场景下客户端本就持续 add_message，服务端握有消息流，「轮距」= 当前 session 消息数 − 记录时消息数（时间戳兜底）。实现轻量：dedup_turns>0 且带 session_id 时，返回前把本次 entries 的 {uri, detail, msg_index, ts} 记入 session 目录下的隐藏 sidecar {session_uri}/.recall_log.json（不塞 SessionMeta 热路径；写时自剪枝，生命周期随 session 目录），轮距时钟用 SessionMeta.total_message_count（单调递增、L1 阶段已驻留内存；#3330 的 turn_id 落地后切换为 User Turn 锚定）。服务端还能做客户端做不准的事：uri-only 宽限（上轮只给了裸 URI 的记忆，本轮允许升 full 档）。收益即本提案主论点：opencode、pi、cursor、trae 及任何手工集成方零实现成本获得去重，消灭 N 份客户端状态文件漂移。如实记账的残余代价：①「已返回」≠「真正注入」（客户端可对确知未注入的轮次不带 dedup_turns 来不记账）；② 记账污染靠 opt-in 隔离（只有显式传参的调用才记账并受账本影响）；③ opted-in 查询带写副作用，与「session 自动管理」定位一致。exclude_uris 降级保留为无状态原语（无 session、capture 未开、或客户端自定义策略时的逃生通道）。

L3 LLM 加工（仅 mode="context" 生效）：

参数	类型/默认	语义
rewrite	false | true | "auto"，默认 false	对组装结果做一次服务端 digest 重写（query_planner 优先、回退主 vlm；超时熔断，失败 digest=""、rendered 照常）
rewrite_max_bullets	int 1–20，默认 6	digest 条数上限

相对原型的增强——结果重写的会话感知：带 session_id 时，L3 重写 prompt 追加 L1 已加载会话上下文的有界切片（archive overview 优先、近几条 user 消息补齐、字符硬帽），零额外 I/O、解码量不变（熔断公式不受影响）。取材优先取 OV 生成的稳定产物（overview / 未来的 checkpoint 摘要）而非 raw 消息尾巴——旁挂模型下原始消息只是插件异步抄送的有损镜像。

rewrite 的 token 成本账：每次开启 rewrite 的调用即一次服务端 LLM 推理——prefill ≈ 重写模板 + rendered 包（≤ max_tokens，默认 1600）+ 会话切片（带 session 时，字符硬帽），decode ≈ 默认 6 bullets 约 300–500 token，单次合计约 2–3k token；成本由部署方的 query_planner 模型（未配置时回退主 vlm）承担，不消耗终端用户的订阅额度。auto-recall 场景下该开销随对话轮数线性放大，是一笔真实的新增消耗；收益端则是注入主对话的内容从 rendered 全文换成 digest 摘要——省下的是主模型（通常更贵）的窗口 token，一增一减是否划算取决于部署的模型价差与召回频率。对应的设计选择：① 默认 false，纯 opt-in；② 重写任务对模型能力要求不高，建议部署方为 query_planner 配置小模型；③ 响应 stats 透传 rewrite_usage: {prompt_tokens, completion_tokens}（模型响应的 usage 现成），让部署方可核算与监控这笔开销。对照说明：L1 query_expansion 不构成新增成本——旧 /search 携带 session 时本就调用 IntentAnalyzer，本提案只是给它加上界。

参数交互规则（校验层执行）：mode="list" 时出现 L2/L3 参数 → 422（显式报错优于静默忽略）；配额采样启用时 limit 不生效（quota-free 默认态下自然生效）；context 模式下 level 失效（档位归 detail 管）、filter/tags/since/until 无损透传到每个来源子桶（组装模式免费获得时间窗与标签过滤——v1 recall 至今不具备）；首版 context 模式拒绝 target_uri（422，桶与 target 求交语义待真实需求出现再定义）；purpose 只提供默认值，显式参数逐项覆盖。

3.3 响应模型

mode="list"：完全不变。mode="context"：

{
  "entries": [
    {
      "uri": "viking://user/.../events/2026/07/14/x.md",  // 永远在场
      "category": "events",
      "score": 0.72,
      "detail": "full" | "overview" | "abstract" | "uri",  // 实际渲染档位；uri 为降级状态
      "text": "..."
    }
  ],
  "rendered": "...",  // 注入就绪的最终文本，永远填充
  "digest": "",        // rewrite 开启且成功时非空
  "stats": { "query_expansion": "off|used|failed", "rewrite": "off|ok|failed|timeout", "rewrite_usage": { "prompt_tokens": 0, "completion_tokens": 0 }, "excluded": 2, ... }
}

rendered 必须存在的两个硬理由：① 预算核算必须发生在文本最终形态上，预算与渲染逻辑不可分割；② 拼装格式只能有服务端一份实现，杜绝 N 个插件各自拼装的规则漂移（vikingbot 与服务端移植版已漂移 3 处，是付过的学费）。entries 是给自定义呈现客户端的结构化原料，rendered 是官方默认成品，同宗同源。

格式改版：扁平可读 XML。记忆正文几乎必然含 markdown 标题，纯 markdown 无法可靠划界，边界必须用 XML；要修的是 v1 的深嵌套（元数据全是子标签、正文深埋 <content> 内）。改为每条记忆一个标签对、元数据全部属性化、正文即标签体：

<memory uri="viking://user/alice/memories/events/2026/07/14/x.md" type="events" score="0.72" detail="full">
# Summary
2026-07-14，NPM vhost 27 上游端口应指向 caddy 1935……
</memory>

<memory uri="viking://user/alice/memories/preferences/style.md" type="preferences" score="0.61" detail="abstract">
偏好结论先行的汇报风格；测量后先给结论再动手。
</memory>

标签深度 3 层压平为 1 层；最外层 <openviking-context> 包裹仍由客户端负责（同现状）。属性取舍、按类型消费提示（如 preferences=遵循）等微观细节实现期定稿（D10）。

不变式底线：URI 永远在场——每个 entry 必须携带 uri；rendered 中每个 <memory> 必须带 uri 属性；digest 每条 bullet 必须显式引用合法 viking:// URI（缺引用直接丢弃，原型的 normalize_recall_digest 已提供实现与测试）。

3.4 档位概念模型

main 代码事实：系统分层 ContextLevel：L0=abstract、L1=overview、L2=full（core/context.py）。目录有真实的 .abstract.md/.overview.md sidecar；单文件只有 abstract（写入期生成的 summary 同时进父目录 overview 和该文件向量行的 abstract payload，~447B 封顶），resources 同样有 abstract。/find 返回的 abstract 直接取自向量 payload，零文件读。历史债：v1 recall 的 "summary" 档混称两种数据源（events=读全文后正则抽 # Summary 段；其他类型=索引 abstract）。

统一模型（对齐 ContextLevel，每档都带 URI）：

每条目档位（纵向，成本严格单调）:
  1. uri + L0 abstract    零文件读（payload 现成）
  2. uri + L1 overview    仅目录命中有实档；文件命中回落档 1
  3. uri + full           fs.read 正文，按条封顶
整包变换（横切，与档位正交）:  digest（LLM 重写，保 URI 引用）

• detail 是上限：固定值 = 全体条目钉在该档、超预算截条数；auto（默认）= 三轮填充。纯 uri 不是可请求档位，只是降级状态（预算溢出或去重冷却时 entry 如实记 detail:"uri"）。
• auto 三轮填充（先广后深，轮内按分数排序）：第 0 轮全体降落档 1（abstract 长度在 payload 里现成，预算核算精确、零 I/O）；第 1 轮在余算内把目录命中升 overview（先筛「预估装得下」候选，再并发读 sidecar）；第 2 轮把文件命中升 full（升级前 stat 探尺寸，避免「读入大文件又整条丢弃」）。对比 v1 render:true 的贪深策略（top 几条塞满全文、尾部只剩裸 uri 甚至被丢弃）：实测命中分数集中在 0.38–0.50 窄带、区分度弱，把预算押在 top-1 全文上风险高；auto 保证所有命中至少暴露一次可见度（URI+摘要），再按分逐条加深。
• 业内旁证：对 v1 降级链路运行实况的调研发现，entities/preferences 没有 summary 档，预算吃紧时直接跌到裸 URI——真实会话注入中多数条目只剩 filename + score，语义价值近乎为零。竞品 claude-mem 的对偶哲学是「宁可全员降级为单行摘要，绝不让任何一条退化成不可读指针」。档 1 保底 + 先广后深正是对此的机制化回应；同时 detail 固定档位把业内「宽索引+下钻 vs 全文推送」的注入形态之争收敛为同一参数的不同取值，A/B 成本降为改一个值（D13）。
• 来源上限：detail 是全局上限，各来源另有更严默认上限——memory 上限 full；resources/skills 默认封顶 abstract（防大文件或含敏感配置的 skill 被自动全文注入；显式放开留作后续参数）；目录命中的 full（子树聚合读）默认封顶 overview。
• "summary" 债清算：档 1 严格取索引 abstract（零读）；events 正文天然以 # Summary 开头，full 档按条封顶截头会自然保住该段——v1 summary 档的核心价值被承接，无需专门提取机制。
• compress/digest 不是档位：它作用于整包而非单条，是横切参数 rewrite，与 detail 正交（detail="abstract" + rewrite=true 合法：把摘要档喂给重写器）。
• 收敛旁证：[RFC] OpenViking Session 上下文优化：Turn-aware Retention、Pending/Failed 恢复与预算控制 #3330 的 checkpoint 结构正是 ContextPart{uri, abstract}——两个子系统独立演进收敛到同一形态，说明档位阶梯应是平台级概念。

3.5 选择策略与 purpose

默认（不传 purpose/quotas）：quota-free，纯分数排序。 现网 v1 默认配额 {events:10, entities:10, preferences:3, experiences:0} 继承自 vikingbot 的场景性动机（瘦身 profile 后靠配额保稳定类型），且配比数值在源码与提交记录中找不到任何评测依据（纯经验拍板）。场景性经验参数不应固化为通用接口默认。统一后默认路径：一次跨域 find（+可选查询扩展）→ 全候选纯分数排序 → auto 档位阶梯渲染；副产品是默认路径更简单便宜（省掉分桶多次检索），limit 自然生效。

配额采样 opt-in：显式传 quotas 或指定 purpose 才触发分桶采样（按来源子树独立 find，机制上保证弱势类型不被淹没）。预设配比每类保底 1。示意配比（初版建议，非最终承诺）：

purpose	events	entities	preferences	experiences	resources	skills	events 预算占比
chat	10	8	4	1	1	2	0.75
coding	4	6	2	4	8	6	0.40

预设放 retrieval.purpose_profiles 配置（ov.conf 可覆写/扩展），内置 chat/coding 两档（D5）。兼容性：v1 语义可由显式 quotas 100% 复现（已发布插件本就显式发送 quotas，迁移后行为零漂移）。诚实声明：配比数值同样缺乏评测数据支撑，本 PR 交付的是机制（API 参数面 + 配置面），数值最优解依赖后续召回命中率遥测迭代——这正是设计为配置项而非硬编码的原因。

3.6 初始化上下文托管（bootstrap，fast-follow 构思项）

现状：SessionStart 注入完全在客户端拼装（profile + 目录索引 + archive），每次启动 5–7 个 HTTP 往返，预算/剪除/格式逻辑散落在四个 harness 各一份变体——正是合并 recall 前「N 份拼装」处境的重现。

提案：新增 mode: "bootstrap"——复用同一 search 端点与同一组装内核，不新增端点。与 mode="context" 的唯一差异是候选来源：不是检索命中，而是声明式槽位 manifest；预算、渲染、档位逻辑完全同源。基于一个重度使用约 3 个月的真实记忆库实测校验（profile ~20k 字符 / preferences 170 文件 / 单月 events 688 文件）后的槽位设计：

槽位	回答的问题	机制
identity	我在和谁说话	profile.md，size-gate：超额则字符硬帽截头部 + URI 指针（实测否定了行/块/日期粒度的聪明选择）
working_state	我们正在忙什么	近 N 天 events 时间窗（cap 5–10 条、时间序；复用 L0 since/time_field——槽位即检索原语组合，也是 bootstrap 属于 search 的实质理由）；peer 启用时 peer:user ≈ 8:2
continuity	上次聊到哪	archive overview + 近期 abstracts（resume/compact 且有 session_id；现役机制经 manifest 表达）
listing	还有什么可查	目录索引（文件名 + abstract 注解），排序改为按更新时间倒序（修掉字母序截断留下随机前缀的缺陷）
instructions	这些记忆怎么用	服务端静态模板（零检索、零 LLM）：URI 如何展开、档位语义、recall/read/remember 使用时机；随服务端版本化，content_hash 客户端缓存

要点：偏好正文不进启动注入（170 条领域特定偏好里启动期任何预选都是任意抽样——正文交给每轮条件化召回与 MCP read，启动期只暴露文件名 affordance）；最大杠杆在写侧治理（profile 无界累积、preferences owner 分裂是上游数据纪律问题，bootstrap 定位为受策展工件的薄运输层，不做聪明内容挑选）；坚决不做 LLM 重写、不做语义检索（启动期无 query）。副产品：bootstrap 若同时以 MCP 工具暴露，纯 MCP 宿主（无 hook 能力的 harness）一次调用即可自助获取完整启动注入，新 harness 接入门槛从「手写 hook 管线」降为「教模型调一个工具」。

处置：fast-follow（D12）——首 PR 只需保证组装内核的候选来源可插拔（检索命中 / 静态 manifest 两种 provider）。

3.7 超时与延迟契约

• retrieval.recall_intent_timeout_s = 10：查询扩展熔断（实测 ~2s）；超时退化原查询。
• retrieval.recall_rewrite_timeout_s = 60：digest 重写熔断。实测 6 bullets（300–500 token）7–11s，按 20 bullets 线性外推 25–45s，60s 覆盖契约上限全部输出规模。语义是「一个回合最多愿意为 digest 卡多久」：正常路径 7–11s 返回，不受默认值抬高影响；抬高只为病态情况（模型 hang、集群过载）换取慢成功而非误杀——digest 成功率优先于尾延迟。超时则 digest=""、rendered 照常。
• 客户端配套（硬性耦合、必须成对改）：服务端熔断必须被客户端请求超时包住，否则客户端抢先断连、连 rendered 一起丢。开 rewrite 的客户端请求超时抬至 65s（总上限 ~80s，仍在 CC hook 外层 120s 保险丝内）；两数值在配置文档成对高亮。

统一行为准则：任何 LLM 环节失败都优雅降级、绝不整体失败。

4. 端点兼容与迁移

消费方	影响	迁移动作
官方插件（新版，随 PR 发布)	可留在 /recall（新默认即 auto-recall 预设）	recall-core 逐步改发新参数；对旧服务端保留 400/422 剥参降级（原型已验证）；/find 回落链保留兜底
已发布插件 0.4.x × 新服务端	零影响——v1 字段经别名全质量工作	无需动作；Deprecation header 提示，别名拆除（下一 minor）前完成升级
MCP recall 工具	无（直调实现，不经 REST）	保留工具名（D6）
Python/Go/TS SDK、ov CLI	零影响（从未暴露 recall）	后续按需补 context-mode 参数
vikingbot	无（进程内自装 type-quota）	无需动作
文档/测试	提及 /api/v1/search/recall 处	PR 内更新为双入口定位；测试改造为「预设等价钉 + 别名翻译断言 + 旧 search 逐字节兼容钉」三组

（另有商业化侧代理服务需同步参数面演进与别名拆除时间表，属外部协调项。）

单 PR 边界：服务端（routers/search.py 重排 + type_quota_recall.py 泛化为组装内核、建议更名 context_assembler.py + 有界扩展/recall_rewrite 拆件 + 删无界 IntentAnalyzer 路径 + default_search_mode 接线 + purpose 配置/超时配置）+ 插件参数面升级 + 中英文档与测试迁移，预估 ~2–3k 行 diff。建议 PR 内按提交分层：组装内核泛化 → search 扩参 → 端点路由处置 → 插件适配 → 文档。规模超限时的安全切出子集：① D4（resources/skills 桶 + purpose）延后 fast-follow；② L3 rewrite 延后（纯增量参数，不影响端点统一落地）。

组装内核的实现边界（与 #3330 的 plan_retention() 同习语）：严格分离「候选产生」（检索命中 / quotas 分桶 / bootstrap manifest 三种 provider 可插拔）与「组装流水线」（去重 → 档位规划 → 读取执行 → 渲染 → stats）；组装侧再拆「纯策略规划（无 I/O、无 LLM，凭 payload abstract 长度与 stat 预判制定装配计划）+ I/O 执行」两步——规划器可独立单测，且结构性保证读取纪律（只读大概率装得进预算的候选）。

5. 备选方案与否决理由

备选	否决理由
维持三端点 + 继续加强 recall	固化双 LLM 路径与端点边界含混；每个组装新能力都要再回答一次「为什么在 recall 不在 search」。注意与终稿区别：终稿保留的 /recall 是同实现的默认值预设，无独立能力面——否决的是 recall 作为第二条独立实现继续演进
反向合并：recall 为主面、search 退役	"recall" 是记忆域行话，作通用检索面命名不成立；SDK/CLI 既有 search 面全要动，破坏面更大
新开第四端点 /context，search/recall 双退役	命名最贴「Data in, Context out」，但过渡期三面并存、SDK 全家改名，成本大于收益；mode="context" 保留未来平移可能
组装退回客户端（只留原语）	HTTP ×15–25、扩展 LLM ×3–4、N 份实现漂移有付费历史
旁挂契约上建服务端上下文状态机（Context Delta、注入回执等）	属接管型消费模型能力：harness 自管上下文时服务端维护这些状态是争夺所有权且必然失真；重新评估条件=「出现新的把上下文所有权交给 OV 的消费方」

6. 风险

1. 默认行为回归：search 是 SDK/CLI/vikingbot 活跃路径。缓解：兼容钉测试（无新参数时响应逐字节一致）+ Pydantic extra="forbid"。
2. query_expansion 默认 auto 的语义微变：带 session 的旧调用从「无界分析」变为「有界 ≤3 + 熔断」——延迟与稳健性改善、扩展广度略减，写入 CHANGELOG。
3. resources/skills 注入质量未知：abstract 是入库时 447B 截取，信噪比未评测；quota-free 下凭分数即可混入注入结果（合并后的刻意行为变化）。缓解：score_threshold 守门 + resources/skills 默认封顶 abstract 档；强记忆流客户端可显式 quotas 锁回 memory-only；遥测证实分数系统性偏高再引入来源降权。
4. 别名拆除长尾：下一 minor 拆别名时仍发 v1 字段的存量插件会 400 → 回落 /find；窗口已从「合入即发生」推迟到拆除节点，期间有 Deprecation header + warning 日志过渡。
5. 单 PR 体量：~2–3k 行。缓解：commit 分层 + 两个安全切出子集。
6. 原型代码搬运集成风险：expansion/rewrite/compact 各带单测，但挂载宿主变更，需与 L0 scoping 组合参数重新集成校验。
7. rewrite 的边际模型开销：高频 auto-recall 场景下 rewrite=true 的服务端推理成本随对话轮数线性增长（单次 prefill ~2k token + decode 300–500 token，见 §3.2 成本账）。缓解：默认关闭、纯 opt-in；query_planner 建议配置小模型；stats.rewrite_usage 透传用量供部署方监控核算；必要时客户端按轮次门控触发频率。

7. 决策点清单（征求意见）

以下为报告评审阶段已形成倾向的决策点，发出来一并征求社区意见——尤其欢迎对 D8（预算单位）、D11（服务端记账去重）、D13（auto 默认档）的不同视角：

#	问题	建议决议
D1	/recall 处置	保留为薄预设入口：同实现、仅默认值差异 + v1 字段别名；下一 minor 拆的是别名不是端点
D2	组装模式触发	显式 mode:"context"（组合歧义最少）
D3	档位命名	detail auto|abstract|overview|full，对齐 ContextLevel；消灭 bool 与 summary 混称
D4	resources/skills 桶 + purpose 进首 PR	同 PR（「用途配比」的意义所在）；规模超限时首选切出项
D5	purpose 预设存放	内置两档 + retrieval.purpose_profiles 配置覆写
D6	MCP recall 工具	保留工具名（agent 人体工学；与 REST 解耦）
D7	context 模式下 target_uri	首版 422；filter/tags/时间窗 先透传（免费红利），target 求交待需求
D8	预算单位	search 面仅 max_tokens（默认 1600）；/recall 别名折算；估算器保持启发式（±15%），不引入 tokenizer 依赖
D9	L3 rewrite 进首 PR	同 PR（原型已验证、纯增量参数）；第二切出项备选
D10	rendered 输出格式	扁平 XML（元数据属性化）；微观细节实现期定稿
D11	服务端记账去重进首 PR	同 PR（实现薄：sidecar + total_message_count 轮距；opencode/pi 等零实现受益）
D12	bootstrap（§3.6）	fast-follow；形态定为 mode:"bootstrap"，不新增端点
D13	detail 默认值	auto（实测分数窄带、排序区分度弱，广度优先更鲁棒；要贪深显式传 full）

附录：本提案依据的关键代码事实（main, v0.4.9）

• FindRequest/SearchRequest 同构性、RecallRequest v1 字段全集：openviking/server/routers/search.py
• /search 退化条件与 IntentAnalyzer 触发分支（无保险丝）：openviking/storage/viking_fs.py
• session 上下文构成（archive overview + 近 20 条消息）：openviking/session/session.py
• 检索模式仅由 rerank 配置决定、default_search_mode 未接线：openviking/retrieve/hierarchical_retriever.py
• ContextLevel L0/L1/L2：openviking/core/context.py；目录 sidecar：storage/queuefs/semantic_sidecar.py；单文件 abstract 仅存索引 payload（~447B）：utils/embedding_utils.py
• /recall 档位降级与 summary 双重来源：openviking/retrieve/type_quota_recall.py
• MCP 工具注册与 /recall 直调：openviking/server/mcp_endpoint.py
• SDK/CLI 均无 recall 暴露：sdk/python、sdk/go、sdk/typescript、crates/ov_cli
• vikingbot 进程内 type-quota：bot/vikingbot/agent/memory.py
• 实验分支拆件素材（_recall_query_plan、retrieve/recall_rewrite.py、compact 渲染器、并行读、超时配置及测试）：feat/auto-recall-v2