מדריך היוצרים
בנו ערכת צבעים, חבילת חוקים, חבילת Habits, שרת MCP או תבנית Rex ופרסמו אותם בחנות של Ingot עם כלי שורת הפקודה ingot, מתיקייה ריקה ועד דף בחנות בכתובת /marketplace/<publisher>.<name>.
@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).
- התחברו לחשבון Ingot שלכם.
- פתחו את לוח בקרה › מפרסם (/dashboard/publisher).
- בחרו מזהה (3 עד 32 אותיות לטיניות קטנות, ספרות ומקפים), שם לתצוגה ואם תרצו גם אתר.
- לחצו על יצירת מפרסם.
אי אפשר לשנות את המזהה אחר כך. מזהים שנראים רשמיים (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 |
|---|---|---|---|
| ערכת צבעים | theme | themes/<name>.json | ערכת צבעים תחת Settings › Appearance |
| חבילת חוקים | rules | rules/<name>.mdc | קבצים בתיקייה .ingot/rules/ של הפרויקט |
| חבילת Habits | habits | habits/<id>.json | דפוסים ש-Habits מחפש |
| שרת MCP | mcp | server/index.mjs (שרת stdio שעובד) | רשומה ב-.ingot/mcp.json |
| תבנית Rex | rex-template | templates/<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 מפרסם עם טוקן לפרסום, לא עם הסיסמה שלכם.
- פתחו את לוח בקרה › מפרסם.
- תחת טוקנים לפרסום, תנו שם (למשל
LaptopאוGitHub Actions) ובחרו מתי יפוג התוקף: 30, 90, 180 או 365 ימים. - לחצו על יצירת טוקן והעתיקו אותו. הוא מתחיל ב-
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.