راهنما · ۷ دقیقه مطالعه
کار با PiCode برای توضیح و ویرایش کد
راهنمای نصب و استفادهٔ مسئولانه از PiCode برای فهم کد و ویرایش فایل، همراه با چکلیست بازبینی.
PiCode ابزار خط فرمان PiGPT برای کار از محیط ترمینال است. وقتی مسئله داخل یک پروژه و فایلهای آن قرار دارد، خط فرمان میتواند از کپی کردن قطعههای پراکنده به یک گفتگوی وب مناسبتر باشد. در نسخهٔ عمومی فعلی، مسیر نصب، ورود مرورگری، چت و ویرایش فایل ارائه شده است؛ وضعیت نسخهها در چنجلاگ PiCode ثبت میشود.
این راهنما روی دو کار متمرکز است: توضیح کدی که میخواهید بفهمید و ویرایش کنترلشدهٔ فایلی که میخواهید تغییر دهید. در هر دو حالت، مسئولیت اجرای دستور، بررسی تفاوت و آزمودن نتیجه با شماست. پاسخ هوش مصنوعی نباید بدون بازبینی وارد محیط عملیاتی شود.
PiCode چه زمانی انتخاب مناسبی است؟
اگر فقط یک مفهوم عمومی میپرسید، گفتگوی PiGPT کافی است. PiCode زمانی ارزش دارد که ترمینال محل طبیعی کار شماست، فایل یا پروژهٔ مشخصی دارید و میخواهید چرخهٔ پرسش، بررسی و تغییر را نزدیک همان پروژه نگه دارید.
نمونهٔ مناسب: فهمیدن نقش یک تابع، پیدا کردن مسیر داده میان چند فایل، پیشنهاد تغییر کوچک، توضیح خطای آزمون یا بازنویسی محدود یک بخش. نمونهٔ نامناسب: دادن دسترسی بیقید به کل سرور و درخواست «همهچیز را درست کن». هرچه دامنهٔ کار کوچکتر و معیار پایان روشنتر باشد، بازبینی خروجی آسانتر است.
PiCode یک محیط توسعهٔ کامل یا جایگزین کنترل نسخه نیست. حتی اگر ابزار فایلی را ویرایش کند، باید تفاوت را با ابزارهای معمول پروژه ببینید، آزمونها را اجرا کنید و امکان بازگشت داشته باشید.
نصب از مسیر رسمی
صفحهٔ زندهٔ نصب در /app/cli است و فهرست فایلهای رسمی نیز در /downloads/picode/ قرار دارد. در لینوکس، macOS یا WSL دستور یکخطی صفحه چنین است:
bash curl -fsSL https://pigpt.ir/install-picode.sh | bash
در ویندوز، دستور PowerShell رسمی این است:
powershell irm https://pigpt.ir/install-picode.ps1 | iex
اسکریپت ویندوز در صورت نیاز Python 3.12 را فراهم میکند، محیط مجازی میسازد، بسته را از مسیر دانلودهای PiGPT نصب میکند و فرمان picode را به PATH اضافه میکند. اجرای مستقیم اسکریپت اینترنتی یک تصمیم امنیتی است؛ پیش از اجرا میتوانید فایل را از دامنهٔ رسمی باز کنید و محتوای آن را بررسی کنید.
پس از نصب، نسخه را کنترل کنید:
bash picode --version
شمارهٔ نسخه را با صفحهٔ چنجلاگ PiCode و فایلهای دانلود تطبیق دهید. اگر ترمینال فرمان را پیدا نکرد، یک پنجرهٔ تازه باز کنید تا PATH دوباره بارگذاری شود.
ورود با مرورگر
برای اتصال حساب، فرمان زیر را اجرا کنید:
bash picode login
مرورگر روی pigpt.ir باز میشود. پس از ورود وب، نشست خط فرمان توکن خود را ذخیره میکند. روش اصلی همین ورود مرورگری است؛ لازم نیست توکن حساب را در خط فرمان یا فایل پروژه paste کنید.
اگر مرورگر باز نشد، صفحهٔ PiCode یک مسیر پشتیبان با picode login --manual دارد. کد دستگاه را فقط در صفحهٔ رسمی PiGPT وارد کنید. گزینهٔ ورود با توکن نیز پشتیبان نهایی است و نباید توکن را در تاریخچهٔ شل، اسکرینشات یا مخزن کد نگه دارید.
برای اطمینان از اتصال، میتوانید یک پیام یکمرحلهای بفرستید:
bash picode chat "در یک جمله بگو اتصال برقرار است."
این فرمان از مسیر چت CLI PiGPT استفاده میکند. برای کار روی فایل، از دستورها و راهنمای نسخهٔ نصبشده پیروی کنید؛ نام گزینهها ممکن است میان نسخهها تغییر کند، بنابراین خروجی picode --help منبع دقیق همان نصب است.
چگونه از PiCode بخواهیم کد را توضیح دهد؟
درخواست «این کد را توضیح بده» معمولاً پاسخی طولانی و کمتمرکز میسازد. ابتدا هدف مطالعه را مشخص کنید. آیا میخواهید جریان داده را بفهمید، علت خطا را پیدا کنید، قرارداد تابع را بشناسید یا برای بازبینی امنیتی آماده شوید؟
یک درخواست بهتر چنین ساختاری دارد: «فایل و تابع هدف را توضیح بده؛ ورودی، خروجی، اثر جانبی و وابستگیها را جدا کن. فقط بر اساس کد موجود حرف بزن. اگر بخشی بیرون از محدوده است، نام فایل لازم را بگو و حدس نزن.»
برای کد پیچیده، توضیح را در سه دور بگیرید. دور اول نقشهٔ کلی ماژول؛ دور دوم مسیر اجرای یک سناریوی مشخص؛ دور سوم بررسی یک شاخه یا خطا. این روش از شرح خطبهخط همهٔ فایل جلوگیری میکند و سؤال بعدی را بر اساس فهم واقعی شما میسازد.
از ابزار بخواهید ادعاهایش را به نماد یا بخش مشخص کد وصل کند. جملهٔ «اعتبارسنجی انجام میشود» کافی نیست؛ باید معلوم باشد کدام تابع و پیش از کدام عملیات. سپس خودتان همان مسیر را در فایل ببینید.
درخواست ویرایش را کوچک و قابل سنجش بنویسید
ویرایش خوب یک مسئله، محدوده و معیار پذیرش دارد. مثال: «در تابع X، مقدار خالی را پیش از فراخوانی Y رد کن. رفتار ورودی معتبر عوض نشود. آزمون واحد برای مقدار خالی اضافه کن و فایل دیگری را تغییر نده.» این درخواست بسیار امنتر از «اعتبارسنجی را بهتر کن» است.
قبل از ویرایش، وضعیت پروژه را ذخیره کنید. اگر مخزن Git دارید، تغییرات قبلی را بررسی کنید تا خروجی ابزار با کار ناتمام شما مخلوط نشود. لازم نیست برای هر آزمایش commit بسازید، اما باید بدانید خط پایه چیست و چگونه تفاوت را خواهید دید.
پس از پیشنهاد یا اعمال تغییر، سه چیز بخواهید: خلاصهٔ علت، فهرست فایلهای تغییرکرده و آزمون پیشنهادی. سپس خودتان diff را بخوانید. اگر فایل نامرتبط تغییر کرده یا بازآرایی بزرگی همراه اصلاح کوچک آمده، تغییر را متوقف و دامنه را محدود کنید.
بازبینی تغییر؛ از ظاهر عبور کنید
کدی که مرتب به نظر میرسد ممکن است قرارداد را بشکند. نخست سازگاری با رفتار قبلی را بررسی کنید: نام و نوع ورودی، خروجی، خطاها و اثرهای جانبی. دوم، مسیر شکست را ببینید: ورودی خالی، خطای شبکه، نبود فایل، مجوز ناکافی یا زمانپایان.
سوم، امنیت را بررسی کنید. آیا دادهٔ کاربر مستقیم وارد فرمان، SQL، HTML یا مسیر فایل شده است؟ آیا توکن یا کلید در لاگ چاپ میشود؟ آیا تغییر، کنترل دسترسی را دور میزند؟ از PiCode بخواهید این موارد را فهرست کند، اما بررسی نهایی را به خروجی خودش واگذار نکنید.
چهارم، آزمون را اجرا کنید. فرمان دقیق آزمون به پروژه بستگی دارد؛ ابزار نباید آن را حدس بزند اگر مستندات پروژه موجود نیست. ابتدا فایل راهنما، اسکریپتهای package یا تنظیمات CI را ببینید و همان فرمان رسمی پروژه را به کار ببرید.
توضیح خطا با شواهد کافی
برای رفع خطا، پیام کامل، فرمانی که اجرا شده، نسخهٔ محیط و کوچکترین مسیر بازتولید را بدهید. فقط آخرین خط stack trace اغلب کافی نیست. در عین حال، رمز، کلید، دادهٔ شخصی و آدرسهای حساس را پیش از فرستادن حذف کنید.
از ابزار بخواهید میان «مشاهده»، «فرضیه» و «آزمایش بعدی» تفکیک کند. مشاهده چیزی است که در لاگ وجود دارد؛ فرضیه توضیح احتمالی است؛ آزمایش باید آن فرضیه را تأیید یا رد کند. این قالب مانع آن میشود که اولین حدس بهعنوان علت قطعی پذیرفته شود.
اگر دو تلاش نتیجه نداد، مسئله را بزرگتر نکنید. ورودی را کوچک کنید، یک آزمون مستقل بسازید یا فایل مرتبط دیگری را بررسی کنید. تغییرهای پیاپی بدون فرضیه، علت اصلی را پنهان میکنند.
محدودهٔ امن برای فایلها و فرمانها
PiCode را از پوشهٔ پروژهای اجرا کنید که واقعاً قصد بررسی آن را دارید. فایلهای محیط، کلیدهای خصوصی، نسخهٔ پشتیبان پایگاه داده و پوشههای خارج از پروژه نباید بیدلیل در دامنه باشند. درخواست ویرایش را به فایلهای مشخص محدود کنید.
فرمانهای مخرب، مهاجرت پایگاه داده، انتشار، تغییر زیرساخت و نصب سراسری بستهها نیاز به بررسی جدا دارند. هیچ پیشنهاد تولیدشدهای را صرفاً چون از ابزار آمده اجرا نکنید. ابتدا اثر فرمان، مسیر اجرا و راه بازگشت را بفهمید.
برای پروژهٔ تولیدی، تغییر را در محیط توسعه یا شاخهٔ جدا آزمایش کنید. بررسی انسانی، تست خودکار و بازبینی امنیتی مکمل یکدیگرند؛ هیچکدام بهتنهایی تضمین کامل نمیدهند.
چکلیست یک جلسهٔ کاری
- PiCode را فقط از مسیر رسمی نصب و نسخه را کنترل کنید.
- با picode login و دامنهٔ pigpt.ir وارد شوید.
- هدف را به یک تابع، خطا یا تغییر کوچک محدود کنید.
- از ابزار بخواهید واقعیت کد را از فرضیه جدا کند.
- پیش از ویرایش، وضعیت پایه و فایلهای دارای تغییر را بشناسید.
- پس از ویرایش، diff و فایلهای نامرتبط را بررسی کنید.
- آزمون رسمی پروژه را اجرا و نتیجه را ثبت کنید.
- توکن، رمز و دادهٔ حساس را وارد درخواست یا مخزن نکنید.
جمعبندی
کار با PiCode زمانی مؤثر است که آن را همکار بررسی بدانید، نه مجری بدون نظارت. از صفحهٔ PiCode نصب کنید، با مرورگر وارد شوید، سؤال را به کد مشخص وصل کنید و هر ویرایش را با diff و آزمون بسنجید. برای آگاهی از نسخهٔ عمومی و تغییرات واقعی نیز چنجلاگ PiCode را ببینید.
