رفع خطاهای نصب و نسخه در DeepSeek Harness

نصب DeepSeek Harness دقیقاً چیست

نصب DeepSeek Harness تنها یک دستور است: npx @deepseek-ai/dsh web. هیچ برنامه نصبی وجود ندارد و هیچ سرویسی برای پیکربندی در کار نیست. بیشتر مشکلاتی که کاربران با آن مواجه می‌شوند، اصلاً مربوط به نصب نیست. مشکل اصلی، تعیین نسخه (version resolution) است: این‌که npx امروز تصمیم گرفته کدام build از @deepseek-ai/dsh را اجرا کند و این‌که آیا نسخه Node.js شما توانایی اجرای آن را دارد یا خیر.

دو واقعیت، تمام موارد زیر را هدایت می‌کند. نخست، هر نسخه از @deepseek-ai/dsh که تاکنون در npm منتشر شده، یک release candidate است و تگ latest به یکی از آن‌ها اشاره دارد. تا تاریخ 18 August 2026، این نسخه 0.1.0-rc.7 است که در 17 August 2026 منتشر شده است. دوم، فایل README پروژه بیان می‌کند که این harness در مرحله developer preview قرار دارد، به‌سرعت در حال تغییر است و تغییرات ناسازگار (compatibility-breaking) خواهد داشت. پرچمی که هفته گذشته کار می‌کرد، ممکن است این هفته حذف شده باشد. پیش از آن‌که هر چیزی بر پایه آن بسازید، نسخه را ثابت (pin) کنید.

ابتدا چند اصطلاح: dsh ابزار خط فرمان DeepSeek Harness است. Node.js محیط اجرای JavaScript است که به آن نیاز دارد. npx یک package runner است که همراه با npm (مدیر بسته node) ارائه می‌شود و به‌جای نصب دائمی یک بسته، آن را در لحظه دریافت و اجرا می‌کند.

dsh به کدام نسخه Node.js نیاز دارد؟

ریشه مخزن package.json نسخه "engines": {"node": "^22.19.0 || >=24.0.0"} را اعلام می‌کند که در تاریخ 18 آگوست 2026 در نسخه 0.1.0-rc.7 خوانده شده است. بنابراین به Node 22.19.0 یا جدیدتر در شاخه 22، یا Node 24 و بالاتر نیاز دارید. Node 20 پشتیبانی نمی‌شود.

پیش از هر اقدامی، نسخه فعلی خود را بررسی کنید.

node -v
npm -v

این بخشی است که کاربران را غافلگیر می‌کند. بسته منتشرشده @deepseek-ai/dsh فاقد فیلد engines در فایل خود است. فقط ریشه monorepo این فیلد را اعلام می‌کند و آن فایل ریشه هرگز در npm منتشر نمی‌شود. بنابراین npm چیزی برای بررسی ندارد، هیچ هشدار EBADENGINE چاپ نمی‌کند و مانع نصب نمی‌شود. در Node 20 به نظر می‌رسد نصب با موفقیت انجام شده است، اما خطا زمانی رخ می‌دهد که کد بارگذاری‌شده به سینتکس یا API دسترسی پیدا کند که runtime شما از آن پشتیبانی نمی‌کند. هیچ رشته خطای واحد و پایداری برای جستجو وجود ندارد، زیرا اینکه کدام خط ابتدا با خطا مواجه شود، به ترتیب بارگذاری ماژول‌ها بستگی دارد. به جای بررسی متن خطا، node -v را مطالعه کنید.

اگر نسخه Node شما قدیمی است، nvm (مدیریت نسخه Node) کم‌دردسرترین راه حل روی VPS است، زیرا در دایرکتوری home شما نصب می‌شود و Node سیستمی را دست‌نخورده باقی می‌گذارد.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
exec $SHELL -l
nvm install 24
nvm use 24
node -v

node -v اکنون باید نسخه‌ای را چاپ کند که با v24. شروع می‌شود. اگر shell همچنان نسخه قدیمی را گزارش می‌دهد، تابع shell مربوط به nvm بارگذاری نشده است؛ بنابراین یک login shell جدید باز کنید و دوباره امتحان کنید. Node 24.19.0 نسخه LTS (پشتیبانی بلندمدت) فعال تا آگوست 2026 است و به دلیلی که در ادامه به آن می‌پردازیم، هدف بهتری برای نصب محسوب می‌شود.

چرا npx هر روز نسخه متفاوتی را اجرا می‌کند؟

npx @deepseek-ai/dsh web هیچ نسخه‌ای را مشخص نمی‌کند، بنابراین npx از رجیستری می‌پرسد که برچسب latest به چه چیزی اشاره دارد. آن برچسب تغییر می‌کند. وقتی DeepSeek نسخه 0.1.0-rc.8 را منتشر می‌کند، دستوری که در یادداشت‌های شما قرار دارد شروع به اجرای کد متفاوتی می‌کند، بدون اینکه هیچ اعلان یا لیست تغییراتی پیش روی شما باشد.

شما می‌توانید هر بخش متغیر را از طریق خط فرمان بررسی کنید.

npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --json

dist-tags نشان می‌دهد که در حال حاضر latest به چه چیزی اشاره دارد. در تاریخ 18 August 2026 هر دو مورد latest و next به 0.1.0-rc.7 اشاره داشتند، بنابراین کانال پایدار مجزایی برای سوئیچ کردن وجود ندارد. لیست versions جالب‌تر است، زیرا در آن حفره‌هایی وجود دارد: 0.0.1-rc.1، 0.0.1-rc.2، 0.0.1-rc.5، 0.1.0-rc.2، 0.1.0-rc.3، 0.1.0-rc.6، 0.1.0-rc.7. اعداد در آن توالی جا افتاده‌اند زیرا برخی از نسخه‌های کاندیدای انتشار (release candidates) هرگز منتشر نشدند. حدس زدن -rc.N بعدی در یک اسکریپت استقرار (deploy script) با شکست مواجه خواهد شد، بنابراین به‌جای شمارش رو به بالا، لیست را بخوانید.

چرا npx همچنان نسخه قدیمی را اجرا می‌کند؟

این دقیقاً نقطه مقابل شکایت قبلی است و بسته به اینکه از کدام نسخه npm استفاده می‌کنید، هر دو مورد صادق هستند.

npx دایرکتوری پکیج مخصوص به خود را دارد که از کش tarball جداست و در پوشه‌ای به نام _npx در داخل کش npm قرار دارد. مسیر آن را چاپ کنید و بررسی نمایید:

npm config get cache
ls "$(npm config get cache)/_npx"

سال‌ها npx برای نام‌های پکیج ساده (bare package name) از هر چه در آنجا پیدا می‌کرد استفاده می‌کرد و هرگز دوباره از registry پرس‌وجو نمی‌کرد. npm 11.2.0 این رفتار را تغییر داد. اکنون وقتی مشخصات پکیج یک نام ساده یا محدوده نسخه باشد، npx ابتدا manifest را دریافت می‌کند و تنها زمانی از نسخه کش‌شده استفاده می‌کند که tarball حل‌شده با آنچه registry به‌تازگی بازگردانده است، مطابقت داشته باشد.

اینکه کدام رفتار را دریافت می‌کنید توسط نسخه Node شما تعیین می‌شود، زیرا Node یک نسخه خاص از npm را همراه خود دارد:

• Node 20.20.2 شامل npm 10.8.2 است.
• Node 22.19.0 شامل npm 10.9.3 است.
• Node 22.23.2، جدیدترین نسخه 22، شامل npm 10.9.8 است.
• Node 24.19.0 شامل npm 11.17.0 است.

بنابراین کل سری Node 22 که harness به‌طور رسمی از آن پشتیبانی می‌کند، نسخه‌ای از npm قدیمی‌تر از 11.2.0 را ارائه می‌دهد. در Node 22، یک npx @deepseek-ai/dsh web ساده همچنان همان release candidate که هفته‌ها پیش کش شده است را اجرا می‌کند. همان دستور در Node 24 در هر بار اجرا، دوباره resolve می‌شود. یک دستور، دو رفتار متفاوت، و هیچ‌کدام هم به شما هشدار نمی‌دهند. از خود ابزار بپرسید که چیست:

npx @deepseek-ai/dsh --version

پاک‌سازی کش npx

در npm 11.2.0 و نسخه‌های جدیدتر، زیردستورهای اختصاصی وجود دارند.

npm cache npx ls
npm cache npx rm --force

بدون --force، npm از پاک کردن همه چیز خودداری کرده و Please use --force to remove entire npx cache را چاپ می‌کند. زمانی که می‌خواهید یک ورودی خاص را بر اساس کلید حذف کنید و نه همه آن‌ها را، ابتدا از npm cache npx ls استفاده کنید.

در npm 10 این زیردستورها وجود ندارند، بنابراین باید دایرکتوری را شخصاً حذف کنید.

rm -rf "$(npm config get cache)/_npx"

npm cache clean --force در اینجا کمکی نمی‌کند. این دستور _cacache یعنی محل ذخیره tarballها را پاک می‌کند و کاری به _npx ندارد. همین جداسازی دقیقاً دلیلی است که npm بعداً زیردستورهای npm cache npx را اضافه کرد. پاک کردن _npx نیز هیچ هزینه دائمی برای شما ندارد: این پوشه فقط پکیج‌های دانلود شده را نگه می‌دارد، در حالی که وضعیت harness شما در $DSH_HOME/profiles/<name> قرار دارد و دست‌نخورده باقی می‌ماند.

چگونه یک نسخه release candidate خاص را پین کنم؟

نام کامل نسخه، شامل بخش -rc.N را ذکر کنید.

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

استفاده از --yes در اسکریپت اهمیت دارد، زیرا در غیر این صورت npx پیش از نصب بسته‌ای که قبلاً مشاهده نکرده است، یک اعلان (prompt) نمایش می‌دهد و منتظر پاسخی می‌ماند که هرگز دریافت نخواهد شد.

نسخه دقیق، سریع‌ترین مسیر نیز هست. npx دایرکتوری کش خود را بر اساس رشته مشخصاتی که وارد کرده‌اید کلیدگذاری می‌کند و برای یک نسخه دقیق، آن را با شناسه بسته‌ای که از قبل نصب شده مقایسه کرده و بدون هیچ رفت‌وبرگشتی به registry، آن را اجرا می‌کند. در npm 11.2.0 و نسخه‌های جدیدتر، استفاده از نام ساده (بدون نسخه) باعث می‌شود در هر بار اجرا، یک درخواست برای دریافت manifest ارسال شود.

نصب سراسری (global) نیز به همین شکل پین می‌شود و یک دستور کوتاه در اختیار شما قرار می‌دهد.

npm install -g @deepseek-ai/dsh@0.1.0-rc.7
dsh --version

خطای No matching version found for @deepseek-ai/dsh@^0.1.0

محدوده‌های caret یا tilde برای این بسته کار نمی‌کنند. npm install -g @deepseek-ai/dsh@^0.1.0 با کد خطای ETARGET و خط No matching version found for @deepseek-ai/dsh@^0.1.0. پاسخ می‌دهد. وضعیت registry سالم است. این یک قانون semver است: یک محدوده نسخه با نسخه prerelease مطابقت ندارد، مگر اینکه خود محدوده نیز یک prerelease را نام ببرد. هر build منتشرشده از این بسته دارای پسوند -rc.N است که یک prerelease محسوب می‌شود، بنابراین ^0.1.0 با هیچ‌چیز مطابقت ندارد. نسخه دقیق را بنویسید.

این قانون یک اثر جانبی مفید دارد. از آنجا که محدوده‌ها نمی‌توانند به یک release candidate جدید تغییر مسیر دهند، هیچ وضعیت نیمه‌پین‌شده‌ای وجود ندارد که نیاز به تحلیل داشته باشد. شما یا روی یک نسخه دقیق هستید یا روی یک تگ متغیر.

آیا باید از npx استفاده کنم یا dsh را به‌صورت سراسری (globally) نصب کنم؟

برای بررسی اولیه از npx استفاده کنید، زیرا به‌جز یک دایرکتوری cache که اکنون می‌دانید چگونه آن را پاک کنید، هیچ فایلی باقی نمی‌ماند. برای هر چیزی که باید پس از reboot همچنان کار کند، مانند یک coding agent که روی یک VPS اجرا می‌کنید، از نصب سراسری با نسخه ثابت (pinned) استفاده کنید.

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

which dsh
dsh --version
npx @deepseek-ai/dsh --version

which dsh پیدا نشدن دستور بلافاصله پس از یک نصب سراسری موفق، تقریباً همیشه به این معنی است که دایرکتوری bin سراسری npm در PATH شما وجود ندارد. دستور npm prefix -g را اجرا کنید تا مسیر root چاپ شود؛ فایل‌های اجرایی در پوشه bin در زیرمجموعه آن قرار دارند.

یک نکته امنیتی: npx هر زمان که مورد جدیدی را resolve می‌کند، کد را از registry دریافت و اجرا می‌کند که در یک سرور، یک آسیب‌پذیری واقعی است، نه صرفاً تئوری. Pin کردن بخشی از پاسخ است. بقیه پاسخ در چگونگی نفوذ حملات زنجیره تأمین npm به سرور آمده است.

معنای نسخه پیش‌نمایش توسعه‌دهنده برای تکرارپذیری

0.1.0-rc.6 در تاریخ 13 اوت 2026 و 0.1.0-rc.7 در 17 اوت 2026 منتشر شد. با فاصله چهار روز. با این سرعت، دستورالعمل‌هایی که یک ماه پیش نوشته شده‌اند ممکن است خط فرمانی را توصیف کنند که دیگر وجود ندارد، و این شامل همین صفحه نیز می‌شود. برای هر ادعای نسخه‌ای که یادداشت می‌کنید، از جمله یادداشت‌های خودتان، تاریخ بزنید.

دو عادت باعث می‌شود پیش‌نمایش قابل‌تحمل باشد. نسخه دقیق را در هر دستور و هر اسکریپت ثابت (Pin) کنید تا بازسازی سرور، همان محیط اجرایی را تولید کند. سپس خروجی راهنما (help) را از همان بیلد ثابت‌شده بخوانید، نه از هیچ راهنمای دیگری.

npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-config

نیمه دوم تکرارپذیری، پروفایل است. dsh --profile <name> پروفایل ذخیره‌شده در $DSH_HOME/profiles/<name> را بارگذاری می‌کند و پروفایل‌های web و headless در اولین استفاده از روی قالب‌های ارائه‌شده ساخته می‌شوند. آن دایرکتوری همچنین جایی است که harness کلید API، مدل و تنظیمات endpoint خود را از آن می‌خواند، بنابراین یک نسخه ثابت‌شده و یک پیکربندی کاری، دو مورد مجزا هستند که باید به درستی تنظیم شوند. بسته‌های داخلی (In-box bundles) از نصب dsh که در حال اجراست حل می‌شوند، به این معنی که تغییر نسخه ثابت‌شده شما، آن بسته‌ها را نیز تغییر می‌دهد. افزونه‌های خارج از درخت (Out-of-tree plugins) رفتار متفاوتی دارند. آن‌ها در دایرکتوری پروفایل قرار دارند و dsh plugin --profile <name> add <package> آرگومان‌های خود را برای نصب آن‌ها به pnpm ارسال می‌کند. بنابراین pnpm باید در PATH شما باشد و dsh وقتی این‌طور نیست، به وضوح آن را اعلام می‌کند. فایل package.json خودِ پروفایل است که آن افزونه‌ها را ثابت می‌کند، بنابراین یک ثابت‌سازی (pin) کامل، دو فایل را پوشش می‌دهد، نه یکی.

اگر ابزارهای پایتون را در محیط‌های ایزوله روی سرور نگه داشته باشید، این جداسازی برایتان آشنا خواهد بود: ابزار و چیزهایی که به آن اضافه می‌کنید در مکان‌های جداگانه‌ای ثابت می‌شوند. هنگامی که harness شروع به کار می‌کند، سوال بعدی معمولاً به جای نسخه‌ها، شبکه است که در آن دسترسی به رابط کاربری وب dsh روی یک VPS از راه دور و راهنمای طولانی‌تر در نصب DeepSeek Harness روی یک VPS وارد عمل می‌شوند.

خطاهای آرگومان که با آن‌ها مواجه خواهید شد

این خطاها از پارسر داخلی CLI ناشی می‌شوند، بنابراین در تمامی نسخه‌های release candidate ثابت هستند و هر کدام دقیقاً به مشکل اشاره می‌کنند.

error: --profile <name> is required

شما npx @deepseek-ai/dsh را بدون زیردستور و بدون profile اجرا کرده‌اید. دستور پایه یک profile را بوت می‌کند، بنابراین به یک نام نیاز دارد. dsh web زیردستوری است که به هیچ --profile نیاز ندارد، زیرا profile پیش‌فرض web را برای شما بوت می‌کند.

error: --patch needs a path

--patch بدون هیچ مقداری پس از آن فراخوانی شده است. این فلگ قابل تکرار است و هر بار باید یک مسیر فایل به آن داده شود.

error: --dump-config and --dump-default-config are mutually exclusive

یکی را انتخاب کنید. --dump-default-config لایه‌های باندل ارائه‌شده را چاپ می‌کند و هیچ --patch را نمی‌پذیرد. --dump-config پیکربندی ترکیب‌شده برای یک profile را چاپ می‌کند. هر دو دستور پس از چاپ اطلاعات، بدون اجرای harness خارج می‌شوند؛ این روش امن‌ترین راه برای مشاهده تغییرات اعمال‌شده در یک release candidate جدید است.

error: plugin needs pnpm arguments to forward (e.g. add <package>)

به dsh plugin --profile <name> هیچ مقداری برای انتقال داده نشده است. این زیردستور در صورت نبود profile، آن را مقداردهی اولیه می‌کند و سپس باقی خط فرمان را به pnpm می‌سپارد، بنابراین به آرگومان‌هایی مانند add @scope/dsh-plugin-example نیاز دارد.

FAQ

DeepSeek Harness به کدام نسخه از Node.js نیاز دارد؟

مخزن پروژه در ^22.19.0 || >=24.0.0 واقع در ریشه package.json، این مورد را در تاریخ 18 اوت 2026 و در نسخه 0.1.0-rc.7 اعلام کرده است. بنابراین به Node 22.19.0 یا نسخه‌های بالاتر از سری 22، یا Node 24 و جدیدتر نیاز دارید. Node 20 کار نخواهد کرد. پکیج منتشرشده در npm فاقد فیلد engines است، بنابراین npm هرگز به شما هشدار نمی‌دهد و نصب را مسدود نمی‌کند؛ در نتیجه خطا در زمان اجرا (runtime) ظاهر می‌شود. ابتدا node -v را بررسی کنید. در هر صورت Node 24 انتخاب بهتری است، زیرا همراه با npm 11 عرضه می‌شود که مشکل استفاده مجدد از نسخه در npx را برطرف کرده است.

چگونه npx را مجبور کنم به جای استفاده از نسخه کش‌شده، از جدیدترین dsh استفاده کند؟

در npm 11.2.0 و نسخه‌های جدیدتر، npx @deepseek-ai/dsh در هر بار اجرا، رجیستری را برای نام پکیج بررسی می‌کند. در npm 10 که همراه با تمام نسخه‌های Node 22 ارائه می‌شود، این اتفاق نمی‌افتد. کش npx را در npm 11 با npm cache npx rm --force پاک کنید یا در npm 10 پوشه مربوطه را با rm -rf "$(npm config get cache)/_npx" حذف نمایید. سپس با npx @deepseek-ai/dsh --version تأیید کنید. توجه داشته باشید که npm cache clean --force دایرکتوری متفاوتی را پاک می‌کند و این مشکل را حل نخواهد کرد.

چرا نصب @deepseek-ai/dsh@^0.1.0 با خطا مواجه می‌شود؟

npm کد خطای ETARGET را همراه با خط No matching version found for @deepseek-ai/dsh@^0.1.0. برمی‌گرداند. تمام بیلد‌های منتشرشده، پیش‌انتشار (prerelease) هستند (مانند 0.1.0-rc.7) و بازه semver با نسخه‌های پیش‌انتشار مطابقت ندارد، مگر اینکه خود بازه به یک نسخه خاص اشاره کند. نسخه دقیق را با درج پسوند -rc.N نصب کنید. برای مشاهده نسخه‌های موجود، npm view @deepseek-ai/dsh versions --json را اجرا کنید، زیرا در توالی نسخه‌ها شکاف‌هایی وجود دارد که نشان‌دهنده کاندیداهای انتشاری است که هرگز منتشر نشده‌اند.

آیا باید dsh را به صورت سراسری (global) نصب کنم یا از طریق npx اجرا کنم؟

npx برای بررسی اولیه مناسب است، زیرا به جز دایرکتوری کش، چیزی در سیستم باقی نمی‌ماند. نصب سراسریِ پین‌شده (pinned) مانند npm install -g @deepseek-ai/dsh@0.1.0-rc.7 برای هر کاری که باید به‌طور مداوم کار کند مناسب است، زیرا نسخه فقط زمانی تغییر می‌کند که شما آن را تغییر دهید. اگر پس از نصب سراسری، دستور dsh پیدا نشد، دایرکتوری bin سراسری npm در PATH شما وجود ندارد؛ npm prefix -g مسیر ریشه‌ای که در آن قرار دارد را چاپ می‌کند.

آیا DeepSeek Harness برای توسعه به اندازه کافی پایدار است؟

هنوز خیر، طبق توضیحات خود پروژه. فایل README بیان می‌کند که این پروژه در مرحله پیش‌نمایش توسعه‌دهنده (developer preview) است، به‌سرعت در حال تغییر است و تغییرات ناسازگار با نسخه‌های قبلی خواهد داشت. کاندیداهای انتشار 0.1.0-rc.6 و 0.1.0-rc.7 با فاصله چهار روز در اوت 2026 منتشر شدند. یک نسخه دقیق را پین کنید و به جای تکیه بر راهنماها، --help همان بیلد پین‌شده را مطالعه کنید. برای یادداشت‌های خود تاریخ بزنید تا متوجه شوید چقدر قدیمی شده‌اند.