إعداد مزوّد مخصص لـ ZCode (سطح المكتب وCLI)

اربط ZCode بـ QCode.cc كمزوّد مخصص: خطوات سطح المكتب وفق الوثائق الرسمية، وZCode CLI 0.17.1 مُختبَر على Anthropic وOpenAI Chat وResponses.

تحتاج مفتاح API؟ أنشئ حسابًا ←·نقاط النهاية وعناوين Base URL ←

آخر تحقق: 2026-11-10 · 📄 وفق الوثائق الرسمية (ZCode desktop v3.17.2، بتاريخ 2026-11-03 في README وسجل التغييرات) · ✅ اتصال QCode مُختبَر مع ZCode CLI 0.17.1 (2026-11-10)

نعم، يمكن لـ ZCode استخدام مفتاح API ونقطة النهاية الخاصين بك. في تطبيق سطح المكتب تضيفه ضمن Add Provider؛ ويقرأه ZCode CLI مفتوح المصدر من ~/.zcode/v2/provider_config.json. حتى 2026-11-10، ومُختبَرًا مع ZCode CLI 0.17.1: يعمل QCode على البروتوكولات الثلاثة كلها (Anthropic Messages، OpenAI Chat Completions، OpenAI Responses)، ولا حاجة لتسجيل الدخول إلى Z.ai أو BigModel. تتبع خطوات سطح المكتب الوثائق الرسمية.

نظرة سريعة¶

أي بروتوكول¶

لدى ZCode ثلاث طرق للحصول على نموذج، وتختلف في مصدر الحصة:

تغطي هذه الصفحة الطريقة الثالثة. يقدّم QCode Claude على بروتوكول Anthropic فقط، وGPT على بروتوكولي OpenAI فقط؛ وتعمل GLM وKimi وDeepSeek وQwen على Anthropic وOpenAI Chat (راجع نقاط النهاية ومسارات API):

يضيف ZCode مسار API بنفسه. في مصدر CLI (normalizeAnthropicBaseURL)، يُضاف /v1 إلى Base URL الخاص بـ Anthropic الذي لا ينتهي بـ /v1، ثم يضيف SDK بعده /messages، لذا يصل https://api.qcode.cc/api إلى /api/v1/messages. وبالنسبة لنوعي OpenAI، يضيف /chat/completions أو /responses إلى Base URL، ولهذا تنتهي القيمتان بـ /openai/v1. لا تُضِف / في النهاية. يعمل المفتاح نفسه على us.qcode.cc وasia.qcode.cc؛ بدّل المضيف واحتفظ بالمسار.

تطبيق سطح المكتب (📄 وفق الوثائق الرسمية)¶

تتبع الخطوات أدناه الوثائق الرسمية للإصدار v3.17.2. وقد نجحت عناوين QCode نفسها في اختبار ZCode CLI؛ وفي تطبيق سطح المكتب، تؤكد رسالة الاختبار الأولى لديك الاتصال.

التثبيت¶

تقول صفحة التثبيت الرسمية إن ZCode «يدعم macOS (Apple Silicon / Intel)، وWindows (x64 / ARM64)، وLinux (x64، ARM64، AppImage، DEB، RPM).» وتشير إلى أن v3.17.2 هو أحدث إصدار.

• macOS: افتح ZCode.dmg الذي نزّلته واسحب ZCode.app إلى مجلد Applications. إذا قال macOS إن التطبيق تالف، فالإصلاح الرسمي هو xattr -dr com.apple.quarantine /Applications/ZCode.app.
• Windows: نزّل برنامج التثبيت، وانقر عليه نقرًا مزدوجًا، واتبع المعالج.
• Linux: نزّل .AppImage أو .deb أو .rpm؛ وبالنسبة إلى AppImage شغّل chmod +x ZCode-*.AppImage.

نزّل برامج التثبيت من zcode.z.ai.

إضافة QCode بوصفه مزوّدًا¶

تعرض الوثائق مزوّدين يملؤون نقطة نهاية واحدة، ومثال DeepSeek يملأ كلتيهما، لكنها لا توضح كيف يختار ZCode بين نقطتي نهاية لمزوّد واحد. لذلك تستخدم هذه الصفحة مزوّدًا واحدًا لكل بروتوكول:

1. افتح ZCode، وانقر اسم النموذج في مربع المحادثة، ثم إدارة النماذج أسفل القائمة. يفتح ذلك الإعدادات -> إعدادات النموذج. عند أول تشغيل دون نموذج صالح للاستخدام، يؤدي استخدام مفتاح API في شاشة الترحيب أيضًا إلى إعدادات مزوّد النموذج.
2. انقر إضافة مزوّد أسفل قائمة المزوّدين على اليسار.

3. للمزوّد الأول:

4. الاسم: QCode Claude (الاسم متروك لاختيارك؛ وتقترح الصفحة الرسمية أسماء مثل claude أو deepseek)

5. نقطة نهاية Anthropic: https://api.qcode.cc/api (الصياغة الرسمية هي «اختر Base URL الخاص بالمورّد من القائمة المنسدلة، أو أدخل Base URL الخاص بـ API يدويًا»؛ أدخله يدويًا)
6. مفتاح API: مفتاح QCode الخاص بك (يبدأ بـ cr_)
7. انقر إضافة نموذج وأدخل معرّف كل نموذج، على سبيل المثال claude-sonnet-5-5. النص الرسمي: «انقر إضافة نموذج وأدخل معرّفات النماذج التي تدعمها تلك الخدمة».
8. شغّل مفتاح التفعيل («شغّل مفتاح التفعيل لبدء استخدامه») واحفظ.
9. كرّر ذلك مع الاسم QCode OpenAI، ونقطة نهاية OpenAI https://api.qcode.cc/openai/v1، والمفتاح نفسه، ونماذج مثل gpt-6.1-sol وdeepseek-v4-flash.

استخدم معرّفات النماذج المدرجة على qcode.cc/models حرفًا بحرف؛ وتُدرج هناك أيضًا أسعار كل نموذج. تعمل النماذج الصينية أيضًا على نقطة نهاية Anthropic إذا كنت تفضّل إبقاءها في QCode Claude. تسمّي وثائق سطح المكتب نقطتي نهاية Anthropic وOpenAI؛ ولا تدرج خيار Responses منفصلًا، لذا استخدم CLI أدناه من أجل Responses.

ملف إعدادات سطح المكتب¶

تدرج الأسئلة الشائعة الرسمية ~/.zcode/v2/config.json بوصفه الملف الذي يحوي «إعداد مزوّد النموذج (مفاتيح API، وعناوين Base URL، وقوائم النماذج)»، لذا تعامل معه بوصفه سرًّا ولا تُضمّنه في commit. وتوثّق الصفحة قاعدة واحدة بشأنه: «لا يتعرّف خيار options الخاص بالمزوّد إلا على إعدادات الاتصال مثل apiKey وbaseURL وapiKeyRequired وheaders؛ وأي مفاتيح أخرى تُضاف يدويًا (مثل reasoning_effort وvl_high_resolution_images) تُتجاهل بصمت ولا تُكتب أبدًا في جسم الطلب.» أعدّ المزوّدين في واجهة المستخدم بدلًا من تحرير الملف يدويًا. تذكر الأسئلة الشائعة أيضًا أن متغيرات بيئة الطرفية وإعداد النموذج في تطبيق سطح المكتب نقطتا إدخال منفصلتان، وأن الإعدادات لا تُزامَن تلقائيًا.

ZCode CLI (✅ تم اختباره في 2026-11-10)¶

حتى 2026-11-10، وبعد الاختبار باستخدام ZCode CLI 0.17.1: تعمل بروتوكولات QCode الثلاثة جميعها عبر ~/.zcode/v2/provider_config.json، دون تشغيل zcode login.

البناء من المصدر¶

يُوزَّع CLI على هيئة شفرة مصدر: يبنيه البدء السريع من المستودع. يتطلب Git وNode.js 24.14.0 وpnpm 10.33.2 (ويُعدّ mise.toml في المستودع المرجع). نفّذ الأوامر في جذر المستودع:

git clone https://github.com/zai-org/ZCode.git
cd ZCode
pnpm install --frozen-lockfile
pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --version
node apps/zcode-cli/packages/cli/dist/zcode.cjs doctor --json

في الأوامر أدناه، يمثل zcode الأمر node /absolute/path/to/zcode.cjs؛ احتفظ بالملفات التي يضعها البناء بجانبه.

كتابة provider_config.json¶

احفظ هذا في ~/.zcode/v2/provider_config.json واستبدل cr_xxx بمفتاح QCode الخاص بك. هذا هو إعداد Anthropic من الاختبار:

{
  "schemaVersion": 1,
  "config": {
    "providerConfigRules": {
      "providerRules": [
        {
          "providerId": "qcode",
          "providerName": "QCode",
          "config": {
            "group": "standard-personal",
            "access": { "type": "api-key", "apiKey": "cr_xxx" },
            "api": {
              "type": "anthropic-messages",
              "baseUrl": "https://api.qcode.cc/api"
            },
            "personalModelIds": ["claude-haiku-5-5"]
          }
        }
      ]
    },
    "modelConfigRules": {
      "providerModelRules": [],
      "manualProviderModelRules": []
    },
    "defaultModelSelection": {
      "providerId": "qcode",
      "modelId": "claude-haiku-5-5"
    }
  }
}

لبروتوكول آخر، غيّر api.type وapi.baseUrl ومعرّف النموذج (في كل من personalModelIds وdefaultModelSelection.modelId):

نقطتان من دليل CLI الرسمي:

• الحقل هو api.baseUrl، ويُكتب بشكل مختلف عن options.baseURL في ملف سطح المكتب؛ يقرأ CLI الملف provider_config.json وليس ~/.zcode/v2/config.json.
• لا يَعِد الدليل باستبدال ${ENV} في apiKey، لذا يوجد المفتاح في الملف بنص عادي. قيّد صلاحيات الملف وابقِه خارج Git:

chmod 600 ~/.zcode/v2/provider_config.json

تشغيل فحص غير تفاعلي¶

zcode --prompt "Reply with one word: ready. Do not call tools." \
  --cwd /path/to/project --mode plan --json --no-color

يعيد --json القيم sessionId وresponse وتفاصيل التشغيل؛ وتعني قيمة response المساوية لـ ready أن المزوّد يعمل. مرّر --mode دائمًا: فبدونه يعمل --prompt في وضع yolo، الذي ينفّذ الأوامر ويعدّل الملفات. تشغيل zcode بلا وسائط يبدأ واجهة TUI التفاعلية.

التحقق¶

1. سطح المكتب: اختر نموذج المزوّد الجديد من محدّد النموذج في مربع المحادثة وأرسل تعليمة اختبار قصيرة، كما تنصح الصفحة الرسمية («أرسل تعليمة اختبار قصيرة»).
2. CLI: نفّذ فحص --prompt أعلاه.
3. افتح probe.qcode.cc، وأدخل مفتاح QCode الخاص بك وتحقق من ظهور الطلب مع ذلك النموذج.
4. لاختبار المفتاح والمسار دون ZCode:

KEY="cr_your_key"

# Anthropic Messages
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-haiku-5-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

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

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

يحوّل ZCode مستوى التفكير المختار إلى ما يناسب نقطة النهاية: «تستخدم نقاط النهاية المتوافقة مع OpenAI حقل reasoning_effort على المستوى الأعلى، بينما تستخدم نقاط النهاية المتوافقة مع Anthropic الحقلين thinking / effort.»

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

• يتبع جزء سطح المكتب الوثائق الرسمية للإصدار v3.17.2؛ وقد تتغير أسماء القوائم بين الإصدارات. اختُبر جزء CLI مع 0.17.1 ونموذج واحد لكل بروتوكول.
• تقول الصفحة الرسمية إن إضافة معاملات طلب مخصصة لنماذج الطرف الثالث غير مدعومة بعد.
• تذكر وثائق سطح المكتب نقطتي نهاية Anthropic وOpenAI؛ ويتوفر Responses عبر openai-responses في CLI. لا يوفّر QCode نماذج Gemini في الوقت الحالي.
• CLI: يُخزَّن المفتاح كنص عادي في provider_config.json، ويعمل --prompt دون --mode في وضع yolo.

ذات صلة¶

• نقاط النهاية ومسارات API — جدول البروتوكول × عائلة النموذج
• نظرة عامة على توافق الأدوات — أي الأدوات تستخدم أي بروتوكول
• Kimi Code CLI — وكيل طرفية آخر مع مزوّدات Anthropic وOpenAI Chat وResponses
• MiniMax Code — تطبيق سطح مكتب وCLI mcode مع تنسيقات API الثلاثة نفسها
• DeepSeek Harness (dsh) — إطار تشغيل وكلاء آخر مع نموذج مخصص
• النماذج الصينية — معرّفات ومسارات GLM / Kimi / DeepSeek / Qwen

المؤسسات ←