מדריך היוצרים

בנו ערכת צבעים, חבילת חוקים, חבילת Habits, שרת MCP או תבנית Rex ופרסמו אותם בחנות של Ingot עם כלי שורת הפקודה ingot, מתיקייה ריקה ועד דף בחנות בכתובת /marketplace/<publisher>.<name>.

בטא. הפרסום בחנות חדש. השלבים כאן עובדים היום מול www.ingotide.com; פקודות ומגבלות עוד עשויות להשתנות. בזמן הבטא ייתכן שהחבילה @ingotide/cli עוד לא נמצאת ב-npm: אם npm install לא מוצא אותה, בנו אותה מהקוד (שלב 1).

מה תעשו: תתקינו את ה-CLI, תיצרו פרופיל מפרסם, תיצרו שלד של תוסף, תבדקו אותו בפרויקט אמיתי, תארזו אותו כקובץ .ingotx, תיצרו טוקן לפרסום ותפרסמו. עדכון והסרה מופיעים בסוף. לתוסף הראשון כדאי להקדיש כ-15 דקות.

1. התקנת ה-CLI

צריך Node.js בגרסה 22 ומעלה.

npm install -g @ingotide/cli
ingot --version

אפשר גם להריץ כל פקודה בלי להתקין: npx @ingotide/cli <command>.

אם החבילה עוד לא ב-npm, בנו אותה מהמאגר של פורטל Ingot:

git clone https://github.com/yaghobieh/ingot-portal.git
cd ingot-portal/packages/ingot-cli
npm ci && npm run build && npm link
ingot --version

ingot help מציג את כל הפקודות, ו-ingot <command> --help מציג את האפשרויות של כל פקודה. הרשימה המלאה נמצאת במדריך ה-CLI.

2. יצירת פרופיל מפרסם

כל מה שאתם מפרסמים שייך למפרסם. המזהה שלו הוא השדה publisher בכל ingot.json והחלק הראשון של כל מזהה תוסף (acme.react-rules).

  1. התחברו לחשבון Ingot שלכם.
  2. פתחו את לוח בקרה › מפרסם (/dashboard/publisher).
  3. בחרו מזהה (3 עד 32 אותיות לטיניות קטנות, ספרות ומקפים), שם לתצוגה ואם תרצו גם אתר.
  4. לחצו על יצירת מפרסם.

אי אפשר לשנות את המזהה אחר כך. מזהים שנראים רשמיים (ingot, zaprex, ingot-…, official, support ודומים) שמורים.

3. יצירת שלד לתוסף

ingot init יוצר תיקייה עם ingot.json תקין, README, CHANGELOG, רישיון MIT, .gitignore, קבצי התחלה לסוג שבחרתם, ו-workflow של GitHub Actions שמפרסם כשדוחפים תגית גרסה.

ingot init my-theme --type theme --publisher acme
cd my-theme

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

סוג--typeקבצי התחלהמה זה הופך להיות ב-Ingot
ערכת צבעיםthemethemes/<name>.jsonערכת צבעים תחת Settings › Appearance
חבילת חוקיםrulesrules/<name>.mdcקבצים בתיקייה .ingot/rules/ של הפרויקט
חבילת Habitshabitshabits/<id>.jsonדפוסים ש-Habits מחפש
שרת MCPmcpserver/index.mjs (שרת stdio שעובד)רשומה ב-.ingot/mcp.json
תבנית Rexrex-templatetemplates/<name>.mdתבנית ש-Rex מריץ ב-Zaprex

פקודה אחת לכל סוג:

ingot init my-theme    --type theme        --publisher acme --yes
ingot init react-rules --type rules        --publisher acme --yes
ingot init team-habits --type habits       --publisher acme --yes
ingot init word-tools  --type mcp          --publisher acme --yes
ingot init nightly-fix --type rex-template --publisher acme --yes

--yes מקבל את ברירות המחדל. הוסיפו --ci gitlab כדי לקבל pipeline של GitLab במקום GitHub Actions, או --ci none בלי קובץ CI. סוגי תוספים מסביר כל סוג ואת הקבצים שלו.

4. הוספת חוקים, Habits, פקודות ושרתי MCP

חבילה יכולה לכלול יותר מהסוג הראשי שלה: חבילת חוקים יכולה להוסיף פקודות סלאש, ערכת צבעים יכולה לכלול קובץ חוקים, וכן הלאה. ingot add כותב את הקובץ ואת הרשומה שלו ב-ingot.json בבת אחת:

ingot add rule testing --description "How we write tests"
ingot add habit no-any --match ":\s*any\b" --rule "- Don't use the any type."
ingot add command review --description "Review the open files"
ingot add mcp acme-api --command npx --env ACME_API_KEY="Your Acme API key" -- -y @acme/mcp-server
ingot add mcp docs --url https://mcp.acme.dev/sse
  • חוקים הם קבצי Markdown או .mdc עם frontmatter אופציונלי (description, globs, alwaysApply), בדיוק כמו בחוקים.
  • פקודות הופכות ל-/<name> בצ'אט של הסוכן.
  • שרתי MCP מריצים פקודה מקומית או מתחברים לכתובת https:// מרוחקת. רשמו משתני סביבה עם תיאור של מה להזין; לעולם אל תשימו סוד בחבילה.

ערכו את הקבצים ובדקו את העבודה בכל שלב:

ingot validate

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

5. בדיקה בפרויקט אמיתי

ingot try מתקין את התוסף בפרויקט כמו שהחנות תתקין אותו:

ingot try ~/code/my-app
  • כל החבילה מועתקת אל ~/code/my-app/.ingot/extensions/acme.my-theme/.
  • החוקים נכנסים ל-.ingot/rules/, הפקודות ל-.ingot/commands/, ושרתי MCP מתווספים ל-.ingot/mcp.json (כש-${extensionDir} מוחלף בתיקייה האמיתית).

פתחו את הפרויקט ב-Ingot והשתמשו בתוסף: עברו לערכת הצבעים, שאלו את הסוכן משהו שהחוקים שלכם מכסים, הריצו /review, או קראו לכלים של שרת ה-MCP. הריצו ingot try שוב אחרי כל שינוי. כדי לבטל, מחקו את הקבצים שהועתקו.

6. אריזה

ingot package

הפקודה בודקת שוב וכותבת את acme.my-theme-0.1.0.ingotx: קובץ ZIP עם ingot.json, ה-README, ה-CHANGELOG והרישיון, וכל קובץ שהמניפסט מצביע עליו. רק הקבצים האלה נכנסים, ועוד כל מה שרשמתם תחת files ב-ingot.json. האריזה דטרמיניסטית (אותם מקורות נותנים אותם בייטים), וה-CLI מדפיס את ה-SHA-256.

מגבלות: 4 MB לחבילה, 20 MB אחרי פריסה, 2 MB לקובץ, 200 קבצים. הפרטים במניפסט.

7. יצירת טוקן לפרסום

ה-CLI מפרסם עם טוקן לפרסום, לא עם הסיסמה שלכם.

  1. פתחו את לוח בקרה › מפרסם.
  2. תחת טוקנים לפרסום, תנו שם (למשל Laptop או GitHub Actions) ובחרו מתי יפוג התוקף: 30, 90, 180 או 365 ימים.
  3. לחצו על יצירת טוקן והעתיקו אותו. הוא מתחיל ב-ingot_pub_ ומוצג פעם אחת בלבד.

טוקנים יכולים רק לפרסם ולהסיר בשם המפרסם שלכם; הם לא יכולים לקרוא או לשנות שום דבר אחר בחשבון. Ingot שומר רק hash של כל טוקן. בטלו טוקן באותו דף והוא מפסיק לעבוד מיד. השתמשו בטוקן נפרד לכל מחשב או מערכת CI כדי שתוכלו לבטל כל אחד לחוד.

8. התחברות ופרסום

ingot login

הדביקו את הטוקן כשתתבקשו (הקלט מוסתר). ה-CLI בודק אותו מול החנות ושומר אותו ב-~/.ingot/cli/credentials.json, שרק אתם יכולים לקרוא. ingot whoami מראה לאיזה מפרסם הוא שייך.

אחר כך פרסמו מתיקיית התוסף:

ingot publish

publish אורז את התיקייה ומעלה אותה. כדי להעלות קובץ שכבר בניתם, העבירו אותו: ingot publish acme.my-theme-0.1.0.ingotx. החנות בודקת את החבילה שוב, שומרת את הגרסה ומדפיסה את הדף שלה:

Publishing acme.my-theme@0.1.0 to https://www.ingotide.com…
Published acme.my-theme@0.1.0.
Store page: https://www.ingotide.com/marketplace/acme.my-theme

התוסף מופיע עכשיו בחנות תחת מהקהילה, בקטגוריה שלו ובחיפוש, עם תג קהילה. בדף שלו יש את ה-README, היסטוריית הגרסאות וכפתור הורדת ‎.ingotx.

פתיחת תוספים מהקהילה ישירות מהחנות (קישור ההתקנה ingot://) דורשת גרסה חדשה יותר של Ingot. עד אז, דף הפריט מסביר איך להתקין ידנית: מורידים את ה-.ingotx, פורסים אותו ומריצים ingot try <project> --cwd <folder>.

9. פרסום עדכונים

כל העלאה צריכה גרסה חדשה וגבוהה יותר. העלו אותה עם ingot version, שגם מוסיף כותרת ל-CHANGELOG.md:

ingot version patch        # 0.1.0 → 0.1.1 (or minor, major, or an exact 1.2.0)
ingot publish

הגרסאות לפי ניהול גרסאות סמנטי: 1.2.3, או גרסה מוקדמת כמו 1.3.0-beta.1. החנות דוחה גרסה שכבר הועלתה או שאינה גבוהה מהאחרונה, כך שמספר גרסה לעולם לא חוזר, גם אחרי הסרה.

כדי לפרסם מ-CI, עשו commit, תייגו ודחפו; ה-workflow מ-ingot init עושה את השאר:

git commit -am "v0.1.1" && git tag v0.1.1 && git push --follow-tags

ההגדרה לוקחת חמש דקות: ראו פרסום מ-CI/CD.

10. הסרה מהחנות

ingot unpublish acme.my-theme@0.1.1   # one version
ingot unpublish acme.my-theme         # every version

הריצו בתוך תיקיית התוסף בלי מזהה כדי להשתמש ב-ingot.json. ה-CLI מבקש להקליד את שם התוסף לאישור; בסקריפטים העבירו --yes. אפשר גם ללחוץ על הסרה מהחנות ליד התוסף בלוח בקרה › מפרסם.

הסרה מוציאה את הגרסה (או את כל התוסף) מהחנות, מה-sitemap ומהחיפוש. עותקים שכבר הותקנו ממשיכים לעבוד. מספר הגרסה נשאר תפוס: כדי לחזור, פרסמו את הגרסה הבאה.

לפני שאתם מפרסמים באמת, קראו את כללי החנות. כל שדה מוסבר במניפסט, וכל אפשרות במדריך ה-CLI.