SKILL: Pengkodean Pengalaman Operasional Logistik

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

SKILL bukan sekadar referensi perintah. Ini adalah panduan operasional untuk Agen AI: kapan menggunakan perintah, mana yang didahulukan, bidang apa yang tidak boleh ditebak, kapan harus memvalidasi, kapan harus membaca kembali.

CLI Saja Tidak Cukup

Perintah CLI memberikan kekuatan eksekusi kepada Agen.

Tetapi kekuatan tanpa penilaian menyebabkan masalah:

Agen membutuhkan lebih dari sekadar perintah. Mereka membutuhkan penilaian operasional.

Apa itu SKILL?

SKILL adalah panduan operasional yang ditulis untuk Agen AI.

Ini bukan:

• Daftar perintah sederhana
• Manual referensi
• Halaman bantuan

Ini adalah:

SKILL memberikan penilaian operasional kepada Agen.

Instalasi

SKILL adalah pelengkap Apidog CLI:

# Instal SKILL untuk Agen AI Anda
apidog skill install

Ini menginstal 8 SKILL pelengkap yang membantu Agen memahami:

• Semantik perintah CLI
• Struktur sumber daya
• Alur kerja tugas
• Penanganan kesalahan
• Pola verifikasi

Mengapa SKILL Penting: Alur Kerja Tersembunyi

Agen masih perlu tahu bagaimana tugas harus didekomposisi menjadi alur eksekusi lintas-bisnis.

Pengalaman ini tidak dapat:

• Ditulis secara komprehensif ke dalam deskripsi alat (akan mengonsumsi terlalu banyak konteks)
• Tersebar dalam konteks obrolan (akan hilang di antara sesi)
• Dihafal oleh model (spesifik produk, bukan pengetahuan umum)

Alur kerja tersembunyi dan "jebakan bisnis" memerlukan panduan eksplisit.

Contoh: Pemeliharaan Skenario Pengujian

Pertimbangkan untuk memelihara skenario pengujian yang kompleks.

Pendekatan yang salah (Agen menulis dari awal secara manual):

Agen: "Saya akan membuat struktur skenario uji secara manual"
Agen: Menulis array langkah lengkap dengan pernyataan, ekstraktor, prosesor
Hasil: Kesalahan bidang, perbandingan yang salah, bidang wajib yang hilang
CLI: Menolak penulisan atau membuat skenario yang tidak lengkap

Pendekatan yang benar (dikodekan dalam SKILL):

SKILL tidak hanya mengatakan "ada perintah test-scenario update."

Ia mengatakan:

"Skenario kompleks tidak cocok untuk menulis struktur lengkap dari awal secara manual. Jalur yang lebih stabil adalah dengan terlebih dahulu mengimpor langkah-langkah titik akhir atau kasus yang ada, kemudian membaca kembali struktur lengkap, dan akhirnya melakukan modifikasi lokal."

Perintah di Balik Panduan SKILL

Berikut adalah perintah aktual yang SKILL pandu Agen untuk digunakan:

# Langkah 1: Impor langkah-langkah dari titik akhir
apidog test-scenario import-steps <scenarioId> --project <projectId> \
  --source endpoint --ids <endpointIds> --sync manual

# Langkah 2: Baca kembali dengan detail lengkap
apidog test-scenario get <scenarioId> --project <projectId> \
  --with-case-detail

# Langkah 3: Perbarui bagian tertentu (Agen menghasilkan JSON pembaruan)

# Langkah 4: Validasi sebelum pembaruan
apidog cli-schema validate test-scenario-update --file ./scenario-update.json

# Langkah 5: Jalankan pembaruan
apidog test-scenario update <scenarioId> --project <projectId> \
  --file ./scenario-update.json

# Langkah 6: Jalankan verifikasi
apidog run --project <projectId> --test-scenario <scenarioId>

SKILL memberi tahu Agen kapan menggunakan setiap perintah dan mengapa.

Wawasan Utama: get--with-case-detail

SKILL menekankan:

"Gunakan get--with-case-detail untuk mendapatkan struktur nyata, bukan membayangkan kasus di dalam langkah-langkah."

Mengapa ini penting:

Mendapatkan struktur nyata mencegah pembaruan berbasis imajinasi.

Evolusioner: SKILL Dapat Berubah

Apidog SKILL adalah pengalaman operasional yang dapat berevolusi dan diberi versi.

Mengapa Ini Penting

Bagaimana Cara Kerjanya

Agen diberikan izin tulis ke SKILL.

Jika SKILL tertinggal atau menjadi sulit digunakan:

• Agen dapat memodifikasinya
• Agen dapat menyarankan peningkatan
• SKILL berevolusi melalui penggunaan

SKILL bukanlah dokumentasi yang beku. Ini adalah kode operasional yang hidup.

Lapisan Kompatibilitas

Kami belajar ini dari bug nyata:

Masalah ditemukan:

Beberapa langkah skenario, selama pembaruan sekunder, memiliki langkah-langkah luar yang berhasil diperbarui, tetapi kasus HTTP internal tidak diperbarui dengan benar.

Penyebab utama:

• Penanda pembaruan kasus internal memerlukan penanganan khusus
• Agen tidak tahu tentang penanda ini
• Semantik produk memerlukan flag tertentu

Solusi:

• Logika kompatibilitas dimasukkan ke dalam CLI
• CLI menangani penanda internal secara otomatis
• Pengguna dan Agen tidak perlu tahu detail internal

Arti batasan dilapisi ke dalam SKILL:

SKILL memberi tahu Agen untuk menggunakan perintah yang tepat. CLI menangani semantik produk di balik perintah-perintah tersebut. Agen tidak perlu memahami penanda internal.

Pemuatan Sesuai Permintaan

SKILL mengikuti prinsip yang sama dengan cli-schema:

Kompleksitas harus diserap oleh eksekusi dan dokumentasi, tidak sepenuhnya diekspos ke model.

Pendekatan SKILL:

• Agen memanaskan SKILL sesuai permintaan
• SKILL dimuat ketika jenis tugas teridentifikasi
• Hanya panduan alur kerja yang relevan yang masuk ke konteks

SKILL vs. Dokumentasi

8 SKILL Pelengkap

Apidog menyediakan 8 SKILL pelengkap:

Setiap SKILL berisi:

• Identifikasi jenis tugas
• Panduan urutan perintah
• Batas keamanan bidang
• Titik pemeriksaan validasi
• Pola verifikasi

Apa Selanjutnya

Sekarang setelah kita menetapkan ketiga komponen inti:

• validasi cli-schema — Gerbang kualitas
• agentHints — Navigasi langkah berikutnya
• SKILL — Penilaian alur kerja

Pertanyaan selanjutnya adalah:

Apakah ini benar-benar berfungsi? Berapa angkanya?

Di Bagian 6, Angka Tidak Bohong: 30% Lebih Sedikit Panggilan Alat, 25% Lebih Sedikit Token, kami akan membagikan hasil kuantitatif dari perbandingan internal kami—dan menjelaskan dari mana penghematan itu berasal.

Poin-Poin Penting

• CLI memberikan kekuatan eksekusi; SKILL memberikan penilaian operasional
• SKILL adalah panduan operasional, bukan referensi perintah
• Alur kerja tersembunyi memerlukan panduan eksplisit
• Impor langkah-langkah → baca kembali → perbarui secara lokal lebih aman daripada menulis manual
• --with-case-detail mencegah pembaruan berbasis imajinasi
• SKILL dapat berevolusi—Agen dapat memodifikasinya
• CLI menyerap semantik produk, SKILL memandu alur kerja
• Pemuatan sesuai permintaan mencegah beban konteks

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.