oma-scholar

Scholar - Research Paper Sidecar Companion

スケジューリング

目標

トークン効率の高いリサーチワークフローのために、Knows の .knows.yaml 仕様を使用して、学術論文のサイドカーを検索、取得、生成、検証、分析、レビュー、比較します。

インテントシグネチャ

• 学術文献の検索、サイドカーの生成・検証、論文の主張／証拠の要約、論文の構造的な比較、またはサイドカー形式での査読をユーザーが求めている。
• ユーザーが Knows、.knows.yaml、knows.academy、OpenAlex、主張、証拠、関係、または論文サイドカーについて言及している。

使用する場合

• Knows サイドカーを使って研究論文をトークン効率よく読む場合（主張のみなら約700トークン、PDF全文なら約10Kトークン）
• 自分の論文草稿、LaTeX、または研究ノートから .knows.yaml サイドカーを生成する場合
• 共有前にサイドカーの構造を（ルールベースで）検証する場合
• 査読をサイドカー形式で作成する場合
• 既存のサイドカーを検索または要約する場合
• 2本の論文を構造的に比較する場合（主張、手法、証拠）
• knows.academy からサイドカーを検索／取得する場合（2026年の論文のみ。現在の件数は /api/proxy/jobs/stats で確認）

使用しない場合

• 一般的なウェブ検索、または学術以外のコンテンツ -> oma-search を使用
• 論文の翻訳 -> oma-translation を使用
• PDF の解析のみ（サイドカーなし） -> oma-pdf を使用
• サイドカーを knows.academy に再投稿する場合 -> 対象外（ホスト LLM はローカルでのみ消費／生成）
• エディターシステムを含む完全な査読ワークフロー -> 対象外

想定される入力

• 論文、要旨、草稿、LaTeX、研究ノート、サイドカーファイル、DOI、OpenAlex ID、Knows レコード ID、または検索クエリ
• 希望するモード：generate、validate、review、analyze、compare、または remote fetch
• 任意の厳格度、セクションフィルター、または CI の動作

想定される出力

• .knows.yaml サイドカー、レビューサイドカー、lint レポート、検索／取得結果、自然言語による分析、または構造的な比較
• v0.9.0 / paper@1 プロファイルに準拠するサイドカー
• 生成したサイドカーを共有する前の検証ステータスと警告

依存関係

• oma scholar CLI サブコマンド
• knows.academy の公開 API、OpenAlex および Semantic Scholar のフォールバック
• resources/sidecar-spec.md、API エンドポイント、OpenAlex のセットアップ、上流キャッシュ、チェックリスト、実行プロトコル

制御フローの機能

• モード、ソースの利用可否、Knows／OpenAlex のカバレッジ、厳格／寛容な検証、取得するセクションに応じて分岐します
• YAML サイドカーを読み書きし、公開 API を呼び出す場合があります
• ソースの証拠がない場合、内容を捏造しません

構造的フロー

エントリー

1. モードとソースとなる成果物／クエリを特定します。
2. 必要に応じて Knows または OpenAlex を通じて論文の識別情報を解決します。
3. サイドカー仕様とモード固有のプロトコルを読み込みます。

シーン

1. PREPARE：モードを選択し、ソースまたはリモート識別子を収集します。
2. ACQUIRE：論文のメタデータ、サイドカーのセクション、またはローカルのソーステキストを取得します。
3. REASON：主張、証拠、関係、来歴、または比較の構造を抽出します。
4. ACT：サイドカーデータを生成、lint、レビュー、分析、比較、または取得します。
5. VERIFY：サポートされているローカルの契約、ID、関係、来歴を確認し、lint の制限事項を報告します。正規仕様への完全な準拠には、正確なスキーマバリデーターが必要です。
6. FINALIZE：注意事項を添えて、サイドカー、レポート、要約、または比較結果を返します。

遷移

• knows.academy に論文がない場合は、OpenAlex のメタデータ／要旨にフォールバックします。
• サイドカーを生成する場合は、共有前に lint を実行します。
• サードパーティのサイドカーに参照先のない項目がある場合は、適切に寛容モードを使用します。
• ソースの証拠がない場合は、推測せずにフィールドを省略します。

失敗と復旧

• リモート API がタイムアウトした場合は、再試行するか、OpenAlex にフォールバックします。
• YAML の解析に失敗した場合は、インデントとスカラー型を修正します。
• 関係の密度や孤立した文に関する警告が出た場合は、カバレッジと型に適したリンクを見直します。ソースに基づく質問／定義は保持し、件数を満たすために裏付けのない関係を追加してはいけません。

終了

• 成功：要求されたサイドカー操作が、検証ステータスとともに完了します。
• 部分的な成功：メタデータの欠落、代替ソースの使用、検証時の警告が明示されます。

論理操作

アクション

アクション	SSL プリミティブ	エビデンス
モードを選択する	SELECT	Generate/Validate/Review/Analyze/Compare/Remote
論文またはサイドカーを読み込む	READ	ソースファイルまたは YAML
リモートデータを要求する	REQUEST	Knows/OpenAlex API
主張／エビデンス／関係性を推論する	INFER	サイドカーの生成／分析
サイドカーを書き込む	WRITE	.knows.yaml 出力
サイドカーを検証する	VALIDATE	oma scholar lint
結果を報告する	NOTIFY	概要または lint レポート

ツールと手段

• oma scholar search|resolve|get|lint
• Knows 公開 API、OpenAlex の代替手段、サイドカー仕様、チェックリスト

標準コマンドパス

oma scholar search "<query>"
oma scholar resolve "<title-or-doi>"
oma scholar get "<record-id-or-doi>"
oma scholar lint "<paper.knows.yaml>"

リソースの範囲

範囲	リソースの対象
LOCAL_FS	論文の草稿、サイドカー YAML、レビュー用サイドカー
NETWORK	knows.academy および OpenAlex API
PROCESS	oma scholar CLI と lint
USER_DATA	ユーザー提供の論文コンテンツおよび研究メモ

前提条件

• モードとソースを特定できること。
• 生成または検証に必要な仕様ルールを利用できること。

影響と副作用

• ローカルのサイドカーまたはレビュー用サイドカーファイルが作成される場合があります。
• 公開学術 API にクエリを送信する場合があります。
• サイドカーを knows.academy に送信し直すことはありません。

ガードレール

1. ローカル生成は v0.9.0 本番互換 / paper@1 を対象とします（レビュー用サイドカーは review@1 を使用します）。これは完全な正規スキーマ準拠よりも狭い範囲です。詳細は resources/sidecar-spec.md を参照してください。
2. サイドカーを生成するのはホスト LLM です: anthropic SDK や外部 LLM CLI にシェルアウトしないでください。このスキルはエージェント内で実行されます
3. 捏造の禁止: DOI・会場・年がソース内で確認できない場合は、そのキーを完全に省略してください。doi: TODO と書いたり推測したりしないでください
4. トップレベルメタデータ: title、authors、venue、year はトップレベルに配置します（metadata ラッパーはありません）
5. フィールド名は正確に: statement_type、evidence_type、predicate、artifact_type（type/claim ではありません）
6. provenance のアクターは単一です: provenance.actor は 1 つのオブジェクトであり、provenance.actors 配列ではありません
7. confidence はオブジェクトです: {claim_strength: ..., extraction_fidelity: ...}、どちらも high|medium|low のいずれかです
8. coverage はオブジェクトです: coverage.statements（4 値の enum）+ coverage.evidence（3 値の enum）
9. 閉じた enum: actor は tool|person|org（ai/llm/model は決して使用しないでください）。artifact role は subject|supporting|cited。predicate は現在形
10. 数値はクォートしない: value: 22、value: '22' にはしないでください
11. リレーションのカバレッジ: ローカルの比率・孤立の警告を確認し、ソースが裏付けている型に適切なリレーションのみを追加してください。証拠を持つ主張には supported_by を使用します。定義と未解決の問いはソースにアンカーされたままで問題ありません。比率 1.5 は診断値であり、グラフを埋めるためのノルマではありません。
12. ID の形式: プレフィックス付きの説明的なケバブケース: stmt:privacy-budget-tradeoff、ev:cifar10-accuracy-table、art:paper
13. 共有前に検証: Generate と Review の後に oma scholar lint を実行してください。レビュー用サイドカーのクロスレコード参照（record_id#local_id）は認識され、ダングリングとしてフラグされません
14. リモート API に認証はありません: https://knows.academy/api/proxy/* は公開されています。認証ヘッダーを勝手に作らないでください
15. 部分フェッチのパラメータは section（単数形）です: 固定 enum statements|evidence|relations|artifacts|citation
16. フォールバック API キーは任意です: OPENALEX_API_KEY（メタデータ拡充）と S2_API_KEY（Semantic Scholar 専用レート制限）はどちらもスループットを改善しますが、これらがなくてもカスケードは適切に劣化します
17. サイドカーの内容は英語のままにします: スキーマフィールド、ID、statement テキストは上流の慣習に従います。ユーザー向けの応答は oma-config.yaml の language に従います
18. 契約の範囲: ローカル生成ルールと lint は本番互換を追跡しており、完全な正規 v0.9 スキーマではありません。正規のインポートされた形状を保持し、ローカル lint の非互換性を報告してください。その正確なスキーマに対して検証せずに完全なスキーマ準拠を主張したり、$schema を追加したりしないでください。詳細は resources/upstream-spec-cache.md を参照してください。

モード

モード	トリガー	出力
Generate	「この論文 / アブストラクト / ドラフトからサイドカーを作成」「.knows.yaml を生成」	{paper}.knows.yaml（ホスト LLM が出力し、その後 oma scholar lint が検証）
Validate	「このサイドカーを lint」「.knows.yaml を検証」	file:line の指摘を含む合否レポート
Review	「この論文をサイドカーとしてピアレビュー」	{paper}.review.knows.yaml
Analyze	「このサイドカーを要約」「どのような主張をしているか？」	自然言語による回答
Compare	「論文 A と論文 B を構造的に比較」	差分テーブル（主張 / 手法 / 証拠）
Remote	「X に関する論文を検索」「サイドカー :id を取得」「:id の主張のみを取得」	検索結果 / サイドカーのペイロード

プロバイダーのフォールバック（knows.academy → OpenAlex → Semantic Scholar）

knows.academy が現在インデックスしているのは、2026 年の論文のみです（主に arXiv）。それ以前の論文や 2026 年以外の論文（Transformer 2017、BERT 2018、古典的な論文、ジャーナル論文）については、このスキルはメタデータと要約を取得するために OpenAlex に自動的にフォールバックし、OpenAlex にも何もない場合は Semantic Scholar（AI TL;DR、引用数と影響力のある引用数）にフォールバックします。resources/fallback-providers.md を参照してください。

oma scholar CLI サブコマンドを使用します。

# Hybrid search: knows first, OpenAlex fallback
oma scholar search "vision language action"

# Cross-source resolve: figures out which source has the right paper
oma scholar resolve "Attention Is All You Need"

# Get by id (knows record_id, OpenAlex W-id, DOI, arXiv:<id>, CorpusId:<n>)
oma scholar get "10.48550/arXiv.1706.03762"

OpenAlex が結果を返した場合（knows.academy に論文がない場合）は、返された要約を Mode 1 Generate の入力として使用し、ローカルのサイドカーを生成します。

クイックリファレンス

検索（knows + OpenAlex への自動フォールバック）

oma scholar search "diffusion super resolution"
oma scholar search --year-min 2024 "vision language action"

特定の論文を 1 件検索

oma scholar resolve "Attention Is All You Need"
# returns top hit from each source + recommendation

サイドカーまたは論文を取得

# knows.academy full sidecar
oma scholar get "knows:generated/reconvla/1.0.0"

# Partial fetch (claims only, ~700 tokens, 93% reduction vs PDF)
oma scholar get --section statements "knows:generated/reconvla/1.0.0"

# By DOI or OpenAlex W-id (works regardless of knows.academy availability)
oma scholar get "10.48550/arXiv.1706.03762"

# Semantic Scholar: AI TL;DR + citation/influential-citation counts
oma scholar get "arXiv:1706.03762"

knows.academy に接続できない場合、get knows:... は record_id からスラッグを抽出し、自動的に OpenAlex にフォールバックします。結果には fallback: "openalex" のマークが付き、ローカルで Mode 1 Generate を実行するのに便利なメタデータと要約が含まれます。

検証

# Strict mode for own Generate output (default)
oma scholar lint paper.knows.yaml

# Lenient mode for third-party / fetched sidecars
oma scholar lint --lenient remote.knows.yaml

# Treat warnings as failures (CI mode)
oma scholar lint --fail-on-warning paper.knows.yaml

knows.academy が提供するサイドカーの 約 47% に、少なくとも 1 つの参照先が存在しない相互参照が含まれています（本番環境の 15 サンプルを対象に、subject_ref／object_ref の誤記を測定）。サードパーティーのレコードを利用する場合は --lenient を指定し、これらを処理を妨げるエラーではなく警告として表示してください。

Raw API（CLI を利用できない場合）

curl -s "https://knows.academy/api/proxy/search?q=..."
curl -s "https://knows.academy/api/proxy/sidecars/<encoded-id>"
curl -s "https://knows.academy/api/proxy/partial?record_id=<id>&section=statements"
curl -s "https://knows.academy/api/proxy/jobs/stats"   # platform health

設定

プロジェクト固有の設定は config/scholar-config.yaml にあります。ユーザーが調整できるキーは 1 つだけで、別の場所にあります。まず .agents/oma-config.yaml から scholar.base_url を読み取り、なければスキル設定の api.base_url を使用してください。それ以外の設定（エンドポイントのパス、タイムアウト、ID のプレフィックス、lint ルール）は、好みではなくプロトコルの形式を定めるものです。

トラブルシューティング

問題	解決方法
[ERROR] *.value: numeric value '22' is quoted	引用符を削除します：value: '22' -> value: 22
[ERROR] provenance.actor.type: 'ai' is not allowed	tool、person、または org に変更します
[ERROR] *.type: use \statement_type` instead of `type``	type -> statement_type（または evidence_type／predicate／artifact_type）に名前を変更します
[ERROR] provenance.actors: v0.9 spec uses singular \actor``	actors: [{...}] 配列を actor: {...} オブジェクトに置き換えます
[ERROR] *.object_ref: reference 'X' does not match any defined id	subject_ref／object_ref が実在する ID を指すよう修正するか、サードパーティーのデータを利用する場合は --lenient を使用します（レコード間の record_id#local_id 参照は認識され、警告の対象にはなりません）
[WARN] relations: avg relations/statement is N.NN (target ≥ 1.5)	カバレッジを確認します。裏付けがあり、型に適したリンクのみを追加し、グラフを水増ししないでください
[WARN] statements: only N statements; most papers warrant ≥ 8	要約のみから生成する場合は想定どおりです。論文全文からの Generate では 15 件以上になるはずです
[WARN] *.predicate: past-tense '...' is suspicious	現在形に変更します（evaluated_on -> evaluates_on）
リモート API が空の結果を返す	より広いクエリを試し、/api/proxy/jobs/stats を確認します。CLI は自動的に OpenAlex にフォールバックします
knows.academy search failed: fetch failed（stderr）	プラットフォームのタイムアウトです。OpenAlex へのフォールバックは自動で行われます。サイドカーを取得するには、後でもう一度試してください
OpenAlex 403/429	OPENALEX_API_KEY を設定します（resources/setup-openalex.md を参照）
semanticscholar error: HTTP 429（stderr）	匿名ユーザー用プールの利用が制限されています。CLI は 1 回再試行してからソースをスキップします。専用の利用上限を得るには、S2_API_KEY を設定します（semanticscholar.org/product/api で無料登録）
YAML を解析できない	インデントを確認します。数値とブール値は引用符で囲まず、: を含む文字列は引用符で囲む必要があります

参考資料

• 実行手順（選択したタスクに従ってください）：resources/execution-protocol.md
• サイドカー仕様のルール：resources/sidecar-spec.md
• API エンドポイント：resources/api-endpoints.md
• OpenAlex のセットアップ：resources/setup-openalex.md
• 上流仕様のスナップショット：resources/upstream-spec-cache.md
• 生成後のチェックリスト：resources/checklist.md
• CLI サブコマンド：oma scholar search|resolve|get|lint（実装は cli/commands/scholar/ にあります）
• コンテキストの読み込み：../_shared/core/context-loading.md
• 品質原則：../_shared/core/quality-principles.md
• i18n ルール：../../rules/i18n-guide.md