canvas

Canvas

キャンバスは、Vault スコープの JSON Canvas ドキュメントとして扱います。読み取りは読み取り専用のままにし、要求された変更はすべて、復旧可能な 1 つのトランザクションを通じて行います。

Vault や現在の作業ディレクトリではなく、このスキル自体の場所からインストール済みの製品ルートを解決します。

PRODUCT_ROOT=/absolute/path/to/installed/claude-obsidian
CORE="$PRODUCT_ROOT/scripts/claude-obsidian.py"
test -f "$CORE"

このファイル内の ../wiki/references/ リンクはすべて、選択した Vault の wiki/ ディレクトリではなく、$PRODUCT_ROOT 配下にあるこのスキル自体のディレクトリを基準に、同じ方法で解決されます。

構文の参照元を選ぶ

形式の詳細には、別途インストールされた kepano/obsidian-skills の json-canvas スキルを優先します。利用できない場合は、references/canvas-spec.md を読みます。公開標準は JSON Canvas 1.0 です。

上流の構文スキルが利用できる場合でも、Vault のワークフローとトランザクションの安全性には、このスキルを使用します。

範囲

• 読み取りを行う前にユーザーの Vault を解決します。プラグインファイルから Vault を導き出してはいけません。
• ボードは wiki/canvases/ に保存します。ユーザーがボードを指定していない場合に限り、wiki/canvases/main.canvas をデフォルトとして使用します。
• wiki/canvases/_index.md は任意のカタログとして扱います。カタログがある場合は、新しいボードを同じトランザクションで追加します。既存のボード内のノードまたはエッジを編集する場合、カタログの変更は不要です。
• トランザクションエンジンが対応するのは、ファイルの作成と置換のみです。このスキルではボードファイルを削除または名前変更できません。ファイルの削除または名前変更のリクエストには、その制限を説明し、別途クリーンアップ計画を提示します。ホストのファイルツールで代用したり、名前変更を黙ってコピーに置き換えたりしてはいけません。
• file と background には Vault 相対パスを使用します。絶対パス、.. によるトラバーサル、ホームへのショートカット、シンボリックリンクを経由して外部に出るパスは拒否します。
• 参照できるのは、すでに Vault 内にあるファイル、または同じレビュー済みトランザクションで作成されたファイルのみです。任意のキャプチャまたはメディア機能が検出された場合は、それと連携し、返された Vault 相対パスを使用します。特定のプラグイン、コマンド、セッションログを前提にしてはいけません。また、このスキルでアセットをダウンロードまたはコピーしてはいけません。
• URL には link ノードを使用します。HTTPS URL のみ受け付けます。link ノードを使っても、ページを取得する許可が与えられるわけではありません。その JSON を作成するだけならリクエストは発生しませんが、Obsidian で開くと、その URL のホストから Open Graph メタデータが取得される場合があります。このレンダリング時の外部通信を開示し、許容できるか確認します。許容できない場合は、URL を含む text ノードを使用します。

読み取り専用の操作

ステータスまたは一覧のリクエストでは、選択した .canvas ファイルを解析し、ノード数、グループラベル、接続先が見つからないエッジ、存在しない Vault 相対ファイルの参照先を報告します。デフォルトのキャンバスがない場合は、その事実を報告し、作成プレビューを提示します。ステータスのリクエスト中に作成してはいけません。

変更案の作成

1. キャンバス全体と、対象となるカタログがあればその全体を読み取ります。各ファイルに期待される SHA-256 を記録します。存在してはいけないファイルには null を記録します。
2. 不明な JSON フィールドと既存の配列順序を保持します。ノード配列の順序は、下から上への Z 順です。
3. 要求されたノードまたはエッジの変更案を作成します。
   • 各ノードとエッジには一意の ID を付与します。ランダムな 16 文字の小文字の 16 進 ID を優先し、未使用であることを確認します。
   • すべてのノードに整数の x、y、width、height を必須とします。
   • JSON Canvas の定義どおりに text、file、link、または group を使用します。
   • すべての fromNode と toNode が、既存または新たに作成するノードを参照するようにします。
4. 新しいコンテンツは意図的に配置します。グループは視覚的なコンテナであり、親ではありません。内側の余白には 20 px、間隔には 40 px を使用し、必要に応じて次の行に折り返します。グループを拡張する場合はプレビューを提示します。
5. 最上位に nodes 配列と edges 配列を含む、有効な UTF-8 JSON としてシリアライズします。

最小限のノード例：

{
  "nodes": [
    {
      "id": "6f0ad84f44ce9c17",
      "type": "text",
      "text": "# Research map\n\nA concise orientation card.",
      "x": 0,
      "y": 0,
      "width": 400,
      "height": 180
    },
    {
      "id": "a1b2c3d4e5f67890",
      "type": "file",
      "file": "wiki/concepts/Contextual Retrieval.md",
      "x": 460,
      "y": 0,
      "width": 400,
      "height": 240
    }
  ],
  "edges": []
}

ノート、画像、PDF、その他の Vault ファイルには file を使用し、必要に応じて subpath: "#Heading" を指定します。url は link ノードでのみ使用します。JSON 文字列内の改行は、リテラルのバックスラッシュと n の組み合わせではなく、\n としてエスケープします。

プレビューと適用

プレビューを表示する前に、次の項目を検証します。

• JSON が解析でき、サポートされているノードタイプを使用していること。
• ID が一意で、エッジの両端が存在すること。
• 寸法が正の整数であること。
• ファイルと背景のパスが安全で、Vault 内の相対パスであり、ファイルが存在すること。
• 新しいノードが意図せず重なったり、指定されたグループからはみ出したりしないこと。

操作タイプが canvas の claude-obsidian.transaction.v1 バンドルを1つ作成します。 カタログに変更がある場合は、キャンバスとカタログを同じバンドルに含めます。 operation-transactions.md を読み、 適用する前にバンドルを確認します。

python3 "$CORE" transaction inspect BUNDLE --vault VAULT
# Set APPROVAL_SHA256 to the inspect result's approval_sha256 after review.
python3 "$CORE" transaction apply BUNDLE --vault VAULT \
  --approved-plan-sha256 "$APPROVAL_SHA256"

ノードやエッジの削除など、ボード内の破壊的な編集については、プレビューを提示した後、明示的な同意を得てください。これらの編集では、トランザクションエンジンを通じてボードファイルが置き換えられます。操作 ID、変更された正確なパス、ボード名、ノード ID、最終位置を報告してください。Git のコミットは行わないでください。