openevidence-tools

# OpenEvidence 工具 *[繁體中文版 → README.zh-TW.md](README.zh-TW.md)* 两个相互配合的部分，使 [OpenEvidence](https://www.openevidence.com) 成为一个值得信赖的证据来源： 1. **MCP 服务器**，将 OpenEvidence 暴露给任何 MCP 客户端（例如 Claude Code），作为四个工具 — `ask_openevidence`、`list_recent_oe_queries`、`fetch_oe_result`、`ask_oe_followup`。 2. **`/oe-verify` 技能**，它会交叉检查 OE 答案中的每个引用与原始来源，并标记 OE 遗漏的内容。 **为什么需要两者？** OpenEvidence 快速回答临床问题，但它是一个 RAG 管道（向量搜索 + LLM 合成），其引用可能不正确，即使底层声明是真实的。经典的失败是 **传递性引用**：OE 检索了一篇评论的全文，其中评论引用了另一项试验的数字，然后将该数字归因于评论本身。声明是真实的；归因是错误的。**请勿在未经验证的情况下吸收 OE 答案** — 这就是 `/oe-verify` 存在的原因。 --- ## MCP 服务器提供的功能 | 工具 | 目的 | |---|---| | `ask_openevidence(question, preserve_citations=False)` | 提交新的临床问题；返回基于证据的答案 + 引用。自动记录 article_id 以便恢复。 | | `list_recent_oe_queries(limit=20)` | 列出最近提交的查询（时间戳、article_id、问题）— 恢复中断运行后的 article_id。 | | `fetch_oe_result(article_id, preserve_citations=False)` | 通过 ID 重新获取以前提交的答案。这是一个 GET 请求，不会消耗任何问题配额。 | | `ask_oe_followup(parent_article_id, followup_question, preserve_citations=False)` | 在同一个对话线程中深入探讨；OE 将之前的问答作为上下文进行扩展。 | ### `preserve_citations=True` — `/oe-verify` 使用的出处通道 当 `preserve_citations=True` 时，答案会保留其内联 `[N]` 标记，并追加一个 `## Citation Data` JSON 块。每个条目都包含验证器所需的元数据 — `title`、`doi`、`pmid`、`journal`、`authors`、`publication_types`、`impact_score`、`recency_days`、`is_guideline`、`url`，以及两个出处字段： - **`origin`** — 引用块的来源。OE 以 ROT-1 方式混淆（每个字节偏移 +1，因此 `_` 到达时为反引号）；服务器解码它，例如 `` mbodfu`gvmmufyu`tdsbqfe`w3 `` → `lancet_fulltext_scraped_v2`。 - **`origin_risk`** — 从 `origin` 导出的传递性引用风险等级： | 等级 | 来源 | 含义 | |---|---|---| | **高** | `*_fulltext_scraped_*`（lancet、nejm、aan、…） | 抓取的**评论全文** — 引用的句子通常是评论引用**他人的**试验。这是 OE 的主要失败模式。 | | **中等** | `wiley_cdsr_fulltext`（Cochrane）、`wiley_research_fulltext`、`guidelines_fulltext_*`、`media_annotated_gemini` | 出版商全文 / AI 注释图表 — 真实块，但不一定是论文自己的发现。 | | **低** | `pubmed_abstracts_*` | 摘要级别；几乎没有误归属的空间。 | | **未知** | 没有跨度元数据 | 出处不可用 — 被视为中等，从不视为低。 | `/oe-verify` 使用 `origin_risk` 来瞄准其归属检查：高/中等块支持**量化**声明是危险区域，每个此类引用都被追溯到该数字是否真正是**该论文的**发现。 > 一篇论文可以合法地拥有多个 `[N]` 索引 — OE 按检索的**块**索引，而不是按论文索引（观察：7 篇论文中有 10 个索引）。服务器按位置映射标记到引用对象（第 i 个 `[N]` 出现 == 文档顺序中的第 i 个引用对象），并且在任何计数不匹配时，都会明确降低而不是猜测。 --- ## `/oe-verify` 技能 对一个 OE 答案进行三层验证（`skills/oe-verify/SKILL.md`）： - **步骤 0.5 — 存在门控**：每个 DOI 在进行任何语义工作之前都会被检查是否与 CrossRef 匹配。如果 DOI 无法解析，则为 `FABRICATED`；不会浪费代理令牌。 - **层 1 — 每个引用的准确性**（并行廉价代理）：在 Semantic Scholar / PubMed 中查找每篇论文，比较 OE 声称的内容与来源内容，并针对高/中等出处量化声明运行归属检查，以捕获传递性引用。 - **层 2 — 完整性**（一个更强的代理）：锚定在最近的系统性综述/荟萃分析，并询问 OE **遗漏**了什么，在两个方向上，以及对您自己的实践背景的适用性检查。 - **层 3 — 内部矛盾扫描**：OE 自己引用的论文是否实际上彼此同意？仅当 ≥2 篇论文对同一结果提出量化声明时才运行。 输出是一个紧凑的 Markdown 报告，带有每个引用的判决表（✅ 准确、⚠️ 高估、❌ 歪曲、🚫 捏造、↗️ 传递性、🔄 次要未追踪、❓ 无法验证）和证据景观摘要。 --- ## 要求 - **OpenEvidence 账户**（OpenEvidence 面向临床医生）。您在正常浏览器中登录。 - **本地浏览器桥接守护进程**。服务器不会抓取或伪造任何内容：它在您**自己的已登录** openevidence.com 浏览器选项卡中运行每个 OpenEvidence API 调用，通过一个监听 `127.0.0.1` 的小型本地守护进程驱动。每种请求因此都使用**您自己的账户和会话** — 与您在选项卡中点击的情况完全相同。参考实现针对一个名为 `kimi-webbridge` 的守护进程（默认端点 `http://127.0.0.1:10086/command`）；将 `OE_BRIDGE_URL` 指向任何使用相同简单 `{action, args, session}` JSON 契约的守护进程。OpenEvidence 没有公共 API，其会话 cookie 是 httpOnly，这就是为什么使用选项卡内的获取（而不是普通的 HTTP 客户端）。 - **Python 3.10+** 和 `requirements.txt` 中的依赖项（`mcp`）。 ### 配置（环境变量） | 变量 | 默认值 | 目的 | |---|---|---| | `OE_BRIDGE_URL` | `http://127.0.0.1:10086/command` | 浏览器桥接守护进程端点。 | | `OE_BRIDGE_BIN` | `~/.kimi-webbridge/bin/kimi-webbridge.exe` | 如果未运行，则自动启动的守护进程二进制文件。 | | `OE_DATA_DIR` | `~/.openevidence` | 查询日志和速率日志写入的位置。 | ### 安装 ```bash pip install -r requirements.txt # 使用 MCP 客户端注册，例如 Claude Code： claude mcp add openevidence -- python /path/to/openevidence-tools/mcp/server.py # 将 skills/oe-verify/ 放在客户端发现技能的位置。 ``` 在您的普通浏览器中登录 openevidence.com，并确保您的浏览器桥接守护进程正在运行；服务器将根据需要打开/重用 OpenEvidence 选项卡。 --- ## 负责任的使用 - **您自己的账户，您自己的会话。** 此工具自动化了您**已登录的**浏览器选项卡。请仅使用您有权使用的账户，并遵循 OpenEvidence 的服务条款。 - **尊重配额。** OpenEvidence 的账户配额约为 **100 个问题/小时**，只有新的问题和后续问题会消耗配额（重新获取先前的答案是免费的）。服务器强制实施一个内置的礼貌速率限制器（滑动窗口 + 并发上限），以保守为目的 — 不要提高它来轰炸服务。 - **在临床使用前请验证。** 在依赖 OE 答案之前，请运行 `/oe-verify`（或检查原始来源）。这是此存储库的全部意义。 - **不是医疗建议。** 这些工具帮助临床医生评估证据；它们不能取代临床判断，其输出不是医疗建议。 --- ## 致谢 — htlin222 该项目最初是独立的：我希望 OpenEvidence 答案能够流入我的笔记编写工作流程，而第一个版本通过我自己的浏览器自动化驱动了该站点。该版本因机器人检测而失效，而当我寻找前进的道路时，我发现了 **[Hsieh-Ting Lin (htlin222)](https://github.com/htlin222)** 的工作。现在，该存储库的许多优秀成果都源自他的最新更新，值得具体说明来源。 从 **[audit-oe-skill](https://github.com/htlin222/audit-oe-skill)** （MIT）中，我们获得了整个存储库的核心见解：OpenEvidence 的 `origin` 字段是 ROT-1 混淆的，它命名了引用的块的 RAG 源，并且因此可以**预测**引用被错误归属的可能性。他还命名了失败模式 — **传递性引用**，其中评论引用了另一项试验的数字，而 OE 将其归因于评论 — 并构建了我们采用的验证架构：每个引用的一个廉价代理并行，一个用于量化声明的回溯阶段，和一个扫描引用论文的单个更强代理，寻找彼此之间的矛盾，按严重/警告/注意分级。我们的 `origin_risk` 等级是他的风险表；我们的第 1 层和第 3 层是他的第 3 和第 4 阶段。当您阅读我们的验证报告时，它提出的大多数问题都是他的问题。 从 **[openevidence-mcp](https://github.com/htlin222/openevidence-mcp)** （Apache-2.0）中，我们获得了使我们摆脱困境的传输想法：OpenEvidence 没有公共 API 和 httpOnly 会话 cookie，因此不要抓取它 — 在临床医生**自己的已登录**浏览器选项卡中运行调用。我们的实现是我们自己的（并驱动一个不同的守护进程），但方向是他的。 我们编写了自己的工具层，而不是分叉，因为我们的验证器需要通过 MCP 契约本身返回 `publication_types`、`impact_score`、`recency_score`、`is_guideline` 和每个块的 `origin`，并且我们驱动一个通用的浏览器守护进程，而不是一个专用扩展程序。我们还添加了一个完整性层，他的技能没有（OE **遗漏**了什么？），一个 CrossRef 存在门控，以及一个标记↔引用索引映射，我们的架构需要这个映射，而他的架构不需要。那些是他的基础上的补充，而不是替代品。 `skills/oe-verify/` 源自 `audit-oe-skill`，MIT © 2026 Hsieh-Ting Lin；参见 [NOTICE](NOTICE)。感谢 Hsieh-Ting。 ## 与 textbook-to-note 配合使用 `/oe-verify` 设计用于插入到 [textbook-to-note](https://github.com/drpwchen/textbook-to-note) 笔记编写工作流程中，作为其可选的**证据丰富阶段**：当笔记的管理/治疗部分需要当前指导时，`ask_openevidence` 获取它，而 `/oe-verify` 在其进入笔记之前进行验证。独立使用 — 只是询问 OE 问题并验证答案 — 同样可以。