ข้ามไปยังเนื้อหา

คำสั่ง Fingerprint

codeknit fingerprint คำนวณ Context-Triggered Piecewise Hash (CTPH) บนโทเค็นของเนื้อหาที่ถูก normalize ของฟังก์ชัน เมธอด ตัวแปร และประเภททุกตัว ชื่อตัวแปร สตริง literal และการประกาศประเภทจะถูก normalize ออกก่อนการ hashing ดังนั้นการคัดลอกและเปลี่ยนชื่อหรือการแปลงไปยังภาษาอื่นจึงยังสามารถจับคู่ได้

คู่มือนี้แสดงวิธีการค้นหารายการซ้ำ ปรับช่วงความคล้ายคลึง ลดผลบวกลวง และตัดสินใจว่าจะ refactor อะไร

  • codeknit ได้รับการติดตั้งแล้ว ดู การติดตั้ง
  • คุณมีไดเรกทอรีต้นทางที่ต้องการสแกน เช่น ./src

เรียกใช้คำสั่งบนไดเรกทอรีที่ต้องการตรวจสอบ:

Terminal window
codeknit fingerprint ./src

คำสั่งจะเขียนไฟล์ ./skeleton/fingerprints.skt และรายงานคู่ที่มีความคล้ายคลึงตั้งแต่ 65% ถึง 95%

เปิดไฟล์ ไฟล์ส่วน [duplicates] จะปรากฏเสมอ โดยแสดงรายการที่มีความคล้ายคลึงสูงสุดก่อน:

[duplicates]
# similarity range: 65%-95%
similarity:93% pkg/user.go::GetUser <-> pkg/admin.go::GetAdmin
similarity:88% src/auth.ts::validateToken <-> src/session.ts::validateSession
similarity:81% lib/math.py::compute_tax <-> lib/math.py::compute_vat

แต่ละบรรทัดมีรูปแบบ similarity:<N>% <file>::<symbol> <-> <file>::<symbol> หากไม่มีรายการใดอยู่ในช่วงนี้ ส่วนนี้จะมีเพียง # no duplicates found

สำหรับไวยากรณ์เอาต์พุตทั้งหมด ดูที่ เอกสารอ้างอิงรูปแบบเอาต์พุต

ช่วงเริ่มต้นจะสิ้นสุดที่ 95% ดังนั้นการจับคู่ที่ 100% จึงถูกยกเว้น หากต้องการแสดงรายการที่ซ้ำกันเป๊ะเท่านั้น ให้ตั้งค่าช่วงทั้งสองเป็น 100:

Terminal window
codeknit fingerprint ./src --min-similarity 100 --max-similarity 100

“เป๊ะ” หมายถึงสตรีมโทเค็นที่ถูก normalize ทั้งหมดเหมือนกันภายในหมวดหมู่สัญลักษณ์เดียวกัน ไม่ได้หมายความว่าเนื้อหาโค้ดเหมือนกันเป๊ะ หรือว่าสัญลักษณ์ทั้งสองถูกพิสูจน์ว่าเทียบเท่ากัน

ขยายช่วงเพื่อค้นหารายการที่คล้ายกันแบบหลวม ๆ

หัวข้อที่มีชื่อว่า “ขยายช่วงเพื่อค้นหารายการที่คล้ายกันแบบหลวม ๆ”

ลดค่าต่ำสุดเพื่อรวมโค้ดที่มีรูปแบบอัลกอริทึมคล้ายกัน แต่มีรายละเอียดแตกต่างกัน:

Terminal window
codeknit fingerprint ./src --min-similarity 50 --max-similarity 80

ผลลัพธ์ที่ต่ำกว่า 50% มักจะเป็นสัญญาณรบกวน

ลดผลบวกลวงด้วยการจัดอันดับใหม่เชิงความหมาย

หัวข้อที่มีชื่อว่า “ลดผลบวกลวงด้วยการจัดอันดับใหม่เชิงความหมาย”

หากผลลัพธ์จากโครงสร้างมีสัญญาณรบกวนมาก ให้จัดอันดับใหม่ด้วย embeddings จากเซิร์ฟเวอร์ Ollama ในเครื่อง

  1. เริ่ม Ollama และดึงโมเดล embedding เริ่มต้น:

    Terminal window
    ollama serve
    ollama pull qwen3-embedding:0.6b
  2. เรียกใช้คำสั่งพร้อมกับ --rerank:

    Terminal window
    codeknit fingerprint ./src --rerank

หากต้องการใช้โมเดล embedding อื่น ให้ส่ง --model:

Terminal window
codeknit fingerprint ./src --rerank --model qwen3-embedding:4b

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

หากต้องการดู fingerprint ของทุกสัญลักษณ์ ให้เพิ่ม --show-all:

Terminal window
codeknit fingerprint ./src --show-all

จะเพิ่มส่วน [fingerprints] ซึ่งจัดกลุ่มตามไฟล์ต้นทาง หนึ่งบรรทัดต่อสัญลักษณ์:

[fingerprints]
## src/auth.ts
validateToken FP:3:a1b2c3...:d4e5f6... tokens:8e0f1a2b...

รูปแบบบรรทัดคือ <symbol-name> FP:<blocksize>:<hash1>:<hash2> tokens:<hex> tokens คือสตรีมโทเค็นที่ถูก normalize และเข้ารหัสเป็น hex

Terminal window
codeknit fingerprint ./src -o duplicates.skt

ไฟล์ทดสอบจะถูกข้ามโดยค่าเริ่มต้น รวมไฟล์ทดสอบด้วย --collect-test:

Terminal window
codeknit fingerprint ./src --collect-test

หากต้องการจำกัดการสแกน ให้ใช้แฟล็กการเลือกไฟล์ต้นทาง ควรใส่เครื่องหมายคำพูดเพื่อไม่ให้เชลล์ขยายรูปแบบ:

Terminal window
codeknit fingerprint ./src --include '**/*.ts' --exclude '**/generated/'

การควบคุมการเลือกอื่น ๆ:

  • --max-file-size BYTES ข้ามไฟล์ที่มีขนาดใหญ่กว่า ค่าเริ่มต้นคือ 10485760 (10 MiB) 0 ปิดการจำกัด
  • --strict จะล้มเหลวก่อนเขียนเอาต์พุตหากการสแกนหรือการแยกวิเคราะห์ไม่สมบูรณ์
  • --header-language c|cpp เลือก parser สำหรับไฟล์ .h ที่กำกวม ดู การรองรับภาษา

ลิงก์สัญลักษณ์ที่ถูกข้าม ไฟล์ที่มีขนาดใหญ่เกิน และคำเตือนเกี่ยวกับไวยากรณ์จะปรากฏบน stderr การรวมไม่ได้แทนที่ .gitignore หรือการกรองไฟล์ทดสอบ และการยกเว้นมีความสำคัญมากกว่าการรวม ดู เอกสารอ้างอิงความน่าเชื่อถือของการวิเคราะห์ สำหรับการรับประกันที่แน่นอน

ช่วง สิ่งที่มักพบ
96-100% รายการซ้ำหรือเกือบซ้ำเชิงโครงสร้าง; การคัดลอกที่ชัดเจน
85-95% รายการที่เกือบซ้ำ; มักเป็นการคัดลอกที่มีการแก้ไขเล็กน้อย
65-84% ช่วงเริ่มต้น; ความคล้ายคลึงเชิงโครงสร้างสูง มักเป็นผู้สมัครสำหรับการ refactor
50-64% รูปแบบอัลกอริทึมเดียวกันแต่มีรายละเอียดต่างกัน
ต่ำกว่า 50% มักเป็นสัญญาณรบกวน

หากต้องการดูสองแถวบนสุด ให้เพิ่ม --max-similarity เป็น 100

  1. เริ่มต้นด้วยช่วงเริ่มต้นและอ่านคู่ที่อยู่บนสุด
  2. เปิดสัญลักษณ์ทั้งสองของแต่ละคู่และเปรียบเทียบ
  3. ถือว่าการจับคู่เป็นสัญญาณ ไม่ใช่การพิสูจน์ Fingerprints วัดรูปร่างโครงสร้าง ไม่ใช่ชื่อตัวระบุหรือเจตนา โค้ดเดียวกันที่เขียนแบบวนซ้ำและแบบเรียกซ้ำจะได้คะแนนต่ำ และโค้ดที่ไม่เกี่ยวข้องกันแต่มีรูปร่างเหมือนกันอาจได้คะแนนสูง
  4. คู่ในช่วง 85–95% มักเป็นผู้สมัครที่ปลอดภัยที่สุดในการรวม คู่ในช่วง 65–84% มักต้องพิจารณาอย่างละเอียด
  5. หากรายการมีสัญญาณรบกวนมาก ให้จำกัดช่วงหรือเพิ่ม --rerank

การจับคู่ข้ามภาษาทำงานได้กับโครงสร้างที่เทียบเท่ากัน คุณลักษณะเฉพาะภาษาอาจทำให้เกิดการจับคู่ที่มีความคล้ายคลึงต่ำแบบผิดพลาด

เปอร์เซ็นต์ความคล้ายคลึงเป็นการจัดอันดับแบบฮิวริสติกส์ ไม่ใช่ระยะทางการแก้ไข โปรเจ็กต์ตัวอย่างที่มีการปรับเทียบจะรายงานความแม่นยำและการเรียกคืนแยกจากคะแนนความคล้ายคลึง เป็นการตรวจสอบการถดถอย ไม่ใช่การประมาณความแม่นยำในโค้ดของคุณ

  • ต่ำกว่า 500 สัญลักษณ์ที่มีสิทธิ์ codeknit จะให้คะแนนทุกคู่ในหมวดหมู่เดียวกัน
  • ที่ 500 สัญลักษณ์หรือมากกว่า กลุ่มโทเค็นที่ถูก normalize เป๊ะจะถูกเก็บไว้เสมอ คู่อื่น ๆ จะใช้เพื่อนบ้านประมาณ 50 อันดับแรกต่อสัญลักษณ์ ดังนั้นผลลัพธ์รายการที่เกือบซ้ำอาจไม่สมบูรณ์
  • สำหรับรายการซ้ำเป๊ะ ให้ใช้คำสั่ง 100/100 ด้านบน ซึ่งไม่ได้รับผลกระทบจากการประมาณ
  • การเรียงลำดับเป็นแบบ deterministic สำหรับอินพุตและคะแนนที่เสถียร
อาการ สาเหตุและวิธีแก้ไข
# no duplicates found ไม่มีคู่ใดอยู่ในช่วง ลด --min-similarity หรือเพิ่ม --max-similarity
ฟังก์ชันสั้นที่ทราบขาดหายไป สัญลักษณ์ที่มีโทเค็นที่ถูก normalize น้อยกว่า 4 ตัวจะถูกข้าม
สำเนาเป๊ะขาดหายไป ค่าสูงสุดเริ่มต้นคือ 95% ใช้ --min-similarity 100 --max-similarity 100 ด้วย --rerank ตัวกรองเชิงความหมายอาจลบออกได้
--rerank ล้มเหลว ตรวจสอบว่า ollama serve กำลังทำงานและโมเดลถูกดึงแล้ว
ผลลัพธ์บางส่วนพร้อมคำเตือนบน stderr แก้ไขไฟล์ที่รายงาน หรือเพิ่ม --strict เพื่อล้มเหลวแทนที่จะเผยแพร่เอาต์พุตไม่สมบูรณ์
แฟล็ก ค่าเริ่มต้น คำอธิบาย
-o, --output ./skeleton/fingerprints.skt เส้นทางไฟล์ .skt สำหรับเอาต์พุต
--min-similarity 65 เปอร์เซ็นต์ความคล้ายคลึงขั้นต่ำที่จะรายงาน (0–100)
--max-similarity 95 เปอร์เซ็นต์ความคล้ายคลึงสูงสุดที่จะรายงาน (0–100)
--show-all false ยังแสดงส่วน [fingerprints] พร้อมข้อมูลโทเค็นดิบ
--rerank false จัดอันดับใหม่ด้วย embeddings เชิงความหมายผ่าน Ollama ต้องการ ollama serve และ ollama pull qwen3-embedding:0.6b
--model qwen3-embedding:0.6b โมเดล embedding ของ Ollama ที่จะใช้กับ --rerank
--collect-test false รวมไฟล์ทดสอบในการวิเคราะห์
--workers NumCPU จำนวน goroutines การแยกวิเคราะห์พร้อมกันสูงสุด
--verbose false แสดงข้อมูลความคืบหน้า

สำหรับรายการทั้งหมด รวมถึง --include, --exclude, --max-file-size, --strict, และ --header-language ดู เอกสารอ้างอิงแฟล็ก CLI