Tekmeria

可核验的引文：由服务端签发的句柄，以及针对生物医学证据的确定性审计

概览 • 快速入门 • 结果 • 引文的工作原理 • 架构 • 评估 • 用法 • 引用

离线演示中的审计视图：每个句子都有状态，每条引文都有判定。该答案因包含一条伪造引文和一条格式错误的引文而未通过。

概述

该项目不参与争夺覆盖范围的竞赛。BioMCP 已覆盖约 70 个生物医学数据源，而检索本身帮助有限：生物医学 RAG 相较于不使用检索，通常只提升 1 到 2 个百分点（Nourbakhsh et al.）。模型往往在引用上出错：

• 在要求模型引用时，Ahmed et al. 中表现最好的模型给出的 PMID 只有 15.3% 相关，其余大多对应真实存在但属于无关领域的论文；
• 在 Chen et al. 中，当强化学习只奖励正确答案时，医疗 Agent 的引用伪造率从 16.5% 升至 31.8%。

协议也指向同一方向：2026-07-28 MCP 修订版指出，需要在多次调用之间保持状态的服务应使用“显式、由服务签发并作为普通工具参数传递的句柄”。

其他项目也选择信任工具，而非模型。Agent 运行时可以为每次工具调用签发签名回执，并核验引用该回执的主张（Basu）；渲染器可以仅在数值与其所指记录相符时将其标记为已验证（Solatorio）；通过 MCP 访问的基因组编写工具层则要求每个数值都必须来自经过验证的工具（Ali et al.）。Tekmeria 将这一理念应用于生物医学内容片段的引用：模型写出的句柄本身经过了认证，因此无论答案由哪个模型或 MCP 主机编写，签发句柄的服务都能仅凭自己的密钥进行核验。

状态。 研究软件，版本 0.1.1。引用约定单独进行版本管理，当前为 0.1.0；当版本号处于 0.x 时，任何不兼容变更都会提高次版本号。变更记录见 CHANGELOG.md。技术说明介绍了设计和评估：10.5281/zenodo.23374728。

快速开始

你需要安装 uv（如果需要，它会安装合适的 Python）。无需 API 密钥。运行一条命令即可使用记录的响应运行离线演示，并在浏览器中打开其审计报告：

uvx tekmeria demo --open

要在聊天中使用 tekmeria，请将其添加到 Claude Desktop 或 VS Code 等 MCP 主机：参见用法。该命令会从 PyPI 安装已发布的软件包。若要改为运行开发版本，请使用 uvx --from git+https://github.com/PedroMarkovicz/tekmeria tekmeria，或将本地克隆路径传给 --from。

结果

引文的工作原理

pmid:30831578/abstract.7~ae2tc
\__/ \______/ \________/ \___/
scheme  id      path     check code: HMAC of everything before the "~"

flowchart TD
    C["A citation: a handle, and perhaps a quote"] --> G{"Does it match the handle grammar?"}
    G -- "no" --> M["malformed"]
    G -- "yes" --> K{"Does the check code match this installation's key?"}
    K -- "no" --> F["forged"]
    K -- "yes" --> R{"Could the source be reached?"}
    R -- "no" --> U["unavailable"]
    R -- "yes" --> P{"Do the record and the passage still exist?"}
    P -- "no" --> W["withdrawn"]
    P -- "yes" --> Q{"A quote, and not verbatim in the text as issued or as it is now?"}
    Q -- "yes" --> X["quote_mismatch"]
    Q -- "no" --> O["ok, with flags: retracted, preprint, version_changed"]

架构

flowchart TB
    subgraph HOST["MCP host: Claude Desktop, VS Code, MCP Inspector"]
        MODEL["Model"]
        VIEW["Audit view<br/>an MCP App"]
    end

    subgraph SERVER["server/ : MCP layer"]
        TOOLS["7 tools, a prompt,<br/>2 resource templates"]
    end

    subgraph CONTRACT["contract/ : pure and typed"]
        CODEC["Handle codec<br/>HMAC-SHA256, 25-bit check code"]
        AUDIT["Citation parsing and the audit"]
    end

    subgraph SOURCES["sources/ : evidence service"]
        SVC["Routing, merging, time budgets,<br/>handle minting and resolution"]
    end

    subgraph UP["Upstream APIs"]
        APIS["PubMed, Europe PMC, PubTator3, Crossref,<br/>ClinicalTrials.gov, openFDA"]
    end

    INFRA["infra/ : keys, rate-limited HTTP,<br/>SQLite cache, recorded fixtures"]

    MODEL <--> TOOLS
    TOOLS --> SVC
    TOOLS --> AUDIT
    AUDIT --> CODEC
    AUDIT --> SVC
    SVC --> CODEC
    SVC --> APIS
    SVC --> INFRA
    AUDIT -- "report" --> VIEW

各层职责

演示

tekmeria demo 使用录制的响应离线运行。它会搜索、获取两篇论文，并审计一个答案，其中植入了六种情况：正确引文、错误引文、伪造的校验码、格式错误的句柄、引用已撤稿论文，以及未引用的句子。以下是审计结果：

verdict: FAIL  (5 citations: 1 malformed, 1 forged, 1 quote_mismatch, 2 ok)
fabricated: 1  retracted cited: 1  cited sentences: 2/6  verbatim quotes: 1/2
[1] cited: A nationwide Danish cohort found no increased risk of autism after MMR vaccination.
    ok             pmid:30831578/abstract.7~ae2tc "During 5 025 754 person-years of follow-up, 6517 children were diagnosed with autism"
[2] invalid_only: The same study concluded that MMR vaccination raises autism risk.
    quote_mismatch pmid:30831578/abstract.9~wdbv3 "MMR vaccination strongly increases the risk of autism"
                   closest: "MMR vaccination does not increase the risk for autism" (0.8491)
[3] invalid_only: A second cohort reported the same null association.
    forged         pmid:30831578/abstract.7~ae2t0
[4] invalid_only: Earlier reviews reached the same conclusion.
    malformed      pmid:30831578-abstract
[5] cited: A 1998 case series that proposed a link was later retracted.
    ok             pmid:9500320/abstract.4~z567x [retracted]
[6] uncited: Parents should discuss the vaccination schedule with their paediatrician.

在聊天中

一次真实运行

2026-10-07，Claude Desktop 中的模型按照 cite_by_handle 的说明回答了 “MMR 疫苗接种会导致自闭症吗？”，随后审计了自己的答案：

verdict: WARN  (16 citations: 16 ok)
fabricated: 0  retracted cited: 0  cited sentences: 13/21  verbatim quotes: 4/4

评估

tekmeria evaluate用于衡量审计的判定效果。它会在 34 个类别中植入正确结论已预先确定的引文：

• 真实引文，包括逐字引用，以及采用比较逻辑必须接受的排版变体的引文：空格、分解形式的重音符号、比较逻辑会折叠的所有破折号、撇号和引号，以及会移除的不可见字符；
• 只改动一处细节的引文：数字、小数点、比较符号、单位、负号、字母大小写、添加的重音符号、上标数字、删除的空格、插入的“not”或调换的单词；
• 伪造的核对码、路径和记录 ID，写在方括号外的伪造句柄、格式错误的句柄，以及写在引文内的注释；
• 不存在的段落和记录，以及已宕机的来源；
• 已撤回的论文、预印本和较早版本的记录；
• 藏在未闭合引号内的伪造句柄；
• 同一句中与真实引文并列的错误引用或已撤回记录引文。

案例的构建方式。

• 案例基于演示项目已记录响应中的 7 条真实记录（213 个段落）。
• 已撤回和不可用案例引用虚构路径、虚构记录，以及被视为无法访问的记录。
• 每个案例植入的内容由一个参考判定器决定，该判定器依据规范编写，且与审计不共享任何代码。但它并非独立：两者由同一位作者编写。

评分方式。

• 每个案例都会以结构化声明的形式和模型可能使用的某种引用格式的答案文本形式进行审计。裸句柄和隐藏句柄案例只对答案文本运行，而将引号嵌套在引文中的两个类别只对结构化声明运行。同一案例的两种审计使用相同的植入引文，因此并非独立观测。
• 只有当每条引文都得到植入的判定和恰好对应的标记时，案例才算通过。
• 这些案例也会写入由多个句子构成的完整答案。只有当每个句子的状态、每条引文、每项指标和最终判定都与植入内容一致时，完整答案才算通过。声明状态、指标或最终判定中的错误不会影响引文本身的判定，因此只有完整答案才能发现这些错误。完整答案分为三种：
  • 混合：每次取四个案例，全部纳入，并添加标题、粗体引导语和无引文句子；
  • 纯净：仅含真实引文，且应通过；
  • 配对：从每个可写成答案文本的类别中，选取第一个案例（34 个类别中有 32 个），放在两个各自包含一条真实引文的句子之间，以便评估该案例对最终判定的影响。无论单独出现在一句中，还是与真实引文并列，引用不匹配或已撤回的引文都会产生 warn。
• CI 会在推送到 main 和创建拉取请求时运行评估。

其输出如下，种子为 0，每个类别 25 个案例：

选项。 --seed（默认值为 0）和 --per-category（默认值为 25）用于选择案例；--json-out 会写入完整报告，其中包含混淆矩阵。

如何解读。

• 小型样本池会被重复抽取：参见“不同案例数”。
• 植入的引用主要来自药品标签和试验：参见最后一个表格。
• 评估结果表明，审计能正确判定这些植入的错误。但这并未说明模型多常犯这类错误：要了解这一点，需要使用真实模型进行多次运行，例如上面的运行。

注入故障。 python -m tekmeria.evaluation.faults 每次破坏审计的一项判定（模拟真实 Bug），然后重新运行评估。38 个故障均为手动挑选：

• 比较器过于宽松：忽略大小写、标点、变音符号、空白字符、NFKC，或只检查前 40 个字符；
• 逐一移除合约的 19 种折叠规则，并加入一种未将不换行空格识别为空白字符的故障（单独删除该折叠条目本身不会改变结果，因为空白字符规范化已将其识别为空格）；
• 不再删除 4 种不可见字符中的任一种；
• 校验码忽略路径、标志被删除，以及声明状态、覆盖率、有效性和整体判定规则错误；其中包括早先的两条规则：仅被无效引用引用的句子，或有效引用旁边存在无效引用时，都不会触发警告。 它能捕获其中 37 个。漏掉的那个会连同原因一并列出：快照中的段落都不含省略号，因此无法植入省略号折叠故障。CI 每个类别运行 10 个用例，足以让每种破折号和引号都出现。

变异分数。 python -m tekmeria.evaluation.mutants 的筛选没那么严格。它每次对审计代码做一处小改动（引文解析器、句柄编解码器、引文比较逻辑和审计本身），然后针对每处改动运行评估。改动会否定一次比较或将其移到边界之外、互换 and 和 or、移除一个 not、翻转一个布尔值，或给整数加 1。字符串和正则表达式常量不会被修改，因此分数几乎不能说明引文语法或折叠表的情况：注入故障的测试已覆盖了这些内容。

• 评估杀死了 78 处改动中的 71 处：52 处导致结果错误，19 处导致崩溃。
• 还有一处改动会阻止快照加载，因此评估无法对其进行判断，故未计入分数。
• 七处未被杀死的改动中，有三处对当前源解析器能够构建的任何记录都不起作用：两处位于 preprint 规则中，该规则的两个信号总是由解析器同时设置；另一处涉及粗体引导语的处理，其效果会被后续步骤移除。
• 剩余四处是未能检出的故障：评估未评分的 checked_against、一个空引文（两处改动），以及普通 [1] 方括号文本。
• 以下内容超出范围，因此从未被修改：诊断信息 closest_match、check_handles 工具、密钥长度检查、游标签名，以及仅证据服务使用的记录 ID 解析和段落寻址。

有些类别的段落数量很少：只有一个段落含有带重音字母，因此分解重音类别只测试一个字符。

用法

快速入门会运行离线演示。若要在聊天中使用 tekmeria，请将其添加到 MCP 宿主：

{
  "mcpServers": {
    "tekmeria": {
      "command": "uvx",
      "args": ["tekmeria"]
    }
  }
}

{
  "servers": {
    "tekmeria": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tekmeria"]
    }
  }
}

npx @modelcontextprotocol/inspector uvx tekmeria

命令

配置

所有配置均为可选项，且从环境变量读取；不会读取 .env 文件。

此外，还有一个提示词 cite_by_handle，以及两个资源模板 evidence://record/{+record_id} 和 evidence://passage/{+handle}（+ 可让句柄中的斜杠原样通过）。

开发

检查方式

uv sync
uv run pytest            # Python tests, offline (recorded fixtures)
uv run ruff check && uv run ruff format --check && uv run pyright
uv run pytest -m live    # smoke tests against the real APIs

审核视图：

cd web
npm ci
npm test && npm run typecheck
npm run build            # rewrites src/tekmeria/ui/audit-view.html; commit it

仓库

它无法告诉你的内容

• 某段内容是否支持其对应的句子。 审计会检查引用是否由此服务签发、其中的段落是否仍然存在，以及任何引文是否为逐字引用（与签发时或当前文本一致）。但不会检查内容是否构成支持。
• 医疗建议。 Tekmeria 会检索和审计证据，但不会对证据作出判断，其返回的内容均不构成临床指导。它会查询公开的生物医学 API，且并非为患者数据而构建。
• 注册库的旧版本。 ClinicalTrials.gov 和 openFDA 只提供记录的当前版本；如果引用的旧版本已变更，系统会标记为 version_changed，但只能从 tekmeria 的缓存中获取其旧文本。
• 来自其他安装实例的句柄。 句柄只能在签发它的安装实例（密钥）上验证。
• PubMed 图书章节。 搜索会排除 StatPearls 或 GeneReviews 等记录，获取此类记录时会报告未找到。
• 跨页去重的结果流。 search_literature 不会在同一页显示同一条记录两次，但该记录可能会在后续页面再次出现。

贡献与支持

• 遇到问题或有疑问： 请提交议题。如果判定有误，请附上你审计的答案文本和报告；句柄只能在签发它的安装实例上验证，因此请说明你是否使用了演示密钥。
• 发现漏洞： 请按照 SECURITY.md 中的说明，通过仓库的 Security 选项卡私下报告。
• 提交更改： 欢迎提交拉取请求。CONTRIBUTING.md 列出了需要运行的检查，以及更改需要满足的要求；如果更改会影响审计判定，则需要在评估中加入相应案例。
• 权利持有人希望删除已记录的条目时，可以按照 NOTICE 中的说明提交议题。

引用

@software{markovicz_tekmeria,
  author  = {Markovicz, Pedro},
  title   = {tekmeria},
  note    = {Server-issued citation handles and a deterministic audit for biomedical evidence},
  version = {0.1.1},
  year    = {2026},
  doi     = {10.5281/zenodo.23376855},
  url     = {https://github.com/PedroMarkovicz/tekmeria},
  license = {Apache-2.0}
}

@misc{markovicz_tekmeria_note,
  author    = {Markovicz, Pedro},
  title     = {Tekmeria: Server-Issued Citation Handles and a Deterministic Audit for Biomedical {LLM} Answers},
  year      = {2026},
  publisher = {Zenodo},
  note      = {Preprint, version 1},
  doi       = {10.5281/zenodo.23374729}
}

数据与许可