# คู่มือสูตรสำเร็จ

Canonical source: https://maguyva.ai/th/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).

ขั้นตอนใช้งาน Maguyva MCP สำหรับงานประจำวัน แต่ละขั้นตอนระบุเครื่องมือและลำดับการใช้งาน ไม่ใช่เอกสารอ้างอิงพารามิเตอร์ฉบับเต็ม ดูพารามิเตอร์ของเครื่องมือได้ที่ [อ้างอิง MCP API](https://maguyva.ai/docs/mcp-api) หากตั้งค่าครั้งแรก ให้เริ่มจาก [เริ่มต้นอย่างรวดเร็ว](https://maguyva.ai/docs/quickstart)

### เลือกเครื่องมือที่เหมาะสม

คำถามส่วนใหญ่เริ่มได้ด้วยการเรียกเครื่องมือครั้งเดียว ค่อยค้นต่อเมื่อคำตอบแรกกว้างเกินไปหรือให้ข้อมูลน้อยเกินไป

- `intelligent_search` — เริ่มที่นี่เมื่อมีคำถามเกี่ยวกับฐานโค้ดด้วยภาษาธรรมชาติ ค่าเริ่มต้น auto/balanced ส่งคำถามที่ระบุได้อย่างมั่นใจว่าเกี่ยวกับนิยามไปยังการค้นหาเชิงโครงสร้าง ส่งคำถามเกี่ยวกับการอ้างอิงหรือผลกระทบไปยังกราฟ และส่งคำถามที่ต้องการผลตรงกันทุกประการไปยังการค้นหาข้อความ คำถามอื่นใช้ความหมายและข้อความที่จัดทำดัชนีแล้ว ใช้ mode=hybrid หรือ auto ร่วมกับ quality=thorough เพื่อขอใช้รูปแบบการค้นหาทั้งสี่แบบ โดยโหมดที่ระบุไว้อย่างชัดเจนจะมีผลเหนือ quality
- `find_symbol` — คุณรู้ฟังก์ชัน คลาส หรือชื่อตัวแปรอยู่แล้ว
- `dependency_search` — รัศมีผลกระทบ: โค้ดที่เรียกใช้ ส่วนประกอบที่พึ่งพา หรือผลกระทบก่อนและหลังการแก้ไข
- `get_task_context` — สำหรับส่วนที่ยังไม่คุ้นเคย รวบรวมไฟล์ สัญลักษณ์ และการพึ่งพาเป็นชุดข้อมูลที่จำกัดขนาดสำหรับคำอธิบายงาน
- `repository_context` — แสดงรายการรีโพซิทอรีที่เข้าถึงได้ หรือตรวจสอบว่าชื่อรีโพซิทอรีถูกจับคู่กับรีโพซิทอรีใด
- `ask_maguyva` พร้อม `operation="guidance"` — ความช่วยเหลือเฉพาะที่เกี่ยวกับการเลือกเครื่องมือและการใช้งาน Maguyva (ไม่มีการเปลี่ยนแปลงรีโพ)

บล็อก JSON เป็นอินพุตของ MCP tools/call แทนที่ owner/repo, แบรนช์ และชื่อสัญลักษณ์ด้วยค่าจากรีโพซิทอรีของคุณ

### ติดตั้งและตรวจสอบไคลเอนต์

เพิ่ม Maguyva ในไคลเอนต์ MCP ของคุณ แล้วตรวจสอบการเชื่อมต่อด้วยการเรียกดูรายการรีโพซิทอรีจริง

1. สร้างคีย์ API ใน [app.maguyva.ai](https://app.maguyva.ai) (คีย์ขึ้นต้นด้วย `mgv_`)
2. เชื่อมต่อและจัดทำดัชนีรีโพซิทอรี GitHub อย่างน้อยหนึ่งรายการที่คุณเข้าใจอยู่แล้ว
3. เชื่อมต่อไคลเอนต์ของคุณโดยใช้ [คู่มือการติดตั้ง](https://maguyva.ai/docs/installation) (ปลั๊กอิน Claude Code หรือการกำหนดค่าระยะไกลแบบเนทีฟสำหรับ Cursor, VS Code, Devin Desktop, Zed และอื่นๆ)
4. ถามเอเจนต์ของคุณว่า "ฉันเชื่อมต่อรีโพซิทอรีใดบ้าง" — เพื่อทดสอบการยืนยันตัวตนและ `repository_context` ตั้งแต่ต้นจนจบ
5. ถามคำถามจริงหนึ่งข้อเกี่ยวกับรีโพนั้นซึ่งคุณสามารถให้คะแนนคำตอบได้ คุณควรเห็นเส้นทางของไฟล์และหมายเลขบรรทัดจากแผนผังที่จัดทำดัชนี

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

ติดปัญหาคีย์ บริดจ์ หรือหารีโพซิทอรีไม่เจอ? ดู [การแก้ไขปัญหา](https://maguyva.ai/docs/troubleshooting)

### ถามก่อนที่จะแก้ไข

ทำแผนที่สัญลักษณ์และรัศมีผลกระทบก่อนแก้โค้ดที่ใช้ร่วมกัน เครื่องมือ Maguyva ไม่แก้ไขรีโพซิทอรีของคุณ แต่ให้ข้อมูลประกอบการแก้ไขที่ไคลเอนต์จะทำในเครื่อง

1. หากทราบชื่อสัญลักษณ์ ให้เรียก `find_symbol` เพื่อค้นหานิยามและจุดที่ใช้งาน
2. หากคุณมีเฉพาะคำอธิบายงาน ("เพิ่ม SSO", "แก้ไขเว็บฮุคการเรียกเก็บเงิน") ให้เริ่มต้นด้วย `get_task_context` หรือ `intelligent_search`
3. ก่อนแก้ไขสัญลักษณ์ที่ใช้ร่วมกัน ให้เรียก `dependency_search` เพื่อวิเคราะห์ส่วนประกอบที่พึ่งพาหรือผลกระทบ (หรือส่งพาธที่เปลี่ยนแปลงเพื่อวิเคราะห์ผลกระทบแบบ PR) เพื่อดูรัศมีผลกระทบ
4. เปิดไฟล์ที่อ้างถึง (การอ่านในเครื่องสำหรับไฟล์บนดิสก์ `get_file` สำหรับเส้นทางระยะไกล/ข้ามรีโพ) และยืนยันแผนกับโค้ดจริง
5. หลังแก้ไข ให้ตรวจสอบสัญลักษณ์เดิมอีกครั้งด้วย `dependency_search` โดยใช้ verify_after_edit=true และ targets หรือ changed_paths เครื่องมือนี้อ่านกราฟที่จัดทำดัชนีแล้ว ไม่ใช่การเปลี่ยนแปลงในเครื่องที่ยังไม่ได้ commit: ตรวจสอบ indexed_commit_sha และความเป็นปัจจุบันของดัชนีก่อนถือว่าผลลัพธ์เป็นหลักฐานสำหรับรุ่นแก้ไขใหม่ และรันการทดสอบในเครื่องด้วย

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

พารามิเตอร์แบบเต็ม: [อ้างอิง MCP API](https://maguyva.ai/docs/mcp-api)

### ค้นหาแล้วเปลี่ยนแปลง

วงจรการทำงานพื้นฐานของเอเจนต์: สำรวจ → ระบุสัญลักษณ์ที่เกี่ยวข้อง → แก้ไขโดยมีหลักฐาน

1. เริ่มต้นด้วย `intelligent_search` และคำค้นภาษาธรรมชาติ ("การหมดอายุของเซสชันทำงานอย่างไร", "ตรรกะการลองใหม่อยู่ที่ไหน")
2. จำกัดผลลัพธ์ด้วยตัวกรองภาษาหรือเส้นทางหากผลลัพธ์ชุดแรกมีข้อมูลที่ไม่เกี่ยวข้องมาก language_filter จะตัดกราฟออกจาก auto/hybrid ส่วนคำค้นแบบ auto ที่ถูกส่งไปยังกราฟเพียงอย่างเดียวจะกลับไปใช้การค้นหาเชิงความหมายและข้อความ หากระบุโหมดกราฟอย่างชัดเจนพร้อม language_filter ระบบจะปฏิเสธคำขอ ตรวจดู routing_decision.modalities_used เพื่อทราบแผนการค้นหาที่เลือก ส่วน warnings จะปรากฏเฉพาะเมื่อเซิร์ฟเวอร์แจ้งคำเตือนเท่านั้น
3. ตรวจสอบผลลัพธ์ที่น่าสนใจต่อด้วย `find_symbol` หรือ `dependency_search` แทนการถามคำถามเดิมที่ยังคลุมเครือซ้ำ
4. ใช้ `get_file` เฉพาะเมื่อคุณต้องการพาธที่จัดทำดัชนีเฉพาะซึ่งไม่อยู่บนดิสก์
5. แก้ไขในเครื่องมือไคลเอนต์ปกติของคุณ Maguyva มีไว้เพื่อการค้นพบและการตรวจสอบ ไม่ใช่การเขียน

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

ทำไมลูปนี้ถึงใช้งานได้: [มันทำงานอย่างไร](https://maguyva.ai/docs/how-it-works)

### ไม่มีผลลัพธ์หรือได้ข้อมูลน้อยเกินไป

เมื่อเครื่องมือไม่ส่งคืนข้อมูลที่มีประโยชน์ ให้ตรวจสอบการเลือกรีโพซิทอรีและการจัดทำดัชนีก่อน แทนที่จะเขียนคำค้นใหม่ซ้ำไปเรื่อย ๆ

1. ยืนยันว่ามีการเชื่อมต่อรีโพซิทอรีและจัดทำดัชนีใน [app.maguyva.ai](https://app.maguyva.ai) เสร็จแล้ว
2. ตรวจสอบชื่อรีโพซิทอรี: `"owner/repo"` ใช้แบรนช์เริ่มต้น ส่วน `"owner/repo:branch"` ระบุแบรนช์ที่ต้องการ การจับคู่ไม่แยกตัวพิมพ์เล็กกับตัวพิมพ์ใหญ่ แต่ไม่ใช่การจับคู่แบบคล้ายคลึง — ระบบไม่แก้คำพิมพ์ผิดให้อัตโนมัติ
3. เรียก `repository_context` ด้วย `action="info"` แล้วตรวจสอบเมทาดาทาการจับคู่รีโพซิทอรี (เช่น `metadata.resolution_reason`)
4. ละเว้น `repository` เฉพาะเมื่อไคลเอนต์ MCP ของคุณระบุค่าเริ่มต้นของคำขอ หรือคีย์สามารถเข้าถึงรีโพซิทอรีเพียงแห่งเดียวเท่านั้น มิฉะนั้นก็ส่งผ่านอย่างชัดเจน
5. ลองอีกครั้งโดยใช้ข้อความค้นหาที่เจาะจงมากขึ้น ชื่อสัญลักษณ์ที่รู้จักผ่าน `find_symbol` หรือตัวกรองภาษา/เส้นทาง หากการเชื่อมต่อขาดหาย ให้ใช้ [การแก้ไขปัญหา](https://maguyva.ai/docs/troubleshooting)

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

ความล้มเหลวในการตั้งค่า: [การแก้ไขปัญหา](https://maguyva.ai/docs/troubleshooting)

### ทำงานกับหลายรีโพซิทอรี

เลือกรีโพซิทอรีที่จัดทำดัชนีไว้ให้ถูกต้อง เมื่อคีย์เข้าถึงได้มากกว่าหนึ่งรีโพซิทอรี

1. เรียก `repository_context` ด้วย `action="list"` หนึ่งครั้ง เพื่อดูชื่อรีโพซิทอรี (slug) ที่คีย์ของคุณค้นหาได้
2. ส่งผ่าน `repository` อย่างชัดเจนในการค้นหาและเครื่องมือสัญลักษณ์ เมื่อคุณต้องการรีโพที่ไม่ใช่ค่าเริ่มต้น (เช่น `"owner/other-repo"` หรือ `"owner/other-repo:develop"`)
3. เก็บหนึ่งคำถาม = หนึ่งรีโพซิทอรี เว้นแต่คุณจะตั้งใจเปรียบเทียบระหว่างรีโพซิทอรีในการเรียกแยกกัน
4. ใช้ `get_file` เมื่อไฟล์อยู่ในรีโพที่จัดทำดัชนีซึ่งไม่ใช่เวิร์กทรีที่คุณกำลังใช้งาน
5. ข้อควรจำ: เครื่องมือจะไม่เขียนกลับไปที่ GitHub — บริบทของหลายรีโพ มีไว้เพื่อการอ่านและการวางแผนเท่านั้น

รายละเอียดรูปแบบรีโพซิทอรี: [อ้างอิง MCP API](https://maguyva.ai/docs/mcp-api)

ตั้งค่าครั้งแรกใช่ไหม? เริ่มจาก [เริ่มต้นอย่างรวดเร็ว](https://maguyva.ai/docs/quickstart) แล้วใช้ขั้นตอนเหล่านี้กับงานประจำวัน