DeepSeek Harness: إطار عمل وكلاء مفتوح المصدر حيث يصبح كل شيء فعلياً إضافة قابلة للتوصيل

مكدس وكيل كامل، مُلقاً على GitHub

أصدرت DeepSeek معاً مطوراً لـ DeepSeek Harness (dsh) في 13 أغسطس 2026. المستودع موجود على deepseek-ai/deepseek-harness. وبحلول نهاية اليوم حصل على 1.6k نجمة و 12,293 كوميت و 19 مساهماً — أرقام تخبرك أن هذا ليس مجرد تجربة عطلة نهاية أسبوع. قاعدة الكود مكونة من 97.1% TypeScript، و1.6% CSS، و0.7% Python. إصدار الحزمة عند النشر: 0.1.0-rc.5。

الصفحة الرئيسية موجودة على deepseek.com/harness ووثائق المطورين على deepseek-harness.github.io/deepseek-harness。

مرخّص بموجب MIT。

ملخص سطر واحد

من ملف README: «الوكيل = النموذج + Harness»。

النموذج هو الروح. يسمح Harness للوكيل بأن يفهم بيئته، ويستخدم الأدوات، ويستمر في العمل في الإعدادات الحقيقية. وجهة نظر DeepSeek: كل قدرة — النماذج، الأدوات، المهارات، الجلسات، الصناديق الرملية، التخزين، الحلقات، الجدولة، وواجهة المستخدم — هي إضافة قابلة للتبديل。

هذا ليس مجرد شعار. إنها مفروضة من قبل الهندسة المعمارية。

Cordis: النواة تحت كل شيء

تم بناء DeepSeek Harness فوق Cordis، وهو إطار عمل إضافات مضمّن. وُصِم تصميم Cordis في ورقة بحثية بعنوان A Programming Paradigm for Spatiotemporal Composability。

يختصر الإطار الكامل إلى خمس أفكار:

الإضافة هي كائن ينفذ واجهة Service. يمكن أن تكون دالة بها inject و apply(ctx)، أو فئة فرعية من Service。
السياق هو مستودع للخدمات. تطالب الإضافة بمفتاح ثابت مثل ctx.tools أو ctx.llm أو ctx.sessions. تجد الإضافات الأخرى الخدمات بواسطة المفتاح بدلاً من استيراد تطبيقات ملموسة。
اعلن تبعية الخدمة عبر inject. الإضافة التي تسمي الخدمات المطلوبة تنتظر حتى تتوفر تلك الخدمات. لا حاجة لتسلسل تمهيد يدوي。
الأحداث المكتوبة للاتصال. أربعة أوضاع للإرسال: emit (إرسال ونسيان)، waterfall (نمط middleware مع next())، parallel (جميع المستمعين يعملون بشكل متزامن)، و serial (المستمعون يعملون بالترتيب مع قيم الإرجاع)。
عمليات التسجيل هي تأثيرات عكسية. أقسام الموجهات، ومخططات الأدوات، والمحولات، والمستمعون — كل شيء يتم تثبيته عبر ctx.effect() حتى يعيد إعادتها إعادة التحميل والإغلاق بشكل يمكن التنبؤ به。

يعمل نموذج الـ waterfall في Cordis كنمط around-middleware. يتلقى المستمع (...args, next). استدعِ next() لتفويض العملية إلى الخدمة التالية؛ ارجع دون استدعاء next() لقطع السلسلة. بالنسبة للأحداث ذات القرار الواحد، قطع السلسلة هو التصميم المقصود — يمكن لمستمع سياسة أن يمتلك القرار تماماً。

كل شيء إضافة (حقاً)

قائمة الإضافات على deepseek.com/harness توضح سطح القدرة الكامل:

Models — خوادم LLM الخلفية (DeepSeek، OpenAI، Anthropic، Bedrock، Vertex، Azure، Codex، بالإضافة إلى أي نقطة نهاية متوافقة مع OpenAI)
Tools — ما يمكن للنموذج استدعاؤه
Skills — حزم موجهات وأدوات قابلة لإعادة الاستخدام
Sessions — إدارة حالة المحادثة
Sandboxes — حيث يعمل الكود (PTY bash، خلفية محلية danger-full-access، صندوق رملي أصلي قائم على landlock)
Storage — استمرارية الجلسات
Loops — منطق دورة الوكيل
Scheduling — إرسال الوكلاء الفرعيين والمهام
UI — واجهة الويب التي تُخدم على المنفذ 3080 افتراضياً

يمكن للمطور اختيار أي من هذه العناصر أو تبديلها أو توسيعها عبر التكوين — دون إجراء تغييرات على المصدر الخاص بـ DeepSeek Harness نفسه. يتم إنشاء Plugin Config Catalog تلقائياً من المصدر (scripts/gen-config-catalog.ts) ويتم التحقق منه حديثاً بواسطة CI، لذا فإن كل حقل في كتلة config: في cordis.yml يتطابق تماماً مع نوع التكوين المعلن للإضافة。

أربعة أوضاع وقت التشغيل

تأتي الوثائق بأربعة إعدادات مسبقة. كل واحدة تستهدف حالة استخدام مختلفة。

Standard Mode — وكيل برمجة كامل: تحرير الملفات، shell، بحث في الملفات والويب، مهارات، تخطيط، أهداف، وكلاء فرعيون، وسير عمل. هذه هي تجربة واجهة الويب الافتراضية。

Code Mode — كل شيء في Standard، ولكن الأدوات تتوفر عبر Code Mode SDK حتى يتمكن النموذج من دمج العمليات متعددة الخطوات في برنامج TypeScript واحد. يحل برنامج واحد مولد من النموذج محل عدة جولات من استدعاء الأدوات。

Minimal Mode — أداتان فقط: shell bash دائم و str_replace_editor. هذا لاختبار نماذج الأداء في بيئة مبسطة. لا مهارات، لا تخطيط، لا وكلاء فرعيون — قدرة النموذج الخام مقابل قاعدة كود حقيقية。

Creator Mode — مصمم لكتابة إعدادات وكلاء مخصصة. يتضمن جميع قدرات وضع Standard بالإضافة إلى فحص وقت التشغيل، وتجارب إضافات Cordis في الذاكرة، وإرشادات تأليف الإعدادات المسبقة. هكذا تبني الوضع الخامس والسادس والسابع。

كل تشغيل قابل للتتبع

هنا يميز Harness نفسه عن معظم أدوات الوكيل. كل ما يراه النموذج يتم تسجيله في سجل جلسات ذو إلحاق فقط:

الموجهات النظامية
مخرجات التفكير
استدعاءات الأدوات ونتائجها
قرارات جدولة الوكلاء الفرعيين
كل حقن سياق

تحتوي واجهة الويب على طريقة عرض Trajectory حيث يمكنك فحص هذه السجلات مصنفة حسب المصدر. الاستئناف، والتفرع، والبحث، وإعادة التشغيل — جميع العمليات الأربع تعمل على نفس دفق الأحداث. لا قاعدة بيانات تتبع منفصلة، لا خطوة تصدير. ملف JSONL الخاص بالجلسة هو مصدر الحقيقة。

بالنسبة لـ Python SDK، يخزن دليل الجلسة ملف JSONL غير مضغوط يحتوي على طلبات النموذج المجمعة واستدعاءات الأدوات. يوضح المثال الموجود في examples/jsonrpc-agent/minimal.py هذا من البداية إلى النهاية。

تكوين النموذج: DeepSeek + أي شيء آخر

تحتوي صفحة تكوين النموذج (Configure models) على ثلاث طبقات。

DeepSeek Official. افتح الإعدادات → النماذج، الصق مفتاح DeepSeek API، احفظ. المفتاح للكتابة فقط. بعد الحفظ، تتلقى واجهة المستخدم واصفاً محذوفاً، وليس النص العادي أبداً. تعيش المفاتيح في \$DSH_HOME/.credentials.yaml؛ تحتفظ صفحة الإعدادات فقط بمرجع بيانات الاعتماد。

Catalog providers. انقر على «Add provider» واختر Anthropic أو OpenAI، ثم الصق المفتاح. الموفرون الذين يستخدمون المصادقة الأصلية (Bedrock عبر بيانات اعتماد AWS + المنطقة، Vertex عبر مشروع ADC، Azure عبر api-version، Codex عبر OAuth) لا تعمل بمجرد حقل مفتاح API — كل يحتاج إلى مسار مصادقة خاص به。

Custom providers. لبوابة الشركة، أو الخادم المستضاف ذاتياً، أو أي موفر غير موجود في الكتالوج. عيّن معرف موفر بأحرف صغيرة (دائم — تستخدمه الطلبات، والجلسات المحفوظة، وإعدادات النموذج الافتراضية، ومراجع بيانات الاعتماد جميعها)، وعنوان URL الأساسي، وبروتوكول API، وبيانات الاعتماد، ونموذجاً واحداً على الأقل。

تحتاج النماذج البصرية إلى خطوة إضافية. بما أن نقطة النهاية المخصصة لا تملك وسيلة للإعلان عن الوسائط المدعومة، لا يستطيع النموذج اكتشاف دعم الرؤية تلقائياً. قم بإضافة input: [text, image] إلى النموذج في \$DSH_HOME/settings.yaml. إذا كانت جميع نماذجك المخصصة تقبل الصور، عيّن defaultInput: [text, image] مرة واحدة على مستوى الموفر بدلاً من كل نموذج. الحقل input هو تأكيد، وليس فحصاً — إذا زعمت أن النموذج يدعم الرؤية ولكن نقطة النهاية في الواقع لا تفعل ذلك، فسيقوم الموفر برفض الطلب بدلاً من Harness。

تم توضيح استكشاف الأخطاء وإصلاحها مباشرة في الوثائق:

MISSING_CREDENTIAL → قم بتخزين مفتاح الموفر عبر صفحة النماذج أو قم بتصدير متغير البيئة المشار إليه
UNKNOWN_MODEL → اختر نموذجاً مكوناً، أو أضف النموذج المفقود إلى الموفر المخصص
«Get available models returns 401» → تحقق من المفتاح. يستدعي اكتشاف النماذج نقطة النهاية GET /models المتوافقة مع OpenAI. إذا لم تعرض خدمتك ذلك، أدخل النماذج يدوياً。
«Image rejected before send» → لم يعلن النموذج عن وسيلة image. أضف input: [text, image]。
«Provider rejects a request with an image» → زعم النموذج قدرة رؤية لا تمتلكها نقطة النهاية فعلياً. قم بإزالة image من القائمة وابدأ جلسة جديدة (تظل الصورة القديمة في سجل الجلسة وتستمر في تكرار نفس الطلب)。

البدء: ثلاثة مسارات

المسار 1: `npx @deepseek-ai/dsh web`

ثبّت Node.js، شغّل أمراً واحداً. تبدأ واجهة الويب على http://127.0.0.1:3080. هذا كل شيء. لا استنساخ، لا بناء، لا pnpm。

npx @deepseek-ai/dsh web

ثم: الإعدادات → النماذج → الصق مفتاح DeepSeek API. اختر مساحة العمل (الدليل الذي تم استدعاء dsh منه يعمل). ابدأ جلسة:

قم بتلخيص هذا المستودع وتحديد حزمته الرئيسية。

يقرأ الوكيل ملفات مساحة العمل ويحررها، وينفذ الأوامر، وينوب عن العمل، ويحافظ على خطة. أي عملية تحتاج إلى موافقة بموجب سياسة الأذونات النشطة تظهر مربع حوار في واجهة الويب قبل التنفيذ。

المسار 2: استنساخ والبناء من المصدر

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

المسار 3: Python SDK

المتطلبات: Python 3.10+، Linux x64 / Linux arm64 / macOS 14+ على arm64، نقطة نهاية متوافقة مع DeepSeek。

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

عيّن بيانات الاعتماد:

export DEEPSEEK_API_KEY=sk-your-key-here
# Optional:
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

شغّل مهمة على مساحة عمل معزولة:

python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

بالنسبة لكودك الخاص، نقطة دخول SDK هي DeepSeekHarness كمدير سياق:

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )
    print(result.final_response)

يقوم DeepSeekHarness بتشغيل وقت التشغيل المجمع كسولاً ويعيد استخدامه حتى يخرج من كتلة with. أعد استخدام نفس معرف الجلسة للحفاظ على عملية Bash (دليل العمل، متغيرات البيئة، دوال shell). استخدم معرف جلسة جديد لمهمة مستقلة。

التكوين الأدنى لـ jsonrpc-agent مقصود متعمداً: فقط bash الدائم و str_replace_editor كأدوات متاحة للنموذج. مهلة Bash 300 ثانية. حد إخراج المحرر 16,000 حرف. تم تعطيل ضغط السياق. يستخدم نظام الملفات الخلفية المحلية البحتة — يمكن لمسارات المحرر معالجة أي شيء يمكن لعملية وقت التشغيل رؤيته. تحذر الوثائق صراحة: «قم بتشغيله فقط داخل checkout أو حاوية يمكن التخلص منها». تتطلب الخلفية PTY الدائمة أيضاً ركيزة طرفية POSIX — لا دعم لـ Windows لهذا التكوين。

اكتب إضافتك الأولى

البرنامج التعليمي: Your first plugin。 الإضافة هي وحدة TypeScript تصدر دالة apply:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

قم بتسجيلها في تصحيح cordis.yml:

- insert:
  - id: hello
    name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

قم بالتمهيد مع الطبقة المتراكبة:

pnpm dsh web --patch ./scratch-plugin/cordis.yml

التنظيف التلقائي هو الميزة المميزة. أي شيء يتم تسجيله عبر ctx — مستمعو الأحداث، والأدوات، والموقتات — يتم تنظيفه عند إلغاء تحميل الإضافة. لا removeListener يدوي ولا clearInterval. بالنسبة للتنظيف الصريح (اتصالات الشبكة)، ارجع جهاز تخلص من ctx.effect()。

يتم الإعلان عن التبعيات بـ inject:

export const name = 'my-tool-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  // ctx.tools is ready here
}

ينتظر Cordis كل خدمة مطلوبة قبل تحميل الإضافة。

هناك ثلاثة أشكال للإضافة: دالة (أعلاه)، وكائن به apply، وفئة توسع Service. استخدم شكل الفئة عندما توفر الإضافة نفسها خدمة لتستهلكها إضافات أخرى。

اكتب أداتك الأولى

البرنامج التعليمي: Build a tool。 استخدم defineTool من @deepseek-ai/dsh-tools:

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: {
        type: 'string',
        required: true,
        description: 'The name to greet',
      },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

يستنتج defineTool args من parameters ويصححها. ترجع execute القيمة القياسية المعلنة بواسطة output.schema. يحول output.render هذه القيمة القياسية إلى محتوى متاح للنموذج. بعد إعادة التشغيل مع التصحيح، اسأل في واجهة الويب: «Use the greet tool to greet Ada». يستدعي النموذج greet ويتلقى Hello, Ada!。

الخطوات التالية من البرنامج التعليمي هي plugin configuration، و مرجع تأليف الأدوات (المخططات المتداخلة، والقيم القياسية، والعمل الخلفي، وخطافات السياسة، و Code Mode، وبطاقات واجهة المستخدم)، و capability layering (تقسيم تعريف الخدمة → موفر الخدمة → حزمة المستهلك)。

أوضاع دخول CLI

أمر @deepseek-ai/dsh هو مُشغِّل المنتج. أربع نقاط دخول:

Command	Purpose
`dsh --profile <name>`	قم بتمهيد الملف الشخصي المسماة ضمن `\$DSH_HOME/profiles/<name>`
`dsh --profile headless "job"`	شغّل جلسة دائمة واحدة جديدة، واطبع الإجابة النهائية، واخرج
`dsh web`	اسم مستعار لـ `--profile web`
`dsh plugin --profile <name> <pnpm args>`	أدر إضافات الملف الشخصي عن طريق التوجيه إلى pnpm

الدليل الذي تم فيه الاستدعاء هو جذر مساحة العمل الافتراضي. تتم تهيئة ملفات web و headless الشخصية تلقائياً من القوالب المشحونة عند أول استخدام. يجب إنشاء أي ملف شخصي آخر عبر dsh plugin。

تأتي أعلام المُشغِّل أولاً. الرمز المميز الأول الذي لا يتعرف عليه المُشغِّل يصبح حجج التطبيق. مثال: dsh --profile web --port 8080 يسلم --port 8080 إلى تطبيق الويب، وليس إلى المُشغِّل。

يحتوي دليل الملف الشخصي على package.json (تبعيات الإضافات خارج الشجرة، بالإضافة إلى بيان الملف الشخصي dsh.profile مع قائمة bundles المرتبة) و cordis.patch.yml (طبقة تصحيح المستخدم الخاصة به). ترتيب التركيب فوق جذر فارغ هو: تصحيح كل حزمة بترتيب dsh.profile.bundles → cordis.patch.yml الخاص بالملف الشخصي → \$DSH_HOME/cordis.patch.yml على مستوى المنزل → طبقات متراكبة --patch. استخدم --dump-default-config و --dump-config لفحص الشجرة المركبة دون تمهيدها。

إضافات المجتمع والنظام البيئي

قم بتمييز مستودع الإضافة الخاص بك بالعلامة dsh-plugin على GitHub لسهولة الاكتشاف. يربط الموقع الرسمي مباشرة بصفحة الموضوع هذه. هناك أيضاً مجتمع Discord الخاص بـ DeepSeek Harness للمناقشة。

يستخدم المشروع مناقشات GitHub للتعليقات وتقارير الأخطاء. ترتبط الوثائق بـ CONTRIBUTING.md لسير عمل التطوير، و architecture.md لتصميم النظام، و AGENTS.md للاتفاقيات البرمجية الخاصة بالوكيل。

المعاينة المطورة — نعم، ستنكسر

يضعها ملف README بأحرف كبيرة: «THERE WILL BE COMPATIBILITY-BREAKING CHANGES.»

الإضافات الأساسية وواجهات برمجة التطبيقات لا تزال تتطور. تقول الصفحة الرئيسية ذلك مباشرة: «لا يزال DeepSeek Harness في المعاينة المطورة ولا يزال يتم اختباره من قبل المطورين الذين يبنون إطارات عمل الوكلاء.»

إذا كنت تبني فوقه، فقم بتثبيت تجزئة الكوميت، واحتفظ بإضافاتك رفيعة مقابل كتالوج التكوين، وتوقع إعادة الاختبار عند كل زيادة في إصدار rc. يجعل التنظيف التلقائي للإضافات وحقن التبعيات إعادة الاختبار أقل إيلاماً من الأطر الأحادية الكتلة، لكن «المعاينة المطورة» تعني بالضبط ما هو مكتوب。

ما الذي يجعل هذا مختلفاً

تبدأ معظم أطر عمل الوكلاء اليوم بدورة دورة وتلحق إمكانية التوسيع كفكرة متأخرة. يقلب Harness الأمر: إمكانية التوسيع هي الإطار، ودورة الدوران هي مجرد إضافة أخرى. النتيجة الملاحظة هي ثلاثة أشياء لا تحصل عليها عادة في حزمة واحدة:

بدّل أي شيء بدون فرع. لا يعجبك نظام الأدوات المدمج؟ استبدله. هل تريد طبقة توجيه LLM مختلفة؟ بدّل الموفر. كل شيء يُحل عبر مفاتيح خدمات Cordis。
قابلية التتبع افتراضياً. سجل الإلحاق فقط ليس إضافة للمراقبة. إنه الطريقة التي تعمل بها الجلسات. الاستئناف، والتفرع، والبحث، وإعادة التشغيل كلها تستخدم نفس الدفق。
إعدادات مسبقة قابلة للتركيب، لا أعلام ميزات. الأربعة أوضاع (Standard / Code / Minimal / Creator) هي مجرد طبقات تصحيح حزمة إضافات مرتبة. يمكنك وضع طبقات إعداداتك الخاصة فوقها باستخدام YAML بدلاً من الكود。

سواء كان هذا النهج ينتصر على أطر العمل الأحادية الكتلة أم لا، فهذا يعتمد على ما إذا كان النظام البيئي للإضافات ينتج ما يكفي من أدوات وموفري طرف ثالث لجعل قصة الاستبدال وإعادة التركيب حقيقية. عند 1.6k نجمة و 12k كوميت في اليوم الأول، فإن الزخم موجود بوضوح。

DeepSeek Harness: إطار عمل وكلاء مفتوح المصدر حيث يصبح كل شيء فعلياً إضافة قابلة للتوصيل

مكدس وكيل كامل، مُلقاً على GitHub

ملخص سطر واحد

Cordis: النواة تحت كل شيء

كل شيء إضافة (حقاً)

أربعة أوضاع وقت التشغيل

كل تشغيل قابل للتتبع

تكوين النموذج: DeepSeek + أي شيء آخر

البدء: ثلاثة مسارات

المسار 1: `npx @deepseek-ai/dsh web`

المسار 2: استنساخ والبناء من المصدر

المسار 3: Python SDK

اكتب إضافتك الأولى

اكتب أداتك الأولى

أوضاع دخول CLI

إضافات المجتمع والنظام البيئي

المعاينة المطورة — نعم، ستنكسر

ما الذي يجعل هذا مختلفاً

المراجع

Share this page

Scan to share on WeChat

DeepSeek Harness: إطار عمل وكلاء مفتوح المصدر حيث يصبح كل شيء فعلياً إضافة قابلة للتوصيل

مكدس وكيل كامل، مُلقاً على GitHub

ملخص سطر واحد

Cordis: النواة تحت كل شيء

كل شيء إضافة (حقاً)

أربعة أوضاع وقت التشغيل

كل تشغيل قابل للتتبع

تكوين النموذج: DeepSeek + أي شيء آخر

البدء: ثلاثة مسارات

المسار 1: npx @deepseek-ai/dsh web

المسار 2: استنساخ والبناء من المصدر

المسار 3: Python SDK

اكتب إضافتك الأولى

اكتب أداتك الأولى

أوضاع دخول CLI

إضافات المجتمع والنظام البيئي

المعاينة المطورة — نعم، ستنكسر

ما الذي يجعل هذا مختلفاً

المراجع

Share this page

المسار 1: `npx @deepseek-ai/dsh web`