إعداد dsh: مفاتيح API والنماذج ونقاط النهاية

المكان الذي يحتفظ فيه dsh بإعداده

يحتفظ dsh (DeepSeek Harness) بإعداده في دليل واحد: $DSH_HOME، والقيمة الافتراضية له هي ~/.dsh. تُكتب كل قيمة تضبطها في Web UI هناك كملفات نصية عادية. انسخ هذا الدليل إلى خادم آخر، وسيعمل الخادم الجديد مثل الخادم القديم.

تحتوي أربعة مسارات على كل ما ستتعامل معه.

• يحتوي ~/.dsh/settings.yaml على الإعدادات المكتوبة يدوياً وتلك التي تكتبها واجهة المستخدم، بما في ذلك مسارات الموفر والنموذج.
• يحتوي ~/.dsh/.credentials.yaml على الأسرار. تحتفظ الإعدادات بمرجع إلى بيانات اعتماد فقط، بينما توجد قيمة المفتاح نفسها في ملف واحد.
• يحتوي ~/.dsh/profiles/ على الملفات التعريفية المسماة، ويحتوي ~/.dsh/storages/ على الجلسات المحفوظة.
• يمثّل ~/.dsh/cordis.patch.yml طبقة التصحيحات الخاصة بك. تُطبَّق هذه الطبقة فوق الإعداد المضمّن لكل ملف تعريفي.

أعلن DeepSeek عن harness كإصدار معاينة للمطورين بترخيص MIT في 17 August 2026، وتذكر README أنّه ستطرأ تغييرات تؤدي إلى كسر التوافق. تتوافق أسماء الحقول والمسارات في هذا الدليل مع توثيق المستودع حتى August 2026. قارِنها بتوثيق الإصدار الذي ثبّتَّه قبل نسخ الإعداد من أي دليل، بما في ذلك هذا الدليل، لأن إصدار المعاينة قد يعيد تسمية العناصر بين الإصدارات.

الحد الأدنى الصادق للوصول إلى أول مخرَج

يحتاج dsh إلى Node.js 22.19 أو إصدار أحدث ضمن السلسلة 22، أو إلى الإصدار 24 وما بعده. يقع Node 23 خارج هذا النطاق. تحقّق من الإصدار أولاً، لأن عدم تطابق الإصدار يفشل عند بدء التشغيل، وتبدو رسالة الخطأ كأنها تشير إلى وجود حزمة معطوبة.

node -v
npx @deepseek-ai/dsh web

ينزّل npx الحزمة من سجل npm ويبدأ واجهة Web UI على http://127.0.0.1:3080. ويربط عنوان loopback، ما يعني أن المنفذ لا يمكن الوصول إليه من جهاز آخر حتى عندما يسمح جدارك الناري بذلك. على VPS، مرّر الاتصال عبر SSH بدلاً من فتح المنفذ 3080 أمام الإنترنت.

ssh -N -L 3080:127.0.0.1:3080 you@your-server

افتح http://127.0.0.1:3080 على الكمبيوتر المحمول، ثم انتقل إلى Settings وModels. تحتوي بطاقة DeepSeek على حقل واحد لمفتاح API. الصق المفتاح من platform.deepseek.com واحفظه. يصبح مسار النموذج قابلاً للاستخدام فوراً دون إعادة تشغيل، لأن الخادم قيد التشغيل يخزّن بيانات الاعتماد ويحلّ المرجع مباشرة. يشرح الوصول إلى واجهة dsh Web UI على خادم بعيد حالة النفق وreverse proxy، بينما يشرح تثبيت DeepSeek Harness على VPS إعداد الخادم الذي يفترضه هذا الدليل.

بعد الحفظ، تحقّق مما أنشأه التطبيق.

ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml

ينبغي أن ترى settings.yaml و.credentials.yaml وprofiles/. إذا طبع stat وضعاً غير 600، فنفّذ chmod 600 ~/.dsh/.credentials.yaml. يتيح ملف بيانات اعتماد قابل للقراءة من المجموعة أو من جميع المستخدمين مفتاحك لكل حساب آخر على الخادم.

لإجراء التشغيل الأول دون متصفح، يكفي أمر واحد.

npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"

يشغّل ملف التعريف headless جلسة واحدة ويطبع الإجابة النهائية.

متغيرات البيئة أو ملف الإعداد

توجد طريقتان لمنح dsh مفتاحاً، ولا يمكن استخدامهما بالتبادل.

يحصل موفّر الكتالوج (DeepSeek وAnthropic وOpenAI وبقية القائمة المضمّنة) على مفتاحه من خلال صفحة Models. تُحفظ القيمة في ~/.dsh/.credentials.yaml، ولا تتضمن إعداداتك سوى مرجع إليها. ولا تعرض Web UI المفتاح مرة أخرى بعد حفظه.

يمكن لموفّر مخصّص استخدام متغير بيئة بدلاً من ذلك، مع apiKeyEnv. هذا هو الشكل الذي توضحه الوثائق في ~/.dsh/settings.yaml.

llm-pi-ai:
  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]

أضف موفّراً واحداً أولاً من خلال Web UI، ثم افتح ~/.dsh/settings.yaml وانسخ البنية التي أنشأها. أثناء المعاينة للمطورين، تكون البنية المتداخلة أكثر الأجزاء عرضة للتغيير، والملف الذي أنشأه التطبيق للتو يكون دائماً محدثاً.

تُقرأ apiKeyEnv من بيئة عملية dsh، وليس من shell تسجيل الدخول الخاص بك. يكون المفتاح الذي تصدّره في جلسة تفاعلية غير مرئي لوحدة systemd، لذلك يعيد الإعداد نفسه الذي يعمل عند كتابة dsh web يدوياً القيمة MISSING_CREDENTIAL عند تشغيله كخدمة. امنح الوحدة ملفاً خاصاً بها.

[Service]
EnvironmentFile=/etc/dsh/dsh.env

احتفظ بهذا الملف بالوضع 600، واجعله مملوكاً للمستخدم الذي تعمل الخدمة بحسابه.

اختيار النماذج ومعرّف لا يمكنك إعادة تسميته

يظهر كل موفّر تم تكوينه في منتقي النماذج. ويؤدي اختيار نموذج أيضاً إلى تعيينه نموذجاً افتراضياً للجلسات الجديدة. أما الجلسات الموجودة مسبقاً، فتحتفظ بالنموذج المسجّل فيها، لذلك لا يغيّر التبديل محادثة قديمة.

معرّف Provider دائم. تشير إليه الطلبات والجلسات المحفوظة والإعدادات الافتراضية للنماذج ومراجع بيانات الاعتماد، لذلك لا يوجد زر لإعادة تسميته. تغييره يعني إنشاء موفّر جديد وحذف الموفّر القديم. اختر اسماً يمكنك الإبقاء عليه: local-ollama بدلاً من test2.

تكون النماذج نصية فقط ما لم تعلن خلاف ذلك. أضف input: [text, image] إلى إدخال النموذج للإعلان عن دعم الصور، أو عيّن defaultInput على مستوى route كخيار احتياطي للنماذج التي لا يصفها الكتالوج. إن route الخاص بـDeepSeek والمبني على chat-completions نصي فقط ولا يمكن تكوينه بطريقة أخرى، لذلك يُرفض إرفاق صورة بهذا route قبل إرسال أي شيء.

وجّه dsh إلى نقطة نهاية محلية حتى يبقى الكود على الخادم

يوفّر Ollama واجهة API متوافقة مع OpenAI على http://127.0.0.1:11434/v1. يتصل dsh بأي عنوان أساسي متوافق مع OpenAI عبر موفّر مخصص، لذلك يتصل البرنامجان مباشرةً دون طبقة وسيطة. أعدّ خادم النماذج أولاً: يشرح استضافة LLM ذاتياً باستخدام Ollama على VPS طريقة التثبيت وتنزيل النموذج.

تأكد من أن نقطة النهاية تستجيب قبل تعديل dsh.

ollama list
curl -s http://127.0.0.1:11434/v1/models

يطبع ollama list الوسم الدقيق لكل نموذج نزّلته. انسخ هذه السلسلة. يعرض curl النماذج نفسها بتنسيق JSON. تعني القائمة الفارغة أن Ollama يعمل من دون تنزيل أي نموذج. يعني Connection refused أن Ollama لا يعمل أو أنه لا يستمع على 11434.

أضف الموفّر الآن. يتطلب Ollama حقلاً لمفتاح API ويتجاهل قيمته، لذلك تصلح أي سلسلة غير فارغة.

llm-pi-ai:
  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 من رؤيته.

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

تغطي 3 حالات فشل معظم المحاولات. يعني MISSING_CREDENTIAL أن dsh لم يتمكن من قراءة المتغير الذي يسميه apiKeyEnv، لذلك افحص بيئة العملية، لا بيئة الطرفية. يعني UNKNOWN_MODEL أن id لا يطابق نموذجاً مهيّأً، لذلك قارنه مع ollama list حرفاً بحرف، بما في ذلك الوسم الذي يلي النقطتين. ينتج الخطأ 401 أثناء جلب النماذج المتاحة عن اكتشاف النماذج، إذ يستدعي GET /models على عنوانك الأساسي؛ وتحتاج نقاط النهاية التي لا توفّر هذا المسار إلى إدخال نماذجها يدوياً.

هناك مشكلة أخرى محتملة في العنوان الأساسي. اترك /v1 خارج العنوان، وإلا ستصل الطلبات إلى مسارات لا يوفّرها Ollama، فتُرجع العملية الخطأ 404 ولا يعمل النموذج. هذه اللاحقة جزء من واجهة OpenAI المتوافقة، وليست نصاً زائداً.

إذا كان Ollama يعمل على جهاز آخر، يصبح عنوان ذلك الجهاز هو العنوان الأساسي، ثم تعبر مطالباتك الشبكة بنص واضح عبر HTTP العادي. أبقه على المضيف نفسه، أو ضعه خلف TLS (أمان طبقة النقل) والمصادقة: تأمين نقطة نهاية Ollama المكشوفة.

ما الذي يغادر الجهاز في كل وضع

عند استخدام مفتاح DeepSeek، يُرسل كل طلب إلى API الخاص بـDeepSeek. يتضمن الطلب الموجّه الذي أدخلته، ومحتويات الملفات التي قرأها الوكيل للإجابة عنه، ومخرجات الأوامر التي شغّلها، وأي نتائج أدوات اختار تضمينها. يكون كود المصدر جزءاً من هذه البيانات عندما يفتح الوكيل ملفاً. هكذا يعمل النموذج المستضاف، ولذلك يجب أن تفكّر في الدليل الذي تبدأ الوكيل منه.

عند استخدام موفّر آخر من الكتالوج أو بوابة تابعة لشركتك، تُرسل البيانات نفسها إلى ذلك الموفّر بدلاً من ذلك. ويحدّد عنوان URL الأساسي المكان بدقة.

عند استخدام نقطة نهاية محلية، يُرسل طلب النموذج إلى 127.0.0.1:11434 ويبقى على الجهاز. لا يصل أي جزء من كودك إلى موفّر نموذج. لكن ثلاثة أشياء تعبر الشبكة مع ذلك. ينزّل npx الحزمة من سجل npm. ويمكن لأي أداة يشغّلها الوكيل الوصول إلى الإنترنت بشكل مستقل، بما في ذلك خوادم MCP (بروتوكول سياق النموذج) التي ربطتها؛ ويشرح تشغيل خوادم MCP على VPS ذلك بالتفصيل. كما تعبر بيانات القياس الشبكة إذا فعّلتها.

تكون بيانات القياس معطّلة حتى توافق على تفعيلها. DSH_TELEMETRY_MODE هو مفتاح الموافقة، وتتحول القيم غير المعيّنة أو الفارغة أو غير المعروفة إلى DISABLED. في هذه الحالة، لا ينشئ dsh أي موفّر أو معالج أو مُصدّر لـOpenTelemetry (OTel)، ولذلك لا يُجري الملف الشخصي الجديد أي طلب شبكة لبيانات القياس. يفعّل FEEDBACK_ONLY مشاركة سجل الجلسة عند إرسال ملاحظات. ويسمح FULL أيضاً بإرسال تقارير المشغّل. ويمكن لخلاصة الجلسة تصدير محتوى الجلسة وبيانات الأدوات والموجّهات ومسارات مساحة العمل، لذلك اعتبر FULL إرسالاً لعملك إلى DeepSeek.

لإيقاف ذلك نهائياً دون الاعتماد على ضبط سلسلة الوضع بشكل صحيح، عيّن DSH_TELEMETRY_DISABLED=1. أي قيمة غير فارغة تُعدّ إلغاء اشتراك صريحاً، وتُقرأ قبل بدء التشغيل، لذلك لا يستطيع كود المشروع إعادة تفعيلها أثناء الجلسة. عنوان المُجمّع الافتراضي هو harness-telemetry.deepseeksvc.com، ومن المفيد معرفة هذا الاسم عند قراءة سجلات الجدار الناري الخاص بك.

تحقق بدلاً من الوثوق بالإعداد. أثناء تشغيل مهمة، اعرض الاتصالات الصادرة التي تحتفظ بها العملية.

sudo ss -tnp | grep -i node

في وضع النموذج المحلي، يجب أن ترى اتصال loopback بالمنفذ 11434، وألا ترى أي اتصال بعنوان عام. يجب تحديد أي اتصال آخر قبل المتابعة. يجري ما الذي يرسله وكيل البرمجة إلى الجهة المشغّلة الفحص نفسه مع أطر تشغيل أخرى، ويشرح كيفية قراءة النتيجة.

المواضع التي يجب ألا تضع فيها الأسرار

• سجل أوامر Shell. يُكتب export DEEPSEEK_API_KEY=sk-... إلى ~/.bash_history بنص واضح، ويبقى هناك بعد وقت طويل من تدوير المفتاح. أضف مسافة في بداية الأمر عندما يكون HISTCONTROL=ignorespace مضبوطاً، أو تجاوز Shell واكتب القيمة مباشرةً في ملف ذي الوضع 600.
• ملفات dotfiles المضمّنة في المستودع. وجود مفتاح في ~/.bashrc أو ~/.zshrc يعني أنه لا يفصلك عن مستودع عام سوى git add واحدة إذا كنت تحفظ dotfiles في git. شغّل git grep -I -n 'sk-' في ذلك المستودع قبل الدفع.
• settings.yaml. استخدم apiKeyEnv مع موفّرات مخصصة، بحيث يحتوي الملف على اسم متغير بدلاً من سر. تُلصق ملفات الإعداد في تقارير المشكلات ومحادثات الدعم، أما ملفات بيانات الاعتماد فلا تُلصق فيها.
• مخرجات env ولقطات شاشة الطرفية. كل ما يطبع البيئة كاملة يطبع المفتاح معها.
• النسخ الاحتياطية. يستحق ~/.dsh النسخ الاحتياطي، لكن .credentials.yaml الموجود داخله سر حي. استبعد ذلك الملف، أو شفّر الأرشيف.

لا تقتصر هذه القواعد على dsh، كما يشرح إبقاء الأسرار خارج ملفات env في Compose المشكلة نفسها في جانب الحاويات من الخادم نفسه.

التعامل مع نسخة معاينة للمطورين

ثبّت الإصدار الذي اختبرته، لأن نسخة المعاينة قد تغيّر مفتاح إعدادات في إصدار تصحيحي، وعندها يفشل المزوّد في التحميل. احتفظ بـsettings.yaml وcordis.patch.yml في نظام التحكم بالإصدارات، مع استثناء ملف بيانات الاعتماد، حتى تتمكن من معرفة ما تغيّر بعد الترقية.

يساعدك خياران عندما لا يعمل ملف تعريف بطريقة صحيحة. يطبع --dump-default-config الإعدادات الافتراضية المجمّعة من دون تشغيل البرنامج، بينما يطبع --dump-config الإعدادات المجمّعة لملف التعريف الخاص بك بالطريقة نفسها. تكشف مقارنة الناتجين ما غيّرته طبقة التعديلات فعلياً، وهذا أسرع من قراءة الطبقات يدوياً.

dsh --profile web --dump-config

عندما يحدث عطل بعد الترقية، شغّل ذلك أولاً. يظهر المفتاح الذي انتقل بين الإصدارات كفرع مفقود في المخرجات، ويكون الإصلاح تعديلاً في سطر واحد بدلاً من إعادة التثبيت.

FAQ

أين يخزّن dsh مفتاح DeepSeek API الخاص بي؟

في $DSH_HOME/.credentials.yaml، وهو ~/.dsh/.credentials.yaml ما لم تعيّن DSH_HOME بنفسك. تكتب صفحة Models المفتاح هناك، ولا تحتفظ إعداداتك إلا بمرجع إليه، لذلك يبقى السر في ملف واحد. تحقّق من الوضع باستخدام stat -c '%a %n' ~/.dsh/.credentials.yaml وعيّنه إلى 600 إذا كان أكثر تساهلاً. ويمكن لمزوّد مخصّص تجنّب الملف بالكامل عبر تسمية متغيّر بيئة باستخدام apiKeyEnv.

كيف أجعل dsh يستخدم نموذجاً محلياً بدلاً من DeepSeek API؟

أضف مزوّداً مخصّصاً يكون عنوانه الأساسي هو نقطة النهاية المحلية المتوافقة مع OpenAI. بالنسبة إلى Ollama، يكون العنوان http://127.0.0.1:11434/v1، مع api: openai-completions واسم نموذج id منسوخاً حرفياً من ollama list. تتطلب Ollama قيمة لمفتاح API وتتجاهلها، لذلك تصلح أي سلسلة غير فارغة. أكّد أن نقطة النهاية تستجيب باستخدام curl -s http://127.0.0.1:11434/v1/models قبل تعديل أي إعدادات في dsh، لأن نقطة النهاية المتوقفة والإعداد الخاطئ ينتجان أخطاء متشابهة.

هل يرسل dsh التعليمات البرمجية الخاصة بي إلى أي مكان تلقائياً؟

مع نموذج مستضاف، نعم. يكون طلبك ومحتوى الملفات التي قرأها الوكيل داخل طلب API المرسل إلى ذلك المزوّد. أما مع نقطة نهاية محلية، فيُرسل الطلب إلى loopback ويبقى على الجهاز. القياس عن بُعد قناة منفصلة، وهو معطّل تلقائياً: تُرجع DSH_TELEMETRY_MODE القيمة DISABLED عند عدم تعيينها، وفي هذه الحالة لا يُنشأ أي exporter. عيّن DSH_TELEMETRY_DISABLED=1 لتعطيل القياس، وتُقرأ هذه القيمة قبل بدء التشغيل.

لماذا يعرض dsh الخطأ MISSING_CREDENTIAL رغم أن المتغيّر معيّن؟

لأن dsh يقرأ المتغيّر الذي تسميه apiKeyEnv من بيئة العملية الخاصة به. لا يصل متغيّر مُصدَّر في shell إلى خدمة systemd، أو جلسة مستخدم آخر، أو عملية بدأت قبل تصدير المتغيّر. ضع القيمة في EnvironmentFile بالوضع 600 للوحدة، أو صدّرها في shell نفسه الذي يبدأ dsh. تحقّق مما تحتفظ به العملية قيد التشغيل فعلياً باستخدام sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.

ما إصدار Node.js الذي يحتاج إليه dsh؟

يحتاج إلى Node.js 22.19 أو إصدار أحدث ضمن خط 22، أو الإصدار 24 وما بعده. الإصدار Node 23 خارج النطاق المدعوم. شغّل node -v قبل أي شيء آخر، لأن فشل بدء التشغيل الناتج عن runtime غير مدعوم يبدو كأنه تثبيت معطّل، ويدفع المستخدمين إلى إعادة تثبيت الحزمة بدلاً من runtime.