grounded-citations

根拠付き引用

外部ソースから得た主張にはすべて、Perplexity 形式でインラインの番号付き引用と Sources: リストを付けます。url → [n] の対応付けは台帳スクリプトが管理するため、 番号と URL は取得した情報に基づくものであり、記憶から生成されることはありません。モデルが 出力するのは、渡された小さな整数だけです。

重要度の高い作業では、同じ台帳をファクトチェックのチェーンとしても使用します。逐語引用を 各ソースに添付し（取得したページのテキストに文字どおり含まれていない引用は却下されます）、 モデルの知識に基づく主張には [unverified] のフラグを付けます。また、verify --evidence を実行すると、引用元に根拠がない草稿はすべて失敗します。

このスキルは、チャットでの回答、文書（markdown、PDF、docx、スライド）、調査レポートを対象とします。 学術論文の BibTeX パイプラインは対象外です。会議論文には arxiv スキルを使用してください。このスキルは そのスキルに情報を提供します（references/citation-formats.md を参照）。

使用する場合

回答や成果物が、既知の情報ではなく取得した情報に基づく場合は必ず使用します。

• 調査、比較、ニュースの要約、「X の現在の状況はどうなっていますか」
• 外部の事実を引用、言い換え、報告する、ディスクに書き込むすべての成果物 — レポート、概要資料、ドキュメント、スライド資料、Wiki ページ
• ユーザーが作業内容を確認したいと考えるファクト調査
• 相反する情報源を明示する必要がある、複数ソースの統合

取得が別の作業に付随するだけの場合は、インライン引用を省略します。たとえば、コーディング中に構文やバージョンを手早く調べる場合、気軽な会話、創作などです。ユーザーがリンクを求めると考えられる場合に限り、URL を記載してください。

前提条件

標準ツールセット以外に必要なものはありません。scripts/sources.py は Python 3 の標準ライブラリのみを使用します。 情報の取得には、設定されているもの（web_search、web_extract、 browser_exec、または terminal（curl、CLI））を使用します。

台帳の場所：$HERMES_HOME/cache/citations/ledger.json（プロファイル対応）。 タスクごとに --ledger <path> または HERMES_CITATION_LEDGER で上書きできます。

実行方法

S=~/.hermes/skills/research/grounded-citations/scripts/sources.py

python "$S" reset                                  # start a clean ledger
python "$S" add https://example.com/a --title "A"  # prints: [1]
python "$S" add https://example.com/b --title "B"  # prints: [2]
python "$S" list                                   # ledger table
python "$S" render                                 # Sources: block
python "$S" verify draft.md                        # catch bad citations

add は冪等で、URL を正規化します。同じ台帳内では、同じページに常に同じ ID が割り当てられるため、複数回にわたる検索や抽出でも ID は安定します。

クイックリファレンス

操作	コマンド
新しいタスク用に台帳を初期化	sources.py reset
ソースを登録して ID を取得	sources.py add <url> [--title T]
複数のソースを一度に登録	sources.py add <url1> <url2> ...
JSON ツール出力から登録	sources.py ingest results.json
ソースに逐語的な根拠を添付	sources.py quote <id> --text "exact wording" --from page.txt
台帳を表示	sources.py list [--json]
Sources ブロックを生成	sources.py render [--style markdown|plain|footnotes|bibtex|evidence] [--only 1,3]
草稿が引用するソースだけを生成	sources.py render --cited-in draft.md
草稿内の Sources ブロックを書き換え	sources.py render --replace-in draft.md
草稿の引用を確認	sources.py verify draft.md [--strict] [--min-coverage 0.6] [--evidence]

手順

① 台帳をリセットします。 根拠に基づく回答やドキュメントを作成するタスクの開始時に実行してください。ID がすでに下書きに含まれる作業を続ける場合は、リセットを省略します。台帳を再利用すると、番号を安定させられます。

② 取得時にすべてのソースを登録します。 web_search／web_extract／browser_exec／フェッチを行うたびに、URL を sources.py add に渡す（または生の JSON を sources.py ingest にパイプする）必要があります。文章を書く前に実行してください。後から記憶を頼りに登録することは、このスキルが防ごうとしている失敗です。

③ 執筆と同時に引用します。 ソースが裏付ける各文の直後に、角括弧で囲んだ ID を配置してください。

Ice floats because it is less dense than liquid water.[1][2]

• 角括弧の前にスペースを入れないでください。各 ID はそれぞれ別の角括弧に入れます。
• 1 文あたり最大 3 個の ID を付けます。末尾にまとめて引用せず、文ごとに引用してください。
• 台帳が返した ID のみを使用してください。ID や URL を捏造してはいけません。
• 自分の知識に基づく主張には引用を付けません。
• ソースが食い違う場合は、それぞれの見解を個別の ID とともに示してください。
• 数値、日付、名前は、ソースに記載されているとおりに正確に引用してください。情報が見つからない場合は、曖昧にせず「X に関するソースは見つかりませんでした」と明記してください。

④ Sources ブロックを追加します。 sources.py render --cited-in <draft> を使用し、ID と URL の対応を台帳から機械的に生成してください。手作業で入力してはいけません。Markdown 以外の形式では、該当する --style を選び、配置については references/citation-formats.md に従ってください（docx では脚注、PDF／LaTeX では文末注、スライドでは Sources スライド、wiki 出力ではページごとのソース一覧）。

⑤ 提出前に確認します。 sources.py verify <draft> は、未知の ID がある場合、Sources ブロックが台帳と一致しない場合、または（--min-coverage を指定したときに）文章の引用が不十分な場合に、ゼロ以外の終了コードを返します。修正して再実行してください。

⑥ チャットでの回答も同じ手順に従います。 下書きには返信文を使用し、ソースを登録して本文中で引用し、最後にレンダリングした Sources: リストを付けてください。短い回答では、ファイルに書き出す代わりに sources.py render --only <ids> でブロックを生成できます。

マルチプラットフォーム調査

「X について、みんなはどう言っていますか」／「ウェブ全体で X を調査してください」という依頼に対して、web_search だけを使うのでは不十分です。ソースの種類ごとに並行して検索・収集し、すべての主張を、それが見つかったプラットフォームに帰属させて統合してください。

ソースの種類	方法	得られる情報
オープンウェブ	web_search → web_extract	公式ドキュメント、記事、発表
コミュニティでの議論	reddit-reading（search、thread）	実際のユーザー体験、不満、回避策
ブログ／リリース／変更履歴	rss-feeds（read、discover）	日付のある一次投稿、バージョン履歴
動画	youtube-content	解説、デモ、講演
コード	gh search repos／gh search issues を使う terminal	実装、未解決のバグ
X／Twitter	xurl（API アクセスが必要）	発表、開発者の発言

reddit-reading と rss-feeds のスキルは任意です。利用できない場合は、使用する前に hermes skills install official/social-media/reddit-reading または hermes skills install official/research/rss-feeds でインストールしてください。

各方法で取得したすべての URL は、到着時に台帳へ登録してください（手順②）。意見と測定結果は分けて扱います。Reddit のスレッドが裏付けるのは、ユーザーが何かを「報告している」ということであり、それが事実であることではありません。一次ソースと組み合わせるか、感情・意見として明示してください。プラットフォームごとのカバレッジの不足（「Reddit の検索では 3 月より新しい情報は見つかりませんでした」など）を報告し、うまくいった検索結果だけに黙って範囲を狭めてはいけません。

ファクトチェックモード

読者が根拠の連鎖を確認できる必要がある作業（医療、法律、金融、安全性、議論のある主張など）、またはユーザーがファクトチェックを求めている場合は、引用からエビデンスに切り替えます。

① ソースごとに逐語的な引用を添付します。 ページを抽出した後、そのテキストをファイルに保存し、各主張を裏付ける文を添付します。

python "$S" quote 1 --text "Ice is about 9% less dense than liquid water." --from page1.txt

引用は、エビデンステキストに逐語的に含まれていない限り、拒否されます（空白、大文字と小文字、Markdown のマークアップは無視されます。抽出テキストの _[ERAP1](https://…)_ のようなインラインリンクは、読者に見えるプレーンな文章と一致します）。そのため、言い換えや記憶違いの数値がエビデンスを装うことはありません。取得したテキストからコピー＆ペーストしてください。入力し直してはいけません。読者に見えるとおりに文を引用してください。照合処理が抽出ツールのマークアップを考慮するため、引用にリンク構文やエスケープされたアスタリスクを再現する必要はありません。

② モデルの知識に基づく主張には [unverified] を付けます。 ソースを確認できなかった、根拠となる重要な主張には、引用の代わりに明示的なマーカーを付けます。

The refactor likely predates the 2.0 release.[unverified]

verify --min-coverage は [unverified] の文をカバー済みとして数えます。目標はすべての主張について情報源を明示することであり、すべての文に引用を付けることではありません。重要な主張を確認できる場合は確認してください。[unverified] は本当に確認できない内容に使い、成果物のファクトチェックが [unverified] マーカーばかりになる場合は、概要にその旨を記載してください。

③ 議論のある事実は、2つ目の独立したソースと照合します。 2つのソースの見解が異なる場合は、それぞれの ID と引用を添えて両方の見解を示し、どちらを重視するか、その理由も記載してください。1つのソースは報告、独立した2つのソースは裏付けです。

④ エビデンスゲートで検証し、エビデンスブロックを出力します。

python "$S" verify report.md --evidence --min-coverage 0.5
python "$S" render --style evidence --replace-in report.md

--evidence は、引用されたソースに引用文が添付されていない場合、ドラフトを失敗させます。evidence レンダースタイルは各ソースの URL の下に引用文を出力するため、成果物には「主張 → ソース → 正確な裏付けテキスト」が示され、何も鵜呑みにする必要がありません。--replace-in <draft> を使うと、既存の Sources ブロックをその場で書き換えられます（冪等性があり、引用を追加した後でも安全に再実行できます）。一方、--cited-in は標準出力に出力します。どちらも見出し ## Sources を出力します（--style plain の場合は Sources: を出力します）。

--min-coverage のカウント対象。 カバレッジは 情報源が明示された文 / 本文の文 です。本文の文とは、Sources ブロック、見出し（#）、表の行（|）、フェンス付きコードを除外し、引用ブロックのマーカーを取り除いた後の、4語以上を含む空でない行の断片です。情報源は [n] の引用または [unverified] マーカーのいずれかで明示されます。両方を含む文も1文として数えます。しきい値を指定せずに verify を実行し、info: stats: の行を確認して件数を把握してから数値を選んでください。

落とし穴

• 執筆後に登録すること。 台帳には草稿から再構成するのではなく、ツールの出力から情報を登録する必要があります。そうすると、番号付けで取り除いたはずの、まさにその URL の幻覚リスクが再び生じます。
• タスクの途中で番号を振り直すこと。 草稿内の ID を手作業で編集してはいけません。ID は台帳上の識別子です。草稿が [4] を参照しているなら、[4] はその情報源のままでなければなりません。reset を実行するのはタスク間のみです。
• Sources ブロックに URL を再入力すること。 必ず render を使ってください。手入力した URL は未検証の主張です。
• 検索結果のスニペットをページを読んだかのように引用すること。 web_search の説明が裏付けるのは、そこに文字どおり記載されている内容のみです。主張の裏付けに本文が必要なら、抽出したページを引用してください。まず web_extract を実行します。
• 引用しすぎること。 1 文あたりの ID は 3 つが上限です。すべての節に引用を付けると文章が読みにくくなり、どの情報源が根拠となっているか分かりにくくなります。
• コードや設定ファイルなどの成果物で台帳を引用すること。 情報源のコメントは、コード内ではなく、文章の成果物やドキュメントのヘッダーに記載します。
• サブエージェントを並行して使うこと。 各サブエージェントの作業ディレクトリは個別です。出力を統合する場合は、すべてのサブエージェントで --ledger（または HERMES_CITATION_LEDGER）を指定して 1 つの台帳を使ってください。そうしないと、ID が衝突します。
• ページではなくスニペットから引用すること。 根拠となる引用は検索結果の説明ではなく、抽出したページのテキストから取る必要があります。まず web_extract を実行してテキストを保存し、その後 quote --from でそのファイルを指定します。
• quote --text の内容を言い換えること。 原文一致チェックで拒否されます。実際の文を探してください。一致するように言い換えてはいけません。
• [unverified] を逃げ道として使うこと。 これは、実際に情報源を特定できないまれな主張に付けるものです。ほとんどの文に付いているなら、必要なのはマーカーの追加ではなく、さらなる情報収集です。
• Sources ブロックを手作業で編集すること。 render --replace-in <draft> を使ってください。ファイルを自分で切り貼りすると、古いブロックや重複したブロックが残り、verify に警告されるおそれがあります。

検証

python "$S" verify report.md --strict --min-coverage 0.5

緑色の表示は、草稿内のすべての [n] が台帳に存在し、Sources ブロックに引用した ID と台帳内の URL が漏れなく記載され、情報源がある文のうち引用が付いている割合が基準を満たしていることを示します。終了コードが 0 でも警告を確認してください。登録済みの情報源に引用がない場合、通常は編集時に主張の帰属情報が失われています。