Evidence Sieve · 证据筛

面向 Agent 的本地证据筛选小工具：检索后保守去重、保留来源、按版本和对象过滤，通过 CLI / MCP / Skill 使用，不需要修改 Agent 源码。

适合这样的场景：多个文档反复描述同一个事实，直接 Top-K 被重复段落占满，真正的限制条件和互补信息进不了上下文。

实验定位：有条件地有用，尚未证明优于通用 MMR，也未测试最终 Agent 答案正确率。 在 12 个作者编写的中英文同义场景中，独立事实覆盖从 Top-K 的 69.44% 提高到 80.56%，但 MMR 达到 86.11%。在 12 个差异保护场景中，普通向量去重只保留 75% 的必要证据，本工具保留 100%。这些是小规模机制测试，不是独立盲测。完整对比、公开数据实验与负结果。

公开 BEIR SciFact（5,183 篇文档，全部 300 个测试问题；最多 6 条、3,000 token 预算）的实测结果：

压力条件给检索前 5 篇文档各加 3 个精确副本。它证明重复会挤占证据位置，不能证明语义去重优于精确去重。 自然语料没有观察到 Sieve 的额外增益；压力条件下输出 token 从 Top-K 的平均 2,166 增至 2,472，不作省 token 宣传。

它做什么

flowchart LR
    A[Agent 的问题] --> B[本地文档检索]
    B --> C[严格过滤版本和对象]
    C --> D[广召回候选]
    D --> E[保守去重与来源归组]
    E --> F[按相关性和预算选择原文]
    F --> G[返回证据包给 Agent]

同义段落只显示一个代表原文，同时保留组内来源 ID。遇到规则能识别的数字、否定、单位、条件、代码标识符、版本和对象差异，会拒绝语义合并。释放的名额从剩余候选中按相关性补位，低于阈值的不拿来凑数。这仍是启发式规则，不能保证找出所有重要差异。

提供五种策略供实际语料比较：topk、mmr、naive_dedup（仅向量阈值）、exact（空白归一化后精确去重）和 sieve（默认，保守语义去重）。它们共用检索编码器、过滤和预算。

Related MCP server: RAG In A Box MCP Server

安装和第一次查询

要求 Python 3.11+。项目目前从 GitHub 安装，尚未发布到 PyPI。

Windows PowerShell：

git clone https://github.com/2gg-bit/evidence-sieve.git
cd evidence-sieve
python -m venv .venv
.venv/Scripts/python.exe -m pip install -e ".[semantic]"
.venv/Scripts/python.exe -m evidence_sieve.cli search --corpus examples/corpus.jsonl --encoder semantic --query "备份保留多久，维护期间执行吗？" --version 2 --scope atlas

macOS / Linux：

git clone https://github.com/2gg-bit/evidence-sieve.git
cd evidence-sieve
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[semantic]"
.venv/bin/python -m evidence_sieve.cli search --corpus examples/corpus.jsonl --encoder semantic --query '备份保留多久，维护期间执行吗？' --version 2 --scope atlas

语义模式使用本机 CPU，无 API Key。首次运行从 Hugging Face 下载 多语言 MiniLM 模型，也会下载 tiktoken 编码文件；后续可复用缓存。安装 [semantic] 会包含 PyTorch 等较大的依赖。

若只想先验证接入，可安装 pip install -e . 并省略 --encoder semantic，使用默认 tfidf。TF-IDF 是词面检索，不等同于语义去重能力。 本项目实验也保留了该模式的负结果。

下面的短命令假设已激活虚拟环境；未激活时请使用上面的 python -m evidence_sieve.cli 形式。

evidence-sieve search --corpus examples/corpus.jsonl --encoder semantic --query "备份策略" --budget 1500 --k 4
evidence-sieve search --corpus examples/corpus.jsonl --encoder semantic --query "备份策略" --method mmr
evidence-sieve expand --corpus examples/corpus.jsonl --id retention
evidence-sieve serve --corpus examples/corpus.jsonl --encoder semantic

serve 会等待 MCP 客户端通过标准输入输出通信，直接启动后看似没有输出是正常现象。

准备自己的文档

方式一：Markdown 文件夹。 传 --corpus /absolute/path/docs，按空行切段，来源保留相对路径和行号。它不解析标题层级、front matter、PDF 或 Word，不自动推断版本。

方式二：JSONL。 每行一个 UTF-8 JSON 对象，推荐在需要版本/对象过滤时使用：

{"id":"backup-v2-a","text":"备份保留 7 天。","source":"kb-a/backup.md#L12","version":"2","scope":"atlas","claim_key":"backup.retention","claim_value":"7 days"}
{"id":"backup-v2-b","text":"维护期间暂停自动备份。","source":"kb-b/operations.md#L8","version":"2","scope":"atlas"}

可把不同知识库的段落合并到一个 JSONL，保持 ID 唯一、来源清楚。不要把 scope 仅作为文件夹名随意填写：它会阻止跨 scope 合并，也影响严格查询过滤。

--version 2 只匹配元数据恰好为 "2" 的条目，缺少版本的条目会被排除。conflicts 只比较已选证据中、显式填写的 claim 元数据，不是通用自然语言矛盾检测器。

输出与参数

输出 JSON 的 evidence 每项包含代表原文、相似度、版本/对象和 sources；合并来源的 ID 仍可用 expand 查看。不会生成摘要或修改原文。stats.duplicates_collapsed 是整个候选池中归组的数量，不表示这些组最终都被选中。

预算包括原文、所有来源和冲突信息，不含 MCP 外层包装、宿主提示和后续展开请求。不同宿主模型 tokenizer 不同，因此不能把这个上限当作实际账单。过长段落整个跳过，不偷偷截断；若来源列表过长，也可能导致整组无法装入预算。

接入 Claude Code / Codex / OpenCode / Pi

查看 完整接入说明，含绝对路径配置、Skill、环境变量、提示词示例和故障排查。标准 MCP 提供 search_evidence、expand_evidence 两个工具。Pi 等可调用 CLI。

只筛选经本工具查询的资料，不会自动替换 Agent 的全部文件读取或搜索。 只有候选仍留在服务内部、筛选结果才进入会话时，才可能改善上下文利用。

已有检索系统怎么复用

Python API 可以对自己的候选及向量进行筛选，无需重新构建一个知识库：

from evidence_sieve import Document, EvidenceSieve, SearchOptions

# candidate_vectors 与 query_vector 必须由同一编码模型生成；行顺序与 documents 一致。
documents = [Document(id="a", text="备份保留 7 天。", source="kb/a.md", version="2")]
engine = EvidenceSieve(documents, vectors=candidate_vectors)
packet = engine.search("备份保留多久？", SearchOptions(version="2"), query_vector=query_vector)

示例中的两个向量变量由调用方提供。当前没有内置 Qdrant、Milvus、云知识库连接器，也没有重排模型。

实验和开发

查看 实验报告、预先记录的协议 和 逐条原始结果。包括 24 个中英文机制场景、公开 SciFact 的全部 300 个测试问题、自然语料与人工重复压力条件、五种策略对比。实验脚本不把 gold/qrels 输入算法。

python -m pip install -e ".[semantic,benchmark,dev]"
python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m build
python benchmarks/run_controlled.py --encoder semantic --revision e8f8c211226b894fcb81acc59f3b34ba3efd5f42 --output results/controlled-semantic.json
python benchmarks/run_controlled.py --encoder tfidf --output results/controlled-tfidf.json
python benchmarks/run_scifact.py

公开数据默认从 BEIR 官方 Hugging Face 镜像下载，数据与 embedding 缓存在忽略的 work/，模型在 Hugging Face 缓存中。实验报告记录固定数据/模型 revision、数据摘要和依赖版本；时间指标受硬件、缓存和负载影响。

当前边界

• 原型通过本地 CLI 和真实 MCP 协议测试；未做各 Agent 宿主的完整模型任务评测。

• 守护规则覆盖有限，中文数字、实体关系、复杂条件等可能误判；高相似度不是含义相同的证明。

• 默认语义模型最多编码 128 个模型 token，长段落尾部可能无法参与相似度计算；返回的原文仍是完整段落。推荐自行准备短且语义完整的切块。

• 内存内全量索引，没有增量更新、持久化向量库或大规模性能保证。TF-IDF 使用稠密矩阵，大语料可能占用大量内存。

• 不自动判定来源权威性、不推断哪个版本最新、不消除自然语言冲突。

• 目前没有下游生成模型对比，不能宣称减少幻觉、提高答案正确率或降低总成本。来源元数据和补充事实可能使返回 token 增加。

MIT 开源。外部模型和数据各自遵循原许可证；公开 SciFact 文本不随本仓库分发。数据来源与许可见 实验报告。