תיעוד

משטח הכלים לסוכנים

סוכן יכול לתרגם דרך BetterTranslator באמצעות Model Context Protocol. זהו אותו תרגום שהחלון מבצע, דרך אותו מפעל ואותן הגנות, והתוצאות נוחתות באותה היסטוריית שיחה.

מה זה

המימוש הוא חבילת ה־C# ModelContextProtocol 2.1.0. השרת מזדהה כ־ bettertranslator

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

שני מסלולי תעבורה

שניהם רושמים את אותם עשרה כלים דרך אותו נתיב קוד.

צינור שהסוכן מפעיל, דרך bt mcp
נקודת קצה של HTTP המאוחסנת בתוך היישום, ממופה אל /mcp

יש הבדל התנהגותי אחד. שרת צינור שהופעל בנפרד אינו נושא חלון שאפשר לדבר אליו, ולכן הכלי שמציג רשומה בממשק מדווח שאין חלון: show_in_gui

עשרת הכלים

בדיקה מוודאת שהמשטח המוגש מורכב בדיוק מעשרת אלה ומשום דבר אחר.

כלי	מה הוא עושה
translate_text	סינכרוני. מקבל את הטקסט ואת שפת המקור ושפת היעד, ומשיב בתוצאה, במודל, בספירת טוקנים, במשך, בהערה כלשהי ובמזהה הרשומה שנשמרה.
translate_file	אסינכרוני. משיב במזהה משימה ובמצב בתור, ומחזיר שגיאה עוד לפני הכניסה לתור כאשר הקובץ אינו קיים או כאשר אין קורא לפורמט.
translate_batch	אסינכרוני. משיב במזהה משימה, בתיקייה ובמספר הקבצים. נלקחים רק הקבצים שנמצאים ישירות בתוך התיקייה.
job_status	כלי התשאול לשתי המשימות האסינכרוניות. משיב במצב, בהתקדמות ובשורת תוצאה לכל קובץ. אידמפוטנטי.
job_cancel	קבצים שכבר נכתבו נשארים כתובים, והשאר אינם מתורגמים. קריאה לכלי על משימה שהסתיימה אינה משנה דבר.
list_languages	ללא פרמטרים. משיב במודל ובשורה לכל שפה הנושאת את הקוד, השם, שם הלשון במקור, הכתב, כיוון הכתיבה, הזמינות והנימוק.
list_models	ללא פרמטרים. משיב בשם, בקובץ, בנתיב, בגודל ובדגלי מותקן ונבחר של כל מודל.
select_model	מתאים לפי שם, שם קובץ או נתיב מלא. הבחירה נשמרת ושורדת מעבר לשרת, וחלון פועל קולט אותה מיד.
show_in_gui	הכלי היחיד שזקוק לחלון. בלעדיו הוא מחזיר שגיאת כלי שאומרת זאת.
get_entry	קורא תרגום שמור אחד לפי מזהה. אין כלי שמפרט רשומות. המקור והתוצאה נחתכים, והחיתוך מציין כמה תווים היו בסך הכול.

הזיכרון הוא אפשרות בכלי הטקסט בלבד, והוא כבוי אלא אם מבקשים אותו. הוא אינו קיים בכלי הקובץ או התיקייה: use_memory

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

מזהי משימות ותשאול

המזהים נספרים כלפי מעלה החל מ־ job_0001

משימה אחת רצה בכל רגע, ולכן משימה בתור ממתינה לזו שרצה. משימה מסתיימת ככושלת כאשר לא הפיקה תוצאות או כאשר כל תוצאה נכשלה, ואחרת ככזו שהושלמה. המצבים הם: queued running done failed cancelled

במה כל כלי משיב

כל תשובה נושאת מבנה קריא־למכונה בסגנון snake case לצד גוש Markdown קריא לאדם. שגיאה מדליקה את דגל השגיאה עם משפט פשוט וללא מבנה. הטבלאות הן טבלאות Markdown אמיתיות, וכל תא נחתך כדי שערך ארוך אחד לא יציף את התמליל.

איך מפעילים

נקודת הקצה כבויה כברירת מחדל. כשהיא מופעלת היא נקשרת ל־loopback: 127.0.0.1:8765

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

איך רושמים

דרך HTTP, כשהיישום פועל:

claude mcp add --transport http bettertranslator http://127.0.0.1:8765/mcp

כשמוגדר אסימון, הוסיפו את כותרת ה־authorization: --header "Authorization: Bearer <token>"

דרך צינור, בלי שהיישום פועל:

claude mcp add -s user bettertranslator -- "<path to>\cli\bt.exe" mcp

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

סירובים והרשת

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

כשמוגדר אסימון, כותרת ה־authorization מושווית בדיוק וכל דבר אחר נדחה.

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

אבחון חיבור מת

השורה הראשונה בפלט השגיאות התקני היא כותרת פתיחה:

bettertranslator mcp <version>, built <yyyy-MM-dd HH:mm>, from <path>

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

לאן הולכות התוצאות

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

רק כלי הטקסט מחזיר מזהה רשומה, וזה מה שקורא הרשומות וכלי ההצגה צורכים: entry_id

חזרה לתחילת העמוד