کشیدن وزن: مشارکت در پروژه های یکدیگر

Summarize this content to 400 words in Persian Lang
این هفته، به عنوان بخشی از کلاس خود در زمینه توسعه منبع باز، با همکلاسی ام مایانک کار کردم تا در پروژه های یکدیگر مشارکت داشته باشیم. پروژه Mayank، dev-mate-cli، یک ابزار خط فرمان (CLI) است که فایل‌های کد منبع را با استفاده از هوش مصنوعی می‌خواند و نظراتی را برای درک آسان‌تر ایجاد می‌کند. به عنوان مرجع، پروژه من، codeshift، نیز یک ابزار CLI است که از هوش مصنوعی استفاده می کند، به جز برای ترجمه فایل های کد منبع به سایر زبان های برنامه نویسی. وظیفه ما اضافه کردن گزینه ای به ابزار یکدیگر بود که تعداد توکن های استفاده شده توسط ارائه دهنده هوش مصنوعی را برای پردازش فایل های منبع نمایش می دهد.

ابزار خط فرمان برای مستندسازی سریع کد شما

ابزار خط فرمانی که از API تکمیل چت OpenAI برای مستندسازی کد با کمک مدل‌های هوش مصنوعی استفاده می‌کند تا برای مشاهده ویژگی‌ها، این ویدیوی آزمایشی را تماشا کنید.

ویژگی ها

اسناد کد منبع: به طور خودکار نظرات و مستندات را برای کد منبع خود ایجاد کنید.

پردازش چندین فایل: یک یا چند فایل را در یک فرمان مدیریت کنید.

انتخاب مدل: انتخاب کنید از کدام مدل هوش مصنوعی استفاده کنید –model پرچم

خروجی سفارشی: خروجی نتایج به یک فایل با –output پرچم گذاری کنید یا آنها را در کنسول نمایش دهید.

نصب و راه اندازی

کلون کردن مخزن:

git clone https://github.com/mayank-Pareek/dev-mate-cli.git
cd dev-mate-cli

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نصب وابستگی ها:

npm install

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

تنظیم متغیرهای محیطی:
ایجاد یک .env فایل را در دایرکتوری ریشه پروژه با پیکربندی زیر دریافت کنید API_KEY و BASE_URL از ارائه دهنده مدل مورد نظر شما:

API_KEY=your_api_key
BASE_URL=base_url

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

پیکربندی LLM را تنظیم کنید:
باز کنید config.json فایل را از دایرکتوری ریشه پروژه و ویرایش تنظیمات پیش فرض برای سفارشی کردن LLM. از کلید API خود دیدن کنید…

به منظور مشارکت در پروژه‌های یکدیگر، از ما خواسته شد تا مسائل را بایگانی کنیم و درخواست‌ها (PRs) را انجام دهیم. من قبلاً تجربه ای با ایجاد مشکلات و درخواست های کششی داشتم، اما این هفته، با این روند بسیار آشنا شدم.

سهم من

قبل از ایجاد مشکل برای این ویژگی، با خواندن کد Mayank شروع کردم. مایانک از TypeScript برای پروژه خود استفاده کرد، که من زیاد به آن عادت ندارم، اما کمی از اینجا و آنجا استفاده کرده ام. کد او نیز به چندین ماژول تقسیم شد، الگویی که در ابتدا برایم ترسناک بود. من فکر کردم که یک نقطه شروع خوب پیدا کردن فایلی است که در آن فراخوانی API با هوش مصنوعی انجام شده است، زیرا به داده های بازگردانده شده از آن نیاز دارم. جدا از قابلیتی که باید اضافه می‌کردم، متوجه چند بهبودی شدم که می‌توانست در پروژه ایجاد شود و آنها را یادداشت کردم تا بعداً مشکلاتی ایجاد شود.

مایانک برای ایجاد ابزار CLI خود از همان ماژول npm استفاده کرد – commander.js. این باعث شد که من به راحتی وارد آن شوم و دقیقاً جایی که باید کد خود را اضافه کنم شناسایی کنم. مجبور شدم ثبت نام کنم -u/–token-usage گزینه، بررسی کنید که آیا تصویب شده است یا خیر، و اگر چنین بود، ویژگی استفاده توکن را که توسط API برگردانده شده است چاپ کنید. به اندازه کافی ساده من همچنین مطمئن شدم که تا حد امکان به سبک کد پروژه نزدیک می‌شوم.

من این موضوع را در GitHub ایجاد کردم و احساس رضایت کردم، اما بعد از اینکه دیدم برخی از مسائلی که دیگران ایجاد کرده‌اند چقدر جزئیات دارند، احساس می‌کنم باید به جزئیات بیشتری می‌رفتم. توضیحات من Pull Request نیز چندان روشنگر نبود. گمان می‌کنم که فکر می‌کردم تغییرات به اندازه‌ای ساده هستند که نیاز به توضیح عمیق ندارند.

یک پرچم خط فرمان جدید اضافه کنید: –token-usage یا -t. وقتی برنامه با –token-usage/-t پرچم تنظیم شد، اطلاعات اضافی به آن گزارش خواهد شد stderr در مورد تعداد توکن هایی که در اعلان ارسال شده و در تکمیل بازگردانده شده اند.
من می خواهم روی این ویژگی کار کنم. لطفاً اگر دستورالعمل اجرایی خاصی دارید به من اطلاع دهید.

رفع شماره 6.
برخی ملاحظات:

من استفاده کردم -u پرچم کوتاه از آن زمان -t در حال استفاده بود
این پیاده سازی استفاده از نشانه را چاپ نمی کند اگر -o پرچم استفاده می شود.

پس از ارسال روابط عمومی من، Mayank به سرعت آن را تایید کرد، اما از آنجایی که آزمایشگاه برای درخواست تغییرات نیاز به تمرین داشت، من یک روابط عمومی دیگر را بر اساس یکی از بهبودهای بالقوه ای که قبلاً ذکر کردم، ارائه کردم، که نام و نسخه برنامه را وارد می کرد. package.json فایل برای چاپ هنگام استفاده از –version پرچم به این ترتیب، هنگام به‌روزرسانی آن‌ها، لازم نیست این کار را در چندین فایل انجام دهید. من درخواست کشش را ارائه کردم، چون مطمئن نبودم چه چیزی را باید تغییر دهم، و Mayank مشاهده کرد که توضیحات برنامه استفاده شده در پیام راهنما نیز می تواند از همان فایل وارد شود و از من خواست که تغییر را به آن اضافه کنم. روابط عمومی، که من انجام دادم.

به روز شد tsconfig.json اجازه می دهد تا فایل های JSON را به عنوان ماژول وارد کنید
نام و رشته های نسخه با متغیرهای وارد شده از package.json

نام به اضافه شد -v خروجی

شماره 7 را می بندد، شماره 9 را می بندد

برای این تغییر مجبور شدم فایل پیکربندی TypeScript را ویرایش کنم tsconfig.json برای اجازه واردات .json فایل ها یادگیری کمی بیشتر در مورد نحوه عملکرد TypeScript و نحوه پیکربندی آن جالب بود.

نتیجه

من از کارم در مورد راضی بودم –token-usage ویژگی، اما بعداً متوجه شدم که آنطور که در نظر گرفته شده بود کار نمی کند. به جای چاپ کل نشانه های استفاده شده برای کل دستور در انتها، توکن های استفاده شده را پس از پردازش هر فایل ورودی چاپ می کند. این پیاده سازی کار می کند، اما کاملاً آن چیزی نیست که من تصور می کردم. من به مایانک اطلاع دادم، و خوشبختانه، او با اجرای آن مشکلی ندارد.

در گذشته، ای کاش چنین نظارت آشکاری انجام نمی دادم، اما خوشحالم که درست از آب درآمد.

من همچنین چند موضوع دیگر را در مورد پروژه ثبت کردم: یکی پیشنهاد اضافه کردن a .env.example فایل، حاوی متغیرهای محیط مکان نگهدار برای آسان‌تر کردن راه‌اندازی اولیه، یکی نشان می‌دهد که فهرست پیشرفت‌های آینده را از فایل منتقل کنید. README به مشکلات GitHub، و یکی اشاره به چگونگی پروژه –version دستور نام برنامه را چاپ نمی کند، که برای پروژه الزامی بود. من مشکل دوم را با روابط عمومی دوم خود برطرف کردم.

ایجاد یک .env.example فایل حاوی جفت‌های کلید/مقدار مکان‌نما برای آسان‌تر کردن راه‌اندازی پروژه.

# .env.example

API_KEY=your_api_key
BASE_URL=https://openrouter.ai/api/v1

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

بخش Future Enhancements را حذف کنید README.md و در عوض مسائلی را برای مستندسازی آنها ایجاد کنید.

–version و -v قرار است نام برنامه را چاپ کنند اما این کار را نمی کنند.
خروجی می تواند چیزی شبیه به:
dev-mate-cli v0.1.0

سهم مایانک

مایانک اضافه کرد –token-usage ویژگی پروژه من است، و به اندازه کافی مهربان بود که روی چند موضوع دیگر که باز داشتم نیز کار کنم:

این درخواست کشش یک مورد جدید اضافه می کند –token-usage پرچم (با مختصر -t گزینه) به برنامه، به کاربران این امکان را می دهد که اطلاعات استفاده از رمز را هنگام درخواست به API مشاهده کنند. این پرچم برنامه را قادر می‌سازد تا تعداد نشانه‌های اعلان، نشانه‌های تکمیل و کل توکن‌های استفاده شده توسط درخواست را نمایش دهد.

هر دو یک پرچم بلند اضافه شده است –token-usage و یک پرچم کوتاه -t به برنامه برای گزارش استفاده از رمز.
اضافه شدن منطق برای بررسی –token-usage پرچم در برنامه اگر پرچم وجود داشته باشد و پاسخ حاوی داده های استفاده از رمز باشد، برنامه اکنون آن را استخراج کرده و در کنسول با استفاده از آن نمایش می دهد. console.error.
داده های مربوطه استخراج شده است chunk?.x_groq?.usage در پاسخ، از ساختار پاسخ GROQ API پیروی می کند.
فایل README.md را برای مستندسازی جدید به روز کرد –token-usage (-t) گزینه

هیچ تغییر شکستی در این درخواست کشش ارائه نشد.
این روابط عمومی با اضافه کردن گزینه استفاده از رمز درخواستی، شماره 10 را می بندد.

لطفاً در صورت نیاز به تغییرات اضافی به من اطلاع دهید.

این درخواست کشش برنامه را تغییر می دهد تا زمانی که چندین فایل ورودی ارائه می شود، داده ها را به فایل خروجی اضافه کند –output پرچم استفاده می شود. قبلاً، برنامه فایل خروجی را با داده های هر فایل ورودی بازنویسی می کرد. اکنون، نتایج هر ورودی را به فایل خروجی مشخص شده اضافه می کند.

منطق استفاده را به روز کرد fs.appendFile به جای fs.writeFile هنگامی که چندین فایل ورودی همراه با ارسال می شوند –output پرچم این تضمین می‌کند که داده‌های همه فایل‌های ورودی به‌جای بازنویسی محتوای قبلی، به‌طور متوالی در همان فایل خروجی نوشته می‌شوند.
منطق اضافه شده برای خروجی پیام هشدار در صورت خالی نبودن فایل خروجی. فایل با استفاده از بررسی می شود fs.readFile برای چک خالی

این شماره 12 را برطرف می کند، در صورت نیاز به تغییرات بیشتر به من اطلاع دهید.

اگر –output پرچم ارسال می شود برنامه فقط در فایل خروجی می نویسد، این تغییرات #8 حل می شود.

می توانید پست وبلاگ او را در مورد آنها اینجا بخوانید:

نتیجه

تغییرات مایانک در بیشتر موارد بسیار خوب بود و برخی ناسازگاری‌های سبک کد را ممنوع کرد، که از او خواستم هنگام بررسی روابط عمومی تغییر کند. اجرای او از –token-usage شبیه من بود، یعنی خروجی بعد از هر فایل ثبت می شد. از آنجایی که این کار از طرف من غیرعمدی بود، وقتی متوجه شدم که این اشکال وجود دارد، در نهایت کد را تغییر دادم تا همانطور که در ابتدا قصد داشتم کار کند.

خوشحالم که مایانک تصمیم گرفت کمک کند و مسائل دیگری را حل کند. او به یک اشکال بزرگ در برنامه من اشاره کرد: هنگام تعیین یک فایل برای خروجی، کد ترجمه شده از آخرین فایل ورودی، فایل های قبلی را بازنویسی می کند. او این مشکل را با افزودن آن به فایل خروجی مشخص شده برطرف کرد و همچنین یک پیام هشدار کنسول اضافه کرد.

من کاملاً از این تغییر راضی نبودم – ترجیح دادم ابزار CLI من تا حد امکان بی صدا باشد، مشابه دستورات یونیکس mv یا cp بازخورد ارائه نکنید مگر اینکه شکست بخورند. من همچنین می‌خواستم دقیقاً همان کاری را انجام دهد که کاربر دستور داده است – اگر آنها یک فایل خروجی موجود را برای نوشتن مشخص کنند، می‌خواستم محتویات بازنویسی شود (البته بدیهی است که این واقعیت که فقط محتوای آخرین فایل ورودی را خروجی می‌کرد یک مشکل بود. ).

با وجود این، من در نهایت تغییرات را ادغام کردم. رویکرد Mayank در ارائه بازخورد به کاربر، استفاده از این ابزار را آسان‌تر می‌کند. اما بعد از مدتی نشستن روی آن، کاملاً درست به نظر نمی‌رسید، و در نهایت آن را تغییر دادم تا محتوای اصلی را بازنویسی کند، اما با اصلاح او برای نوشتن خروجی از همه فایل‌های ورودی.

باز هم، من کاملا از روند بررسی خود راضی نیستم. احساس می‌کنم باید تغییرات را دقیق‌تر بررسی می‌کردم و آن‌ها را دقیق‌تر آزمایش می‌کردم.

نتیجه گیری

به طور خلاصه، این تجربه نه تنها به من درک عمیق‌تری از ایجاد و بررسی درخواست‌های کشش داد، بلکه درک بهتری از اهمیت بررسی‌ها و آزمایش‌های دقیق کد به من داد. من در خواندن و کار با کد دیگران احساس اطمینان بیشتری می کنم، اما باید هم نسبت به تغییراتی که ایجاد می کنم و هم نسبت به تغییراتی که می پذیرم انتقاد بیشتری داشته باشم. امیدوارم با ادامه مشارکت در پروژه‌های منبع باز بیشتر در این زمینه به سرعت پیشرفت کنم.

# .env.example

API_KEY=your_api_key
BASE_URL=https://openrouter.ai/api/v1