تثبیت وضعیت تصویر در ویرایشگر Kiro با مدل Gemini و پروتکل MCP

تصور کنید می‌خواهید یک جزئیات کوچک را در یک تصویر پیچیده تغییر دهید، اما هر بار که درخواستی می‌فرستید، تمام صحنه، نورپردازی و چهره‌ها به‌هم می‌ریزند. این «عذاب بی‌وضعیت» (Stateless Suffering) در هنر هوش مصنوعی، جایی که هر تغییر کوچک نیازمند بازنویسی کامل تمام توصیفات صحنه است، اکنون با معرفی ابزار nb2lite-skill-kiro به پایان رسیده است.

به نقل از مستندات منتشرشده در ۲۳ جولای ۲۰۲۶، این ابزار تخصصی به عامل (Agent) هوش مصنوعی Kiro اجازه می‌دهد تا با استفاده از مدل gemini-3.1-flash-lite-image (که به اختصار NB2Lite نامیده می‌شود)، ویرایش‌های متوالی و حافظه‌محور (Stateful) را روی تصاویر اجرا کند. این قابلیت در ادامه تلاش‌های گوگل برای دموکراتیزه کردن ابزارهای بصری است؛ درست مانند زمانی که دسترسی رایگان به تولید تصویر شخصی‌سازی‌شده را برای کاربران آمریکایی فراهم کرد تا کاربرگان بیشتری بتوانند با مدل‌های Gemini تعامل داشته باشند. در مدل‌های سنتی تولید تصویر، فرآیند مانند یک خیابان یک‌طرفه است: شما پرامپتی می‌فرستید، پیکسل‌ها را دریافت می‌کنید و مدل بلافاصله تمام جزئیات جلسه را فراموش می‌کند. این موضوع منجر به یک جریان کاری ناکارآمد می‌شود که در آن کاربران باید کل صحنه را دوباره توصیف کنند و امیدوار باشند که شخصیت، نورپردازی و ترکیب‌بندی در این چرخه باقی بماند (که معمولاً چنین نمی‌شود).

همان‌طور که در تحلیل قبلی ما درباره‌ی OwnCode اشاره کردیم که Gemini را مجبور به نوشتن اپلیکیشن‌های کامل می‌کرد، این ابزار جدید تمرکز را از تولید کد به «تداوم بصری» منتقل می‌کند. در این رویکرد، بوم تصویر به جای یک خروجی یک‌بارمصرف و قابل دورریز، به عنوان یک وضعیت پایدار (Persistent State) در نظر گرفته می‌شود.

سازوکار: رابط برنامه‌نویسی Interactions API

قلب تپنده این قابلیت، Interactions API است؛ یک نقطه اتصال وضعیت‌دار (Stateful) در Gemini که به مدل اجازه می‌دهد بستر بصری را در سمت سرور و از طریق یک شناسه منحصر‌به‌فرد (interaction_id) حفظ کند. برخلاف نقاط اتصال استاندارد، این API اجازه می‌دهد مدل حافظه بصری را در سرورهای گوگل نگه دارد.

طبق اعلام توسعه‌دهنده، جریان منطقی این سیستم به شرح زیر است:

• کلاینت تابعی مانند client.interactions.create(...) را با یک پرامپت و تنظیم store=True فراخوانی می‌کند.
• پاسخ سیستم شامل یک interaction_id است؛ شناسه‌ای که مانند یک «گیره» برای حفظ وضعیت بصری آن مرحله در سرورهای گوگل عمل می‌کند.
• در فراخوانی‌های بعدی، کاربر شناسه قبلی (previous_interaction_id) را ارسال می‌کند.
• مدل بر اساس این شناسه، ویرایشی روی بوم موجود اعمال کرده و تداوم شخصیت، استایل و پیکسل‌ها را حفظ می‌کند.

این حافظه سیستمی به این معناست که کاربر به جای توصیف مجدد یک «روباه آبی در جنگلی مه‌آلود در سپیده‌دم با نوری ملایم، یک روسری قرمز و سه درخت غان در سمت چپ»، صرفاً می‌گوید: «یک فانوس در دستش قرار بده». در اینجا، به جای مبارزه با «انحراف پرامپت» (Prompt Drift)، بستر ذخیره‌شده، بقیه صحنه را به‌طور خودکار نگه می‌دارد.

یکپارچگی با پروتکل زمینه مدل (MCP)

برای اجرای این سازوکار در Kiro، توسعه‌دهنده یک سرور پروتکل زمینه مدل (Model Context Protocol یا به اختصار MCP) به نام nb2lite-agent طراحی کرده است. این سرور در واقع یک اپلیکیشن FastMCP تک-فایلی است که در فایل server.py قرار دارد.

پروتکل MCP یک استاندارد باز برای اتصال دستیاران هوش مصنوعی به ابزارها و داده‌ها است. پیش از این استاندارد، دادن دسترسی به یک سرویس برای هر دستیار نیازمند یکپارچگی سفارشی بود (تعداد دستیاران × تعداد سرویس‌ها). MCP این پیچیدگی را از بین می‌برد: نویسنده ابزار تنها یک سرور می‌نویسد که ابزارهای تایپ‌شده را ارائه می‌دهد و هر کلاینت سازگار با MCP — از جمله Kiro، Claude Code و Claude Desktop — می‌تواند آن‌ها را از طریق JSON-RPC روی stdio شناسایی و فراخوانی کند.

یک سرور MCP معمولاً به عنوان یک فرآیند محلی کوچک اجرا می‌شود. هنگام اجرای کلاینت، سیستم می‌پرسد «چه ابزارهایی داری؟» و مدل می‌تواند از آن پس آن‌ها را مانند توابع استاندارد فراخوانی کند. سرور nb2lite-agent دقیقاً چهار ابزار ارائه می‌دهد:

• generate_image: تبدیل متن به یک تصویر ۱ کیلو-پیکسلی. این ابزار فایل را به‌صورت محلی ذخیره کرده و مسیر فایل و یک Interaction ID را باز می‌گرداند.
• edit_image: یک ویرایش وضعیت‌دار که شناسه تعامل قبلی و توصیفی از تغییرات خاص را دریافت می‌کند.
• edit_local_image: هر فایل تصویر محلی موجود را از طریق base64 آپلود کرده و ویرایشی روی آن اعمال می‌کند؛ این ابزار به عنوان نقطه ورود برای فایل‌هایی که توسط مدل ساخته نشده‌اند عمل می‌کند.
• get_help: گزارش پیکربندی زنده، شامل وضعیت کلید API، مدل فعال، دایرکتوری خروجی و مرجع کامل ابزارها.

نقش مهارت‌های Kiro (Kiro Skills)

اگر سرور MCP «دست‌های» سیستم باشد، Kiro skill در واقع «حافظه عضلانی» آن است. یک «مهارت» شامل یک فایل Markdown (SKILL.md) و منابع bundled است که در زمینه (Context) Kiro بارگذاری می‌شوند تا به او جریان کاری بهینه را بیاموزند. این مهارت‌ها در مسیر .kiro/skills/<skill-name>/ در یک پروژه قرار می‌گیرند. وقتی Kiro یک عبارت ماشه‌ای (Trigger phrase) مطابق با توصیف مهارت شناسایی کند، راهنمایی‌های مربوطه را به‌طور خودکار فعال می‌کند.

برای nb2lite-image، این مهارت محدودیت‌های عملیاتی دقیقی را برای جلوگیری از خطا کدگذاری کرده است:

• ترتیب تشخیص: در صورت بروز مشکلات در راه‌اندازی، ابتدا باید get_help فراخوانی شود؛ زیرا اگر کلید API موجود نباشد، سایر ابزارها شکست می‌خورند.
• پرامپت‌نویسی افزایشی: هنگام استفاده از ابزار ویرایش، تنها تغییر را توصیف کنید، نه کل صحنه را. هدف توصیف «تفاضل» (Diff) است، نه کل نقشه.
• زنجیره شناسه‌ها: همیشه آخرین Interaction ID را به زنجیره متصل کنید. هر مرحله یک شناسه جدید بازمی‌گرداند. ویرایش بر اساس یک شناسه قدیمی باعث «شاخه‌بندی» (Fork) بی‌صدا در جلسه از یک وضعیت قدیمی‌تر می‌شود که به عنوان یک باگ ظریف و آزاردهنده توصیف شده است.
• مدیریت هزینه: تولید تصاویر هزینه دارد. مهارت به عامل دستور می‌دهد که ویرایش‌های مرتبط را دسته‌بندی کند و برای پیش‌نویس‌های اولیه از thinking_level: low استفاده کند.

برای اینکه نصب بدون دردسر باشد، این مهارت به‌صورت خودکفا (Self-contained) طراحی شده است. این بسته شامل سرور MCP (server.py)، نیازمندی‌های آن، یک اسکریپت نصب و یک نسخه داخلی از راهنمای توسعه‌دهنده Interactions API است.

محدودیت‌های فنی و عملکرد

مدل NB2Lite برای بهره‌وری بالا طراحی شده است و تولید تصاویر را در کمتر از ۲ ثانیه انجام می‌دهد و رندرینگ متنی استواری را در بیش از ۲۵ زبان ارائه می‌کند. با این حال، توسعه‌دهنده به چندین محدودیت حیاتی در API اشاره می‌کند که سرور باید آن‌ها را مدیریت کند تا از خطاهای HTTP 400 جلوگیری شود:

سطوح تفکر (Thinking Levels)
API دو سطح اصلی را پشتیبانی می‌کند: low (پیش‌فرض، برای پیش‌نویس‌های سریع) و high (برای رندرهای پیچیده، چیدمان دقیق متن و ترکیب‌بندی precise شخصیت‌ها). اگرچه مشخصات کلی API سطوحی مانند «minimal» و «medium» را لیست کرده است، اما API زنده برای این مدل خاص، این سطوح را با خطای HTTP 400 رد می‌کند. سرور این مورد را انتزاع (Abstract) می‌کند تا کاربر مجبور نباشد از طریق آزمون و خطا با آن آشنا شود.

نسبت ابعاد و تداوم (Aspect Ratios)
نسبت‌های پشتیبانی شده شامل ۱:۱، ۱۶:۹، ۹:۱۶، ۴:۳ و ۳:۴ است. این نسبت‌ها در اولین فراخوانی generate_image انتخاب شده و در ویرایش‌های وضعیت‌دار به ارث می‌رسند. از آنجا که تغییر نسبت ابعاد در میانه‌ی جلسه باعث تخریب پیوستگی پیکسل‌ها می‌شود، ابزار edit_image به‌طور عمدی ورودی جدید برای نسبت ابعاد نمی‌پذیرد.

مدیریت فایل و مدیریت خطا
تصاویر با یک قرارداد نام‌گذاری سخت‌گیرانه ذخیره می‌شوند: gen_<timestamp>_<uuid8>.jpg و در صورت لزوم پیشوندهای edit_ یا edit_local_ اضافه می‌شوند. پسوند UUID مانع از آن می‌شود که تولیدات هم‌زمان، فایل‌های یکدیگر را بازنویسی کنند. برای کمک به عامل هوش مصنوعی در بازیابی از شکست، خطاها به جای خطاهای پروتکل، به صورت رشته‌های متنی همراه با علامت 🔴 بازگردانده می‌شوند تا عامل بتواند شکست را بخواند و واکنش مناسب نشان دهد.

مسیرهای استقرار و عیب‌یابی

این پروژه چهار مسیر نصب را برای انعطاف‌پذیری در محیط‌های مختلف توسعه‌دهندگان ارائه می‌دهد:

۱. Bootstrap (کلون و بوت‌استرپ): کاربران مخزن را کلون کرده و ./init.sh را اجرا می‌کنند. این تنظیم تک-دستوری، وابستگی‌ها را نصب کرده، سرور MCP را در .mcp.json ثبت می‌کند و کلید API Gemini را درخواست کرده و در ~/gemini.key ذخیره می‌کند.
۲. یکپارچگی با پروژه: با استفاده از دستور make init TARGET=/path/to/your/project ARGS='--output-dir ./images'، مهارت به پوشه .kiro/skills/nb2lite-image/ پروژه کپی شده و ورودی مربوطه در .mcp.json آن پروژه نوشته می‌شود. این روش در صورت وجود از ~/gemini.key استفاده مجدد می‌کند.
۳. ثبت دستی: شامل نصب وابستگی‌ها از طریق pip install -r requirements.txt و افزودن دستی ورودی nb2lite-agent به فایل .mcp.json است. در این حالت، command به عنوان python و args به صورت [.kiro/skills/nb2lite-image/mcp/server.py] تعریف می‌شود و کلیدهای env برای GEMINI_API_KEY و IMAGE_OUTPUT_DIR تنظیم می‌گردند.
۴. داکر (Docker): استفاده از ایمیج xbill9/nb2lite-agent. این روش نیازمند یک mount خاص (-v /abs/path/to/project:/abs/path/to/project) و دایرکتوری کاری (-w /abs/path/to/project) است، زیرا سرور برای ذخیره تصاویر و خواندن فایل‌های محلی باید پروژه را در همان مسیر مطلق میزبان ببیند.

در صورت بروز مشکل در تنظیمات، توسعه‌دهنده بررسی‌های زیر را پیشنهاد می‌کند:

• ناپدید شدن سرور: اگر سرور MCP در رابط کاربری ظاهر نشد، Kiro را در دایرکتوری پروژه ری‌استارت کنید.
• خطاهای کلید API: اگر ابزارها پیام 🔴 GEMINI_API_KEY is not set را بازگرداندند، کاربران باید source set_env.sh را اجرا کرده (یا کلید را دستی export کنند) و مجدداً ری‌استارت نمایند.
• تشخیص کلی: از Kiro بخواهید ابزار get_help را فراخوانی کند تا وضعیت زنده پیکربندی گزارش شود.

تجربه عملی: یک جلسه در واقعیت

پس از نصب، ابزار از طریق انگلیسی ساده تعامل می‌کند. یک جریان کاری وضعیت‌دار به این شکل است:

گام ۱: تولید اولیه
کاربر: «یک کلبه دنج در جنگلی برفی در هنگام غروب، ۱۶:۹ تولید کن.»
فراخوانی Kiro: generate_image(prompt="A cozy log cabin in a snowy forest at dusk, warm light in the windows", aspect_ratio="16:9", thinking_level="low")
نتیجه: ذخیره در ./gen_1784759001_a1b2c3d4.jpg با Interaction ID v1_ChdpRU5...

گام ۲: ویرایش آگاه از وضعیت
کاربر: «عالیه. دود لوله‌ای که از دودکش بلند می‌شود را اضافه کن.»
فراخوانی Kiro: edit_image(previous_interaction_id="v1_ChdpRU5...", edit_prompt="add gentle smoke curling from the chimney")
نتیجه: ذخیره در ./edit_1784759050_e5f6a7b8.jpg با یک Interaction ID جدید v1_Xk9mPq2...

گام ۳: پالایش بیشتر
کاربر: «حالا شب کن، با شفق قطبی در آسمان.»
Kiro ادامه می‌دهد و از آخرین ID استفاده می‌کند. کلبه، درختان و دود دودکش ثابت می‌مانند و تنها آسمان تغییر می‌کند. این امر «قمار تداوم» (Continuity Roulette) در پرامپت‌نویسی سنتی را حذف می‌کند. این رویکرد تکرارشونده به کاربر اجازه می‌دهد تا مانند یک کارگردار، صحنه را تکامُل دهد؛ مشابه آنچه گوگل در قابلیت Video Remix برای تبدیل خاطرات تصویری به استودیو تولید پیاده کرد، جایی که کاربر می‌تواند بر روی محتوای موجود اثر بگذارد.

جریان کاری فایل‌های خارجی
کاربر: «تصویر ./whiteboard-sketch.png را بگیر و آن را به عنوان یک موکاپ سه‌بعدی تمیز از محصول رندر کن.»
فراخوانی Kiro: edit_local_image(image_path="./whiteboard-sketch.png", edit_prompt="render this hand-drawn sketch as a high-fidelity 3D product mockup", aspect_ratio="4:3")
این عمل یک Interaction ID تولید می‌کند که اجازه می‌دهد پالایش‌های بعدی با تغییر به ابزار edit_image به‌صورت وضعیت‌دار پیش بروند.

بررسی محصول توسط سازنده (Dogfooding)

نویسنده بر رویکرد «سگ-غذاخوری» (Dogfooding) تأکید می‌کند؛ یعنی استفاده از محصول خود برای کارهای واقعی جهت کشف نقاط ضعف. این تفاوت میان «باید کار کند» و «من هر روز با این خروجی می‌گیرم» است. این مخزن در هر لایه خود را تست می‌کند: مهارت در داخل مخزن خودش فعال است، بنابراین هر جلسه توسعه به عنوان یک تست یکپارچگی عمل می‌کند. علاوه بر این، تست‌های یکپارچگی (make test) همان چهار ابزار MCP را علیه API زنده اجرا می‌کنند که کاربر نهایی با آن‌ها مواجه است.

تصویر شاخص این مقاله نیز با استفاده از ابزار generate_image در یک جلسه Kiro در همین مخزن تولید شده است. برای دستیابی به این نتایج، نویسنده از thinking_level: high برای رندر پیچیده یک فضای کاری هوش مصنوعی آینده‌محور استفاده کرد. پرامپت، یک تصویر تکنولوژی با تم تاریک، یک ترمینال درخشان در سمت چپ، یک پنل تولید تصویر در سمت راست و یک لوگوی نئونی آبی «K» در مرکز به عنوان پل ارتباطی را درخواست کرده بود.

این خروجی خاص چندین نکته فنی کلیدی را ثابت می‌کند:

• دقت متن: برچسب‌های "nb2lite-image" و "Powered by Gemini • Built for Kiro" بدون غلط املایی رندر شده‌اند که قدرت سطح تفکر بالا برای چیدمان‌های متنی سنگین را نشان می‌دهد.
• معماری بصری: تصویر به‌طور لفظی معماری ابزار را تجسم می‌کند (کد در چپ، پیکسل در راست و Kiro در وسط).
• پتانسیل تکرار: اگر رنگ‌های تاکیدی نیاز به تغییر داشتند، نویسنده می‌توانست از edit_image با Interaction ID v1_ChdtbDloYW9iV0JaZlZqTWNQcHJDTXVBOBIXbWw5aGFvYldCWmZWak1jUHByQ011QTg استفاده کند تا رنگ‌های آبی را بدون تولید مجدد کل صحنه به بنفش تغییر دهد.

این تغییر، فرض بنیادین تولید تصویر با هوش مصنوعی را از یک «دستگاه قمار» (که اهرم را می‌کشید و امیدوارید نتیجه خوب باشد) به یک «بوم دیجیتال» تغییر می‌دهد که در آن شما مجموعه‌ای دقیق از تغییرات را هدایت می‌کنید. برای توسعه‌دهندگان و طراحان، این بدان معناست که اصطکاک «مهندسی پرامپت» برای تغییرات جزئی با یک جریان مکالمه طبیعی جایگزین شده است. قابلیت آپلود یک طرح تخته‌سفید (مانند whiteboard-sketch.png) و تبدیل آن به یک موکاپ سه‌بعدی با کیفیت بالا از طریق edit_local_image نشان‌دهنده گذار به ابزارهای طراحی تکرارشونده در سطح حرفه‌ای است. Dogfooding ارزان‌ترین راه برای کسب اعتبار است: خروجی واقعی ابزار اولین چیزی است که خواننده می‌بیند، و پرامپت اصلی و Interaction ID مستقیماً در مخزن به عنوان رسید ثبت شده‌اند.