راهنمای Kilo Code برای VS Code؛ اتصال مدل، Permission و Snapshot

Kilo Code یک عامل کدنویسی متن‌باز است که در محیط‌هایی مانند VS Code، JetBrains و ترمینال کار می‌کند. تفاوت آن با تکمیل‌کننده ساده کد این است که Agent می‌تواند Context پروژه را بخواند، فایل تغییر دهد، فرمان اجرا کند، نتیجه را تحلیل کند و چند مرحله برای رسیدن به هدف پیش برود. همین توانایی، استفاده از آن را مفید و در عین حال نیازمند کنترل می‌کند.

در این راهنما نسخه VS Code را نصب می‌کنیم، Provider و مدل را انتخاب می‌کنیم، نخستین Task را روی یک Repository آزمایشی اجرا می‌کنیم و Permissionها، Snapshot، Diff و Secretها را طوری تنظیم می‌کنیم که تصمیم نهایی همچنان دست توسعه‌دهنده بماند. رابط و نام بعضی گزینه‌ها ممکن است با Releaseهای بعدی تغییر کند؛ برای دانلود و تنظیمات نهایی همیشه مستندات رسمی همان نسخه را ملاک بگیرید.

Kilo Code چیست و چه کاری انجام می‌دهد؟

Kilo Code یک پلتفرم Agentic Engineering است؛ یعنی مدل زبانی را به ابزارهایی برای خواندن و ویرایش فایل، جست‌وجوی کد، اجرای Shell، مرور وب و مدیریت کارهای چندمرحله‌ای متصل می‌کند. خود Kilo Code مدل زبانی نیست. شما یک Provider و Model سازگار انتخاب می‌کنید و Agent با توجه به Prompt، Context و Permissionهای تعریف‌شده از آن استفاده می‌کند.

در نسخه فعلی، هسته مشترکی میان افزونه VS Code، CLI و برخی محیط‌های دیگر وجود دارد. تنظیمات اصلی در فایل‌های JSONC قابل حمل نگه‌داری می‌شوند و Agentهای سفارشی با فایل Markdown تعریف می‌شوند. اگر آموزش قدیمی درباره فایل‌های legacy mode یا گزینه‌های منسوخ می‌خوانید، قبل از اجرا آن را با صفحه رسمی نسخه فعلی مقایسه کنید.

تفاوت Kilo Code با Copilot معمولی و Chat

مزیت Agent در کارهایی مانند Refactor چندفایلی، نوشتن Test، تحلیل خطا و به‌روزرسانی مستندات دیده می‌شود. برای تغییر کوچک یک خطی ممکن است Autocomplete سریع‌تر باشد. ابزار مناسب را بر اساس دامنه کار انتخاب کنید، نه صرفاً بر اساس جدیدبودن فناوری.

پیش‌نیازهای نصب در VS Code

• VS Code نسخه 1.84 یا جدیدتر طبق راهنمای رسمی نصب
• یک Repository آزمایشی و ترجیحاً Git فعال
• Provider و Model سازگار یا حساب Kilo
• اینترنت امن برای دریافت افزونه و ارتباط با Provider
• در شبکه سازمانی، Proxy و گواهی ریشه مورد اعتماد
• Branch جدا و Test پایه پیش از سپردن تغییر به Agent

از پروژه‌ای شروع کنید که Secret واقعی، فایل مشتری یا دسترسی Production ندارد. اگر Repository شما فایل env، کلید خصوصی یا Export پایگاه داده دارد، پیش از بازکردن Workspace آن‌ها را از دامنه Agent خارج کنید. فایل gitignore به‌تنهایی تضمین نمی‌کند یک ابزار نتواند فایل موجود روی Disk را بخواند؛ Permission خواندن و Scope Workspace تعیین‌کننده‌اند.

بررسی نسخه VS Code و Git

code --versiongit --versiongit status --short --branch

اگر فرمان code در PATH نیست، نسخه را از Help و About داخل VS Code ببینید. برای رفع این مورد VS Code را دوباره از منبع رسمی نصب یا فرمان Shell مربوط به همان سیستم‌عامل را فعال کنید؛ PATH را با دانلود فایل اجرایی ناشناس تغییر ندهید.

نصب Kilo Code از Marketplace رسمی

1. در VS Code کلیدهای Ctrl+Shift+X را بزنید تا Extensions باز شود.
2. عبارت Kilo Code را جست‌وجو و Publisher را بررسی کنید.
3. از فلش کنار Install، گزینه Install Pre-Release Version را انتخاب کنید.
4. پس از پایان نصب، در صورت درخواست پنجره VS Code را Reload کنید.
5. آیکون Kilo Code را از Primary Side Bar باز کنید.

طبق مستندات رسمی، برچسب Pre-Release در حال حاضر کانال توزیع نسخه جدید افزونه است و همان نسخه توصیه‌شده محسوب می‌شود. افزونه Runtime لازم را همراه خود دارد و برای استفاده در VS Code نیازی نیست CLI را جداگانه نصب کنید. اگر Marketplace در دسترس نیست، از Open VSX برای Editorهای سازگار یا فایل VSIX موجود در Release رسمی GitHub استفاده کنید.

نصب VSIX به‌صورت دستی

فایل VSIX را فقط از Release رسمی مخزن Kilo Code دریافت کنید. سپس در Extensions منوی سه‌نقطه را باز و Install from VSIX را انتخاب کنید. Hash یا امضای منتشرشده را در صورت ارائه بررسی و فایل را از کانال‌های بازنشرشده دریافت نکنید. اگر موقتاً به نسخه قبلی برمی‌گردید، Auto Update را آگاهانه مدیریت و دلیل Pin شدن نسخه را در مستندات تیم ثبت کنید.

تنظیم Provider و مدل

پس از نصب، Settings داخل Kilo Code را باز و به بخش Providers بروید. Provider می‌تواند سرویس میزبان مدل یا Gateway مورد اعتماد شما باشد. نام Model، هزینه، Context Window، قابلیت Tool Calling و سیاست نگه‌داری داده را پیش از استفاده روی کد واقعی بررسی کنید.

API Key را داخل Prompt، فایل تنظیمات Project، اسکرین‌شات یا Commit قرار ندهید. از Secret Store یا سازوکار امن پیشنهادی Provider استفاده کنید. برای تیم، Credential جدا با Scope و Budget محدود بسازید و استفاده از کلید شخصی مدیر سیستم را ممنوع کنید. اگر Key افشا شد، آن را فوراً Rotate کنید؛ حذف از آخرین Commit برای پاک‌کردن History کافی نیست.

Agentها جای Modeهای قدیمی را چگونه گرفته‌اند؟

در افزونه جدید، Agentهای قابل سفارشی‌سازی در مسیر .kilo/agents با فایل Markdown تعریف می‌شوند. مفهوم Agent همان تخصصی‌کردن رفتار برای کاری مانند برنامه‌ریزی، کدنویسی، تست یا Review است، اما فایل‌ها و جریان تنظیمات آموزش‌های قدیمی ممکن است تغییر کرده باشند. Legacy modeها هنگام Startup قابل مهاجرت‌اند، با این حال خروجی مهاجرت را بررسی کنید.

اصل حداقل دسترسی را از نقش Agent شروع کنید. Agent مستندسازی نباید به Deploy نیاز داشته باشد و Agent Review معمولاً نباید فایل را تغییر دهد. تخصصی‌کردن Prompt بدون محدودکردن Permission کافی نیست؛ متن رفتاری و کنترل فنی باید هم‌جهت باشند.

نمونه Agent فقط‌خواندنی برای Review

# Repository ReviewerReview the requested diff for correctness and security.Do not edit files, run deployment, or access secrets.Report findings with file paths, evidence, and severity.If evidence is missing, state the uncertainty.

ساختار دقیق Front Matter و گزینه‌های Agent ممکن است با نسخه تغییر کند؛ این نمونه فقط متن رفتاری را نشان می‌دهد. برای Propertyهای قابل پشتیبانی از صفحه Custom Modes یا Agentهای رسمی همان Release استفاده کنید.

Permissionها: تفاوت Allow، Ask و Deny

Kilo Code برای ابزارها Permission سطح‌دانه دارد. Allow اجرای خودکار را ممکن می‌کند، Ask پیش از هر اقدام منطبق مکث می‌کند و Deny ابزار را مسدود می‌کند. اگر Ruleای منطبق نباشد، رفتار پیش‌فرض Ask است. تنظیم مناسب به حساسیت Repository و ابزار بستگی دارد.

Auto Approve اصطکاک را کم می‌کند اما کنترل تأیید را کنار می‌زند. به‌خصوص Allow عمومی برای Bash خطرناک است. الگوی محدود مانند یک فرمان Test مشخص از Rule گسترده برای همه Shell بهتر است. تغییر Permission پروژه هنگام Session فعال ممکن است فوراً خوانده نشود؛ طبق مستندات، پس از ویرایش فایل kilo.jsonc پنجره VS Code را Reload یا Session تازه ایجاد کنید.

نمونه محافظه‌کارانه تنظیم Permission

{  // نام کلیدها را با Schema نسخه نصب‌شده تطبیق دهید.  "permission": {    "external_directory": "deny",    "bash": "ask",    "edit": "ask",    "webfetch": "ask",    "websearch": "ask"  },  "snapshot": true}

این فایل را بدون بررسی Schema نسخه نصب‌شده Copy/Paste نکنید. هدف نمونه، نشان‌دادن سیاست حداقلی است. تنظیم Global در مسیر کاربر روی همه پروژه‌ها اثر می‌گذارد؛ تنظیم Project باید در Code Review دیده و از اضافه‌شدن Credential به Repository جلوگیری شود.

Snapshot و Git؛ دو لایه متفاوت بازگشت

Snapshotها که در مستندات قدیمی Checkpoint نامیده می‌شوند، پیش و پس از تغییر Agent از فایل‌های Workspace نسخه می‌گیرند و امکان مقایسه یا بازگشت سریع را می‌دهند. در افزونه جدید، Snapshot Repository جداگانه‌ای بیرون از پروژه دارد. برای کارکرد آن Git باید نصب باشد و Workspace نیز Git Repository باشد؛ در غیر این صورت ممکن است Snapshot رد شود.

Snapshot جای Commit و Backup تیمی نیست. Snapshot برای بازگشت سریع داخل Session مناسب است، Git تاریخچه رسمی پروژه را نگه می‌دارد و Backup در برابر خرابی یا حذف Storage محافظت می‌کند. پیش از اجرای Agent وضعیت Git را تمیز کنید تا تغییر کاربر و Agent با هم مخلوط نشوند.

git status --short --branchgit switch -c feature/kilo-first-taskdotnet testgit diff --stat

فرمان Test را متناسب با پروژه خود عوض کنید. ساخت Branch جدید وقتی Worktree تغییرات ثبت‌نشده دارد آن تغییرها را حذف نمی‌کند؛ ابتدا وضعیت را بفهمید و داده کاربر را با Reset یا Checkout مخرب پاک نکنید.

نخستین Task را چگونه بنویسیم؟

Prompt خوب باید هدف، محدوده، معیار پذیرش و ممنوعیت‌ها را روشن کند. «کد را بهتر کن» دامنه نامحدود دارد. در مقابل، «برای متد محاسبه مالیات Test حالت مقدار منفی اضافه کن؛ فقط پروژه Tests و همان متد را تغییر بده؛ Dependency، Migration و API عمومی تغییر نکند؛ در پایان Diff و نتیجه Test را گزارش کن» قابل ارزیابی است.

• یک هدف کوچک برای هر Session انتخاب کنید.
• فایل‌ها یا Directoryهای مجاز را نام ببرید.
• فرمان Test و معیار موفقیت را مشخص کنید.
• Deploy، Push، انتشار Package و Migration را صریحاً ممنوع کنید.
• از Agent بخواهید قبل از ویرایش Plan کوتاه ارائه دهد.
• بعد از اجرا، Diff و خروجی Test را مستقل بررسی کنید.

نمونه Prompt نخستین تمرین

Add one regression test for an empty customer name.Change only the unit-test project and CustomerValidator.Do not add dependencies, change the database, push, or deploy.Show a short plan before editing.Run the focused test and report the final diff and result.

فارسی یا انگلیسی بودن Prompt به توان مدل و اصطلاحات پروژه بستگی دارد. نام فایل، Command و Identifier را دقیق بنویسید. اگر Agent درباره نیاز مبهم سؤال می‌پرسد، پاسخ‌دادن بهتر از اجازه‌دادن برای حدس درباره Rule کسب‌وکار است.

بررسی Actionها پیش از تأیید

وقتی Permission روی Ask است، نام Tool و Argumentها را بخوانید. برای Bash فقط ابتدای فرمان را نگاه نکنید؛ Redirect، Pipe، Wildcard، Subcommand و مسیر مقصد می‌توانند اثر واقعی را تغییر دهند. فرمان دانلود و اجرای Script، حذف بازگشتی، تغییر Permission، دسترسی Cloud و نصب سراسری Package نیازمند توقف و بررسی جداگانه‌اند.

Workflow امن روزانه با Kilo Code

1. Repository را Pull و وضعیت Git را بررسی کنید.
2. یک Branch یا Worktree جدا برای Task بسازید.
3. Test پایه را بدون Agent اجرا کنید.
4. فایل‌های حساس را از Workspace و Context دور نگه دارید.
5. Agent تخصصی و Model متناسب با Task انتخاب کنید.
6. Permissionهای Bash، Edit، Web و External Directory را روی Ask یا Deny نگه دارید.
7. Goal، Scope و معیار پذیرش را در Prompt بنویسید.
8. Plan و هر Action پرریسک را قبل از اجرا بخوانید.
9. Snapshot و Diff را بررسی و Test را مستقل تکرار کنید.
10. Commit کوچک بسازید و Pull Request را به Review انسانی بدهید.

اگر چند Agent یا Session هم‌زمان روی یک Checkout کار کنند، تغییرها می‌توانند روی هم نوشته شوند. برای موازی‌سازی از Worktreeهای جدا استفاده و ادغام را با Git انجام دهید. یک Directory مشترک را به چند Agent خودمختار ندهید مگر اینکه مالکیت فایل و ترتیب کار کاملاً تعریف شده باشد.

Proxy، گواهی و شبکه سازمانی

افزونه VS Code Runtime تعبیه‌شده دارد و تنظیمات مرتبط شبکه را از VS Code می‌گیرد. در شبکه دارای Proxy، http.proxy و http.noProxy را طبق سیاست سازمان تنظیم کنید. اگر بازرسی HTTPS انجام می‌شود، CA سازمان را در Trust Store سیستم‌عامل نصب و فقط در صورت نیاز مسیر فایل PEM را در تنظیم extraCaCerts قرار دهید.

غیرفعال‌کردن Strict SSL مشکل گواهی را پنهان می‌کند و حمله واسط را آسان‌تر می‌سازد؛ آن را راه‌حل دائمی قرار ندهید. خطای Certificate باید با زنجیره اعتماد صحیح، ساعت سیستم، نام میزبان و Proxy بررسی شود. Key سرویس را در URL Proxy یا Log خطا نگذارید.

خطاهای رایج و روش رفع آن‌ها

چه زمانی از Kilo CLI استفاده کنیم؟

CLI برای توسعه‌دهنده‌ای مناسب است که Workflow ترمینالی، Session تعاملی یا Automation کنترل‌شده می‌خواهد. حالت Interactive پیش از عملیات تأییدنشده سؤال می‌پرسد. حالت Auto برای CI بدون تعامل طراحی شده اما فقط Permissionهای از قبل مجاز را اجرا می‌کند؛ استفاده از آن بدون محیط ایزوله، سقف زمان، Secret محدود و Review خروجی توصیه نمی‌شود.

برای شروع در VS Code، CLI را جدا نصب نکنید؛ افزونه Runtime خودش را دارد. وقتی Workflow داخل Editor پایدار شد و نیاز مشخصی برای Terminal یا CI داشتید، راهنمای رسمی CLI نسخه 1.0 یا جدیدتر را بخوانید و همان Permission Model را حفظ کنید.

مقایسه مسیر یادگیری با ابزارهای مشابه

اگر ابزار Terminal-first با ادغام مستقیم Git می‌خواهید، آموزش Aider AI مسیر مکمل خوبی است. برای یک Agent دیگر داخل VS Code، راهنمای Cline را ببینید. همچنین راهنمای وایب کدینگ امن اصول مشترک تعریف Scope، Review و آزمون مستقل را توضیح می‌دهد.

هیچ‌کدام به‌طور مطلق بهترین نیستند. کیفیت مدل، کنترل Permission، تجربه Editor، هزینه، حریم خصوصی، قابلیت بازگشت و سازگاری با Workflow تیم مهم‌تر از جدول Featureهای تبلیغاتی است. یک Task واقعی و تکرارپذیر تعریف و ابزارها را با معیار یکسان مقایسه کنید.

چک‌لیست پیش از استفاده روی پروژه واقعی

• افزونه از Marketplace یا Release رسمی نصب شده است.
• نسخه VS Code، افزونه و مدل ثبت شده است.
• Repository روی Branch یا Worktree جدا و وضعیت Git تمیز است.
• Snapshot فعال و Git قابل استفاده است.
• Secret، داده مشتری و دسترسی Production در Workspace نیست.
• External Directory روی Deny و Bash و Edit روی Ask هستند.
• Provider سیاست داده و سقف هزینه مناسب دارد.
• Prompt شامل Goal، Scope، Test و ممنوعیت Deploy است.
• Diff، Test و خروجی امنیتی مستقل بررسی می‌شوند.
• Commit و انتشار فقط پس از Review انسانی انجام می‌شود.

جمع‌بندی

Kilo Code عامل کدنویسی متن‌بازی است که تجربه Agent را به VS Code می‌آورد و می‌تواند از شناخت پروژه تا ویرایش، Test و Review پیش برود. ارزش واقعی آن وقتی نمایان می‌شود که Task چندمرحله‌ای اما قابل سنجش باشد. در مقابل، Permission گسترده، Workspace آلوده به Secret و Prompt مبهم می‌تواند یک میان‌بر سریع را به تغییر پرریسک تبدیل کند.

از Repository آزمایشی شروع کنید، افزونه Pre-Release رسمی را نصب کنید، Provider را با Key محدود تنظیم کنید و Bash، Edit، Web و دسترسی بیرون پروژه را کنترل کنید. Snapshot و Git را فعال نگه دارید و هیچ خروجی Agent را بدون Diff، Test و Review انسانی منتشر نکنید.

امروز یک Branch آزمایشی بساز، Kilo Code را با Permission محافظه‌کارانه نصب کن و نخستین Task را فقط به افزودن یک Test قابل بازگشت محدود کن.

منابع رسمی

• راهنمای رسمی نصب Kilo Code
• Kilo Code برای VS Code
• راهنمای نخستین Task
• Auto-Approving Actions و Permissionها
• Snapshot و Checkpoint
• Agentها و Custom Modes
• مستندات رسمی Kilo CLI
• مخزن رسمی Kilo Code در GitHub