نحوه استفاده از AI OpenHands: راهنمای عملی برای تنظیمات، درخواستها و گردشکارهای واقعی
اگر همیشه آرزو داشتهاید که یک توسعهدهنده توانمند به صورت شبانهروزی با شما همبرنامهنویسی کند، AI OpenHands به طرز چشمگیری به این آرزو نزدیک است. این یک "مهندس هوش مصنوعی" متنباز است که میتواند مخزن (repo) شما را بخواند، کد بنویسد، ترمینالها را اجرا کند، اسناد را مرور کند و تکرار کند— درست مانند یک توسعهدهنده تازهکار که به سرعت یاد میگیرد و بیوقفه کار میکند. اما این قدرت زمانی آشکار میشود که آن را به درستی تنظیم کرده و یاد بگیرید که چگونه آن را هدایت کنید.
این راهنما شما را گام به گام در نحوه استفاده از AI OpenHands راهنمایی میکند— از نصب تا گردشکارهای پیشرفته— تا بتوانید با اطمینان سریعتر محصول خود را ارائه دهید.
- گزینههای نصب و شروع سریع
- اجرای OpenHands به صورت محلی یا با مدلهای ابری
- بهترین روشها برای درخواستها، مخازن و وظایف
- گردشکارهای اثباتشده برای کار روی ویژگیها، رفع اشکال، تستها و اسناد
- محافظتها، حریم خصوصی و همکاری
نکته قابل توجه: OpenHands به طور فعال توسط تیم All Hands و جامعه توسعه داده میشود. اسناد رسمی، ستاره راهنمای شما برای دستورالعملها و نکات فعلی هستند. همچنین میتوانید راهنماهای نصب عملی را از متخصصانی که تنظیمات محلی و ماشین مجازی (VM) را مستند کردهاند، دنبال کنید. برای اجرا با مدلهای محلی، اسناد شامل راهنماییهای خاصی نیز هستند.
AI OpenHands چیست— و چرا باید از آن استفاده کرد؟
AI OpenHands را به عنوان یک همتیمی هوش مصنوعی با صفحه کلید در نظر بگیرید. برخلاف دستیارهای فقط چت، OpenHands میتواند:
- باز کردن و خواندن فایلهای پروژه
- استفاده از ترمینال برای اجرای دستورات، تستها و لینترها
- ویرایش کد در فایلها و دایرکتوریها
- مرور وب (بسته به پیکربندی)
- ارائه و اعمال برنامههای گام به گام
این ویژگیها آن را برای وظایفی مانند پیادهسازی ویژگیها، رفع اشکالات، نوشتن تستها، ایجاد اسناد، بازسازی و مدرنسازی پایگاههای کد ایدهآل میسازد. به جای دست و پنجه نرم کردن با درخواستها و کپی/پیست کردن، شما به OpenHands یک هدف میدهید و اجازه میدهید تا تکرار کند، در حالی که شما حرکات آن را نظارت میکنید.
شروع سریع: سریعترین راه برای استفاده از OpenHands
چندین راه برای شروع وجود دارد. انتخاب شما بستگی به این دارد که آیا میخواهید از یک مدل زبانی بزرگ (LLM) ابری استفاده کنید یا همه چیز را به صورت محلی اجرا کنید.
گزینه A: استفاده از LLM ابری (آسانترین)
- برای نصب و اجرای برنامه، اسناد رسمی "Start Building" و "Getting Started" را دنبال کنید. به طور معمول:
- پیشنیازها را نصب کنید (Docker، Node، Python، Git بسته به مسیر)
- یک کلید API برای یک مدل ابری پشتیبانیشده ارائه دهید (به عنوان مثال، OpenAI، Anthropic، یا سایر مدلهایی که پروژه در آن زمان پشتیبانی میکند)
- رابط OpenHands را اجرا کرده و مخزن خود را متصل کنید
این مسیر شما را به سرعت با حداقل سربار محاسباتی به بهرهوری میرساند.
گزینه B: اجرای OpenHands با یک LLM محلی
- اگر ترجیح میدهید کد و درخواستها را خارج از ابر نگه دارید یا میخواهید از هزینههای API جلوگیری کنید، از راهنمای LLMهای محلی در اسناد رسمی استفاده کنید.
- یک مدل محلی سازگار را تنظیم کنید (از طریق Ollama یا سایر پشتیبانهای پشتیبانیشده در آن زمان)
- نقاط پایانی مدل و محدودیتهای context را پیکربندی کنید
- اطمینان حاصل کنید که دستگاه شما VRAM/CPU و فضای دیسک کافی دارد
گزینه C: استقرار در یک ماشین مجازی (VM)
- اگر به یک محیط اختصاصی نیاز دارید، متخصصان مستند کردهاند که چگونه OpenHands را روی یک VM راهاندازی کنید و در عرض چند دقیقه یک برنامه بسازید. این برای تیمهایی که یک نمونه مهندس هوش مصنوعی پایدار و مشترک میخواهند مفید است.
اولین اجرا: تنظیم پروژه و چارچوببندی وظیفه
OpenHands زمانی میدرخشد که بتواند کد شما را ببیند. با این کار شروع کنید:
- باز کردن مخزنی که میخواهید روی آن کار کند.
- اجرا یا فهرستبندی پروژه به طوری که OpenHands بتواند ساختار را نقشهبرداری کند.
- دادن یک هدف واضح با محدودیتها به آن.
مثال خوب برای چارچوببندی وظیفه:
- "بازنشانی رمز عبور کاربر را به سرویس
auth با استفاده از پیوندهای ایمیلی مبتنی بر توکن اضافه کنید. از ماژول mailer موجود استفاده کنید. تستهای واحد را برای تولید و انقضای توکن اضافه کنید. طرحواره دادههای کاربر را تغییر ندهید."
چرا این کار میکند:
- این نام مؤلفه، دامنه، وابستگیها و مرزها را مشخص میکند. هر چه واضحتر باشید، OpenHands بهتر برنامهریزی و اجرا میکند.
نحوه نوشتن درخواستهای موثر برای OpenHands
درخواستها را به عنوان تیکتهای مختصر در نظر بگیرید. بهترین آنها:
- تعریف نتیجه: "X را با محدودیتهای Y پیادهسازی کنید"
- ارجاع به فایلها، ماژولها یا تستها: "به
auth/routes.py و tests/test_auth.py مراجعه کنید"
- بیان محدودیتها: "بدون تغییرات در طرحواره DB; رابطهای موجود را حفظ کنید"
- شامل معیارهای پذیرش: "تستها باید پاس شوند:
pytest -k password_reset"
قالبهایی که میتوانید دوباره استفاده کنید:
هدف: <آنچه میخواهید ساخته یا تعمیر شود>
زمینه: <فایلهای مرتبط، محدودیتهای شناختهشده، خدمات خارجی>
پذیرش: <شکل پاس شدن چگونه است: تستها، نقاط پایانی، معیارها>
مرزها: <چه چیزی نباید تغییر کند یا رویکردهایی که باید از آنها اجتناب شود>
ابزارها: <دستوراتی که میتواند اجرا کند، اسکریپتها یا منابع داده>
گردشکار اصلی: برنامهریزی → اجرا → تأیید → اصلاح
OpenHands معمولاً یک برنامه چند مرحلهای پیشنهاد میکند. در اینجا نحوه راهنمایی آن آمده است:
- برنامه آن را زود تأیید یا تنظیم کنید. آن را وادار کنید ابتدا تستها را اجرا کند تا شکستها را مبنا قرار دهد.
- از آن بخواهید یک تست برای تعریف موفقیت ایجاد یا به روز کند، سپس کد را پیادهسازی کند.
- آن را وادار کنید مجموعه تست و لینترها را مرتباً اجرا کند.
- اگر متوقف شد، زمینه بیشتری اضافه کنید: نام فایلها، ردیابی پشته یا گزارشها.
نکته حرفهای: تغییرات کوچک در اندازه PR را به جای ویرایشهای یکپارچه تشویق کنید. این به بررسی و بازگشت کمک میکند.
گردشکارهای نمونهای که میتوانید کپی کنید
1) پیادهسازی ویژگی
- درخواست: "صادرات CSV را به صفحه
orders اضافه کنید. از صفحهبندی سمت سرور استفاده کنید، نتایج را از طریق text/csv پخش کنید. دکمه Export را در OrdersTable.jsx و نقطه پایانی را در routes/orders.ts اضافه کنید. تستهایی را برای صفحهبندی و سرصفحهها اضافه کنید."
- نقطه پایانی و دکمه مشتری را اضافه میکند
- تستها را مینویسد و آنها را اجرا میکند
- شما نظارت میکنید، تغییرات را تأیید میکنید و پس از سبز شدن، ادغام میکنید.
2) رفع اشکال یک ساخت ناموفق
- درخواست: "CI در Node 20 با شکست مواجه میشود. خطاهای وارد کردن ESM/CJS را در
build.mjs برطرف کنید. پلاگینهای rollup موجود را حفظ کنید; پیکربندی و کد را برای پاس کردن CI بهروز کنید."
- گزارشها را ارائه دهید یا به مصنوعات CI پیوند دهید.
- از OpenHands بخواهید به صورت محلی تکرار کند (
npm run build) و حداقل تفاوتها را پیشنهاد کند.
3) پوشش تست و سختسازی
- درخواست: "پوشش برای
payments/service.py را از 62٪ به 85٪+ افزایش دهید. تستهای واحد را برای retry_charge، refund، webhook_signature اضافه کنید. مگر اینکه تست یک اشکال را نشان دهد، منطق تجاری را تغییر ندهید."
- به OpenHands اجازه دهید تستها را تولید کند، آنها را اجرا کند و اصلاح کند.
4) اسناد و تجربه توسعهدهنده
- درخواست: "یک
CONTRIBUTING.md و DEVELOPMENT.md برای این مخزن ایجاد کنید. شامل تنظیمات محیط، اسکریپتها، دستورات تست و دستورالعملهای PR باشد."
- آن را وادار کنید با اجرای واقعی آنها، دستورات را تأیید کند.
محافظتها: OpenHands را مفید و ایمن نگه دارید
- دامنه دایرکتوری: آن را به یک مخزن یا دایرکتوری خاص اشاره کنید تا از ویرایشهای تصادفی در جاهای دیگر جلوگیری شود.
- حفاظت از فایل: فایلهای پیکربندی یا زیرساختهای حیاتی را در صورت امکان فقط خواندنی علامتگذاری کنید.
- ممیزی دستور: برای دستورات مخرب (به عنوان مثال،
rm -rf، بازنشانی پایگاه داده) نیاز به تأیید دارید.
- بهداشت اسرار: هرگز کلیدهای API را در درخواستها جایگذاری نکنید. از متغیرهای محیطی و گزارشهای ماسکشده استفاده کنید.
- دسترسی به شبکه: اگر مرور فعال است، آن را سندباکس کنید و تماسهای خروجی را ثبت کنید.
مدلهای محلی در مقابل ابری: انتخاب مناسب برای شما
- مزایا: استدلال/کدنویسی قوی، حداقل تنظیمات، تکرار سریع
- معایب: هزینه جاری، ملاحظات مربوط به حاکمیت داده
- مزایا: حریم خصوصی، کنترل، پیشبینیپذیری هزینه
- معایب: تقاضای سختافزاری، کیفیت مدل متفاوت است، نیاز به تنظیم بیشتر
برای پیکربندی باطنهای مدل و محدودیتهای حافظه، به دستورالعملهای رسمی LLMهای محلی مراجعه کنید.
بازی تیمی: استفاده از OpenHands در یک جریان مشارکتی
- گردشکار اول شاخه: از OpenHands بخواهید یک شاخه ویژگی ایجاد کند و تغییرات را برای بررسی PR ارسال کند.
- بهداشت commit: از آن بخواهید commitهای اتمی با پیامهای واضح تولید کند و به شمارههای مشکل ارجاع دهد.
- قالبهای PR: قالبهای PR را ایجاد و اعمال کنید تا بازبینان بدانند چه چیزی تغییر کرده و چرا.
- مالکان کد: با CODEOWNERS ترکیب کنید تا PRهای تولید شده توسط هوش مصنوعی را به بازبینان مناسب هدایت کنید.
عیبیابی مشکلات رایج
- گیر میکند یا حلقه میزند: دامنه را محدود کنید. از آن بخواهید مرحله بعدی خود را توضیح دهد. یک تست ناموفق ارائه دهید.
- تفاوتهای بههمریخته: یک برنامه کوچکتر و مرحلهای درخواست کنید—ابتدا تستها، سپس حداقل تغییرات کد.
- ویرایشهای نادرست فایل: مسیرهای دقیق را مشخص کنید و مرزها را به آن یادآوری کنید.
- به صورت محلی پاس میشود اما در CI با شکست مواجه میشود: جزئیات و گزارشهای محیط CI را به اشتراک بگذارید; آن را وادار کنید با یک کانتینر تکرار کند.
نکات عملکرد و حرکات قدرتمند
- زمینه شروع گرم: از آن بخواهید ابتدا فایلهای کلیدی را بخواند (
README، package.json، فایلهای سرویس اصلی).
- به آن اسکریپت بدهید: یک
make test یا npm run verify ارائه دهید تا بتواند به سرعت تأیید کند.
- دامنه را آموزش دهید: یک نمای کلی معماری کوتاه ارائه دهید; در خطاهای منطقی کمتر نتیجه میدهد.
- اعمال سبک: به پیکربندیهای
.eslintrc، .prettierrc، black/ruff اشاره کنید تا به درستی قالببندی شود.
- از ایستهای بازرسی استفاده کنید: پس از هر نقطه عطف، خلاصه و مراحل بعدی را بپرسید تا آن را در مسیر خود نگه دارید.
سناریوی دنیای واقعی: از گزارش اشکال تا پچ در یک ساعت
- وضعیت: یک اشکال تولید، 500های غیرقابلکنترل را در بارهای JSON بدشکل در API
orders رها میکند.
- درخواست شما: "500 را در JSON بدشکل در POST
orders بازتولید کنید. اعتبارسنجی طرحواره را اضافه کنید و 400 را با جزئیات خطا برگردانید. تستها را برای پوشش بارهای بدشکل بهروز کنید."
- API را به صورت محلی اجرا میکند، خطا را بازتولید میکند
- یک لایه اعتبارسنجی و مدیریت خطا اضافه میکند
- تستها را بهروز میکند و اطمینان حاصل میکند که CI پاس میشود
- یک PR فشرده با یک ورودی changelog تولید میکند
صرفهجویی در زمان: شما روی تجزیه و تحلیل تأثیر و استقرار متمرکز شدید، در حالی که OpenHands داربست را اداره کرد.
ادغامهایی که OpenHands را فوقالعاده شارژ میکنند
- دوندههای تست: pytest, Jest, Vitest, JUnit
- ابزارهای ساخت: Vite, Webpack, Rollup, Babel
- مدیریتکنندههای بسته: npm, pnpm, yarn, pip/poetry
- لینترها/قالببندها: ESLint, Prettier, black, ruff
- کانتینرها: Docker Compose برای برابری محلی با CI
با استانداردسازی این ابزارها، OpenHands میتواند استک شما را مطمئنتر استدلال کند و بیشتر حلقه توسعه را خودکار کند.
به هر حال: استفاده از Sider.AI در کنار OpenHands
امتیاز ارتباط: 8/10. اگر از OpenHands به عنوان مهندس هوش مصنوعی خود استفاده میکنید، ارزش دارد که آن را با یک کمک خلبان تحقیق و پیشنویس برای مشخصات، توضیحات PR و مستندات جفت کنید. به هر حال، Sider.AI میتواند به شما کمک کند تا به سرعت مشخصات فنی را پیشنویس کنید، RFCها را خلاصه کنید یا گزارشهای اجرای OpenHands را به changelogها و یادداشتهای انتشار تمیز تبدیل کنید. این ترکیب، تعویض زمینه را کاهش میدهد: OpenHands اقدامات کد را انجام میدهد در حالی که Sider.AI نتایج را به اسناد تمیز و رو به کاربر تبدیل میکند.
چک لیست امنیت، حریم خصوصی و انطباق
- اسرار را در متغیرهای env نگه دارید; هرگز کلیدها را در درخواستها جاسازی نکنید
- هر تغییری که توسط هوش مصنوعی تولید شده است را مانند PR یک توسعهدهنده تازهکار بررسی کنید
- دستورات و اقدامات را برای قابلیت ممیزی ثبت کنید
- نسخههای زنجیره ابزار را پین کنید; از ارتقاء تصادفی در فایلهای قفل خودداری کنید
- اگر از LLMهای ابری استفاده میکنید، با سیاستهای نگهداری داده خود هماهنگ شوید
چه زمانی از OpenHands استفاده نکنیم
- طراحی الگوریتم جدید بدون داربست تست یا مشخصات قوی
- پایگاههای کد بسیار تنظیمشده بدون یک فرآیند بررسی قوی
- اسکریپتهای یکباره که کدنویسی دستی در آنها سریعتر است
60 دقیقه اول شما با OpenHands: یک کتاب بازی کوچک
- دقیقه 0–10: با استفاده از Quickstart رسمی نصب و راهاندازی کنید
- دقیقه 10–20: مخزن خود را متصل کنید; از آن بخواهید ساختار پروژه را نقشهبرداری کند
- دقیقه 20–35: یک هدف کوچک و قابل آزمایش تعریف کنید; برنامه آن را تأیید کنید
- دقیقه 35–50: اجازه دهید پیادهسازی کند و تستها را اجرا کند; در صورت نیاز هل دهید
- دقیقه 50–60: تفاوتها را بررسی کنید، اصلاح کنید و در یک شاخه ویژگی ادغام کنید
پیوندهای کلیدی و مراحل بعدی
- اسناد رسمی "Start Building" و استفاده برای OpenHands: نکات، شروع سریع و بهترین شیوهها.
- راهنمای تنظیم LLM محلی: OpenHands را به طور کامل روی دستگاه خود پیکربندی و اجرا کنید.
- راهنمای نصب مبتنی بر جامعه در یک VM: مراحل نصب دنیای واقعی و یک پروژه نمایشی سریع.
نکات کلیدی
- وظایف را مانند تیکتها با معیارهای پذیرش روشن چارچوببندی کنید.
- تکرارها را کوچک نگه دارید; زود و اغلب تست کنید.
- از محافظتها استفاده کنید و تغییرات را بررسی کنید—آن را مانند یک همتیمی تازهکار در نظر بگیرید.
- ابر را برای راحتی، مدلهای محلی را برای حریم خصوصی انتخاب کنید.
- با ابزارهای مستندسازی جفت کنید (به عنوان مثال، Sider.AI) تا مشخصات و یادداشتهای انتشار را تسریع کنید.
سوالات متداول
Q1:چگونه میتوانم به سرعت AI OpenHands را نصب کرده و شروع به استفاده کنم؟
از quickstart رسمی برای نصب پیشنیازها، اتصال یک LLM پشتیبانیشده (ابری یا محلی) و راهاندازی رابط کاربری برای اتصال مخزن خود استفاده کنید. اسناد "Start Building" دستورالعملهای گام به گام را با نکات تنظیم ارائه میدهند.
Q2:آیا میتوانم OpenHands را با یک LLM محلی به جای یک مدل ابری اجرا کنم؟
بله. راهنمای LLMهای محلی را دنبال کنید تا یک باطن مدل محلی را پیکربندی کرده و تنظیمات زمینه را تنظیم کنید. این برای پروژههای حساس به حریم خصوصی یا اجتناب از هزینههای API ایدهآل است.
Q3:بهترین راه برای درخواست از OpenHands برای وظایف کدنویسی چیست؟
درخواستها را مانند تیکتهای مختصر بنویسید: هدف را تعریف کنید، به فایلهای خاص ارجاع دهید، مرزها را تعیین کنید و معیارهای پذیرش را وارد کنید. از آن بخواهید تستها را برای تأیید پیشرفت ایجاد یا اجرا کند.
Q4:آیا استفاده از AI OpenHands در کد تولید ایمن است؟
آن را مانند یک توسعهدهنده تازهکار در نظر بگیرید: از محافظت از شاخه، بررسی کد و CI برای تأیید تغییرات استفاده کنید. محافظتهایی را برای دستورات اضافه کنید و اسرار را از درخواستها دور نگه دارید.
Q5:OpenHands در مقایسه با یک دستیار کد سنتی چگونه است؟
برخلاف ابزارهای فقط چت، OpenHands میتواند دستورات را اجرا کند، فایلها را ویرایش کند و به طور مستقل در مخزن شما تکرار کند. این برای وظایف سرتاسری مانند ویژگیها، رفع اشکال و تستها ساخته شده است.
