Semua operasi pengeditan yang dimulai dari Apidog CLI diperlakukan sebagai dimulai oleh AI / AI Agents secara default.AI Branch dirancang untuk menyediakan cabang pengeditan terisolasi bagi AI Agents dalam proyek Apidog. Dengan AI Branch, AI dapat membuat dan memperbarui sumber daya proyek tanpa secara langsung mengubah cabang utama atau cabang sprint standar. Setelah perubahan selesai, pengguna dapat meninjau perbedaan di klien atau CLI, lalu menggabungkan hasilnya ke cabang target secara langsung atau melalui merge request.Mengapa AI Branch Diperlukan#
Pengeditan yang dimulai oleh AI dapat sulit diprediksi, sementara Apidog CLI menyediakan berbagai kemampuan pengeditan yang luas. AI Branch dirancang untuk operasi pengeditan yang dimulai oleh AI dengan risiko lebih tinggi ini, sehingga AI Agents dapat mengedit sumber daya proyek dalam cakupan yang terkendali.Anda juga dapat meningkatkan ke Apidog 2.8.31 atau versi yang lebih baru dan mengaktifkan izin pengeditan langsung untuk cabang utama, cabang sprint standar, dan cabang umum sesuai kebutuhan di Project Settings -> Feature Settings -> External AI Edit Permissions. Setelah diaktifkan, izin ini melewati pembatasan pengeditan langsung yang biasanya mengharuskan penggunaan AI Branch.Apa Itu AI Branch?#
AI Branch adalah cabang sprint khusus. Seperti cabang sprint standar, AI Branch menyimpan perubahan pada sumber daya proyek. Namun, secara default AI Branch ditujukan untuk operasi AI eksternal, seperti pengeditan berbasis CLI, dan mempertahankan langkah konfirmasi manusia sebelum perubahan digabungkan.Karakteristik utama AI Branch mencakup:1.
Pengeditan terisolasi: Perubahan yang dibuat dari CLI pada sumber daya seperti API, dokumentasi, model data, dan skenario pengujian disimpan di AI Branch dan tidak secara langsung memengaruhi cabang utama atau cabang sumber.
2.
Sumber yang jelas: AI Branch tidak dapat dibuat secara langsung di klien Apidog. AI Branch harus dibuat dari sumber CLI atau MCP. AI Branch mencatat cabang sumbernya dan biasanya digabungkan kembali ke cabang sumber tersebut, sehingga lebih mudah memahami konteks perubahan yang dihasilkan AI.
3.
Konfirmasi manusia: Perubahan dalam AI Branch harus dikonfirmasi oleh pengguna sebelum digabungkan. Pengguna dapat meninjau perbedaan, memilih cakupan sumber daya, dan memilih apakah akan menggabungkan secara langsung atau membuat merge request.
4.
Tanpa batas jumlah: Saat ini tidak ada batas aktif pada jumlah AI Branch yang dapat dibuat. AI Agents dapat menggunakannya untuk memproses data berdasarkan domain bisnis, iterasi, atau fitur.
5.
Pengarsipan otomatis: Untuk mencegah pertumbuhan AI Branch yang tidak terkendali selama kolaborasi proyek, setiap AI Branch dibandingkan dengan cabang sumbernya setiap 24 jam. Jika tidak ditemukan perbedaan, cabang tersebut akan diarsipkan secara otomatis. Anda dapat memulihkan AI Branch yang diarsipkan di Apidog kapan saja, atau membuat ulang AI Branch baru dari Apidog CLI, tanpa batas apa pun.
AI Branch digunakan untuk menyimpan hasil penulisan dari operasi AI eksternal atau CLI. Pengeditan normal dalam klien, penggabungan, dan peninjauan oleh pengguna tetap mengikuti izin anggota proyek dan aturan perlindungan cabang.
Kasus Penggunaan#
AI Branch sesuai ketika AI perlu berpartisipasi dalam pemeliharaan sumber daya proyek, sementara isolasi cabang dan konfirmasi manusia tetap harus dipertahankan.| Skenario | Deskripsi |
|---|
| Menghasilkan draf API dari kode | Setelah membaca kode, AI membuat atau memperbarui endpoint HTTP API di AI Branch. Pengguna mengonfirmasi perubahan sebelum penggabungan. |
| Mengatur sumber daya API secara massal | AI dapat menyesuaikan direktori API, menambahkan deskripsi, dan memperbarui model data atau komponen respons tanpa secara langsung memengaruhi cabang kolaborasi saat ini. |
| Menghasilkan draf pengujian otomatis | AI dapat membuat skenario pengujian, kasus pengujian, atau data pengujian di AI Branch untuk kemudian dikonfirmasi oleh penguji. |
| Mengisi kekosongan dalam dokumentasi API | AI dapat melengkapi bidang yang hilang berdasarkan laporan bug, implementasi API, atau file OpenAPI. |
| Penulisan batch dalam CI/CD | Alur kerja otomatis dapat menulis hasil yang dihasilkan ke AI Branch dan menunggu tinjauan pengguna sebelum penggabungan. |
Alur Kerja Dasar#
Alur kerja AI Branch yang umum adalah sebagai berikut:1
Buat AI Branch dan tentukan cabang sumber yang menjadi dasarnya.
2
Impor sumber daya yang perlu diedit ke AI Branch, atau buat sumber daya baru di AI Branch.
3
AI Agent, CLI, atau skrip otomasi memodifikasi sumber daya di AI Branch.
4
Pengguna meninjau perbedaan antara AI Branch dan cabang sumber, lalu mengonfirmasi cakupan sumber daya yang akan digabungkan.
5
Bergantung pada aturan perlindungan cabang target, lakukan penggabungan langsung atau buat merge request.
Membuat AI Branch#
Gunakan branch create --type ai untuk membuat AI Branch. Titik masuk lama sprint-branch dan sb tetap kompatibel, tetapi titik masuk terpadu branch direkomendasikan.| Perintah | Deskripsi | Contoh |
|---|
branch create --type ai | Membuat AI Branch. | apidog branch create --project <projectId> --type ai --name "ai/20260312-from-main-userRegister" --from main |
branch list --type ai | Melihat AI Branch dalam proyek. | apidog branch list --project <projectId> --type ai |
branch list --type all | Melihat semua jenis cabang dalam proyek. | apidog branch list --project <projectId> --type all |
branch get --type ai | Melihat detail AI Branch tertentu, termasuk jenis cabang dan informasi sumbernya. | apidog branch get <branchName> --project <projectId> --type ai |
Contoh: Membuat AI Branch untuk API pendaftaran penggunaKami merekomendasikan penamaan AI Branch dalam format ai/YYYYMMDD-from-sourceBranch-featureOrModule, misalnya, ai/20260312-from-main-userRegister. Nama yang jelas membantu tim memahami sumber cabang, tujuan, dan waktu pembuatannya.
Mengedit Sumber Daya dalam AI Branch#
Ketika CLI menulis sumber daya proyek, Anda dapat menggunakan parameter cabang untuk menulis sumber daya tersebut ke AI Branch. Parameter sedikit berbeda di antara perintah sumber daya. Sebelum digunakan, periksa bantuan perintah terkait dan JSON Schema.| Jenis Sumber Daya | Perintah Umum | Contoh |
|---|
| Endpoint HTTP API | endpoint create, endpoint update | apidog endpoint create --project <projectId> --branch <aiBranchName> --file ./endpoint.json |
| Model data | schema create, schema update | apidog schema update <schemaId> --project <projectId> --branch <aiBranchName> --file ./schema.json |
| Dokumen Markdown | doc create, doc update | apidog doc create --project <projectId> --branch <aiBranchName> --file ./doc.json |
| Skenario pengujian | test-scenario create, test-scenario update | apidog test-scenario update <scenarioId> --project <projectId> --branch <aiBranchName> --file ./scenario.json |
| Test suite | test-suite create, test-suite update | apidog test-suite create --project <projectId> --branch <aiBranchName> --file ./suite.json |
| Data pengujian | test-data create, test-data update | apidog test-data create --project <projectId> --branch <aiBranchName> --file ./test-data.json |
Saat membuat atau memperbarui sumber daya yang kompleks, kami merekomendasikan penggunaan cli-schema terlebih dahulu untuk melihat dan memvalidasi struktur data.Mengimpor Sumber Daya dari Cabang Sumber#
Jika AI Branch perlu memodifikasi sumber daya yang sudah ada, gunakan branch pick-to terlebih dahulu untuk mengimpor sumber daya dari cabang sumber ke AI Branch. Setelah impor, AI dapat terus mengedit sumber daya tersebut di AI Branch.| Perintah | Deskripsi | Contoh |
|---|
branch pick-to | Mengimpor sumber daya dari cabang sumber ke AI Branch target. | apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids> |
Contoh: Mengimpor endpoint dan membiarkan AI memodifikasinyapick-to hanya mengimpor sumber daya yang ditentukan secara eksplisit dalam perintah. Jika direktori, model data, komponen respons, atau sumber daya terkait lainnya diperlukan, konfirmasikan cakupan sumber daya sebelum mengimpor.
Melihat Perubahan AI Branch#
Sebelum penggabungan, kami merekomendasikan untuk meninjau pratinjau perubahan kandidat antara AI Branch dan cabang target. CLI dapat menggunakan merge-request preview untuk memindai jenis sumber daya yang saat ini didukung. Anda juga dapat melihat perbedaan cabang yang lebih lengkap di klien.| Perintah | Deskripsi | Contoh |
|---|
merge-request preview | Memindai perubahan kandidat untuk mengonfirmasi cakupan sumber daya sebelum penggabungan. | apidog merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName> |
branch get --type ai | Melihat informasi dasar AI Branch. | apidog branch get <aiBranchName> --project <projectId> --type ai |
Contoh: Meninjau pratinjau perubahan kandidat sebelum penggabunganmerge-request preview memindai perbedaan kandidat untuk jenis sumber daya yang saat ini didukung oleh CLI. Ini bukan diff sumber daya yang lengkap. Sebelum penggabungan akhir, kami tetap merekomendasikan untuk mengonfirmasi konten sumber daya penting di klien.
Menggabungkan AI Branch#
Setelah perubahan AI Branch selesai, Anda dapat menggabungkannya kembali ke cabang sumber atau cabang target lain. Untuk cabang target yang tidak dilindungi, gunakan branch merge untuk menggabungkan secara langsung. Untuk cabang utama yang dilindungi, gunakan merge-request create untuk membuat merge request dan melalui proses peninjauan.| Perintah | Deskripsi | Contoh |
|---|
branch merge | Menggabungkan sumber daya tertentu secara langsung dari AI Branch. | apidog branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids> |
merge-request create | Membuat merge request. | apidog merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids> |
merge-request approve | Menyetujui merge request. | apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json |
merge-request reject | Menolak merge request. | apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName> |
Contoh: Menggabungkan perubahan endpoint secara langsungContoh: Membuat merge requestBaik penggabungan langsung maupun merge request hanya menggabungkan daftar sumber daya yang diberikan secara eksplisit. Keduanya tidak secara otomatis menyertakan sumber daya yang direferensikan atau sumber daya direktori. Saat menentukan cakupan penggabungan, konfirmasikan dependensi di antara endpoint, direktori, model data, komponen respons, dan sumber daya pengujian.
Mengarsipkan dan Menghapus AI Branch#
Setelah AI Branch digabungkan atau tidak lagi diperlukan, Anda dapat mengarsipkannya terlebih dahulu lalu menghapusnya. Sebelum penghapusan, konfirmasikan bahwa perubahan dalam cabang telah digabungkan atau tidak lagi diperlukan.| Perintah | Deskripsi | Contoh |
|---|
branch archive --type ai | Mengarsipkan AI Branch. | apidog branch archive <aiBranchName> --project <projectId> --type ai |
branch delete --type ai | Menghapus AI Branch yang diarsipkan. | apidog branch delete <aiBranchName> --project <projectId> --type ai |
Izin Pengeditan AI Eksternal#
Secara default, CLI merekomendasikan penulisan sumber daya proyek melalui AI Branch. Hal ini memungkinkan perubahan yang dihasilkan AI masuk ke cabang terisolasi terlebih dahulu dan hanya digabungkan setelah konfirmasi pengguna.Jika Anda ingin operasi AI eksternal atau CLI mengedit cabang utama, cabang sprint standar, atau cabang umum secara langsung, aktifkan izin terkait di klien:Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions
| Izin | Deskripsi |
|---|
| Izin pengeditan langsung cabang utama | Mengizinkan operasi AI eksternal atau CLI untuk menulis secara langsung ke cabang utama. |
| Izin pengeditan langsung cabang sprint standar | Mengizinkan operasi AI eksternal atau CLI untuk menulis secara langsung ke cabang sprint standar. |
| Izin pengeditan langsung cabang umum | Mengizinkan operasi AI eksternal atau CLI untuk menulis secara langsung ke cabang umum. |
| Izin pengeditan langsung AI Branch | Mengizinkan operasi AI eksternal atau CLI untuk menulis ke AI Branch yang dibuat dan dipelihara oleh AI. Ini biasanya tetap diaktifkan. |
Untuk melindungi sumber daya proyek, kami merekomendasikan agar operasi AI eksternal atau CLI menulis ke AI Branch terlebih dahulu dan hanya menggabungkan setelah konfirmasi pengguna. Aktifkan izin pengeditan langsung hanya ketika alur kerja otomasi jelas perlu memodifikasi cabang target secara langsung.
Praktik Terbaik#
1.
Buat satu AI Branch per tugas: Setiap AI Branch harus sesuai dengan tugas yang jelas, seperti menyelesaikan API pendaftaran pengguna, mengatur dokumentasi modul pesanan, atau menghasilkan skenario pengujian pembayaran.
2.
Impor sebelum mengedit: Saat memodifikasi sumber daya yang sudah ada, gunakan pick-to untuk mengimpornya terlebih dahulu, lalu perbarui di AI Branch untuk menghindari kebingungan tentang sumbernya.
3.
Tinjau pratinjau perbedaan sebelum penggabungan: Gunakan merge-request preview atau tampilan diff klien untuk mengonfirmasi konten sumber daya dan dependensi.
4.
Pilih cakupan penggabungan secara eksplisit: Perintah penggabungan hanya memproses daftar sumber daya yang diberikan. Untuk sumber daya terkait seperti direktori API, model data, komponen respons, dan kasus pengujian, konfirmasikan semuanya bersama-sama.
5.
Pertahankan tinjauan manusia: Definisi API, skrip pengujian, dan model data yang dihasilkan AI harus ditinjau oleh anggota proyek sebelum digabungkan.
6.
Arsipkan cabang dengan segera: AI Branch yang telah digabungkan atau ditinggalkan harus segera diarsipkan agar daftar cabang tetap jelas.
FAQ#
AI Branch adalah cabang sprint khusus yang terutama digunakan untuk menyimpan hasil penulisan dari AI eksternal, operasi CLI, atau skrip otomasi. AI Branch mencatat cabang sumber dan mendorong pengguna untuk mengonfirmasi perbedaan sebelum penggabungan. Cabang sprint standar biasanya digunakan untuk kolaborasi sehari-hari di antara anggota tim.
Tidak. Perubahan dalam AI Branch disimpan terlebih dahulu di AI Branch tersebut. Sumber daya terkait masuk ke cabang target hanya setelah pengguna melakukan penggabungan langsung atau membuat dan menyetujui merge request.
Dalam proyek Apidog, buka Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions, lalu aktifkan izin pengeditan langsung untuk cabang utama, cabang sprint standar, atau cabang umum sesuai kebutuhan. Setelah izin ini diaktifkan, operasi AI eksternal atau CLI dapat menulis secara langsung dalam cakupan cabang terkait.
Tidak. Baik branch merge maupun merge-request create dijalankan sesuai dengan daftar sumber daya yang diberikan secara eksplisit. Jika endpoint mereferensikan model data, komponen respons, direktori, atau sumber daya pengujian, konfirmasikan dan tambahkan cakupan sumber daya terkait sebelum penggabungan.
Tidak. Penghapusan tidak wajib. Kami merekomendasikan pengarsipan cabang setelah mengonfirmasi bahwa perubahannya telah digabungkan atau tidak lagi diperlukan, lalu memutuskan apakah akan menghapusnya sesuai dengan konvensi tim Anda untuk menghindari penumpukan cabang historis dalam jangka panjang.
