Skip to content
palmoni5 edited this page Nov 5, 2026 · 4 revisions

מערכת התוספים

דף מפתחים זה מתאר את צד אוצריא בענף dev: טעינה, גשר, הרשאות, אחסון ומחזור חיים. לכתיבת תוסף, התחל בפיתוח תוספים; להתקנה וניהול, פתח את מדריך המשתמש.

תוסף עם ממשק הוא יישום HTML/CSS/JavaScript בתוך WebView. המארח מזריק window.Otzaria, והקוד פונה לשירותי אוצריא דרך RPC. יש גם תוספים ללא ממשק ותרומות דקלרטיביות שהמארח מבצע ללא הרצת JavaScript.

המניפסט וההתקנה

PluginManifest מפרש manifest.json; InstalledPlugin מוסיף מצב התקנה, החלטות הרשאה, הפעלה, הצמדה, סדר ומקור. חשוב להבחין בין שם שדה Dart לבין מבנה JSON שהתוסף צריך לספק:

נושא במניפסט
מזהה וגרסה id, version, schemaVersion
שם ותאימות name, minAppVersion, maxAppVersion, sdkVersion
קובץ כניסה entrypoint
תוסף ללא ממשק headless
הרשאות מבוקשות permissions
רשת network.enabled, network.allowlist
דף הכלי contributes.toolTab
קובץ רקע חלופי contributes.background.entrypoint
תרומות שמוגדרות מראש contributes.startup

אריזה מופצת היא ZIP עם סיומת .otzplugin. המקורות הנוספים הם תיקיית פיתוח (development) ושרת פיתוח מקומי (localhost_dev).

PluginInstallerService מפריד בין הכנה — חילוץ ואימות — לבין השלמת ההתקנה. אין לחשוף תוסף שהותקן חלקית. ההתקנות וההרשאות נשמרות באמצעות PluginRegistryRepository במסד plugins_host.db; קובצי התוסף נמצאים תחת נתיבי התוספים של AppPaths.

בעדכון נשמרות החלטות הרשאה קודמות. resolvePluginInstallDecision יכול לוותר על דיאלוג בעדכון רגיל שיזם המשתמש בממשק אוצריא, כשאין הרשאות חדשות או הרשאות שהמשתמש ביטל. הפעלה חיצונית או בקשת התקנה מתוסף מחייבות החלטה. אין להסיק מ־isUpdate לבדו שמותר להתקין בלי דיאלוג.

תוספים שנארזו עם האפליקציה נרשמים במסלול ייעודי, לפי רשימת מזהים שנקבעה בבנייה. מסלול זה אינו זהה להתקנה מקובץ: בהרשמה ראשונה הוא יכול להעניק את הרשאות המניפסט, ועדכונים משמרים החלטות משתמש. תוסף מובנה שנמחק אינו מותקן שוב בכל הפעלה. הפרטים נמצאים ב־docs/bundled_plugins.md.

שכבות הגשר

רכיב תפקיד
plugin_api_catalog.dart רשימת המתודות ומיפוי ההרשאות שהמארח מכיר
PluginBridgeHandler קבלת RPC, אימות מקור הקריאה, הרשאה, הגבלת קצב וזמן, החזרת שגיאות
PluginBridgeAdapter מימוש פעולות המארח והפניה לשירותי התחום
PluginRuntimeDispatcher איתור מופעים, מסירת אירועים, פעילות והשהיה
שירותי database, fs, network מדיניות מפורטת לכל משאב

ה־handler מזריק סוד גשר למסגרת הראשית ודורש אותו בכל RPC; מסגרת משובצת של תוכן צד שלישי אינה מקבלת אוטומטית את גישת התוסף. יש מגבלת קצב ו־timeout כללי; פעולות שמנהלות בעצמן משימה ממושכת או ממתינות לבחירת משתמש מוחרגות לפי רשימה מפורשת. library.getBookContent מוחרג מהגבלת הקצב כדי שקריאת תוכן במקטעים לא תיעצר באמצע.

בין תחומי ה־API: פרטי האפליקציה וערכת הנושא, ספרייה ותוכן, חיפוש, פתיחת ספר ופעולות קורא, סימניות ושולחנות עבודה, הערות, לוח שנה, ביוגרפיות, קבצים, נתונים פרטיים ורשת. החתימות, הגבולות וההרשאות המדויקות מתועדים ב־API_REFERENCE; אין להעתיק רשימת מתודות חלקית ולהפוך אותה לחוזה נוסף.

הרשאות וקבצים

הרשאה מוכרזת והרשאה שהוענקה בפועל הן שני דברים שונים. גם אחרי ההתקנה המשתמש יכול לבטל הרשאות. פעולת RPC חייבת לבדוק את ההחלטה התקפה, ולא רק את המניפסט שנקרא בזמן יצירת ה־WebView.

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

סוג משאב מסלול הגישה
אחסון KV פרטי לתוסף storage.*, עם הפרדת מרחב שמות לכל תוסף
קובצי data ו־cache פרטיים שירות הקבצים הפרטי של התוסף
קובץ שבחר המשתמש API לבחירת קובץ וההרשאה המתאימה לקריאה או לשמירה
תיקייה קבועה של המשתמש fs.pickUserFolder ואישור מפורש של גישה קבועה
קובץ גדול להצגה ב־WebView רישום ב־PluginFileServer וקבלת URL מקומי מוגבל

הסכמה לבחירת תיקייה אינה מתירה גישה שרירותית לכל הדיסק. שירותי הקבצים מקנננים נתיבים ובודקים שהיעד נשאר בתחום המותר. אישורי תיקייה קבועה נשמרים במרחב פנימי שאינו זמין ב־storage.*, וביטולם חל גם על תוסף שכבר רץ.

PluginFileServer מאזין ב־loopback ומגיש רק קבצים שנרשמו עם token. תמיכה ב־HTTP Range מאפשרת צריכת קובץ גדול בלי להעבירו דרך RPC כ־base64. יכולת ה־WebView להציג פורמט מסוים עדיין תלויה בפלטפורמה; למשל, אין להסתמך על קורא PDF מובנה בכל פלטפורמה.

רשת: אינטרנט ושירות מקומי

כל בקשת רשת צריכה network.enabled: true ויעד ב־network.allowlist. יש שתי הרשאות נפרדות:

יעד הרשאה בדיקה נוספת
אינטרנט network.access היעד צריך להיכלל גם ברשימת ההיתר הרשמית של אוצריא
שירות מקומי במחשב network.localhost היעד חייב להיות loopback שמוכר במדיניות המארח

ההפרדה המלאה חלה מ־0.9.98.1; בקוד נשמר גם מסלול תאימות לגרסאות קודמות. אין להתייחס לכל רשת מקומית כ־localhost: ההגדרה כוללת localhost, ‏::1 וכתובות 127.0.0.x תקניות לפי המדיניות, ולא כתובות LAN שרירותיות.

evaluatePluginNetworkAccess הוא מרכז ההכרעה. הוא משמש את ה־RPC וגם את שערי ה־WebView, ו־PluginNetworkPolicy מפיק מדיניות מקבילה לאכיפה בתוך מנוע הדפדפן. שינוי ברשימת ההיתר או בהרשאות צריך לעדכן את כל המסלולים.

PluginNetworkAccessResolver טוען את הרשימה הרשמית מהרשת עם מסלולי גיבוי ועותק מקומפל. קבלת HTML מדף חסימה אינה נחשבת רשימה רשמית ריקה. מצב מנותק משפיע גם על זמינות התוסף לפתיחה; החלטת הזמינות נמצאת במודל ובקטלוג הכלים ולא נקבעת רק לפי עצם קיום network.enabled.

הגדרות ומסדי נתונים

settings.* משתמש במדיניות חסימת מפתחות רגישים לפי מפתחות, קידומות וחלקי שם. אין להציג זאת כרשימת היתר סגורה. המפרט המחולל כולל את כללי החסימה, והוולידטורים החיצוניים צריכים להתאים להם.

PluginDatabaseService מקבל שאילתות דקלרטיביות: מקור, בחירה, תנאים, joins, סדר ומגבלה. השירות בונה SQL פרמטרי ומגביל טבלאות, עמודות וקשרים לפי policy. התוסף אינו מקבל SQL חופשי או חיבור לכתיבה במסד הספרייה.

מחזור חיים, רקע וריבוי מופעים

דף תוסף רץ בתוך כרטיסייה. השהיה וחידוש מוסרים אירועי lifecycle; התוסף צריך לשמור מצב עבודה ולבטל פעילות שאינה נחוצה כשהוא מושהה. plugin.setRestoreState מיועד לשחזור מצב הכרטיסייה.

ברירת המחדל אינה מאפשרת כמה מופעים של אותו תוסף באותו חלון. contributes.toolTab.allowMultipleInstances מאפשר זאת באופן מפורש. המופעים חולקים אחסון: מצב של כרטיסייה אחת לא צריך להיכתב מעל מצב של האחרת. ה־runtime מזהה את המופע והחלון הרלוונטיים בעת מסירת אירועים.

contributes.startup יכול לרשום פריטי ממשק ותכניות Host בלי להעלות WebView. בתוסף המשתמש בתרומות startup, הרצת JavaScript ברקע דורשת גם app.run_on_startup וגם אירועי הפעלה או טריגרים מתאימים; הרשאה לבדה אינה פקודת הפעלה. תוספים מדור קודם בלי תרומות startup משתמשים במסלול תאימות של טעינה בעליית האפליקציה, בכפוף להרשאה. מנוע רקע מועלה לפי צורך ומכובה לאחר חוסר פעילות. בקשת keepAlive מחייבת הרשאה נפרדת, שכבויה כברירת מחדל.

תוסף headless אינו מקבל דף כלים. יש להתאים את נקודת הכניסה והתרומות למצב זה, כפי שמוגדר ב־SDK.

התאוששות וניקוי

PluginCrashGuard מסמן ניסיון העלאת WebView ומבדיל בין טעינה שהסתיימה לבין קריסה. PluginSafeMode יכול להשעות תוספים לכל הסשן, גם בהפעלה עם --safe-mode או בעקבות קריסות חוזרות. הוא אינו מוחק את ההתקנות ואינו זהה למצב סייפר.

בעת הסרה או הפעלה מחדש יש לסגור WebViews, מנועי רקע ורישומי תרומות. איפוס נתוני תוסף מנקה את נתוניו בלי להסיר אותו ובלי לשנות את החלטות ההרשאה; הסרה היא מסלול נפרד.

חוזה SDK וולידציה

docs/plugin-sdk/spec.json הוא מפרט מכונה מחולל. מקורותיו כוללים את קטלוג ה־API, ההרשאות, הוולידטור ומדיניות ההגדרות. אין לערוך אותו ידנית או לגזור את רשימת המתודות מטבלאות Markdown.

dart run tool/plugins/generate_plugin_spec.dart
dart run tool/plugins/generate_plugin_spec.dart --check

הפקודה השנייה היא בדיקת העדכניות ב־CI. שינוי API עשוי לדרוש גם עדכון TypeScript, מדריך API, בדיקות ועותקי המפרט בריפו הוולידטור ובאתר. SPEC.md מפרט את סדר הסנכרון ואת ההבדל בין שינוי נתוני המפרט לשינוי אלגוריתם האכיפה.

דפים קשורים

מקורות בקוד

Clone this wiki locally