Academic Research Kernel

academic-research-kernel

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Deutsch · Français · Español · Português · Русский · Bahasa Indonesia · Italiano · हिन्दी · العربية · বাংলা · اردو · Tiếng Việt · Türkçe · فارسی · Kiswahili · Polski

这个仓库是一套实用工具包，可借助 AI Agent 验证学术来源、核查统计数据并追踪研究证据。研究人员使用语言模型阅读论文或撰写文献综述时，模型经常会编造引文、误读表格，或无法追踪支持某项具体论断的页面。为避免这些问题，academic-research-kernel 将 14 个学术工作流和 12 个确定性验证工具打包，通过标准的模型上下文协议（MCP）服务和命令行界面提供。你可以用它核对论文身份和撤稿情况、重新计算已报告的统计数据、将论文整理成附有来源链接的报告、管理系统综述筛选日志，并记录每项论断及其支持证据和负面结果。它可直接与 Claude Code、Cursor、Codex、Gemini CLI 和 Hermes Agent 配合使用。验证范围和外部服务限制详见项目审计。

作者：Junfu Shi（SJF，xngg1021），Hermes Agent。许可证：Source Lineage License 1.0。

快速开始

如果你希望 AI Agent 阅读论文、核查数据并生成报告，请安装支持 PDF 的软件包，并将 paper-research 工作流导出到 Agent 的技能目录；如果你希望将 12 个验证工具作为后台 MCP 服务连接到 MCP 客户端，请安装 uv 并启动 stdio 服务：

# 1. Read PDF papers and generate reports with your local AI agent
uv tool install "academic-research-kernel[research]==2.2.0"
academic-research-kernel research skill --output ./paper-research

# 2. Or start the background stdio MCP server for an MCP client
uvx [email protected] mcp

请注意，在终端中运行 mcp 会静默等待 MCP 客户端发送 JSON-RPC 请求，而不是打开交互式菜单。2.2.0 版本发布页列出了软件包哈希值和发布状态。如果你下载了发布版 wheel，也可以使用 uvx --from ./academic_research_kernel-2.2.0-py3-none-any.whl academic-research-kernel mcp 在本地运行。软件包支持 Python 3.10–3.14，使用 uvx --python 3.12 可指定 Python 版本。基础安装包含全部 12 个验证工具，并会在调用统计数据重新计算功能时按需加载统计库。

验证安装

uvx [email protected] doctor
uvx [email protected] --version

doctor 命令可离线运行，并会检查运行时依赖、JSON 架构和全部 12 个工具定义。未配置可选的外部 API 不会导致检查失败。如果需要机器可读输出，请传入 doctor --json。

安装软件包

uv tool install academic-research-kernel==2.2.0
academic-research-kernel doctor
academic-research-kernel mcp

你也可以使用 pipx install academic-research-kernel==2.2.0 安装软件包，或在虚拟环境中运行 python -m pip install academic-research-kernel==2.2.0。使用 [full] 安装会添加扩展科学计算示例所用的库。使用 [research] 安装会添加 pypdf==6.19.0 和 fonttools==4.65.0，以确保在 Python 3.10 及更高版本的全新环境中，PDF 字体解码行为一致。使用 [qa] 安装会在这些解析库的基础上添加仓库测试工具。HTML、XML、DOCX 和 XLSX 文件的读取使用 Python 标准库；GPU 后端和付费学术数据库则为可选项。

Hermes

确保 uv 位于 Hermes 进程的 PATH 中，然后安装并启用插件：

hermes plugins install xngg1021/academic-research-kernel --no-enable
hermes plugins enable academic-skills

该插件保留 academic-skills 这一名称以确保兼容性，并包含全部 14 项技能，包括 paper-research。其 mcp.json 配置使用 Python 3.12 和仓库的 uv.lock 文件运行 uv run --frozen --no-dev --no-editable，并将隔离环境存放在 ${PLUGIN_DATA}/runtime 下。首次运行时，它会安装自身的依赖项，不会修改 Hermes 或系统 Python 包。如果你更希望在不使用插件运行时的情况下单独安装技能，请参阅集成与便携式用法。

从源代码运行

git clone https://github.com/xngg1021/academic-research-kernel.git
cd academic-research-kernel
uv sync --frozen --no-dev --no-editable
uv run --frozen --no-dev --no-editable academic-research-kernel doctor
uv run --frozen --no-dev --no-editable python scripts/mcp_server.py

有关依赖组、可复现的构建步骤和发布验证检查点，请参阅分发与发布。

许可证

包含此声明的快照，对所涵盖的材料及 LICENSE-APPLICATION.md 中所述权利适用 Source Lineage License 1.0。初始 SLL 提交以及随后记录许可边界的提交均记录在 LICENSE-HISTORY.md 和 SOURCE-LINEAGE.md 中。保留此声明的后续快照具有相同的许可范围。

截至提交 439ce4a29d6d2d9137308d7f9f045863e9f0c5b3 的历史快照均以 MIT License 分发。使用这些早期快照的用户保留其 MIT 许可权限，无需迁移到 SLL。此前的 MIT 许可证文本 和 tests/upstream/LICENSE 均按原样保留。

SLL 允许使用、研究、修改、商业使用、再分发和添加专有扩展，前提是保留规定的许可证和源代码沿袭声明。它并非著佐权许可证，也不要求公开你的源代码。在不分发软件副本的情况下运行网络服务，不会触发源代码沿袭声明要求。该许可证不包含明确的专利授权，第三方文件仍受其原始许可证约束。英文版 LICENSE 文本具有权威效力；LicenseRef-Source-Lineage-1.0 是本地标识符，并非 SPDX 代码或 OSI 批准的代码。贡献规则 与下游许可权利彼此独立。

技能

技能	版本	功能
skills/academic-source-verification	1.2.0	跨数据库检查论文元数据和引用次数，查看勘误或撤稿信息，查找开放获取的全文，并验证本地 PDF 是否与引用的作品相符
skills/literature-analysis	1.3.0	十二种日常工作流：查找相似论文、检查文本重叠、搜索反面证据、总结作者经历、模拟同行评审、检查推理缺陷、建立对照表、推荐目标期刊、导出 BibTeX、双语阅读、发现研究空白，以及规划复现
skills/academic-writing	1.1.1	修改学术文稿，格式化引用（ISO 690、APA、MLA、Chicago、IEEE、AMA 及地区标准），检查期刊作者指南，准备投稿文件，并验证盲审匿名化情况
skills/math-computation	1.2.1	将符号、数值和统计计算任务交由经过验证的 Python 工具处理，并配有四份领域参考指南
skills/quantitative-paper-audit	1.1.0	根据汇总数据重新计算报告的效应量、p 值、置信区间、优势比或风险比以及统计功效，以发现报告错误
skills/research-reproducibility	1.0.1	根据包含 14 个步骤的清单，审查论文的代码、数据、依赖项和报告指标是否可以复现
skills/systematic-review-meta-analysis	1.0.1	记录 PRISMA 检索和筛选日志，转换效应量，检验异质性，汇总固定效应或随机效应，并进行敏感性和发表偏倚检查
skills/literature-watch	1.1.0	每周监控 OpenAlex 和 Crossref，按主题、作者或引用的 DOI 查找新论文，并去重以确保只报告新作品
skills/retraction-watch	1.1.0	每周将 DOI 监控列表与 OpenAlex 撤稿标记和 Crossref 更新记录进行复核，仅报告状态发生变化的论文
skills/research-object-identity	1.1.0	将 DOI、arXiv ID 和文件哈希规范化为规范记录，验证资源状态，并追踪衍生文件如何由原始来源生成
skills/claim-evidence-graph	1.0.0	将每项科学主张关联到支持或反驳该主张的确切来源段落、表格或计算记录
skills/decision-ledger	1.0.0	维护仅追加的研究决策日志，记录方法选择、失败的尝试、放弃某个方向的原因，以及后续对结果的修订
skills/paper-research	1.0.0	从 DOI、URL 或本地文件夹阅读论文及其补充材料，验证提取的数字，保存结构化研究状态，并生成带来源链接的中文报告或双论文比较
skills/cross-review-five	2.0.0	协调多个语言模型或子 Agent 进行独立盲审，合并重叠意见，安排交叉质询，并按 P0 至 P3 对问题分级，同时保留未解决的异议

在这 14 项技能中，有 22 份 Markdown 参考指南会在任务需要时按需加载。

学术标准与多配置文件基线

引文格式、报告清单和元数据规则取决于目标期刊、资助方、学科和地区。本仓库采用 ISO 690:2021（文献参考文献）、ISO 5127:2017（文献工作术语）和 W3C PROV（来源记录）作为国际基线，同时遵循区域标准，例如中国大陆的 GB/T 7714-2025、西班牙的 UNE-ISO 690:2024 和德国的 DIN ISO 690:2021，以及 APA 第 7 版、IEEE、ACM、Vancouver、Chicago、PRISMA 2020 和 ICMJE 等学科指南。目标期刊自己的说明始终优先于默认设置。请参阅学术标准架构和自然术语指南。

保存研究状态时，内核会检查 DOI 和外部标识符是否匹配，防止同一项检查出现相互矛盾的统计判定，并在共享审核清单中跟踪未解决的问题。缓存验证会直接根据已保存的源包和哈希绑定重建状态，而不是依赖汇总列表，因此即使同时删除记录及其缓存条目，在重放期间仍会被发现。详情记录在四项阻断问题的收尾说明中。

集成与便携式用法

1. 通用 Agent 插件 v1 与 Model Context Protocol（MCP）

本仓库遵循与供应商无关的 Agent Plugins v1 格式（plugin.json），并通过标准的 stdio MCP 服务（mcp.json / scripts/mcp_server.py）提供验证和统计工具。你可以将其直接加载到 Claude Code、Cursor、Codex、Gemini CLI 或任何其他兼容 MCP 的客户端中。虽然仓库名为 academic-research-kernel，但插件名称 academic-skills 和现有 MCP 别名保持不变，以确保现有配置继续有效：

# Add as stdio MCP server in your agent harness
uvx academic-research-kernel mcp

2. 原生 Hermes 安装

在现有 Hermes 安装中，你也可以直接注册 skill tap：

hermes skills tap add xngg1021/academic-research-kernel
hermes skills search academic-source-verification
hermes skills install xngg1021/academic-research-kernel/skills/academic-source-verification

要安装其他技能，请替换命令末尾的目录名称。由于 tap add 会读取默认分支，全新安装会获取上文列出的 14 项技能。如果你想测试尚未合并的工作分支，请在本地检出该分支，并从本地文件夹安装，而不要期待 tap 拉取某个 pull request 分支。

根据 Hermes 上游提交 245e48008fa814b3251f50755eb656bd9fb86cb1 检查过的相关技能包括 arxiv、grounded-citations、docx、pdf 和 manim-video。可选技能（如 huggingface-hub 和 llama-cpp）可以单独安装。ocr-and-documents 和 pc-hardware-benchmark 均非必需。

数据源访问

• OpenAlex 允许匿名进行首页查询，但每日预算较少。OpenAlex 当前的速率限制为：无密钥时每秒 10 个请求，使用免费或预付费 API 密钥时每秒 30 个请求，使用年度套餐时每秒 50 个请求；匿名使用额度为每天 $0.10，免费 API 密钥额度为每天 $1。要通过 next_cursor 访问首页之后的内容，必须在 OPENALEX_API_KEY 中提供 API 密钥（匿名请求第二页游标会返回 HTTP 401，且结果会截断为首页）。
• Crossref 提供公开元数据，并设有速率限制。检查更正和撤稿时，必须核实 DOI 和更新方向；结果为空并不能证明论文没有问题。
• Unpaywall 要求在 UNPAYWALL_EMAIL 中提供真实联系邮箱。如果 Unpaywall 未返回链接，其他地方仍可能存在开放获取版本。
• arXiv、Europe PMC、PubMed E-utilities 和 DOAJ 可作为其他来源，各自设有速率限制。Semantic Scholar 将共享的匿名速率限制与专用 API 密钥配额区分开来；拥有 API 访问权限并不保证每篇论文都能获取引文上下文摘录。
• Scite、Dimensions、Scopus、Web of Science 和商业 AI 检测器是可选的第三方服务。调用前，请检查你自己的账户权限和配额。

参见 OpenAlex 身份验证、预算/查询成本和 Crossref 更新筛选器。

研究状态存储与验证边界

摄取模块使用 ResearchArtifactEnvelope v1 和 ArtifactIngestionReceipt v1，将 15 个适配器（14 个技能各一个，另有一个纯文本回退适配器）与 12 个无状态 stdio MCP 工具配对。系统保存研究对象、主张–证据链接、Research Decision Log 条目、待审查项目或验证记录时，会将其规范 SHA-256 哈希记录在摄取回执中。重放缓存时会直接检查这些哈希。空决策日志是有效的，任何在执行中途失败的批量写入都会干净地回滚，不会留下部分文件。

将记录标记为 fully_verified，需要访问底层源字节，以便独立复现检查结果。可信 Python 调用方通过 LineageVerificationContext 提供这些内容，而 MCP 调用方则直接传递有大小限制的文件字节，不暴露主机文件系统路径。默认文件大小限制为 10 MiB，可信主机可根据需要提高该限制。没有源字节时，fully_verified 声明无法通过验证。非结构化笔记保持不变，审阅者之间的分歧会继续显示，研究状态的提交、研究路线的丢弃或重新开启，以及最终的学术判断仍由人类研究人员负责。

有关数据契约，请参见架构指南；有关打包详情，请参见发布指南。全部 21 份根目录及区域 README 均已与 2.2.0 基线同步，清单会跟踪所有区域设置的加密同步哈希。发布验证和审查记录已归档在收尾账本中。

验证与测试

请在专用的 Python 虚拟环境中运行测试套件，以避免可选科学库与主机环境发生冲突：

python -m pip install -r requirements-qa.txt
python -m pip install 'torch>=2.5,<3' --index-url https://download.pytorch.org/whl/cpu
python scripts/qa.py
python -m pytest -q -rs tests
python scripts/i18n_sync.py --check
python scripts/verify_external_apis.py --output external-status.json --summary external-summary.md
git diff --check

scripts/qa.py 会检查技能的 frontmatter、文件链接、意外的本地路径或机密字符串、Python 语法以及可执行代码示例。每个 smoke-test: true 代码块都会在干净的子进程中运行，并将绘图保存到 PLOT_DIR（默认为 ~/plots，测试期间则使用临时文件夹）。未标注的 Python 代码块会被拒绝，fragment: 代码块只进行语法检查，而 external-test: 代码块只有在调用 scripts/verify_external_apis.py 时才会运行。外部检查在所有已配置的检查均通过时以 0 退出，在代码或数据错误时以 1 退出，在网络或配额限制导致无法访问时以 2 退出；未配置的可选服务会标记为 SKIP。

我们的测试套件会对每项技能复用上游 Hermes 技能编写规则，同时依据固定版本的目录验证本仓库中的全部 14 项技能。CI 只在安装软件包时访问网络；标准的拉取请求检查绝不会调用外部学术 API。

GitHub Actions 会运行正交测试矩阵，覆盖 Linux x86_64（Python 3.10、3.12 和 3.14）、Linux ARM64（ubuntu-24.04-arm）、Windows x86_64（windows-latest，使用 Python 3.10 并检查非 UTF-8 管道）、Windows ARM64（windows-11-arm）和 macOS ARM64（macos-latest，使用 Python 3.14），并进行与上游 Hermes 的实时兼容性检查。本地回归套件通过了 1319 项测试（在正确性修复报告中的 1165 项基线测试基础上扩展而来）。向 main 推送时，单独的工作流会安装 tests/upstream/provenance.json 中固定版本的 Hermes 提交，并针对本仓库测试 tap add、search、install 和 list。确切的版本和测试边界请参阅项目审计。

tools/longtail/ 包含确定性场景生成器，它会生成 4096 个由 SHA256 播种的候选项，选出 30 个测试场景，并输出覆盖率报告，涵盖 16 个能力类别（E01）、本仓库的 14 项技能（E02）和 36 个任务目标（E03）。每项技能至少会在两个不同目标中出现两次，其中包括其核心工作流目标。

scripts/scfabric/ 包含科学计算基准测试工具，包括硬件检测、数值精度检查、五种工作负载配置文件和 ComputeReceipt 日志。基准测试结果记录在 docs/scientific-compute-fabric.md 中；默认使用 CPU 进行计算，只有在基准测试回执验证通过后才会启用硬件加速器。

使用本地 Agent 阅读和比较论文

安装 [research] 扩展，并将 paper-research 技能导出到本地 Agent 工作区：

academic-research-kernel research skill --output ./agent-skills/paper-research

让 Work 或其他本地 Agent 使用导出的 SKILL.md，提供 DOI、公开 URL 或本地文件夹，并提出： “研究这篇论文及其补充材料，整理方法，核对能重算的关键数字，给我一份带出处的中文报告。” 如果有两篇论文，请让 Agent 比较它们的数据集、方法、实验条件和结果，并说明哪些数字可以直接比较。Agent 将在一个工作流中读取源文件、提取候选数字、运行统计检查、保存已验证状态，并撰写带来源链接的报告。

CLI 在后台会运行三个步骤：

academic-research-kernel research prepare INPUT --project PROJECT
academic-research-kernel research finish --project PROJECT --candidate CANDIDATE.json
academic-research-kernel research compare LEFT_PROJECT RIGHT_PROJECT --analysis COMPARISON.json --output OUTPUT

prepare 会下载或读取论文及其补充材料，记录文件哈希，并按页码和章节索引文本段落。finish 会检查 Agent 提取的结构化数字，重新计算 t 检验、p 值、两组效应量和百分比，保存已验证状态，并撰写中文 Markdown 和 HTML 报告。compare 会检查两篇论文之间的结构化比较。由于 CLI 依赖你的当前 Agent 阅读 paper-research 后的说明，因此不需要单独的大模型 API 账户。已保存的源文件和提取快照可随时离线重放。

统计精度、撤稿追踪和软件包验证

academic_recompute_statistics MCP 工具会重新计算 t 检验 p 值和两组 Cohen's d 或 Hedges' g 效应量；置信区间以及比值比或风险比则可通过 Python 函数计算。如果报告的 p 值末尾的零很重要，请传入 p_value_literal（例如 "1.0e-5"）或 p_value_decimals。字符串字面量会保留末尾的零，普通数字使用其浮点值；如果精度设置冲突，则会返回明确的错误。舍入检查会计入下半界，并排除上界。若论文报告的数字与重新计算的值不一致，会返回常规验证结果；只有输入无效或计算本身失败时，才会将 isError 设为 true。

撤稿检查会将当前运行的观测结果（True、False 或 unknown）与上次确认的状态分开存储。短锁会按 DOI 对更新排序，避免覆盖观察列表中的其他 DOI。如果网络错误或速率限制导致最近一次运行的结果为 unknown，系统会报告当前检查未经过验证，同时保留之前已确认的历史记录。回归测试使用带标签的本地 HTTP 夹具，而不是实时网络调用。

stdio MCP 服务会响应 ping，对 notifications/cancelled 等有效通知保持静默，并在客户端发送格式错误的输入时保持会话打开，遵循 MCP 消息约定 和 ping 规范。

要在隔离环境中构建和验证发布软件包，请运行：

python -m build
python -m twine check --strict dist/*
python scripts/package_acceptance.py --dist dist --uvx --source-checks --report package-acceptance.json

--source-checks 会将源代码归档解压到仓库外的临时目录，设置 ARK_REPO 和 ARK_SDIST，并针对解压后的文件运行单元测试、静态 QA、可执行示例和 i18n 检查。wheel 和源代码归档都会在全新的虚拟环境中测试；uvx 则会使用隔离缓存对本地 wheel 进行测试。