Режими Live і Headless

Під час кожного виклику сервер шукає редактор, який тримає документ, за файлами блокування, які редактори зберігають у ~/.erd-editor/ide/. Кожне вікно VS Code і кожне вікно сховища (vault) 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 з таблицями, які вже входять до цієї групи (або вже не входять до жодної, коли groupId має значення null); erd_move_table_group у точку, де група вже стоїть; erd_resize_table_group до прямокутника, який група вже має; erd_sort_tables для документа без таблиць; або імпорт з аргументом 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, створюють крок відміни навіть тоді, коли задають значення, яке документ уже містить.

Історія змін агента обривається, і результат містить про це примітку, коли:

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

Сервер також закриває документ, до якого агент не звертався 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, не взятий на редагування (check out). Зробіть його доступним для запису й повторіть виклик. Читання все одно працює.

Якщо редактор починає обслуговувати документ, поки агент редагує його на диску, саме ця зміна відхиляється з кодом 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 не зберігає так, як її написано, пропускається.