knowledge-graph

ナレッジグラフ

目標

提供されたソースを、エージェントがエンティティ、タイプ、関係性をたどれる永続的なグラフに変換します。以下のアーティファクトツリーを構築します。

entities/
  <entity-id>.md
relations.jsonl

ソースは読み取り専用として扱います。スコープ、言語、対象読者、詳細度についてはタスクの指示に従い、指示がない場合はソースで最も多く使われている言語を使用します。すべてのノード、重要な主張、エッジは、提供されたソースに根拠を置いてください。ソース自体がその領域で名前の付いた対象でない限り、ソースはドメインノードではなく、出典情報として扱います。

エンティティノード

人物、組織、グループ、動物、場所、製品、プロジェクト、システム、サービス、モジュール、データセット、標準、文書、アーティファクト、名前の付いたイベントなど、安定したアイデンティティまたは境界を持つ名前の付いた対象のノードを作成します。

各ノードは entities/<entity-id>.md に次の構造で保存します。

---
type: entity
id: 取经队伍
title: 取经队伍
entity_type: group
description: 由唐三藏率领、以西行取经为目标的行动团体。
aliases: [唐僧师徒, 师徒五众]
sources:
  - viking://resources/source.md
---

アーティファクトの種類には type: entity を使い、エンティティの意味上の分類には entity_type を使います。person、organization、group、animal、place、product、project、system、service、module、dataset、standard、document、artifact、event など、安定した小文字の snake_case 値を選びます。グラフを更新する際は、既存のタイプ語彙を再利用してください。フィルタリングや可視化が実質的に改善される場合に限り、より限定的なタイプを導入します。

description には、文脈に依存しない、安定したアイデンティティを示す1文を記述します。単一の出来事における行動、一時的な状態、ソース固有の意見、抽出履歴は description に含めないでください。エンティティのアイデンティティと説明を裏付ける正確なソース参照を、空ではない sources リストに記録します。このノード単位のリストは、主張ごとの根拠に代わるものではありません。

フロントマターに続けるMarkdownは、フィンガープリントを超える有用な情報を補う場合に限り、簡潔に記述します。該当する安定した属性、責任、インターフェース、境界、またはソースの範囲内の文脈を説明します。## Overview などのレベル2見出し、または出力言語での相当する見出しを使い、空のセクションは省略します。重要な主張を裏付ける正確なソースURI、リポジトリからの相対パス、または提供されたリンクを、その主張の近くに記載します。単一の出来事に関する事実や期間限定の事実は、安定した概要に含めないでください。明確に範囲を限定したコンテキストセクションに記載するか、イベントノードでモデル化します。

relations.jsonl に記載すべきエンティティ間の事実を、本文で重複させないでください。ノードにリテラル属性を含めるのは、それが有用で、かつ根拠がある場合に限ります。たとえば、チームのメンバー構成は、メンバーを列挙した文だけで表すのではなく、member_of エッジとして保存します。

ノードのアイデンティティは一貫性を保って選定します。

• 正規名を1つ選び、有用な別名は aliases に記録します。
• 安定した、パスに使用できるIDを作成します。ラテン文字の場合は小文字のケバブケースを優先し、他の文字体系では文字と数字を保持して、空白や句読点をハイフンに置き換えます。
• 正規名がラテン文字以外の文字体系で表記される新しいエンティティでは、その文字体系をIDとファイル名にも使用します。特に、出力言語と正規名が中国語の場合は、正規の中国語名をそのまま使用し、英語のIDに翻訳または音訳しないでください。
• id には .md を除いたファイル名を設定し、type は常に entity とします。
• 既存のノードが同じアイデンティティを表す場合は、確立済みのIDとパスを再利用します。ローカライズのために既存のIDを変更しないでください。ローカライズした表示名は title に設定します。
• 同名異義語には必要最小限の文脈を加えて区別し、異なるアイデンティティは別々のノードにします。
• 中心的、反復的、要求対象である、関係性が豊富である、またはソースの領域を理解するうえで重要なエンティティを優先します。
• ソースファイル、ディレクトリ、セクション、チャンクが存在するというだけの理由でノードを作成しないでください。名前の付いた契約、標準、出版物、報告書のように、そのアイデンティティと関係性がグラフ上で重要な場合に限り、ソース文書をドメインエンティティとして作成します。

広範なテーマ、属性、行動、関係を表す語句は、エンティティやエッジの説明に使い、単独のノードにはしないでください。

型付きエッジ

relations.jsonl に、1 行につき 1 つの有向エッジを記述します。

{"from":"孙悟空","relation":"member_of","label":"属于","to":"取经队伍","evidence":["viking://resources/source.md"]}

各行を <from> <relation> <to> というステートメントとして扱います。次のルールを適用します。

• from と to には、最終的なエンティティ ID を使用します。
• relation は、言語に依存しない、方向性のある、安定した小文字の snake_case 述語として表現します。たとえば、member_of、works_for、leads、created、depends_on、originates_from、located_in などです。同じ意味には、確立済みの述語を再利用します。
• label には、要求された出力言語で簡潔かつ人が読める関係の表現を設定します。中国語出力の場合は、任职于、属于、持有、位于 などの中国語ラベルを使用し、表示ラベルに英語の述語をそのまま使用しないでください。
• relation と label が同じ意味を表すようにします。ローカライズされたラベルがもっともらしく見えるというだけで、グループへの所属に works_for を使用したり、地理的な出身地に belongs_to を使用したり、ほかの広義の述語を使用したりしないでください。
• グラフ内で、各 relation 述語には一貫した label を使用します。既存のグラフを更新する場合は、述語コードを維持し、保持するエッジのうち label がないものにローカライズされたラベルを追加します。
• エッジを裏付ける、正確な出典参照を含む空でない evidence 配列を指定します。
• 重複する (from, relation, to) の組み合わせのエビデンスは、1 行にまとめます。
• 有用であり、出典に裏付けられる場合は、相互エッジまたは逆方向のエッジを追加します。
• 両方のエンドポイントが最終的なエンティティ集合に含まれるようにします。
• 配列で囲まず、簡潔な独立した JSON オブジェクトを出力します。
• 決定論的な出力となるよう、from、次に relation、次に to の順に行を並べます。

エッジの確立には、明示的な出典内の記述、または信頼できる出典資料によって示された挙動を使用します。同時に登場することは関係を見つける手掛かりとして扱い、その意味と方向が裏付けられてから関係を記述します。

独自の ID を持つ場合、または 3 人以上の参加者、資格、状態変化が不可欠な場合は、関係をノードとしてモデル化します。長い述語に意味を隠すのではなく、名称のある契約、合意、任命、取引、会議、イベントを中間ノードとして使用します。たとえば、当事者を party_to で名称のある合意に接続し、次にその合意を governs_use_of で規制対象のアーティファクトに接続します。アーティファクトに対して直接 signs_agreement とエンコードしないでください。

逆方向のエッジは選択的に使用します。探索性を高め、明確で一貫して再利用される述語がある場合にのみ追加し、すべてのエッジを機械的に反転させないでください。

出典情報

ドメイン知識と出典情報を区別します。

• エンティティの ID と安定した説明を確立するエビデンスには、各エンティティの sources リストを使用します。
• その正確なトリプルを裏付けるエビデンスには、エッジの evidence リストを使用します。
• Markdown 内の追加の主張を裏付けるエビデンスは、その主張の近くに配置します。
• 提供された URI、リポジトリ相対パス、リンク、利用可能なアンカーを正確に保持します。出典参照や場所を決して捏造しないでください。
• 出典参照は裏付けとして扱い、出典内のすべての記述が真実であるという保証として扱わないでください。出典間で食い違いがある場合は、矛盾、適用範囲、時系列、不確実性を維持します。
• 見出しのない 来源：... または Source: ... の行を出力しないでください。フロントマターの sources フィールドを、ページ単位のデフォルトの出典一覧とします。タスクで人が読める出典一覧が明示的に要求されている場合は、Markdown の箇条書きとして ## 来源 または ## Sources の下に一度だけ記載し、主張ごとのリンクを重複して記載しないでください。

表示に関する契約

識別子と表示を分けてください。ビジュアライゼーションやその他の人向け表示では、各ノードの id ではなく title を、各エッジの relation ではなく label を表示します。relation は機械処理用のキーとして扱い、label のない古いエッジを読み込む場合に限り、フォールバックとして使用します。ノードの形状、色、グループ化、フィルタリングには entity_type を使用します。出典とエビデンスは詳細パネルまたは検査ビューで参照できるようにし、通常のドメインノードとして表示しないでください。

ワークフロー

調査

情報源の種類、権威性、時系列、語彙、網羅範囲を確認します。段階的な更新を計画する前に、既存のエンティティ成果物と relations.jsonl を調べます。 コードの情報源については、エンティティの識別情報と関係を確立するために必要な関連マニフェスト、ドキュメント、公開コントラクト、スキーマ、テスト、エントリーポイント、実行時の配線、設定を調べます。

正規化

正規名、別名、候補 ID、識別の手がかり、意味上のエンティティ型、根拠、既存ノードとの一致をまとめた作業用セットを作成します。表記のバリエーションと真の同義語は統合します。情報源から十分な識別根拠が得られるまでは、曖昧な参照を未解決のままにします。

抽出

候補ノードごとに、安定したフィンガープリントと情報源に固有の事実を分けます。候補エッジごとに、始点ノード、終点ノード、正確な述語、根拠となる証拠を特定します。情報源で表現されている意味を保持する述語を選びます。文章を作成する前に、中間となるイベント、合意、文書、その他の関係ノードが必要な関係を特定します。

統合

正確な既存ノードとエッジを保持し、補完し合う根拠を統合して、新たなグラフの知識を追加し、提供されたより強い証拠または新しい証拠によって事実が更新されている場合は修正します。重複ノードを統合する場合は、影響を受けるすべてのエッジの終点を、存続するエンティティ ID に書き換えます。

変更のないノードには既存のパスを維持しながら、エンティティとリレーションの成果物一式を提出します。

品質チェック

完了前に、以下を確認します。

• すべてのノードが識別可能なエンティティを 1 つだけ表し、ファイルとフロントマターの ID が一致している。
• すべてのノードに、根拠のある entity_type、安定した description、空でない sources がある。
• 新たに作成した非ラテン文字の正規 ID がすべて情報源の言語規則に従い、既存の ID は維持されている。
• 正規 ID、別名、意味上の型がグラフ全体で一貫している。
• 重要な主張とエッジすべてに、適切な粒度で正確な提供済みの根拠がある。
• すべてのリレーションが、必須の JSONL スキーマ、正確な方向性を持つ述語、空でないローカライズ済み表示ラベルを使用している。
• すべての述語とラベルが意味的に同等であり、所属、雇用、出身、所有、包含が混同されていない。
• 繰り返し使われるリレーション述語ごとに、選択した言語で一貫したラベルが使われている。
• すべてのエッジの終点がエンティティノードを参照している。
• すべての中心的または選択されたエンティティが、根拠のあるエッジに少なくとも 1 つ参加している。ただし、情報源に関係がないと示され、孤立ノードを残すことに明確な有用性がある場合を除く。
• ノードの文章で説明されている重要なエンティティ間の関係がすべてエッジとして表現されており、中心的な複数当事者間の関係には適切な中間ノードが使われている。
• 重複するトリプルが統合され、リレーション行が決定的な順序で並べ替えられている。
• エンティティファイルに、見出しのない 来源：... または Source: ... の行が含まれていない。
• 最終成果物ツリーに、完全なエンティティ一式と relations.jsonl が含まれている。