Lệnh Fingerprint

Lệnh codeknit fingerprint phát hiện mã trùng lặp và gần trùng lặp trong codebase của bạn bằng cách sử dụng Context-Triggered Piecewise Hashing (CTPH). Nó hoạt động trên nhiều tệp và thậm chí trên nhiều ngôn ngữ lập trình bằng cách chuẩn hóa tên biến, chuỗi ký tự và chú thích kiểu trước khi tính toán fingerprint cấu trúc.

Chức năng

codeknit fingerprint phân tích mọi hàm, phương thức, biến và kiểu trong codebase của bạn và tính toán một fingerprint cấu trúc được chuẩn hóa dựa trên:

• Luồng điều khiển (if, for, while, switch)
• Toán tử (=, +, ==, &&, ||)
• Lời gọi, trả về, gán và tạo đối tượng
• Cấu trúc ngôn ngữ như try/catch, yield, await, defer

Việc chuẩn hóa này có nghĩa là sao chép-đổi tên, tái cấu trúc đơn giản, và logic tương đương trong các ngôn ngữ khác nhau vẫn có thể được phát hiện là trùng lặp.

Thuật toán sử dụng CTPH (một biến thể của rolling hash) để tìm kiếm gần trùng lặp một cách hiệu quả. Mã tương tự sẽ tạo ra fingerprint tương tự, cho phép khớp mờ ngay cả khi mã đã được chỉnh sửa nhẹ.

Cách sử dụng cơ bản

codeknit fingerprint ./src

Lệnh này sẽ:

• Phân tích tất cả các tệp nguồn trong ./src
• Tính toán fingerprint cấu trúc
• Xuất kết quả ra ./skeleton/fingerprints.skt
• Báo cáo các kết quả khớp với độ tương đồng từ 65% đến 95% (khoảng mặc định)

Cờ lệnh

Cờ lệnh	Giá trị mặc định	Mô tả
-o, --output	./skeleton/fingerprints.skt	Đường dẫn tệp .skt đầu ra
--min-similarity	65	Độ tương đồng tối thiểu để báo cáo (0–100)
--max-similarity	95	Độ tương đồng tối đa để báo cáo (0–100)
--show-all	false	Bao gồm phần [fingerprints] với dữ liệu token thô
--rerank	false	Sắp xếp lại các ứng viên CTPH bằng cách sử dụng embeddings ngữ nghĩa qua Ollama để loại bỏ kết quả dương tính giả (yêu cầu: ollama serve và ollama pull qwen3-embedding:0.6b)
--model	qwen3-embedding:0.6b	Mô hình embedding Ollama sử dụng với --rerank
--collect-test	false	Bao gồm các tệp kiểm thử trong phân tích
--workers	NumCPU	Số lượng goroutine phân tích đồng thời tối đa (0 = sử dụng tất cả lõi CPU)
--verbose	false	Hiển thị thông tin tiến trình trong quá trình xử lý

Định dạng đầu ra

Đầu ra là một tệp .skt với các phần sau:

[duplicates] (luôn có mặt)

Liệt kê các cặp ký hiệu có độ tương đồng trên ngưỡng:

[duplicates]
similarity:96%  pkg/user.go::GetUser <-> pkg/admin.go::GetAdmin
similarity:88%  utils/str.go::TrimSpaces <-> lib/text.go::CleanString

Mỗi dòng hiển thị:

• Phần trăm độ tương đồng
• Ký hiệu bên trái (đường dẫn tệp, phạm vi, tên)
• Ký hiệu bên phải (đường dẫn tệp, phạm vi, tên)

[fingerprints] (chỉ có với --show-all)

Chứa dữ liệu fingerprint thô cho mỗi ký hiệu:

[fingerprints]
validateToken  FP:3:a1b2c3...:d4e5f6...  tokens:8e0f1a2b...

Các trường:

• Tên ký hiệu
• FP:<version>:<hash1>:<hash2> — fingerprint CTPH
• tokens:<hex> — luồng token của nội dung đã chuẩn hóa

Phần này hữu ích cho việc gỡ lỗi hoặc xây dựng các công cụ hạ nguồn.

Các mẫu sử dụng phổ biến

# Quét mặc định
codeknit fingerprint ./codeknit/de/src

# Tìm chỉ các trùng lặp chính xác
codeknit fingerprint ./src --min-similarity 100

# Tìm mã có độ tương đồng trung bình (ví dụ: cùng thuật toán, tên khác nhau)
codeknit fingerprint ./src --min-similarity 50 --max-similarity 80

# Sử dụng sắp xếp lại ngữ nghĩa để giảm kết quả dương tính giả
# Yêu cầu: ollama serve && ollama pull qwen3-embedding:0.6b
codeknit fingerprint ./src --rerank

# Sử dụng mô hình embedding khác cho việc sắp xếp lại
codeknit fingerprint ./src --rerank --model qwen3-embedding:4b

# Xuất danh sách fingerprint đầy đủ (cho các công cụ phân tích)
codeknit fingerprint ./src --show-all

# Tệp đầu ra tùy chỉnh
codeknit fingerprint ./src -o duplicates.skt

Lựa chọn khoảng độ tương đồng

Khoảng	Hướng dẫn
96–100%	Trùng lặp cấu trúc chính xác hoặc gần chính xác. Gần như chắc chắn là sao chép-dán.
85–95%	Gần trùng lặp. Thường là sao chép-dán với chỉnh sửa nhỏ (ví dụ: đổi tên biến, thêm log).
65–84%	Khoảng mặc định. Độ tương đồng cấu trúc cao. Ứng viên tốt cho tái cấu trúc.
50–64%	Độ tương đồng trung bình. Hình dạng thuật toán giống nhau nhưng chi tiết khác nhau. Kiểm tra thủ công.
< 50%	Thường là nhiễu. Không phải trùng lặp có ý nghĩa.

Mẹo

• Fingerprint đo lường cấu trúc, không phải ý nghĩa: Điểm độ tương đồng cao có nghĩa là mã trông giống nhau, không phải là mã thực hiện cùng một việc. Luôn xem xét cả hai ký hiệu.
• Sử dụng --rerank cho kết quả nhiễu: Nếu bạn nhận được nhiều kết quả dương tính giả, hãy bật sắp xếp lại ngữ nghĩa để lọc các kết quả khớp bằng embeddings.
• Bỏ qua các nội dung ngắn: Các ký hiệu có ít hơn 4 token đã chuẩn hóa (ví dụ: các getter đơn giản) sẽ bị bỏ qua để tránh nhiễu.
• Khớp đa ngôn ngữ hoạt động: Các cấu trúc tương đương (ví dụ: một hàm Python và một hàm Go có cùng logic) có thể khớp, nhưng các mẫu đặc thù ngôn ngữ có thể tạo ra các kết quả khớp có độ tương đồng thấp không chính xác.
• Kết quả khớp là tín hiệu, không phải phán quyết: Xem mỗi kết quả khớp như một lời nhắc để điều tra — không phải bằng chứng tự động về trùng lặp.