source-tracker

ソーストラッカー

概要

ソーストラッカーは、研究ワークフロー向けの小規模な永続化引用管理ツールです。 研究ソースは、ブラウザーのタブ、メモ、一時ファイル、別々のセッションに分散しがちです。 URLは一度引用されただけで見失われ、http／https や www の違いによる重複が蓄積し、参考文献のエクスポートは最後に手作業で整理することになります。

このスキルは、引用したすべてのURLをポータブルなSQLiteデータベースで管理することで、こうした問題を解決します。 引用したらすぐにソースを追加し、トピック別にタグを付け、URLのバリエーションを重複排除し、古くなったリンクを再確認して、Markdown、BibTeX、CSV、JSON形式で参考文献をエクスポートできます。

データベースのパスは、--db-path または SOURCE_TRACKER_DB 環境変数で設定できます。 どちらも設定されていない場合、コマンドは現在の作業ディレクトリを基準とした ./sources.db を使用します。

クイックスタート

スキルのディレクトリから実行します。

python scripts/source_db.py add --url URL --topic TOPIC

実践的な例：

python scripts/source_db.py add \
  --url "https://example.org/report" \
  --topic "battery supply chain" \
  --title "Example Battery Report" \
  --notes "Baseline market-size estimate" \
  --type report

研究が複数のフォルダーやセッションにまたがる場合は、永続化されたプロジェクトデータベースを使用します。

export SOURCE_TRACKER_DB="$HOME/research/sources.db"
python scripts/source_db.py add --url "https://example.org" --topic "market scan"

または、パスを明示的に指定します。

python scripts/source_db.py --db-path "$HOME/research/sources.db" add --url "https://example.org" --topic "market scan"

ワークフロー

1. ソースを追加する

URLが引用ソースになった時点で、すべて追加します。必ずトピックを指定してください。 通常のウェブページではない資料には、ソースタイプを指定してください。

python scripts/source_db.py add \
  --url "https://example.com/article#section" \
  --topic "ai regulation" \
  --title "Example Article" \
  --notes "Defines the enforcement timeline" \
  --type news \
  --session-id "research-2026-07-06"

--title を省略すると、スクリプトは可能な範囲でGETリクエストを試み、<title> を解析します。 取得に失敗した場合でも、タイトルが空欄の状態でソースは追加されます。

完了条件：新しい行の場合は inserted: true、すでにDBに存在する正規化済みURLと完全に一致する場合は inserted: false を含むJSONオブジェクトがコマンドから出力されます。

2. ソースを検索する

トピックと任意のフィルターを指定して検索します。 結果はJSON形式なので、ほかのツールにパイプで渡せます。

python scripts/source_db.py search --topic "ai regulation"

日付範囲で絞り込みます。

python scripts/source_db.py search \
  --topic "ai regulation" \
  --from 2026-01-01 \
  --to 2026-12-31

ソースタイプと確認ステータスで絞り込みます。

python scripts/source_db.py search \
  --topic "ai regulation" \
  --type report \
  --verified true

完了条件：JSON配列に、トピックとフィルターに一致するレコードのみが含まれていること。

3. URLのバリエーションを重複排除する

調査が一段落した後、またはエクスポートの前に重複排除を実行します。 http と https、www. の有無、フラグメントのみの違い、末尾のスラッシュの違いなど、一般的なURLのバリエーションを統合します。

python scripts/source_db.py dedup

完了条件：merged_groups、removed_rows、removed_ids を含むJSONの概要がコマンドから出力されます。 統合後に残るレコードには、最も早い accessed_at が保持され、統合されたすべての行から空でないメモがまとめられます。

4. 参考文献をエクスポートする

トピックの参考文献をエクスポートします。 --output を省略すると、内容が標準出力に出力されます。 --output を指定した場合は、ファイルパスをユーザーに伝えてください。

Markdown：

python scripts/source_db.py export \
  --topic "ai regulation" \
  --format markdown \
  --output ai-regulation-sources.md

BibTeX：

python scripts/source_db.py export \
  --topic "ai regulation" \
  --format bibtex \
  --output ai-regulation-sources.bib

CSV：

python scripts/source_db.py export \
  --topic "ai regulation" \
  --format csv \
  --output ai-regulation-sources.csv

JSON：

python scripts/source_db.py export \
  --topic "ai regulation" \
  --format json \
  --output ai-regulation-sources.json

完了条件：出力に、指定したトピックのすべてのソースが、トピック／タイトル／日付順で指定形式に並んでいること。

5. ヘルスチェック

最終レポートの作成前に手動で、またはcronスケジューラーからリンクのヘルスチェックを実行します。 チェッカーはHEADリクエストを使用し、HTTP 200〜399を有効と判定して last_checked を更新します。また、verified = 0 に設定してリンク切れを記録します。

python scripts/url_health.py --stale-days 30 --timeout 10 --batch-size 50

データベースのパスを明示的に指定する場合：

python scripts/url_health.py \
  --db-path "$HOME/research/sources.db" \
  --stale-days 7 \
  --timeout 5 \
  --batch-size 100

完了条件：Checked N URLs: M alive, K dead がコマンドから出力され、終了コード0で終了すること。 リンク切れはデータベースに記録され、実行時エラーとしては扱われません。

6. 統計情報とトピック一覧

トピック、タイプ、確認ステータス別にソース数を表示します。

python scripts/source_db.py stats

すべてのトピックタグを一覧表示します。

python scripts/source_db.py list-topics

完了条件：統計情報はJSONとして出力され、トピック一覧は重複のないトピック文字列のJSON配列として出力されます。

URL の正規化ルール

Source Tracker では、URL を次の 2 つのレベルで処理します。

1. 正規保存 URL

   • スキームとホストを小文字にします。
   • #section などの URL フラグメントを削除します。
   • ルート以外のパス末尾にあるスラッシュを削除します。
   • クエリー文字列は保持します。
   • www. は、ユーザーが表示を期待している URL の一部である可能性があるため保持します。

2. 重複比較キー

   • 正規保存のルールをすべて適用します。
   • http と https のバリエーションを同じソースとして扱います。
   • 比較時に限り、ホストの先頭にある www. を削除します。

例：

入力	正規 URL	重複比較
HTTPS://WWW.Example.com/Page/#intro	https://www.example.com/Page	//example.com/Page
http://example.com/	http://example.com/	//example.com/
https://www.example.com	https://www.example.com/	//example.com/

ソースの種類

--type には、次のいずれかの値を指定します。

種類	用途
web	一般的なウェブページ、ドキュメントページ、ブログ記事、ランディングページ。
pdf	PDF への直接 URL、または正式なソースが PDF であるページ。
api	API エンドポイント、JSON/XML データエンドポイント、機械可読なサービス出力。
dataset	データのダウンロード、CSV/Parquet リポジトリ、公開データカタログ。
book	オンライン書籍、書籍の章、スキャン画像、書籍の書誌ページ。
news	ニュース記事、通信社の報道、インタビュー、ライブブログ。
report	ホワイトペーパー、政府報告書、アナリストレポート、機関の報告書。

リサーチワークフローとの統合

ディープリサーチ

反復的に検索、抽出、統合を行う際は、品質フィルターを通過したソースを、統合で使用する前にすぐ追加します。

python scripts/source_db.py add \
  --url "SOURCE_URL" \
  --topic "PROJECT_TOPIC" \
  --title "SOURCE_TITLE" \
  --notes "Supports sub-question: ..." \
  --session-id "SESSION_ID"

最終レポートの作成前に、次を実行します。

python scripts/source_db.py dedup
python scripts/source_db.py export --topic "PROJECT_TOPIC" --format markdown --output bibliography.md

ノートブック形式のソース保管庫

ソース保管庫を構築する際は、各ソースを保管庫に登録する時点で追加します。保管庫またはコーパスの識別子を --session-id に保存し、primary evidence、background、contradiction などの対象範囲ラベルにはメモを使用します。

python scripts/source_db.py add \
  --url "SOURCE_URL" \
  --topic "VAULT_TOPIC" \
  --notes "Vault source 007; primary evidence" \
  --session-id "vault-007"

エンティティのリサーチ

エンティティの概要資料では、エンティティ名とリサーチの観点を組み合わせてソースにタグを付けます。ソースの種類を使って、公式登録情報、ネガティブ報道、報告書、データセットを区別します。

python scripts/source_db.py add \
  --url "SOURCE_URL" \
  --topic "Acme Ltd adverse media" \
  --type news \
  --notes "Allegation source; not independently verified"

cron の使用方法

cron スケジューラーを使って、週次のヘルスチェックを実行します。crontab の設定例：

0 9 * * 1 cd /path/to/source-tracker && SOURCE_TRACKER_DB=/path/to/sources.db python scripts/url_health.py --stale-days 30 --batch-size 100 >> /path/to/source-health.log 2>&1

非常に大規模なデータベースでは、スケジューラージョブの実行時間が長くならないよう、小さなバッチを使用します。

0 9 * * 1 cd /path/to/source-tracker && python scripts/url_health.py --db-path /path/to/sources.db --stale-days 30 --batch-size 50

出力形式

• Markdown の参考文献一覧 — トピックごとにまとめ、各ソースを - [Title](URL) — notes (accessed_at) の形式で出力します。
• BibTeX — @misc{key, title={...}, url={...}, note={...}, urldate={...}}。
• CSV — id,url,title,topic,source_type,accessed_at,notes,verified,last_checked。
• JSON — session_id と正規化済み URL フィールドを含む、完全なソースオブジェクトの配列。

具体例については、references/export-formats.md を参照してください。

よくある落とし穴

1. URL を捏造する — ウェブ検索ツール、ウェブ抽出ツール、ユーザー提供のソース、またはその他の検証可能なソース経路から得た URL 以外は追加しないでください。URL を推測した場合は、追加する前に検証してください。
2. トピックタグの付け忘れ — --topic が必須なのには理由があります。検索、統計、エクスポートで類似するトピックが分散しないよう、一貫したトピック名を使用してください。
3. ヘルスチェックの古さ — verified = 1 は、最後のチェック時にソースが有効だったことを示すもので、いつまでも有効であることを示すものではありません。長期プロジェクトでは、最終納品前に url_health.py を実行してください。
4. 重複するバリエーション — https://www.example.com/、http://example.com、https://example.com#intro は、同じソースを指している場合があります。エクスポート前に dedup を実行してください。
5. タイトルが空欄 — タイトルの抽出は最善を尽くして行われます。重要な引用では、リモートページの取得に頼らず、--title を明示的に指定してください。
6. 相対データベースパスの混同 — デフォルトの ./sources.db は、現在の作業ディレクトリによって異なります。長期プロジェクトでは SOURCE_TRACKER_DB または --db-path を使用してください。

検証チェックリスト

• 追加前に、引用するすべてのURLを実際のソースチャネルで確認しました。
• 追加した各行に、意味のある --topic と適切な --type が設定されています。
• 参考文献をエクスポートする前に、python scripts/source_db.py dedup を実行しました。
• 最終成果物に対して、最近 python scripts/url_health.py を実行しました。
• エクスポートした参考文献は、指定された形式と出力先を使用しています。
• リンク切れや未検証のリンクを、最終的に引用する前に確認しました。
• 複数セッションで作業する場合、データベースのパスを明示しています（--db-path または SOURCE_TRACKER_DB）。