Bu, Apidog'un API testi ve API yaşam döngüsü yönetimi için bir komut satırı aracı olan Apidog CLI'ı nasıl geliştirdiğini paylaşan 10 bölümlük bir seridir. Sırasıyla okuyun veya ilgilendiğiniz herhangi bir gönderiye atlayın:
| Başlık | Odak Noktası | |
|---|---|---|
| 1 | 126 MCP Aracı Oluşturduk. Ancak Bu, Temsilci İçin En İyi Çözüm Değil | Sorun keşfi |
| 2 | Neden Yepyeni Apidog CLI Geliştirdik | Mimari geliştirme |
| 3 | Altın Kural: CLI Gerçekleri Üretir, Model Gerçekler Üzerine Hareket Eder | Temel felsefe |
| 4 | agentHints: CLI'lara Temsilcilerle Konuşmayı Öğretmek |
Yapılandırılmış çıktı |
| 5 | YETENEK: Operasyonel Deneyimi Kod Olarak Gönderme | Operasyonel deneyim |
| 6 | Sayılar Yalan Söylemez: %30 Daha Az Araç Çağrısı, %25 Daha Az Token | Nicel sonuçlar |
| 7 | PRD'den Test Döngüsüne: Apidog CLI ile Eksiksiz Bir Temsilci İş Akışı | Pratik eğitim |
| 8 | CI/CD Uyumluluğu Neden Temsilci Araçları İçin Tartışılmazdır? | DevOps perspektifi |
| 9 | Yapay Zeka Dalı: Yapay Zeka Temsilcileri ile Daha Güvenli Proje Değişiklikleri | Güvenlik katmanı |
| 10 | Önce Şartname Dündü. Yetenek-Önce'ye Hoş Geldiniz. | Vizyon ve gelecek |
Tipik kullanıcı görevlerinde MCP ile CLI + YETENEK'i karşılaştırdık. Sonuçlar: daha az araç çağrısı, daha az token israfı, daha iyi hata kurtarma—ve veriler nedenini açıklıyor.
Önemli Soru
Paylaştığımız tüm felsefe ve tasarım prensipleri gerçekten işe yarıyor mu?
Her iki yaklaşımda da birçok tipik kullanıcı görevini dahili olarak karşılaştırdık:
| Görev Türü | Açıklama |
|---|---|
| Test durumu ekle + doğrulama | Uç nokta için test durumu oluştur, testleri çalıştır |
| Test senaryolarını sürdür | Karmaşık çok adımlı senaryoları güncelle |
| Proje varlıklarını içe aktar/doğrula | Verileri içe aktar, yapıyı onayla, testleri çalıştır |
Sonuçlar sadece öznel iyileştirmelerden ibaret değildi. Bunlar ölçülebilir düşüşlerdi.
Görev 1: Uç Noktaya Göre Test Durumu Ekle
Kullanıcı talebi:
"Bu uç nokta için bir test ekle ve doğrulamayı çalıştır"
MCP Rotası
| Aşama | Ne Olur |
|---|---|
| Araç keşfi | Temsilci araç listesinde arama yapar |
| Araç seçimi | Doğru aracı seçmek için birden fazla tur |
| Alan keşfi | Temsilci araç şemasını okur |
| Alan tahmini | Temsilci gerekli alanları tahmin eder |
| Yazma denemesi | Temsilci oluşturma aracını çağırır |
| Hata yanıtı | Sunucu reddeder (yanlış alan/eksik gerekli alan) |
| Yeniden deneme | Temsilci ayarlar, tekrar dener |
| Daha fazla yeniden deneme | Başarılı olana kadar tekrarla |
| Testleri çalıştır | Temsilci çalıştırma aracını bulur, yürütür |
Tipik desen:
Araçları ara → Araç seç → Şemayı oku → Alanları tahmin et → Yaz → Hata → Yeniden dene → Yaz → Hata → Yeniden dene → Başarı → Çalıştırma aracını bul → ÇalıştırCLI + YETENEK Rotası
| Aşama | Ne Olur |
|---|---|
| YETENEK rehberliği | YETENEK görev türünü tanımlar, iş akışı sağlar |
| Uç noktayı oku | CLI uç nokta gerçeklerini okur |
| Test durumu oluştur | Temsilci, gerçek uç nokta verilerine göre oluşturur |
| Yerel olarak doğrula | cli-schema yazmadan önce doğrular |
| Yaz | CLI test durumu oluşturur |
| Geri oku | CLI oluşturulan yapıyı + agentHints'i döndürür |
| Testleri çalıştır | agentHints çalıştırmayı önerir, Temsilci takip eder |
Tipik desen:
YETENEK rehberlik eder → Uç noktayı oku → Oluştur → Doğrula → Yaz → Geri oku → ÇalıştırSonuçlar
| Metrik | MCP Rotası | CLI + YETENEK | İyileşme |
|---|---|---|---|
| Araç çağırma adımları | ~15-20 | ~10-12 | ↓ %30 |
| Açıklamalardan gelen token | ~50.000 yüklendi | ~2.000 yüklendi | ↓ %96 |
| Yeniden denemelerden gelen token | ~5.000+ israf | ~500 israf | ↓ %90 |
| Toplam token israfı | ~55.000 | ~2.500 | ↓ %25 |
Araç çağırma adımları yaklaşık %30 azaldı. Geçersiz araç açıklamaları ve hata yeniden denemelerinden kaynaklanan token tüketimi yaklaşık %25 azaldı.
Görev 2: Yapılandırılmış Yazmalar (İşleyici, Onaylama, Çıkartıcı)
Kullanıcı talebi:
"Bu test durumuna işlem sonrası onaylamaları ve değişken çıkarma ekle"
MCP Rotası
| Aşama | Ne Olur |
|---|---|
| Alan adlarını tahmin et | Temsilci tam adları bilmez |
| Enum değerlerini tahmin et | Temsilci karşılaştırıcıyı, türü tahmin eder |
| Yazma denemesi | Sunucu yanlış değerleri reddeder |
| Ağ yeniden denemesi | Her hata için gidiş-dönüş |
| Birden fazla deneme | 3-5 yeniden deneme yaygındır |
Yaygın hatalar:
| Yanlış Tahmin | Doğru Değer | Yeniden Deneme Sayısı |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
Her hata = 1 ağ gidiş-dönüşü + yanıt + Temsilci işleme.
CLI + YETENEK Rotası
| Aşama | Ne Olur |
|---|---|
| Test durumunu oku | CLI gerçek yapıyı alır |
| Eklemeleri oluştur | Temsilci gerçek formata göre oluşturur |
| Yerel olarak doğrula | cli-schema ağdan önce hataları yakalar |
| Yerel olarak düzelt | Temsilci doğrulama çıktısına göre ayarlar |
| Tekrar doğrula | Düzeltmeyi onayla |
| Yaz | Yalnızca geçerli yazmalar sunucuya gider |
Tüm hatalar yerel olarak yakalandı. Alan hataları için ağ yeniden denemesi yok.
Sonuçlar
| Metrik | MCP Rotası | CLI + YETENEK | İyileşme |
|---|---|---|---|
| Yapısal hatalardan kaynaklanan ağ yeniden denemeleri | 3-5 | 0 | ↓ %100 |
| Hata yanıtlarından gelen token | ~2.000 | ~0 | ↓ %100 |
| Toplam tekrarlanan çağrılar | ~5 | ~1 | ↓ %40 |
Yapısal hatalardan kaynaklanan tekrarlanan çağrılar yaklaşık %40 azaldı.
Görev 3: Oluşturma Sonrası Sürekli Operasyonlar
Kullanıcı talebi:
"Bu uç noktalarla bir test senaryosu oluştur"
MCP Rotası
| Aşama | Ne Olur |
|---|---|
| Senaryo oluştur | Temsilci oluşturma aracını çağırır |
| Başarılı yanıt | Temsilci "oluşturuldu" ifadesini görür |
| Yazmaya devam et | Temsilci hemen günceller/ekler |
| Geri okumayı atla | Temsilci gerçek yapıyı okumaz |
| Varsayıma dayalı yazma | Temsilci tahmini kimlikler/yapı ile yazar |
| Hata veya eksik | Sonuç beklentiyi karşılamaz |
Sorun: Yürütme ataleti.
Model, başarıdan sonra doğrudan devam etme eğilimindedir ve geri okuma adımını atlar.
CLI + YETENEK Rotası
| Aşama | Ne Olur |
|---|---|
| Senaryo oluştur | CLI senaryo oluşturur |
| Başarı + agentHints | CLI başarıyı + sonraki adım önerilerini döndürür |
agentHints: "Önce geri oku" |
Temsilci öneriyi görür |
| Öneriyi takip et | Temsilci geri okur |
| Gerçek yapı ile çalış | Temsilci doğru verilerle devam eder |
agentHints açıkça geri okumayı önerir. Temsilci takip eder.
Sonuçlar
| Metrik | MCP Rotası | CLI + YETENEK | İyileşme |
|---|---|---|---|
| Devam etmeden önce geri okuyanların oranı | ~%20 | ~%85 | ↑ %425 |
| Doğrudan atlamalardan kaynaklanan hata yeniden denemeleri | ~3-5 | ~0-1 | ↓ %21 |
Temsilcilerin proaktif olarak geri okuma, doğrulama ve doğrulama çalıştırma oranı önemli ölçüde arttı. Bir sonraki adıma doğrudan atlamadan kaynaklanan hata yeniden denemeleri yaklaşık %21 azaldı.
Özet: Tasarrufların Kaynağı
| Tasarruf Kaynağı | Açıklama |
|---|---|
| Araç keşfi | CLI komutları açık adlara sahiptir; YETENEK seçime rehberlik eder |
| Şema doğrulama | Yerel doğrulama ağ çağrısından önce hataları yakalar |
| Hata kurtarma | agentHints sadece "başarısız" demek yerine eyleme geçirilebilir öneriler sunar |
| Geri okuma rehberliği | Varsayıma dayalı yazmaları önler |
| İş akışı sırası | YETENEK karar noktalarını azaltır |
Gerçek Maliyet Analizi
Temel içgörü:
Ürünlerin temsilci tarafından etkinleştirilmesi, daha fazla araç, daha iyi demek değildir.
Modelin gerçekten tükettiği:
| Maliyet Türü | MCP Yükü | CLI + YETENEK Yükü |
|---|---|---|
| Bağlam | Araç açıklamaları, şemalar | Yalnızca göreve odaklı YETENEK |
| Dikkat | Birçok araç arasından seçim yapma | Rehberli iş akışını takip etme |
| Yol seçimi | Sıralamaları tahmin etme | YETENEK tanımlı sıra |
| Kullanıcı token maliyetleri | Yeniden denemeler, başarısız çağrılar | Doğrulanmış yazmalar, daha az çağrı |
Araç sayısı arttıkça, modelin gerçekten tükettiği şey API çağrı yeteneği değil, bağlam, dikkat, yol seçimi ve kullanıcı token maliyetleri arasındaki dengelemelerdir.
Mühendislik Prensibi
Hedef:
Bu maliyetleri model bağlamından çıkarıp mühendislik sisteminin karşılayabileceği konumlara geri taşımak.
| Maliyet | MCP Konumu | CLI + YETENEK Konumu |
|---|---|---|
| Araç keşfi | Model aramalıdır | YETENEK sağlar |
| Alan doğrulama | Model bilmelidir | cli-schema doğrular |
| Sonraki adım rehberliği | Model karar vermelidir | agentHints önerir |
| Ürün semantiği | Model anlamalıdır | CLI ele alır |
Mühendislik sistemi karmaşıklığı emer. Model, üretim ve yargılamaya odaklanır.
Bu Sayılar Ne Anlama Geliyor
Sayılar daha spesifik bir sorunu açıklıyor:
| İçgörü | Çıkarım |
|---|---|
| %30 daha az araç çağrısı | Karmaşıklık keşiften rehberliğe taşındı |
| %25 daha az israf edilen token | Ağdan önce hatalar yakalandı |
| %40 daha az yapısal yeniden deneme | Doğrulama kapısı çalışıyor |
| %21 daha az atlama hatası | agentHints kör devamı önler |
CLI + YETENEK sadece mimari zarafet değil. Ölçülebilir verimliliktir.
Sırada Ne Var
Yaklaşımı sayılarla doğruladığımıza göre, şimdi onu eylemde görelim.
Bölüm 7'de, PRD'den Test Döngüsüne: Eksiksiz Bir Temsilci İş Akışı, gerçek bir örneği inceleyeceğiz—bir ekibin "Sipariş İadesi" PRD'si var ve Temsilci, OpenAPI oluşturmak, testler oluşturmak, doğrulamak ve onaylamak için CLI + YETENEK kullanıyor.
Temel Çıkarımlar
- Araç çağırma adımları yaklaşık %30 azaldı
- Açıklamalardan ve yeniden denemelerden kaynaklanan token israfı yaklaşık %25 azaldı
- Yapısal hata yeniden denemeleri yaklaşık %40 azaldı
- Geri okumayı atlamadan kaynaklanan atlama hataları yaklaşık %21 azaldı
- Tasarruflar şunlardan kaynaklanır: rehberli keşif, yerel doğrulama, eyleme geçirilebilir ipuçları
- Karmaşıklık bağlamdan mühendislik sistemine taşındı
Apidog'u tek bir çalışma alanında API'ları tasarlamak, taklit etmek, test etmek ve belgelemek için indirin. Komut satırı API testi, CI otomasyonu ve Yapay Zeka Temsilcisi iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.