# Jev 意图导向搜索：V3 契约

`adaptive_search` 是**搜索结果筛选工具**，不是自主研究或答案验证工具。主 agent 提供问题、关键词和搜索意图；Jev 判断哪些结果值得阅读、哪些关键词值得继续；代码执行查询、维护状态并控制预算。主 agent 负责读原文、证据核实和最终回答。

## 输入

```json
{
  "questions": ["ExampleDB 4.2 升级有哪些兼容风险？"],
  "keywords": ["migration guide", "breaking changes"],
  "intent": "优先实际迁移步骤与具体不兼容案例；保留反证，不需要营销介绍。",
  "page_size": 20
}
```

- `questions`：1–6 个非空问题，每个≤400字符。单问题可配扁平 `keywords`；多问题必须使用逐项对应的二维关键词列表。每组1–4个词，每词≤100字符。不传则以问题本身为检索词。
- 也可使用 `tasks:[{context, time_range?, targets:[{id, keywords, question, intent?, facts?}]}]`：最多6任务、每任务4目标、总计12目标。任务模式不能传根级 `keywords`，与 `questions` 二选一。
- 根级 `intent` ≤2000字符，目标级 `intent` ≤1000字符，均须非空；两者共同作为判断上下文并参与执行去重。它们是简洁搜索偏好，不是私密推理、凭据或秘密。意图送往配置的 Jev 服务，但不直接拼入引擎查询。
- `facts:[{id,question}]` 为兼容旧调用而保留，最多8个、ID唯一。V3将其解释为**可选搜索主题**，不要求全部回答，不自动生成事实。
- `time_range:{start,end,basis}` 是包含边界的日期约束；`basis` 为 `published` 或 `event`，不以发表时间推断事件时间。相对今天/昨天按调用开始时UTC解释；未知日期不能通过显式日期门。
- 翻页只传 `cursor` 和可选 `page_size`，不能同时传问题、任务、关键词或意图。

## 数学模型

每个当前审查片段：切题度 `r`、阅读价值 `v`、方向帮助度 `d`。

```text
u = min(r,v) × (1−λ+λd)
λ = 0.2（有 intent），否则 0
A_k = max_i(u_i × m_ik)
F = Σ_f w_f max_i(u_i × m_if)
R_k = Σ_f w_f Σ_{j=2..n_f} (1−ρ)ρ^(j−2)q_fj，ρ=0.5
S_k = 0.25 A_k + 0.90 F + 0.10 R_k
```

`m` 是上下文中的关键词/主题匹配分，仅大于0.5才计分。`w` 为归一化主题权重；有调用方主题时跨关键词共享主题覆盖，没有时以当前关键词为主题（`F=A_k`）。`q_fj` 是同一主题下按质量降序排列、重复分组后各组最强结果的 `u×min(m_ik,m_if)`。新主题的首条只赚F，不冒充该主题的额外重复佐证。

首条建立基础分；新主题按权重增加最大覆盖，不因文档序号打折；只有额外重复主题结果的补充收益递减。同站及近复制保守归组仅影响R，不取消新主题的F。重复轮次不产生分数。这里的R表示补充阅读价值，不证明来源独立或事实得到佐证。

筛选门：已知有限的 `r>0.60`、`v>0.50`、注入风险 `≤0.7`，且满足显式日期约束。方向分**不是硬门**；反证也能高度符合任务。方向未知保留null、不加方向奖励；缺失必要判断不通过筛选。可信导航线索、需要进一步打开的页面、局部有用信息均可有高阅读价值，不要求摘要已经包含答案事实。

这些权重与阈值是未校准的工程起点。`u/S`都不是正确率。S仅供续搜参考，不存在“S过线且所有事实齐全才完成”的规则。

## 执行与停止

```text
问题＋绑定关键词＋意图
  → 代码构造候选查询，Jev选择查询/引擎
  → 搜索、去重、审查摘要或引擎提供的文本
  → Jev typed noul/choice 判断阅读价值、方向、匹配
  → 每关键词 typed choice：continue / satisfied / exhausted
  → 代码维护队列、处理 pending、检查预算并返回结果
```

- `satisfied` 必须至少有一条**当前有效且符合该关键词**的可用结果；不是完整答案。
- `exhausted` 意为当前未见值得继续的路径，不是成功或不存在的证明。引擎未成功或候选尚待审查时不接受该结论。
- `pending` 表示续搜判断缺失、无效或未能完成；不能替代满足/找不到。
- 已改变片段不能继续支撑旧的满足判断；同URL增加新材料或日期元数据，也会使旧的 exhausted 判断重开。后来补到的发表日期会让日期相关评分重新审查，而不是沿用“日期未知”时的旧判断。当前有效的既有结果不会因后续服务失败被抹掉。
- 必要字段或可用材料的关键词匹配缺失时，优先有界重审：同一审查版本（文本＋发表日期）最多两次、同一轮最多一次，仍受原调用/HTTP/token上限约束。用尽重审额度仍保留 pending 计数，不把未知改成否定，也不无限阻塞其他查询。
- 连续分数不变不等于没有可搜内容：还有未尝试的关键词查询或可重审材料时继续；搜索调用额度用尽明确报告 budget_calls。分批续搜判断中断后，未执行批次都标为 pending。
- 队列全关闭时 `stopReason=keyword_queue_empty`；只要包含 exhausted，`retrievalSufficient` 就为false。预算/截止/取消/服务失败分别报告，不能假装成功。
- 默认没有自动正文抓取、引用追踪、事实联合判断或最终完整性验收。Jev不自由生成关键词、摘要或答案。

固定上限：6轮、30次搜索、72次逻辑Jev请求、80次HTTP尝试（含重试）、120万估算输入token；每轮全局最多500唯一URL、每微批最多24关联并受字节上限约束。后续轮按待搜关键词比例恢复配额。宿主截止时间仍适用。500是容量，不保证检索得到或全部审查500条；单引擎结果帽仍可远低于500。为续搜决策预留预算，未审查项公开计数。

## 输出和兼容

分页结果含：

- `schemaVersion:3`
- `results:[{url,title,description,valueScore,directionMatch,kind,matches}]`，按阅读价值排序、URL去重。`description` 为审查过的抽取文本，不是生成总结。列表按单结果 `u/valueScore` 排序；关键词 `S` 仅供续搜判断参考，不直接作为URL排序分。`kind` 为 direct/lead/counterevidence/context/unknown。同URL跨目标合并时，顶层分数/方向/类别和摘录取最强结果；`matches` 保留各目标 taskId/targetId/canonicalId、分数、方向和类别，不能把顶层方向分套用到所有目标。相同目标复用一次执行时，仍保留每个原始目标身份。
- `retrievalSufficient`：是否所有关键词均满足搜索需求，**不是答案完整性**。
- `keywordProgress`：目标身份、关键词、status/reason、score/A/F/R、distinctEvidence和目标状态。
- `pendingAssessments`：已收集但未完成审查的关联数。
- `coverageComplete`：废弃兼容字段，V3恒为false，表示不再评估答案完整性。**不得把它改为 retrievalSufficient 的别名**。旧消费者应迁移到新字段和状态，而不是因它为false反复重跑。
- `stopReason`、`warnings`、`totalResults`、`nextCursor`、`expiresAt`。

单页默认20、最多50，另有软字节预算；极大单项可完整返回并警告。累计返回没有固定条数帽，但检索和审查有预算。所有候选并非都会获准；未审查/拒绝项不发布。游标只读取本进程内存，最多保留30分钟/32次结果；进程重启、到期或淘汰后失效。分页完毕不代表全网穷尽。

MCP/Pi/DSH共用核心输入、描述与渲染逻辑；MCP的Zod和DSH的输出schema同步维护。未配置Jev时工具仍注册，但返回not_configured且不发起网络请求。任务/意图/必要片段会发送到配置的Jev服务（默认TypeSafe），引擎凭据不会发送。调用授权不包括更改凭据或持久设置。

## 验证与限制

`npm run test:retrieval` 检查新默认控制器、数学性质和公开接口；完整离线门为 `npm run prepublishOnly`。旧V1/V2测试显式冻结内部策略，仅作历史回归，不能证明新默认质量。旧设计资产保持原样，见 [事实控制器历史记录](jev-fact-implementation.md)。

尚无新方案的独立真实网页质量校准。合成500条测试只证明容量/预算路径；不证明真实召回、阅读价值或时延提升。来源分组可能过度合并同站独立文章，也可能漏掉改写转载。摘要不足不证明原文没有价值；关键论断仍由主agent读原文核实。

## 自审回归记录

本轮主执行器直接自审，先以失败测试复现缺失评分不重审、exhausted未随同URL新内容重开、停滞过早停止、规范化目标丢失归属、分批失败漏标pending、零成功引擎被当成成功、补充发表日期未触发重审，再修复验证。

新默认测试：12项评分代数、41项循环与边界测试、公开接口检查；完整 `npm run prepublishOnly` 通过。日志：`/tmp/jev-self-review-prepublish.log`。本轮没有子代理、真实搜索或在线Jev质量校准；离线通过不是线上效果证明。未提交或发布。