라이브와 헤드리스

서버는 호출마다 에디터가 ~/.erd-editor/ide/에 남기는 잠금 파일을 통해 문서를 담고 있는 에디터를 찾습니다. ERD Editor가 있는 VS Code 창과 Obsidian 볼트 창은 각각 잠금 파일을 하나씩 남기고, JetBrains IDE는 IDE 전체에 하나를 남기며 그 안에 열린 모든 프로젝트를 나열합니다. 에디터는 닫힐 때 잠금 파일을 제거합니다. 서버가 무엇을 찾느냐에 따라 편집이 적용되는 곳이 정해집니다.

찾은 것	편집의 동작
워크스페이스, 볼트, 열려 있는 프로젝트에 문서가 포함되어 있거나 문서를 열어 둔 에디터	라이브. 필요하면 문서를 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가 표시되며, 거부된 편집은 그 이유를 알려 줍니다. 탐색은 호출마다 다시 실행되므로, 에디터를 열거나 닫으면 다음 호출도 그에 따라 옮겨 갑니다.

둘 이상의 에디터가 문서를 담고 있으면, 문서를 열어 둔 에디터가 문서가 있는 폴더를 담당하기만 하는 에디터보다 우선하고, 폴더를 담당하는 에디터끼리는 폴더가 가장 깊은 곳에 있는 에디터가 우선합니다. 두 에디터가 모두 문서를 열어 둔 경우처럼 우열이 가려지지 않으면, 잠금 파일이 가장 최근에 바뀐 에디터가 우선합니다. 따라서 VS Code 워크스페이스 폴더 안의 Obsidian 볼트에 있는 문서는, VS Code는 문서를 열어 두었고 Obsidian은 열어 두지 않은 경우가 아니라면 Obsidian으로 갑니다.

한 문서에 대한 호출은 서버에 도착한 순서대로 하나씩 실행됩니다. 서로 다른 문서에 대한 호출은 나란히 실행됩니다.

라이브

에이전트는 참여자 한 명이 더 들어오듯 에디터에 합류합니다. 에이전트의 편집은 그 문서를 연 모든 에디터에 곧바로 전달되고, 참여자의 포커스와 마찬가지로 에이전트가 편집 중인 테이블과 셀에 에이전트의 포커스가 그려집니다. focusTracker 문서를 참고하세요.

읽기는 에디터를 열지 않습니다. 편집은 문서가 아직 열려 있지 않으면 키보드 포커스를 가져가지 않은 채 ERD Editor에서 엽니다.

저장

각 에디터는 사용자의 편집을 저장하는 방식대로 에이전트의 편집을 저장합니다.

VS Code에서 에이전트의 편집은 사용자의 편집처럼 탭을 저장되지 않은 상태로 표시하며, 문서가 저장될 때에만 디스크에 반영됩니다. erd_save는 VS Code 자체의 저장 명령과 마찬가지로 VS Code를 통해 문서를 저장합니다. 사용자가 대신 Ctrl + S (Windows/Linux) or ⌘ + 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도 Undo 항목을 만들지 않으며, 그래도 그룹은 옮겨진 자리에 그대로 있습니다. 아무것도 바꾸지 않는 호출도 Undo 항목을 만들지 않습니다. 문서가 이미 가진 값으로 설정하는 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, 테이블을 하나도 가져오지 않는(erd_import_json은 테이블도 메모도 가져오지 않는) mode가 append인 가져오기입니다. 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 항목을 만듭니다.

에이전트의 Undo 히스토리는 다음과 같은 경우 결과에 안내를 남기고 끊깁니다.

• 예를 들어 에디터가 문서에서 에이전트를 내보낸 뒤처럼, 에이전트가 문서에 다시 참여할 때.
• 에디터가 종료되거나 문서를 닫고 더 이상 담당하지 않아서, 에이전트가 디스크의 파일을 이어서 편집할 때.
• 에이전트가 디스크에서 편집하던 문서를 에디터가 넘겨받을 때.

서버는 에이전트가 30분 동안 호출하지 않은 문서도 닫으며, 이때 Undo 히스토리도 안내 없이 함께 사라집니다.

에디터가 사라졌을 때

에디터가 문서를 담고 있는 동안 서버는 스스로 파일 편집으로 넘어가지 않습니다. 연결이 끊기면 다시 연결합니다. 에디터가 종료되었거나, 문서를 닫고 그 문서나 문서가 있는 폴더를 더 이상 나열하지 않을 때에만 서버가 파일을 편집하며, 결과에 그 사실을 알립니다. 담당하는 모든 폴더 바깥에 있는 다이어그램(VS Code에서는 워크스페이스 바깥에서 연 다이어그램)을 닫을 때, Obsidian에서 ERD Editor 플러그인을 끌 때, JetBrains IDE에서 문서가 있는 프로젝트를 닫거나 플러그인을 끌 때 이런 일이 일어납니다. 에디터가 담당하는 폴더 안의 다이어그램은 닫혀도 그 에디터에 남으며, 에이전트의 다음 편집이 다시 엽니다.

아직 실행 중이지만 잠금 파일이 사라졌고, 문서를 닫지 않은 채 연결이 끊긴 에디터는 다음 편집을 hubGone으로 거부합니다. 메시지에 문서를 풀어 주는 방법이 나옵니다. VS Code에서는 그 창을 다시 로드하거나 창을 닫아 에이전트가 파일을 직접 편집하게 하고, Obsidian에서는 ERD Editor 플러그인을 다시 켜거나 그 창을 닫고, JetBrains IDE에서는 플러그인을 다시 켜거나 IDE를 종료합니다.

다음 두 경우에는 읽기가 대신 디스크의 파일을 읽으며, 에디터에서 아직 저장하지 않은 편집은 빠져 있다는 안내를 남깁니다. 문서를 담고 있는 에디터의 허브가 꺼져 있을 때와, 위의 hubGone 경우입니다. 에디터의 허브에 연결하지 못한 읽기는 편집과 마찬가지로 hubUnreachable로 거부됩니다.

헤드리스

문서를 담당하는 에디터가 없으면, 각 편집은 파일을 불러와 변경을 적용하고 파일에 다시 씁니다. 쓰기는 문서 옆의 .<name>.<id>.tmp라는 임시 파일로 먼저 가고 그 파일이 문서를 교체하므로, 아래에서 설명하는 Windows의 제자리 쓰기 경우를 제외하면 문서가 반쯤 쓰인 채로 남는 일은 없습니다.

마지막 단계 전에 서버는 호출 중에 디스크의 파일이 바뀌었는지 확인합니다. 바뀌었다면 아무것도 쓰지 않고 파일을 다시 불러오며, 호출은 conflict로 거부됩니다. 에이전트가 다시 호출합니다. 두 호출 사이에 바뀐 파일은 그냥 다시 불러오며, 그 전까지의 에이전트 Undo 히스토리는 버려집니다.

읽기 전용 파일은 그대로 두며, 편집은 readonly로 거부됩니다. 체크아웃하지 않은 Perforce 또는 TFVC 파일처럼, 소유자에게 쓰기 권한이 없거나 Windows에서 읽기 전용 특성이 있는 파일입니다. 파일을 쓸 수 있게 한 뒤 다시 호출하세요. 읽기는 그대로 동작합니다.

에이전트가 디스크에서 편집하는 동안 에디터가 그 문서를 맡기 시작하면, 그 편집 하나는 hubAppeared로 거부되고 아무것도 쓰이지 않습니다. 다음 호출은 에디터를 통해 편집합니다.

Windows에서는 두 가지 규칙이 더 적용됩니다.

• 폴더와 다른 자체 권한을 가진 문서는 그 권한을 유지하도록 교체하는 대신 제자리에 쓰며, 임시 파일은 그 뒤에 제거됩니다. 그 쓰기 도중에 문서를 읽는 프로그램은 파싱되지 않는 텍스트를 볼 수 있습니다.
• 다른 프로그램이 열어 둔 파일은 교체할 수 없으므로, 서버는 최대 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 파일을 나열하며, 읽기 전용 파일은 readonly로 표시하고 Windows에서는 Windows가 적힌 그대로 저장하지 않는 이름을 빼놓습니다.