# إعداد DeepSeek Harness (dsh) مع QCode

> **آخر تحقق**: 2026-11-09 · 📄 وفقًا للوثائق الرسمية (DeepSeek Harness 0.2.2-rc.1، نُشر على npm وGitHub في 2026-11-04؛ وقد قُرئت وثائق المستودع في 2026-11-09)

## نظرة سريعة

| البند | التفاصيل |
|---|---|
| ما هو | DeepSeek Harness (`dsh`) هو إطار تشغيل مفتوح المصدر للوكلاء طوّرته DeepSeek AI، مع واجهة Web UI تُشغَّل بواسطة `dsh web` |
| النماذج التي يمكنك استخدامها | Claude ✅ (مزوّد Anthropic Messages) · GPT ✅ · GLM / Kimi / DeepSeek / Qwen ✅ (مزوّد OpenAI Chat Completions) · Gemini ❌ (لا يوفّر QCode نماذج Gemini في الوقت الحالي) |
| البروتوكول وBase URL | OpenAI Chat Completions: `https://api.qcode.cc/openai/v1` · Anthropic Messages: `https://api.qcode.cc/api` |
| مكان الإعداد | **الإعدادات → النماذج** → **إضافة مزوّد نموذج** → **واجهة API المخصصة للنماذج** |
| مكان الكتابة | `$DSH_HOME/profiles/<profile>/cordis.patch.yml`؛ ويُكتب المفتاح إلى `$DSH_HOME/.credentials.yaml` |
| الوثائق الرسمية | [تهيئة النماذج](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md) · [المستودع](https://github.com/deepseek-ai/deepseek-harness) |

DeepSeek Harness في مرحلة المعاينة للمطورين. يقول README الرسمي: «THERE WILL BE COMPATIBILITY-BREAKING CHANGES.» تحقق من الإصدار الذي تشغّله مقابل هذه الصفحة.

## أي بروتوكول

يجب أن يكون **بروتوكول API** للمزوّد المخصص هو البروتوكول الذي تتحدثه البوابة. يعرض المحدد ثلاثة خيارات: OpenAI Chat Completions وOpenAI Responses وAnthropic Messages، وتُخزَّن باسم `openai-completions` و`openai-responses` و`anthropic-messages`. يتحدث المزوّد بروتوكولًا واحدًا، لذا تحتاج البوابة التي تخدم بروتوكولين إلى مزوّدين.

يقدّم QCode Claude فقط عبر بروتوكول Anthropic وGPT فقط عبر بروتوكولي OpenAI؛ أما العائلات الصينية الأربع فتعمل عبر كليهما. راجع [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths). ينتج عن ذلك مزوّدان:

| المزوّد | بروتوكول API | Base URL | معرّفات النماذج (أمثلة) |
|---|---|---|---|
| `qcode` | OpenAI Chat Completions (`openai-completions`) | `https://api.qcode.cc/openai/v1` | `gpt-6-sol`، `deepseek-v4-pro`، `glm-5.3`، `kimi-k3`، `qwen3.8-max` |
| `qcode-claude` | Anthropic Messages (`anthropic-messages`) | `https://api.qcode.cc/api` | `claude-sonnet-5`، `claude-opus-5` |

معرّفات المزوّدين هي أسماء تختارها أنت. استخدم معرّفات النماذج المدرجة في [qcode.cc/models](https://qcode.cc/models) حرفًا بحرف؛ ومعرّفات النماذج الصينية مدرجة أيضًا في [النماذج الصينية](/docs/usage/cn-models). لا تضف `/` في نهاية Base URL، ولا تضع معرّفات `claude-…` خلف Base URL الخاص بـ OpenAI.
## التثبيت

يحتاج DeepSeek Harness إلى Node.js 24.9 أو أحدث (تعلن حزمة npm عن `node >=24.9.0`، وتقول ملاحظات إصدار v0.2.2-rc.1: «ارفع الحد الأدنى لإصدار Node.js المدعوم إلى 24.9.»). ثبّت Node.js، ثم شغّل:

```sh
npx @deepseek-ai/dsh web
```

يبدأ الأمر واجهة الويب على `http://127.0.0.1:3080` افتراضيًا ويفتحها في المتصفح الافتراضي عند التشغيل المحلي. ولا يطبع التشغيل عبر SSH سوى عنوان URL للمضيف. مرّر `--no-open` لتشغيل الخادم دون فتح متصفح.

لتشغيله من نسخة مستخرجة من المستودع بدلًا من ذلك:

```sh
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
```

`$DSH_HOME` هو جذر بيانات DeepSeek Harness؛ ويكون افتراضيًا `~/.dsh` ما لم تضبط متغير البيئة `DSH_HOME`. راجع [إشعار السلامة](https://github.com/deepseek-ai/deepseek-harness/blob/master/SAFETY.md) الرسمي قبل تشغيل المشروع.

## الإعداد

تسري تغييرات النموذج على الطلب التالي دون إعادة تشغيل الخادم.

1. افتح واجهة الويب، ثم **الإعدادات → النماذج**، واختر **إضافة مزوّد نموذج**.
2. بدّل البطاقة إلى **API نموذج مخصص**. وهي مخصصة لخدمة ترحيل، أو بوابة شركة، أو خادم مستضاف ذاتيًا، أو أي مزوّد غير موجود في الكتالوج المثبّت.
3. املأ الاستمارة للمزوّد الأول:
   - **معرّف المزوّد**: `qcode` (بحروف صغيرة؛ وهو دائم، لذا اختره بعناية)
   - **اسم العرض**: `QCode` (اختياري)
   - **Base URL**: `https://api.qcode.cc/openai/v1`
   - **بروتوكول API**: OpenAI Chat Completions
   - **مفتاح API**: مفتاح QCode الخاص بك (يبدأ بـ `cr_`)
4. في قائمة **النماذج** بالاستمارة (يسميها الدليل الرسمي كتالوج النماذج)، اختر **إضافة نموذج** وأدخل كل معرّف نموذج، مثل `deepseek-v4-pro` و`gpt-6-sol`. يسأل **جلب النماذج المتاحة** نقطة النهاية عن النماذج التي تقدمها؛ وهو تسهيل، ويقول الدليل الرسمي إنه عندما يفشل أو لا يسرد شيئًا، تضيف معرّفات النماذج يدويًا وتعمل بالطريقة نفسها. على QCode، تسرد نقطة نهاية OpenAI نماذج GPT، لذا أضف المعرّفات الصينية يدويًا.
5. اختر **إنشاء مزوّد**. ثم كرّر باستخدام معرّف المزوّد `qcode-claude`، واسم العرض `QCode Claude`، وBase URL `https://api.qcode.cc/api`، وبروتوكول API **Anthropic Messages**، والمفتاح نفسه، والنموذج `claude-sonnet-5`، واختر **إنشاء مزوّد** مجددًا.
6. افتح منتقي النماذج واختر نموذجًا. اختيار نموذج يجعله أيضًا الافتراضي للجلسات الجديدة.

المفاتيح للكتابة فقط: بعد الحفظ، تتلقى الصفحة وصفًا منقّحًا، وليس السر الحرفي أبدًا. يُخزَّن المفتاح في `$DSH_HOME/.credentials.yaml`، بينما تحتفظ الإعدادات بمرجع بيانات الاعتماد الخاص به فقط.

### ما تكتبه الصفحة

للمرجع، تبدو المزوّدات نفسها في `$DSH_HOME/profiles/<profile>/cordis.patch.yml` هكذا. في التشغيل القياسي `dsh web` تكون `<profile>` هي `web`، لذا يكون المسار `$DSH_HOME/profiles/web/cordis.patch.yml`. تكتب الصفحة هذا المستند نيابةً عنك؛ لا تحرّره يدويًا إلا إذا كنت تحتاج إلى إعداد لا توفره الاستمارة.

```yaml
- id: llm-pi-ai
  config:
    providers:
      qcode:
        displayName: QCode
        apiKeyEnv: QCODE_API_KEY
        api: openai-completions
        baseURL: https://api.qcode.cc/openai/v1
        models:
          - id: deepseek-v4-pro
          - id: gpt-6-sol
      qcode-claude:
        displayName: QCode Claude
        apiKeyEnv: QCODE_CLAUDE_API_KEY
        api: anthropic-messages
        baseURL: https://api.qcode.cc/api
        models:
          - id: claude-sonnet-5
```

`apiKeyEnv` مرجع لبيانات الاعتماد: تشتقه الصفحة من معرّف المزوّد (`qcode` → `QCODE_API_KEY`، `qcode-claude` → `QCODE_CLAUDE_API_KEY`) وتخزّن المفتاح الذي أدخلته تحت ذلك الاسم. يقول إدخال استكشاف الأخطاء الرسمي الخاص بـ `MISSING_CREDENTIAL`: خزّن مفتاح المزوّد عبر صفحة النماذج أو وفّر متغير البيئة المُشار إليه. تجاوز إعداد Cordis يستبدل إعداد الإدخال بالكامل، لذا أبقِ مزوّداتك الأخرى عند تحرير تجاوز موجود.
## التحقق

1. اختر نموذجًا أضفته في منتقي النماذج وأرسل رسالة قصيرة مثل `ping`.
2. افتح [probe.qcode.cc](https://probe.qcode.cc)، وأدخل مفتاح QCode الخاص بك، وتحقق من ظهور الطلب مع ذلك النموذج.
3. لاختبار المفتاح والمسار دون dsh:

```bash
KEY="cr_your_key"

# OpenAI Chat Completions provider
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"deepseek-v4-pro","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

# Anthropic Messages provider
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

## استكشاف الأخطاء وإصلاحها

| العرَض | السبب | الإصلاح |
|---|---|---|
| `MISSING_CREDENTIAL` | لم يُخزَّن أي مفتاح، أو أن متغير البيئة المُشار إليه فارغ | خزّن المفتاح عبر **الإعدادات → النماذج**، أو صدّر المتغير المسمى في `apiKeyEnv` قبل تشغيل `dsh` |
| `UNKNOWN_MODEL` | النموذج المحدد ليس في قائمة المزوّد | اختر نموذجًا مُعدًّا أو أضف معرّف النموذج إلى المزوّد |
| جلب النماذج المتاحة يعيد 401 | المفتاح خاطئ | تحقق من المفتاح؛ إذ يستدعي اكتشاف النماذج نقطة النهاية `GET /models` المتوافقة مع OpenAI |
| الجلب لا يسرد شيئًا أو يفشل | قائمة نقطة النهاية بتنسيق لا يقرأه الاكتشاف | أدخل معرّفات النماذج يدويًا |
| `model_not_available_on_endpoint` | أُضيف معرّف `claude-…` إلى مزوّد OpenAI Chat Completions | ضع معرّفات Claude في مزوّد Anthropic Messages مع Base URL `https://api.qcode.cc/api` |
| 404 | `/` زائدة في النهاية أو بادئة مسار خاطئة في Base URL | قارن مع [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) |
| البوابة ترفض كل طلب رغم أن المفتاح وURL صحيحان | شكل طلبها يختلف عن طلبات OpenAI | النصيحة الرسمية: ابدأ بـ `compat.supportsDeveloperRole: false` و`compat.maxTokensField: max_tokens` على المسار |
| نماذج الاستدلال فقط تفشل | يرسل pi-ai الـ prompt النظامي الخاص بها بدور `developer` | اضبط `compat.supportsDeveloperRole: false` |
| قائمة الجهد لا تظهر لنموذج أدخلته يدويًا | لا يعلن النموذج عن مستويات استدلال | فعّل **مستويات الاستدلال** في **خيارات النموذج** للنموذج |

## القيود المعروفة

- معاينة للمطوّرين: قد تتغير حقول الإعداد والسلوك بين الإصدارات؛ روجعت هذه الصفحة مقابل 0.2.2-rc.1، وهو الإصدار الذي يوسمه npm بـ `latest` في 2026-11-09.
- لا تحتوي الاستمارة على حقل لمفاتيح `compat`؛ اضبطها على المسار في `cordis.patch.yml` كما هو موضح في الدليل الرسمي.
- النموذج الذي تدخله يدويًا لا يعلن عن مستويات استدلال حتى تضيفها، ويبدأ نصيًا فقط حتى تحدد **صورة** في **خيارات النموذج** (انظر أقسام الدليل الرسمي عن إدخال الصور وجهد الاستدلال).
- القيم الافتراضية للسعة: تقول ملاحظات إصدار 0.2.2-rc.1 إن النماذج المخصصة التي لا تعلن عن سعة أصبحت الآن تعتمد افتراضيًا على نافذة سياق 1M بالنظام العشري وإخراج 128K، وإن على نقاط النهاية الأصغر ضبط سعات صريحة لتجنب تأخر الضغط. يسرد QCode نافذة سياق كل نموذج على [qcode.cc/models](https://qcode.cc/models)؛ لنموذج أقل من 1M، حرّر المزوّد ضمن **الإعدادات → النماذج** وأدخل نافذة سياق ذلك النموذج والحد الأقصى من tokens الإخراج.

## مواضيع ذات صلة

- [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) — جدول البروتوكول × عائلة النموذج
- [النماذج الصينية](/docs/usage/cn-models) — معرّفات ومسارات GLM / Kimi / DeepSeek / Qwen
- [CodeWhale (DeepSeek-TUI)](/docs/ide/deepseek-tui) — وكيل طرفية آخر يدعم البروتوكولين
- [نظرة عامة على توافق الأدوات](/docs/ide/tool-compatibility) — أي الأدوات تتحدث أي بروتوكول
- [T3 Code](/docs/ide/t3code) — واجهة تحكم تشغّل Claude Code وCodex
- [دليل DeepSeek Harness على qcode.cc](https://qcode.cc/ar/deepseek-harness-guide) — الخلفية وحالات الاستخدام