راهنمای تنظیمات dsh: API Key و اتصال به Ollama
نحوه پیکربندی dsh در لینوکس، مدیریت فایلهای کانفیگ در ~/.dsh و اتصال به DeepSeek API یا Ollama. در این راهنما میآموزید که کدام دادهها از سیستم شما خارج میشوند.
محل نگهداری پیکربندی dsh
ابزار dsh (مخفف DeepSeek Harness) دادههای harness خود را در مسیر $DSH_HOME نگهداری میکند که بهصورت پیشفرض ~/.dsh است. این ابزار پیکربندی اشتراکی agent را از یک ریشه مجزا به نام $DSH_AGENTS_HOME میخواند که بهصورت پیشفرض ~/.agents است. هر تنظیمی که در رابط کاربری وب (Web UI) اعمال میکنید، در آنجا به شکل فایلهای متنی ساده ذخیره میشود. هنگام انتقال پیکربندی به سروری دیگر، دایرکتوری home مربوط به harness و تمامی دستورالعملها و مهارتهای سراسری (global instructions and skills) را از ریشه اشتراکی agent کپی کنید.
چهار مسیر، تنظیمات اصلی harness، اسرار (secrets) و لاگهای نشست (session logs) را در خود جای دادهاند.
- مسیر
~/.dsh/profiles/<profile>/cordis.patch.ymlشامل تنظیماتی است که رابط کاربری وب برای آن پروفایل مینویسد؛ این شامل مسیرهای ارائهدهنده (provider) و مدل شماست.dsh webپروفایلwebرا اجرا میکند، بنابراین فایل مربوطه~/.dsh/profiles/web/cordis.patch.ymlاست. - مسیر
~/.dsh/.credentials.yamlمحل نگهداری اسرار است. تنظیمات فقط حاوی ارجاع به یک اعتبارنامه (credential) هستند، بنابراین مقدار کلید در یک فایل مجزا قرار دارد. - مسیر
~/.dsh/profiles/پروفایلهای نامگذاریشده را نگه میدارد و~/.dsh/sessions/محل ذخیره لاگهای نشست است. - مسیر
~/.dsh/cordis.patch.ymlلایه patch شخصی شماست. این لایه بر روی پیکربندی پیشفرض برای هر پروفایل اعمال میشود و اولویت آن از فایل پروفایل بالاتر است؛ بنابراین اگر ویرایشی در رابط کاربری وب انجام دهید که با این لایه تداخل داشته باشد، سیستم بهجای ذخیره، آن را رد میکند.
ریشه اشتراکی agent خارج از $DSH_HOME قرار دارد، زیرا سایر ابزارهای agent نیز از آن استفاده میکنند. dsh دستورالعملهای سراسری کاربر را از ~/.agents/AGENTS.md میخواند و مسیر ~/.agents/skills/ را برای یافتن مهارتها اسکن میکند؛ برای تغییر این ریشه، DSH_AGENTS_HOME را تنظیم کنید.
نسخههای قدیمیتر، این تنظیمات را در ~/.dsh/settings.yaml نگهداری میکردند. نسخههای فعلی آن فایل را یکبار به پروفایل فعال وارد کرده و به settings.yaml.imported تغییر نام میدهند؛ بنابراین اگر راهنمای قدیمیتری به شما میگوید که settings.yaml را ویرایش کنید، آن فایل دیگر توسط dsh خوانده نمیشود.
DeepSeek این harness را بهعنوان یک پیشنمایش توسعهدهنده با مجوز MIT منتشر کرده است و فایل README هشدار میدهد که تغییرات ناسازگار با نسخههای قبلی (compatibility-breaking changes) رخ خواهد داد. نام فیلدها و مسیرهای ذکر شده در این راهنما با مستندات فعلی مخزن که در تاریخ 5 نوامبر 2026 بررسی شده، مطابقت دارد. پیش از کپی کردن پیکربندی از هر راهنمایی (از جمله همین متن)، آنها را با مستندات نسخه نصبشده خود تطبیق دهید، زیرا در نسخههای پیشنمایش، نامها بین هر release تغییر میکنند.
حداقلهای لازم برای اولین اجرا
نرمافزار dsh به Node.js نسخه 24.9 یا جدیدتر نیاز دارد. از تاریخ 5 نوامبر 2026، فایل package.json آن نسخه >=24.9.0 را اعلام کرده است، بنابراین نسخه 22 پشتیبانی نمیشود. نسخههای 24.0 تا 24.8 نیز کافی نیستند. ابتدا نسخه را بررسی کنید، زیرا عدم تطابق نسخه باعث شکست در راهاندازی میشود و پیام خطا بهگونهای است که گویی پکیج آسیب دیده است.
node -v
npx @deepseek-ai/dsh webدستور npx پکیج را از مخزن npm دانلود کرده و رابط کاربری وب را روی http://127.0.0.1:3080 اجرا میکند. این دستور روی آدرس loopback متصل میشود، به این معنی که حتی اگر فایروال شما اجازه دهد، پورت از ماشین دیگری قابل دسترسی نیست. روی یک VPS، بهجای باز کردن پورت 3080 به روی اینترنت، آن را از طریق SSH فوروارد کنید. اگر URL چاپ شده گیجکننده است، بخش دلیل اجرای dsh روی این آدرس توضیح میدهد که اتصال loopback از چه چیزی محافظت میکند و چه کاری انجام نمیدهد.
ssh -N -L 3080:127.0.0.1:3080 you@your-serverآدرس http://127.0.0.1:3080 را در لپتاپ خود باز کنید، سپس به بخش Settings و Models بروید. کارت DeepSeek دارای یک فیلد برای API key است. کلید را از platform.deepseek.com کپی کرده و ذخیره کنید. مسیر مدل بلافاصله قابل استفاده میشود و نیازی به راهاندازی مجدد نیست، زیرا سرور در حال اجرا، اعتبارنامه را ذخیره کرده و ارجاع را بهصورت زنده حل میکند. بخش دسترسی به رابط کاربری وب dsh روی سرور راه دور تونلزنی و حالت reverse proxy را پوشش میدهد و نصب DeepSeek Harness روی VPS آمادهسازی سروری که این راهنما فرض کرده است را توضیح میدهد.
پس از ذخیرهسازی، آنچه برنامه ایجاد کرده است را بررسی کنید.
ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yamlشما باید .credentials.yaml و profiles/ را ببینید، در حالی که تنظیمات رابط کاربری وب در profiles/web/cordis.patch.yml قرار دارد. دایرکتوری home که توسط بیلد قدیمیتری ایجاد شده باشد، ممکن است حاوی settings.yaml.imported نیز باشد. اگر stat حالتی غیر از 600 را نشان داد، دستور chmod 600 ~/.dsh/.credentials.yaml را اجرا کنید. فایلی که توسط گروه قابل خواندن باشد، کلید شما را در معرض حسابهای آن گروه قرار میدهد؛ فایلی که برای همه قابل خواندن باشد، آن را در معرض تمام حسابهای دیگر روی سیستم قرار میدهد.
برای اولین اجرا بدون مرورگر، یک دستور کافی است.
npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"پروفایل headless یک نشست واحد را اجرا کرده و پاسخ نهایی را چاپ میکند.
متغیرهای محیطی یا فایل پیکربندی
ابزار dsh میتواند کلید را از طریق اعتبارنامههای ذخیرهشده یا متغیرهای محیطی جایگزین (fallback) شناسایی کند.
یک ارائهدهنده کاتالوگ (مانند DeepSeek، Anthropic، OpenAI و سایر موارد موجود در لیست پیشفرض) کلید را از طریق صفحه Models میپذیرد، یا در صورتی که هیچ اعتبارنامه ذخیرهشدهای آن را تأمین نکند، از متغیر محیطی پشتیبانیشده استفاده میکند. مقدار کلید در ~/.dsh/.credentials.yaml قرار میگیرد و تنظیمات شما فقط حاوی ارجاعی به آن است. رابط کاربری وب پس از ذخیره کردن، دیگر کلید را نمایش نمیدهد.
یک ارائهدهنده سفارشی میتواند با استفاده از apiKeyEnv به یک مرجع اعتبارنامه اشاره کند که آن نیز از متغیرهای محیطی جایگزین پشتیبانی میکند. این ساختاری است که مستندات برای یک ورودی در patch پروفایل مانند ~/.dsh/profiles/web/cordis.patch.yml ارائه میدهند.
- id: llm-pi-ai
config:
providers:
my-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://gateway.example/v1
models:
- id: legacy-chat
- id: vision-preview
input: [text, image]ابتدا یک ارائهدهنده را از طریق رابط کاربری وب اضافه کنید، سپس فایل cordis.patch.yml پروفایل را باز کرده و ساختاری که برنامه نوشته است را کپی کنید. در طول دوره پیشنمایش توسعهدهنده (developer preview)، احتمال تغییر در ساختار تو در تو (nesting) وجود دارد و فایلی که برنامه بهتازگی نوشته است، همیشه معتبرترین منبع است.
apiKeyEnv از طریق مخزن اعتبارنامهها (credential store) شناسایی میشود: اولویت با فایل ذخیرهشده است، سپس محیط اجرای برنامه (launch environment)، فایل .env در دایرکتوری فراخواننده، و در نهایت $DSH_HOME/.env. کلیدی که فقط در یک نشست تعاملی (interactive session) صادر (export) شده باشد، برای یک unit در systemd نامرئی است؛ بنابراین بدون منبع اعتبارنامه دیگر، همان پیکربندی که هنگام تایپ دستی dsh web کار میکند، در زمان اجرا به عنوان یک سرویس، خطای MISSING_CREDENTIAL را برمیگرداند. برای unit مورد نظر، فایل اختصاصی خود را تعریف کنید.
[Service]
EnvironmentFile=/etc/dsh/dsh.envآن فایل را با مجوز 600 و مالکیت کاربری که سرویس با آن اجرا میشود، نگهداری کنید.
انتخاب مدلها و شناسهای که نمیتوانید تغییر نام دهید
هر ارائهدهندهای که پیکربندی شده باشد، در انتخابگر مدل ظاهر میشود. انتخاب یک مدل، آن را به عنوان پیشفرض برای نشستهای جدید نیز تعیین میکند. نشستهایی که قبلاً درخواستی ارسال کردهاند، مدل ثبتشده در خود را حفظ میکنند، بنابراین تغییر مدل باعث بازنویسی مکالمات قدیمی نمیشود.
شناسه ارائهدهنده (Provider ID) دائمی است. درخواستها، نشستهای ذخیرهشده، مدلهای پیشفرض و ارجاعات اعتبارنامه همگی به آن اشاره دارند، به همین دلیل دکمهای برای تغییر نام وجود ندارد. تغییر آن به معنای ایجاد یک ارائهدهنده جدید و حذف ارائهدهنده قدیمی است. نامی را انتخاب کنید که با آن راحت باشید: local-ollama بهتر از test2 است.
مدلهای سفارشی که قابلیت تصویر موروثی ندارند، فقط متنی هستند مگر اینکه خلاف آن را اعلام کنید. برای اعلام پشتیبانی از تصویر، input: [text, image] را به ورودی مدل اضافه کنید، یا defaultInput را در سطح مسیر (route) به عنوان جایگزین برای مدلهایی که در کاتالوگ توصیف نشدهاند، تنظیم کنید. در مسیر اختصاصی DeepSeek، مدلی که هیچ حالتی (modality) برای آن اعلام نشده باشد، فقط متنی محسوب میشود؛ بنابراین پیش از پیوست کردن تصویر، یک ورودی کاتالوگ با قابلیت تصویر (بهطور پیشفرض deepseek-flash) انتخاب کنید. تصویری که به مدلی ارسال شود که پشتیبانی از تصویر را اعلام نکرده است، پیش از ارسال هرگونه داده، رد خواهد شد.
اشاره dsh به یک endpoint محلی برای نگهداری کد روی سرور
Ollama یک API سازگار با OpenAI را روی http://127.0.0.1:11434/v1 ارائه میدهد. dsh از طریق یک provider سفارشی با هر base URL سازگار با OpenAI ارتباط برقرار میکند، بنابراین این دو بدون واسطه به هم متصل میشوند. ابتدا سرور مدل را راهاندازی کنید: self-hosting an LLM with Ollama on a VPS مراحل نصب و دریافت مدل را پوشش میدهد.
پیش از کار با dsh، پاسخدهی endpoint را تأیید کنید.
ollama list
curl -s http://127.0.0.1:11434/v1/modelsollama list تگ دقیق هر مدلی که دریافت کردهاید را چاپ میکند. آن رشته را کپی کنید. curl همان مدلها را به صورت JSON برمیگرداند. لیست خالی به این معنی است که Ollama در حال اجراست اما مدلی دریافت نشده است. Connection refused به این معنی است که Ollama در حال اجرا نیست یا روی پورت 11434 گوش نمیدهد.
مدلی را انتخاب کنید که روی این دستگاه اجرا میشود. سرور Ollama که وارد سیستم شده باشد، مدلهای ابری را نیز از طریق همان آدرس محلی ارائه میدهد و تگ ابری مانند gemma4:cloud روی سرورهای Ollama اجرا میشود؛ بنابراین پرامپتهای شما از دستگاه خارج میشوند، حتی اگر dsh فقط با 127.0.0.1 صحبت کند.
اکنون provider را به patch پروفایل اضافه کنید. یک مقدار غیرخالی برای API key در این پیکربندی وارد کنید؛ سرور محلی Ollama آن را نادیده میگیرد.
- id: llm-pi-ai
config:
providers:
local-ollama:
apiKeyEnv: OLLAMA_API_KEY
api: openai-completions
baseURL: http://127.0.0.1:11434/v1
models:
- id: <the exact tag printed by ollama list>متغیری که فرآیند dsh آن را میبیند، export کنید.
sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.envسه خطا تقریباً تمام تلاشها در این زمینه را پوشش میدهند. MISSING_CREDENTIAL به این معنی است که مرجع نامگذاری شده توسط apiKeyEnv به هیچ نتیجهای نرسیده است، بنابراین علاوه بر ترمینال، اعتبارنامههای ذخیرهشده و محیط اجرا را نیز بررسی کنید. UNKNOWN_MODEL به این معنی است که id با مدل پیکربندیشده مطابقت ندارد، بنابراین آن را کاراکتر به کاراکتر با ollama list، از جمله تگ بعد از دونقطه، مقایسه کنید. خطای 401 هنگام دریافت مدلهای موجود ناشی از کشف مدل است که GET /models را روی base URL شما فراخوانی میکند؛ endpointهایی که این مسیر را ارائه نمیدهند، نیاز دارند مدلهایشان به صورت دستی وارد شود.
یک تله دیگر، base URL است. /v1 را از انتهای آن حذف نکنید، در غیر این صورت درخواستها به مسیرهایی ارسال میشوند که Ollama ارائه نمیدهد و فراخوانی با خطای 404 برمیگردد و مدل هرگز اجرا نمیشود. این پسوند بخشی از سطح سازگار با OpenAI است، نه یک تزئین.
اگر Ollama روی دستگاه دیگری اجرا میشود، آدرس آن دستگاه به base URL تبدیل میشود و پرامپتهای شما از طریق شبکه به صورت متن ساده (cleartext) روی HTTP معمولی منتقل میشوند. آن را روی همان میزبان نگه دارید یا پشت TLS (امنیت لایه انتقال) و احراز هویت قرار دهید: locking down an exposed Ollama endpoint.
چه چیزی در هر حالت از دستگاه خارج میشود
با داشتن یک کلید DeepSeek و endpoint پیشفرض، درخواستهای مدل به API شرکت DeepSeek ارسال میشوند. این درخواست شامل prompt شما، محتوای فایلهایی که agent برای پاسخدهی خوانده است، خروجی دستوراتی که اجرا کرده و هر نتیجهای از ابزارهاست که برای گنجاندن انتخاب کرده است. هر زمان که agent فایلی را باز کند، کد منبع شما درون آن payload قرار میگیرد. این نحوهٔ کارکرد یک مدل میزبانیشده (hosted) است و به همین دلیل باید در مورد دایرکتوریای که agent را در آن اجرا میکنید، دقت کنید.
نسخههای فعلی همچنین بهطور پیشفرض، یک پسوند پذیرفتهنشده از لاگ رویدادهای نشست را از طریق آداپتور بومی DeepSeek، شامل gatewayهای پیکربندیشده، به عنوان یک فیلد جداگانه dsh_session_log به درخواستها پیوست میکنند. مدل هرگز آن را نمیبیند، اما مقصد درخواست آن را دریافت میکند. این قابلیت را در Settings و بخش General (گزینه "Upload Session Log when using the official model API") غیرفعال کنید، یا enabled: false را روی پلاگین session-log-deepseek تنظیم نمایید. سوئیچهای تلهمتری در ادامه، این آپلود را کنترل نمیکنند.
پروفایلهای ارائهشده همچنین نام و نسخهٔ بستههای پلاگین فعال را از طریق آداپتور بومی DeepSeek در یک فیلد جداگانه dsh_plugin_packages ارسال میکنند. برای متوقف کردن این مشارکت، enabled: false را روی plugin-package-inventory-deepseek تنظیم کنید.
با استفاده از یک ارائهدهنده کاتالوگ دیگر یا یک gateway شرکتی، همان payload به جای آن به آن فروشنده ارسال میشود. URL پایه دقیقاً به شما میگوید که مقصد کجاست.
با یک endpoint محلی، درخواست مدل به 127.0.0.1:11434 میرود، اما آدرس loopback به تنهایی باعث نمیشود که دادهها در دستگاه باقی بمانند. مستندات Ollama میگوید: "برای استفاده از مدلهای ابری از طریق این سرور، به Ollama وارد شوید"، بنابراین یک مدل ابری که از طریق همان سرور محلی انتخاب شده باشد، promptها و کد شما را به فضای ابری Ollama میفرستد. تنها زمانی که خودِ مدل بهصورت محلی اجرا شود، درخواست مدل در دستگاه باقی میماند. با این حال، سه مورد همچنان از شبکه عبور میکنند. npx بسته را از رجیستری npm دانلود میکند. هر ابزاری که agent اجرا میکند میتواند بهطور مستقل به اینترنت دسترسی داشته باشد، از جمله سرورهای MCP (پروتکل زمینه مدل) که به آنها متصل شدهاید، که در اجرای سرورهای MCP روی یک VPS بهطور مفصل پوشش داده شده است. یک پلاگین در همان دسته قرار میگیرد، زیرا نصب آن باعث اجرای کد نویسندهٔ دیگری با مجوزهای agent شما میشود، بنابراین ارزش آن را دارد که پیش از نصب پلاگین، بررسی کنید به چه چیزی دسترسی دارد. و تلهمتری، که نسخههای فعلی هر زمان که بازخورد ارسال میکنید، مجوز صادرات آن به DeepSeek را صادر میکنند، چه مدل محلی باشد و چه میزبانیشده.
تلهمتری بهطور پیشفرض به بازخورد محدود شده است. DSH_TELEMETRY_MODE حالت را انتخاب میکند و در پیکربندی پایه فعلی، مقدار تنظیمنشده یا خالی به FEEDBACK_ONLY تبدیل میشود. در آن حالت، فعالیتهای عادی هیچ مجوزی برای ضبط تلهمتری صادر نمیکنند. هنگامی که بازخورد متنی ارسال میکنید، رتبهبندی ایجاد یا ویرایش میکنید، یادداشتی را ویرایش میکنید یا بازخورد خود را پس میگیرید، dsh مجوز صادرات پیشوند لاگ نشست (که هنوز به صادرکننده تحویل داده نشده است) را از طریق آن رویداد بازخورد، شامل زمینه به ارث رسیده، به https://dsh-otel-collector.deepseeksvc.com/v1/logs صادر میکند. تحویل کامل تضمین نمیشود: یک رویداد بیش از حد بزرگ بدون کوتاه شدن رد میشود و پیشوندهای بزرگ ممکن است هنگام خروج از CLI بهصورت ناقص ارسالنشده باقی بمانند. دستههای مجاز میتوانند بدون تعامل یا فراخوانی مدل دیگر، به ارسال ادامه دهند. فایل README تلهمتری میگوید این مورد "برای همه کاربران و ارائهدهندگان" اعمال میشود، بنابراین اجرای محلی مدل آن را غیرفعال نمیکند. DISABLED هیچ انتقال OpenTelemetry (OTel) ایجاد نمیکند. FULL دیگر پذیرفته نمیشود: هر مقداری غیر از آن دو با unsupported mode رد میشود. صادرات بازخورد میتواند شامل متن پیام، آرگومانها و نتایج ابزارها و مسیرهای فضای کاری باشد، بنابراین بازخورد را به عنوان مجوزی برای ارسال آن پیشوند نشست به DeepSeek در نظر بگیرید.
برای توقف قطعی که به درست بودن رشته حالت وابسته نباشد، DSH_TELEMETRY_DISABLED=1 را تنظیم کنید. هر مقدار غیرخالی یک انصراف (opt-out) معتبر است، از جمله 0 و false، و این مقدار پیش از شروع اجرا خوانده میشود، بنابراین کد پروژه نمیتواند آن را در میانه نشست دوباره فعال کند. آدرس پیشفرض جمعآوریکننده dsh-otel-collector.deepseeksvc.com است؛ DSH_TELEMETRY_OTLP_URL آن را نادیده میگیرد.
به جای اعتماد به تنظیمات، آن را تأیید کنید. در حالی که یک وظیفه در حال اجراست، اتصالات خروجی که فرآیند نگه میدارد را لیست کنید.
sudo ss -tnp | grep -i nodeبا یک مدل که بهصورت محلی اجرا میشود، ترافیک مدل از پورت loopback 11434 استفاده میکند، اما اتصالات عمومی همچنان میتوانند بدون ارسال هیچ بازخوردی از سمت ابزارها ایجاد شوند. پروفایلهای ارائهشده شامل جستجوی وب و fetch هستند و پیشفرض مجوزها، دسترسی شبکه را محدود نمیکند. پیش از نسبت دادن هر مقصد عمومی به تلهمتری، آن را شناسایی کنید؛ زمانبندی به تنهایی ثابت نمیکند که یک اتصال، صادرات بازخورد است. این snapshot ممکن است اتصالات کوتاهمدت را نیز از دست بدهد. این بررسی فقط فرآیند dsh را پوشش میدهد: ترافیک یک مدل ابری از سرور Ollama خارج میشود، بنابراین تأیید کنید که مدل id یک برچسب ابری نباشد. شناسایی هر چیز دیگری پیش از ادامه کار ارزشمند است. آنچه یک agent کدنویسی به خانه میفرستد همین بررسی را روی ابزارهای دیگر اجرا میکند و نحوه خواندن نتیجه را توضیح میدهد.
مکانهایی که نباید اسرار را در آنها قرار داد
- تاریخچه شل (Shell history).
export DEEPSEEK_API_KEY=sk-...بهصورت متن ساده در~/.bash_historyنوشته میشود و مدتها پس از تغییر کلید (rotate) همچنان در آنجا باقی میماند. هنگامی کهHISTCONTROL=ignorespaceتنظیم شده است، پیش از دستور یک فاصله (space) قرار دهید یا از شل صرفنظر کرده و مقدار را مستقیماً با مجوز 600 در یک فایل بنویسید. - فایلهای dotfiles که commit شدهاند. یک کلید در
~/.bashrcیا~/.zshrcتنها به اندازه یکgit addبا یک مخزن عمومی فاصله دارد، اگر dotfiles را در git نگهداری میکنید. پیش از push کردن،git grep -I -n 'sk-'را در آن مخزن اجرا کنید. - فایلهای patch پروفایل. برای ارائهدهندگان سفارشی از
apiKeyEnvاستفاده کنید تاcordis.patch.ymlبهجای یک راز، حاوی نام یک متغیر باشد. فایلهای پیکربندی در گزارشهای خطا و چتهای پشتیبانی کپی میشوند، اما فایلهای حاوی اعتبارنامهها (credentials) نباید چنین باشند. - خروجی
envو اسکرینشاتهای ترمینال. هر چیزی که کل محیط (environment) را چاپ کند، کلید را نیز به همراه آن چاپ میکند. - نسخههای پشتیبان (Backups). ارزش
~/.dshدر پشتیبانگیری است، اما.credentials.yamlدرون آن یک راز فعال است. آن فایل را مستثنی کنید یا آرشیو را رمزنگاری نمایید.
این قوانین مختص dsh نیستند و نگهداری اسرار خارج از فایلهای env در Compose همین مشکل را در سمت کانتینرِ همان سرور پوشش میدهد.
کار با نسخه پیشنمایش توسعهدهنده
نسخهای را که تست کردهاید ثابت (pin) کنید، زیرا یک نسخه پیشنمایش ممکن است کلید پیکربندی را در یک نسخه patch تغییر دهد و در نتیجه ارائهدهنده شما قادر به بارگذاری آن نباشد. اگر نصب ثابتشده (pinned) از اجرا امتناع کرد، یا npx مدام بیلد ناخواستهای را به شما تحویل داد، خطاهای نصب و نسخه که یک پیشنمایش ایجاد میکند کش npx و نسخه npm همراه با Node شما را بررسی میکند. دایرکتوری home یعنی cordis.patch.yml و فایلهای patch در مسیر profiles/ را تحت کنترل نسخه (version control) نگه دارید و فایل credentials را از آن مستثنی کنید تا بتوانید تغییرات پس از ارتقا را مشاهده کنید.
هنگامی که یک پروفایل رفتار غیرمنتظرهای دارد، دو فلگ به شما کمک میکنند. --dump-default-config پیکربندی پیشفرض ترکیبشده را بدون بوت کردن چاپ میکند و --dump-config پیکربندی ترکیبشده برای پروفایل شما را به همان روش نمایش میدهد. مقایسه این دو نشان میدهد که لایه patch شما دقیقاً چه چیزی را تغییر داده است، که بسیار سریعتر از خواندن دستی لایههاست.
dsh --profile web --dump-configهنگامی که پس از یک ارتقا مشکلی پیش آمد، ابتدا آن دستور را اجرا کنید. کلیدی که بین نسخهها جابهجا شده است، به صورت یک شاخه (branch) گمشده در خروجی ظاهر میشود و اصلاح آن به جای نصب مجدد، تنها با یک ویرایش تکخطی انجام میشود.
FAQ
dsh کلید API مدل DeepSeek من را کجا ذخیره میکند؟
در $DSH_HOME/.credentials.yaml، که اگر خودتان DSH_HOME را تنظیم نکنید، بهصورت پیشفرض ~/.dsh/.credentials.yaml است. صفحه Models کلید را در آنجا مینویسد و تنظیمات شما فقط حاوی یک ارجاع به آن است، بنابراین این دادهٔ حساس در یک فایل واحد قرار دارد. وضعیت دسترسی (mode) فایل را با stat -c '%a %n' ~/.dsh/.credentials.yaml بررسی کنید و اگر مقداری غیر از 600 دارد، آن را به 600 تغییر دهید. یک ارائهدهندهٔ سفارشی میتواند با نامگذاری یک متغیر محیطی با apiKeyEnv، بهطور کامل از این فایل صرفنظر کند.
چگونه dsh را وادار کنم بهجای API مدل DeepSeek از یک مدل محلی استفاده کند؟
یک ارائهدهندهٔ سفارشی اضافه کنید که base URL آن، endpoint محلی سازگار با OpenAI شما باشد. برای Ollama این آدرس http://127.0.0.1:11434/v1 است، همراه با api: openai-completions و یک مدل id که دقیقاً از ollama list کپی شده باشد. برای این پیکربندی یک مقدار غیرخالی برای API key وارد کنید؛ سرور محلی Ollama آن را نادیده میگیرد. پیش از ویرایش هرگونه پیکربندی dsh، با curl -s http://127.0.0.1:11434/v1/models تأیید کنید که endpoint پاسخ میدهد، زیرا یک endpoint غیرفعال و یک پیکربندی اشتباه، خطاهای مشابهی ایجاد میکنند.
آیا dsh بهصورت پیشفرض کد من را به جایی میفرستد؟
در صورت استفاده از مدل میزبانیشده (hosted)، بله. prompt شما و محتوای فایلهایی که agent خوانده است، درون درخواست API به آن فروشنده قرار میگیرد. درخواستها از طریق آداپتور بومی DeepSeek، شامل gatewayهای پیکربندیشده، نیز بهصورت پیشفرض تا زمانی که آن را در بخش Settings و General غیرفعال نکنید، حاوی یک پسوند session-log هستند. با مدلی که Ollama بهصورت محلی اجرا میکند، آن درخواست به loopback میرود و روی همان دستگاه باقی میماند، اما یک مدل ابری مانند gemma4:cloud آن را از طریق همان آدرس loopback به فضای ابری Ollama میفرستد. ابزارهای داخلی جستجوی وب و fetch، سایر ابزارها و افزونهها میتوانند مستقل از بازخورد (feedback) با سرویسهای عمومی ارتباط برقرار کنند. تلهمتری یک جریان دادهٔ جداگانه است: در نسخههای فعلی، DSH_TELEMETRY_MODE در صورت تنظیمنشدن به FEEDBACK_ONLY ارجاع داده میشود، بنابراین بازخورد (feedback) اجازهٔ خروج پیشوند session-log را از طریق آن رویداد صادر میکند که شامل context به ارث رسیده برای همهٔ ارائهدهندگان، حتی مدلهای محلی، میشود. تحویل دادهها تضمینشده نیست و آپلودهای مجاز میتوانند پس از تعامل بازخورد نیز ادامه یابند. برای غیرفعالسازی کامل صادرکننده، آن را روی DISABLED تنظیم کنید، یا برای گزینهای که پیش از شروع اجرا خوانده میشود، DSH_TELEMETRY_DISABLED=1 را قرار دهید.
چرا با وجود تنظیم متغیر، dsh خطای MISSING_CREDENTIAL گزارش میدهد؟
زیرا ارجاعی که توسط apiKeyEnv نامگذاری شده است باید در منابع اعتبارسنجی dsh قابلحل باشد. اعتبارنامههای ذخیرهشده بر محیط اجرا (launch environment) اولویت دارند و پس از آن، فایلهای .env و $DSH_HOME/.env در دایرکتوری فراخواننده قرار میگیرند. متغیری که در shell شما export شده است، به یک سرویس systemd، نشست (session) کاربر دیگر یا فرآیندی که پیش از export کردن شما شروع شده، نمیرسد. مقدار را در یک EnvironmentFile با دسترسی 600 برای آن unit قرار دهید یا آن را در همان shell که dsh را شروع میکند، export کنید. با sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ تأیید کنید که فرآیند در حال اجرا واقعاً چه مقداری را در اختیار دارد.
dsh به کدام نسخه از Node.js نیاز دارد؟
طبق فایل package.json مخزن در تاریخ 5 نوامبر 2026، به Node.js 24.9 یا جدیدتر نیاز است. سری 22 دیگر پشتیبانی نمیشود و Node 24.0 تا 24.8 نیز کافی نیستند. پیش از هر کار دیگری node -v را اجرا کنید، زیرا شکست در راهاندازی به دلیل runtime پشتیبانینشده، شبیه به نصب خراب به نظر میرسد و باعث میشود کاربران بهجای نصب مجدد runtime، اقدام به نصب مجدد کل بسته کنند.