Режимы Live и Headless

При каждом вызове сервер ищет редактор, в котором находится документ, по файлам блокировки, которые редакторы хранят в ~/.erd-editor/ide/. Свой файл хранит каждое окно VS Code и каждое окно хранилища Obsidian с ERD Editor, а IDE JetBrains хранит один файл на всю IDE и перечисляет в нем все открытые в ней проекты. При закрытии редактор удаляет свой файл блокировки. От того, что найдет сервер, зависит, куда пойдет правка.

Что найдено	Что делает правка
Редактор, в рабочей области, хранилище или открытом проекте которого находится документ, либо редактор, в котором он открыт	Live. При необходимости открывает документ в ERD Editor, подключается к сеансу редактирования и применяет изменение там. Правки появляются сразу и сохраняются так же, как редактор сохраняет ваши собственные, — см. Сохранение.
Редактора нет	Headless. Загружает файл, применяет изменение и заменяет файл. Инструменту 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, а отклоненная правка сообщает причину отказа. Поиск выполняется заново при каждом вызове, поэтому от открытия или закрытия редактора зависит, куда пойдет следующий вызов.

Если документ находится сразу в нескольких редакторах, редактор, в котором он открыт, имеет приоритет перед редактором, который только обслуживает содержащую его папку, а среди редакторов, обслуживающих папку, выигрывает тот, чья папка вложена глубже всех. При равенстве, например если документ открыт в двух редакторах, выбирается тот, чей файл блокировки изменился последним. Поэтому документ в хранилище Obsidian, которое лежит в папке рабочей области VS Code, достается Obsidian, кроме случая, когда он открыт в VS Code, но не открыт в Obsidian.

Вызовы для одного документа выполняются по одному в том порядке, в котором они поступили на сервер. Вызовы для разных документов выполняются параллельно.

Live

Агент подключается к редактору как еще один соавтор. Его правки сразу доходят до всех редакторов, в которых открыт документ, а его фокус отображается на таблице и ячейке, которые он редактирует, так же как фокус соавтора, — см. focusTracker.

Чтение никогда не открывает редактор. Правка открывает документ в ERD Editor, если он еще не открыт, и при этом не забирает фокус клавиатуры.

Сохранение

Каждый редактор сохраняет правки агента так же, как ваши собственные.

В VS Code правки агента, как и ваши собственные, помечают вкладку как измененную и попадают на диск только при сохранении документа. Инструмент erd_save сохраняет его через VS Code, как это делает собственная команда сохранения VS Code. Вместо этого можно сохранить документ самостоятельно с помощью Ctrl + S (Windows/Linux) или ⌘ + S (Mac). Если закрыть редактор с несохраненными правками агента, появится вопрос, сохранить ли их, как и для любого другого несохраненного изменения.

Obsidian сохраняет правки агента примерно через две секунды после окончания редактирования, а при закрытии вкладки сохраняет их без вопросов. IDE JetBrains записывает их через долю секунды после окончания редактирования, а при закрытии вкладки записывает то, что еще ожидает записи; вкладка никогда не помечается как измененная. В обоих случаях инструмент erd_save записывает их сразу.

Инструмент erd_save сначала ждет до двух секунд, пока в редакторе не окажутся все правки, сделанные агентом. Вызов отклоняется с кодом notSaved, если редактор не смог это подтвердить или не записал файл: VS Code оставляет вкладку несохраненной, если файл изменился на диске, а IDE JetBrains не смогла его записать, например пока было открыто окно или когда файл недоступен для записи.

В VS Code и IDE JetBrains вызов erd_save для документа, в котором уже нечего сохранять, завершается успешно и оставляет файл без изменений. Так бывает, как только все правки сохранены, что IDE JetBrains делает самостоятельно, и так остается, пока каждое последующее изменение — из тех, которые блокировка не пропускает в файл, например прокрутка или масштабирование при включенной блокировке Viewport либо переключение вкладок при включенной блокировке Canvas Type. Все блокировки включены по умолчанию. Если IDE JetBrains не может записать файл, вызов отклоняется даже в этом случае.

Если редактор закрывает документ после последней правки агента, следующий вызов агента содержит примечание о том, что эти правки есть в файле, только если они были сохранены до закрытия редактора.

Отмена изменений

Инструмент erd_undo отменяет последнюю правку, сделанную агентом, но никогда не ваши правки, а erd_redo применяет ее снова. Собственная Отмена редактора работает наоборот: она отменяет ваши правки и никогда — правки агента, поскольку изменения, поступающие из другого редактора, не записываются в вашу историю изменений.

Некоторые правки не создают в редакторе шага отмены: erd_set_database и erd_set_database_name из инструментов настроек, а также erd_resize_memo. Не создает его и вызов erd_move_table_group, который сдвигает группу в сумме меньше чем на 20 пикселей, если сложить сдвиг по горизонтали и по вертикали, хотя группа остается там, куда ее сдвинули. Шага отмены не создает и вызов, который ничего не меняет: 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 со столбцом, который уже входит в индекс; erd_set_table_group с таблицами, которые уже входят в эту группу (или уже не входят ни в одну, при значении null аргумента groupId); erd_move_table_group в точку, где группа уже находится; erd_resize_table_group с прямоугольником, который у группы уже есть; erd_sort_tables для документа без таблиц; или импорт, который при значении append аргумента mode не добавляет ни одной таблицы (для 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, создают шаг отмены, даже если задают значение, которое уже есть в документе.

История изменений агента обрывается, о чем сообщает примечание в результате, когда:

• Агент заново подключается к документу, например после того, как редактор отключил от него агента.
• Редактор завершает работу или закрывает документ и перестает его обслуживать, а агент продолжает редактировать файл на диске.
• Редактор перехватывает документ, который агент редактировал на диске.

Кроме того, сервер закрывает документ, к которому агент не обращался 30 минут, и история изменений пропадает вместе с ним — без примечания.

Если редактор закрыт

Пока документ находится в редакторе, сервер никогда сам не переключается на файл. Если соединение обрывается, он подключается заново. Сервер редактирует файл, только когда редактор завершил работу или закрыл документ и больше не перечисляет ни его, ни содержащую его папку, и сообщает об этом в результате. Так происходит при закрытии диаграммы, которая лежит вне всех папок, обслуживаемых редактором (в VS Code — диаграммы, открытой не из рабочей области), при выключении плагина ERD Editor в Obsidian, а также при закрытии проекта с этим документом в IDE JetBrains или выключении плагина там. Закрытая диаграмма внутри папки, которую обслуживает редактор, остается за редактором, и следующая правка агента снова ее открывает.

Редактор, который все еще работает, но у которого пропал файл блокировки, а соединение закрылось, хотя он не закрыл документ, отклоняет следующую правку с кодом hubGone. В сообщении сказано, что освободит документ: в VS Code перезагрузите это окно или закройте его, чтобы агент редактировал файл напрямую; в Obsidian снова включите плагин ERD Editor или закройте это окно; в IDE JetBrains снова включите плагин или закройте IDE.

Чтение вместо редактора обращается к файлу на диске — с примечанием, что в нем нет правок, еще не сохраненных в редакторе, — в двух случаях: когда у редактора, в котором находится документ, выключен хаб, и в описанном выше случае с hubGone. Чтение, которое не может подключиться к хабу редактора, отклоняется с кодом hubUnreachable, так же как и правка.

Headless

Если документ не обслуживает ни один редактор, каждая правка загружает файл, применяет изменение и записывает файл обратно. Запись идет во временный файл .<name>.<id>.tmp рядом с документом, и затем этот файл заменяет документ, поэтому документ никогда не остается записанным наполовину, кроме описанного ниже случая записи на месте в Windows.

Перед этим последним шагом сервер проверяет, не изменился ли файл на диске во время вызова. Если изменился, ничего не записывается, файл загружается заново, а вызов отклоняется с кодом conflict. Агент повторяет вызов. Файл, изменившийся между двумя вызовами, просто загружается заново, а предшествующая этому история изменений агента отбрасывается.

Файл только для чтения остается без изменений, а правка отклоняется с кодом readonly: это файл без права на запись для владельца или с атрибутом «только для чтения» в Windows, например файл Perforce или TFVC, который не извлечен для редактирования. Сделайте его доступным для записи, затем повторите вызов. Чтение по-прежнему работает.

Если редактор начинает обслуживать документ, пока агент редактирует его на диске, эта одна правка отклоняется с кодом hubAppeared и ничего не записывается. Следующий вызов уже редактирует через редактор.

В Windows действуют еще два правила:

• Документ с собственными разрешениями, отличающимися от разрешений его папки, записывается на месте, а не заменяется, чтобы сохранить их, а временный файл после этого удаляется. Программа, которая читает документ во время такой записи, может получить текст, который не удается разобрать.
• Файл, который держит открытым другая программа, нельзя заменить, поэтому сервер повторяет попытки в течение не более двух секунд. Каждая попытка сначала снова ищет редактор, и редактор, который за это время начал обслуживать документ, отклоняет запись с кодом hubAppeared или, если его хаб выключен, с кодом blocked. Если через две секунды файл все еще занят, ничего не записывается, файл загружается заново, а вызов завершается ошибкой с сообщением, в котором приведена системная ошибка.

Отказ

Окно VS Code оставляет свой файл блокировки, даже когда его хаб выключен: когда выключена настройка dineug.erd-editor.agentHub.enabled, когда рабочая область не является доверенной или когда его хаб не смог начать прослушивание. Окно хранилища Obsidian оставляет свой файл блокировки при выключенном хабе, когда выключен параметр Coding agents, а также когда его хаб не смог начать прослушивание. IDE JetBrains оставляет свой файл блокировки при выключенном хабе, когда выключен параметр Coding agents, когда ее хаб не смог начать прослушивание, а также пока IDE завершает работу.

Правка такого документа отклоняется с кодом blocked, так как открытый редактор может перезаписать изменение, записанное в файл, при своем следующем сохранении. Чтение по-прежнему работает — из файла на диске.

Чтобы агент мог редактировать, снова включите хаб так, как сказано в сообщении для этого редактора: в VS Code отметьте рабочую область как доверенную и включите настройку или перезагрузите окно; в Obsidian включите параметр Coding agents или перезагрузите Obsidian; в IDE JetBrains включите параметр Coding agents или, если он уже включен, перезапустите IDE.

Кроме того, IDE JetBrains отказывается — с кодом hubDisabled — изменять документ, который находится только в проектах, которым она не доверяет. Агенты по-прежнему могут читать такой документ, а инструмент erd_list_documents выводит его с пометкой readonly. Отметьте проект как доверенный, затем повторите вызов.

Редактор, у которого нет файла блокировки, ничего не защищает, и агент редактирует файл на диске, даже пока диаграмма в нем открыта. Так обстоит дело с Obsidian или IDE JetBrains, установленными как Flatpak в Linux, с IDE JetBrains без JCEF и с IDE JetBrains, хаб которой не смог запуститься, — см. Настройка Obsidian и Настройка IDE JetBrains. Расширение VS Code до версии 3.0.0 и плагин JetBrains до версии 0.9.0 тоже не создают такого файла, так как у них нет хаба.

Документы

Документ задается аргументом path — абсолютным путем или путем относительно рабочего каталога сервера.

• Новые документы — это файлы .erd.json. Инструмент erd_open_document с аргументом create создает файл, добавляя .erd.json к имени без расширения. Как и у новой диаграммы в редакторе, у нового документа включены все блокировки, поэтому прокрутка, масштабирование, переключение вкладок или выбор другого языка Генератора кода, стиля имен или типа кавычек в редакторе никогда не меняют файл. Ни один инструмент не включает и не выключает отдельную блокировку: это делается на вкладке «Настройки» редактора. Инструмент erd_import_json в режиме replace заменяет их все блокировками загружаемого документа — см. Импорт.
• Существующие файлы .erd, .vuerd и .vuerd.json тоже открываются. Путь с любым другим расширением отклоняется с кодом invalidPath.
• В Windows путь, содержащий имя, которое Windows не сохраняет в том виде, в каком оно написано, отклоняется с кодом invalidPath еще до чтения или записи документа, в том числе при чтении: имя с двоеточием или другим символом, который Windows не допускает, например orders:v2.erd; имя устройства, например NUL.erd или CON.erd, в любом регистре; или имя, оканчивающееся точкой или пробелом. Переименуйте файл, например заменив : на -.
• Файл, который не является документом, читаемым редактором, например файл с оставшимися маркерами конфликта слияния, отклоняется с кодом invalidDocument и остается без изменений. Он никогда не загружается как пустая диаграмма и не записывается обратно.

Агент изменяет документ только с помощью инструментов, и ему предписано никогда не записывать файл самостоятельно.

Инструмент erd_list_documents выводит список документов с полями path, open, active, dirty и readonly. Он запрашивает редактор, который обслуживает рабочий каталог и выбирается так же, как для документа, и выводит открытые в нем диаграммы, а затем обслуживаемые им ERD-файлы: файлы в папках рабочей области окна VS Code, в хранилище Obsidian или во всех проектах, открытых в IDE JetBrains. В противном случае он выводит ERD-файлы в рабочем каталоге, причем файл только для чтения помечается как readonly, а файл с именем, которое Windows не сохраняет в том виде, в каком оно написано, в Windows не отображается.