jev-documents

用途

jev-documents 用于在文档或已观察到的代码清单中定位、选择、抽取并核验证据。典型用途包括：原文片段（source-span）抽取、段落重排（passage reranking）、论断核查（claim checks），以及代码位置选择等。它帮助用户从授权来源中找到支撑性证据，并判断某条论断是否有据可依。

主要能力

在文档中定位并抽取原始片段，保留文档、页面、行等标识。
对段落进行相关性排序，使用独立的相关性问题，避免仅凭相对选择就断定答案存在。
核查论断：由宿主将论断与其引用的证据进行比对，报告无支撑或被反驳的陈述，并保留来源链接。
代码位置选择：先使用项目所需的图/索引工具，再检查所选代码后再作论断。
判断变更是否正确时，若已安装 jev-eval 则使用它，而不是把相关性分数当作代码审查结果。

使用方式

使用前需先确定服务方式，并保持该选择不变：

A：通过 OpenRouter（OPENROUTER_API_KEY）或 TypeSafe（TYPESAFE_API_KEY）调用真实 Jev。
B：使用本智能体或明确选定的可用模型（如 DeepSeek）进行模拟。

若未设置，需询问用户并等待同意；错误不会授权切换服务。仅检查密钥是否存在，绝不读取密钥值。真实调用会发送证据并产生费用，发送私密数据前需获得批准。

对于 B（模拟）：跳过 CLI/API 调用，标记 agent_simulation 或 model_simulation，在可用时标明实际模型，设置 jev_called: false、probability: null、confidence: null，返回取值、基于证据的理由和 needs_review；证据缺失时使用 null/review。不要编造 Jev 输出或概率。Choice 使用提供的标签，Noul 使用布尔值，Score 使用整数评分索引。

对于 A（真实调用）：使用现有的 jev-decide CLI，配合选定的 --provider openrouter 或 --provider typesafe。若 CLI 不存在，说明依赖关系，不要静默安装。--dry-run 是离线校验，不是判断。退出码 0 表示已选择/已评分，2 表示需复核，1 表示错误。逐一读取每个值：false 的 Noul 仍为 false。选择不等于许可，置信度不等于准确率。保留未知/复核路径。

首次请求示例（需将 <skill-dir> 解析为已安装文件夹）：

jev-decide decide <skill-dir>/assets/example.json --dry-run
# 获得批准后，使用选定 provider 发送编辑后的请求：
jev-decide decide /path/to/request.json --provider openrouter

共享 CLI 需要 Python 3.10+，不需要同级技能。宿主工具仍负责收集与执行动作。

工作流程

读取授权来源，并保留文档/页面/行标识。尽可能让解析器或正则生成精确的候选片段。
精确定义所需角色：例如发票目的地不是任意电子邮件地址。没有候选符合时包含 none。
在对所有段落排序时使用独立的相关性问题；赢得相对 Choice 并不证明答案存在。
按 ID 复制 Jev 选中的原始片段。不要让 Jev 合成抽取字段或编造引文。
宿主将论断与其引用的证据进行比对并撰写综合结论；Jev 可协助筛查大量论断，但不能替代阅读。报告无支撑或被反驳的陈述，并保留来源链接。

上下文与并行

Jev 不会继承智能体的历史记录。每个请求都需提供充分上下文：用户的信息需求、确切论断、来源 ID、周边段落、定义及相关例外。提供文本本身，而不只是 URL 或你自己的总结判断。保留必要的交叉引用，省略无关材料和机密。

对共享状态上的独立论断核查或逐段相关性评分进行批处理，而不是串行 LLM 调用。对于不同的文档组，使用有界并发，配合稳定的文档/问题 ID、速率限制以及成本/时间预算。宿主负责调度调用；CLI 没有并行调度器。同一请求中的问题无法读取其他答案：在询问未见内容前先获取所选来源。利用 Jev 的低延迟进行重复判断，而非文档生成。

适用场景

从文档中抽取并核验支撑性证据。
对检索结果或段落进行重排。
核查论断是否有据可依。
在代码库中定位相关代码位置。
判断变更是否正确（配合 jev-eval）。

限制

需先确定服务方式并保持选择不变；错误不授权切换。
真实调用会发送证据并产生费用，发送私密数据前需获得批准。
仅检查密钥是否存在，绝不读取密钥值。
CLI 不存在时需说明依赖，不要静默安装。
--dry-run 是离线校验，不是判断。
选择不等于许可，置信度不等于准确率。
Jev 不继承智能体历史，需提供充分上下文。
CLI 没有并行调度器，由宿主调度调用。
不要编造 Jev 输出或概率。
共享 CLI 需要 Python 3.10+。

自定义

替换示例中的证据、候选 ID 和标准。当真实任务可能超出标签范围时，保留无匹配路径。在启用任何自动效果前，先就宿主或人员如何消费每个答案达成一致。