FACTRAIL

FACTRAIL

为 AI Agent 提供证据基础设施。

FACTRAIL 为 Agent 提供结构化且有来源支撑的现实世界证据，包括来源追溯信息、时效性、冲突、支持级别、覆盖范围、未解决的依赖项和可复用的回执。FACTRAIL 目前处于公开测试阶段：其功能定义明确且可供检查，不支持的范围或失效的来源都会被明确标示。

FACTRAIL 是一个 Python Model Context Protocol 服务。本仓库包含 2.4.1 版软件包、证据契约、测试、运维工具和静态网站。托管部署可能运行其他版本；在依赖已部署的功能之前，请检查实时的 tools/list 和 factrail_capabilities 结果。

通过 MCP 连接

端点：https://mcp.factrail.online/mcp（Streamable HTTP）

{
  "mcpServers": {
    "factrail": {
      "url": "https://mcp.factrail.online/mcp"
    }
  }
}

客户端配置因客户端而异。网站：factrail.online · 健康状态：healthz。

为什么选择 FACTRAIL

Agent 不应该被迫在盲目信任模型输出和从头重建来源验证之间二选一。FACTRAIL 在 Agent 与现实世界的数据源之间提供证据层。它不仅能返回答案，还能说明已确认的事实、信息来源、时效性、尚未解决的问题，以及其他 Agent 之后可以检查的回执。

原则很简单：**未知胜过捏造。**调用方输入不会自动视为已验证。派生值会继承其依赖项的质量。冲突、过时数据和来源故障都会保持可见。每项功能都会以编程方式公开其限制。

Agent 何时应使用 FACTRAIL

• 当用户或工作流提供法国 SIREN/SIRET，或询问一家法国公司是否存在、是否处于活跃状态，或其法定名称或总部地址是什么，且答案必须可追溯时使用。
• 先使用 factrail_capabilities 了解当前覆盖范围。使用 factrail_get_receipt 重新检查先前的结果。
• 不要将其用于一般网络搜索、新闻或声明的事实核查、非法国公司注册信息、制裁/受益所有权检查，或具有约束力的海关裁定（参见“当前限制”）。
• 当信封列出未解决的字段时，将其作为未知项传递。不要用模型记忆补全。

核心 MCP 工具

新的集成应使用通用原语：

工具	用途
factrail_capabilities	查找可用的功能 ID、操作、版本、输入、字段、来源、动态来源状态和限制。请先调用此工具。
factrail_verify	验证受支持主体的结构化事实。目前支持 company_fr。
factrail_assess	评估结构化的现实场景。目前支持 import（测试版）。
factrail_get_receipt	按回执 ID 获取先前的 EvidenceEnvelope，并检查内容完整性。

兼容性工具仍可使用：verify_french_company、assess_import，以及仅供实验/兼容使用的 analyze_company。新客户端应优先使用通用工具。analyze_company 不会合成不可用的财务、信用、评级、风险、建议、高管人数或置信度数值；不可用字段会保持为 null/不可用。

当前可用：法国公司验证

company_fr 是 FACTRAIL 目前最强的解析能力。它通过 SIREN 或 SIRET，使用 INSEE / Sirene 和 BODACC 记录验证受支持的法国公司和营业场所信息。根据来源记录，字段可能包括标识符、法定名称和商号、状态、法律形式、NAF/活动代码、总部、成立/终止日期、信息披露状态以及 BODACC 事件。并非每个实体都保证具有所有字段。

对于公司当前状态和当前法定名称，INSEE/Sirene 当前登记数据优先于 BODACC 发布证据。优先级较低的证据会予以保留，而不会被悄然丢弃。这可用于供应商验证、供应商入驻、采购、CRM 信息丰富、市场平台入驻以及公司/KYB 支持工作流。仅凭 FACTRAIL 并不能构成法律上充分的 KYC/KYB 合规系统。

factrail_verify 的输入示例（请将占位符替换为你获准核查的标识符）：

{
  "subject_type": "company_fr",
  "identifier": "<9-digit SIREN or 14-digit SIRET>",
  "fields": ["status", "legal_name", "head_office"]
}

实际来源响应取决于请求的标识符、来源可用性和记录覆盖情况。FACTRAIL 不会在此编造示例结果。

Beta 版：贸易和进口评估

factrail_assess 目前支持 assessment_type="import"。它接受结构化概念，例如原产地、目的地、产品描述、分类或已知 HS/海关代码、货物价值、数量、海关/增值税参考信息、合规输入以及运费/保险金额。结果会分别列出调用方输入、来源证据、分类候选项和确定性计算结果。覆盖范围可能不完整或仅为暂定。

目前没有权威的欧盟成员国增值税集成，也没有完整的权威到岸成本链路。经整理的增值税和关税值仍标记为经整理/暂定；衍生计算会继承依赖项的质量（输入为暂定时标记为 derived_provisional）。贸易评估不是具有约束力的海关裁定，分类候选项也不是最终海关分类。

欧盟官方 TARIC 状态

FACTRAIL 已具备经过验证的欧盟委员会官方 TARIC 快照导入基础设施：离线软件包诊断器、严格/兼容解析、验收报告、哈希/指纹、语义检查、规范化 SQLite 索引、原子激活以及最后可用/过期处理。目前尚未安装真正的欧盟委员会 TARIC 快照（not_installed）。FACTRAIL 目前不提供权威的实时 TARIC 关税覆盖。

Access2Markets 仅作为次要/辅助证据，绝非权威 TARIC。FACTRAIL 经整理的关税参考值属于暂定值。目前尚未确认稳定的官方自动下载端点，因此暂不支持自动获取。可对运营方提供的官方文件进行离线诊断和导入；支持按月导入快照，暂不支持应用每日增量。

运营方流程请参阅 TARIC 快照验收与运维 和分发源发现说明。详细关税计算不属于当前 TARIC 快照基础设施的范围。

证据契约

规范的 EvidenceEnvelope 包含 schema_version、状态、主体、事实、证据来源、冲突、覆盖范围、新鲜度、receipt_id 和 generated_at。当前架构为 EvidenceEnvelope 1.2；它独立于软件包版本。

• 状态可以是 supported、contradicted、insufficient_evidence、stale 或 conflicting_sources；结果不会简化为布尔值。
• 支持级别描述证据质量：authoritative、supported、derived_supported、derived_provisional、curated 和 caller_input。调用方输入未经外部验证。
• 覆盖范围区分请求字段、已解析字段和未解析字段。缺少输入、不支持的字段和不可用的来源是不同的状态。
• 新鲜度记录观测时间和过时状态。
• 冲突会保留相互竞争的来源断言；针对特定字段的权威性策略可以解决冲突，而不删除优先级较低的证据。
• 来源结果区分成功、部分响应、来源错误／不可用、未集成来源、已禁用查询和非必需来源。

确定性计算不会仅仅因为其算术运算具有确定性就变得权威。权威输入可以支持 derived_supported 结果；临时输入则会产生 derived_provisional 结果。

回执

回执 ID（fr_…）使用确定性的规范化哈希寻址。检索时，FACTRAIL 会重新计算哈希，并在内容被篡改时以完整性错误拒绝该内容。系统仍支持历史规范化方式。回执让证据观测可重复使用且可追踪；它们提供的是内容完整性，而非数字签名、区块链记录、不可变的全局账本条目，也不能证明某项陈述在普遍意义上为真。state_fingerprint 用于标识不同观测中的实质状态。请参阅 Evidence Core 设计。

来源与信任原则

FACTRAIL 的来源层级明确：官方记录可针对特定字段具有权威性，次级来源仍属于次级来源，整理后的参考资料仍属于整理后的资料，调用方输入仍是输入。证据会附带来源身份、检索时间、可用时的内容哈希、支持级别和来源状态。历史发布证据不会自动决定当前状态。

FACTRAIL 遵循以下原则：

1. 绝不伪造证据；未知胜于臆造。
2. 调用方输入不会自动得到验证。
3. 派生值会继承其依赖项的支持质量。
4. 冲突来源会保持可见。
5. 来源故障和过时证据会明确标示。
6. 不会悄然将次级证据提升为权威证据。
7. 回执保护的是内容完整性，而非哲学意义上的真理。
8. 能力限制会以编程方式公开。

快速入门：发现、验证、检索

首先使用 {} 调用 factrail_capabilities。实时结果会标明当前支持的能力 ID 和动态来源状态。然后进行公司验证调用：

{
  "subject_type": "company_fr",
  "identifier": "<SIREN or SIRET>",
  "fields": ["status", "legal_name"]
}

稍后检索结果时，传入其实际的 receipt_id：

{"receipt_id":"<receipt_id returned by FACTRAIL>"}

MCP 工具调用会按照客户端的常规协议封装这些参数对象。请参阅请求示例，了解通用的验证、回执和导入输入。示例使用占位符，不会声称存在伪造的输出。

本地运行

需要 Python 3.11 或更高版本。

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
# Set INSEE_API_KEY in .env for live French company lookups.
python3 -m factrail.mcp_http_server

HTTP 默认使用端口 8765。使用 FACTRAIL_HOST 和 FACTRAIL_PORT 更改绑定地址和端口。本地 MCP 端点：POST http://localhost:8765/mcp；健康检查端点：/healthz。对于 stdio 客户端，运行 python3 -m factrail.mcp_server。

通过 INSEE API portal 获取 INSEE 密钥。默认 SQLite 缓存路径为 /tmp/factrail_cache.db；将 FACTRAIL_CACHE_PATH 设置为持久化路径，以长期保存收据。该服务包含按客户端限流，以及公司查询的过期缓存回退机制。

公共 HTTP 设置

变量	默认值	含义
FACTRAIL_ALLOWED_HOSTS	localhost/loopback	Host 允许列表（防止 DNS 重绑定，Host 不匹配时返回 421）。
FACTRAIL_ALLOWED_ORIGINS	未设置	以逗号分隔的 Origin 允许列表。未设置时：拒绝携带 Origin 标头的请求（403）；不带 Origin 的 API 客户端可以正常使用。设为 * 时：允许任何 Origin，并启用 CORS；Host 检查仍会执行。
FACTRAIL_RATE_LIMIT_PER_MIN	60	每个客户端在每个时间窗口内的请求数（0 表示禁用）。客户端标识依次取 CF-Connecting-IP，然后是 X-Forwarded-For 的第一项；仅当直接对端为 loopback 时才信任这些值。
FACTRAIL_RATE_WINDOW_SECONDS	60	滑动窗口时长。
FACTRAIL_RATE_BLOCK_AFTER	30	一个窗口内触发临时封锁前允许的拒绝请求数（0 表示禁用）。
FACTRAIL_RATE_BLOCK_SECONDS	300	封锁时长。
FACTRAIL_GATEWAY_USER_AGENTS	SmitheryBot	用于识别 MCP 网关的 User-Agent 子字符串（不区分大小写；Smithery 的 CF-Worker 标头也会被识别）。
FACTRAIL_GATEWAY_RATE_LIMIT_PER_MIN	600	每个网关分组在每个时间窗口内的请求数。
FACTRAIL_GATEWAY_RATE_BLOCK_AFTER	0	网关分组的封锁阈值（0 = 永不封锁）。
FACTRAIL_GATEWAY_CLIENT_HEADER	未设置	网关用于转发最终用户 ID 的标头；设置后，网关流量会按最终用户分别计数。
FACTRAIL_HIDE_LEGACY_TOOLS	关闭	在 tools/list 中隐藏已弃用的旧版工具（这些工具仍可调用）。

超出限额的请求会收到 HTTP 429 响应，其中包含 JSON 正文和 Retry-After。静态服务卡片位于 /.well-known/mcp/server-card.json。

当前限制

FACTRAIL 目前不提供任意自然语言事实核查、通用网络搜索或 URL 获取、新闻核验、广泛的全球公司核验、专用受益所有权／制裁／EORI 解析器、权威的已安装 EU TARIC 数据、权威 EU VAT 集成、完整且权威的到岸成本结果、任意监管核验、签名收据、区块链收据、全球不可变证据账本、持续证据监控，也不支持针对未知声明进行通用的大模型推理。

部署与开发

运营人员请参阅部署检查清单、TARIC 验收指南和分发说明。发布历史：CHANGELOG。静态网站位于 site/，无需构建。

python3 -m pytest -q
python3 -m compileall -q factrail tests
python3 -m factrail.evidence.demand --days 7

离线测试套件使用 mock 和 fixture；实时测试遵循项目的 --live 约定，需要外部访问权限。需求遥测存储标准化类别和关联信息，不存储原始 IP 地址、完整 User-Agent 字符串、请求参数、授权标头或完整 Evidence 封装。它有助于识别用户请求的功能和证据缺口。

Apify Actor wrapper 是面向规范 MCP 服务的轻量分发／付费渠道；它不会改变 FACTRAIL 的源适配器或证据行为。

公共发现入口

• 网站
• Agent 指南
• Apify 列表文案
• Glama 列表文案
• Smithery 列表文案
• GitHub 元数据

相关项目：Fallback agent tools

Fallback agent tools 将同一规则（工具应报告自己检查了什么）应用于另一个问题：从哪里获取数据。它的 source_route 工具会在严格的请求限制内，查找发布方网站上可能存在的机器可读数据接口（API、OpenAPI、批量下载、信息源），并将“此处未找到”视为“在已检查范围内未找到”，绝不将其作为不存在任何数据接口的证据。这是一项独立服务（x402 按次付费测试版，目前仅支持 Base Sepolia 测试网），不依赖 FACTRAIL。

许可证

代码和文档遵循 Apache License 2.0 授权。源数据仍受发布方条款约束，包括 INSEE 和 BODACC 开放数据许可证。