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

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

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

ภาพรวม API

#

เครื่องมือแบ่งออกเป็น 4 หมวดหมู่:

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

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

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

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

#

ใช้รูปแบบเหล่านี้เมื่อระบุรีโพซิทอรี:

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

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

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

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

#

ใช้ language_filter ในโหมดค้นหาที่รองรับ สำหรับ text_pattern_search ให้เลือก search_scope="content" ส่วน get_task_context ให้ใช้ scope="semantic" โดยไม่มีจุดเริ่มต้นหรือบริบทที่เกี่ยวข้อง

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

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

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

#

intelligent_search เสถียร

เริ่มที่นี่สำหรับทุกคำถามเกี่ยวกับฐานโค้ด ค่าเริ่มต้น auto/balanced ส่งคำถามที่ระบุได้อย่างมั่นใจว่าเกี่ยวกับนิยามไปยังการค้นหาเชิงโครงสร้าง ส่งคำถามเกี่ยวกับการอ้างอิงหรือผลกระทบไปยังกราฟ และส่งคำถามที่ต้องการผลตรงกันทุกประการไปยังการค้นหาข้อความ คำถามอื่นใช้ความหมายและข้อความที่จัดทำดัชนีแล้ว ใช้ mode=hybrid หรือ auto ร่วมกับ quality=thorough เพื่อขอใช้รูปแบบการค้นหาทั้งสี่แบบ โดยโหมดที่ระบุไว้อย่างชัดเจนจะมีผลเหนือ quality ส่วน language_filter จะตัดกราฟออกจาก auto/hybrid และปฏิเสธการระบุ mode=graph อย่างชัดเจน เลือกใช้เครื่องมือนี้แทน Grep/Glob เมื่อยังไม่ทราบเส้นทาง

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

query จำเป็น
ประเภท
str minLength=1
คำอธิบาย
คำค้นหา
repository ไม่บังคับ
ประเภท
str
คำอธิบาย
รีโพซิทอรีในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือรีโพซิทอรีเดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือกรีโพอื่นที่จัดทำดัชนีไว้ ระบบจะให้ความสำคัญกับแบรนช์ที่จัดทำดัชนีตรงกันพอดี หากแบรนช์ที่ต้องการไม่พร้อมใช้งาน อาจย้อนกลับไปใช้ main หรือแบรนช์เดียวที่เข้าถึงได้ เมทาดาทาของการตอบกลับจะแสดงตัวตนที่ร้องขอและตัวตนที่ใช้จริง พร้อมแจ้งเตือนเมื่อเกิดการย้อนกลับดังกล่าว
mode ไม่บังคับ
ประเภท
Literal[auto, hybrid, semantic, text, structural, ast, graph]
ค่าเริ่มต้น
auto
คำอธิบาย
โหมดค้นหา
limit ไม่บังคับ
ประเภท
int minimum=1, maximum=50
ค่าเริ่มต้น
10
คำอธิบาย
ผลลัพธ์สูงสุดในหน้าต่าง top-K ที่จัดอันดับนี้
language_filter ไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองภาษา
path_filter ไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตัวเลือกสำหรับการค้นคืนตามพรีฟิกซ์ของพาธไฟล์ โหนดข้างเคียงในกราฟและบริบทของชุมชนที่แนบมาอาจรวมไฟล์ที่อยู่นอกพรีฟิกซ์นี้
boost_by_importance ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
เลือกเปิดใช้: จัดอันดับใหม่ตามความเป็นศูนย์กลาง (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
ค่าเริ่มต้น
false
คำอธิบาย
รวมคำอธิบายการตัดสินใจเกี่ยวกับเส้นทาง
importance_weight ไม่บังคับ
ประเภท
float minimum=0, maximum=1
ค่าเริ่มต้น
0.3
คำอธิบาย
น้ำหนักเพื่อเพิ่มความสำคัญ (0=ไม่มี, 1=เต็ม)
orphans ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
รวมสัญลักษณ์ที่ไม่มีการอ้างอิงขาเข้า
include_community_context ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
รวมสัญลักษณ์ที่เกี่ยวข้องจากชุมชนโค้ดเดียวกัน
community_depth ไม่บังคับ
ประเภท
int minimum=1, maximum=3
ค่าเริ่มต้น
1
คำอธิบาย
ความลึกของการขยายบริบทชุมชน
graph_view ไม่บังคับ
ประเภท
Literal[dependency, type, data_flow, control_flow]
ค่าเริ่มต้น
dependency
คำอธิบาย
มุมมองกราฟสำหรับเมตริก
seed_symbol_ids ไม่บังคับ
ประเภท
list[str] maxItems=20
คำอธิบาย
จุดตั้งต้นของงาน Tier-1: รหัสสัญลักษณ์ที่เป็นศูนย์กลางของงานปัจจุบัน เมื่อตั้งค่าแล้ว จะจัดลำดับผลลัพธ์ที่รวมกันใหม่ตามความใกล้เคียงแบบ depth-decay ของ Approach A (การจับคู่จุดตั้งต้นที่ตรงกันทุกประการและจำนวนก้าวบนขอบกราฟ) เป็นตัวเลือกเสริม — ละเว้นเพื่อใช้การจัดอันดับโดยรวม
seed_file_paths ไม่บังคับ
ประเภท
list[str] maxItems=10
คำอธิบาย
จุดตั้งต้นของงาน Tier-1: พาธไฟล์ที่จัดทำดัชนีซึ่งเอเจนต์เปิดหรือเพิ่งแก้ไข เมื่อตั้งค่าแล้ว จะจัดลำดับผลลัพธ์ที่รวมกันใหม่ตามความใกล้เคียงของพาธด้วย 1/(1+d) depth-decay (ไฟล์เดียวกัน → ไดเรกทอรีเดียวกัน → แพ็กเกจใกล้เคียง) เป็นตัวเลือกเสริม — ละเว้นเพื่อใช้การจัดอันดับโดยรวม

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

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

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

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

semantic_search เสถียร

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

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

query จำเป็น
ประเภท
str minLength=1
คำอธิบาย
คำค้นหา (ตามแนวคิด ตามความหมาย)
repository ไม่บังคับ
ประเภท
str
คำอธิบาย
รีโพซิทอรีในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือรีโพซิทอรีเดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือกรีโพอื่นที่จัดทำดัชนีไว้ ระบบจะให้ความสำคัญกับแบรนช์ที่จัดทำดัชนีตรงกันพอดี หากแบรนช์ที่ต้องการไม่พร้อมใช้งาน อาจย้อนกลับไปใช้ main หรือแบรนช์เดียวที่เข้าถึงได้ เมทาดาทาของการตอบกลับจะแสดงตัวตนที่ร้องขอและตัวตนที่ใช้จริง พร้อมแจ้งเตือนเมื่อเกิดการย้อนกลับดังกล่าว
limit ไม่บังคับ
ประเภท
int minimum=1, maximum=50
ค่าเริ่มต้น
5
คำอธิบาย
ผลลัพธ์สูงสุดในหน้าต่าง top-K ที่จัดอันดับนี้
similarity_threshold ไม่บังคับ
ประเภท
float minimum=0, maximum=1
ค่าเริ่มต้น
0.6
คำอธิบาย
คะแนนความคล้ายคลึงกันขั้นต่ำ
language_filter ไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองภาษา (python, typescript ฯลฯ)
path_filter ไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามคำนำหน้าเส้นทางไฟล์
boost_by_importance ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
เลือกเปิดได้: จัดอันดับใหม่ตามความสำคัญในกราฟที่ปรับมาตรฐานต่อสัญลักษณ์ (ปิดเป็นค่าเริ่มต้น จำกัดที่ 1.5 เท่าของความคล้ายคลึง)
branch ไม่บังคับ
ประเภท
str
คำอธิบาย
ระบุแบรนช์เพื่อแทนค่าเริ่มต้น (ค่าเริ่มต้น: จากพารามิเตอร์ repository หรือ main)
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 ค้นหาในคลังส่วนโค้ดเชิงความหมายที่จำกัดขอบเขต ขอบเขต file และสัญลักษณ์ใช้ได้เฉพาะไตรแกรม โดยค่าเริ่มต้น mode=exact จะถูกเปลี่ยนเป็น fuzzy การควบคุมภาษา ตัวพิมพ์ และเกณฑ์ที่กำหนดเองต้องใช้ขอบเขต content ตัวกรองพาธใช้หน้าต่างรายการผู้สมัครที่จำกัดและรายงานเมื่อครอบคลุมไม่ครบ ใช้ Grep ในเครื่องสำหรับไดเรกทอรีขอบเขตแคบที่มีอยู่บนดิสก์แล้ว

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

query จำเป็น
ประเภท
str minLength=1
คำอธิบาย
รูปแบบข้อความที่จะค้นหา
repository ไม่บังคับ
ประเภท
str
คำอธิบาย
รีโพซิทอรีในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือรีโพซิทอรีเดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือกรีโพอื่นที่จัดทำดัชนีไว้ ระบบจะให้ความสำคัญกับแบรนช์ที่จัดทำดัชนีตรงกันพอดี หากแบรนช์ที่ต้องการไม่พร้อมใช้งาน อาจย้อนกลับไปใช้ main หรือแบรนช์เดียวที่เข้าถึงได้ เมทาดาทาของการตอบกลับจะแสดงตัวตนที่ร้องขอและตัวตนที่ใช้จริง พร้อมแจ้งเตือนเมื่อเกิดการย้อนกลับดังกล่าว
mode ไม่บังคับ
ประเภท
Literal[fuzzy, exact, regex]
ค่าเริ่มต้น
exact
คำอธิบาย
โหมดการค้นหา Regex ทำงานด้วยไวยากรณ์ขั้นสูง/POSIX ของ PostgreSQL ใช้ \y สำหรับขอบเขตคำ (\b หมายถึงอักขระแบ็กสเปซ) รูปแบบยังต้องผ่านตัวตรวจสอบความปลอดภัยของ JavaScript ด้วย ดังนั้นโครงสร้างเฉพาะของ PostgreSQL เช่นแฟล็ก (?i) แบบอินไลน์จะถูกปฏิเสธ ให้ใช้ case_sensitive แทน
search_scope ไม่บังคับ
ประเภท
Literal[content, symbols, files]
ค่าเริ่มต้น
content
คำอธิบาย
สิ่งที่ต้องค้นหา
limit ไม่บังคับ
ประเภท
int minimum=1, maximum=50
ค่าเริ่มต้น
5
คำอธิบาย
จำนวนผลลัพธ์สูงสุดต่อหน้าเมื่อไม่ใช้ cursor การดำเนินการต่อจะใช้ขนาดหน้าที่เก็บไว้ใน cursor ละเว้น cursor เพื่อเริ่มต้นด้วย limit ที่ต่างออกไป
offset ไม่บังคับ
ประเภท
int minimum=0
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursor ไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคงค่า query และตัวกรองไว้เหมือนเดิม ตำแหน่งและขนาดหน้าของ cursor นี้มีความสำคัญเหนือกว่า offset และ limit
language_filter ไม่บังคับ
ประเภท
str
คำอธิบาย
ตัวกรองภาษา
path_filter ไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามคำนำหน้าเส้นทางไฟล์
case_sensitive ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
การจับคู่แบบคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
branch ไม่บังคับ
ประเภท
str
คำอธิบาย
ระบุแบรนช์เพื่อแทนค่าเริ่มต้น
fuzzy_algorithm ไม่บังคับ
ประเภท
Literal[hybrid, trigram, levenshtein]
ค่าเริ่มต้น
hybrid
คำอธิบาย
อัลกอริธึมการจับคู่แบบคลุมเครือ
threshold ไม่บังคับ
ประเภท
float minimum=0, maximum=1
ค่าเริ่มต้น
0.05
คำอธิบาย
เกณฑ์ความคล้ายคลึงขั้นต่ำสำหรับฟัซซี่
semantic_fallback ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
ลองใช้การค้นหาเชิงความหมายหลังจากหน้าแรกของการค้นหาเชิงคำศัพท์ว่างเปล่า metadata.fallback_status ใช้แยกความแตกต่างระหว่างสถานะสำรอง used, empty และ unavailable

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

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

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

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

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

#

structural_search เสถียร

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

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

repository ไม่บังคับ
ประเภท
str
คำอธิบาย
รีโพซิทอรีในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือรีโพซิทอรีเดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือกรีโพอื่นที่จัดทำดัชนีไว้ ระบบจะให้ความสำคัญกับแบรนช์ที่จัดทำดัชนีตรงกันพอดี หากแบรนช์ที่ต้องการไม่พร้อมใช้งาน อาจย้อนกลับไปใช้ main หรือแบรนช์เดียวที่เข้าถึงได้ เมทาดาทาของการตอบกลับจะแสดงตัวตนที่ร้องขอและตัวตนที่ใช้จริง พร้อมแจ้งเตือนเมื่อเกิดการย้อนกลับดังกล่าว
preset ไม่บังคับ
ประเภท
Literal[functions, classes, methods, imports, variables]
คำอธิบาย
ตัวเลือกเชิงโครงสร้างที่แนะนำ ขยายเป็นชนิดโหนด AST ข้ามภาษา — functions (นิยาม function/arrow/method ข้ามภาษา); classes (การประกาศ class/struct/interface, ส่วนเนื้อของชนิด และการอิมพลีเมนต์); methods (นิยาม method (และ function_definition สำหรับภาษาที่ไม่มีโหนด method)); imports (คำสั่ง import/use/include); variables (การประกาศ variable/let/const/static) แนะนำให้ใช้แทน pattern/node_type แบบอิสระสำหรับการค้นหาแบบเรียกดู
pattern ไม่บังคับ
ประเภท
str
คำอธิบาย
pattern แบบอิสระจะเติมเต็มตัวเลือกเชิงโครงสร้างที่ขาดหายไป (ตรวจจับอัตโนมัติ: 'def foo(' → node_type + name_pattern) สามารถใช้ร่วมกับ preset ได้ โดยตัวเลือกที่ระบุชัดเจนจะมีความสำคัญกว่า สำหรับคิวรีแบบเรียกดูแนะนำให้ใช้ preset=
name_pattern ไม่บังคับ
ประเภท
str maxLength=256
คำอธิบาย
รูปแบบชื่อสัญลักษณ์ (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 minimum=1, maximum=50
ค่าเริ่มต้น
20
คำอธิบาย
จำนวนผลลัพธ์สูงสุดต่อหน้าเมื่อไม่ใช้ cursor การดำเนินการต่อจะใช้ขนาดหน้าที่เก็บไว้ใน cursor ละเว้น cursor เพื่อเริ่มต้นด้วย limit ที่ต่างออกไป
offset ไม่บังคับ
ประเภท
int minimum=0
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursor ไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคงค่า query และตัวกรองไว้เหมือนเดิม ตำแหน่งและขนาดหน้าของ cursor นี้มีความสำคัญเหนือกว่า offset และ limit
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
คำอธิบาย
กรองตามตัวปรับแต่ง (export, async, static ฯลฯ)
advanced ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
ตั้ง true เมื่อตั้งใจใช้ตัวกรองพาธ/ltree/การเรียกขั้นสูง (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name) เมื่อเป็น false ตัวกรองขั้นสูงที่ส่งมายังคงถูกใช้พร้อมคำเตือนในเมทาดาทา ควรใช้ preset= สำหรับคำค้นเชิงโครงสร้างทั่วไป
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 เสถียร

เครื่องมือหลักสำหรับรัศมีผลกระทบและกราฟ ตอบว่า «อะไรเรียกสิ่งนี้?» และ «สิ่งนี้ใช้อะไร?» ผ่านกราฟการเรียก/การนำเข้าจริง หากต้องการดูผลกระทบก่อนแก้ไข ให้ใช้ analysis_type="dependents" หรือ analysis_type="impact" (ทิศทางขาเข้า ค่าเริ่มต้นของ impact คือความลึกตื้น) โดยมี include_metrics=false เป็นค่าเริ่มต้น (เปิดเมื่อต้องการค่าความเป็นศูนย์กลางและ refactor_risk) dependents/impact รวม production_callers โดยค่าเริ่มต้น: ตำแหน่งใช้งานจริงที่ไม่ซ้ำ แยกตามชนิด (call, instantiate, value_reference สำหรับฟังก์ชันที่ส่งต่อเป็นค่า) รวมถึงตำแหน่ง IMPORT โดยไม่รวมการทดสอบและแสดงระดับความเชื่อมั่น EXTRACTED/INFERRED ไม่ใช่เพียงรายการเมตริก สำหรับผลกระทบ PR/diff ให้ส่ง changed_paths และ/หรือ patch (unified diff) ระบบระบุสัญลักษณ์ตามพาธและส่งข้อมูลแบบกระชับของส่วนประกอบที่พึ่งพาในทิศทางขาเข้าแบบตื้น โดยไม่ต้องระบุชื่อสัญลักษณ์ หลังแก้ไข ให้ตั้ง verify_after_edit=true พร้อม targets และ/หรือ changed_paths เพื่อค้นหาซ้ำแบบกระชับจากหลายรากสำหรับสัญลักษณ์ที่ได้รับผลกระทบ รองรับ dependencies, centrality และ orphans ด้วย analyze_dependencies ใช้วิธีเดินกราฟเดียวกันเพื่อวิเคราะห์ผลกระทบหลายขั้น

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

repository ไม่บังคับ
ประเภท
str
คำอธิบาย
รีโพซิทอรีในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือรีโพซิทอรีเดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือกรีโพอื่นที่จัดทำดัชนีไว้ ระบบจะให้ความสำคัญกับแบรนช์ที่จัดทำดัชนีตรงกันพอดี หากแบรนช์ที่ต้องการไม่พร้อมใช้งาน อาจย้อนกลับไปใช้ main หรือแบรนช์เดียวที่เข้าถึงได้ เมทาดาทาของการตอบกลับจะแสดงตัวตนที่ร้องขอและตัวตนที่ใช้จริง พร้อมแจ้งเตือนเมื่อเกิดการย้อนกลับดังกล่าว
query ไม่บังคับ
ประเภท
str
คำอธิบาย
ชื่อสัญลักษณ์หรือคำค้นหา
target ไม่บังคับ
ประเภท
str
คำอธิบาย
ชื่อสัญลักษณ์ (นามแฝงสำหรับการสืบค้น)
symbol_id ไม่บังคับ
ประเภท
UUID
คำอธิบาย
เลือกตำแหน่งที่ปรากฏที่ต้องการด้วย UUID จากตัวเลือกที่ตรงกับชื่อใน query/target หลังกรองตามเนมสเปซ พาธ และภาษา ใช้ ID ที่ส่งกลับจาก find_symbol หรือผลลัพธ์ทางเลือกของกราฟ ใช้ได้เฉพาะการเดินกราฟที่ระบุชื่อเท่านั้น; ID ที่อยู่นอกช่วงตัวเลือกที่จำกัดจะทำให้เกิดข้อผิดพลาด
changed_paths ไม่บังคับ
ประเภท
list[str] maxItems=50
คำอธิบาย
พาธไฟล์ที่ตรงเป๊ะซึ่งสัมพันธ์กับรีโพสำหรับผลกระทบ PR/diff (ค่าเริ่มต้น) หรือใช้เป็นจุดเริ่มต้นของการตรวจสอบหลังแก้ไขเมื่อ verify_after_edit=true พาธที่ไม่สามารถแปลงได้อาจส่งคืนคำแนะนำที่มีป้ายกำกับ ไฟล์ที่แนะนำจะไม่กลายเป็นจุดเริ่มต้นของผลกระทบ สำหรับ PR/diff: หากไม่มีข้อมูลบรรทัด จะเดินผ่านนิยามระดับบนสุดของแต่ละพาธ (นิยามที่ส่งออกก่อน ตามลำดับในไฟล์) และรายงาน changed_lines_unknown ส่ง patch= หากต้องการสัญลักษณ์ที่เปลี่ยนในระดับบรรทัด สำหรับการตรวจสอบ: ใช้นิยามระดับบนสุดสูงสุด 5 รายการต่อพาธเป็นจุดเริ่มต้น (มีขีดจำกัดต่ำกว่าในโหมดนี้) ไม่จำเป็นต้องใช้ query/target สำหรับผลกระทบ PR/diff
patch ไม่บังคับ
ประเภท
str maxLength=500000
คำอธิบาย
ผลกระทบ PR/diff: ข้อความ unified diff / git patch ระบบอ่านพาธจากส่วนหัว diff --git / --- / +++ บรรทัดในส่วนที่เปลี่ยนแปลง (ฝั่งเดิม = คอมมิตที่ทำดัชนีไว้) จะถูกจับคู่กับฟังก์ชัน/เมธอด/คลาสที่ครอบอยู่ แล้วเดินต่อจากสิ่งเหล่านั้นเพื่อหาโค้ดที่พึ่งพาอย่างแม่นยำ public_api_changed และโค้ดที่เรียกใช้ซึ่งการเปลี่ยนแปลงไม่ได้แตะ
head_commit ไม่บังคับ
ประเภท
str pattern=^[0-9a-fA-F]{7,64}$
คำอธิบาย
SHA ของคอมมิตของโค้ดที่คุณถามถึง (git rev-parse HEAD หรือคอมมิตฐานของแพตช์) complete:true ต้องการให้ดัชนีอยู่ที่คอมมิตนี้และสร้างโดยรีโซลเวอร์ปัจจุบัน มิฉะนั้นจะยังคงเป็น complete:false พร้อม index_stale / index_freshness_unverified / index_built_by_older_resolver และ index_basis.statement จะบอกว่าคำตอบครบถ้วนภายในขอบเขตใด บรรทัด 'base-commit:' ของแพตช์ (git format-patch --base) ก็ให้ค่านี้ได้เช่นกัน
analysis_type ไม่บังคับ
ประเภท
Literal[centrality, dependencies, dependents, impact, orphans]
ค่าเริ่มต้น
dependencies
คำอธิบาย
โหมดการวิเคราะห์ impact = รัศมีผลกระทบ (dependents ขาเข้า; ความลึก shallow เมื่อละ depth) dependents ก็ตอบ impact ได้เช่นกัน เมื่อกำหนด changed_paths หรือ patch การวิเคราะห์จะถูกบังคับเป็น PR/diff impact centrality/orphans ไม่ต้องมีเป้าหมาย orphans เป็นเพียงรายการที่น่าจะเป็นโค้ดที่ไม่ได้ใช้ ไม่ใช่ข้อพิสูจน์ว่าลบได้อย่างปลอดภัย ให้ตรวจสอบการอ้างอิงในซอร์สโค้ดด้วย
depth ไม่บังคับ
ประเภท
Literal[shallow, balanced, deep]
คำอธิบาย
ความลึกของการท่องกราฟ ค่าเริ่มต้นคือ balanced ส่วน impact และ PR/diff impact จะใช้ shallow เป็นค่าเริ่มต้น การระบุ depth อย่างชัดเจนจะแทนที่ค่าเริ่มต้นเหล่านี้ โหมดตรวจสอบจะใช้ shallow เสมอ
limit ไม่บังคับ
ประเภท
int minimum=1, maximum=50
ค่าเริ่มต้น
20
คำอธิบาย
จำนวนผลลัพธ์สูงสุดต่อหน้าเมื่อไม่ใช้ cursor การดำเนินการต่อจะใช้ขนาดหน้าที่เก็บไว้ใน cursor ละเว้น cursor เพื่อเริ่มต้นด้วย limit ที่ต่างออกไป
offset ไม่บังคับ
ประเภท
int minimum=0
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursor ไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคงค่า query และตัวกรองไว้เหมือนเดิม ตำแหน่งและขนาดหน้าของ cursor นี้มีความสำคัญเหนือกว่า offset และ limit
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
ค่าเริ่มต้น
false
คำอธิบาย
ไม่รวมการประกาศที่สร้างขึ้น รวมถึงบิลด์ การครอบคลุม แคช ซอร์สแมป และพาธอาร์ติแฟกต์ที่ย่อขนาดจากผลลัพธ์การแวะผ่าน
include_module_symbols ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
ค่าเริ่มต้น false: ไม่รวมเอดจ์ที่ from_name หรือ to_name เป็นสัญลักษณ์สังเคราะห์ __module__ (สัญญาณรบกวนระดับโมดูล) ตั้ง true เพื่อรวมเอดจ์ระดับโมดูลในผลลัพธ์ dependents/dependencies
include_isolated ไม่บังคับ
ประเภท
bool
คำอธิบาย
สำหรับ orphans เท่านั้น ค่าเริ่มต้น false ตั้ง true เพื่อส่งคืนสัญลักษณ์ที่ไม่มีแถวในเมตริกกราฟด้วย (ไม่มีเอดจ์ของกราฟเลย) ขณะที่ exclude_test_paths เป็น true สัญลักษณ์ของสไตล์ชีต/มาร์กอัป/ข้อมูล (CSS, HTML, ...) การประกาศ .d.ts และเส้นทาง test/fixture/vendor/ตัวอย่าง จะยังถูกยกเว้นในกรณีที่แบ็กเอนด์รองรับ เว้นแต่ language_filter จะระบุภาษานั้น ทั้งนี้พร็อพเพอร์ตีของออบเจกต์ลิเทอรัลใน TypeScript อาจยังปรากฏเป็นฟังก์ชันที่แยกโดดเดี่ยว
exclude_exported ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
ใช้กับสัญลักษณ์กำพร้าเท่านั้น ค่าเริ่มต้นคือ false: สัญลักษณ์ที่ส่งออก (API สาธารณะ) ซึ่งไม่มีการใช้งานในรีโพซิทอรีจะถูกส่งกลับพร้อม is_exported=true ตั้งเป็น true เพื่อรับเฉพาะตัวเลือกภายใน
branch ไม่บังคับ
ประเภท
str
คำอธิบาย
ระบุแบรนช์เพื่อแทนค่าเริ่มต้น
per_hop_limit ไม่บังคับ
ประเภท
int minimum=1, maximum=300
คำอธิบาย
ความสัมพันธ์สูงสุดต่อการกระโดด (1-300)
include_metrics ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
เมตริกกราฟที่ต้องเปิดใช้เอง บนแถวผลลัพธ์ (บีบอัดพร้อม refactor_risk) เมตริกยังถูกดึงภายในเมื่อ min_centrality>0 แต่จะไม่ส่งคืนเว้นแต่ค่านี้เป็น true
metrics_detail ไม่บังคับ
ประเภท
Literal[summary, full]
ค่าเริ่มต้น
summary
คำอธิบาย
เมื่อ include_metrics=true: summary (ค่าเริ่มต้น) ส่งคืนสัญญาณการตัดสินใจ + refactor_risk; full ส่งคืนชุดเมตริกที่ได้รับการดูแลจัดการที่ใหญ่กว่า
include_edge_metadata ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
รวมเมทาดาทาและน้ำหนักของเอดจ์แบบดิบ (ข้อมูลขนาดใหญ่) คำตอบผลกระทบแบบกระชับจะปิดตัวเลือกนี้ไว้
symbol_types ไม่บังคับ
ประเภท
list[str]
คำอธิบาย
กรองสัญลักษณ์ที่ส่งคืนตามประเภท (function, class, method เป็นต้น) ไม่รองรับในการวิเคราะห์ orphan ในกรณีนั้นให้ใช้ path_filter หรือ language_filter แทน รายการว่างจะไม่ใช้ตัวกรองประเภทใด ๆ
exact_match ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
จำเป็นต้องมีการจับคู่ชื่อสัญลักษณ์ที่ตรงกันทุกประการ
find_similar_patterns ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
ค้นหารูปแบบการใช้งานที่คล้ายกัน
min_centrality ไม่บังคับ
ประเภท
float minimum=0
ค่าเริ่มต้น
0
คำอธิบาย
คะแนน PageRank ต่ำสุดสำหรับการเดินกราฟจากสัญลักษณ์ที่ระบุชื่อและการวิเคราะห์ผลกระทบของ PR/diff ไม่รองรับค่าเกณฑ์ที่มากกว่าศูนย์ในโหมดเรียกดู centrality/orphans เมตริกถูกดึงภายในเพื่อการกรอง; graph_metrics จะส่งคืนเฉพาะเมื่อ include_metrics=true และ verify_after_edit จะไม่สนใจค่านี้เพราะใช้ตัวควบคุมแบบกระชับที่กำหนดไว้ตายตัว
graph_view ไม่บังคับ
ประเภท
Literal[dependency, type, data_flow, control_flow]
ค่าเริ่มต้น
dependency
คำอธิบาย
มุมมองกราฟที่ใช้สำหรับค่าเริ่มต้นความสัมพันธ์ในการท่องกราฟ เมตริก และการจัดอันดับ centrality การวิเคราะห์ orphan คำนวณข้ามทุกมุมมอง
verify_after_edit ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
สืบค้นกราฟผลกระทบที่จัดทำดัชนีไว้ซ้ำสำหรับสัญลักษณ์ที่แก้ไขแล้ว ในการตอบกลับแบบหลายรากที่กระชับเพียงครั้งเดียว ต้องมี targets และ/หรือ changed_paths (หรือ target/query) ใช้การท่องกราฟแบบ shallow ที่ตายตัวและงบประมาณที่กระชับ การควบคุม depth/limit/cursor/metrics จะไม่มีผล ค่าเริ่มต้นจะส่งคืนโค้ดที่พึ่งพาขาเข้า (incoming dependents) ผลลัพธ์สะท้อนกราฟที่จัดทำดัชนีไว้ (อาจล้าหลังกว่าการแก้ไขแบบสด) เมื่อเป็น true จะมีความสำคัญเหนือกว่าผลกระทบ PR/diff สำหรับ changed_paths เดียวกัน
targets ไม่บังคับ
ประเภท
list[str] maxItems=15
คำอธิบาย
เมื่อ verify_after_edit=true: ชื่อสัญลักษณ์ที่จะตรวจสอบอีกครั้ง (โค้ดที่เรียกใช้/ส่วนประกอบที่พึ่งพา) รวมกับ target/query หากระบุทั้งสองอย่าง

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

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

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

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

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

#

find_symbol เสถียร

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

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

symbol_name ไม่บังคับ
ประเภท
str
คำอธิบาย
ชื่อสัญลักษณ์ที่จะค้นหา (ไม่บังคับ — ละเว้นเพื่อเรียกดูตามตัวชี้วัด)
repository ไม่บังคับ
ประเภท
str
คำอธิบาย
รีโพซิทอรีในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือรีโพซิทอรีเดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือกรีโพอื่นที่จัดทำดัชนีไว้ ระบบจะให้ความสำคัญกับแบรนช์ที่จัดทำดัชนีตรงกันพอดี หากแบรนช์ที่ต้องการไม่พร้อมใช้งาน อาจย้อนกลับไปใช้ main หรือแบรนช์เดียวที่เข้าถึงได้ เมทาดาทาของการตอบกลับจะแสดงตัวตนที่ร้องขอและตัวตนที่ใช้จริง พร้อมแจ้งเตือนเมื่อเกิดการย้อนกลับดังกล่าว
scope ไม่บังคับ
ประเภท
Literal[definitions, references, both]
ค่าเริ่มต้น
both
คำอธิบาย
ขอบเขตการค้นหา references ต้องการ symbol_name ที่ไม่ว่างเปล่า
limit ไม่บังคับ
ประเภท
int minimum=1, maximum=50
ค่าเริ่มต้น
15
คำอธิบาย
จำนวนผลลัพธ์สูงสุดต่อหน้าเมื่อไม่ใช้ cursor การดำเนินการต่อจะใช้ขนาดหน้าที่เก็บไว้ใน cursor ละเว้น cursor เพื่อเริ่มต้นด้วย limit ที่ต่างออกไป
offset ไม่บังคับ
ประเภท
int minimum=0
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursor ไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคงค่า query และตัวกรองไว้เหมือนเดิม ตำแหน่งและขนาดหน้าของ cursor นี้มีความสำคัญเหนือกว่า offset และ limit
find_similar ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
รวมชื่อสัญลักษณ์ที่คล้ายกัน
include_metrics ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
รวมการวัดศูนย์กลาง
metrics_detail ไม่บังคับ
ประเภท
Literal[summary, full]
ค่าเริ่มต้น
summary
คำอธิบาย
เมื่อ include_metrics=true: summary (ค่าเริ่มต้น) ส่งคืนสัญญาณการตัดสินใจ + refactor_risk; full ส่งคืนชุดเมตริกที่ได้รับการดูแลจัดการที่ใหญ่กว่า
path_filter ไม่บังคับ
ประเภท
str
คำอธิบาย
กรองตามคำนำหน้าเส้นทางไฟล์
branch ไม่บังคับ
ประเภท
str
คำอธิบาย
ระบุแบรนช์เพื่อแทนค่าเริ่มต้น
symbol_type ไม่บังคับ
ประเภท
str minLength=1
คำอธิบาย
กรองตามชนิดสัญลักษณ์ที่จัดทำดัชนีไว้ เช่น function, class, struct, enum หรือ trait ใช้ชนิดที่ส่งกลับมาจากผลลัพธ์สัญลักษณ์ ชนิดจะแตกต่างกันไปตามภาษา
high_impact ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
เรียกดูสัญลักษณ์ที่สำคัญเชิงสถาปัตยกรรม (ละ symbol_name) โหมดเริ่มต้นคือความนิยม (เดไซล์สูงสุดของ PageRank โดยไม่นับฮับอเนกประสงค์ขนาดใหญ่) ตั้ง high_impact_mode=risk สำหรับจุดตัดและสะพานของกราฟ
high_impact_mode ไม่บังคับ
ประเภท
Literal[popularity, risk]
ค่าเริ่มต้น
popularity
คำอธิบาย
เมื่อ high_impact=true: popularity = กลุ่มเดไซล์สูงสุดของ PageRank โดยไม่นับฮับยูทิลิตีขนาดใหญ่และโมดูล; risk = จุดตัดของกราฟ จัดอันดับตาม SMV bridge_count แล้วตาม k_core (ความเสี่ยงเชิงโครงสร้างในการรีแฟกเตอร์ ไม่ใช่ความนิยมของฮับ)
in_cycle ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
กรองเฉพาะสัญลักษณ์ที่มีการบันทึกการเป็นสมาชิกในวงจรการพึ่งพา
exclude_test_paths ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
true
คำอธิบาย
เมื่อเรียกดูตามตัวชี้วัดกราฟ ให้ยกเว้นการทดสอบ, fixtures, โค้ดของบุคคลที่สาม และตัวอย่างก่อนการจัดอันดับ การค้นหาด้วยสัญลักษณ์ที่มีชื่อไม่มีการเปลี่ยนแปลง
reference_views ไม่บังคับ
ประเภท
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
คำอธิบาย
มุมมองกราฟที่ใช้เส้นเชื่อมขาเข้าเติม references/reference_count (scope เป็น references/both) ค่าเริ่มต้น ["dependency", "type"] ครอบคลุมการเรียก การนำเข้า การส่งออก การอ้างอิง การสร้างอินสแตนซ์ การสืบทอด การแทนที่ เดคอเรเตอร์ และการใช้ชนิดข้อมูล หากไม่ได้เลือก data_flow การใช้งาน data_flow ที่ระบุเป้าหมายได้อย่างแม่นยำ (คอลแบ็ก ตัวจัดการ คีย์เรียงลำดับ) จะส่งกลับแยกเป็น value_references/value_reference_count โดยไม่มีรายการที่อนุมานจากชื่อเพียงอย่างเดียว เพิ่ม data_flow หรือ control_flow หรือส่ง ["all"] สำหรับเส้นเชื่อมทุกชนิดและทุกระดับ ใช้กลุ่มมุมมองเดียวกับ graph_view ของ dependency_search
relationship_types ไม่บังคับ
ประเภท
list[str]
คำอธิบาย
ชนิดเส้นเชื่อมการอ้างอิงที่ระบุอย่างชัดเจน (CALL, IMPORT, READS เป็นต้น) รายการที่ไม่ว่างจะใช้แทน reference_views

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

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

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

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

analyze_dependencies เสถียร

วิเคราะห์รัศมีผลกระทบด้วยวิธีเดินกราฟเดียวกับ dependency_search (dependents/incoming) ควรใช้ dependency_search กับ analysis_type="dependents" หรือ "impact" สำหรับการวิเคราะห์ผลกระทบ ส่งคำตอบผลกระทบหลายขั้นพร้อม graph, connection_summary และเมตริกทางเลือกที่มี refactor_risk โดย connection_summary นับเส้นเชื่อมที่จำกัดตามกลุ่มความสัมพันธ์ของรูทที่เลือก ก่อนการกรองด้วยเทสต์หรือพาธ ส่วนฟิลด์เดิมอย่าง incoming_production/outgoing_production หมายถึงเส้นเชื่อมที่ไม่ใช่ระดับโมดูล ซึ่งรวมเทสต์ด้วย และไม่ใช่จำนวนผู้เรียกในโค้ดที่ใช้งานจริง ใช้ graph_view เพื่อจำกัดกลุ่มความสัมพันธ์: dependency (ค่าเริ่มต้น), type, data_flow, control_flow

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

repository ไม่บังคับ
ประเภท
str
คำอธิบาย
รีโพซิทอรีในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือรีโพซิทอรีเดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือกรีโพอื่นที่จัดทำดัชนีไว้ ระบบจะให้ความสำคัญกับแบรนช์ที่จัดทำดัชนีตรงกันพอดี หากแบรนช์ที่ต้องการไม่พร้อมใช้งาน อาจย้อนกลับไปใช้ main หรือแบรนช์เดียวที่เข้าถึงได้ เมทาดาทาของการตอบกลับจะแสดงตัวตนที่ร้องขอและตัวตนที่ใช้จริง พร้อมแจ้งเตือนเมื่อเกิดการย้อนกลับดังกล่าว
target จำเป็น
ประเภท
str minLength=1
คำอธิบาย
ชื่อสัญลักษณ์ที่จะวิเคราะห์
symbol_id ไม่บังคับ
ประเภท
UUID
คำอธิบาย
เลือกตำแหน่งที่ปรากฏที่ต้องการด้วย UUID จากตัวเลือกของ target หลังกรองตามเนมสเปซ พาธ และภาษา; ID ที่อยู่นอกช่วงตัวเลือกที่จำกัดจะทำให้เกิดข้อผิดพลาด
depth ไม่บังคับ
ประเภท
Literal[shallow, balanced, deep]
ค่าเริ่มต้น
balanced
คำอธิบาย
ความลึกของการวิเคราะห์
limit ไม่บังคับ
ประเภท
int minimum=1, maximum=50
ค่าเริ่มต้น
10
คำอธิบาย
จำนวนผลลัพธ์สูงสุดต่อหน้าเมื่อไม่ใช้ cursor การดำเนินการต่อจะใช้ขนาดหน้าที่เก็บไว้ใน cursor ละเว้น cursor เพื่อเริ่มต้นด้วย limit ที่ต่างออกไป
offset ไม่บังคับ
ประเภท
int minimum=0
คำอธิบาย
ออฟเซ็ตความเข้ากันได้ที่เลิกใช้แล้ว แนะนำให้ใช้ cursor จาก pagination.next_cursor
cursor ไม่บังคับ
ประเภท
str
คำอธิบาย
cursor แบบทึบจาก pagination.next_cursor ส่งต่อโดยไม่เปลี่ยนแปลง และคงค่า query และตัวกรองไว้เหมือนเดิม ตำแหน่งและขนาดหน้าของ cursor นี้มีความสำคัญเหนือกว่า offset และ limit
direction ไม่บังคับ
ประเภท
Literal[incoming, outgoing, both]
ค่าเริ่มต้น
incoming
คำอธิบาย
ทิศทางการท่องกราฟ
relationship_types ไม่บังคับ
ประเภท
list[str]
คำอธิบาย
กรองประเภทของ edge (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 minimum=1, maximum=300
คำอธิบาย
ความสัมพันธ์สูงสุดต่อการกระโดด (1-300)
include_metrics ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
รวมตัวชี้วัดกราฟในผลลัพธ์ โดยแต่ละรายการเสริมด้วยบล็อก 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
ค่าเริ่มต้น
false
คำอธิบาย
รวมข้อมูลเมตาและน้ำหนักของ Raw Edge ปิดใช้งานตามค่าเริ่มต้นเนื่องจากข้อมูลเมตาของตัวแยกข้อมูลอาจมีขนาดใหญ่ ความครอบคลุมของการเพิ่มคุณค่าจะถูกรายงานเมื่อเปิดใช้งาน
exclude_test_paths ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
true
คำอธิบาย
ค่าเริ่มต้น true: ไม่รวมการทดสอบ ฟิกซ์เจอร์ โค้ดของบุคคลที่สาม และเส้นทางตัวอย่างจากขอบกราฟที่ส่งคืน ตั้งค่า false เพื่อรวมไว้
include_module_symbols ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
false
คำอธิบาย
ตามค่าเริ่มต้น false จะไม่รวมขอบกราฟเมื่อ from_name หรือ to_name เป็นสัญลักษณ์ __module__ สังเคราะห์ ตั้งค่า true เพื่อรวมขอบระดับโมดูล
head_commit ไม่บังคับ
ประเภท
str pattern=^[0-9a-fA-F]{7,64}$
คำอธิบาย
SHA ของคอมมิตของโค้ดที่คุณถามถึง (git rev-parse HEAD หรือคอมมิตฐานของแพตช์) complete:true ต้องการให้ดัชนีอยู่ที่คอมมิตนี้และสร้างโดยรีโซลเวอร์ปัจจุบัน มิฉะนั้นจะยังคงเป็น complete:false พร้อม index_stale / index_freshness_unverified / index_built_by_older_resolver และ index_basis.statement จะบอกว่าคำตอบครบถ้วนภายในขอบเขตใด บรรทัด 'base-commit:' ของแพตช์ (git format-patch --base) ก็ให้ค่านี้ได้เช่นกัน

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

  • การวิเคราะห์ผลกระทบหลายขั้นเมื่อต้องการฟิลด์คำตอบ graph และ connection_summary

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

  • การวิเคราะห์ผลกระทบทั่วไป ควรใช้ dependency_search เพื่อเดินกราฟอย่างยืดหยุ่นและตรวจสอบจากหลายราก

get_task_context เสถียร

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

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

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

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

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

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

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

get_file เสถียร

อ่านไฟล์จากรีโพซิทอรีที่จัดทำดัชนีไว้ตามพาธ ควรใช้เครื่องมือไฟล์ในเครื่องสำหรับไฟล์บนดิสก์ก่อน ใช้เครื่องมือนี้สำหรับสแนปช็อตที่จัดทำดัชนีระยะไกล ดำเนินการตอบสนองแบบมีขอบเขตต่อได้ด้วย metadata.next_line_start และ next_character_start ให้ลบอักขระขึ้นบรรทัดใหม่ท้ายสุดพร้อมเครื่องหมาย [truncated] เฉพาะเมื่อ metadata.truncated=true เท่านั้น มิฉะนั้นอาจเป็นข้อความต้นฉบับตามตัวอักษร

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

file_path จำเป็น
ประเภท
str
คำอธิบาย
พาธของไฟล์สัมพันธ์กับรูทของรีโพซิทอรี
repository ไม่บังคับ
ประเภท
str
คำอธิบาย
รีโพซิทอรีในรูปแบบ owner/repo[:branch] เป็นตัวเลือก — ไม่ต้องระบุเพื่อใช้ค่าเริ่มต้นของไคลเอนต์สำหรับคำขอนั้น (หากมี) หรือรีโพซิทอรีเดียวที่เข้าถึงได้ ระบุอย่างชัดเจนเฉพาะเมื่อต้องการเลือกรีโพอื่นที่จัดทำดัชนีไว้ ระบบจะให้ความสำคัญกับแบรนช์ที่จัดทำดัชนีตรงกันพอดี หากแบรนช์ที่ต้องการไม่พร้อมใช้งาน อาจย้อนกลับไปใช้ main หรือแบรนช์เดียวที่เข้าถึงได้ เมทาดาทาของการตอบกลับจะแสดงตัวตนที่ร้องขอและตัวตนที่ใช้จริง พร้อมแจ้งเตือนเมื่อเกิดการย้อนกลับดังกล่าว
line_start ไม่บังคับ
ประเภท
int minimum=1
คำอธิบาย
บรรทัดเริ่มต้น (ดัชนีเริ่มที่ 1)
line_end ไม่บังคับ
ประเภท
int minimum=1
คำอธิบาย
บรรทัดสิ้นสุด (เริ่มดัชนีที่ 1, รวมปลาย; ต้องอยู่ที่หรือหลัง line_start)
character_start ไม่บังคับ
ประเภท
int minimum=0
ค่าเริ่มต้น
0
คำอธิบาย
ออฟเซ็ตในหน่วยรหัส UTF-16 ภายในบรรทัดเริ่มต้นเท่านั้น (ดัชนีเริ่มที่ 0) ใช้ metadata.next_character_start เพื่ออ่านต่อจากบรรทัดที่อ่านไปแล้วบางส่วน
branch ไม่บังคับ
ประเภท
str
คำอธิบาย
ระบุแบรนช์เพื่อแทนค่าเริ่มต้น
max_tokens ไม่บังคับ
ประเภท
int minimum=1, maximum=50000
ค่าเริ่มต้น
5000
คำอธิบาย
งบประมาณเนื้อหาโดยประมาณ (4 หน่วยรหัส UTF-16 ต่อโทเคน ไม่ใช่ขีดจำกัดที่แน่นอนของตัวแบ่งโทเคน)
include_metadata ไม่บังคับ
ประเภท
bool
ค่าเริ่มต้น
true
คำอธิบาย
รวมเมทาดาทาที่อธิบายไฟล์ เมทาดาทาการตัดทอนและการอ่านต่อจะถูกส่งกลับเสมอ

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

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

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

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

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

#

repository_context เสถียร

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

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

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

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

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

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

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

ask_maguyva เสถียร

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

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

operation จำเป็น
ประเภท
Literal[guidance, report_bug, request_feature, evaluate]
คำอธิบาย
ใช้ guidance เพื่อขอความช่วยเหลือเกี่ยวกับเครื่องมือ report_bug สำหรับข้อบกพร่อง หรือ request_feature สำหรับข้อเสนอแนะ evaluate ประมวลผลนิพจน์ที่ให้ผลลัพธ์แน่นอน ควรใช้การคำนวณในเครื่องสำหรับการคำนวณ
query ไม่บังคับ
ประเภท
str maxLength=500
คำอธิบาย
หัวข้อคำแนะนำ (เช่น tool_selection, semantic_search) หรือสตริงนิพจน์สำหรับ evaluate
description ไม่บังคับ
ประเภท
str minLength=1, maxLength=4000
คำอธิบาย
จำเป็นสำหรับ 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

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

  • การคำนวณคณิตศาสตร์ แฮช และสตริง ควรใช้การคำนวณในเครื่องหรือเครื่องมือของสภาพแวดล้อมโฮสต์

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

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

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

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

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

#

คำตอบของเครื่องมือมีฟิลด์สถานะร่วมและฟิลด์ข้อมูลเฉพาะเครื่องมือที่ระดับบนสุด การค้นหาส่งกลับ results ส่วน get_file ส่งกลับ content ฟิลด์ร่วมประกอบด้วย:

  • status: สตริง — "success" หรือ "error" สัญญาณการจับคู่ที่ลดทอนและความสดของดัชนีอยู่ในฟิลด์ของตัวเอง ได้แก่ metadata.resolution_reason ภายใต้ metadata และ index_freshness.status ที่ระดับบนสุดของแอ็กชัน info ใน repository_context
  • timing_ms: เวลาที่ใช้ในการทำงานของเครื่องมือ หน่วยมิลลิวินาที
  • applied_filters: พารามิเตอร์คำขอที่ใช้จริงซึ่งบันทึกไว้สำหรับการดำเนินการ
  • error: สตริงข้อความผิดพลาดเมื่อ status เป็น "error" ซึ่งอาจมีคำแนะนำการกู้คืน
  • metadata: ข้อมูลเพิ่มเติมเกี่ยวกับการดำเนินการ (การกำหนดเส้นทาง การแคช การปรับพารามิเตอร์)
  • pagination: มีอยู่ในคำตอบของชุดข้อมูลที่แบ่งหน้าด้วยเคอร์เซอร์ ประกอบด้วย has_more และ next_cursor หน้าต่างผลการค้นหาที่จัดอันดับเป็นผลลัพธ์ top-K ที่จำกัดจำนวน ไม่ใช่ชุดข้อมูลแบ่งหน้าที่ครอบคลุมทั้งหมด

ตรวจสอบฟิลด์ status ก่อนประมวลผลเพย์โหลดของเครื่องมือ โดยค่าของมันคือ "success" หรือ "error" และควรจัดการข้อผิดพลาดของการส่งข้อมูล MCP/JSON-RPC รวมถึงการตรวจสอบคำขอด้วย เพราะอาจเกิดขึ้นก่อนที่จะมีเพย์โหลดของเครื่องมือเสียอีก ส่วนสัญญาณการจับคู่ที่ลดทอนหรือความสด ให้อ่านจากฟิลด์เฉพาะของมัน ได้แก่ metadata.resolution_reason ภายใต้ metadata หรือ index_freshness.status ที่ระดับบนสุดของแอ็กชัน info ใน repository_context (known/partial/unknown/unavailable)

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

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

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

ที่เกี่ยวข้อง

อ่านต่อ