graph-management

GraphOS スキル：graph-management

HTTP ファーストの API を通じて GraphOS グラフを読み取り、変更するための AI 操作可能なプロトコルです。

使用するタイミング

• グラフの構造、ノードの関係、選択中のノードのコンテキストを確認します。
• 書き込み操作の前に、利用可能なノードタイプを検証します。
• タイプスキーマが見つからない場合は、プラグインのランタイム状態を確認します。
• トランザクションのような動作で、整合性のある変更をまとめて適用します。

ランタイムのベース URL

デフォルトのローカルランタイム：

• http://localhost:3411

環境で異なるホストまたはポートを使用する場合は、それに応じてベース URL を置き換えてください。

Opencode サーバーの設定

GraphOS には、選択したグラフノードに関するプロンプトを処理するため、opencode サーバーに接続する AI Assistant パネルが Properties サイドバーに含まれています。

Opencode サーバーの起動

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

デフォルトでは、opencode serve は http://127.0.0.1:4096 でリッスンします。

GraphOS からブラウザー経由でアクセスするには、CORS を有効にします。

opencode serve --cors http://localhost:3000

環境変数

GraphOS の開発サーバーまたはビルドを実行する際に、環境変数を設定して opencode サーバーの URL を指定します。

変数	デフォルト	説明
VITE_OPENCODE_SERVER_URL	http://localhost:4096	実行中の opencode サーバーのベース URL

.env または .env.local での使用例：

VITE_OPENCODE_SERVER_URL=http://localhost:4096

AI アシスタントの使用方法

1. opencode を起動します：opencode（TUI モード）または opencode serve
2. GraphOS を起動します：npm run dev
3. グラフキャンバスでノードを選択します
4. Properties パネルを下にスクロールし、最下部にある AI Assistant セクションを開きます
5. Generate をクリックして、ノードの ID、タイプ、プロパティを含むプロンプトを自動生成します
6. 必要に応じてプロンプトを編集し、Run in Terminal（または Cmd+Enter）をクリックします

アシスタントは、実行するタスクを opencode ターミナルに送信します。

• ターミナルモード（デフォルト）：tui.appendPrompt と tui.submitPrompt を使用してタスクを opencode TUI に送信し、実行状況をすべて確認できるようにします。TUI が接続されていない場合は、session.prompt にフォールバックします。
• タスクは opencode ターミナルのセッションに表示されて実行され、すべてのツール呼び出しと応答をそこで確認できます。

API リファレンス

get_graph_description

計画と検証に使用する、グラフの完全なスナップショットを取得します。

• メソッド：GET
• パス：/api/graph/description
• クエリ：
  • graphId?: string
• 成功時のレスポンスに含まれる内容：
  • graph：id、name、nodeCount、edgeCount、rootNodeIds、leafNodeIds、selectedNodeId
  • nodes：AI に適したノードの説明
  • edges：エッジ ID を含むエッジの一覧
  • adjacency：ノードごとの親 ID／子 ID
  • aiSummary：自然言語による要約
• 代表的なエラー：
  • グラフが見つからない場合は 404

get_graph_node

フォーカスするノードと、そのローカルコンテキスト（親と子）を取得します。

• メソッド：GET
• パス：/api/graph/node
• クエリ：
  • graphId?: string
  • nodeId?: string
• 動作：
  • nodeId が省略された場合、サーバーはグラフと同期された選択中のノードにフォールバックします
• 成功時のレスポンスに含まれる内容：
  • graph：id、name、selectedNodeId
  • selectedNode
  • parentNodes
  • childNodes
  • aiSummary：フォーカスメタデータと naturalLanguage
• 代表的なエラー：
  • nodeId がなく、同期された選択中のノードも存在しない場合は 400
  • グラフまたはノードが存在しない場合は 404

get_available_node_types

プラグインによって登録されたノードタイプスキーマを一覧表示します。

• メソッド：GET
• パス：/api/node-types
• クエリ：なし
• 成功時のレスポンス：
  • ノードタイプ定義の配列（type、description、properties、inTypes、outTypes）

get_plugins

プラグインのランタイム状態を一覧表示します。

• メソッド：GET
• パス：/api/plugins
• クエリ：なし
• 成功時のレスポンス：
  • プラグイン状態オブジェクトの配列：
    • name
    • status
    • error
    • nodeTypeCount

apply_graph_transaction

呼び出し元から見て、グラフ操作のバッチをアトミックに適用します。

• メソッド：POST
• パス：/api/graph/apply
• 本文：
  • graphId?: string
  • ops: Operation[]

操作スキーマ：

• CREATE_NODE
  • metadata: { id, type, position: { x, y }, data? }
• UPDATE_NODE
  • metadata: { id, data }
• DELETE_NODE
  • metadata: { id }
• CONNECT
  • metadata: { id, source, target, sourceHandle?, targetHandle? }
• DISCONNECT
  • metadata: { id }

注意事項：

• ノードの検証は、登録済みのノードタイプのスキーマに基づいて実行されます
• CONNECT では、source と target のノードが存在している必要があります
• 重複するノード ID と重複するエッジは拒否されます
• DISCONNECT ではエッジ ID を使用します。通常は edge_ です

成功レスポンスには次の内容が含まれます：

• success、appliedCount、errorCount
• applied: string[]
• errors: { op, index, reason }[]
• 更新後の graph、nodes、edges
• aiSummary

手順

ステップ 1：制約と現在の状態を確認する

1. get_available_node_types を呼び出して、スキーマの制約を確認します。
2. get_graph_description を呼び出して、トポロジー全体を取得します。
3. 1 つのノード領域のみを操作する場合は、get_graph_node を呼び出してローカルのコンテキストを確認します。

完了チェック：

• 必要なノードタイプが存在している。
• 正確な source／target ID と、想定される差分を把握している。

ステップ 2：トランザクションを計画する

1. 関連するすべての操作をまとめた、一貫性のある apply_graph_transaction リクエストを作成します。
2. 依存関係が有効になるように操作の順序を決めます（接続の前に作成、削除の前に切断）。
3. 再試行を繰り返しても同じ結果になるよう、ID を安定した決定論的なものにします。

判断ポイント：

• ノードタイプが存在しない場合は、書き込みを再試行する前に get_plugins を確認します。
• 編集によってデータが失われるおそれがある場合は、操作を意図した範囲のみに絞ります。

完了チェック：

• トランザクションに必要な操作がすべて含まれており、冗長な変更がない。

ステップ 3：適用して検証する

1. apply_graph_transaction を送信します。
2. レスポンスの applied と errors を確認します。
3. get_graph_description を再実行して、適用後の状態を検証します。

判断ポイント：

• 一部のみ成功した場合は、バッチ全体を再実行せず、失敗した操作の意図だけを再試行します。
• 検証エラーが発生した場合は、再試行する前にペイロードをノードスキーマに合わせて修正します。

完了チェック：

• グラフトポロジーが、変更後に想定される状態と一致している。
• 未解決の重大なエラーが残っていない。

安全ルール

• 多数の細かな呼び出しではなく、一貫性のある 1 つのトランザクションを優先します。
• 送信前に、ノードのプロパティペイロードがノードタイプの要件を満たしていることを検証します。
• 破壊的な更新を行う場合は、まず現在のグラフを確認し、意図した操作のみを含めます。
• 一部のみの成功は通常どおり起こり得るものとして扱い、errors を確認して失敗した操作の意図だけを再試行します。
• *.graph.json ファイルを直接編集してはいけません。すべてのグラフの読み取りと変更は、このスキルで説明されている GraphOS API を通じて行う必要があります。

リクエスト例

例：グラフを読み取る

GET /api/graph/description?graphId=main

例：トランザクションを適用する

POST /api/graph/apply Content-Type: application/json

{ "graphId": "main", "ops": [ { "op": "CREATE_NODE", "metadata": { "id": "n_fetch", "type": "http.request", "position": { "x": 120, "y": 80 }, "data": { "properties": { "url": "https://example.com" } } } }, { "op": "CONNECT", "metadata": { "id": "edge_manual_n_fetch_n2", "source": "n_fetch", "target": "n2" } } ] }