Groundcheck

Groundcheck

对于精确到日期的 SOFR、EFFR 和 OBFR 百分比声明，Groundcheck 会先查询 NY Fed 的官方基准 API，再进行常规检索。例如，SOFR was 3.88% on 2026-09-29. 会与该生效日期公布的 percentRate 进行比对。 证据会保留日期、检索时间和响应摘要。缺失或含糊的公布数据会保持未验证状态；该路径不会推断日期、认证最初发布的历史版本，也不会转移语言模型的校准结果。

Agent 在给出答案前运行的事实核验。

Groundcheck 会根据实时来源核验事实声明，并返回判定结果、置信度评分和引用。任何 Agent——Claude Code、Cursor 或你自己的 Agent——都可以在任务过程中调用它，在陈述自己不确定的事实之前进行核验。

它也是Agent 商务的验证层：当 Agent 通过 x402 向另一项服务付款时，attest_delivery 会核验交付内容是否与宣传内容一致，并签发经过签名、可离线验证的交付收据，将付款 → 交付 → 有依据的内容绑定在一起。这是中立的责任追踪记录，正是 a2a-payments 文献所称的缺失层（docs/delivery-attestation.md）。

架构

两个部分，各自使用最适合的语言：

server/   TypeScript MCP server   — thin protocol layer (stdio). Holds no logic.
engine/   Python FastAPI service  — retrieval + stance classification + the verdict brain.

MCP 服务由你的客户端通过 stdio 启动，并通过 HTTP 与引擎通信（GROUNDCHECK_ENGINE_URL，默认值为 http://127.0.0.1:8723）。引擎是判定结果生成方式的唯一事实来源，并通过规范的 Python free-llm-router（免费层级提供商）对来源立场进行分类。

verify_claim ─▶ TS MCP server ─HTTP▶ Python engine
                                        ├─ retrieval  (Wikipedia, keyless; or your own search)
                                        ├─ stance     (free-llm-router → supports/refutes/neutral)
                                        └─ verdict    (refuses on conflict, saturating confidence)

工具

工具	适用场景	返回内容
verify_claim(claim, maxSources?)	即将断言一个自己不确定的事实	{ verdict, confidence, rationale, sources }
check_citations(text, maxClaims?)	发布 AI 生成的草稿之前	逐条主张的判定报告
attribution_badge()	想要标记内容已核查	Markdown 徽章
resolve_instrument(query, idType?, maxResults?)	文本提及某项证券，而你需要确定它具体指什么	规范 FIGI 记录 + 来源信息（Bloomberg 开放符号体系）
extract_claims(text, maxClaims?)	想先查看文档包含哪些主张，再付费为其提供依据	原子级、可核查的主张 + 与输入哈希绑定的签名回执
attest_delivery(service, response_text, …)	你通过 x402 向另一项服务付费，并将依据其输出采取行动（或进行核算）	将付款 → 交付 → 有依据的内容绑定在一起的签名交付回执（文档）

verdict 的值为 supported · refuted · unverified。每个判定还带有一个 sufficiency 标签（sufficient · insufficient · no_sources · no_stance · conflict），让 Agent 能区分“什么也没找到”“有来源但无法证实” 和“来源之间存在分歧”——这三种导致弃答的情况含义各不相同，不再被归为一类 （SURE-RAG）。

复合主张会被拆解。 例如 “Marie Curie 获得过两次诺贝尔奖，并且出生于巴黎” 这样的主张会被拆分成若干原子 （Fact in Fragments），分别依据各自的证据进行核查， 再按最弱环节重新组合：其中一部分为假，就会推翻整个主张；其中一部分未经证实， 就无法判定为 supported。真实的部分无法再让虚假的部分蒙混过关。原子拆分结果会在 atoms 中返回。（拆解基于规则，且精度高——仅在明确的并列边界处拆分，否则保留完整主张； 可通过 GROUNDCHECK_DECOMPOSE=0 禁用。）

远程 MCP（无需安装）： 将 https://groundcheck.seiche.info/mcp 添加为远程 MCP 服务 （Claude/ChatGPT/Cursor 连接器，或 Smithery/Glama 之类的网关）。使用可流式传输的 HTTP JSON-RPC；verify_claim 免费，付费工具会通过 HTTP 402 返回 x402 报价。

快速开始

如果 Python 引擎尚未运行，MCP 服务会自动启动 Python 引擎；因此只需注册一次， 无需另行启动和维护进程。

make install                      # deps for both halves (pip + npm)
npm --prefix server run build     # compile the server
export GROQ_API_KEY="gsk_..."     # one free key for stance classification (Groq: ~2 min, 14,400/day)

# register with your MCP client — the engine spawns on first use and stops with the server
claude mcp add groundcheck -- node "$PWD/server/dist/server.js"

已经自行运行引擎（make engine 或 docker compose up -d）？服务会检测并复用它， 也不会触碰并非由它启动的引擎。设置 GROUNDCHECK_NO_SPAWN=1 可阻止它启动任何引擎。

发布到 npm 后，注册命令将变为 claude mcp add groundcheck -- npx -y groundcheck-mcp。 自动启动需要本地 engine/ 和 Python 依赖；如果仅通过 npx 安装，请运行 docker compose up -d 启动引擎，服务会通过 GROUNDCHECK_ENGINE_URL 连接它。

即使没有提供商密钥，引擎仍会运行——检索功能可用，但所有判定都会是 unverified。它会如实降级：后端已禁用、缺少密钥或来源相互冲突，最终都会得到 unverified。未配置的 Groundcheck 无法返回 supported。

注意：OpenRouter 的 :free 模型受配额限制（HTTP 429），不适合作为唯一提供商。 快速分类层建议使用 Groq 或 Cerebras。

为什么要使用基于事实依据的判定，而不是 LLM 判定

让 LLM 判断某个主张是否属实，并不可靠，而且这种不可靠性很容易被忽视。 在 TraderBench（Yuan 等人，2026 年）中，三个前沿 LLM 判定器对同一批候选回答重新评分后，知识检索部分的分数波动约 29 分；而表现基准部分的评分以可验证的计算为依据，波动仅为 0.3 分。 由此可见：用外部证据对判断的约束越多，结果的波动就越小。

Groundcheck 正是基于这一原则构建的。它绝不会要求模型凭参数记忆回答“这是真的吗？”。相反，它会：

• 先检索来源，然后只询问范围明确、以证据为依据的问题——这段被引用的文字是否支持、反驳或对该主张持中立态度（立场分类）；
• 遇到冲突时拒绝判定，并限制置信度上限，让分歧导向 unverified，而不是自信地猜测；
• 返回引用来源，让判定结果可以核查，而不是只能听信模型的说法。

这就是 LLM 判定器与事实依据检查的区别：判定器的自由裁量权就是其产出；而在这里，它会被检索到的证据刻意约束。

校准后的判定：“错误率 ≤ α”保证

没有承诺作为依据的置信度数字，不过是带小数的直觉。部署校准文件后，Groundcheck 会在方向性判定结果中附加一个 guarantee 对象，该对象通过分割保形预测构建（改编自 Multi-LLM Adaptive Conformal Inference，arXiv:2602.01285）：

• 立场分类以评审组的形式运行：最多由 GROUNDCHECK_ENSEMBLE_MAX 个免费提供方独立判断该主张（不同模型系列在哪些主张上出错方面各不相同，因此集成效果胜过其中任意一个模型）。各来源的立场通过多数表决得出；每位评审还会根据片段内容给出该主张为真的概率，并将这些概率合并为加权的 ensemble_score。
• scripts/calibrate.py 会对带标签的主张集运行真实流水线，并将每个主张组（instrument / general，以及 global 回退组）的有限样本阈值存储在 calibration/calibration.json 中。
• 只有当分数超过阈值时，判定结果才会被认证（guarantee.certified: true）。对于与校准集可交换的主张，数学保证：错误主张被认证为 supported 的概率 ≤ α（默认值为 0.1）；refuted 的情况也同样如此。无需分布假设，且有限样本下精确成立。

与其他部分一样，系统会如实处理能力退化：没有文件时，绝不会声称存在保证；对于给定的 α，校准数据不足时，会拒绝提供阈值，而不是将其外推。该保证的有效性取决于可交换性假设——在新领域使用前，应先使用该领域的主张重新校准。

配置（引擎）

变量	默认值	用途
GROUNDCHECK_SEARCH_BACKEND	(未设置)	设为 stub 可禁用实际检索
GROUNDCHECK_SEARCH_URL	Wikipedia	自定义 JSON 搜索端点（{results:[{title,url,snippet,stance?}]}）
GROUNDCHECK_SEARCH_KEY	—	自定义端点的 bearer token
GROUNDCHECK_ROUTER_PATH	同级目录中的检出	free-llm-router Python 包的路径
GROUNDCHECK_ENGINE_HOST / _PORT	127.0.0.1 / 8723	引擎绑定地址
GROQ_API_KEY （或任意路由器提供方密钥）	—	启用立场分类
GROUNDCHECK_ENSEMBLE	1	多提供方立场评审组（0 = 单路由器）
GROUNDCHECK_ENSEMBLE_MAX	3	每个主张的评审人数上限
GROUNDCHECK_CALIBRATION	calibration/calibration.json	保形预测文件路径

机器可支付的托管服务（x402）

托管引擎可通过 x402 协议 按次向 AI Agent 收取 USDC — HTTP 402 + 已签名的转账授权，无需账号或 API 密钥。仅当设置 GROUNDCHECK_X402_PAY_TO 后才会启用；/verify 永远免费，可用于在付款前评估输出；付费功能按粒度提供验证循环：提取 $0.005 → grounding $0.02 → 交付证明包 $0.05（另有 /resolve，价格为 $0.005）。协议的两个代际版本（v1 和 v2）均受支持，Agent 可通过 GET /.well-known/x402 查看报价。完整的运营指南：docs/x402.md。

服务端：

变量	默认值	用途
GROUNDCHECK_ENGINE_URL	http://127.0.0.1:8723	服务端查找引擎的位置
GROUNDCHECK_NO_SPAWN	(未设置)	设置后禁用引擎自动启动
GROUNDCHECK_ENGINE_DIR	repo engine/	自动启动时引擎所在位置
GROUNDCHECK_PYTHON	python3	用于启动引擎的解释器
GROUNDCHECK_REPO_URL	repo URL	用于署名页脚/徽章的 URL

开发

make test        # engine pytest (verdict rule + x402 gating) + server typecheck
make engine      # run the engine
make server      # run the MCP server in dev (tsx)
make build       # compile the server to server/dist

核心逻辑位于 engine/groundcheck_engine/verdict.py：多少来源一致性才算“有依据”、如何处理冲突，以及置信度如何趋于饱和。

MIT。