DeepSeek Harness ile Apidog CLI Kullanımı

DeepSeek Harness ile Apidog CLI’yi API test döngüsüne ekleme

DeepSeek Harness bir döngüdür: çalışma alanınızı okur, dosyaları düzenler, bash aracıyla komutları çalıştırır ve çıktıya göre sonraki adımı seçer. Peki API testleriniz neden bu döngünün parçası olmasın? Şu anda Apidog içinde, bir GUI arkasında duruyor ve yalnızca biri tıklamayı hatırladığında çalışıyor. Aracınız onlara doğrudan erişemiyor.

Apidog'u bugün deneyin

Çözüm, tek bir yapılandırma bloğudur. Apidog CLI, Apidog'da oluşturduğunuz test senaryolarını terminalden çalıştıran apidog-cli npm paketidir. CLI yüklendiğinde ve DeepSeek Harness bunu bildiğinde, araç bir Apidog senaryosunu birim testleriniz gibi çalıştırabilir:

1. Komutu çalıştırır.
2. Çıkış kodunu okur.
3. Test başarısızsa raporu inceler.
4. Kodu düzeltir.
5. Senaryoyu yeniden çalıştırır.

Bu yaklaşım, API'nizin hâlâ çalıştığını doğrulamak için işleyicinin kodunu tekrar okuyup yanıt şekilleri hakkında tahmin yürütmekten daha verimlidir. Tek bir CLI komutu, birkaç satırda kesin bir sonuç döndürür. Böylece araç, bağlamını doğrulama yerine kodu düzeltmeye ayırır.

Bu kılavuz, genel kurulum dokümanlarının atladığı DeepSeek Harness entegrasyonunu ele alır:

• DeepSeek Harness hangi talimat dosyasını okur?
• Bash aracı apidog run komutunu nasıl çalıştırır?
• Test döngüsünü nasıl doğrulanabilir tutarsınız?

CLI'yi henüz yüklemediyseniz önce Bir AI kodlama aracıyla Apidog CLI nasıl kurulur kılavuzunu izleyin. Bu makale, apidog --version komutunun sürüm yazdırdığını ve makinenizin kimlik doğrulamasının tamamlandığını varsayar.

Bu yazı hangi DeepSeek Harness hakkında?

Komut satırında dsh olarak bilinen DeepSeek Harness, DeepSeek'in 13 Ağustos 2026'da yayınladığı açık kaynaklı araç iskeletidir. API'deki V4-Pro ile birlikte yayınlanmıştır.

MIT lisanslı proje, github.com/deepseek-ai/deepseek-harness adresinde bulunur ve 20 Ağustos itibarıyla 169 bin yıldızı geçmiştir. Şu komutla başlatabilirsiniz:

npx @deepseek-ai/dsh web

Bu komut, http://127.0.0.1:3080 adresinde yerel bir web arayüzü açar. Buradan başlattığınız proje dizinini çalışma alanı olarak seçersiniz. Araç daha sonra dosyaları okur ve düzenler, komutları çalıştırır ve etkin izin politikasına göre onay gerektiren işlemlerden önce size sorar.

Bu entegrasyonu değerlendirirken iki noktayı dikkate alın:

1. DeepSeek Harness hâlâ geliştirici önizlemesidir. README, uyumluluğu bozabilecek değişiklikler konusunda uyarır. Bu nedenle dosya adlarını ve yapılandırma anahtarlarını Ağustos 2026 sonu için geçerli kabul edin; bir şey çalışmazsa repo belgelerini yeniden kontrol edin.
2. dsh içindeki özellikler Cordis mimarisi üzerine kurulu eklentilerdir. Bu da proje kurallarınızı hangi eklentinin okuduğunu ve hangi dosyaları aradığını bilmenizi gerektirir.

Genel bakış için DeepSeek Harness nedir? yazısına, karşılaştırma için DeepSeek Harness vs Claude Code yazısına bakabilirsiniz.

Adım 1: CLI komutunu AGENTS.md dosyasına ekleyin

DeepSeek Harness, çalışma alanı talimatlarını @deepseek-ai/dsh-agent-instructions eklentisi üzerinden okur. Eklenti, oturumun çalışma dizininden proje köküne (.git ile işaretlenir) doğru yukarı çıkar ve yol üzerindeki talimat dosyalarını yükler:

• AGENTS.md
• Yedek olarak CLAUDE.md
• Yerel katman olarak AGENTS.local.md
• Yerel katman olarak CLAUDE.local.md
• Kullanıcı genelinde $DSH_HOME/AGENTS.md Varsayılan konum: ~/.dsh/AGENTS.md

Yerel dosyalar temel dosyalardan sonra yüklenir. Kullanıcı genelindeki dosya tüm projelere uygulanır. 1 MiB üzerindeki dosyalar yok sayılır; pratikte bir kural dosyanız bu sınıra yaklaşmamalıdır.

Deponuzda Codex için zaten AGENTS.md veya Claude Code için CLAUDE.md varsa, DeepSeek Harness bunu ek kurulum olmadan kullanabilir. Dosyaya kısa ve uygulanabilir bir Apidog bölümü ekleyin:

## Apidog CLI ile API testi

- API'yi doğrulamak için Apidog test senaryosunu çalıştırın. GUI üzerinden manuel tıklama yapmayın.
- Komut: `apidog run -t <scenario_id> -e <env_id> -r cli`
- Çıkış kodu 0 ise tüm kontroller geçmiştir.
- Sıfır olmayan çıkış kodu bir hata olduğunu gösterir. Raporu okuyun ve kodu düzeltin.
- Makine zaten doğrulanmış durumda. `--access-token` eklemeyin ve bu dosyaya token yazmayın.

Gerçek senaryo ve ortam kimliklerini aldıktan sonra yer tutucuları değiştirin.

Neden kural dosyası kullanmalısınız?

Sohbete yazılan bir senaryo kimliği yalnızca oturum boyunca geçerlidir. AGENTS.md dosyasına yazılan komut ise:

• Depoyu klonlayan her makinede kullanılabilir.
• Her ekip üyesinin yeni oturumuna yüklenir.
• Aracının test çalıştırma adımını unutmasını önler.

Birden fazla projede çalışıyorsanız ~/.dsh/AGENTS.md dosyasına genel bir kural ekleyebilirsiniz:

API değişikliklerini her zaman projenin Apidog çalıştırma komutuyla doğrula.

Senaryo ve ortam kimliklerini ise proje içindeki AGENTS.md dosyasında tutun.

Adım 2: Çalıştırma komutunu Apidog'dan kopyalayın

Senaryo ve ortam kimliklerini tahmin etmeyin. Apidog'da test senaryosunu açın, CI/CD sekmesine gidin ve oluşturulan komutu kopyalayın.

Örnek:

apidog run -t 123456 -e 789012 -r cli

Bayrakların anlamı:

• -t: Test senaryosu kimliği
• -e: Ortam kimliği
• -r cli: Sonuçları satır içi yazdıran raporlayıcı

Gerçek komutu doğrudan AGENTS.md dosyanıza ekleyin:

## Apidog CLI ile API testi

bash
apidog run -t 123456 -e 789012 -r cli

- Çıkış kodu 0 ise test başarılıdır.
- Sıfır olmayan çıkış kodunda raporu okuyup kodu düzeltin.

plaintext

Bu şekilde araç, kimlikleri tahmin etmek yerine Apidog'un oluşturduğu komutu çalıştırır.

Adım 3: DeepSeek Harness'in testi çalıştırmasını sağlayın

Çalışma alanınızı seçerek dsh web arayüzünde bir oturum başlatın. Talimat yükleyici AGENTS.md dosyanızı aracının bağlamına eklediği için CLI komutunu bilir.

API'nizi etkileyen bir değişiklik yaptıktan sonra araca şu talimatı verebilirsiniz:

Apidog test senaryosunu çalıştır ve çıkış kodunu bildir.

Araç komutu bash aracı üzerinden yürütür. Bu aracın çalışma biçimini bilmek, hata ayıklama sırasında önemlidir.

Araç kataloğuna göre varsayılan bash aracı her komutu yeni bir kabukta çalıştırır. Bu nedenle çağrılar arasında şunlar kalıcı olmaz:

• Çalışma dizini
• Ortam değişkenleri
• Shell fonksiyonları

workdir geçirilmezse komutlar oturumun çalışma alanından çalışır.

Bu davranış, tek ve kendi kendine yeten apidog run komutu için uygundur. Ancak araç önce bir dizine cd edip testi ikinci bir komutla çalıştıramaz; ikinci komut yeni bir kabukta başlar. Senaryonuzun bir alt dizinden çalışması gerekiyorsa tam çağrıyı tek satırda tanımlayın:

cd services/payment-api && apidog run -t 123456 -e 789012 -r cli

Bash aracının iki önemli davranışı

Sıfır olmayan çıkışlar açıkça şu biçimde gösterilir:

[exit code: N]

Bu işaret, uzun çıktı kesilse bile testin başarısız olduğunu anlamanızı sağlar.

Komutlar ayrıca dosya korumalı alanı altında çalışabilir. Engellenen bir işlem, normal komut hatası yerine politika reddi olarak raporlanır. Salt okunur bir test çalışması bunu nadiren tetikler; ancak ./apidog-reports dizinine HTML raporu yazmak, etkin politikaya bağlı olarak reddedilebilir.

Onay akışı

apidog run komutunun çalıştırılmadan önce onay isteyip istememesi etkin izin politikasına bağlıdır. Web arayüzü, kullanıcı kılavuzunda belirtildiği gibi onay gerektiren işlemlerden önce soru gösterir.

Bir hazırlık ortamına karşı çalışan test senaryosu için onay istendiğinde işlemi onaylayın. Bu, genellikle güvenli ve çoğunlukla okuma amaçlı bir komuttur.

Adım 4: CLI raporunu okuyun

Bir çalıştırma başarısız olduğunda ilk bakılacak yer rapordur. -r cli ile araç satır içi bir çıktı alır:

• Her istek
• Her kontrol
• Başarısız kontrol
• Beklenen değer
• Gerçek değer

Örneğin başarısız kontrol, beklenen durum kodunu veya eksik alanı doğrudan gösterebilir. Bu bilgi çoğu durumda aracının düzeltmeyi bulması için yeterlidir.

Tarayıcıda açabileceğiniz veya ekip arkadaşınıza gönderebileceğiniz bir HTML raporu da oluşturabilirsiniz:

apidog run -t 123456 -e 789012 -r cli,html

html raporlayıcısı ./apidog-reports dizinine eksiksiz bir rapor yazar. cli raporlayıcısını listede tutun; böylece araç bir sonraki adımı seçmek için satır içi çıktıyı okumaya devam eder.

Döngü baştan sona nasıl çalışır?

Örneğin araç bir ödeme işleyicisini düzenliyor olsun.

CLI entegrasyonu olmadan döngü şu noktada sona erebilir:

Kod doğru görünüyor.

AGENTS.md içindeki Apidog komutuyla döngü şu hâle gelir:

1. Araç ödeme işleyicisini düzenler.
2. Apidog test senaryosunu çalıştırır.
3. Çıkış kodunu okur.
4. Test başarılıysa ilerler.
5. Test başarısızsa raporu inceler.
6. Kodu düzeltir.
7. Senaryoyu yeniden çalıştırır.

Örnek başarısızlıklar şunlar olabilir:

• 200 beklenirken 500 dönmesi
• total alanının eksik olması
• Para birimi kodunun yanlış olması

Bu durumda araç [exit code: 1] işaretini görür, başarısız kontrolü okur, işleyiciyi düzeltir ve testi tekrar çalıştırır. API sözleşmesi kontrolü, birim testlerle aynı düzenleme-test etme-düzeltme döngüsünün parçası olur.

Buradaki önemli nokta, aracın API'nin çalıştığına ikna olmak için her rota dosyasını yeniden okumak zorunda kalmamasıdır. Senaryo, Apidog'da görsel olarak oluşturulmuş beklenen davranışı zaten içerir.

İş bölümü şöyledir:

• DeepSeek Harness kodu yazar.
• Apidog CLI API katmanını doğrular.
• Siz Apidog üzerinde test senaryolarını oluşturursunuz.

dsh komutun gerçekten çalıştırdığını doğrulayın

Araçlar bazen çalıştırmadıkları işlemleri özetleyebilir. DeepSeek Harness geliştirici önizlemesinde olduğu için sonuçları doğrulamadan kabul etmeyin.

1. Gerçek bash çağrısını kontrol edin

dsh web arayüzü, aracın araç çağrılarını ve çıktısını gösterir. Gerçek apidog run ... çağrısını arayın.

Araç testleri çalıştırdığını söylüyor ancak böyle bir bash çağrısı görünmüyorsa test çalıştırılmamış olabilir. Araca komutu yeniden çalıştırmasını ve ham çıktıyı göstermesini söyleyin:

Apidog komutunu gerçekten çalıştır. Bash çağrısını, ham çıktıyı ve çıkış kodunu göster.

2. Çıkış kodunu kontrol edin

Şu soruyu doğrudan sorun:

Apidog çalıştırma komutunun çıkış kodu neydi?

Başarısız çalıştırmalarda [exit code: N] işareti görünmelidir. Özet "testler geçti" dese bile çıkış kodu sıfır değilse güvenilecek değer çıkış kodudur.

3. Doğru senaryonun kullanıldığını kontrol edin

scenario not found veya benzeri bir hata genellikle şu sorunlardan birine işaret eder:

• Araç senaryo kimliğini uydurmuştur.
• Yanlış senaryo kimliği kullanılmıştır.
• Ortam kimliği yanlıştır.

-t ve -e değerlerini hem AGENTS.md içeriğiyle hem de Apidog'un CI/CD sekmesindeki komutla karşılaştırın. Kural dosyasındaki kimlikler kaynaktır; aracın yazdığı kimlikler tahmin olabilir.

İsteğe bağlı: Belirtim erişimi için Apidog MCP sunucusunu ekleyin

Senaryo çalıştırmak doğrulama ihtiyacını karşılar. Aracının kod yazarken API belirtiminizi de okumasını istiyorsanız MCP kullanabilirsiniz.

Ancak mevcut durumu doğru çerçevelemek gerekir: Ağustos 2026 sonu itibarıyla MCP desteği DeepSeek Harness'in temel README'sinde veya kullanıcı kılavuzunda belgelenmemiştir. Mevcut çözüm, dsh-plugin GitHub konusu üzerinden keşfedilen bir topluluk eklentisidir:

hyqhyq3/dsh-mcp-manager

Bu eklenti:

• Ayarlar altında bir MCP sayfası ekler.
• Uzak HTTP ve yerel stdio sunucularını destekler.
• Araçları mcp__<ad>__* biçiminde kaydeder.
• Proje başına sunucu tanımlarını <çalışma_alanı>/.dsh/dshmm/mcp.json dosyasından okur.

Bu yöntemle Apidog MCP sunucusuna bağlanabilirsiniz. Sunucu API belirtimlerini MCP üzerinden açığa çıkarır. Böylece araç, bir senaryo başarısız olduktan sonra değil, işleyiciyi yazmadan önce bir uç noktanın gerçek şemasını kontrol edebilir.

Topluluk eklentisi ve geliştirici önizlemesi nedeniyle entegrasyonun güncellemelerle bozulabileceğini varsayın. Bu yaklaşımı ek bir katman olarak değerlendirin. Temel ve daha dayanıklı yol yalnızca bir shell komutuna ihtiyaç duyan Apidog CLI entegrasyonudur.

Önizleme uyarıları

DeepSeek Harness hızlı geliştirildiği için bazı ayrıntılar değişebilir. Özellikle şu alanları güncel dokümanlarla karşılaştırın:

• Talimat eklentisinin aradığı dosya adları
• Bash aracının korumalı alan raporlaması
• Topluluk MCP eklentisinin davranışı

Bununla birlikte desen taşınabilirdir:

1. Kural dosyasına tek bir API doğrulama komutu yazın.
2. CLI'nin temiz bir çıkış kodu döndürmesini sağlayın.
3. Aracın komutu çalıştırmasını ve sonucu okumasını bekleyin.
4. Başarısızlıkta rapora göre kodu düzeltin.

Bu yöntem dsh'de, Claude Code'da Apidog CLI kullanırken ve benzer araçlarda aynı nedenle çalışır: Araçlar komut çıktısını okuyabilir; ancak bu çıktı olmadan güvenilir doğrulama yapamaz.

Başlamak için Apidog'u indirin, görsel olarak bir test senaryosu oluşturun, CI/CD sekmesinden apidog run komutunu kopyalayın ve bu komutu deponuzdaki AGENTS.md dosyasına ekleyin. DeepSeek Harness API kodunuza bir sonraki değişiklikte dokunduğunda, tamamlandığını söylemeden önce kendi işini de kontrol eder.

Sıkça Sorulan Sorular

DeepSeek Harness, AGENTS.md dosyasını yerel olarak okur mu?

Evet. @deepseek-ai/dsh-agent-instructions eklentisi, proje kökünden ve oturumun çalışma dizininin üzerindeki dizinlerden AGENTS.md dosyasını yükler. AGENTS.md yoksa CLAUDE.md yedek olarak kullanılır.

Ayrıca şu katmanlar da yüklenebilir:

• AGENTS.local.md
• CLAUDE.local.md
• ~/.dsh/AGENTS.md

Diğer araçlar için zaten bir AGENTS.md tutuyorsanız, dsh bu dosyayı olduğu gibi kullanabilir.

dsh'de Apidog CLI kullanmak için ücretli bir DeepSeek planına ihtiyacım var mı?

Hayır. DeepSeek Harness MIT lisanslı açık kaynak bir projedir ve kendi modelinizi kullanabilirsiniz. Katalog sağlayıcıları Anthropic, OpenAI, Bedrock, Vertex ve Azure'u kapsar. Özel ağ geçitleri de settings.yaml üzerinden yapılandırılabilir; ayrıntılar için DeepSeek Harness'te herhangi bir model nasıl çalıştırılır? yazısına bakabilirsiniz.

Apidog CLI ücretsiz bir npm paketidir. Belirli bir model yerine Apidog test senaryosu ve kimlik doğrulaması gerektirir.

Araç neden ikinci komutta ilk komutun değiştirdiği dizini unutuyor?

Bu, varsayılan bash aracının tasarımından kaynaklanır. Her çağrı yeni bir shell'de çalıştığı için cd komutlar arasında kalıcı olmaz.

Çözüm olarak:

• workdir parametresini kullanın.
• Ya da tam apidog run çağrısını tek satırda çalıştırın.

Örnek:

cd services/payment-api && apidog run -t 123456 -e 789012 -r cli

dsh senaryoyu her seferinde sormadan çalıştırabilir mi?

Bu, etkin izin politikasına bağlıdır. Web arayüzü onay gerektiren işlemlerden önce soru gösterir. Kullanıcı kılavuzu politika seviyelerini ayrıntılı biçimde listelemediği için dağıtımınızdaki Ayarlar bölümünü kontrol edin.

Onay istendiğinde, hazırlık ortamına karşı çalışan bir apidog run komutunu onaylamak genellikle güvenli bir işlemdir.