נקודת קצה אחת, 1008 הצהרות, ו-331 מהן שלכם.
אין טבלת נתיבים בפלטפורמה הזאת. http_module רושם בדיוק שני מטפלי Express, app.post("*") ו-app.get("*"), קורא את מקטע הנתיב השלישי של /cpi/<method>, ומחפש את השם הזה באובייקט cpi_methods שב-config.json. האובייקט הזה מחזיק 1008 רשומות. שם שלא נמצא בו חוזר בתור {code: -1, data: 'method "X" not exist'} עוד לפני שנקרא בכלל אישור כלשהו, ב-cpi/http_module/index.mjs שורות 634 עד 650. הוספת מתודה לאובייקט הזה היא כל מעשה שליחת ה-API: זה מה שהופך את המתודה לניתנת לקריאה מעל HTTP, נראית ככלי MCP, מגודרת במסלול, ממוטמנת, נרשמת ביומן ביקורת ונמדדת כמשימה. אין מקום שני לרשום אותה בו ואין לקוח מיוצר לייצר מחדש. 677 מתוך 1008 הרשומות נושאות private: true, שהיא חומת המפעיל שאף מפתח API לא חוצה בשום מצב, ולכן מה שקורא חיצוני באמת יכול להגיע אליו הוא 331 מתודות, וקטלוג ה-REST ורשימת כלי ה-MCP מורכבים מאותה קבוצה בדיוק. שאר העמוד הזה עוקב אחרי קריאה אחת דרך שבעת השלבים שהיא עוברת, מציג את התמליל האמיתי בשני הכיוונים, ומצביע על המקומות שבהם הקוד שנשלח עושה פחות ממה שהממשק סביבו רומז.
מתודות שמוצהרות בקובץ קונפיגורציה אחד
נגישות עם מפתח API של מפתחים
מחרוזות clearance שכל המשטח משתמש בהן
הגדרות שדה מוקלדות, 1102 מהן חובה
כל קריאה עוברת את אותם שבעה שלבים, ויש ארבע דרכים לצאת עוד לפני שהמטפל שלכם רץ.
מתודה אחת היא שם אחד, וכל שם עובר את אותו מסלול בדיוק. תעבורה ציבורית נוחתת על router_module, שמסיים את 443, מפצל לפי מקטע הנתיב הראשון ומעביר את מקרה ה-cpi היישר אל localhost:3007. משם הסדר קבוע וכדאי לזכור אותו, כי שלב אחד יושב במקום שרוב הקוראים מניחים שהוא לא: חוזה השדות המוקלד נבדק לפני האימות ולא אחריו, ולכן בקשה שחסר בה ארגומנט חובה נדחית בלי שהפלטפורמה בכלל הסתכלה על האישור שלכם. האימות עצמו הוא קריאת ברוקר יחידה אל session_module ולא middleware, שני שערי החשבון קוראים ביניהם מסמך חשבון אחד, והמטפל מושג מעל RabbitMQ ולא בייבוא. שום דבר כאן לא מסתעף לפי שם המתודה חוץ מהחיפוש בשלב שתיים.
החוט, שני חצאיו.
שלושה דברים כאן מפתיעים אנשים, ולכן שווה לראות אותם ולא לקרוא עליהם. ראשית, מפתח המפתחים נוסע בגוף ה-JSON בתור api_key. http_module אף פעם לא קורא כותרת Authorization במסלול הזה, ו-session_module שולף api_key היישר מהבקשה בשורה 116, ולכן לקוח ששם את המפתח בכותרת מזדהה כאף אחד. שנית, הצלחה וכישלון הם אותו אובייקט: {code, data}, עם code 1 ומעלה להצלחה ומספר שלילי לכל השאר. שלישית, סטטוס ה-HTTP נגזר מהקוד ולא נבחר, על ידי get_status בשורות 204 עד 210: רק קוד בטווח 400- עד 499- הופך לסטטוס משלו, ולכן 401- הוא 401 אמיתי ו-428- הוא 428 אמיתי, בעוד כל השאר, כולל ה-1- הנפוץ מאוד, מתקפל ל-400 שטוח. לקוח שמסתעף לפי הסטטוס בלבד לא יכול להבדיל בין ארגומנט שגוי לבין מטפל שהתפוצץ. כותרת התשובה היחידה שנחשפת דרך CORS היא xu-region, שמוטבע בה XUDA_HOSTNAME.
private היא החומה, והיא רוב הקטלוג.
clearance מכריע מי הקורא חייב להיות. private מכריע אם אישור שאינו הפעלת דפדפן רשאי בכלל לנסות את המתודה, וזה הדגל שמגדיר את צורת המוצר מבחוץ. 677 מתוך 1008 המתודות המוצהרות נושאות private: true. אף מצב מפתח לא חוצה את הקו הזה: לא מפתח בגישה מלאה, לא מפתח מותאם שהמתודה כתובה ברשימת ההיתרים שלו, ולא הפעלת MCP. מה שנשאר הוא 331 מתודות, ואותן 331 הן מה שכל צרכן חיצוני רואה, בין אם הוא מגיע כ-curl ובין אם כסוכן שמחזיק רשימת כלים. ארבע הנקודות שלמטה הן המכניקה של החומה הזאת, כולל החלק שבה שהוא מוסכמה ולא ערובה.
- ענף מפתח ה-API נכנס רק כשהמתודה אינה private ואינה בבעלות api_module: session_module שורות 121 עד 130 קוראות if (api_key והמיקרו-שירות של המתודה אינו api_module ולא method.private). מתודה פרטית לכן אף פעם לא מגיעה לאימות המפתח. היא נופלת אל מסלול ההפעלה במקום, שקורא עם מפתח בלבד לא יכול לספק, ולכן הדחייה נקראת ככישלון אימות ולא כ-404. api_module שורות 172 עד 181 אוכפות את אותו כלל פעם שנייה עם ההודעה המילולית api method <name> is unauthorized.
- כל 8 מתודות ניהול המפתחות הן עצמן private: create_account_api_key, update_account_api_key, get_account_api_keys, create_app_api_key, update_app_api_key, get_app_api_keys, get_account_system_api_methods ו-get_app_system_api_methods. מפתח לכן אף פעם לא יכול ליצור מפתח, להחליף מפתח, או למנות את המפתחות שעל החשבון שהוא שייך אליו. מחזור חיי המפתח הוא פעולה של הפעלת לוח בקרה בלבד, וזו תכונה של הקטלוג ולא כלל שכתוב איפשהו.
- mcp_module מדלג על private כשהוא רושם כלים, ולכן REST ו-MCP מורכבים מאותה קבוצה בדיוק. מפתח בגישה מלאה מונה את Object.keys(cpi_methods), משמיט את הפרטיות, ורושם את 331 הנותרות ככלים עם סכמת קלט zod שנגזרת מהשדות המוצהרים של כל מתודה. הרשימה נקבעת מחדש לכל הפעלה ולא נאפית לתוך המפתח, ולכן מתודה שנשלחה אחרי הנפקת המפתח נקלטת בלי לגעת במפתח.
- הקצה הכן: private חסר ולא false ב-321 מהרשומות, ורק 10 מצהירות private: false במפורש. החומה מוגדרת לפי שקריות, כלומר מתודה שנשלחה זה עתה בלי שדה private ניתנת לקריאה במפתח כברירת מחדל. זו ברירת מחדל ולא החלטה, וזה הדבר האחד בעמוד הזה ששווה לבדוק מול הציפיות שלכם לפני שאתם נשענים על ה-331.
חמש מחרוזות clearance, ומה כל אחת מהן באמת מבקשת מכם.
מחרוזת אחת ברשומת הקונפיגורציה מכריעה איזה אישור הקורא חייב להציג, והמפיץ אף פעם לא מסתעף לפי שם המתודה כדי להבין את זה: http_module מוסר את method.clearance אל session_module.validate_cpi_access ונותן לפונקציה היחידה הזאת לענות. הספירות וקודי ההצלחה שלמטה נקראו מתוך session_module שורות 115 עד 291, ולא שוכתבו מתוך מסמך. השורה ששווה להאט עליה היא admin. clearance admin הוא תפקיד באפליקציה, לא תפקיד בפלטפורמה: הוא נגזר משורה בתצוגת user_active_shares של xuda_team, ולכן admin בצוות של פרויקט אחד עומד בכל אחת מ-252 מתודות ה-admin באותו פרויקט ובשום דבר מעבר לו. superuser של הפלטפורמה הוא מושג נפרד שאינו ערך clearance בכלל. הוא מערך קונפיגורציה עם רשומה אחת בדיוק, שנבדק כעקיפה שמחזירה code 104 וכופה את auth_clearance ל-admin, כלומר הוא לעולם לא יכול לבטא יותר מ-admin. כל מתודה שחייבת להיות לצוות בלבד בודקת לכן את עצמה בגוף שלה, ו-83 מקומות ב-25 קבצי מודול עושים בדיוק את זה בכך שהם מחזירים {code:-403, data:'superuser only'}. זו מוסכמה ולא מנגנון: שום דבר במפיץ לא מוודא שמתודה לצוות בלבד באמת נושאת את הבדיקה שלה.
מתודות | מה הקורא חייב להציג | מה השער מחזיר | |
|---|---|---|---|
| public | 51 | שום דבר בכלל, הבדיקה חוזרת לפני שנקרא אישור כלשהו | code 100 |
| user | 680 | מסמך הפעלה חי ב-xuda_sessions, בלי app_id | code 106 |
| user_access | 5 | app_id ובנוסף שורת צוות של user_group, developer או admin | code 6 |
| developer | 15 | app_id ובנוסף developer או admin | code 6 |
| admin | 252 | app_id ובנוסף admin, או להיות הבעלים של האפליקציה | code 6, התאמת בעלים 106 |
| superuser | לא clearance | uid במערך superuser_account_ids בעל הרשומה האחת | code 104, נכפה ל-admin |
| ריק או חסר | 5 | שום דבר לא מספק אותו: clearance שקרי זורק לפני כל ענף אחר | code -401. לא מאומת אם חמש אלה הן רשומות לברוקר בלבד |
שתי דלתות כניסה, שער אחד.
mcp_module מריץ אפליקציית Express משלו על פורט 3012 ומדבר Streamable HTTP על /mcp, מה שגורם לו להיראות כמו מודל הרשאות שני. הוא לא כזה. כל מטפל כלי שהוא רושם מבצע fetch פשוט אל http://localhost:3007/cpi/<method> כשה-api_key מועבר מכותרת Authorization אל גוף ה-JSON, ולכן clearance נבדק בדיוק פעם אחת, באותה קריאת validate_cpi_access, בין אם הקורא הוא curl ובין אם סוכן. חמש השורות שלמטה מזווגות בכוונה: קראו לרוחב ותוכלו לראות בדיוק איזה חצי מהסיפור משתנה בין שתי הדלתות, וכמה מעט ממנו משתנה.
הדירוג מתהפך: המודולים הגדולים ביותר חושפים הכי מעט.
שלושים וחמישה מודולים הם הבעלים של 1008 המתודות המוצהרות, לפי שדה המיקרו-שירות שבכל רשומת קונפיגורציה. במיון לפי כמה מודול מצהיר, הרשימה נקראת כמו מפה של הפלטפורמה: app_module 110, ai_module 91, account_module 90, drive_module 77, stripe_module 75. במיון לפי מה שמפתח חיצוני באמת יכול להגיע אליו, הסדר הזה מתהפך, כי העמודה השנייה היא פשוט הראשונה פחות כל מה שנושא private:true. שבעה מודולים לא חושפים כלום בכלל, והם לא הקטנים: stripe_module מצהיר על 75 מתודות ומפרסם אפס, marketplace_module 25 ואפס, shipping_module 26 ואפס, commerce_module 21 ואפס, ו-bot_protection_module ו-jobs_module מצטרפים אליהם. משטח הכסף ומשטח זירת המסחר הם פנימיים לחלוטין, נגישים רק מהפעלת לוח בקרה מחוברת עם ה-clearance הנכון, וזו צורה מכוונת ולא פער תיעוד. השורה האחרונה היא החדה שבהן: כל שמונה מתודות ניהול המפתחות של api_module הן private, ולכן מפתח אף פעם לא יכול ליצור, להחליף או אפילו למנות מפתחות. קראו קודם את האפסים, ואז קראו את ראש הטבלה. שורה אחת ראויה למבט שני ולא לכותרת: voice_module מציג 46 מתוך 46 נגישות מבחוץ, המודול היחיד בפלטפורמה בלי אף מתודה פרטית, וזה שווה בדיקת שפיות מול הכוונה.
מוצהרות | נגישות עם מפתח | |
|---|---|---|
| דרייב | 77 | 66 |
| אפליקציות | 110 | 61 |
| שיחות | 46 | 46 |
| חשבון | 90 | 32 |
| AI | 91 | 26 |
| צוות | 50 | 14 |
| Stripe | 75 | 0 |
| שוק | 25 | 0 |
| משלוחים | 26 | 0 |
| מסחר | 21 | 0 |
| מפתחות API | 8 | 0, מפתח אף פעם לא יכול לנהל מפתחות |
שלוש תנועות מכלום ועד קריאה עובדת.
לוח הבקרה לא מוסר לכם עמוד תחילת עבודה, הוא מוסר לכם ארבע לשוניות של העתק והרץ במסך מפתחות ה-API: MCP, curl, node ו-php, כש-MCP הוא ברירת המחדל והמפתח הראשון שלכם כבר מוצב בתוך הקטע. שווה לומר בפשטות לפני שמתחילים: אין SDK ל-REST. לשונית node היא קריאת fetch מילולית ולשונית php היא בלוק curl_init מילולי, ולכן מה שאתם משתלבים מולו הוא נקודת קצה HTTP ומעטפת JSON, לא ספריית לקוח עם טיפוסים.
- 01
מנפיקים מפתח
שני היקפים, חשבון או אפליקציה, ושני מצבי גישה. מפתח בגישה מלאה נבדק רק מול private, והבדיקה הזאת רצה מחדש בכל קריאה במקום להיאפות פנימה בזמן ההנפקה, ולכן מתודות שנשלחו אחרי יצירת המפתח מכוסות בלי לגעת בו. מפתח מותאם נושא רשימת api_allow_methods במקום, עם יוצא מן הכלל אחד ששווה להכיר: מתודות ב-clearance public עוקפות את רשימת ההיתרים לגמרי, ולכן 51 המתודות האנונימיות נגישות בכל מפתח תקף.
- 02
שואלים את הקטלוג למה מותר לכם לקרוא
get_account_system_api_methods מוסרת בחזרה את כל 331 המתודות שאינן private בתור {description, fields, category}, כש-category הוא המיקרו-שירות הבעלים. אלה בדיוק אותם נתונים שסכמות כלי ה-MCP מהודרות מהם, ולכן קטלוג ה-REST ורשימת כלי הסוכן לא יכולים להיפרד לעולם. get_app_system_api_methods היא התצוגה בהיקף אפליקציה ומחזירה 86, קבוצת ה-admin שאינה private. שתיהן עצמן private, ולכן קוראים אותן מהפעלת לוח בקרה.
- 03
קוראים לה, או מוסרים את אותו מפתח לסוכן
POST /cpi/<method> עם api_key בגוף, או להריץ claude mcp add מול /mcp עם המפתח כטוקן נושא. אותו שער, אותן 331 מתודות, שתי מעטפות. מפתח שאתם מנפיקים לבקאנד שלכם ומפתח שאתם מנפיקים לסוכן נבדלים בשום דבר חוץ מאיזו דלת אתם מכוונים אותו אליה, ולכן צמצום מה שסוכן יכול לעשות פירושו הנפקת מפתח צר יותר ולא הגדרת הסוכן.
קריאה ארוכה עונה מיד ומסיימת מעל שקע.
הדבר שרוב המשתלבים מבינים הפוך: מסלול המשימות הוא ברירת המחדל. http_module מריץ אותו אלא אם רשומת המתודה אומרת job:false, ו-573 מתוך 1008 הרשומות מוותרות ככה, מה שמשאיר 435 שנשארות בפנים. אותן 435 הן הפריסות, הבנייה, ההתקנות מחדש, העבודה שאף פעם לא הייתה מסיימת בתוך בקשה אחת. משימה נרשמת לפני השיגור בכל מקרה, ולכן השאלה היחידה היא אם ביקשתם שימסרו לכם את הכרטיס במקום את התוצאה. מגבלה אחת באותה נשימה: חלק מהמתודות מסיימות את המשימה של עצמן, ולכן מונה השלבים הוא מייעץ ולא ערובה.
- שלחו job:true בגוף והקריאה מחזירה כרטיס שנושא את מזהה המשימה, בזמן שהתוצאה האמיתית נוחתת מאוחר יותר מעל socket.io בפורט 4010. שני מעברי ראיות חלוקים על הקוד המספרי בכרטיס הזה, אחד קורא 88 ואחד קורא 999 עם info "job successfully scheduled to run immediately", ולכן התייחסו למספר כלא מאומת וקראו את מזהה המשימה.
- job_steps הוא הטקסט המילולי של סרגל ההתקדמות, לא מכונת מצבים פנימית. 38 מתודות מצהירות על אחד: build_app מצהירה על 7, reinstall_spa_resources מצהירה על 18, מ-initiating process ועד activating the server. משימה בלי שלבים מוצהרים מקבלת סך הכול 2.
- job_title הוא תבנית lodash שמעובדת מול גוף הבקשה שלכם, ולכן ההודעה הקופצת אומרת Reinstalling SPA Server ולא שם מתודה. 36 מתודות מצהירות על אחד.
- broadcast:true על 194 מתודות הוא מה שהופך את העדכון ללא שקט; כל השאר נמדד בשקט. job_timeout מגביל את ההמתנה בפרוקסי ומוגדר כברירת מחדל ל-1800 שניות, ו-7 מתודות דורסות אותו.
- register_jobמסמך משימה ב-memcached, TTL של 600 שניות
- אתם מקבלים כרטיס, לא תוצאהרק כשהקורא ביקש זאת במפורש בשליחת job:true
- העובד מדווח התקדמותupdate_job עובר על ה-job_steps המוצהרים
- socket.io, פורט 4010אל החדר שהדפדפן שלכם הצטרף אליו; stat 3 בהצלחה, 4 בכישלון
הצהרה אחת, שבעה צרכנים.
המפתחות ברשומת cpi_methods הם לא תיעוד. כל אחד מהם נקרא על ידי תת מערכת אחרת ברגע אחר, ואף אחת מתת המערכות האלה לא יודעת על האחרות. clearance נקרא על ידי שער ההפעלה. private נקרא על ידי מאמת מפתח ה-API, ובנפרד על ידי רשם כלי ה-MCP. fields נבדק על ידי הבודק שרץ לפני האימות ומהודר לסכמת zod כשסוכן פותח הפעלה. job נקרא על ידי התור, cache על ידי memcached ועל ידי כותרת הקצה, min_plan על ידי שער המסלול, security על ידי כותב היומן. הוספת מתודה ל-config.json מכריעה את כל השבעה בבת אחת, ולכן אין טבלת נתיבים, אין קובץ הרשאות ואין סכמה נפרדת לשמור מסונכרנת.
חיבור סוכן הוא שורה אחת.
זה כל משטח השילוב. נקודת הקצה של MCP היא שרת Streamable HTTP על פורט 3012 שמופנה בפרוקסי ל-/mcp, והיא המקום היחיד בפלטפורמה שבו מפתח API נוסע ככותרת: כל מסלול אחר, כולל קריאת הלולאה המקומית שכל כלי מבצע חזרה אל /cpi, קורא api_key מתוך גוף ה-JSON. שתי עובדות מכריעות אם זה עובד בקנה המידה שלכם. רשימת הכלים נקבעת לכל הפעלה ולא נאפית לתוך המפתח, ולכן מפתח בגישה מלאה קולט מתודות שנשלחו אחרי הנפקתו בלי לגעת במפתח ובלי פריסה מחדש. ואותו מפתח עצמו מוסר למודל את כל 331 הכלים ברשימה אחת, בלי קיבוץ ובלי עימוד, וזה מעבר למה שרוב המודלים בוררים היטב. הדרך היחידה לצמצם אותה היא להנפיק מפתח צר יותר, כי מפתח מותאם רושם בדיוק את api_allow_methods שלו ולא יותר.
תשעה דברים שה-API הזה לא עושה, כולל שלושה שלוח הבקרה רומז שכן.
- למפתח יש ארבעה מצבים בממשק, 1 טיוטה, 2 מושעה, 3 פעיל ו-4 מחיקה, ורק מצב 4 נדחה. מפתח בטיוטה או מושעה עדיין מזדהה ועדיין מבצע, גם ב-REST וגם ב-MCP. הבדיקה חיה ב-cpi/api_module/index.mjs שורות 131 עד 199.
- רשימת הדומיינים המותרים נשמרת על המפתח וניתנת לעריכה בממשק, אבל כל ענף שהיה אוכף אותה מוער כהערה. אל תתכננו סביבה.
- אין מגבלת קצב על /cpi. שלושת המגבילים ב-router_module מורכבים על /login ועל ארבעה נתיבי טפסים, ומקרה ה-cpi מועבר היישר לפורט 3007 בלי שום middleware לפניו. מתודות ציבוריות מוגנות על ידי מוצר ההגנה מבוטים, לא על ידי המפיץ.
- קודים שליליים מתקפלים. רק הרצועה מ-400- עד 499- ממופה לסטטוס HTTP משלה, ולכן 401- ו-403- מגיעים כ-401 וכ-403 וכל השאר, כולל ה-1- הנפוץ מאוד, הוא 400 שטוח. קראו code ו-data, אף פעם לא את הסטטוס לבדו.
- private היא שקריות ולא הצהרה. 321 רשומות משמיטות את המפתח לגמרי, ולכן מתודה שנשלחה זה עתה ניתנת לקריאה במפתח אלא אם מישהו זוכר לסמן אותה.
- חמש רשומות לא נושאות clearance שמיש, שלוש מחרוזת ריקה ושתיים כלום בכלל, והשער זורק על clearance שקרי. הן אמורות להיכשל קשות מעל HTTP. אם הן פנימיות לברוקר בלבד שאף פעם לא רואות בקשה, זה לא מאומת.
- הקטלוג בהיקף האפליקציה מסנן לפי ערכי clearance בשם studio ו-user_group שאף מתודה לא נושאת, ולכן הוא מחזיר את 86 מתודות ה-admin ומשמיט בשקט את 5 המתודות של user_access, שכוללות את dbs_read ואת get_app_info.
- MCP Server מופיע כסוג פריסה באשף ובתיעוד, ו-deploy_module דוחה אותו עם code -2 ועם ההודעה deploy_type in beta. משטח ה-MCP שנשלח הוא נקודת הקצה האחת בפלטפורמה שמפתח API פותח, לא פריסה לכל פרויקט.
- כל ספירה בעמוד הזה נקראה מעותק המאגר של config.json. config_dev.json מציג 1026 מוצהרות ו-334 שאינן private, וקונפיגורציית המאסטר החיה לא נקראה, ולכן התייחסו למספרים האלה כאל הצורה ולא כאל הסך המדויק של היום. voice_module שקורא 46 מתוך 46 שאינן private שווה אישור מול הכוונה.
השאלות שמתגבשות אצלכם עכשיו
שישה דברים שהמסמך הטכני לא יגיד לכם, נענים מול הקוד שנשלח ולא מול הכוונה.
לצפות בקריאה יוצאת וחוזרת.
קראו את הקטלוג לפני שאתם כותבים שורה מולו.
קריאה אחת, get_account_system_api_methods, מוסרת בחזרה כל מתודה שמותר לכם להגיע אליה, כל אחת מצומצמת לתיאור שלה, לשדות המוקלדים שלה ולמיקרו-שירות שהוא הבעלים שלה. אלה בדיוק אותן הצהרות שסכמות כלי ה-MCP מהודרות מהן, ולכן הרשימה שנמסרת לסוכן והרשימה שאתם כותבים מולה יוצאות מקובץ אחד ולא משני מסמכים שנפרדים. קראו אותו קודם, החליטו לאילו מתודות באמת התכוונתם, ואז הנפיקו מפתח מותאם שמחזיק רק אותן. מפתח בגישה מלאה הוא הדרך המהירה ביותר להתחיל והדבר הרחב ביותר שאפשר למסור למודל.