מצב חי ומצב ללא ממשק

בכל קריאה, השרת מחפש עורך שמחזיק את המסמך, באמצעות קובצי הנעילה שהעורכים שומרים ב-~/.erd-editor/ide/. כל חלון של VS Code וכל חלון של כספת Obsidian שיש בו ERD Editor שומר קובץ אחד כזה, ו-IDE של JetBrains שומר קובץ אחד לכל ה-IDE, ובו רשימה של כל הפרויקטים שפתוחים בו. עורך מסיר את קובץ הנעילה שלו כשהוא נסגר. מה שהשרת מוצא קובע לאן העריכה הולכת.

מה השרת מוצא	מה עריכה עושה
עורך שסביבת העבודה, הכספת או הפרויקט הפתוח שלו מכילים את המסמך, או שהמסמך פתוח בו	חי. פותחת את המסמך ב-ERD Editor אם צריך, מצטרפת לסשן העריכה ומחילה בו את השינוי. העריכות מופיעות מיד ונשמרות כפי שהעורך שומר את העריכות של המשתמש – ראו שמירה.
אין עורך	ללא ממשק. טוענת את הקובץ, מחילה את השינוי ומחליפה את הקובץ. ל-erd_save אין מה לעשות.
עורך שה-hub שלו כבוי	נדחה. קריאות עדיין עובדות, מהדיסק. שינוי שנכתב לקובץ מאחורי גבו של עורך פתוח עלול להידרס בשמירה הבאה של העורך, ולכן השרת אינו כותב דבר.
עורך שה-hub שלו מופעל אבל מדבר בפרוטוקול שונה מזה של השרת: עם השרת בגרסה 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.

קריאות על מסמך אחד רצות אחת בכל פעם, לפי הסדר שבו הגיעו לשרת. קריאות על מסמכים שונים רצות במקביל.

מצב חי

הסוכן מצטרף לעורך כמו שותף נוסף לעריכה. העריכות שלו מגיעות מיד לכל עורך שבו המסמך פתוח, והפוקוס שלו מוצג על הטבלה והתא שהוא עורך, כמו הפוקוס של שותף לעריכה – ראו 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.

קריאה פונה במקום זאת לקובץ בדיסק, עם הערה שעריכות שעדיין לא נשמרו בעורך חסרות, בשני מקרים: כשה-hub של העורך שמחזיק את המסמך כבוי, ובמקרה של hubGone שתואר למעלה. קריאה שאינה מצליחה להתחבר ל-hub של עורך נדחית עם hubUnreachable, כמו עריכה.

מצב ללא ממשק

כשאף עורך אינו משרת את המסמך, כל עריכה טוענת את הקובץ, מחילה את השינוי וכותבת את הקובץ בחזרה. הכתיבה נעשית לקובץ זמני לצד המסמך, בשם .<name>.<id>.tmp, שמחליף אותו לאחר מכן, כך שהמסמך לעולם אינו נשאר כתוב למחצה, מלבד ב-Windows במקרה של כתיבה ישירה לקובץ, שמתואר בהמשך.

לפני הצעד האחרון הזה, השרת בודק אם הקובץ השתנה בדיסק במהלך הקריאה. אם כן, דבר אינו נכתב, הקובץ נטען מחדש, והקריאה נדחית עם conflict. הסוכן מבצע את הקריאה שוב. קובץ שהשתנה בין שתי קריאות רק נטען מחדש, והיסטוריית הפעולות של הסוכן שקדמה לכך נמחקת.

קובץ לקריאה בלבד נשאר כמות שהוא, והעריכה נדחית עם readonly: קובץ ללא הרשאת כתיבה לבעלים שלו, או עם תכונת הקריאה בלבד ב-Windows, כגון קובץ של Perforce או TFVC שלא בוצע עליו check out. יש להפוך אותו לניתן לכתיבה, ואז לבצע את הקריאה שוב. קריאות עדיין עובדות.

אם עורך מתחיל לשרת את המסמך בזמן שהסוכן עורך אותו בדיסק, העריכה הזאת לבדה נדחית עם hubAppeared ודבר אינו נכתב. הקריאה הבאה עורכת דרך העורך.

ב-Windows חלים שני כללים נוספים:

• מסמך עם הרשאות משלו, שונות מאלה של התיקייה שלו, נכתב ישירות לקובץ עצמו במקום שהקובץ יוחלף, כדי שישמור עליהן, והקובץ הזמני מוסר לאחר מכן. תוכנה שקוראת את המסמך במהלך הכתיבה הזאת עלולה למצוא בו טקסט שאי אפשר לנתח.
• קובץ שתוכנה אחרת מחזיקה פתוח אינו ניתן להחלפה, ולכן השרת מנסה שוב במשך עד שתי שניות. כל ניסיון מחפש תחילה שוב עורך, ועורך שהתחיל לשרת את המסמך בינתיים דוחה את הכתיבה עם hubAppeared, או עם blocked כשה-hub שלו כבוי. אם הקובץ עדיין מוחזק אחרי שתי שניות, דבר אינו נכתב, הקובץ נטען מחדש, והקריאה נכשלת עם הודעה שמצטטת את שגיאת המערכת.

סירוב

חלון של VS Code שומר את קובץ הנעילה שלו גם כשה-hub שלו כבוי: כש-dineug.erd-editor.agentHub.enabled כבוי, כשסביבת העבודה אינה מהימנה, או כשה-hub שלו לא הצליח להאזין. חלון של כספת Obsidian שומר את קובץ הנעילה שלו, עם ה-hub שלו כבוי, כשההגדרה Coding agents כבויה, וכשה-hub שלו לא הצליח להאזין. IDE של JetBrains שומר את קובץ הנעילה שלו, עם ה-hub שלו כבוי, כשההגדרה Coding agents כבויה, כשה-hub שלו לא הצליח להאזין, ובזמן שה-IDE נסגר.

עריכה של מסמך כזה נדחית עם blocked, מפני שהעורך הפתוח עלול לדרוס בשמירה הבאה שלו שינוי שנכתב לקובץ. קריאות עדיין עובדות, מהקובץ בדיסק.

כדי לאפשר לסוכן לערוך, יש להפעיל שוב את ה-hub, כפי שההודעה מסבירה עבור אותו עורך: ב-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 שה-hub שלו לא הצליח להתחיל לפעול – ראו הגדרת Obsidian והגדרת IDE של JetBrains. גם הרחבת VS Code בגרסה שקודמת ל-3.0.0 ותוסף ל-JetBrains בגרסה שקודמת ל-0.9.0 אינם שומרים קובץ כזה, מפני שאין להם hub.

מסמכים

מסמך מצוין באמצעות 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 אינו שומר כפי שנכתב מושמט.