Nereid MCP コラボレーション

ライブな共有TUI/MCPセッションでMermaidベースの図表をコラボレーションします。コンテキストを小さく保ち、編集を構造化し、注意を明示的にしてください。

コラボレーション契約

デフォルトでは共同存在を想定してください：

• ユーザーはTUI内で図表の更新をリアルタイムで見ることができます。
• ユーザーはエージェントがどこに注目しているかを見ることができます。
• エージェントは視覚的に注意を操舵し、その後簡潔に説明すべきです。

このステートモデルでコラボレーションを推進してください：

• attention.human.read: TUI内の人間カーソル/注意を読み取ります。
• attention.agent.read: エージェントスポットライトオブジェクトを読み取ります。
• attention.agent.set: エージェントスポットライトを1つのオブジェクトに移動させます。
• attention.agent.clear: エージェントスポットライトをクリアします。
• follow_ai.read / follow_ai.set: TUIがエージェントスポットライトを追従するかどうかを読み取る、またはトグルします。
• selection.read / selection.update: 共有ワーキングセット選択（複数オブジェクト）。

これらを別の関心事として扱ってください：

• 人間の注意：その人が見ている対象。
• エージェントの注意：エージェントが現在強調したい対象。
• 選択：バッチ推論/編集用の短期ワーキングセット。
• Follow-AI：TUIカメラ/カーソルがエージェントスポットライトを追従するかどうか。

コア原則

• ASTを真実の源として扱い、レンダリングテキストとMermaidテキストは投影です。
• セッションファイル（nereid-session.meta.json、diagrams/*.mmd、walkthroughs/*.wt.json）はアプリ管理スナップショットであり、Nereid実行中に頻繁に上書きされることがあります。
• 標準的なObjectRefをどこでも使用してください： d:<diagram_id>/<seq|flow>/<participant|message|node|edge>/<object_id>。
• 小さな読み取りから始めることを優先してください（diagram.stat、diagram.get_slice、diagram.diff、walkthrough.diff）。
• 大規模なスナップショットの前に、型付きクエリツール（seq.*、flow.*、xref.*、route.find）を使用してください。
• base_revで編集をゲートし、操作を最小限に保ってください。
• 参照として証拠を記録し（xrefとウォークスルーノード）、推論が再開可能になるようにしてください。
• 明示的に削除を求められない限り、ぶら下がったxrefをTODOアーティファクトとして可視化し続けてください。

実行規律

• MCPツールを唯一の真実の源として使用してください。
• ランタイムコラボレーション質問に答えるためにsrc/、tests/、docs/、data/を検査しないでください。
• ユーザープロンプトを読んだ直後に最初の関連MCPコールを行ってください。
• スキーマ/コード探索よりも直接的なMCP実行を優先してください。
• ペイロード形状が不明な場合は、ツールを1回呼び出し、バリデーションエラーから適応してください。
• ユーザーが明示的にファイルレベルの検査またはストレージデバッグを求めた場合にのみ、シェル/ファイルプローブを使用してください。

ツールグループ

• 図表ライフサイクルと対象：diagram.list、diagram.open、diagram.delete、diagram.current、diagram.create_from_mermaid
• 図表読み取り：diagram.stat、diagram.get_slice、diagram.diff、diagram.read、diagram.get_ast、diagram.render_text
• 図表変更：diagram.propose_ops、diagram.apply_ops
• ウォークスルーライフサイクルと対象：walkthrough.list、walkthrough.open、walkthrough.current
• ウォークスルー読み取り：walkthrough.stat、walkthrough.diff、walkthrough.read、walkthrough.get_node、walkthrough.render_text
• ウォークスルー変更：walkthrough.apply_ops
• コラボレーション状態：attention.human.read、attention.agent.read、attention.agent.set、attention.agent.clear、follow_ai.read、follow_ai.set、selection.read、selection.update、view.read_state
• 図表間マッピング：xref.list、xref.neighbors、xref.add、xref.remove
• オブジェクト検査：object.read
• クエリヘルパー（ルート）：route.find
• クエリヘルパー（シーケンス）：seq.messages、seq.search、seq.trace
• クエリヘルパー（フロー）：flow.reachable、flow.paths、flow.cycles、flow.unreachable、flow.dead_ends、flow.degrees

デフォルト操作ループ

1. ターゲットを解決：
   • diagram.current -> diagram.list -> diagram.open。
   • walkthrough.current -> walkthrough.list -> walkthrough.open。
   • 図表がまだ存在しない場合は、diagram.create_from_mermaidでブートストラップしてください。
2. ライブコラボレーション状態を読み取り：
   • attention.human.read、attention.agent.read、follow_ai.read、selection.read。
3. ローカルコンテキストをプローブ：
   • diagram.stat、diagram.get_slice、その後1〜2つの型付きクエリ。
4. 視覚的注意を操舵：
   • attention.agent.setを現在議論中のオブジェクトに設定してください。
   • 注意マーカーが微視的ガイダンスを担う間、チャットは短く保ってください。
5. 最小限の編集を提案して適用：
   • diagram.propose_ops -> diagram.apply_ops。
   • ウォークスルー改善のためにwalkthrough.apply_opsを実行してください。
6. デルタで更新：
   • diagram.diff / walkthrough.diff（必要な場合を除き完全な再読み込みは避けてください）。

ライブ共同存在ルール

• スポットライト優先通信を使用：変更を説明する前にattention.agent.setを設定してください。
• トピックを変更するときはスポットライトを移動し、完了時にクリアしてください。
• ユーザーが積極的に図表を見ている場合は、ナレーションをコンパクトに保ってください。
• 向きが必要でない場合は、クエリのみの回答ではスポットライトの変更をスキップしてください。
• selection.updateをフォーカスプロキシではなく、一時的な複数オブジェクトワーキングセットに使用してください。
• 作成/切り替え専用リクエストの場合、diagram.create_from_mermaid（およびオプションのattention.agent.set）の後に停止してください。ユーザーが検査/デバッグを求めない限り、余分なdiagram.stat、diagram.render_text、またはflow.*プローブを避けてください。

ツール契約（入力/出力）

diagram.create_from_mermaid

入力：

{
  "mermaid": "flowchart TD\n  A --> B",
  "diagram_id": "d-my-flow",
  "name": "My Flow",
  "make_active": true
}

出力：

{
  "diagram": {
    "diagram_id": "d-my-flow",
    "name": "My Flow",
    "kind": "flowchart",
    "rev": 0
  },
  "active_diagram_id": "d-my-flow"
}

diagram.delete

入力：

{
  "diagram_id": "d-my-flow"
}

出力：

{
  "deleted_diagram_id": "d-my-flow",
  "active_diagram_id": "d-next"
}

diagram.get_slice

入力：

{
  "diagram_id": "d-flow",
  "center_ref": "d:d-flow/flow/node/n:a",
  "radius": 1,
  "depth": 1,
  "filters": {
    "include_categories": ["flow/node", "flow/edge"],
    "exclude_categories": []
  }
}

出力：

{
  "objects": ["d:d-flow/flow/node/n:a", "d:d-flow/flow/node/n:b"],
  "edges": ["d:d-flow/flow/edge/e:ab"]
}

diagram.apply_ops

入力：

{
  "diagram_id": "d-seq",
  "base_rev": 3,
  "ops": []
}

出力：

{
  "new_rev": 4,
  "applied": 1,
  "delta": { "added": [], "removed": [], "updated": [] }
}

walkthrough.apply_ops

入力：

{
  "walkthrough_id": "w:1",
  "base_rev": 0,
  "ops": []
}

出力：

{
  "new_rev": 1,
  "applied": 1,
  "delta": { "added": [], "removed": [], "updated": [] }
}

object.read

入力：

{ "object_ref": "d:d-seq/seq/block/b:0000" }

出力：

{
  "objects": [
    {
      "object_ref": "d:d-seq/seq/block/b:0000",
      "object": {
        "type": "seq_block",
        "kind": "alt",
        "header": "guard",
        "section_ids": ["sec:0000:00", "sec:0000:01"],
        "child_block_ids": []
      }
    },
    {
      "object_ref": "d:d-seq/seq/section/sec:0000:00",
      "object": {
        "type": "seq_section",
        "kind": "main",
        "header": "ok",
        "message_ids": ["m:0000"]
      }
    }
  ],
  "context": {}
}

attention.human.read

入力：

{}

出力：

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize",
  "diagram_id": "d-auth-flow"
}

attention.agent.read

入力：

{}

出力：

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize",
  "diagram_id": "d-auth-flow"
}

attention.agent.set

入力：

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize"
}

出力：

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize",
  "diagram_id": "d-auth-flow"
}

attention.agent.clear

入力：

{}

出力：

{
  "cleared": 1
}

follow_ai.read

入力：

{}

出力：

{
  "enabled": true
}

follow_ai.set

入力：

{
  "enabled": true
}

出力：

{
  "enabled": true
}

selection.update

入力：

{
  "object_refs": [
    "d:d-auth-flow/flow/node/n:start",
    "d:d-auth-flow/flow/node/n:authorize"
  ],
  "mode": "replace"
}

出力：

{
  "applied": [
    "d:d-auth-flow/flow/node/n:authorize",
    "d:d-auth-flow/flow/node/n:start"
  ],
  "ignored": []
}

チャート上のプローブ・アンド・リファイン

浅い型付き探索ループを使用してください：

1. 1つのオブジェクトに固定（attention.human.readまたは明示的なobject_ref）。
2. diagram.get_sliceでローカル構造を取得。
3. 1つの型付き質問を提起（seq.*、flow.*、xref.*、route.find）。
4. 必要に応じてエージェントスポットライトを次のオブジェクトに移動。
5. 曖昧性が解決されるまで繰り返す。

ローカルプローブが不十分な場合にのみ、グローバル読み取り（diagram.read、diagram.get_ast、diagram.render_text）にエスカレートしてください。

変更規律

• 非自明な編集の場合、diagram.apply_opsの前にdiagram.propose_opsを使用してください。
• 操作バッチを最小限にし、1つのローカル意図にスコープしてください。
• すべての新しいオブジェクトに安定したIDを使用してください。
• 適用後にdiagram.statまたはdiagram.diffを再読み込みして、結果のリビジョン/状態を確認してください。

ウォークスルーと証拠アーティファクト

再開可能なパンくずとしてウォークスルーを構築してください：

• 証拠参照（refs）を含む簡潔なノードを追加。
• ノードタイトルは短く保ち、詳細はbody_mdに記載。
• 理解が増すにつれてノードを段階的にリンク。
• 最初から再導出する代わりに、編集後にウォークスルーを更新。

xrefを使用して図表間セマンティクスを保存してください：

• 実装/拡張リンクの場合はxref.add。
• マップとトラバーサルの場合はxref.listとxref.neighbors。
• ぶら下がったxrefを明示的に表示してフォローアップ。

競合回復

base_revが古いため変更が失敗した場合：

1. 最後に既知のリビジョンからdiagram.diffまたはwalkthrough.diffを呼び出し、
2. 操作をcurrent_revにリベース、
3. 更新されたbase_revで再試行。

差分履歴ウィンドウが枯渇した場合は、新しいスナップショット（diagram.readまたはwalkthrough.read）を取得し、デルタ優先フローを再開してください。

レポート規律

ユーザーが必要とする内容のみをレポートしてください：

• ターゲット（diagram_id/walkthrough_id）およびリビジョン移動（base_rev -> new_rev）を含める、
• 簡潔なデルタと主要参照を含める、
• リクエストされない限り完全なAST/テキストダンプを避ける、
• ライブセッションでは、TUIで既に見えるマイクロステップすべてをナレーションすることを避けてください。

MCPプレイブック同付録

ペイロードテンプレート追加の場合はreferences/mcp-playbooks.mdを参照してください。このファイルを主要なプロトコルと動作契約として保ってください。