ライブとヘッドレス

呼び出しのたびに、サーバーはエディタが ~/.erd-editor/ide/ に置くロックファイルを通じて、ドキュメントを保持しているエディタを探します。 ERD Editor を入れた VS Code のウィンドウと Obsidian の保管庫のウィンドウはそれぞれ 1 つずつロックファイルを置き、JetBrains IDE は IDE 全体で 1 つを置いて、そこで開いているすべてのプロジェクトを列挙します。 エディタは閉じるときにロックファイルを削除します。 サーバーが何を見つけるかによって、編集の行き先が決まります。

見つかったもの	編集の動作
ワークスペース、保管庫、開いているプロジェクトのいずれかにドキュメントを含むか、ドキュメントを開いているエディタ	ライブ。 必要に応じて ERD Editor でドキュメントを開き、編集セッションに参加して、そこで変更を適用します。編集はすぐに表示され、エディタがユーザー自身の編集を保存するのと同じように保存されます。保存を参照してください。
エディタなし	ヘッドレス。 ファイルを読み込み、変更を適用して、ファイルを置き換えます。erd_save ですることはありません。
ハブがオフのエディタ	拒否。 読み取りはディスクから引き続き行えます。開いているエディタの下でファイルに書き込んだ変更は次の保存で上書きされるおそれがあるため、サーバーは何も書き込みません。
ハブはオンでも、サーバーとは異なるプロトコルを使うエディタ。サーバー 1.0.0 に対しては VS Code の拡張機能 3.x、Obsidian のプラグイン 0.x、JetBrains のプラグイン 0.9.0 または 0.10.0、1.0.0 より前のサーバーに対しては拡張機能 4.0.0 以降またはプラグイン 1.0.0 以降です	拒否。 読み取りも含めて protocolMismatch で拒否されます。メッセージには、更新が必要な側として、拡張機能またはプラグインか、サーバーが示されます。アップデートを参照してください。
Windows で、同じファイルを別のパスで保持しているエディタ。エージェントがこのコンピューターのネットワーク共有や割り当てたネットワークドライブ（\\localhost\C$\… など）を通じて指定し、エディタはドライブのパスで保持している場合、またはその逆の場合です	拒否。 読み取りも含めて invalidPath で拒否されます。メッセージには、エディタがドキュメントを保持しているパスが示されます。そのパスでもう一度呼び出してください。
Windows で、Windows がエージェントを接続させないエディタ。エージェントが管理者として起動されていないときに管理者として起動したエディタ、またはエージェントがサンドボックス内で動作しているときのすべてのエディタです	拒否。 読み取りも含めて hubUnreachable で拒否され、メッセージにその理由が示されます。エディタとエージェントを同じ権限で実行してください。例えば、エディタを管理者権限なしで起動し直します。

編集の結果には実行したモード live または headless が示され、拒否された編集にはその理由が示されます。 検索は呼び出しのたびにやり直されるため、エディタを開いたり閉じたりすると、次の呼び出しもそれに合わせて切り替わります。

複数のエディタがドキュメントを保持している場合は、ドキュメントを開いているエディタが、ドキュメントを含むフォルダを扱っているだけのエディタより優先され、フォルダを扱っているエディタの中では、フォルダが最も深い階層にあるエディタが優先されます。 どちらもドキュメントを開いている 2 つのエディタのように優先度が並んだ場合は、ロックファイルが最後に変更されたエディタが選ばれます。 そのため、VS Code のワークスペースのフォルダ内にある Obsidian の保管庫のドキュメントは、VS Code がそれを開いていて Obsidian が開いていない場合を除き、Obsidian が扱います。

1 つのドキュメントへの呼び出しは、サーバーに届いた順に 1 つずつ実行されます。異なるドキュメントへの呼び出しは並行して実行されます。

ライブ

エージェントは、共同編集の参加者がもう 1 人増えたかのようにエディタに加わります。 エージェントの編集はドキュメントを開いているすべてのエディタにすぐに届き、編集中のテーブルとセルには、共同編集の参加者と同じようにエージェントのフォーカスが描画されます。focusTracker を参照してください。

読み取りでエディタが開くことはありません。編集は、ドキュメントがまだ開かれていなければ、キーボードフォーカスを奪わずに ERD Editor で開きます。

保存

各エディタは、エージェントの編集をユーザー自身の編集と同じ方法で保存します。

VS Code では、エージェントの編集はユーザー自身の編集と同じようにタブを未保存の状態にし、ドキュメントが保存されたときにだけディスクに書き込まれます。 erd_save は、VS Code 自身の保存コマンドと同じように VS Code を通じて保存します。代わりにユーザーが Ctrl + S (Windows/Linux) または ⌘ + S (Mac) で保存することもできます。 エージェントの未保存の編集が残ったままエディタを閉じると、ほかの未保存の変更と同じように、保存するかどうかを尋ねられます。

Obsidian は、編集が止まってから約 2 秒後にエージェントの編集を保存し、タブを閉じると確認せずに保存します。 JetBrains IDE は、編集が止まってから 1 秒足らずでそれらを書き込み、タブを閉じるとまだ書き込まれていない分を書き込みます。タブが変更ありと表示されることはありません。 どちらでも、erd_save はそれらをすぐに書き込みます。

erd_save はまず、エージェントが行ったすべての編集をエディタが保持するまで、最大 2 秒待ちます。 エディタがそれを確認できなかった場合や、ファイルを書き込まなかった場合は、notSaved で拒否されます。ディスク上のファイルが変更されたために VS Code がタブを未保存のままにした場合や、ダイアログが開いていたときやファイルが書き込み不可のときなどに JetBrains IDE が書き込めなかった場合です。

VS Code と JetBrains IDE では、保存するものが残っていないドキュメントへの erd_save は成功し、ファイルはそのまま残ります。 すべての編集が保存された後（JetBrains IDE は自動で保存します）がこれに当たり、その後の変更がすべて、Viewport をロックした状態でのスクロールや拡大・縮小、Canvas Type をロックした状態でのタブの切り替えのように、ロックによってファイルに反映されない変更である間は、その状態が続きます。ロックは既定ですべてオンです。 JetBrains IDE が書き込めないファイルは、その場合でも拒否されます。

エージェントの最後の編集の後にエディタがドキュメントを閉じると、エージェントの次の呼び出しには、エディタが閉じる前に保存された場合に限りそれらの編集がファイルに入っている、という注記が付きます。

Undo

erd_undo はエージェントが行った最後の編集を元に戻し、ユーザーの編集は元に戻しません。erd_redo はそれを再び適用します。 エディタ自身の Undo は逆に働きます。ほかのエディタから届いた変更は自分の履歴に記録されないため、ユーザーの編集を元に戻し、エージェントの編集は元に戻しません。

いくつかの編集は、エディタに Undo の項目を作りません。設定のツールのうちの erd_set_database と erd_set_database_name、そして erd_resize_memo です。 横方向と縦方向の移動量の合計が 20 ピクセル未満となる erd_move_table_group も項目を作りませんが、グループは移動した位置のままです。 何も変えない呼び出しも項目を作りません。ドキュメントがすでに持っている値を設定する erd_set_column_primary_key、erd_set_column_unique、erd_set_column_not_null、erd_set_column_auto_increment、erd_set_index_unique、erd_set_index_column_order、すでにインデックスにあるカラムを指定した erd_add_index_column、すでにそのグループに属しているテーブルを指定した（groupId が null の場合は、すでにどのグループにも属していないテーブルを指定した）erd_set_table_group、グループがすでにある位置への erd_move_table_group、グループがすでに持っている矩形への erd_resize_table_group、テーブルのないドキュメントへの erd_sort_tables、テーブルを 1 つも持ち込まない、mode が append の読み込み（erd_import_json の場合は、テーブルもメモも持ち込まないもの）です。 erd_undo はこれらを飛ばし、結果にその名前を示します。 erd_change_relationship_type、erd_change_relationship_on_delete、erd_change_relationship_on_update、erd_change_table_group_name、erd_change_table_group_color、erd_set_ddl_script など、ほかの編集は、ドキュメントがすでに持っている値を設定するときでも項目を作ります。

エージェントの Undo の履歴は、次の場合に終わり、結果に注記が付きます。

• エージェントがドキュメントに再び参加したとき。例えば、エディタがエージェントをドキュメントから切り離した後です。
• エディタが終了するか、ドキュメントを閉じてそれを扱わなくなり、エージェントがディスク上のファイルの編集を続けるとき。
• エージェントがディスク上で編集していたドキュメントを、エディタが引き継いだとき。

また、エージェントが 30 分間呼び出していないドキュメントはサーバーが閉じ、Undo の履歴もそれとともに、注記なしで失われます。

エディタがなくなったとき

エディタがドキュメントを保持している間、サーバーが自分からファイルの編集に切り替えることはありません。 接続が切れた場合は再接続します。 エディタが終了したときか、ドキュメントを閉じて、そのドキュメントもそれを含むフォルダも列挙しなくなったときにだけ、サーバーはファイルを編集し、そのことを結果に示します。 これは、エディタが扱うどのフォルダにも含まれないダイアグラムを閉じたとき（VS Code では、ワークスペースの外から開いたダイアグラム）、Obsidian で ERD Editor プラグインを無効にしたとき、JetBrains IDE でドキュメントを含むプロジェクトを閉じたときやそこでプラグインを無効にしたときに起こります。 エディタが扱うフォルダ内のダイアグラムは、閉じてもエディタのもとに残り、エージェントの次の編集で再び開かれます。

動作はしているものの、ロックファイルがなくなり、ドキュメントを閉じないまま接続が切れたエディタは、次の編集を hubGone で拒否します。 メッセージには、ドキュメントを解放する方法が示されます。VS Code ではそのウィンドウを再読み込みするか、閉じてエージェントがファイルを直接編集できるようにします。Obsidian では ERD Editor プラグインを再び有効にするか、そのウィンドウを閉じます。JetBrains IDE ではプラグインを再び有効にするか、IDE を終了します。

次の 2 つの場合、読み取りは代わりにディスク上のファイルを読み、エディタでまだ保存されていない編集は含まれない、という注記を付けます。ドキュメントを保持しているエディタのハブがオフの場合と、上記の hubGone の場合です。 エディタのハブに接続できない読み取りは、編集と同じように hubUnreachable で拒否されます。

ヘッドレス

ドキュメントを扱うエディタがない場合、各編集はファイルを読み込み、変更を適用して、ファイルに書き戻します。 書き込みはドキュメントの隣にある .<name>.<id>.tmp という名前の一時ファイルに対して行われ、その後そのファイルがドキュメントを置き換えるため、ドキュメントが書きかけの状態で残ることはありません。ただし、後述する Windows でその場に書き込む場合は例外です。

最後の手順の前に、サーバーは呼び出しの間にディスク上のファイルが変更されたかどうかを確認します。 変更されていた場合は何も書き込まず、ファイルを読み込み直して、呼び出しを conflict で拒否します。エージェントはもう一度呼び出します。 2 つの呼び出しの間に変更されたファイルは単に読み込み直され、それ以前のエージェントの Undo の履歴は破棄されます。

読み取り専用のファイルはそのまま残され、編集は readonly で拒否されます。所有者に書き込み権限のないファイルや、Windows で読み取り専用属性が付いたファイルで、例えばチェックアウトしていない Perforce や TFVC のファイルです。 書き込み可能にしてから、もう一度呼び出してください。読み取りは引き続き行えます。

エージェントがディスク上で編集している間にエディタがそのドキュメントを扱い始めると、その 1 回の編集は hubAppeared で拒否され、何も書き込まれません。次の呼び出しはエディタを通じて編集します。

Windows では、さらに 2 つの規則が適用されます。

• フォルダとは異なる独自のアクセス許可を持つドキュメントは、それを保つために置き換えではなくその場で書き込まれ、一時ファイルは後で削除されます。その書き込みの間にドキュメントを読んだプログラムは、解析できないテキストを目にすることがあります。
• ほかのプログラムが開いているファイルは置き換えられないため、サーバーは最大 2 秒間再試行します。試行のたびにまずエディタを探し直し、その間にドキュメントを扱い始めたエディタがあれば、書き込みは hubAppeared で、そのハブがオフなら blocked で拒否されます。2 秒経ってもファイルが開かれたままなら何も書き込まず、ファイルを読み込み直して、システムのエラーを引用したメッセージとともに呼び出しは失敗します。

拒否

VS Code のウィンドウは、ハブがオフでもロックファイルを保持します。dineug.erd-editor.agentHub.enabled がオフの場合、ワークスペースが信頼されていない場合、ハブが待ち受けできなかった場合です。 Obsidian の保管庫のウィンドウは、Coding agents がオフの場合と、ハブが待ち受けできなかった場合に、ハブがオフのままロックファイルを保持します。 JetBrains IDE は、Coding agents がオフの場合、ハブが待ち受けできなかった場合、IDE の終了中に、ハブがオフのままロックファイルを保持します。

そのようなドキュメントへの編集は blocked で拒否されます。ファイルに書き込んだ変更は、開いているエディタが次に保存するときに上書きしてしまうおそれがあるためです。 読み取りは、ディスク上のファイルから引き続き行えます。

エージェントが編集できるようにするには、そのエディタについてメッセージが示すとおりにハブをオンに戻します。VS Code ではワークスペースを信頼して設定をオンにするか、ウィンドウを再読み込みします。Obsidian では Coding agents をオンにするか、Obsidian を再読み込みします。JetBrains IDE では Coding agents をオンにするか、すでにオンなら IDE を再起動します。

JetBrains IDE は、信頼していないプロジェクトだけが保持しているドキュメントの変更も、hubDisabled で拒否します。 そのようなドキュメントもエージェントは読み取ることができ、erd_list_documents はそれを readonly として一覧表示します。プロジェクトを信頼してから、もう一度呼び出してください。

ロックファイルを置かないエディタは何も保護しないため、ダイアグラムがそこで開いていても、エージェントはディスク上のファイルを編集します。 Linux で Flatpak としてインストールした Obsidian や JetBrains IDE、JCEF のない JetBrains IDE、ハブを起動できなかった JetBrains IDE がこれに当たります。Obsidian の設定とJetBrains IDE の設定を参照してください。 3.0.0 より前の VS Code の拡張機能と 0.9.0 より前の JetBrains のプラグインも、ハブを持たないため、ロックファイルを置きません。

ドキュメント

ドキュメントは path で指定します。絶対パス、またはサーバーの作業ディレクトリからの相対パスです。

• 新しいドキュメントは .erd.json です。erd_open_document に create を付けるとファイルを作成し、拡張子のない名前には .erd.json を付けます。エディタの新しいダイアグラムと同じように、新しいドキュメントではすべてのロックがオンになっているため、エディタでスクロール、拡大・縮小、タブの切り替えをしたり、Code Generator の別の言語、名前のケース、括弧の種類を選んだりしても、ファイルが変わることはありません。ロックを個別にオンまたはオフにするツールはなく、それはエディタの設定タブで行います。replace モードの erd_import_json は、すべてのロックを読み込むドキュメントのロックに置き換えます。読み込みを参照してください。
• 既存の .erd、.vuerd、.vuerd.json ファイルも開けます。それ以外の拡張子のパスは invalidPath で拒否されます。
• Windows では、Windows が指定どおりに保存しない名前を含むパスは、読み取りも含め、ドキュメントを読み書きする前に invalidPath で拒否されます。orders:v2.erd のようにコロンなど Windows が受け付けない文字を含む名前、大文字・小文字を問わず NUL.erd や CON.erd のようなデバイス名、ドットやスペースで終わる名前です。例えば : の代わりに - を使うなどして、名前を変更してください。
• マージコンフリクトのマーカーが残ったファイルなど、エディタが読めるドキュメントではないファイルは invalidDocument で拒否され、そのまま残されます。空のダイアグラムとして読み込まれて書き戻されることはありません。

エージェントはツールを通じてのみドキュメントを変更し、ファイルを自分で書き換えないよう指示されています。

erd_list_documents は、ドキュメントを path、open、active、dirty、readonly とともに一覧表示します。 作業ディレクトリを扱うエディタ（ドキュメントの場合と同じ方法で選ばれます）に問い合わせ、そこで開いているダイアグラム、続いてそのエディタが扱う ERD ファイルを一覧表示します。VS Code のウィンドウのワークスペースのフォルダ、Obsidian の保管庫、JetBrains IDE で開いているすべてのプロジェクトにある ERD ファイルです。 それ以外の場合は作業ディレクトリ以下の ERD ファイルを一覧表示し、読み取り専用のファイルには readonly が付き、Windows では Windows が指定どおりに保存しない名前は除外されます。