Cara Menggunakan Apidog CLI di DeepSeek Harness

DeepSeek Harness bekerja dalam sebuah siklus: agen membaca workspace, mengedit file, menjalankan perintah melalui tool bash, lalu menentukan langkah berikutnya berdasarkan output. Namun, tes API sering berada di luar siklus tersebut—tersimpan di Apidog di balik GUI dan hanya dijalankan ketika seseorang mengklik tombol. Dengan Apidog CLI, agen dapat menjalankan skenario API langsung dari terminal, membaca exit code, lalu memperbaiki kode berdasarkan hasil tes.

Coba Apidog hari ini

Perbaikannya cukup berupa satu blok konfigurasi. Apidog CLI adalah paket npm apidog-cli yang menjalankan skenario tes yang dibuat di Apidog langsung dari terminal. Setelah CLI terinstal dan DeepSeek Harness mengetahuinya, agen dapat menjalankan skenario Apidog seperti menjalankan tes unit:

1. Jalankan perintah.
2. Baca exit code.
3. Jika gagal, baca laporan.
4. Perbaiki kode.
5. Jalankan tes kembali.

Pendekatan ini juga menghemat konteks. Agen tidak perlu membaca ulang seluruh handler dan menebak apakah API masih bekerja. Satu perintah CLI mengembalikan hasil deterministik dalam beberapa baris. Agen dapat menggunakan konteksnya untuk memperbaiki kode, bukan untuk melakukan verifikasi manual.

Panduan ini membahas bagian yang spesifik untuk DeepSeek Harness:

• File instruksi yang dibaca oleh harness.
• Cara tool bash mengeksekusi apidog run.
• Cara menyimpan ID skenario dan lingkungan.
• Cara membaca exit code serta laporan.
• Cara memverifikasi bahwa agen benar-benar menjalankan tes.

Jika CLI belum terinstal, ikuti Cara menginstal Apidog CLI dengan agen pengkodean AI. Panduan tersebut mencakup instalasi npm, autentikasi, dan eksekusi pertama. Artikel ini mengasumsikan apidog --version menampilkan versi dan mesin Anda sudah terautentikasi.

DeepSeek Harness yang Digunakan

DeepSeek Harness, yang dijalankan melalui perintah dsh, adalah harness agen sumber terbuka yang dirilis DeepSeek pada 13 Agustus 2026, bersama V4-Pro pada API. Proyek ini berlisensi MIT dan tersedia di github.com/deepseek-ai/deepseek-harness. Pada 20 Agustus, repositori tersebut telah melampaui 169 ribu bintang.

Anda dapat memulainya dengan:

npx @deepseek-ai/dsh web

Perintah tersebut menyajikan UI web lokal di http://127.0.0.1:3080. Pilih workspace, yaitu direktori proyek tempat perintah dijalankan. Agen kemudian bekerja di dalam workspace tersebut dengan membaca dan mengedit file, menjalankan perintah, serta meminta persetujuan untuk operasi yang dibatasi oleh kebijakan izin aktif.

Ada dua hal penting sebelum mengikuti konfigurasi ini:

1. DeepSeek Harness masih merupakan pratinjau pengembang. README memperingatkan bahwa perubahan yang merusak kompatibilitas dapat terjadi. Anggap nama file dan kunci konfigurasi di bawah ini berlaku untuk akhir Agustus 2026, lalu periksa kembali dokumentasi repositori jika konfigurasi tidak bekerja.
2. Fitur harness dibangun sebagai plugin. Arsitektur Cordis membuat penting untuk mengetahui plugin mana yang membaca aturan proyek dan file apa yang dicarinya.

Untuk gambaran lebih luas, baca apa itu DeepSeek Harness dan DeepSeek Harness vs Claude Code.

Langkah 1: Tambahkan Perintah CLI ke AGENTS.md

DeepSeek Harness membaca instruksi workspace melalui plugin @deepseek-ai/dsh-agent-instructions. Berdasarkan sumber plugin dan katalog konfigurasi, pemuat instruksi:

• Berjalan dari direktori kerja sesi ke atas hingga root proyek yang ditandai .git.
• Membaca AGENTS.md di setiap direktori yang dilewati.
• Menggunakan CLAUDE.md sebagai fallback.
• Memuat AGENTS.local.md atau CLAUDE.local.md setelah file dasar.
• Membaca AGENTS.md global pengguna dari $DSH_HOME, yang secara default adalah ~/.dsh.
• Mengabaikan file yang berukuran lebih dari 1 MiB.

Buat atau tambahkan blok berikut ke AGENTS.md di root repositori:

## Pengujian API dengan Apidog CLI

- Untuk menguji API, jalankan skenario Apidog. Jangan mengklik melalui GUI.
- Perintah: apidog run -t <scenario_id> -e <env_id> -r cli
- Exit code 0 berarti semua assertion lulus.
- Exit code selain 0 berarti tes gagal. Baca laporan dan perbaiki kode.
- Mesin sudah terautentikasi. Jangan menambahkan flag --access-token.
- Jangan menyimpan token di file ini.

File aturan lebih dapat diandalkan daripada instruksi yang hanya dikirim melalui chat. ID skenario yang diberikan di komposer sesi akan hilang setelah sesi berakhir. Sebaliknya, AGENTS.md dimuat pada setiap sesi baru dan dapat dibagikan bersama repositori.

Jika Anda menggunakan beberapa proyek, ~/.dsh/AGENTS.md dapat berisi aturan umum, misalnya:

- Selalu verifikasi perubahan API dengan perintah apidog run proyek.

Simpan ID skenario dan lingkungan yang sebenarnya di AGENTS.md masing-masing proyek.

Langkah 2: Salin Perintah dari Apidog

Anda tidak perlu menebak ID skenario atau lingkungan.

1. Buka skenario tes di Apidog.
2. Buka tab CI/CD.
3. Salin perintah yang dihasilkan.
4. Tempelkan perintah tersebut ke AGENTS.md.

Contoh:

apidog run -t 123456 -e 789012 -r cli

Keterangan flag:

• -t adalah ID skenario tes.
• -e adalah ID lingkungan.
• -r cli memilih reporter CLI yang menampilkan hasil secara inline.

Gunakan ID yang dihasilkan Apidog, bukan ID yang diketik secara manual:

## Pengujian API checkout

- Jalankan:
  apidog run -t 123456 -e 789012 -r cli
- Exit code 0 berarti semua assertion lulus.
- Jika gagal, baca assertion yang gagal sebelum mengubah kode.

Langkah 3: Minta Agen Menjalankan Tes

Mulai sesi di UI web dsh dan pilih workspace proyek. Karena AGENTS.md sudah dimuat ke konteks agen, agen seharusnya mengetahui perintah CLI.

Anda dapat meminta:

Jalankan skenario tes Apidog dan beri tahu saya exit code-nya.

Agen akan menjalankan perintah melalui tool bash. Pahami perilaku tool tersebut agar debugging lebih mudah.

Menurut katalog tool, tool bash default:

• Menjalankan setiap perintah dalam fresh shell.
• Tidak mempertahankan direktori kerja, variabel, atau fungsi antar-panggilan.
• Menjalankan perintah dari workspace sesi, kecuali workdir diberikan.

Perilaku ini tidak bermasalah untuk apidog run karena perintah tersebut biasanya berdiri sendiri. Namun, perintah berikut tidak akan bekerja seperti yang diharapkan:

cd api

Lalu pada pemanggilan berikutnya:

apidog run -t 123456 -e 789012 -r cli

cd tidak bertahan di antara dua pemanggilan. Jika tes harus dijalankan dari subdirektori, gunakan pemanggilan lengkap dalam satu baris:

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

Atau teruskan workdir jika konfigurasi tool Anda mendukungnya.

Exit Code dan Sandbox

Exit code bukan nol akan dikembalikan sebagai penanda eksplisit:

[exit code: N]

Penanda ini tetap berguna ketika output yang panjang dipotong di bagian akhir. Agen masih dapat membedakan tes lulus dan gagal.

Perintah juga dapat berjalan di bawah sandbox file. Operasi yang diblokir akan dilaporkan sebagai penolakan kebijakan, bukan sebagai kegagalan perintah. Skenario read-only jarang memicu masalah ini, tetapi reporter HTML yang menulis ke ./apidog-reports dapat terpengaruh, tergantung kebijakan aktif.

Persetujuan Eksekusi

Apakah eksekusi memerlukan persetujuan bergantung pada kebijakan izin aktif. UI web akan meminta persetujuan untuk operasi yang dibatasi, sesuai panduan pengguna.

Jika diminta menjalankan apidog run terhadap staging, tinjau perintahnya lalu setujui sesuai kebijakan deployment Anda.

Langkah 4: Baca Laporan Tes

Dengan reporter cli, agen mendapatkan hasil inline yang berisi:

• Setiap request.
• Setiap assertion.
• Assertion yang gagal.
• Nilai yang diharapkan.
• Nilai aktual.
• Kode status atau field yang bermasalah.

Contoh perintah dengan reporter CLI dan HTML:

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

Reporter html menulis laporan mandiri ke:

./apidog-reports

Pertahankan cli dalam daftar reporter agar agen tetap dapat membaca hasil tes langsung dari output terminal.

Siklus Edit–Tes–Perbaiki

Misalnya agen sedang mengubah handler checkout. Tanpa integrasi CLI, siklusnya mungkin berhenti pada kesimpulan bahwa kode terlihat benar.

Dengan konfigurasi di AGENTS.md, siklusnya menjadi:

1. Agen mengubah handler.
2. Agen menjalankan:

   apidog run -t 123456 -e 789012 -r cli

1. Agen membaca output.
2. Jika exit code 0, agen melanjutkan.
3. Jika exit code 1, agen membaca assertion yang gagal.
4. Agen memperbaiki handler.
5. Agen menjalankan skenario kembali.

Contoh masalah yang dapat ditemukan dari laporan:

• API mengembalikan 500, padahal yang diharapkan 200.
• Field total tidak ada.
• Kode mata uang memiliki nilai yang salah.

Dengan cara ini, pemeriksaan kontrak API menjadi bagian dari siklus edit–tes–perbaiki yang sama seperti tes unit.

Agen tidak perlu membaca ulang setiap file route untuk meyakinkan dirinya bahwa API bekerja. Skenario Apidog sudah mendefinisikan perilaku yang diharapkan. Agen dapat mendelegasikan verifikasi ke tool deterministik dan menggunakan konteksnya untuk memperbaiki implementasi.

Pembagian tanggung jawabnya:

• DeepSeek Harness menulis atau mengubah kode.
• Apidog CLI memverifikasi lapisan API.
• Anda membuat dan memelihara skenario tes secara visual di Apidog.

Verifikasi bahwa dsh Benar-benar Menjalankan Tes

Agen dapat melaporkan keberhasilan tanpa benar-benar menjalankan perintah. Karena DeepSeek Harness masih merupakan pratinjau pengembang, verifikasi hasilnya secara langsung.

1. Pastikan Perintah Dipanggil

UI web dsh menampilkan pemanggilan tool dan outputnya dalam sesi. Cari pemanggilan bash literal seperti:

apidog run -t 123456 -e 789012 -r cli

Jika agen mengklaim telah menjalankan tes tetapi tidak ada pemanggilan tersebut, minta agen menjalankannya kembali dan menampilkan output mentah.

2. Periksa Exit Code

Tanyakan secara langsung:

Berapa exit code dari perintah apidog run tersebut?

Saat terjadi kegagalan, harness menampilkan penanda seperti:

[exit code: 1]

Jika ringkasan agen mengatakan “tes lulus” tetapi exit code bukan nol, percayai exit code dan laporan, bukan ringkasannya.

3. Validasi ID Skenario

Pesan seperti “skenario tidak ditemukan” biasanya berarti ID yang digunakan salah.

Bandingkan:

• Nilai -t di AGENTS.md.
• Nilai -e di AGENTS.md.
• Perintah yang disalin dari tab CI/CD Apidog.

Perintah yang dihasilkan Apidog dan ID yang tersimpan di file aturan adalah sumber kebenaran. Nilai yang diketik agen harus diverifikasi.

Opsional: Tambahkan Apidog MCP Server untuk Akses Spesifikasi

Apidog CLI cocok untuk menjalankan verifikasi. Jika Anda ingin agen membaca spesifikasi API saat menulis kode, gunakan MCP.

Pada akhir Agustus 2026, dukungan MCP tidak didokumentasikan di README inti DeepSeek Harness atau panduan pengguna. Yang tersedia adalah plugin komunitas hyqhyq3/dsh-mcp-manager, yang ditemukan melalui topik GitHub dsh-plugin.

Plugin tersebut:

• Menambahkan halaman MCP di Pengaturan.
• Mendukung server HTTP jarak jauh dan stdio lokal.
• Mendaftarkan tool dengan format mcp__<name>__*.
• Membaca konfigurasi server per proyek dari:

  <workspace>/.dsh/dshmm/mcp.json

Melalui plugin ini, Anda dapat menghubungkan Apidog MCP server. Agen kemudian dapat memeriksa skema endpoint sebelum menulis handler, bukan hanya setelah skenario tes gagal.

Namun, kombinasi plugin komunitas dan host pratinjau pengembang dapat berubah atau rusak setelah pembaruan. Perlakukan MCP sebagai lapisan tambahan. Integrasi CLI tetap menjadi jalur utama karena hanya memerlukan shell.

Peringatan Pratinjau dan Arah Pengembangan

DeepSeek Harness bergerak cepat dan memperingatkan bahwa perubahan yang merusak kompatibilitas dapat terjadi. Bagian yang paling mungkin berubah meliputi:

• Kandidat file plugin instruksi.
• Pelaporan sandbox tool bash.
• Integrasi plugin MCP komunitas.

Meski begitu, polanya bersifat portabel:

1. Simpan aturan verifikasi di file instruksi proyek.
2. Jalankan satu perintah CLI yang deterministik.
3. Gunakan exit code sebagai sinyal lulus atau gagal.
4. Baca laporan untuk menentukan perbaikan.
5. Jalankan tes kembali.

Pola ini bekerja di dsh dengan alasan yang sama seperti pada Claude Code dan harness lainnya: agen dapat membaca output perintah, tetapi tidak seharusnya dipercaya tanpa bukti eksekusi.

Untuk memulai:

1. Unduh Apidog.
2. Buat satu skenario tes secara visual.
3. Salin perintah apidog run dari tab CI/CD.
4. Tambahkan perintah tersebut ke AGENTS.md.
5. Minta DeepSeek Harness menjalankannya setelah perubahan API.

Dengan begitu, agen memeriksa pekerjaannya sendiri sebelum menyatakan tugas selesai.

Pertanyaan Umum (FAQ)

Apakah DeepSeek Harness membaca AGENTS.md secara native?

Ya. Plugin @deepseek-ai/dsh-agent-instructions memuat AGENTS.md, atau CLAUDE.md sebagai fallback, dari root proyek dan direktori di atas workspace sesi. Plugin tersebut juga mendukung overlay AGENTS.local.md atau CLAUDE.local.md, serta AGENTS.md global pengguna di ~/.dsh.

Jika Anda sudah memiliki AGENTS.md untuk agen lain, dsh dapat membacanya tanpa perubahan tambahan.

Apakah saya memerlukan paket DeepSeek berbayar untuk menggunakan Apidog CLI di dsh?

Tidak. DeepSeek Harness adalah proyek sumber terbuka berlisensi MIT dan menggunakan model dari penyedia yang Anda konfigurasi. Katalog penyedianya mencakup Anthropic, OpenAI, Bedrock, Vertex, dan Azure. Gateway kustom dapat digunakan melalui settings.yaml, seperti dijelaskan dalam cara menjalankan model apa pun di DeepSeek Harness.

Apidog CLI adalah paket npm gratis. Yang dibutuhkan adalah skenario tes Apidog dan autentikasi, bukan model tertentu.

Mengapa perintah kedua melupakan direktori yang diubah oleh perintah pertama?

Itu adalah perilaku yang diharapkan. Tool bash dsh menjalankan setiap panggilan dalam fresh shell, sehingga cd tidak bertahan antar-perintah.

Gunakan workdir, atau gabungkan perintah dalam satu baris:

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

Bisakah dsh menjalankan skenario tanpa meminta persetujuan setiap saat?

Tergantung pada kebijakan izin aktif. UI web akan meminta persetujuan sebelum operasi yang memerlukannya. Panduan pengguna tidak mencantumkan semua tingkat kebijakan, jadi periksa Pengaturan pada build yang Anda gunakan.

Jika prompt muncul, tinjau perintah dan kebijakan deployment sebelum menyetujui eksekusi apidog run terhadap staging.