Slopo là một công cụ dòng lệnh (CLI) nhẹ nhàng và đổi mới, được viết bằng Python, ra đời để giải quyết một vấn đề nhức nhối trong kỹ thuật phần mềm hiện đại: phát hiện sự trùng lặp mã nguồn không chính xác về cấu trúc và ngữ nghĩa trên toàn bộ codebase. Theo thông tin từ trang GitHub chính thức (https://github.com/rafal-qa/slopo), Slopo vượt trội so với các công cụ phân tích tĩnh truyền thống và trình phát hiện copy-paste, vốn chỉ hiệu quả với các đoạn mã trùng lặp y hệt. Các công cụ cũ bất lực khi tên biến được thay đổi, bình luận bị thêm hoặc xóa, hay cấu trúc mã được điều chỉnh nhẹ trong khi logic vẫn hoàn toàn giống nhau. 🤦♀️
Sự trùng lặp không chính xác này cực kỳ tai hại vì nó tạo ra nợ kỹ thuật âm thầm, khiến việc tái cấu trúc dễ mắc lỗi và phân tán logic giống nhau khắp các module, tệp hoặc gói khác nhau. Slopo lấp đầy khoảng trống này bằng cách tận dụng sức mạnh của các mô hình embedding hiện đại để xác định các điểm tương đồng về cấu trúc và ngữ nghĩa.
🎯 Tính Năng Nổi Bật và Ngôn Ngữ Hỗ Trợ
Slopo không chỉ là một công cụ phát hiện đơn thuần; nó được thiết kế để trở thành một trợ thủ đắc lực trong quy trình phát triển: * Phát hiện Tương đồng Ngữ nghĩa & Cấu trúc: Tìm các logic trùng lặp ngay cả khi tên hàm, tên biến, định dạng hoặc bình luận khác biệt hoàn toàn. Đây là điểm khác biệt lớn so với các công cụ truyền thống! * Tối ưu hóa cho Tác nhân AI: Slopo được tối ưu hóa để hoạt động cùng các trợ lý mã hóa AI (như Claude Code, OpenAI Codex hoặc các quy trình LLM tùy chỉnh). Nó xuất ra các cụm tương đồng được sắp xếp gọn gàng, có thứ tự ưu tiên, có thể đưa trực tiếp vào tác nhân AI để thực hiện tái cấu trúc tự động một cách an toàn. 🤖✨ * Ngôn ngữ được Hỗ trợ: Ngay lập tức, Slopo cung cấp phân tích cú pháp và AST cho Python, TypeScript, JavaScript, Java, Kotlin, C#, Go và Rust. Một danh sách khá ấn tượng cho nhiều môi trường phát triển! * Lọc & Xếp hạng Thông minh: Nhóm các cặp trùng lặp thành các cụm có thể hành động và xếp hạng chúng dựa trên cả độ tương đồng Cosine và khoảng cách vật lý trong codebase.
⚙️ Cách Slopo Hoạt Động (Dưới Lớp Vỏ)
Quy trình thực thi của Slopo bao gồm ba giai đoạn riêng biệt, được thiết kế tinh vi để mang lại độ chính xác cao nhất:
1. Tạo Embedding: Slopo phân tích codebase, chia các tệp thành các đơn vị mã có ngữ nghĩa (hàm, lớp hoặc khối mã), sau đó tính toán một embedding vector cho mỗi đơn vị. Theo mặc định, nó hỗ trợ bất kỳ mô hình embedding nào tương thích với LiteLLM (chẳng hạn như text-embedding-3 của OpenAI, các mô hình embedding mã chuyên biệt của Voyage AI, hoặc Cohere). Các mô hình của Voyage AI đặc biệt được khuyến nghị do khả năng xử lý ngôn ngữ lập trình vượt trội và hiệu suất tuyệt vời ngay cả ở chiều thấp (như vector 512). Đây là chìa khóa để Slopo nhận diện được "ý nghĩa" thực sự của mã nguồn! 🧠
2. Lọc và Xếp hạng Lại Hai Lần: * Lượt 1 (Độ tương đồng Cosine): Lọc các cặp đơn vị mã có điểm độ tương đồng Cosine thấp hơn ngưỡng cấu hình (thường là similarity_threshold = 0.85). * Lượt 2 (Tăng cường và Xếp hạng lại theo Khoảng cách): Áp dụng một cơ chế tăng cường chuyên biệt cho điểm tương đồng dựa trên vị trí của các đoạn trùng lặp: * Trong các tệp/module khác nhau: Tăng cường lên tới 15% dựa trên số lần nhảy thư mục giữa các tệp. Mã có ngữ nghĩa tương tự nằm ở các phần hoàn toàn khác nhau của dự án đại diện cho rủi ro cao nhất về lỗi phân kỳ và được tăng cường để thu hút sự chú ý của nhà phát triển. * Trong cùng một tệp: Tăng cường lên tới 10% dựa trên khoảng cách dòng vật lý. * Các cụm mà cặp có điểm cao nhất của chúng nằm dưới rerank_threshold cuối cùng sẽ bị loại bỏ.
3. Loại bỏ Trùng lặp Chính xác Thông minh: Nếu tìm thấy nhiều bản sao chính xác của một đoạn mã, Slopo sẽ nhóm chúng lại và hiển thị một khối mã duy nhất với tất cả các đường dẫn tệp liên quan. Điều này giúp báo cáo cuối cùng rõ ràng, dễ đọc và rất hữu ích. Báo cáo cuối cùng tính toán và hiển thị các tỷ lệ trùng lặp riêng biệt: một bao gồm các bản sao chính xác và một không bao gồm các bản sao chính xác, cung cấp một chỉ số rõ ràng về sự trùng lặp ngữ nghĩa so với vật lý. 📊
🚀 Khởi Đầu Nhanh & Cài Đặt
Bắt đầu sử dụng Slopo rất đơn giản, chỉ với vài bước lệnh dòng:
1. Cài đặt
Slopo được phân phối dưới dạng gói Python và có thể được cài đặt gọn gàng vào một môi trường riêng biệt bằng công cụ uv:
bash uv tool install slopo
2. Khởi tạo & Thiết lập
Chạy lệnh khởi tạo để tạo tệp cấu hình mặc định (slopo.toml):
bash slopo init
Lưu ý quan trọng: Đảm bảo bạn đã thiết lập khóa API của nhà cung cấp embedding (ví dụ: SLOPO_EMBEDDING_API_KEY hoặc OPENAI_API_KEY). Đây là bước không thể thiếu để Slopo hoạt động hiệu quả! 🔑
3. Lệnh Thực thi
Để phân tích codebase của bạn, hãy xác thực các cài đặt và thực thi các lệnh pipeline tuần tự:
```bash # Xác minh cấu hình và thông tin xác thực đang hoạt động slopo show-config
1. Phân tích và lập chỉ mục tệp vào cơ sở dữ liệu SQLite cục bộ
slopo index
2. Tạo embedding vector cho các đơn vị mã đã được lập chỉ mục
slopo embed
3. Phân tích embedding và xuất báo cáo cuối cùng
slopo analyze ```
🛠️ Quy Trình Thực Tế cho Tái Cấu Trúc Hướng AI
Slopo tích hợp hoàn hảo vào một chu trình CI/CD hiện đại hoặc một pipeline tái cấu trúc tương tác, hướng AI:
1. Báo cáo Ban đầu: Chạy slopo analyze để xuất báo cáo markdown toàn diện (index.md) trong thư mục reports/. 2. Loại trừ & Tinh chỉnh: Nếu báo cáo chứa các khối mã tầm thường (ví dụ: test fixtures hoặc mock modules), hãy điều chỉnh source_dir_exclude trong slopo.toml hoặc tăng body_node_count_threshold để lọc chúng ra. 3. Lọc & Bỏ qua bằng AI: Đưa báo cáo cho một tác nhân AI (như Claude Code hoặc GitHub Action). Yêu cầu tác nhân xem xét các cụm. Nếu một cụm là dương tính giả hoặc trùng lặp có chủ ý, tác nhân có thể thêm mã hash duy nhất của nó vào slopo.ignore.txt. 🤖 4. Tái cấu trúc Tự động: Đối với các cụm trùng lặp còn lại, hãy ra lệnh cho tác nhân AI của bạn tái cấu trúc mã trùng lặp thành một hàm trợ giúp hoặc thư viện dùng chung, sau đó chạy slopo analyze một lần nữa để xác minh rằng sự trùng lặp đã được giải quyết thành công. 5. Đồng bộ Hóa Nhóm: Commit slopo.toml và slopo.ignore.txt vào kho lưu trữ git của bạn. Quan trọng: Tuyệt đối không commit cơ sở dữ liệu cục bộ slopo.db! 🛑
📝 Tham Chiếu Cấu Hình
Slopo hoàn toàn có thể cấu hình được, cho phép bạn tinh chỉnh để phù hợp với nhu cầu cụ thể của dự án. Dưới đây là tham chiếu các thông số chính:
| Tham số | Kiểu | Mặc định | Mô tả | | :--- | :--- | :--- | :--- | | source_dir | string | . | Thư mục nguồn chứa codebase để lập chỉ mục. | | source_dir_exclude | list | [] | Các mẫu glob để loại trừ (ví dụ: ["**/test/**", "**/mocks/**"]). | | db_file | string | slopo.db | Cơ sở dữ liệu SQLite cục bộ để lưu trữ chỉ mục và embedding. | | report_dir | string | reports | Thư mục đích cho báo cáo phân tích markdown. | | ignore_file | string | slopo.ignore.txt | Đường dẫn đến danh sách bỏ qua chứa các mã hash cụm bị bỏ qua. | | embedding_model | string | | Tên mô hình embedding tương thích với LiteLLM (ví dụ: voyage/voyage-code-2). | | embedding_dimensions| int | | Kích thước chiều vector mục tiêu. | | similarity_threshold | float | 0.85 | Độ tương đồng Cosine tối thiểu giữa các đơn vị mã. | | rerank_threshold | float | 0.88 | Điểm tương đồng được tăng cường tối thiểu sau khi xếp hạng lại theo khoảng cách. | | body_node_count_threshold| int | 8 | Số lượng nút AST tối thiểu trong một khối mã để được xem xét phân tích. |
🚨 Cảnh báo quan trọng: Các tham số cốt lõi xác định quá trình lập chỉ mục và tạo embedding (như source_dir, embedding_model, và body_node_count_threshold) không thể thay đổi sau khi lập chỉ mục ban đầu. Để cập nhật chúng, bạn cần xóa tệp slopo.db cục bộ của mình và chạy lại slopo index và slopo embed.