# راه‌اندازی 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 توسعه یافته و یک رابط وب با `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 رسمی می‌گوید: «تغییرات ناسازگار با نسخه‌های قبلی وجود خواهد داشت.» نسخه‌ای را که اجرا می‌کنید با این صفحه بررسی کنید.

## کدام پروتکل

**پروتکل 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` | کلیدی ذخیره نشده است، یا متغیر محیطی ارجاع‌شده خالی است | کلید را از طریق **Settings → Models** ذخیره کنید، یا متغیر نام‌برده در `apiKeyEnv` را پیش از اجرای `dsh` export کنید |
| `UNKNOWN_MODEL` | مدل انتخاب‌شده در فهرست ارائه‌دهنده نیست | یک مدل پیکربندی‌شده انتخاب کنید یا شناسه مدل را به ارائه‌دهنده اضافه کنید |
| دریافت مدل‌های موجود خطای 401 برمی‌گرداند | کلید نادرست است | کلید را بررسی کنید؛ کشف مدل، نقطه پایانی سازگار با OpenAI یعنی `GET /models` را فراخوانی می‌کند |
| دریافت فهرست چیزی برنمی‌گرداند یا شکست می‌خورد | قالب فهرست نقطه پایانی از قالبی نیست که کشف مدل می‌خواند | شناسه مدل‌ها را دستی وارد کنید |
| `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` را تنظیم کنید |
| منوی Effort برای مدلی که دستی وارد کرده‌اید نمایش داده نمی‌شود | مدل هیچ سطح استدلالی اعلام نکرده است | **Reasoning levels** را در **Model options** مدل روشن کنید |

## محدودیت‌های شناخته‌شده

- پیش‌نمایش توسعه‌دهنده: فیلدهای پیکربندی و رفتار ممکن است بین انتشارها تغییر کند؛ این صفحه با 0.2.2-rc.1 بررسی شده است، نسخه‌ای که npm در 2026-11-09 با برچسب `latest` علامت می‌زند.
- فرم هیچ فیلدی برای کلیدهای `compat` ندارد؛ آن‌ها را روی مسیر در `cordis.patch.yml` همان‌گونه که در راهنمای رسمی توضیح داده شده تنظیم کنید.
- مدلی که دستی وارد می‌کنید تا زمانی که سطوح استدلالی را اضافه نکنید هیچ سطحی اعلام نمی‌کند و تا وقتی **Image** را در **Model options** آن انتخاب نکنید فقط متنی است (بخش‌های ورودی تصویر و تلاش استدلالی در راهنمای رسمی را ببینید).
- پیش‌فرض‌های ظرفیت: یادداشت‌های انتشار 0.2.2-rc.1 می‌گویند مدل‌های سفارشی که ظرفیتی اعلام نمی‌کنند اکنون به‌طور پیش‌فرض پنجره زمینه 1M اعشاری و خروجی 128K دارند و نقاط پایانی کوچک‌تر باید ظرفیت‌های صریح تعیین کنند تا از فشرده‌سازی تأخیری جلوگیری شود. QCode پنجره زمینه هر مدل را در [qcode.cc/models](https://qcode.cc/models) فهرست می‌کند؛ برای مدلی کمتر از 1M، ارائه‌دهنده را در **Settings → Models** ویرایش کنید و پنجره زمینه و حداکثر توکن خروجی آن مدل را وارد کنید.

## مرتبط

- [نقاط پایانی و مسیرهای 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/en/deepseek-harness-guide) — پیشینه و موارد استفاده