DeepSeek Harness: kodlama ajanı rehberi

DeepSeek Harness, DeepSeek AI tarafından geliştirilen açık kaynak bir kodlama ajanı ve agent runtime'dır. Modelin çevresindeki döngüyü, araçları, workspace erişimini, oturumları, izinleri ve arayüzü sağlar. Model ise hâlâ bir API provider'dan gelir. Bu rehber önce DeepSeek code harness'ın ne yaptığını açıklar, ardından resmi özel provider akışıyla OmniAKey'e bağlar.

DeepSeek Harness nedir?

dsh olarak kısaltılan DeepSeek Harness yeni bir dil modeli değildir. Bir modeli agent'a dönüştüren yazılım katmanıdır: workspace'i anlamasını, araç çağırmasını, dosya düzenlemesini, komut çalıştırmasını, oturum saklamasını ve işlem onayı istemesini sağlar.

Temel tasarım fikri everything is a plugin yaklaşımıdır. Harness, Cordis plugin sistemi üzerine kuruludur; modeller, araçlar, skills, oturumlar, sandbox, depolama, döngüler, zamanlama ve UI yapılandırma ile değiştirilebilir veya yeniden birleştirilebilir.

İzlenebilir event stream yalnızca chat geçmişi değildir. Resume, fork, search ve replay aynı oturum günlüğü üzerinde çalışır; agent cevap vermeden önce birçok tool call yaptığında bu özellikle değerlidir.

Bu araç ne değildir?

• DeepSeek V4 Pro veya başka bir model değildir. Harness ile model farklı katmanlardır.
• Henüz kararlı bir production sürümü değildir. Proje bunu developer preview olarak tanımlar ve uyumluluğu bozacak değişiklikler konusunda uyarır.
• npm quick start ile çalıştırıldığında barındırılan bir kodlama servisi değildir; Web UI varsayılan olarak yerel loopback'e bağlanır.
• Açık kaynak, model inference'ını ücretsiz yapmaz. Repo MIT lisanslıdır; API kullanımını yapılandırdığınız provider faturalandırır.

DeepSeek Harness için OmniAKey ayarları

Ayrıntılı adımlardan önce tüm yapılandırma:

/v1 Base URL'nin parçasıdır. Çıplak origin kullanmayın, /v1/v1 olarak tekrarlamayın ve tam /chat/completions yolunu yapıştırmayın. Araç işlem yolunu kendisi ekler.

1. DeepSeek Harness'ı kurup başlatın

Node.js kurun, agent'ın görmesini istediğiniz proje dizininde terminal açın ve resmi npm quick start komutunu çalıştırın:

npx @deepseek-ai/dsh web

Güncel komut Web UI'yi şu adreste başlatır:

http://127.0.0.1:3080

3080 doluysa Web profile farklı port kabul eder:

npx @deepseek-ai/dsh web --port 3081

dsh komutunu çalıştırdığınız dizin varsayılan filesystem konumu olur; fakat UI'de workspace ekleyip seçene kadar composer kapalıdır. Repo'yu bilinçli seçin: etkin permission policy'ye göre agent dosya ve shell araçları alabilir.

2. OmniAKey için ayrı bir API key oluşturun

OmniAKey API Keys dashboard'unu açıp Harness için ayrı bir anahtar oluşturun. Ayrı credential, birden çok araçla paylaşılan anahtara göre daha kolay limitlenir, döndürülür, iptal edilir ve denetlenir.

Anahtarı repo'ya, shell geçmişine, ekran görüntüsüne, issue'ya veya chat'e koymayın. Web UI kaydedilen key'i write-only tutar: resmi belgelere göre secret $DSH_HOME/.credentials.yaml içinde saklanır, settings yalnız credential reference taşır ve sayfa maskelenmiş açıklama alır.

3. OmniAKey'i özel provider olarak ekleyin

Yeni kurulumda Internal Testing Notice ekranını Continue ile geçin. Sonraki onboarding penceresi yalnız resmi DeepSeek API key ister; OmniAKey yerleşik resmi rota yerine özel provider olarak eklenmelidir, bu yüzden Configure later seçin.

Harness içinde Settings → Models yolunu açın, Add a custom provider seçin ve şunları girin:

1. Provider ID: omniakey. ID küçük harfle başlamalıdır.
2. Display name: OmniAKey.
3. Base URL: https://api.omniakey.com/v1.
4. API protocol: openai-completions.
5. API key: az önce oluşturduğunuz OmniAKey anahtarı.

Mevcut Harness tasarımında Provider ID kalıcıdır; kayıtlı oturumlar, defaults, requests ve credential references onu kullanır. Display name, Base URL, protocol, key ve model listesi düzenlenebilir.

4. Modelleri getirip seçin

Model catalog altında Fetch available models seçeneğini kullanın. Özel OpenAI uyumlu provider için Harness, formdaki Base URL'ye Bearer kimlik doğrulamalı GET /models gönderir. Bu ayarla OmniAKey'in GET /v1/models endpoint'ine ulaşır.

Yalnız kullanacağınız modelleri seçin. Bu iş akışı için iki başlangıç ID'si:

Aynı provider desteklenen Claude, GPT, Gemini, Grok ve GLM modellerini de sunar. ID'leri güncel model kataloğundan kopyalayın; model adları yaklaşık alias değil, tam kimliklerdir.

Discovery kullanılamıyorsa tam Model ID'yi elle ekleyin. Harness özel provider oluşturmak için en az bir model ister.

5. Kaydedin ve güvenli test yapın

Provider'ı kaydedin, Choose workspace ile projenizi seçin, yeni oturum açın ve model picker'da OmniAKey / deepseek-v4-pro veya OmniAKey / deepseek-v4-flash seçin.

Önce dar ve read-only bir prompt çalıştırın:

package.json dosyasını incele ve mevcut script'leri özetle. Dosya düzenleme ve komut çalıştırma.

Bu test; workspace, provider, key, tam Model ID ve temel yanıt yolunu edit veya shell izni vermeden doğrular. Metin yanıtı tüm tool-call biçimlerinin çalıştığını kanıtlamaz; büyük refactor'dan önce geri alınabilir bir araç görevi deneyin.

Model ayarları yeniden başlatmadan sonraki istekte devreye girer. Ancak ilk isteğini gönderen oturum log'a yazılan modeli korur. Provider veya model değiştirdikten sonra net test için yeni oturum başlatın.

İsteğe bağlı: settings.yaml yapılandırması

İlk kullanımda Web UI daha anlaşılırdır. Kontrollü yerel ortamda $DSH_HOME/settings.yaml içinde secret yerine environment variable referanslayan bir profile da kullanabilirsiniz:

export OMNIAKEY_API_KEY="your-omniakey-api-key"

llm-pi-ai:
  providers:
    omniakey:
      displayName: OmniAKey
      apiKeyEnv: OMNIAKEY_API_KEY
      api: openai-completions
      baseURL: https://api.omniakey.com/v1
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash

Anahtar dsh sürecini başlatan environment içinde bulunmalıdır. YAML'da apiKeyEnv yerine literal secret yazmayın. Resmi dsh-llm-pi-ai referansı, secret'ın settings'e girmemesi için credential reference önerir.

Neden DeepSeek Harness ile OmniAKey?

Harness özel gateway kabul eder; OmniAKey bu extension point'i tek, tekrar kullanılabilir provider'a dönüştürür.

• Birden çok aile için tek ayar. Her vendor için ayrı profile kurmadan picker'da tam Model ID'yi değiştirin.
• Model discovery. Harness, ID'leri ezberden yazmak yerine OmniAKey'in OpenAI uyumlu listesini okuyabilir.
• Ayrı operasyonel kontroller. Harness'a özel key, quota, rotation ve usage trail verin.
• Açık model kimliği. OmniAKey sessiz model substitution yapmaz; istenen model çalışır, erişilemeyen upstream görünür hata verir.
• Yeni agent aboneliği yerine API kullanım ücreti. OmniAKey ön ödemeli, token başına faturalandırılır; güncel availability ve fiyat katalogda kalır.

Bu, OmniAKey'in doğrudan resmi sağlayıcı anahtarından her zaman daha iyi olduğu anlamına gelmez. Yalnız resmi hesap ve endpoint gerekiyorsa doğrudan provider mantıklıdır. Aynı Harness kurulumu bir key ve Base URL arkasında seçili DeepSeek ve diğer aileleri kullanacaksa OmniAKey daha değerlidir.

Sorun giderme

Fetch available models 401 döndürüyor

Key'in OmniAKey'den geldiğini, boşluk içermediğini, etkin olduğunu ve tam https://api.omniakey.com/v1 ile kullanıldığını kontrol edin. Discovery Bearer authentication kullanır.

Provider 404 döndürüyor

Önce Base URL'yi kontrol edin. Yaygın hatalar /v1 eklememek, iki kez eklemek veya https://api.omniakey.com/v1/chat/completions değerini Base URL sanmaktır.

UNKNOWN_MODEL

Model provider'ın kayıtlı listesinde değildir. Discovery'yi yenileyin veya katalogdan tam ID'yi ekleyip yeni oturumda seçin.

MISSING_CREDENTIAL

Key'i Settings → Models içinden kaydedin veya OMNIAKEY_API_KEY değişkeninin Harness'ı başlatan shell'de bulunduğunu doğrulayın. Başka terminalde ayarlamak çalışan süreci değiştirmez.

Model değişikliği uygulanmıyor gibi görünüyor

Yeni oturum açın. Mevcut oturum ilk istekten sonra provider ve modeli append-only log'da korur.

Metin çalışıyor ama araç hata veriyor

Temel generation ve structured tool use farklı kontrollerdir. Read-only araç göreviyle başlayın, Trajectory'yi inceleyin ve permission veya limit artırmadan önce hatayı bulun. Geçerli key'i döndürmek bozuk tool call'ı düzeltmez.

Sık sorulan sorular

Bu araç ücretsiz mi?

Kaynak kod MIT lisanslıdır. Model inference ayrıdır ve resmi API, OmniAKey veya başka provider üzerinden ücret doğurabilir.

OmniAKey üzerinden DeepSeek V4 Pro kullanabilir mi?

Evet. OmniAKey'i openai-completions özel provider olarak ekleyin ve tam deepseek-v4-pro ID'sini seçin. Daha düşük fiyatlı rota olarak deepseek-v4-flash da bulunur.

OmniAKey key'ini yerleşik DeepSeek kartına yapıştırmalı mıyım?

Add a custom provider kullanın. Yerleşik kart resmi DeepSeek rotasını yapılandırır; özel provider ise gateway için belgelenmiş yoldur ve OmniAKey'in ihtiyaç duyduğu Base URL, protocol ve model listesi alanlarını açar.

Aynı provider Claude, GPT veya Gemini kullanabilir mi?

Model OmniAKey'in OpenAI uyumlu yüzeyinde destekleniyorsa evet. Canlı listeyi getirip tam ID'leri ekleyin. Protokol özellikleri değişebilir; seçilen modelin tool davranışını test edin.

API key nerede saklanıyor?

Models sayfasından kaydedilen key write-only olarak $DSH_HOME/.credentials.yaml içine gider; settings credential reference tutar. YAML için apiKeyEnv kullanıp secret'ı process environment'a verin.

Kararlı production iş akışına hazır mı?

Bugün değerlendirme hedefi olarak ele alın. Resmi belgeler açıkça developer preview der ve uyumluluğu bozan değişiklikler uyarısı verir. Sürümü pin'leyin, secretsız yapılandırmayı yedekleyin ve yükseltme sonrası resmi rehberi kontrol edin.

Kontrol edilen kaynaklar

• DeepSeek Harness ürün sayfası
• DeepSeek Harness GitHub README
• Resmi Web UI quick start
• Resmi model ve custom provider rehberi
• Resmi dsh-llm-pi-ai referansı
• OmniAKey OpenAI uyumlu API referansı
• OmniAKey güncel model kataloğu