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ırayla okuyun veya ilginizi çeken herhangi bir gönderiye atlayın:
| Başlık | Odak | |
|---|---|---|
| 1 | 126 MCP Aracı Geliştirdik. Ama Ajan için En İyi Çözüm Bu Değil | Sorun tespiti |
| 2 | Neden Yepyeni Apidog CLI Geliştirdik | Mimari geliştirme |
| 3 | Altın Kural: CLI Gerçekleri Üretir, Model Gerçekler Üzerinde Hareket Eder | Çekirdek felsefe |
| 4 | agentHints: CLI'lara Ajanlarla Konuşmayı Öğretmek |
Yapılandırılmış çıktı |
| 5 | SKILL: Operasyonel Deneyimi Kod Olarak Göndermek | 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 Ajan İş Akışı | Pratik eğitim |
| 8 | Ajan Araçları için CI/CD Uyumluluğu Neden Vazgeçilmezdir? | DevOps perspektifi |
| 9 | Yapay Zeka Dalı: Yapay Zeka Ajanları ile Daha Güvenli Proje Değişiklikleri | Güvenlik katmanı |
| 10 | Önce Şartname Dündü. Yetenek Odaklı Yaklaşıma Hoş Geldiniz. | Vizyon ve gelecek |
Bir SKILL sadece bir komut referansı değildir. Bu, Yapay Zeka Ajanları için bir işletim kılavuzudur: bir komutun ne zaman kullanılacağı, hangisinin önce geleceği, hangi alanların tahmin edilmemesi gerektiği, ne zaman doğrulanacağı, ne zaman geri okunacağı.
Yalnızca CLI Yeterli Değil
CLI komutları bir Ajana yürütme gücü verir.
Ancak muhakeme olmaksızın güç, sorunlara yol açar:
| CLI Gücü | Muhakeme Olmadan Risk |
|---|---|
| Test durumu oluşturma | Yanlış projede oluşturur |
| Test senaryosunu güncelleme | Geri okumadan günceller |
| Adımları içe aktarma | Mevcut yapıyı kontrol etmeden içe aktarır |
| Testleri çalıştırma | Değişiklikleri doğrulamadan çalıştırır |
Ajanlar komutlardan fazlasına ihtiyaç duyar. İşletim muhakemesine ihtiyaç duyarlar.
SKILL Nedir?
Bir SKILL, Yapay Zeka Ajanları için yazılmış bir işletim kılavuzudur.
Bu, aşağıdakilerden biri değildir:
- Basit bir komut listesi
- Bir referans kılavuzu
- Bir yardım sayfası
Bu, aşağıdakidir:
| SKILL İçeriği | Amaç |
|---|---|
| Bir komutun ne zaman kullanılacağı | Görev türü → komut eşlemesi |
| Hangi komutun önce geleceği | Sıra rehberliği |
| Hangi alanların tahmin edilmemesi gerektiği | Güvenlik sınırları |
| Ne zaman doğrulanacağı | Kalite kapısı yerleşimi |
| Ne zaman geri okunacağı | Doğrulama zamanlaması |
| Testlerin ne zaman çalıştırılacağı | Onay iş akışı |
SKILL, Ajanlara işletim muhakemesi verir.
Kurulum
SKILL, Apidog CLI'ın bir eşlikçisidir:
# Yapay Zeka Ajanınız için SKILL'i yükleyin
apidog skill installBu, Ajanların aşağıdakileri anlamasına yardımcı olan 8 eşlikçi SKILL yükler:
- CLI komut semantiği
- Kaynak yapıları
- Görev iş akışları
- Hata yönetimi
- Doğrulama kalıpları
SKILL Neden Önemlidir: Gizli İş Akışları
Ajanın hala görevlerin işler arası yürütme akışlarına nasıl ayrılması gerektiğini bilmesi gerekir.
Bu deneyim aşağıdakilerden biri olamaz:
- Araç açıklamalarına kapsamlı bir şekilde yazılmış (çok fazla bağlam tüketirdi)
- Sohbet bağlamına dağıtılmış (oturumlar arasında kaybolurdu)
- Model tarafından ezberlenmiş (ürüne özgü, genel bilgi değil)
Gizli iş akışları ve "iş tuzakları" açık rehberlik gerektirir.
Örnek: Test Senaryosu Bakımı
Karmaşık bir test senaryosunun bakımını düşünün.
Yanlış yaklaşım (Ajan sıfırdan el ile yazar):
Ajan: "Test senaryosu yapısını manuel olarak oluşturacağım"
Ajan: Onaylar, çıkarıcılar, işlemcilerle eksiksiz adımlar dizisi yazar
Sonuç: Alan hataları, yanlış karşılaştırıcılar, eksik gerekli alanlar
CLI: Yazmayı reddeder veya eksik senaryo oluştururDoğru yaklaşım (SKILL'de kodlanmıştır):
| Adım | Neden |
|---|---|
| 1. Mevcut adımları uç noktalardan veya test durumlarından içe aktarın | Karmaşık yapıları el ile yazmayın |
| 2. Eksiksiz yapıyı geri okuyun | Gerçek içe aktarılmış biçimi görün |
| 3. Yerel değişiklikler yapın | Doğru tabanla çalışın |
| 4. Güncellemeden önce doğrulayın | Hataları yerel olarak yakalayın |
| 5. Senaryoyu çalıştırın | Davranışı doğrulayın |
SKILL sadece "test-scenario update komutu var" demez.
Şunu söyler:
"Karmaşık senaryolar, sıfırdan eksiksiz yapıları el ile yazmak için uygun değildir. Daha istikrarlı bir yol, önce mevcut uç nokta veya durum adımlarını içe aktarmak, ardından eksiksiz yapıyı geri okumak ve son olarak yerel değişiklikler yapmaktır."
SKILL Rehberliğinin Arkasındaki Komutlar
İşte SKILL'in Ajanları kullanmaya yönlendirdiği gerçek komutlar:
# Adım 1: Uç noktalardan adımları içe aktarın
apidog test-scenario import-steps <senaryoKimliği> --project <projeKimliği> \
--source endpoint --ids <uçNoktaKimlikleri> --sync manual
# Adım 2: Tam ayrıntıyla geri okuyun
apidog test-scenario get <senaryoKimliği> --project <projeKimliği> \
--with-case-detail
# Adım 3: Belirli kısımları güncelleyin (Ajan JSON güncellemesini oluşturur)
# Adım 4: Güncellemeden önce doğrulayın
apidog cli-schema validate test-scenario-update --file ./senaryo-güncellemesi.json
# Adım 5: Güncellemeyi yürütün
apidog test-scenario update <senaryoKimliği> --project <projeKimliği> \
--file ./senaryo-güncellemesi.json
# Adım 6: Doğrulamayı çalıştırın
apidog run --project <projeKimliği> --test-scenario <senaryoKimliği>SKILL, Ajana her komutu ne zaman kullanacağını ve nedenini söyler.
Anahtar İçgörü: get--with-case-detail
SKILL şunları vurgular:
"Gerçek yapıyı elde etmek için get--with-case-detail kullanın, adımların içindeki durumu hayal etmeyin."Bu neden önemlidir:
get--with-case-detail Olmadan |
get--with-case-detail İle |
|---|---|
| Adımlar yalnızca kimlikleri gösterir | Adımlar tam durum yapılarını gösterir |
| Ajan dahili biçimi bilmez | Ajan gerçek onay/çıkarıcı biçimini görür |
| Ajan alan adlarını tahmin eder | Ajan gerçek örneklerden çalışır |
Gerçek yapıyı elde etmek, hayal gücüne dayalı güncellemeleri önler.
Geliştirilebilirlik: SKILL Değişebilir
Apidog SKILL, geliştirilebilir ve sürümlenebilir bir operasyonel deneyimdir.
Bu Neden Önemli
| Zorluk | SKILL Çözümü |
|---|---|
| CLI komutları değişir | SKILL eşleşecek şekilde güncellenebilir |
| Kullanıcıların kişiselleştirilmiş iş akışları vardır | SKILL özelleştirilebilir |
| Yeni ürün özellikleri | SKILL genişletilebilir |
| İş akışı iyileştirmeleri | SKILL geliştirilebilir |
Nasıl Çalışır
Ajanlara SKILL üzerinde yazma izinleri verilir.
SKILL geride kalırsa veya kullanımı zorlaşırsa:
- Ajan onu değiştirebilir
- Ajan iyileştirmeler önerebilir
- SKILL kullanım yoluyla gelişir
SKILL dondurulmuş bir dokümantasyon değildir. Yaşayan bir operasyonel koddur.
Uyumluluk Katmanı
Bunu gerçek hatalardan öğrendik:
Tespit edilen sorun:
Bazı senaryo adımlarında, ikincil güncellemeler sırasında, dış adımlar başarıyla güncellendi, ancak dahili HTTP durumları doğru şekilde güncellenmedi.
Temel neden:
- Dahili durum güncelleme işaretçileri özel işlem gerektiriyordu
- Ajanlar bu işaretçileri bilmiyordu
- Ürün semantiği belirli bayraklar gerektiriyordu
Çözüm:
- Uyumluluk mantığı CLI'ya yerleştirildi
- CLI dahili işaretçileri otomatik olarak işler
- Kullanıcıların ve Ajanların dahili ayrıntıları bilmesine gerek yok
Kısıtlamanın anlamı SKILL'e katmanlandırılmıştır:
SKILL, Ajana doğru komutları kullanmasını söyler. CLI, bu komutların arkasındaki ürün semantiğini işler. Ajanın dahili işaretçileri anlamasına gerek yoktur.
İsteğe Bağlı Yükleme
SKILL, cli-schema ile aynı prensibi takip eder:
Karmaşıklık, modele tamamen açılmak yerine yürütme ve dokümantasyon tarafından absorbe edilmelidir.
| Alternatif | Sorun |
|---|---|
| Tüm SKILL'i bağlama yükleyin | Token yükü |
Tüm kuralları --help'e koyun |
Dikkat için rekabet eder |
| İstem içine yazın | Güncellenemez |
SKILL yaklaşımı:
- Ajan SKILL'i isteğe bağlı olarak hazırlar
- SKILL, görev türü tanımlandığında yüklenir
- Yalnızca ilgili iş akışı rehberliği bağlama girer
SKILL vs. Dokümantasyon
| Dokümantasyon | SKILL |
|---|---|
| İnsanların okuması için | Ajanların yürütmesi için |
| Komutların ne yaptığını açıklar | Onların ne zaman kullanılacağını açıklar |
| Statik referans | Dinamik iş akışı |
| Kapsamlı | Görev odaklı |
| Ajandan harici | Ajan ile entegre |
8 Eşlikçi SKILL
Apidog 8 eşlikçi SKILL sağlar:
| SKILL | Kapsam |
|---|---|
| Proje yönetimi | Projeler, meta veriler, kaynaklar |
| API tasarımı | Uç noktalar, şemalar, tanımlar |
| Ortam yönetimi | Ortamlar, değişkenler |
| Test durumu oluşturma | Tek uç nokta testleri, onaylar |
| Test senaryosu yönetimi | Çok adımlı testler, içe aktarma, güncelleme |
| Test paketi organizasyonu | Gruplama, yürütme |
| İçe/dışa aktarma iş akışları | Veri taşıma, yedekleme |
| CI/CD entegrasyonu | Pipeline komutları, raporlar |
Her SKILL şunları içerir:
- Görev türü tanımlaması
- Komut dizisi rehberliği
- Alan güvenlik sınırları
- Doğrulama kontrol noktaları
- Doğrulama kalıpları
Sırada Ne Var
Artık tüm üç temel bileşeni oluşturduğumuza göre:
- cli-schema validate — Kalite kapısı
- agentHints — Sonraki adım navigasyonu
- SKILL — İş akışı muhakemesi
Bir sonraki soru:
Bu gerçekten işe yarıyor mu? Sayılar ne diyor?
6. Bölümde, Sayılar Yalan Söylemez: %30 Daha Az Araç Çağrısı, %25 Daha Az Token, dahili karşılaştırmalarımızdan elde ettiğimiz nicel sonuçları paylaşacağız ve tasarrufların nereden geldiğini açıklayacağız.
Temel Çıkarımlar
- CLI yürütme gücü verir; SKILL işletim muhakemesi verir
- SKILL bir işletim kılavuzudur, komut referansı değil
- Gizli iş akışları açık rehberlik gerektirir
- Adımları içe aktarma → geri okuma → yerel olarak güncelleme, el ile yazmaktan daha güvenlidir
--with-case-detail, hayal gücüne dayalı güncellemeleri önler- SKILL geliştirilebilirdir—Ajanlar onu değiştirebilir
- CLI ürün semantiğini absorbe eder, SKILL iş akışını yönlendirir
- İsteğe bağlı yükleme, bağlam yükünü önler
Tek bir çalışma alanında API'ları tasarlamak, taklit etmek, test etmek ve belgelemek için Apidog'u indirin. Komut satırı API testi, CI otomasyonu ve Yapay Zeka Ajanı iş akışları için Apidog CLI hakkında daha fazla bilgi edinin.