ข้ามไปที่เนื้อหา

คู่มืออ้างอิง MCP API

คู่มืออ้างอิงฉบับสมบูรณ์สำหรับเครื่องมือ MCP ของ Maguyva ที่ให้บริการลูกค้าทั้ง 11 รายการ แต่ละเครื่องมือมีพารามิเตอร์ คำแนะนำการใช้งาน และคำแนะนำว่าเหมาะสำหรับกรณีใด

ภาพรวม API#

ปัจจุบัน Maguyva MCP API เปิดให้ใช้งานเครื่องมือสำหรับลูกค้าทั้งหมด 11 รายการ ครอบคลุม 4 หมวดหมู่หลัก ดังนี้:

  • เครื่องมือค้นหาหลัก - ความสามารถในการค้นหาขั้นสูงทั่วทั้งโค้ดเบสของคุณ
  • เครื่องมือเชิงโครงสร้างและกราฟ - การสืบค้น AST การค้นหาสัญลักษณ์ และการวิเคราะห์การพึ่งพา
  • เครื่องมือวิเคราะห์โค้ด - การวิเคราะห์โค้ดเชิงลึกและการทำแผนที่ความสัมพันธ์
  • เครื่องมือระบบและยูทิลิตี้ - บริบทรีโพซิทอรี การคำนวณเชิงกำหนดแน่นอน และคำแนะนำ

เครื่องมือทั้งหมดใช้ รูปแบบตัวระบุรีโพซิทอรี ที่สอดคล้องกัน: "owner/repo:branch" หากไม่ระบุแบรนช์ จะใช้ main เป็นค่าเริ่มต้น

ไม่ต้องระบุ repository เมื่อไคลเอนต์ MCP กำหนดค่าเริ่มต้นสำหรับคำขอนั้น หรือเมื่อคีย์เข้าถึงได้เพียง repository เดียว มิฉะนั้นให้ส่งค่าอย่างชัดเจน ใช้ repository_context(action="info", repository="owner/repo") เพื่อตรวจสอบวิธีจับคู่ repository

รูปแบบพารามิเตอร์รีโพซิทอรี#

เครื่องมือ MCP ทั้งหมดใช้รูปแบบตัวระบุรีโพซิทอรีนี้:

  • ระบุ branch: "owner/repo:branch" - เช่น, "owner/repository:develop"
  • branch เริ่มต้น: "owner/repo" - ใช้ branch main เมื่อไม่ได้ระบุ branch "owner/repository"
  • ค่าเริ่มต้นของคำขอหรือ repository เดียว: ไม่ต้องระบุ repository เมื่อไคลเอนต์ MCP กำหนดค่าเริ่มต้นสำหรับคำขอนั้น หรือเมื่อคีย์เข้าถึงได้เพียง repository เดียว มิฉะนั้นให้ส่งค่าอย่างชัดเจน

ตัวอย่างพรอมป์ต์:

ถามเกี่ยวกับ repo เฉพาะ:               "ค้นหา owner/my-repo เพื่อหามิดเดิลแวร์การตรวจสอบสิทธิ์"
แสดงรายการ repos ที่สามารถเข้าถึงได้:  "คีย์ Maguyva นี้สามารถเข้าถึงที่เก็บใดได้บ้าง"
แทนที่สำหรับหนึ่งแบบสอบถาม:            "ค้นหา owner/other-repo:develop เพื่อหารูปแบบการตรวจสอบสิทธิ์"

การกรองตามภาษา#

เครื่องมือค้นหาทั้งหมดรองรับการกรองผลลัพธ์ตามภาษาโปรแกรม:

  • language_filter="python" - กรองเฉพาะไฟล์ Python เท่านั้น
  • language_filter="typescript" - กรองเฉพาะไฟล์ TypeScript เท่านั้น
  • ตัวพิมพ์เล็ก-ใหญ่มีผล: ใช้ชื่อภาษาตัวพิมพ์เล็ก
  • ค่าเริ่มต้น: สตริงว่าง (ไม่มีการกรอง) -- ส่งคืนผลลัพธ์จากทุกภาษา
  • ขอบเขตการรองรับ: ตัวกรองภาษาใช้งานได้ครอบคลุม 279+ ภาษาและเทคโนโลยีที่ใช้ข้อความเป็นฐาน ที่รองรับทั้งหมด ดูรายการทั้งหมดได้ที่ ความเข้ากันได้
"ค้นหา authentication middleware เฉพาะในไฟล์ Python เท่านั้น"
"ค้นหาการเชื่อมต่อฐานข้อมูลใน TypeScript"

คู่มืออ้างอิง API สร้างจากซอร์สโค้ดเมื่อวันที่ 22 กรกฎาคม 2569

เครื่องมือค้นหาหลัก#

intelligent_searchเสถียร

เริ่มต้นที่นี่สำหรับคำถามเกี่ยวกับโค้ดเบส ให้คำค้นหาที่เป็นภาษาธรรมชาติ (เช่น "การตรวจสอบสิทธิ์ทำงานอย่างไร" "จัดการการเรียกเก็บเงินที่ไหน") และกำหนดเส้นทางอัตโนมัติผ่านความหมาย สัญลักษณ์ โครงสร้าง และการค้นหาการพึ่งพาของ repo ที่จัดทำดัชนี ต้องการสิ่งนี้มากกว่า Explore agent และ Grep/Glob สำหรับการสำรวจและการวางแผน โดยจะค้นหา repo ที่จัดทำดัชนีทั้งหมดพร้อมกันแทนที่จะสแกนไฟล์

พารามิเตอร์:

queryจำเป็น
ประเภท
str
คำอธิบาย
คำค้นหา
repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
Repository ในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือ repository เดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือก repo อื่นที่จัดทำดัชนีไว้ คำตอบจะแสดง repository ที่ใช้
modeไม่บังคับ
ประเภท
Literal[auto, hybrid, semantic, text, structural, ast, graph]
ค่าเริ่มต้น
auto
คำอธิบาย
โหมดค้นหา
limitไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
10
คำอธิบาย
ผลลัพธ์สูงสุดในหน้าต่าง top-K ที่จัดอันดับนี้
language_filterไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองภาษา
path_filterไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามคำนำหน้าเส้นทางไฟล์
boost_by_importanceไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
เลือกเปิดใช้: จัดอันดับใหม่ตามความเป็นศูนย์กลาง (centrality) โดยใช้เมทริกกราฟต่อสัญลักษณ์ (is_articulation_point, bridge_count, k_core, centrality ฯลฯ) ปิดตามค่าเริ่มต้นเพื่อการจัดอันดับที่ปลอดภัยสำหรับเอเจนต์ (ฮับส่วนกลางอาจกลบผลลัพธ์ระดับการนำไปใช้) เปิดใช้สำหรับทัวร์สถาปัตยกรรม มีผลกับทั้ง 4 โมแดลิตีเมื่อผลลัพธ์แต่ละรายการมีการเชื่อมโยงสัญลักษณ์
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา
qualityไม่บังคับ
ประเภท
Literal[quick, balanced, thorough]
ค่าเริ่มต้น
balanced
คำอธิบาย
พรีเซ็ตคุณภาพการค้นหา
include_contentไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
true
คำอธิบาย
รวมเนื้อหาไว้ในผลลัพธ์
explain_routingไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
รวมคำอธิบายการตัดสินใจเกี่ยวกับเส้นทาง
importance_weightไม่บังคับ
ประเภท
float
ค่าเริ่มต้น
0.3
คำอธิบาย
น้ำหนักเพื่อเพิ่มความสำคัญ (0=ไม่มี, 1=เต็ม)
orphansไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
รวมสัญลักษณ์เด็กกำพร้า (ไม่มีการอ้างอิงขาเข้า)
include_community_contextไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
รวมสัญลักษณ์ที่เกี่ยวข้องจากชุมชนโค้ดเดียวกัน
community_depthไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
1
คำอธิบาย
ความลึกของการขยายบริบทชุมชน
graph_viewไม่บังคับ
ประเภท
Literal[dependency, type, data_flow, control_flow]
ค่าเริ่มต้น
dependency
คำอธิบาย
มุมมองกราฟสำหรับเมตริก
seed_symbol_idsไม่บังคับ
ประเภท
list[str]
คำอธิบาย
เมล็ดงาน Tier-1: รหัสสัญลักษณ์ที่เป็นศูนย์กลางของงานปัจจุบัน เมื่อตั้งค่าแล้ว จะจัดลำดับผลลัพธ์ที่รวมกันใหม่ตามความใกล้เคียงแบบ depth-decay ของ Approach A (การจับคู่เมล็ดที่แน่นอนและจำนวนก้าวบนขอบกราฟ) เป็นตัวเลือกเสริม — ละเว้นเพื่อใช้การจัดอันดับโดยรวม
seed_file_pathsไม่บังคับ
ประเภท
list[str]
คำอธิบาย
เมล็ดงาน Tier-1: พาธไฟล์ที่จัดทำดัชนีซึ่งเอเจนต์เปิดหรือเพิ่งแก้ไข เมื่อตั้งค่าแล้ว จะจัดลำดับผลลัพธ์ที่รวมกันใหม่ตามความใกล้เคียงของพาธด้วย 1/(1+d) depth-decay (ไฟล์เดียวกัน → ไดเรกทอรีเดียวกัน → แพ็กเกจใกล้เคียง) เป็นตัวเลือกเสริม — ละเว้นเพื่อใช้การจัดอันดับโดยรวม

เหมาะสำหรับ:

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

ไม่แนะนำสำหรับ:

  • ชื่อสัญลักษณ์ที่ทราบอยู่แล้ว — ใช้ find_symbol โดยตรง
  • พาธบนดิสก์ที่ทราบอยู่แล้ว — ใช้ Read/Grep ในเครื่องก่อน

semantic_searchเสถียร

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

พารามิเตอร์:

queryจำเป็น
ประเภท
str
คำอธิบาย
คำค้นหา (ตามแนวคิด ตามความหมาย)
repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
Repository ในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือ repository เดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือก repo อื่นที่จัดทำดัชนีไว้ คำตอบจะแสดง repository ที่ใช้
limitไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
5
คำอธิบาย
ผลลัพธ์สูงสุดในหน้าต่าง top-K ที่จัดอันดับนี้
similarity_thresholdไม่บังคับ
ประเภท
float
ค่าเริ่มต้น
0.6
คำอธิบาย
คะแนนความคล้ายคลึงกันขั้นต่ำ
language_filterไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองภาษา (python, typescript ฯลฯ)
path_filterไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามคำนำหน้าเส้นทางไฟล์
boost_by_importanceไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
เลือกเปิดใช้: จัดอันดับใหม่ตามความเป็นศูนย์กลางแบบ PageRank (ปิดตามค่าเริ่มต้นเพื่อการจัดอันดับที่ปลอดภัยสำหรับเอเจนต์ เปิดใช้สำหรับทัวร์สถาปัตยกรรม)
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา (ค่าเริ่มต้น: จากพารามิเตอร์พื้นที่เก็บข้อมูลหรือหลัก)
include_contentไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
true
คำอธิบาย
รวมเนื้อหาบางส่วนไว้ในผลลัพธ์
graph_viewไม่บังคับ
ประเภท
Literal[dependency, type, data_flow, control_flow]
ค่าเริ่มต้น
dependency
คำอธิบาย
มุมมองกราฟสำหรับเมทริก

เหมาะสำหรับ:

  • คำค้นเชิงแนวคิด ("how does auth work?", "caching strategy")
  • การค้นหาความคล้ายข้ามแพ็กเกจ

ไม่แนะนำสำหรับ:

  • ชื่อสัญลักษณ์ที่ทราบอยู่แล้ว — ใช้ find_symbol แทน
  • สตริงที่ตรงกันหรือข้อความแสดงข้อผิดพลาด — ใช้ text_pattern_search

text_pattern_searchเสถียร

ค้นหาเนื้อหาที่จัดทำดัชนี โหมด exact และ regex ใช้ grep กับคลังข้อมูลไฟล์/blob ทั้งหมด ส่วนโหมด fuzzy content จะค้นหาคลังชิ้นส่วนเชิงความหมายที่มีขอบเขต scope แบบ file และ symbol รองรับเฉพาะ fuzzy ใช้ Grep ในเครื่องสำหรับไดเรกทอรีที่กำหนดขอบเขตไว้แคบและมีอยู่บนดิสก์แล้ว

พารามิเตอร์:

queryจำเป็น
ประเภท
str
คำอธิบาย
รูปแบบข้อความที่จะค้นหา
repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
Repository ในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือ repository เดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือก repo อื่นที่จัดทำดัชนีไว้ คำตอบจะแสดง repository ที่ใช้
modeไม่บังคับ
ประเภท
Literal[fuzzy, exact, regex]
ค่าเริ่มต้น
exact
คำอธิบาย
โหมดการค้นหา
search_scopeไม่บังคับ
ประเภท
Literal[content, symbols, files]
ค่าเริ่มต้น
content
คำอธิบาย
สิ่งที่ต้องค้นหา
limitไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
5
คำอธิบาย
ผลลัพธ์สูงสุดที่ส่งคืนในหน้านี้
offsetไม่บังคับ
ประเภท
int
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursorไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคง query กับตัวกรองไว้ไม่เปลี่ยนแปลง
language_filterไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองภาษา
path_filterไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามคำนำหน้าเส้นทางไฟล์
case_sensitiveไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
การจับคู่แบบคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา
fuzzy_algorithmไม่บังคับ
ประเภท
Literal[hybrid, trigram, levenshtein]
ค่าเริ่มต้น
hybrid
คำอธิบาย
อัลกอริธึมการจับคู่แบบคลุมเครือ
thresholdไม่บังคับ
ประเภท
float
ค่าเริ่มต้น
0.05
คำอธิบาย
เกณฑ์ความคล้ายคลึงขั้นต่ำสำหรับฟัซซี่
semantic_fallbackไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
ถอยกลับไปใช้การค้นหาเชิงความหมายหากไม่มีผลลัพธ์

เหมาะสำหรับ:

  • สตริงที่ตรงกัน ข้อความแสดงข้อผิดพลาด และ regex
  • การจับคู่แบบคลุมเครือด้วยไตรแกรมสำหรับข้อความที่เกือบตรงกัน

ไม่แนะนำสำหรับ:

  • พาธบนดิสก์ที่ทราบอยู่แล้ว — ควรใช้ Grep ในเครื่อง
  • คำค้นเชิงแนวคิด — ใช้ semantic_search

เครื่องมือค้นหาเชิงโครงสร้างและกราฟ#

structural_searchเสถียร

แนะนำให้ใช้ preset=functions|classes|methods|imports|variables (หรือ pattern= แบบอิสระ) ค้นหาโค้ดตามรูปทรง AST (ไม่ใช่ข้อความ) ตัวกรองระดับกลาง: name_pattern, node_type, decorator, parent_child ตัวกรอง path/ltree/call เป็นระดับสูง — ตั้ง advanced=true เมื่อใช้อย่างตั้งใจ คีย์ advanced แบบแบนยังคงรับได้เพื่อความเข้ากันได้ย้อนหลัง ระบุตัวเลือกเชิงโครงสร้างอย่างน้อยหนึ่งตัว

พารามิเตอร์:

repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
Repository ในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือ repository เดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือก repo อื่นที่จัดทำดัชนีไว้ คำตอบจะแสดง repository ที่ใช้
presetไม่บังคับ
ประเภท
Literal[functions, classes, methods, imports, variables]
คำอธิบาย
ตัวเลือกเชิงโครงสร้างที่แนะนำ ขยายเป็นชนิดโหนด AST ข้ามภาษา — functions (นิยาม function/arrow/method ข้ามภาษา); classes (นิยาม class/struct/impl); methods (นิยาม method (และ function_definition สำหรับภาษาที่ไม่มีโหนด method)); imports (คำสั่ง import/use/include); variables (การประกาศ variable/let/const/static) แนะนำให้ใช้แทน pattern/node_type แบบอิสระสำหรับการค้นหาแบบเรียกดู
patternไม่บังคับ
ประเภท
str
คำอธิบาย
รูปแบบอิสระเมื่อค่าที่ตั้งไว้ล่วงหน้าหยาบเกินไป (ตรวจจับอัตโนมัติ: 'def foo(' → node_type + name_pattern) แนะนำให้ใช้ preset= สำหรับการค้นหาแบบเรียกดู
name_patternไม่บังคับ
ประเภท
str
คำอธิบาย
รูปแบบชื่อสัญลักษณ์ (shell wildcard, POSIX regex แบบมีขอบเขต หรือข้อความแบบ fuzzy; สูงสุด 256 อักขระ)
node_typeไม่บังคับ
ประเภท
str
คำอธิบาย
ชนิดโหนด AST (function_definition, class_definition ฯลฯ) — แนะนำให้ใช้ preset= สำหรับรูปทรงทั่วไป
decoratorไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองชื่อเดคอเรเตอร์
base_classไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองคลาสพื้นฐาน
language_filterไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองภาษา (python, typescript ฯลฯ)
limitไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
20
คำอธิบาย
ผลลัพธ์สูงสุดที่ส่งคืนในหน้านี้
offsetไม่บังคับ
ประเภท
int
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursorไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคง query กับตัวกรองไว้ไม่เปลี่ยนแปลง
path_filterไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามคำนำหน้าเส้นทางไฟล์
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา
query_typeไม่บังคับ
ประเภท
Literal[node_type, name_pattern, parent_child]
คำอธิบาย
ประเภทแบบสอบถามที่ชัดเจน
parent_typeไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองชนิดโหนดพาเรนต์ AST
relationshipไม่บังคับ
ประเภท
Literal[parent, ancestor]
ค่าเริ่มต้น
parent
คำอธิบาย
สำหรับการสืบค้น parent_child: โดยตรงเฉพาะพาเรนต์หรือบรรพบุรุษใด ๆ (ใช้บรรพบุรุษสำหรับเมธอดคลาสที่ซ้อนอยู่ใต้เนื้อหา/บล็อกของคลาส)
has_modifierไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามตัวแก้ไข (ส่งออก, อะซิงก์, คงที่ ฯลฯ)
advancedไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
ตั้งค่า true เมื่อตั้งใจใช้พาธขั้นสูง, ltree หรือตัวกรองการโทร (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name) ตามค่าเริ่มต้น false จะคงอินเทอร์เฟซของตัวแทนเน้นไปที่การตั้งค่าล่วงหน้า คีย์ขั้นสูงในรูปแบบแบนยังคงใช้งานได้สำหรับความเข้ากันได้แบบย้อนหลัง โดยมีคำเตือนข้อมูลเมตา
callee_textไม่บังคับ
ประเภท
str
คำอธิบาย
ระดับสูง — แนะนำให้ใช้ preset=functions|classes|methods|imports|variables ตัวกรองข้อความ callee ของนิพจน์การเรียก ตั้ง advanced=true เมื่อใช้ตัวกรอง path/ltree/call อย่างตั้งใจ
callee_nameไม่บังคับ
ประเภท
str
คำอธิบาย
ระดับสูง — แนะนำให้ใช้ preset=functions|classes|methods|imports|variables ตัวกรองชื่อ callee ของนิพจน์การเรียก ตั้ง advanced=true เมื่อใช้ตัวกรอง path/ltree/call อย่างตั้งใจ
field_roleไม่บังคับ
ประเภท
str
คำอธิบาย
ระดับสูง — แนะนำให้ใช้ preset=functions|classes|methods|imports|variables ตัวกรองบทบาทฟิลด์ AST ตั้ง advanced=true เมื่อใช้ตัวกรอง path/ltree/call อย่างตั้งใจ
ltree_ancestorไม่บังคับ
ประเภท
str
คำอธิบาย
ระดับสูง — แนะนำให้ใช้ preset=functions|classes|methods|imports|variables ตัวกรองเส้นทางบรรพบุรุษ ltree ของ AST ตั้ง advanced=true เมื่อใช้ตัวกรอง path/ltree/call อย่างตั้งใจ
ltree_descendantไม่บังคับ
ประเภท
str
คำอธิบาย
ระดับสูง — แนะนำให้ใช้ preset=functions|classes|methods|imports|variables ตัวกรองเส้นทางลูกหลาน ltree ของ AST ตั้ง advanced=true เมื่อใช้ตัวกรอง path/ltree/call อย่างตั้งใจ
definition_nameไม่บังคับ
ประเภท
str
คำอธิบาย
ระดับสูง — แนะนำให้ใช้ preset=functions|classes|methods|imports|variables ตัวกรองชื่อนิยาม ตั้ง advanced=true เมื่อใช้ตัวกรอง path/ltree/call อย่างตั้งใจ
min_depthไม่บังคับ
ประเภท
int
คำอธิบาย
ระดับสูง — แนะนำให้ใช้ preset=functions|classes|methods|imports|variables ความลึก AST ต่ำสุด ตั้ง advanced=true เมื่อใช้ตัวกรอง path/ltree/call อย่างตั้งใจ
max_depthไม่บังคับ
ประเภท
int
คำอธิบาย
ระดับสูง — แนะนำให้ใช้ preset=functions|classes|methods|imports|variables ความลึก AST สูงสุด ตั้ง advanced=true เมื่อใช้ตัวกรอง path/ltree/call อย่างตั้งใจ

เหมาะสำหรับ:

  • โครงสร้างระดับ AST: คลาส เดคอเรเตอร์ พรีเซ็ตของฟังก์ชัน/เมธอด
  • การค้นหาโค้ดตามรูปทรงแทนที่จะเป็นตามข้อความ

ไม่แนะนำสำหรับ:

  • คำค้นแบบข้อความอิสระหรือเชิงแนวคิด — ใช้ semantic_search หรือ intelligent_search

dependency_searchเสถียร

พื้นผิว blast-radius / กราฟหลัก ตอบ "อะไรเรียกสิ่งนี้?" / "สิ่งนี้ใช้อะไร?" ผ่านกราฟ call/import จริง สำหรับผลกระทบก่อนแก้ไข: analysis_type="dependents" หรือ analysis_type="impact" (incoming, ค่าเริ่มต้น shallow สำหรับ impact), include_metrics=false ตามค่าเริ่มต้น (เลือกเปิดสำหรับ centrality + refactor_risk) ผลกระทบ PR/diff (P1-8): ส่ง changed_paths และ/หรือ patch (unified diff) — จะระบุสัญลักษณ์ต่อเส้นทางและส่งคืนเพย์โหลด dependents แบบ shallow-incoming ที่กระชับโดยไม่ต้องใช้ชื่อสัญลักษณ์ หลังการแก้ไข ตั้ง verify_after_edit=true พร้อม targets และ/หรือ changed_paths เพื่อสอบถามซ้ำแบบหลายรากที่กระชับของสัญลักษณ์ที่ได้รับผลกระทบ ยังรองรับ dependencies, centrality และ orphans อีกด้วย analyze_dependencies เป็น ชื่อแทน บาง ๆ สำหรับเส้นทาง impact — แนะนำให้ใช้เครื่องมือนี้สำหรับเอเจนต์ใหม่

พารามิเตอร์:

repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
Repository ในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือ repository เดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือก repo อื่นที่จัดทำดัชนีไว้ คำตอบจะแสดง repository ที่ใช้
queryไม่บังคับ
ประเภท
str
คำอธิบาย
ชื่อสัญลักษณ์หรือคำค้นหา
targetไม่บังคับ
ประเภท
str
คำอธิบาย
ชื่อสัญลักษณ์ (นามแฝงสำหรับการสืบค้น)
changed_pathsไม่บังคับ
ประเภท
list[str]
คำอธิบาย
พาธที่สัมพันธ์กับ repo สำหรับผลกระทบ PR/diff (ค่าเริ่มต้น) หรือใช้เป็นจุดเริ่มต้นของการตรวจสอบหลังแก้ไขเมื่อ verify_after_edit=true สำหรับ PR/diff: ค้นหาสัญลักษณ์ในแต่ละพาธและเดินตาม dependent ขาเข้าแบบตื้น สามารถใช้ร่วมกับ patch= ได้ สำหรับการตรวจสอบ: ใช้สัญลักษณ์สูงสุด 5 รายการต่อพาธเป็นจุดเริ่มต้น (มีขีดจำกัดต่ำกว่าในโหมดนี้) ไม่จำเป็นต้องใช้ query/target สำหรับผลกระทบ PR/diff
patchไม่บังคับ
ประเภท
str
คำอธิบาย
ผลกระทบ PR/diff: ข้อความแพทช์ diff / git แบบรวม เส้นทางจะถูกแยกวิเคราะห์จากส่วนหัว diff --git / --- / +++ เส้นทางกระแทกขนาดกะทัดรัดเช่นเดียวกับ changed_paths
analysis_typeไม่บังคับ
ประเภท
Literal[centrality, dependencies, dependents, impact, orphans]
ค่าเริ่มต้น
dependencies
คำอธิบาย
โหมดการวิเคราะห์ impact = blast radius (dependents ขาเข้า; ความลึก shallow เมื่อละ depth) dependents ก็ตอบ impact ได้เช่นกัน เมื่อกำหนด changed_paths หรือ patch การวิเคราะห์จะถูกบังคับเป็น PR/diff impact centrality/orphans ไม่ต้องมีเป้าหมาย
depthไม่บังคับ
ประเภท
Literal[shallow, balanced, deep]
ค่าเริ่มต้น
balanced
คำอธิบาย
ความลึกในการเคลื่อนที่ (การไล่กราฟ) สำหรับ analysis_type=impact และ PR/diff impact ค่าเริ่มต้นที่มีผลคือ shallow เว้นแต่คุณจะตั้ง depth อย่างชัดเจน
limitไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
20
คำอธิบาย
ผลลัพธ์สูงสุดที่ส่งคืนในหน้านี้
offsetไม่บังคับ
ประเภท
int
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursorไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคง query กับตัวกรองไว้ไม่เปลี่ยนแปลง
path_filterไม่บังคับ
ประเภท
str
คำอธิบาย
จำกัดการระบุสัญลักษณ์เป้าหมายด้วยคำนำหน้าเส้นทางไฟล์ ความสัมพันธ์ของกราฟที่ส่งคืนอาจข้ามออกนอกเส้นทางนั้น
language_filterไม่บังคับ
ประเภท
str
คำอธิบาย
กรองการระบุเป้าหมายและผลลัพธ์การเรียกดูตามภาษา
directionไม่บังคับ
ประเภท
Literal[outgoing, incoming, both]
คำอธิบาย
ทิศทางการเคลื่อนที่ (แทนที่การอนุมาน analysis_type)
relationship_typesไม่บังคับ
ประเภท
list[str]
คำอธิบาย
กรองชนิดขอบ (CALL, IMPORT, INHERITS_FROM ฯลฯ) รายการที่ไม่ว่างจะแทนที่ค่าเริ่มต้นของ graph_view
exclude_test_pathsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
true
คำอธิบาย
ค่าเริ่มต้น true: ยกเว้นเส้นทาง test, fixture, vendor และ ตัวอย่าง จากผลการเคลื่อนที่และ centrality ตั้ง false เพื่อรวมไว้ การวิเคราะห์ orphan จะใช้การยกเว้นสัญญาณรบกวนที่เข้มงวดกว่าของตัวเองเสมอ
exclude_generated_pathsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
ไม่รวมการประกาศที่สร้างขึ้น รวมถึงบิลด์ การครอบคลุม แคช ซอร์สแมป และพาธอาร์ติแฟกต์ที่ย่อขนาดจากผลลัพธ์การแวะผ่าน
include_module_symbolsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
ตามค่าเริ่มต้น false จะไม่รวมขอบกราฟเมื่อ from_name หรือ to_name เป็นสัญลักษณ์ __module__ สังเคราะห์ (สัญญาณรบกวนระดับโมดูล) ตั้งค่า true เพื่อรวมขอบระดับโมดูลในผลลัพธ์สำหรับความสัมพันธ์แบบพึ่งพาและแบบพึ่งพา
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา
per_hop_limitไม่บังคับ
ประเภท
int
คำอธิบาย
ความสัมพันธ์สูงสุดต่อการกระโดด (1-300)
include_metricsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
เมทริกกราฟที่ต้องเปิดใช้เอง บนแถวผลลัพธ์ (บีบอัดพร้อม refactor_risk) เมทริกยังถูกดึงภายในเมื่อ min_centrality>0 แต่จะไม่ส่งคืนเว้นแต่ค่านี้เป็น true
metrics_detailไม่บังคับ
ประเภท
Literal[summary, full]
ค่าเริ่มต้น
summary
คำอธิบาย
เมื่อ include_metrics=true: summary (ค่าเริ่มต้น) ส่งคืนสัญญาณการตัดสินใจ + refactor_risk; full ส่งคืนชุดเมตริกที่ได้รับการดูแลจัดการที่ใหญ่กว่า
include_edge_metadataไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
รวมข้อมูลเมตาและน้ำหนักของ Raw Edge (ใหญ่) เพย์โหลดการกระแทกขนาดกะทัดรัดทำให้สิ่งนี้หมดไป
symbol_typesไม่บังคับ
ประเภท
list[str]
คำอธิบาย
กรองสัญลักษณ์ที่ส่งคืนตามชนิด (function, class, method ฯลฯ)
exact_matchไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
จำเป็นต้องมีการจับคู่ชื่อสัญลักษณ์ที่ตรงกันทุกประการ
find_similar_patternsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
ค้นหารูปแบบการใช้งานที่คล้ายกัน
min_centralityไม่บังคับ
ประเภท
float
ค่าเริ่มต้น
0
คำอธิบาย
คะแนน PageRank ต่ำสุด เมทริกถูกดึงภายในเพื่อการกรอง; graph_metrics จะส่งคืนเฉพาะเมื่อ include_metrics=true
graph_viewไม่บังคับ
ประเภท
Literal[dependency, type, data_flow, control_flow]
ค่าเริ่มต้น
dependency
คำอธิบาย
มุมมองกราฟที่ใช้สำหรับค่าเริ่มต้นความสัมพันธ์ในการเคลื่อนที่ เมทริก และการจัดอันดับ centrality; การวิเคราะห์ orphan คำนวณข้ามทุกมุมมอง
verify_after_editไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
โหมดตรวจสอบหลังการแก้ไข P2-7: ค้นหากราฟผลกระทบที่จัดทำดัชนีไว้อีกครั้งสำหรับสัญลักษณ์ที่แก้ไขล่าสุดในการตอบกลับหลายรูทขนาดกะทัดรัดเพียงครั้งเดียว ต้องใช้ targets และ/หรือ changed_paths (หรือ target/query) ค่าเริ่มต้นเป็นผู้อยู่ในอุปการะขาเข้าตื้น ผลลัพธ์สะท้อนถึงกราฟที่จัดทำดัชนี (อาจทำให้การแก้ไขสดล่าช้า) เมื่อเป็นจริง จะมีความสำคัญเหนือกว่าผลกระทบ PR/diff บน changed_paths เดียวกัน
targetsไม่บังคับ
ประเภท
list[str]
คำอธิบาย
เมื่อ verify_after_edit=true: ชื่อสัญลักษณ์ที่จะตรวจสอบอีกครั้ง (ผู้โทร/ผู้อยู่ในอุปการะ) รวมเข้ากับ target/query หากมีมาให้ทั้งคู่

เหมาะสำหรับ:

  • การวิเคราะห์รัศมีผลกระทบก่อนแก้ไขสัญลักษณ์ที่ใช้ร่วมกัน
  • ผลกระทบของ PR/diff ผ่าน changed_paths หรือ patch
  • การตรวจสอบหลังแก้ไขผ่าน verify_after_edit

ไม่แนะนำสำหรับ:

  • การค้นหาข้อความหรือสัญลักษณ์อย่างง่าย — ใช้ text_pattern_search หรือ find_symbol

เครื่องมือวิเคราะห์โค้ด#

find_symbolเสถียร

ข้ามไปยังตำแหน่งที่มีการกำหนดและใช้ฟังก์ชัน คลาส หรือตัวแปร ใช้เมื่อคุณทราบชื่อ (เช่น "getCurrentUser") — เร็วกว่าและแม่นยำกว่า Grep และครอบคลุม repo ที่จัดทำดัชนีไว้ทั้งหมด ส่งคืนข้อมูลอ้างอิงและเมตริกความสำคัญหรือไม่ก็ได้

พารามิเตอร์:

symbol_nameไม่บังคับ
ประเภท
str
คำอธิบาย
ชื่อสัญลักษณ์ที่จะค้นหา (ไม่บังคับ — ละเว้นเพื่อเรียกดูตามหน่วยเมตริก)
repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
Repository ในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือ repository เดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือก repo อื่นที่จัดทำดัชนีไว้ คำตอบจะแสดง repository ที่ใช้
scopeไม่บังคับ
ประเภท
Literal[definitions, references, both]
ค่าเริ่มต้น
both
คำอธิบาย
ขอบเขตการค้นหา
limitไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
15
คำอธิบาย
ผลลัพธ์สูงสุดที่ส่งคืนในหน้านี้
offsetไม่บังคับ
ประเภท
int
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursorไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคง query กับตัวกรองไว้ไม่เปลี่ยนแปลง
find_similarไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
รวมชื่อสัญลักษณ์ที่คล้ายกัน
include_metricsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
รวมการวัดศูนย์กลาง
metrics_detailไม่บังคับ
ประเภท
Literal[summary, full]
ค่าเริ่มต้น
summary
คำอธิบาย
เมื่อ include_metrics=true: summary (ค่าเริ่มต้น) ส่งคืนสัญญาณการตัดสินใจ + refactor_risk; full ส่งคืนชุดเมตริกที่ได้รับการดูแลจัดการที่ใหญ่กว่า
path_filterไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามคำนำหน้าเส้นทางไฟล์
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา
symbol_typeไม่บังคับ
ประเภท
Literal[function, class, variable, method, constant, module, interface, type]
คำอธิบาย
กรองตามประเภทสัญลักษณ์
high_impactไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
เรียกดูสัญลักษณ์ที่สำคัญเชิงสถาปัตยกรรม (ละ symbol_name) โหมดเริ่มต้นคือความนิยม (เดไซล์สูงสุดของ PageRank โดยไม่นับฮับอเนกประสงค์ขนาดใหญ่) ตั้ง high_impact_mode=risk สำหรับจุดตัดและสะพานของกราฟ
high_impact_modeไม่บังคับ
ประเภท
Literal[popularity, risk]
ค่าเริ่มต้น
popularity
คำอธิบาย
เมื่อ high_impact=true: ความนิยม = ด้านบน PageRank เดไซล์ ลบยูทิลิตี้ mega-hubs/โมดูล; ความเสี่ยง = จุดประกบจัดอันดับโดย SMV bridge_count จากนั้น k_core (ความเสี่ยงในการปรับโครงสร้างใหม่ ไม่ใช่ความนิยมของฮับ)
in_cycleไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
กรองสัญลักษณ์ในรอบการขึ้นต่อกัน
exclude_test_pathsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
true
คำอธิบาย
เมื่อเรียกดูตามตัวชี้วัดกราฟ ให้ยกเว้นการทดสอบ, fixtures, โค้ดของบุคคลที่สาม และตัวอย่างก่อนการจัดอันดับ การค้นหาด้วยสัญลักษณ์ที่มีชื่อไม่มีการเปลี่ยนแปลง

เหมาะสำหรับ:

  • การระบุนิยาม การอ้างอิง และเมตริกกราฟของสัญลักษณ์ที่ทราบ
  • การเรียกดูตาม centrality, high_impact หรือ in_cycle เมื่อละ symbol_name ไว้

ไม่แนะนำสำหรับ:

  • คำค้นเชิงแนวคิดหรือพื้นที่ที่ไม่ทราบ — ใช้ intelligent_search หรือ semantic_search

analyze_dependenciesเสถียร

นามแฝงสำหรับ blast-radius ผ่าน dependency_search (dependents/incoming) แนะนำให้ใช้ dependency_search พร้อม analysis_type="dependents" หรือ "impact" สำหรับเอเจนต์ใหม่ คงรูปแบบการตอบสนอง impact แบบหลายฮอปดั้งเดิม (graph, connection_summary, เมทริกทางเลือกพร้อม refactor_risk) ใช้ graph_view เพื่อกำหนดขอบเขตตระกูลความสัมพันธ์: dependency (ค่าเริ่มต้น), type, data_flow, control_flow

พารามิเตอร์:

repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
Repository ในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือ repository เดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือก repo อื่นที่จัดทำดัชนีไว้ คำตอบจะแสดง repository ที่ใช้
targetจำเป็น
ประเภท
str
คำอธิบาย
ชื่อสัญลักษณ์ที่จะวิเคราะห์
depthไม่บังคับ
ประเภท
Literal[shallow, balanced, deep]
ค่าเริ่มต้น
balanced
คำอธิบาย
ความลึกของการวิเคราะห์
limitไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
10
คำอธิบาย
ผลลัพธ์สูงสุดที่ส่งคืนในหน้านี้
offsetไม่บังคับ
ประเภท
int
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursorไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคง query กับตัวกรองไว้ไม่เปลี่ยนแปลง
directionไม่บังคับ
ประเภท
Literal[incoming, outgoing, both]
ค่าเริ่มต้น
incoming
คำอธิบาย
ทิศทางการเคลื่อนที่
relationship_typesไม่บังคับ
ประเภท
list[str]
คำอธิบาย
ประเภทขอบฟิลเตอร์ (CALL, IMPORT, INHERITS_FROM ฯลฯ) จะแทนที่ค่าเริ่มต้นที่ได้รับจาก graph_view ด้านล่างเสมอเมื่อมีให้มา
graph_viewไม่บังคับ
ประเภท
Literal[dependency, type, data_flow, control_flow]
ค่าเริ่มต้น
dependency
คำอธิบาย
มุมมองกราฟ: กำหนดทั้งชนิดเอดจ์เริ่มต้นสำหรับการสำรวจและเมตริกของมุมมองที่จะใช้เมื่อ include_metrics=true โดย dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (ค่าเริ่มต้น), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO] และ control_flow=[CONTROL_FLOW,THROWS,CATCHES] ค่านี้ใช้เป็นค่าเริ่มต้นของ relationship_types เฉพาะเมื่อไม่ได้ระบุ relationship_types อย่างชัดเจนเท่านั้น และใช้ชื่อพารามิเตอร์ graph_view เดียวกับ dependency_search เพื่อให้เครื่องมือต่าง ๆ สอดคล้องกัน
path_filterไม่บังคับ
ประเภท
str
คำอธิบาย
จำกัดการระบุสัญลักษณ์เป้าหมายด้วยคำนำหน้าเส้นทางไฟล์ ความสัมพันธ์ของกราฟที่ส่งคืนอาจข้ามออกนอกเส้นทางนั้น
language_filterไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองภาษา
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา
per_hop_limitไม่บังคับ
ประเภท
int
คำอธิบาย
ความสัมพันธ์สูงสุดต่อการกระโดด (1-300)
include_metricsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
รวมตัวชี้วัดกราฟในผลลัพธ์ โดยแต่ละรายการเสริมด้วยบล็อก refactor_risk ที่ได้รับ ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}) ความเสี่ยงคือ "low" เมื่อไม่ใช่จุดประกบ (ในมุมมองที่เลือก) "medium" เมื่อจุดประกบเชื่อมขอบบางส่วน "high" เมื่อเชื่อมต่อหลายจุด (เกณฑ์การศึกษาพฤติกรรม ไม่ผ่านการตรวจสอบเชิงประจักษ์) ละเว้นต่อสัญลักษณ์เมื่อไม่มีแถวเมตริกสำหรับสัญลักษณ์/มุมมองนั้น
metrics_detailไม่บังคับ
ประเภท
Literal[summary, full]
ค่าเริ่มต้น
summary
คำอธิบาย
เมื่อ include_metrics=true: summary (ค่าเริ่มต้น) ส่งคืนสัญญาณการตัดสินใจ + refactor_risk; full ส่งคืนชุดเมตริกที่ได้รับการดูแลจัดการที่ใหญ่กว่า
include_edge_metadataไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
รวมข้อมูลเมตาและน้ำหนักของ Raw Edge ปิดใช้งานตามค่าเริ่มต้นเนื่องจากข้อมูลเมตาของตัวแยกข้อมูลอาจมีขนาดใหญ่ ความครอบคลุมของการเพิ่มคุณค่าจะถูกรายงานเมื่อเปิดใช้งาน
exclude_test_pathsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
true
คำอธิบาย
ค่าเริ่มต้น true: ไม่รวมการทดสอบ ฟิกซ์เจอร์ ผู้จำหน่าย และเส้นทางตัวอย่างจากขอบกราฟที่ส่งคืน ตั้งค่า false เพื่อรวมไว้
include_module_symbolsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
ตามค่าเริ่มต้น false จะไม่รวมขอบกราฟเมื่อ from_name หรือ to_name เป็นสัญลักษณ์ __module__ สังเคราะห์ ตั้งค่า true เพื่อรวมขอบระดับโมดูล

เหมาะสำหรับ:

  • ผู้เรียกใช้แบบเดิมที่เชื่อมกับรูปแบบการตอบสนองของมันอยู่แล้ว (graph, connection_summary)

ไม่แนะนำสำหรับ:

  • ลูปเอเจนต์ใหม่ — ควรใช้ dependency_search ซึ่งใช้แกนการท่องกราฟเดียวกัน

get_task_contextเสถียร

เริ่มงานในพื้นที่ที่ไม่คุ้นเคยใช่ไหม? อธิบายงาน (เช่น "เพิ่มการรองรับ SSO", "แก้ไข webhook การเรียกเก็บเงิน") แล้วรับชุดรวมแบบเรียกครั้งเดียวที่มีขอบเขตของไฟล์ โค้ด สัญลักษณ์ และ dependencies ที่เกี่ยวข้อง ไฟล์ตั้งต้น ให้เนื้อหาที่จัดทำดัชนีโดยตรง แม้จะไม่ได้นิยามสัญลักษณ์ใด ๆ หากต้องการผลลัพธ์เพิ่มเติม ให้ดำเนินการต่อด้วยเครื่องมือค้นหาเฉพาะสำหรับชั้นนั้น

พารามิเตอร์:

task_descriptionจำเป็น
ประเภท
str
คำอธิบาย
คำอธิบายของงานที่คุณต้องการบริบท
repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
Repository ในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือ repository เดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือก repo อื่นที่จัดทำดัชนีไว้ คำตอบจะแสดง repository ที่ใช้
limitไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
15
คำอธิบาย
ผลลัพธ์สูงสุดต่อเลเยอร์
scopeไม่บังคับ
ประเภท
Literal[semantic, symbols, dependencies, all]
ค่าเริ่มต้น
all
คำอธิบาย
เลเยอร์บริบทใดที่จะรวมไว้
language_filterไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองภาษา
path_filterไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามคำนำหน้าเส้นทางไฟล์
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา
include_related_contextไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
รวมบริบทที่เกี่ยวข้องจากสัญลักษณ์ที่อยู่ติดกัน
seed_symbol_idsไม่บังคับ
ประเภท
list[str]
คำอธิบาย
เมล็ดเริ่มต้นที่ระบุชัดเจนระดับ Tier-1: ID สัญลักษณ์ที่ agent รู้อยู่แล้วว่าเป็นแกนหลักของงาน (เช่น สัญลักษณ์ในไฟล์ที่เปิดอยู่) จัดอันดับก่อนเมล็ดที่ได้จากคีย์เวิร์ดในเลเยอร์ dependencies/related_context เป็นข้อมูลเพิ่มเติม — ไม่ต้องระบุหากต้องการพฤติกรรมปัจจุบันที่ใช้คีย์เวิร์ดเท่านั้น
seed_file_pathsไม่บังคับ
ประเภท
list[str]
คำอธิบาย
เมล็ดพันธุ์ระบุชัดเจน Tier-1: เส้นทางไฟล์ที่จัดทำดัชนีซึ่งเอเจนต์เปิดอยู่หรือเพิ่งแก้ไข ส่งคืนหลักฐานไฟล์โดยตรงแบบมีขอบเขตและระบุสัญลักษณ์ได้สูงสุด 5 รายการต่อไฟล์สำหรับบริบทกราฟ รวมถึงเอกสารและ config ที่ไม่มีสัญลักษณ์ เป็นแบบเพิ่มเติม — ละไว้เพื่อพฤติกรรมแบบใช้คีย์เวิร์ดเท่านั้น

เหมาะสำหรับ:

  • บริบทที่คำนึงถึงงานซึ่งผสานไฟล์ตั้งต้นกับชั้นเชิงความหมาย สัญลักษณ์ และการพึ่งพา

ไม่แนะนำสำหรับ:

  • การค้นหาด้วยเครื่องมือเดียวที่เครื่องมือเฉพาะเจาะจงกว่าตอบคำถามได้อยู่แล้ว

get_fileเสถียร

อ่านไฟล์จาก repo ที่จัดทำดัชนีตามเส้นทาง แนะนำให้ใช้เครื่องมือ Read ภายในเครื่องสำหรับไฟล์บนดิสก์ — ใช้สิ่งนี้สำหรับการค้นหาข้าม repo หรือระยะไกลที่ไฟล์ไม่ได้อยู่ในเวิร์กกิงทรีของคุณ รองรับช่วงบรรทัดที่เป็นทางเลือก; ดำเนินการต่อจากการตอบสนองที่ถูกตัดด้วยโทเคนจาก metadata.next_line_start

พารามิเตอร์:

file_pathจำเป็น
ประเภท
str
คำอธิบาย
พาธของไฟล์สัมพันธ์กับรูทของที่เก็บ
repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
Repository ในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือ repository เดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือก repo อื่นที่จัดทำดัชนีไว้ คำตอบจะแสดง repository ที่ใช้
line_startไม่บังคับ
ประเภท
int
คำอธิบาย
เส้นเริ่มต้น (ดัชนี 1)
line_endไม่บังคับ
ประเภท
int
คำอธิบาย
บรรทัดสิ้นสุด (เริ่มดัชนีที่ 1, รวมปลาย; ต้องอยู่ที่หรือหลัง line_start)
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา
max_tokensไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
5000
คำอธิบาย
โทเค็นสูงสุดที่จะส่งคืน
include_metadataไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
true
คำอธิบาย
รวมข้อมูลเมตาของไฟล์ในการตอบกลับ

เหมาะสำหรับ:

  • สแนปช็อตไฟล์ระยะไกลหรือที่จัดทำดัชนีแล้ว (ช่วงบรรทัด ขีดจำกัดโทเค็น)

ไม่แนะนำสำหรับ:

  • พาธที่อยู่บนดิสก์ในเครื่องแล้ว — ใช้เครื่องมือ Read ในเครื่อง

เครื่องมือระบบและยูทิลิตี#

repository_contextเสถียร

แสดงรายการรีโพซิทอรีที่คุณสามารถค้นหาได้ หรือรับข้อมูลระบุตัวตนของหนึ่งรายการ (namespace/branch, indexed_commit_sha / ความสดของดัชนี) เรียกด้วย action:"list" หนึ่งครั้งเพื่อทราบ repo slug ที่แน่นอนซึ่งเครื่องมือค้นหายอมรับ (หากคีย์ของคุณมี repo เดียว เครื่องมือค้นหาจะใช้เป็นค่าเริ่มต้น — คุณข้ามขั้นตอนนี้ได้) จำนวน file/blob/edge ทั่วทั้ง namespace เป็นแบบเลือกเปิดผ่าน include_statistics=true

พารามิเตอร์:

actionจำเป็น
ประเภท
Literal[list, info]
คำอธิบาย
การดำเนินการ: ใช้ list เพื่อแสดง repo ที่เข้าถึงได้ หรือใช้ info เพื่อดูข้อมูล repo
repositoryไม่บังคับ
ประเภท
str
คำอธิบาย
พื้นที่เก็บโค้ดในรูปแบบ owner/repo หรือ owner/repo:branch (ต้องระบุเมื่อใช้ info)
branchไม่บังคับ
ประเภท
str
คำอธิบาย
การแทนที่สาขา
patternไม่บังคับ
ประเภท
str
คำอธิบาย
กรองรายการพื้นที่เก็บข้อมูลตามรูปแบบ
include_statisticsไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
คำอธิบาย
เลือกเปิดใช้: รวมจำนวนข้อมูลที่จัดทำดัชนีทั่วทั้ง namespace (file/blob/edge) ค่าเริ่มต้น false — การระบุตัวตนรีโพซิทอรีไม่จำเป็นต้องใช้การรวมที่ช้ากว่านี้
limitไม่บังคับ
ประเภท
int
ค่าเริ่มต้น
20
คำอธิบาย
ผลลัพธ์สูงสุดที่ส่งคืนในหน้านี้
offsetไม่บังคับ
ประเภท
int
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว ชอบ cursor จาก pagination.next_cursor
cursorไม่บังคับ
ประเภท
str
คำอธิบาย
ทึบแสง cursor จาก pagination.next_cursor ส่งต่อโดยไม่มีการเปลี่ยนแปลง และคงข้อความค้นหาและตัวกรองไว้ไม่เปลี่ยนแปลง

เหมาะสำหรับ:

  • การแสดงรายการที่เก็บโค้ดที่เข้าถึงได้
  • การระบุตัวตนของที่เก็บโค้ด แบรนช์ และความสดใหม่ของ HEAD-vs-ดัชนี

ไม่แนะนำสำหรับ:

  • สถิติทั่วทั้งเนมสเปซโดยค่าเริ่มต้น — ส่ง include_statistics=true อย่างชัดเจน เนื่องจากอาจช้ากว่าการระบุตัวตน

ask_maguyvaเสถียร

ความช่วยเหลือและข้อเสนอแนะของ Maguyva หลัก: รับคำแนะนำเครื่องมือ หรือส่งรายงานข้อบกพร่อง / คำขอฟีเจอร์ที่จัดเก็บไว้สำหรับผู้ดูแล Maguyva อย่าใส่ความลับหรือข้อมูลส่วนบุคคลที่ละเอียดอ่อนในข้อเสนอแนะเด็ดขาด การดำเนินการ evaluate ยังคงอยู่เพื่อความเข้ากันได้ย้อนหลังเท่านั้น — แนะนำให้ใช้การประมวลผลภายในเครื่องหรือเครื่องมือโฮสต์สำหรับงานคณิต/hash/สตริง

พารามิเตอร์:

operationจำเป็น
ประเภท
Literal[guidance, report_bug, request_feature, evaluate]
คำอธิบาย
หลัก: guidance, report_bug, request_feature เฉพาะดั้งเดิม/เข้ากันได้ย้อนหลัง: evaluate (เอนจินนิพจน์แบบกำหนดได้แน่นอน; ไม่ใช่ส่วนหนึ่งของเวิร์กโฟลว์เอเจนต์หลัก)
queryไม่บังคับ
ประเภท
str
คำอธิบาย
หัวข้อคำแนะนำ (เช่น tool_selection, semantic_search) สำหรับ evaluate ดั้งเดิมเท่านั้น: สตริงนิพจน์
descriptionไม่บังคับ
ประเภท
str
คำอธิบาย
จำเป็นสำหรับ report_bug และ request_feature ข้อเสนอแนะรูปแบบอิสระสำหรับผู้ดูแล Maguyva อย่าใส่ความลับหรือข้อมูลส่วนบุคคลที่ละเอียดอ่อนเด็ดขาด
related_toolไม่บังคับ
ประเภท
Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
คำอธิบาย
เครื่องมือเสริม Maguyva ที่เกี่ยวข้องกับความคิดเห็นมากที่สุด

เหมาะสำหรับ:

  • คำแนะนำการใช้เครื่องมือ (operation="guidance")
  • รายงานข้อบกพร่องและคำขอฟีเจอร์ที่คงทนสำหรับผู้ดูแล Maguyva

ไม่แนะนำสำหรับ:

  • การคำนวณคณิตศาสตร์/แฮช/สตริง — การดำเนินการ evaluate เป็นแบบเดิม/เพื่อความเข้ากันได้ย้อนหลังเท่านั้น ควรใช้การประมวลผลบนโฮสต์ในเครื่อง

แนวทางปฏิบัติที่ดี#

  1. ใช้การแทนที่แบบระบุชัดเจนอย่างรอบคอบ: ไม่ต้องระบุ repository เมื่อไคลเอนต์ MCP กำหนดค่าเริ่มต้นสำหรับคำขอนั้น หรือเมื่อคีย์เข้าถึงได้เพียง repository เดียวเท่านั้น มิฉะนั้นให้ส่งค่าอย่างชัดเจน
  2. เลือกโหมดการค้นหาที่เหมาะสม: ใช้ intelligent_search กับ mode="auto" สำหรับกรณีส่วนใหญ่ ระบุโหมดเมื่อคุณรู้แน่ชัดว่าต้องการอะไร
  3. ใช้ประโยชน์จากตัวกรองภาษา: ใช้ language_filter เพื่อจำกัดผลลัพธ์ให้แคบลงและปรับปรุงประสิทธิภาพ
  4. GraphRAG บูสต์: การเพิ่มความสำคัญด้วย GraphRAG ถูกปิดใช้งานตามค่าเริ่มต้นสำหรับการค้นหาเชิงความหมาย (boost_by_importance=false) เพื่อให้การจัดอันดับปลอดภัยต่อเอเจนต์ ส่ง boost_by_importance=true เพื่อเปิดใช้การจัดอันดับใหม่ที่คำนึงถึงความเป็นศูนย์กลางสำหรับการสำรวจสถาปัตยกรรม
  5. การจับคู่ repository ไม่คำนึงถึงตัวพิมพ์ใหญ่-เล็ก ไม่ใช่แบบ fuzzy: repository_context จับคู่ชื่อ repository โดยไม่คำนึงถึงตัวพิมพ์ใหญ่-เล็ก — แต่ไม่แก้ไขการพิมพ์ผิด ตรวจสอบ metadata.resolution_reason ในแอ็กชัน info ("exact" เทียบกับ "corrected") เพื่อดูว่าชื่อถูกรีโซลฟ์อย่างไร
  6. รวมเครื่องมือ: ใช้ API หลายวิธีร่วมกันเพื่อการวิเคราะห์ที่ครอบคลุม
  7. จัดการผลลัพธ์จำนวนมาก: ใช้ limit และการควบคุมเพจเฉพาะเครื่องมือ (เช่น line_start/line_end ใน get_file)
  8. ใช้ ask_maguyva สำหรับคำแนะนำเครื่องมือ: การดำเนินการ evaluate ของ ask_maguyva (hash, base64, JSON, คณิตศาสตร์) เป็นของเดิม/เพื่อความเข้ากันได้ย้อนหลังเท่านั้น ให้เรียก ask_maguyva ด้วย operation="guidance" และ query="tool_selection" แทน เพื่อรับเมทริกซ์ "เครื่องมือในเครื่องชนะ" และชีตสรุปแบบเครื่องมือต่อเครื่องมือฉบับเต็ม
  9. ตรวจสอบผลกระทบทั้งก่อนและหลังการแก้ไข: ก่อนแก้ไขสัญลักษณ์ที่ใช้ร่วมกัน ให้เรียก dependency_search ด้วย analysis_type="impact" (หรือส่ง changed_paths สำหรับผลกระทบของ PR/diff) เพื่อดูรัศมีผลกระทบ หลังแก้ไข ให้ตั้ง verify_after_edit=true พร้อม targets และ/หรือ changed_paths เพื่อตรวจสอบสัญลักษณ์เดิมซ้ำอย่างกระชับ

คุณลักษณะด้านประสิทธิภาพ#

การดำเนินการหมายเหตุด้านประสิทธิภาพ
การค้นหาเชิงความหมายต่ำกว่า 1 วินาที แต่มีการเรียก API เวกเตอร์ฝังตัวแบบสดทุกครั้ง (ไม่ได้แคช) — ควรคาดว่าจะมีเวลาแฝงเพิ่มเติมนอกเหนือจากการสืบค้นเวกเตอร์
การค้นหาข้อความต่ำกว่า 1 วินาทีสำหรับ exact/regex ส่วนการค้นหาเนื้อหาแบบ fuzzy จะแบ่งหน้าที่ฝั่งไคลเอนต์ ดังนั้นออฟเซ็ตที่ลึกจะมีต้นทุนสูงขึ้น — จำกัดให้แคบลงด้วย path_filter/language_filter
การค้นหาเชิงโครงสร้างจัดทำดัชนีด้วย AST — ต้นทุนแปรผันตามปริมาณผลลัพธ์ ไม่ใช่ขนาดของ repository
การค้นหาการพึ่งพาต้นทุนแปรผันตามความลึก — ควรเลือก depth="shallow" เว้นแต่คุณต้องการบริบทแบบหลายฮอป โดย per_hop_limit จะจำกัดการกระจายออก
การดึงไฟล์เกือบทันทีสำหรับไฟล์เดียว — แบ่งหน้าไฟล์ขนาดใหญ่ด้วย line_start/line_end หรือ max_tokens แทนการดึงครั้งเดียวขนาดใหญ่
บริบทรีโพซิทอรีการรีโซลฟ์เนมสเปซถูกแคชเฉพาะต่อคำขอเท่านั้น ไม่ใช่ข้ามการเรียก — การเรียกใช้เครื่องมือทุกครั้งจะรีโซลฟ์ใหม่
ask_maguyva (guidance / evaluate)เกือบทันที — ทำงานภายใน Worker โดยไม่มีการเรียกฐานข้อมูล

การจัดการข้อผิดพลาด#

เมธอด API ทั้งหมดส่งคืนซองข้อมูล (envelope) แบบมีโครงสร้าง:

  • status: สตริง — "success" หรือ "error" สัญญาณการจับคู่ที่ลดทอนและความสดใหม่จะอยู่ในฟิลด์ซ้อน เช่น metadata.resolution_reason บน repository_context หรือ metadata.index_freshness.status
  • tool: ชื่อของเครื่องมือที่สร้างการตอบสนองนี้
  • data: เพย์โหลดผลลัพธ์เมื่อสำเร็จ (โครงสร้างแตกต่างกันไปตามเครื่องมือ)
  • error: อ็อบเจ็กต์ข้อผิดพลาดแบบมีโครงสร้างเมื่อ status เป็น "error" — ประกอบด้วย type, message, suggestions และ recovery_actions
  • metadata: ข้อมูลเพิ่มเติมเกี่ยวกับการดำเนินการ (การกำหนดเส้นทาง การแคช การปรับพารามิเตอร์)
  • pagination: ปรากฏในการตอบสนองแบบรายการ — ประกอบด้วย has_more และ next_cursor

ตรวจสอบฟิลด์ status เสมอก่อนประมวลผลผลลัพธ์ — ค่าของมันมีเพียง "success" หรือ "error" เท่านั้น สำหรับสัญญาณการจับคู่ที่ลดทอนหรือความสดใหม่ ให้อ่านฟิลด์ซ้อนแทน: metadata.resolution_reason บน repository_context หรือ metadata.index_freshness.status (known/partial/unknown/unavailable)

เริ่มต้นใช้งาน#

  1. กำหนดค่าไคลเอ็นต์ MCP: ชี้ไคลเอ็นต์ MCP ของคุณไปที่จุดสิ้นสุดเซิร์ฟเวอร์ Maguyva
  2. ยืนยันการเข้าถึงพื้นที่เก็บข้อมูล: ใช้ repository_context พร้อมรายการหรือข้อมูลเพื่อตรวจสอบที่เก็บข้อมูลที่มีให้กับคีย์ API
  3. เริ่มการค้นหา: เริ่มต้นด้วย intelligent_search และสำรวจเครื่องมือพิเศษตามต้องการ
  4. รวมเครื่องมือ: ใช้เครื่องมือหลายอย่างร่วมกันเพื่อการวิเคราะห์โค้ดที่ครอบคลุม

สำหรับคำแนะนำการติดตั้งใช้งานโดยละเอียด ดูที่ คู่มือการติดตั้ง