Aturan Emas: CLI Menghasilkan Fakta, Model Bertindak Berdasarkan Fakta

Ini adalah seri 10 bagian yang membagikan bagaimana Apidog mengembangkan Apidog CLI, alat baris perintah untuk pengujian API dan manajemen siklus hidup API. Bacalah secara berurutan atau lompat ke postingan mana pun yang menarik minat Anda:

Jangan membuat model menghafal semua aturan—biarkan aturan dieksekusi di tempat yang tepat. cli-schema validate mengubah Skema dari pengetahuan menjadi gerbang kualitas.

Prinsip Inti: Biarkan Aturan Dieksekusi di Tempat yang Tepat.

Kami menyaring satu prinsip inti dari pengalaman kami:

Jangan membuat model menghafal semua aturan. Biarkan aturan dieksekusi di tempat yang tepat.

Ini mirip dengan pelajaran dari evaluasi Agen:

Di Apidog CLI + SKILL:

Biarkan CLI memvalidasi struktur. Biarkan Agen menghasilkan konten.

Masalah dengan Memori Model

Ketika Agen AI membantu membuat atau memperbarui sumber daya Apidog, bagian yang berisiko bukan hanya menghasilkan konten.

Bagian yang berisiko adalah menulis konten yang dihasilkan ke dalam proyek nyata tanpa struktur atau verifikasi yang cukup.

Sumber daya Apidog terstruktur. Pertimbangkan apa yang termasuk dalam kasus uji atau skenario uji:

Jika Agen menebak strukturnya:

• Nama bidang yang salah → Penulisan gagal
• Nilai enum tidak valid → Penolakan server
• Bidang wajib yang hilang → Sumber daya tidak lengkap
• Tipe yang salah → Masalah tampilan UI
• Penestingan yang salah → Pengujian tidak berjalan sesuai harapan

cli-schema validate: Gerbang Kualitas

Perwujudan paling langsung dari prinsip kami adalah cli-schema validate.

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

Ketika Agen ingin menulis atau memperbarui skenario uji, membiarkan AI menghasilkan struktur langkah yang kompleks sangat rawan kesalahan.

Perintah validate:

• Mengkonfirmasi nama bidang
• Memeriksa validitas struktural
• Memverifikasi efektivitas nilai enum
• Memvalidasi batasan tipe

Semua sebelum memulai permintaan penulisan.

Kesalahan Umum yang Ditangkap cli-schema

Berikut adalah contoh nyata kesalahan yang sering dibuat Agen—dan yang ditangkap oleh cli-schema validate:

Ini bukan teoritis. Kami menemukannya melalui interaksi Agen yang nyata.

Setiap kesalahan akan menyebabkan:

• Permintaan penulisan yang gagal
• Respons kesalahan API
• Kebingungan Agen tentang apa yang salah
• Beberapa upaya percobaan ulang
• Pemborosan token pada panggilan berulang

Dengan cli-schema validate, kesalahan ini ditangkap secara lokal, sebelum panggilan jaringan.

Filosofi Desain

Mari kita pertimbangkan alternatifnya:

Alternatif 1: Menulis Aturan ke dalam Prompt

Jika kita menulis semua aturan bidang ke dalam prompt Agen:

• Setiap nama bidang didokumentasikan
• Setiap nilai enum tercantum
• Setiap batasan tipe dijelaskan
• Setiap struktur bertingkat dijelaskan

Hasil: Beban konteks yang masif.

Skema skenario uji yang komprehensif dapat dengan mudah membutuhkan 5.000+ token deskripsi. Itu adalah konteks yang harus dibawa model untuk setiap tugas, bahkan ketika sebagian besar aturan tidak relevan.

Alternatif 2: Mengandalkan Memori Model

Jika kita mengandalkan model untuk "mengetahui" struktur yang benar:

• Model dilatih pada beberapa pola API
• Tetapi tidak secara spesifik pada skema Apidog
• Nama bidang bervariasi antar produk
• Nilai enum spesifik produk

Hasil: Tingkat kesalahan tinggi.

Model tidak memiliki memori yang sempurna tentang konvensi khusus Apidog. Ia akan menebak—dan tebakan akan salah.

Pendekatan yang Lebih Baik: Validasi Secara Lokal

Biarkan Agen menghasilkan draf. Biarkan CLI mengeksekusi validasi sebelum menulis.

# Agen menghasilkan JSON
# (Agen tidak perlu menghafal semua aturan)

# CLI memvalidasi
apidog cli-schema validate test-case-create --file ./test-case-create.json

# CLI menampilkan kesalahan spesifik jika ada
# Agen menyesuaikan berdasarkan kesalahan

# Hanya penulisan yang valid yang dilanjutkan
apidog test-case create --project <projectId> --file ./test-case-create.json

Transformasi Skema

cli-schema validate mengubah arti Skema:

Masalah tidak dikonsumsi dalam permintaan jaringan bolak-balik yang tidak berarti.

Pemeriksaan kualitas diselesaikan melalui perintah lokal.

Contoh Praktis

Mari kita telusuri alur kerja nyata:

# Agen membaca endpoint
apidog endpoint get <endpointId> --project <projectId>

# Agen menghasilkan JSON kasus uji
# (Membuat ./test-case-create.json)

# Validasi sebelum menulis
apidog cli-schema validate test-case-create --file ./test-case-create.json

Jika validasi berhasil:

apidog test-case create --project <projectId> --file ./test-case-create.json

Jika validasi gagal:

Error: Field "assertions[0].comparator" has invalid value "contains"
Valid values: equal, not_equal, greater, less, include, not_include, exists, not_exists

Error: Field "extractors[0].type" has invalid value "global"
Valid values: globals, environment, collection, local

Suggestion: Fix these fields and re-validate before writing.

Agen:

1. Membaca kesalahan spesifik
2. Memahami dengan tepat apa yang salah
3. Menyesuaikan file JSON
4. Menjalankan ulang validasi
5. Melanjutkan hanya jika valid

Tidak ada penulisan yang gagal. Tidak ada percobaan ulang yang membingungkan. Tidak ada token yang terbuang.

Pelajaran yang Lebih Luas

Prinsip ini meluas melampaui validasi.

Aturan deterministik → Sistem rekayasa

Penilaian semantik → Agen

Apa Selanjutnya

Sekarang setelah kita menetapkan prinsip validasi, pertanyaan selanjutnya adalah:

Setelah validasi, bagaimana CLI memandu Agen ke langkah selanjutnya?

Di Bagian 4, agentHints: Mengajari CLI untuk Berbicara dengan Agen, kita akan mengeksplorasi bagaimana output terstruktur dengan saran langkah selanjutnya mengubah CLI dari eksekutor perintah menjadi navigator alur kerja.

Poin-Poin Penting

• Prinsip inti: aturan ada di eksekusi, bukan di konteks
• cli-schema validate adalah gerbang kualitas sebelum menulis
• Kesalahan umum: nama bidang yang salah, enum tidak valid, tipe yang salah
• Validasi menangkap kesalahan secara lokal, menghemat bolak-balik jaringan
• Skema bertransformasi dari "pengetahuan yang harus dihafal" menjadi "gerbang yang harus dilewati"
• Aturan deterministik → rekayasa; penilaian semantik → Agen

Unduh Apidog untuk mendesain, membuat mock, menguji, dan mendokumentasikan API dalam satu ruang kerja. Pelajari lebih lanjut tentang Apidog CLI untuk pengujian API baris perintah, otomatisasi CI, dan alur kerja Agen AI.