frame-check

Frame Check

了解文档未呈现的内容。

Frame Check 是一款确定性的结构性框架分析工具。它会指出文档采用了哪些分析视角、忽略了哪些视角，以及如何定位读者；同时，它会将文档中的数字主张与大模型无法访问的第一手来源（SEC EDGAR、FRED、World Bank 等）进行交叉核查。它本身不会调用 LLM，因此同一份文档始终会得到相同的分析结果，且无需支付模型调用成本。

快速开始（MCP 服务）

PyPI 软件包 frame-check-mcp 是 Model Context Protocol 服务。它在本地运行，为任何兼容 MCP 的 AI 客户端（Claude Desktop、Cursor、Cline、Continue.dev 等）提供确定性的结构性框架分析工具。

pip install frame-check-mcp

然后，将 MCP 客户端指向已安装的入口点。对于 Claude Desktop，请在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "frame-check": {
      "command": "frame-check-mcp"
    }
  }
}

重启客户端。之后，在任意对话中询问：“能否对这份文档进行框架分析？”完整的安装与验证详情见 docs/MCP_SERVER.md。

验证 wheel（sigstore 证明）

每个已发布的 wheel 都附带 sigstore 构建来源证明，该证明通过 OIDC 在 GitHub Actions 发布工作流中生成。希望验证 wheel 是由此仓库的 CI 构建（且从运行器到 PyPI 期间未被修改）的使用者，可以通过 gh CLI 完成验证：

pip download frame-check-mcp --no-deps -d /tmp/fc-verify
gh attestation verify /tmp/fc-verify/frame_check_mcp-*.whl \
  --owner Clarethium

验证通过可证明 wheel 工件的哈希值与对应标签的发布工作流运行所签署的哈希值一致，证明中还记录了工作流文件路径和 git SHA。验证并非必需；注重安全的部署和软件包镜像可能希望将其纳入安装流程。

功能

传入一份文档，Frame Check 会返回：

• 结构性框架分析：文档涵盖了五种分析视角（原因、风险、利益相关方、趋势、不确定性）中的哪些，忽略了哪些，以及各视角的密度。
• 语气与认知立场：文档如何定位读者，以及有多少比例的主张注明了来源。
• 时间取向：文档是否以历史数据、当前状态或预测为结论提供依据。
• Frame Vocabulary Standard 候选匹配项：文本中触发基于规则的信号的已命名框架模式，每项均附有识别线索和详细示例。这些匹配项是候选级别的信号，并非经过验证的标签。
• 来源网络验证：针对 SEC EDGAR、FRED、World Bank、Alpha Vantage 和 Wolfram Alpha 核查数字主张（仅限这些服务商覆盖的内容）。
• 可选的 AI 叙述，从文字层面解读框架。此内容会明确标注，以免读者将大模型解读与确定性测量结果混为一谈。

方法

结构测量是基础。工具做出的每项框架判断，都由确定性的模式匹配器计算得出；对于相同输入，始终返回相同结果。如果配置了 API 密钥，还可以通过 AI 辅助解读进行补充，但这类内容会明确标注，绝不会隐藏在结构层之下。

验证范围有限。工具只会针对确实覆盖相应声明类型的数据提供方验证数值声明，并公开自身的校准结果（各提供方的精确率、召回率和 F1），而不会在缺乏证据时断言结论。

命名模式检测是独立于结构画像的另一个 Beta 层。它会呈现候选匹配、检测不足标记、密度注意事项和置信状态，而不是给出笃定的标签，让你看清工具不确定的地方，而不是盲目相信过度自信的结论。

校准数据、诚实说明的局限，以及背后的方法论，都见于 frame.clarethium.com/corpus/methodology 上的方法论页面。

为什么要用它，而不只是用大模型

兼容 MCP 的 AI 客户端已经可以通过提示大模型来分析文档。Frame Check 的价值在于弥补大模型的不足：

• 确定性。 对于相同输入，结构层在不同运行、部署和模型版本中都会返回相同的数值。让大模型回答“这份文档使用了哪些框架”，每次得到的答案都不同，换个模型也会不同。可复现的分析需要确定性结构；观点可以在此基础上叠加。
• 每次查询零成本。 Frame Check 的 MCP 服务不会在服务端调用大模型。用户需要的话，由调用方的 Agent 解读文本。这意味着，Frame Check 检查一份 10,000 字的文档，用户无需支付费用（$0.00）；大模型调用则会收取 $0.05 至 $0.50。
• 明确指出缺失内容。 框架差异区块会将已匹配的框架与 Frame Vocabulary Standard 目录进行比较，列出文档未涉及的内容。让大模型回答“缺少了什么”，它可能会编造听起来合理的缺漏；Frame Check 则会列出未在文本中触发的目录条目，并明确说明这一点。
• 经过校准的检测。 API 响应会将命名模式层标记为 Beta（engine_status: beta），并呈现检测不足标记，而不是给出笃定的标签。你得到的是诚实的“这一点尚不确定”，而非自信的猜测。
• 来源核验。 对于有数据提供方覆盖的数值声明，工具会根据各提供方的定价档位（免费或使用用户密钥），与 SEC EDGAR / FRED / World Bank / REST Countries / Alpha Vantage / Wolfram Alpha 进行交叉核验。让大模型判断“这个数字对吗”，它无法获取一手来源；Frame Check 则可以。

确定性、以来源为依据的测量并非大模型擅长的工作。Frame Check 提供这一层，让大模型能够依托它，而不必在对话中直接承担这项工作。

示例

同一个提示词，四个前沿大模型，得出四种截然不同的框架特征。 data/worked_examples/four-llms-on-bitcoin-retirement-2026.md 使用 Claude Haiku 4.5、GPT-5、Grok 4.1 Fast Reasoning 和 Gemini 2.5 Flash 回答一个投资问题，并呈现各模型的结构特征：语气、覆盖范围、框架匹配和来源引用率。简单来说：你的 AI 只是多种框架选择之一，而不是唯一的框架。

另有五个已发布示例：对回应人生抉择提示词的大模型回复进行框架分析、分析一家 AI 公司创始人的文章、分析 FOMC 货币政策声明、对大模型总结的财报新闻稿进行来源网络核验，以及逐步分析 Claude 关于比特币退休建议的差异。完整示例集见 data/worked_examples/。

文档

查看 docs/README.md，按用途整理了阅读路径（安装与使用、理解框架分歧、阅读完整示例）。完整目录如下：

• docs/MCP_SERVER.md：MCP 服务参考（工具、资源、提示词）
• docs/COOKBOOK.md：针对常见采用者任务的五个配方（Agent 提交前进行框架检查、决策点处的分歧、基于来源的验证、双大模型比较、自定义 FVS 规则）
• docs/FRAME_DIVERGENCE_CONTRACT_v1.md：框架分歧输出格式的接口契约（c1.0）
• data/frame_library/：包含 20 项的框架词汇标准目录
• data/worked_examples/：已发布的完整示例，含多大模型比较和逐文档框架检查分析（6 项）
• 框架词汇标准背后的方法论见 frame.clarethium.com/corpus/methodology
• 框架检查简介（博客）：四个分析层级及其输出示例

运行测试

pip install -e .[test]
python3 run_tests.py

或者直接通过 pytest 运行：

python3 -m pytest -q

tests/ 下有 26 个测试文件，端到端运行约需 30 秒。包括 tests/test_mcp_adversarial.py 中的 40 个对抗性调度器测试函数（收集时参数化为 63 个测试）、针对七个 wheel-surface 模块的按模块 80% 覆盖率门槛（scripts/check_per_module_coverage.py）、配方契约测试套件（tests/test_cookbook_recipes.py），以及体裁分类器和框架分歧覆盖率测试。

许可证

代码采用 Apache-2.0 许可证；FVS 库和完整示例采用 CC-BY-4.0 许可证 （各目录的具体清单见 NOTICE）。

引用

如果 Frame Check 对你的工作有帮助，请参阅 .github/CITATION.cff 获取可引用格式。Frame Check 由 Lovro Lucic 编写。

贡献

根据 .github/CONTRIBUTING.md，需要提供 Sign-off-by-DCO。治理规则见 .github/GOVERNANCE.md（采用 BDFL 模式，并为规范晋升决策指定了具名的强制职能）。

问题反馈

https://github.com/lluvr/frame-check/issues