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 エージェントを活用して学術情報源を検証し、統計値を確認し、研究の根拠を追跡するための実践的なツールキットです。研究者が言語モデルを使って論文を読んだり、文献レビューを作成したりする際、モデルはしばしば引用を捏造し、表を読み違え、特定の主張を裏付けるページを見失います。これを防ぐため、academic-research-kernel は14の学術ワークフローと12の決定論的な検証ツールを、標準のModel Context Protocol（MCP）サーバーおよびコマンドラインインターフェースとして提供します。論文の識別情報や撤回状況の確認、報告された統計値の再計算、出典と紐付いたレポートを作成するための論文の読み込み、システマティックレビューのスクリーニング記録の管理、さらに各主張を裏付けとなる根拠や否定的な結果とともに記録することができます。Claude Code、Cursor、Codex、Gemini CLI、Hermes Agentで直接利用できます。検証の対象範囲と外部サービスの制限については、プロジェクト監査に記載されています。

作成者：Junfu Shi（SJF、xngg1021）、Hermes Agent。ライセンス：Source Lineage License 1.0。

クイックスタート

AI エージェントに論文を読ませ、数値を確認し、レポートを生成させたい場合は、PDFサポート付きでパッケージをインストールし、paper-research ワークフローをエージェントのスキルディレクトリにエクスポートしてください。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 という名前を維持しており、paper-research を含む 14 個すべてのスキルを搭載しています。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	12 の日常的なワークフローに対応します。同様の論文の検索、テキストの重複確認、反証の検索、著者の経歴の要約、模擬査読、推論の欠陥の確認、比較表の作成、投稿先ジャーナルの提案、BibTeX のエクスポート、二言語での読解、研究上のギャップの発見、再現計画の作成を行います
skills/academic-writing	1.1.1	学術的な文章の推敲、引用形式（ISO 690、APA、MLA、Chicago、IEEE、AMA、および地域標準）の調整、ジャーナルの著者向けガイドラインの確認、投稿ファイルの準備、ブラインド査読用の匿名化の検証を行います
skills/math-computation	1.2.1	記号計算、数値計算、統計計算のタスクを検証済みの Python ツールに振り分け、4 つの分野別リファレンスガイドも提供します
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	方法論上の選択、失敗した試み、方針を断念した理由、その後の結果の修正を追記専用の Research Decision Log に記録します
skills/paper-research	1.0.0	DOI、URL、またはローカルフォルダーから論文と補足資料を読み取り、抽出された数値を検証し、構造化された研究状態を保存して、出典に紐付けた中国語のレポートまたは 2 論文の比較を生成します
skills/cross-review-five	2.0.0	複数の言語モデルまたはサブエージェントによる独立したブラインドレビューを調整し、重複する指摘をまとめ、相互の課題を割り当て、未解決の異論を保持しながら問題を 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 7th、IEEE、ACM、Vancouver、Chicago、PRISMA 2020、ICMJE などの分野別ガイドも参照しています。対象とする学術誌独自の指示は、常にデフォルト設定より優先されます。学術標準のアーキテクチャと自然な用語ガイドをご覧ください。

研究状態を保存する際、カーネルは DOI と外部識別子の一致を確認し、同じチェックに矛盾する統計的判定が記録されるのを防ぎ、未解決の質問を共有レビューリストで追跡します。キャッシュの検証では、要約リストを信頼するのではなく、保存済みのソースパッケージとハッシュの対応付けから状態を直接再構築するため、レコードとそのキャッシュエントリーの両方を削除しても、再生時に検出されます。詳細は4つのブロッカーのクローズアウトに記録されています。

統合とポータブルな使用方法

1. Universal Agent Plugins 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インストールから、スキルタップを直接登録することもできます。

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がプルリクエストのブランチを取得することを期待するのではなく、そのブランチをローカルでチェックアウトして、ローカルフォルダーからインストールしてください。

上流のHermesコミット245e48008fa814b3251f50755eb656bd9fb86cb1と照合した関連スキルには、arxiv、grounded-citations、docx、pdf、manim-videoが含まれます。huggingface-hubやllama-cppなどのオプションのスキルは、別途インストールできます。ocr-and-documentsもpc-hardware-benchmarkも必須ではありません。

データソースへのアクセス

• OpenAlexでは、匿名で1ページ目のクエリを少量の日次利用枠内で実行できます。現在のOpenAlexのレート制限は、APIキーなしの場合は毎秒10リクエスト、無料またはプリペイドのAPIキーを使用する場合は毎秒30リクエスト、年間プランの場合は毎秒50リクエストです。匿名利用の上限は1日あたり$0.10、無料APIキーの上限は1日あたり$1です。1ページ目より先のnext_cursorを使用するには、OPENALEX_API_KEYにAPIキーを設定する必要があります（匿名で2ページ目以降のカーソルリクエストを行うとHTTP 401が返され、結果は1ページ目に切り詰められます）。
• 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個のスキルそれぞれに1つと、プレーンテキスト用フォールバック1つ）を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 は、スキルのフロントマター、ファイルリンク、意図しないローカルパスやシークレット文字列、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（Python 3.10 を使用する windows-latest と非 UTF-8 パイプのチェック）、Windows ARM64（windows-11-arm）、macOS ARM64（Python 3.14 を使用する macos-latest）にわたる直交テストマトリクスを実行し、上流 Hermes とのライブ互換性チェックも行います。ローカルの回帰テストスイートでは 1319 件のテストに合格します（正確性修正レポートの 1165 件のベースラインを拡張したものです）。main へのプッシュ時には、別のワークフローが tests/upstream/provenance.json に記載された固定 Hermes コミットをインストールし、このリポジトリに対して tap add、search、install、list をテストします。正確なバージョンとテスト範囲については、プロジェクト監査を参照してください。

tools/longtail/ には、決定論的なシナリオ生成ツールが含まれています。このツールは SHA256 でシードされた候補を 4096 個生成し、テストシナリオを 30 個選択して、16 の機能ファミリー（E01）、リポジトリ内の 14 スキル（E02）、36 のタスク目標（E03）にわたるカバレッジレポートを出力します。各スキルは、コアのワークフロー目標を含め、少なくとも 2 つの異なる目標にまたがる 2 回以上のシナリオに必ず登場します。

scripts/scfabric/ には、ハードウェア検出、数値精度チェック、5 種類のワークロードプロファイル、ComputeReceipt ログなど、科学計算ベンチマークツールが含まれています。ベンチマーク結果は docs/scientific-compute-fabric.md に記録されます。計算にはデフォルトで CPU が使用され、ベンチマークレシートによって検証された場合にのみハードウェアアクセラレーターが有効になります。

ローカルエージェントで論文を読み、比較する

[research] エクストラをインストールし、paper-research スキルをローカルエージェントのワークスペースにエクスポートします。

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

Work または別のローカルエージェントに、エクスポートした SKILL.md を指定し、DOI、公開 URL、またはローカルフォルダーを渡して、次のように依頼します。 「この論文と補足資料を調査し、手法を整理して、再計算できる主要な数値を検証し、出典付きの日本語レポートを作成してください。」 2 本の論文がある場合は、データセット、手法、実験条件、結果を比較し、どの数値を直接比較できるか説明するようエージェントに依頼します。エージェントはソースファイルを読み、候補となる数値を抽出し、統計的検証を実行して、検証済みの状態を保存し、出典リンク付きレポートを 1 つのワークフローで作成します。

内部では、CLI が次の 3 つのステップを実行します。

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 はエージェントが抽出した構造化数値を検証し、t 検定、p 値、2 群の効果量、パーセンテージを再計算して、検証済みの状態を保存し、日本語の Markdown および HTML レポートを作成します。compare は 2 本の論文間の構造化された比較を検証します。CLI は paper-research の後に続く文章を読み取るアクティブなエージェントに依存するため、別途モデル API アカウントを用意する必要はありません。保存したソースファイルと抽出スナップショットは、いつでもオフラインで再実行できます。

統計的精度、撤回状況の追跡、パッケージの検証

academic_recompute_statistics MCP ツールは、t 検定の p 値と 2 群の Cohen's d または Hedges' g 効果量を再計算します。信頼区間、オッズ比、リスク比は Python 関数で利用できます。報告された p 値の末尾のゼロが重要な場合は、p_value_literal（例："1.0e-5"）または p_value_decimals を指定してください。文字列リテラルでは末尾のゼロが保持され、通常の数値には浮動小数点値が使用されます。精度設定が競合すると、明示的なエラーが返されます。丸めの検証では下側の中間値境界を含み、上側の境界は含みません。論文で報告された数値が再計算値と一致しない場合は、通常の検証結果が返されます。isError が設定されるのは、入力が無効な場合、または計算自体が失敗した場合のみです。

撤回状況の確認では、現在の実行結果（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 とソースアーカイブの両方を、新しい仮想環境でテストします。また、分離されたキャッシュを使用して、ローカルの wheel に対する uvx もテストします。