cross-linker

クロスリンカー — Wiki の相互参照を自動化

互いに参照するべきなのに、まだ参照していないページ間の不足している [[wikilinks]] を見つけて追加し、Wiki のナレッジグラフをより緊密につなげます。

llm-wiki/SKILL.md の検索プリミティブ表に従ってください。 ステップ 1 では、フロントマターのみを grep して（ページ全体は対象にせず）レジストリを作成します。リンクされていない言及を検出する工程に限り、ページ全体を Read します。その場合も、概要やタイトルからリンク先として妥当と考えられるページのみを読みます。Vault 全体を無差別に読み込むのを避けることが、このフレームワークの目的です。

開始前に

執筆スタイル： 自然言語の Markdown を新規作成または書き直す前に、llm-wiki/SKILL.md の「執筆スタイルの解決」セクションを読み、その内容を適用してください。フレームワークのスキーマ、出典、安全性、および操作固有の要件が優先されます。 WRITING.md の設定は、新規作成または書き直す自然言語の Markdown にのみ適用します。元の内容と構造化レコードはそのまま保持してください。

1. 設定を解決する — llm-wiki/SKILL.md の設定解決プロトコルに従います（インラインの @name による上書き → CWD から .env を親ディレクトリへたどる → グローバル設定 → プロンプトでのセットアップ）。これにより、OBSIDIAN_VAULT_PATH と OBSIDIAN_LINK_FORMAT が得られます（デフォルト：wikilink）。
2. index.md を読んで、すべてのページと各ページの1行の説明を確認します。
3. log.md に目を通し、最近取り込まれた内容を確認します（新しいページへのリンク付けを優先します）。

ステップ 4 でリンクを挿入する際は、llm-wiki/SKILL.md のリンク形式のセクションに従い、OBSIDIAN_LINK_FORMAT の値を使用してください。OBSIDIAN_LINK_FORMAT=markdown の場合は、編集対象のファイルからリンク先ページまでの相対 .md パスを計算します。

ステップ 1：ページレジストリを作成する

Vault 内のすべての .md ファイルを Glob で取得します（_archives/、_readouts/、.obsidian/ は除外）。各ページから以下を抽出します。

• ファイル名（.md を除く）— wikilink のターゲットです
• フロントマターのタイトル
• フロントマターのエイリアス（あれば）
• フロントマターのタグ
• フロントマターまたはディレクトリから推定したカテゴリ
• 1行の概要 — 最初の文、または title フィールド

次の参照テーブルを作成します。

page_name → { path, title, aliases, tags, summary }

これが「語彙」です。このテーブルの各項目は、有効な wikilink ターゲットです。

ステップ 2：不足しているリンクをスキャンする

Vault 内の各ページについて、次の手順を実行します。

1. 内容全体を読む

2. 既存の wikilink を抽出する — すでに存在するすべての [[...]] 参照を見つけます

3. リンクされていない言及を検索する — ページのテキストに、次のいずれかが [[...]] で囲まれずに含まれているか確認します。

   • ページのファイル名（例：「MyProject」という単語が登場するのに、[[projects/my-project/my-project]] が存在しない）
   • フロントマターのページタイトル
   • フロントマターのエイリアス
   • レジストリにあるエンティティ名、プロジェクト名、概念名

4. 意味的なつながりを確認する — 複数のタグを共有するページや、同じプロジェクトディレクトリにあるページのうち、相互にリンクしていないものを確認します。

マッチングルール

• 名前は大文字・小文字を区別せずに照合します（例：「my-project」はページ MyProject に一致します）
• 発音区別符号を区別せずに照合します — 比較する前に、ページ名と本文テキストの両方を Unicode NFKD で正規化します（アクセント付き文字を基本文字と結合文字に分解し、結合文字を削除します）。これにより、本文中の「Muller」がページ [[entities/müller]] に一致し、その逆も可能になります。
• 自己参照は除外します — ページは自分自身にリンクしません
• 一般的な単語は除外します — 「the」「and」などの一般的な語句はリンクしません。特徴的な名前のみを照合します
• 曖昧さのない最短の wikilink パスを優先します — Vault 内で一意の名前であれば、[[full/path/to/page-name]] ではなく [[page-name]] を使用します
• コードブロック内やフロントマター内にはリンクしません
• 二重にリンクしません — ページにすでに [[foo]] がある場合、追加のリンクは作成しません

ステップ 3：候補を評価して順位付けする

考えられるリンクをすべて追加する価値があるとは限りません。複合的な指標を使って各候補を評価し、確信度ラベルを付けます。

スコアリング

シグナル	ポイント	例
テキスト内の完全一致する名前	+4	本文に「MyProject」が登場 → my-project.md にリンク
共通タグ（2つ以上）	+2	どちらにも #ai #agent のタグがあるが、相互リンクはない
同じプロジェクトでリンクなし	+2	どちらも projects/my-project/ 配下にあるが、互いを参照していない
言及されたエンティティ／概念	+2	ページで「ナレッジグラフ」に言及 → [[concepts/knowledge-graphs]] にリンク
カテゴリをまたぐ関連性	+2	ソースが concepts/ にあり、ターゲットが entities/ にある（または skills/ ↔ synthesis/）— 異なる知識レイヤー間のリンクは、アーキテクチャ上の価値が高くなります
周辺ページからハブへの接続	+2	ソースページのリンク総数が ≤ 2（周辺ページ）で、ターゲットが ≥ 8（ハブ）— つながりの弱いページを、基盤となる概念につなげます
名前の部分一致	+1	「graph」が登場するが、ページ名は knowledge-graphs — 妥当ではあるものの、曖昧です

信頼度ラベル

スコアに基づいて、各候補に信頼度ラベルを付けます：

スコア	ラベル	対応
≥ 6	EXTRACTED	リンクの確度は非常に高く、完全一致または非常に強い一致です。インラインで適用します。
3–5	INFERRED	共通の文脈、カテゴリをまたぐ関連性、周辺ページからハブへの接続に基づく妥当な推論です。インラインまたは関連セクションとして適用します。
1–2	AMBIGUOUS	一致が弱い、または部分的です。ユーザーがつながりの弱いページの関連付けを明示的に求めていない限り、スキップします。

EXTRACTED と INFERRED の候補のみを適用します。ユーザーが INFERRED のリンクを信頼する前に確認できるよう、クロスリンクレポートには信頼度ラベルを含めてください。

ステップ 4：リンクを適用する

書き込み前のスナップショット — 最初のファイル書き込みの前に、保管庫自体が Git リポジトリのルートかどうかを確認します。より大きなリポジトリのサブディレクトリであるだけでは該当しません。そこで git add -A を実行すると、無関係なファイルまで追加される可能性があります。保管庫が独立した Git リポジトリでない場合は、このステップを何も言わずにスキップします。警告したり、git init を提案したりしないでください。

VAULT_REAL_PATH=$(cd "$OBSIDIAN_VAULT_PATH" && pwd -P)
VAULT_GIT_ROOT=$(git -C "$OBSIDIAN_VAULT_PATH" rev-parse --show-toplevel 2>/dev/null || true)
SNAPSHOT_SHA=""

if [ -n "$VAULT_GIT_ROOT" ] && [ "$VAULT_GIT_ROOT" = "$VAULT_REAL_PATH" ]; then
  if git -C "$OBSIDIAN_VAULT_PATH" diff --quiet \
    && git -C "$OBSIDIAN_VAULT_PATH" diff --cached --quiet \
    && [ -z "$(git -C "$OBSIDIAN_VAULT_PATH" ls-files --others --exclude-standard)" ]; then
    SNAPSHOT_SHA=$(git -C "$OBSIDIAN_VAULT_PATH" rev-parse HEAD)
  else
    if ! git -C "$OBSIDIAN_VAULT_PATH" add -A; then
      echo "Pre-write snapshot failed; abort the skill without writing any vault files." >&2
      exit 1
    fi
    if ! git -C "$OBSIDIAN_VAULT_PATH" commit -m "pre-cross-linker snapshot" --quiet; then
      echo "Pre-write snapshot failed; abort the skill without writing any vault files." >&2
      exit 1
    fi
    SNAPSHOT_SHA=$(git -C "$OBSIDIAN_VAULT_PATH" rev-parse HEAD)
  fi
fi

クリーンなリポジトリの場合は、意図的に git commit を実行しないため、「コミットするものがありません」はエラーとして扱われません。git add または git commit が失敗した場合は、保管庫を編集する前に停止してください。約束したスナップショットを作成せずに続行してはいけません。

SNAPSHOT_SHA が空でなく、スキルがファイルを書き込む場合は、最終レポートに SHA を含めてください。実行全体を取り消すには、後から加えられた変更のうち残す価値があるものがないことを確認してから、次を実行できます：

git -C "$OBSIDIAN_VAULT_PATH" reset --hard "$SNAPSHOT_SHA"
git -C "$OBSIDIAN_VAULT_PATH" clean -fd

リンクが不足しているページごとに、次の手順を行います：

4a：インラインリンク（推奨）

本文でその用語が最初に自然な形で登場する箇所を見つけ、ウィキリンクで囲みます：

変更前：

This project uses knowledge graphs to connect entities.

変更後：

This project uses [[concepts/knowledge-graphs|knowledge graphs]] to connect entities.

ウィキリンクのパスと表示テキストが異なる場合は、[[path|display text]] 形式を使用します。

4b：関連セクション（代替手段）

本文でその用語に自然な形で触れていないものの、ページ同士に意味的な関連性（共通タグ、同じプロジェクト）がある場合は、ページの末尾に ## Related セクションを追加します：

## Related

- [[projects/my-project/my-project]] — Also uses AI agents for research automation
- [[concepts/knowledge-graphs]] — Core technique used in this project

## Related セクションがすでにある場合は、そこに追記します。既存の項目を重複して追加しないでください。

4c: 関係タイプを推論して書き込む

追加されたすべての EXTRACTED または INFERRED リンク（インラインまたは関連セクション）について、周囲の文脈から意味的な関係タイプを推論し、ページの relationships: frontmatter ブロックに書き込みます。AMBIGUOUS リンクはスキップします。

タイプ推論ルール — 言及を含む文（関連セクションのリンクの場合は、ページタイトルと共有タグの文脈）をスキャンします:

文のパターン	推論されるタイプ
"X extends / builds on / generalises Y"	extends
"X implements / is an implementation of Y"	implements
"X contradicts / opposes / refutes / is at odds with Y"	contradicts
"X is derived from / based on / adapted from Y"	derived_from
"X uses / relies on / depends on / requires Y"	uses
"X replaces / supersedes / deprecates Y"	replaces
共有タグ、または方向性の手がかりがないカテゴリ横断の推論	related_to

周囲の文脈が曖昧な場合、またはリンクが共有タグのマッチング（本文中の言及なし）に由来する場合は、デフォルトで related_to とします。

ブロックの書き込み:

ページの YAML frontmatter を読み取ります。relationships: ブロックがすでに存在する場合は、既存のターゲットを重複させずに新しいエントリを追加します。ブロックが存在しない場合は、aliases: の後（aliases: がない場合は tags: の後）に追加します。

relationships:
  - target: "[[concepts/knowledge-graphs]]"
    type: uses

relationships: YAML ブロックの target 値には、OBSIDIAN_LINK_FORMAT に関係なく、常に wikilink 形式（[[path/to/page]]）を使用してください。OBSIDIAN_LINK_FORMAT 設定は本文の内容を制御しますが、frontmatter プロパティは常に wikilink 構文を使用することで、wiki-export が確実に解析できるようになります。

このクロスリンカー実行で追加されたリンクのエントリのみを追加してください — すでに存在していた型付きエントリには触れないでください。

Step 5: Misc ページの親和性をスコアリングする

メインのリンク処理の後、misc/ 内のすべてのページ（frontmatter に promotion_status: misc があるページ、または misc/ ディレクトリ配下にあるページ）の親和性スコアを更新します。

各 misc ページについて:

1. 発信リンクを収集 — ページ本文内のすべての [[wikilinks]]
2. 受信リンクを収集 — vault 内で [[misc/<slug>]] および [[<slug>]] 参照を grep する
3. リンクされた各ページ（双方向）について、プロジェクトに属するかどうかを確認する:
   • projects/<project-name>/ 配下にある
   • プロジェクト名に一致する project: frontmatter フィールドがある
4. プロジェクト名でグループ化して合計する: outgoing_links + incoming_links
5. misc ページの affinity frontmatter ブロックを更新する:

affinity:
  obsidian-wiki: 3
  another-project: 1

6. いずれかのプロジェクトのスコアが 3 以上の場合: このページを 昇格候補 としてフラグを立て、レポート用に記録する

効率化の注意: misc ページのみ本文全体を読み取ってください — 他のページはプロジェクト所属を判定するために frontmatter の grep だけで十分です。

Step 6: レポート

概要を提示します:

## Cross-Link Report

### Links Added: 23 across 12 pages

| Page | Links Added | Confidence | Placement | Relationship Types |
|---|---|---|---|---|
| `projects/my-project/my-project.md` | 3 | EXTRACTED | 2 inline, 1 related | uses ×2, related_to ×1 |
| `entities/jane-doe.md` | 5 | INFERRED | 3 inline, 2 related | extends ×1, uses ×3, related_to ×1 |
| ... | | | | |

### Orphan Pages Remaining: 2
- `references/foo.md` — no incoming or outgoing links found
- `concepts/bar.md` — could not find related pages

### Misc Promotion Candidates: N
Pages in misc/ that have ≥ 3 connections to a single project — ready to be promoted:

| Page | Top Project | Score |
|---|---|---|
| `misc/web-martinfowler-articles-microservices.md` | `obsidian-wiki` | 4 |

To promote: move the page to `projects/<project-name>/references/` and update all backlinks.

### Pages Skipped: 3
- `index.md`, `log.md` — special files
- `_archives/*` — archived content
- `_readouts/*` — derived readouts (wiki-narrate output)

Step 7: ログとホットキャッシュを更新する

1 回のロックされた呼び出しで、ログとホットキャッシュを更新します（インデックスは影響を受けません — ページは作成されていません）:

obsidian-wiki memory sync CROSS_LINK \
  pages_scanned=<N> links_added=<M> typed_relations_written=<T> \
  pages_modified=<P> orphans_remaining=<Q> \
  misc_affinity_updated=<R> promotion_candidates=<S> \
  --takeaways "Cross-linked 23 mentions across 12 pages; 2 orphans remain."

index.md、log.md、hot.md を手動で編集しないでください — このコマンドは、並行ライターがあなたの更新を失うのを防ぐロックを取得します。

完全な手順は .skills/llm-wiki/references/MEMORY.md を参照してください。

Tips

• 毎回の取り込み後に実行してください。 新しいページはほとんどの場合、つながりが不十分です。これがその修正です。
• インラインリンクは控えめに。 すべての出現箇所ではなく、最初の自然な言及のみをリンクしてください。
• _archives/ または _readouts/ 内のページには触れないでください。 アーカイブは凍結されたスナップショットであり、readout は wiki-narrate からの派生出力であり、ナレッジページではありません。
• 既存の構造を尊重してください。 ページが ## Key Concepts セクションでリンクを丁寧に整理している場合は、別の ## Related を作成するのではなく、そのセクションに追加してください。
• エンティティページはリンクの磁石です。 jane-doe のようなエンティティは、ほぼすべてのプロジェクトページからリンクされるべきです。これらを優先してください。

Vault への書き込み後の QMD 更新

QMD は検索インデックスであり、信頼できる唯一の情報源ではありません。$QMD_WIKI_COLLECTION が空または未設定の場合は、この手順をスキップしてください。このスキルによって Vault の Markdown が新規作成または書き換えられた後にのみ実行してください。QMD の更新に失敗しても Vault の変更はロールバックせず、QMD の状態は別途報告してください。

$QMD_CLI が設定されている場合はそれを使用し、設定されていない場合は qmd を使用してください。

${QMD_CLI:-qmd} update

出力にベクトルが必要である、または埋め込みが古くなっている可能性があると示されている場合は、次を実行してください。

${QMD_CLI:-qmd} embed

次のいずれかの方法でコレクションを検証してください。

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

または、特定のページパスがわかっている場合は、次を実行してください。

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

次のいずれかを記録してください。

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>