# Buku Resipi

Canonical source: https://maguyva.ai/ms/docs/cookbook

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Resipi praktikal untuk kerja Maguyva MCP setiap hari. Setiap resipi menamakan alatan dan urutan — bukan rujukan parameter penuh. Untuk parameter alat, gunakan [Rujukan MCP API](https://maguyva.ai/docs/mcp-api). Untuk persediaan kali pertama, gunakan [Mula pantas](https://maguyva.ai/docs/quickstart).

### Pilih alat yang betul

Kebanyakan soalan bermula dengan satu panggilan. Tingkatkan hanya apabila jawapan pertama terlalu luas atau terlalu nipis.

- `intelligent_search` — mulakan di sini untuk soalan tentang pangkalan kod dalam bahasa semula jadi. Tetapan lalai auto/balanced menghalakan pertanyaan yang dikenal pasti dengan keyakinan tinggi sebagai carian definisi kepada carian berstruktur, soalan tentang rujukan atau kesan kepada graf, dan soalan tentang padanan tepat kepada carian teks. Soalan lain menggunakan makna semantik dan teks yang diindeks. Gunakan mode=hybrid atau auto dengan quality=thorough untuk meminta keempat-empat modaliti carian. Mod yang dipilih secara eksplisit mengatasi tetapan quality.
- `find_symbol` — anda sudah tahu fungsi, kelas atau nama pembolehubah.
- `dependency_search` — lingkungan impak: kod pemanggil, komponen yang bergantung atau impak sebelum dan selepas suntingan.
- `get_task_context` — kawasan yang belum dikenali; satu himpunan terhad fail, simbol dan kebergantungan untuk penerangan tugas.
- `repository_context` — senaraikan repositori yang boleh diakses atau periksa cara nama repositori diselesaikan.
- `ask_maguyva` dengan `operation="guidance"` — bantuan setempat tentang pemilihan alat dan penggunaan Maguyva (tanpa mengubah repositori).

Blok JSON ialah input MCP tools/call. Gantikan owner/repo, cabang dan nama simbol dengan nilai daripada repositori anda.

### Pasang dan sahkan klien

Dapatkan Maguyva ke dalam klien MCP anda dan sahkan sambungan dengan senarai repositori sebenar.

1. Cipta kunci API dalam [app.maguyva.ai](https://app.maguyva.ai) (kunci bermula dengan `mgv_`).
2. Sambung dan indeks sekurang-kurangnya satu repositori GitHub yang anda sudah fahami.
3. Sambungkan klien anda menggunakan [Panduan Pemasangan](https://maguyva.ai/docs/installation) (plugin Claude Code, atau konfigurasi jauh asli untuk Cursor, VS Code, Devin Desktop, Zed dan lain-lain).
4. Tanya ejen anda "Apakah repositori yang saya sambungkan?" — ini menguji pengesahan dan `repository_context` dari hujung ke hujung.
5. Tanya satu soalan sebenar tentang repo itu yang jawapannya boleh anda nilai. Anda sepatutnya melihat laluan fail dan nombor baris daripada pokok yang diindeks.

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}
```

Menghadapi masalah dengan kunci, jambatan atau repo yang hilang? [Menyelesaikan masalah](https://maguyva.ai/docs/troubleshooting).

### Tanya sebelum anda mengedit

Petakan simbol dan lingkungan impak sebelum menukar kod kongsi. Alat Maguyva tidak mengubah suai repositori anda — ia memberi maklumat untuk suntingan yang dilaksanakan oleh klien anda secara setempat.

1. Jika anda tahu nama simbol, panggil `find_symbol` untuk mencari takrif dan tempat penggunaannya.
2. Jika anda hanya mempunyai perihalan tugasan ("tambah SSO", "betulkan webhook pengebilan"), mulakan dengan `get_task_context` atau `intelligent_search`.
3. Sebelum menyunting simbol kongsi, panggil `dependency_search` dengan analisis komponen yang bergantung atau analisis impak (atau hantarkan laluan yang berubah untuk analisis impak gaya PR) supaya anda dapat melihat lingkungan impaknya.
4. Buka fail yang dipetik (bacaan tempatan untuk fail pada cakera; `get_file` untuk laluan jauh/rentas repo) dan sahkan pelan terhadap kod sebenar.
5. Selepas suntingan, semak semula simbol yang sama dengan `dependency_search` menggunakan verify_after_edit=true dan targets atau changed_paths. Ini membaca graf terindeks, bukan perubahan setempat yang belum dikomit: semak indexed_commit_sha dan kemutakhiran indeks sebelum menganggapnya sebagai bukti untuk versi kod baharu, dan jalankan ujian setempat.

```json
{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}
```

Parameter penuh: [Rujukan MCP API](https://maguyva.ai/docs/mcp-api).

### Cari, kemudian tukar

Gelung ejen lalai: teroka → kenal pasti simbol → sunting dengan bukti.

1. Mulakan dengan `intelligent_search` dan pertanyaan bahasa biasa ("bagaimana sesi tamat tempoh berfungsi", "di manakah logik cuba semula").
2. Kecilkan skop dengan penapis bahasa atau laluan jika set hasil pertama mengandungi terlalu banyak hasil yang tidak berkaitan. language_filter mengecualikan graf daripada auto/hybrid; pertanyaan auto yang dihalakan hanya kepada graf akan beralih semula kepada carian semantik dan teks. Mod graph yang dipilih secara eksplisit dengan language_filter ditolak. Semak routing_decision.modalities_used untuk melihat rancangan carian yang dipilih; warnings hadir hanya apabila pelayan mengeluarkan amaran.
3. Susuli padanan yang menjanjikan dengan `find_symbol` atau `dependency_search` dan bukannya bertanya semula soalan samar-samar yang sama.
4. Gunakan `get_file` hanya apabila anda memerlukan laluan diindeks khusus yang tiada pada cakera.
5. Sunting dalam alat klien biasa anda. Maguyva adalah untuk penemuan dan pengesahan — bukan penulisan.

```json
{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}
```

Mengapa gelung ini berfungsi: [Bagaimana Ia Berfungsi](https://maguyva.ai/docs/how-it-works).

### Hasil kosong atau tidak mencukupi

Apabila alat tidak mengembalikan apa-apa yang berguna, betulkan resolusi dan pengindeksan sebelum menulis semula pertanyaan selama-lamanya.

1. Sahkan repositori disambungkan dan selesai pengindeksan dalam [app.maguyva.ai](https://app.maguyva.ai).
2. Semak rentetan repositori: `"owner/repo"` menggunakan cabang lalai; `"owner/repo:branch"` menetapkan cabang tertentu. Pemadanan tidak peka huruf besar/kecil dan bukan pemadanan anggaran — kesilapan menaip tidak dibetulkan secara automatik.
3. Panggil `repository_context` dengan `action="info"` dan periksa metadata resolusi (contohnya `metadata.resolution_reason`).
4. Abaikan `repository` hanya apabila klien MCP anda membekalkan lalai bagi permintaan tersebut atau kunci boleh mengakses tepat satu repositori; jika tidak, berikannya secara eksplisit.
5. Cuba semula dengan pertanyaan yang lebih khusus, nama simbol yang diketahui melalui `find_symbol` atau penapis bahasa/laluan. Jika sambungan itu sendiri terputus, gunakan [Menyelesaikan masalah](https://maguyva.ai/docs/troubleshooting).

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}
```

Kegagalan persediaan: [Menyelesaikan masalah](https://maguyva.ai/docs/troubleshooting).

### Bekerja merentasi berbilang repositori

Sasarkan repo diindeks yang betul apabila kunci boleh melihat lebih daripada satu.

1. Panggil `repository_context` dengan `action="list"` sekali untuk mengetahui slug tepat yang boleh dicari oleh kunci anda.
2. Berikan `repository` secara eksplisit pada alat carian dan simbol apabila anda memerlukan repo bukan lalai (contohnya `"owner/other-repo"` atau `"owner/other-repo:develop"`).
3. Kekalkan satu soalan = satu repositori melainkan anda sengaja membandingkan merentas repo dalam panggilan berasingan.
4. Gunakan `get_file` apabila fail berada dalam repo terindeks yang bukan worktree semasa anda.
5. Ingat: alat ini tidak pernah menulis kembali kepada GitHub — konteks berbilang repo adalah untuk bacaan dan perancangan sahaja.

Butiran format repositori: [Rujukan MCP API](https://maguyva.ai/docs/mcp-api).

Membuat persediaan buat kali pertama? Mulakan dengan [Mula pantas](https://maguyva.ai/docs/quickstart), kemudian gunakan resipi ini untuk tugas harian.