Xây dựng và chạy CometixCode, trợ lý lập trình AI trên terminal bằng Rust

CometixCode là gì?

CometixCode là trợ lý lập trình AI chạy trên terminal, được viết bằng Rust. Đây là bản triển khai lại độc lập theo từng tệp của giao diện terminal Claude Code của Anthropic, không phải sản phẩm chính thức của Anthropic.

CometixCode không chính thức, không liên kết với Anthropic và không được Anthropic chứng thực hoặc hỗ trợ. Claude và Claude Code là các nhãn hiệu của Anthropic, PBC.

Giao diện terminal Claude Code ban đầu sử dụng TypeScript cùng React và Ink. CometixCode tái tạo cấu trúc đó bằng Rust thông qua CometixTUI, một nhánh của framework giao diện terminal retained-mode iocraft. Các component TypeScript được ánh xạ sang component Rust, hook được ánh xạ sang hook, còn những khác biệt kiến trúc có chủ đích được ghi lại trong mã nguồn.

Dự án vẫn đang trong quá trình phát triển. Phần lớn vòng lặp tương tác, thực thi công cụ, quyền hạn, tích hợp Model Context Protocol và các lệnh slash đã được triển khai, nhưng một số khu vực vẫn chưa hoàn thiện.

Tính năng và kiến trúc chính

• Giao diện terminal dựa trên Rust: Giao diện được triển khai theo mô hình component và hook kiểu React.
• Chuyển port kiến trúc gần sát: Dự án bám theo cấu trúc CLI được công bố của Claude Code theo từng tệp, thay vì thay thế bằng một thiết kế mới.
• Quy trình lập trình tương tác: Các phần chính của vòng lặp trợ lý và hệ thống thực thi công cụ đã được triển khai.
• Quyền hạn và lệnh: Tính năng xử lý quyền hạn và hỗ trợ lệnh slash đã được triển khai khá đầy đủ.
• Hỗ trợ MCP: Chức năng Model Context Protocol được tích hợp, dù toàn bộ dự án vẫn đang phát triển.
• Tiện ích terminal nâng cao: CometixTUI cung cấp cơ chế diff ở cấp hàng, lan truyền sự kiện, khôi phục SIGCONT, hỗ trợ con trỏ IME, dán có đánh dấu và bố cục dạng lưới.
• Tìm kiếm tệp bên ngoài: CometixCode sử dụng một tệp thực thi ripgrep riêng thay vì biên dịch ripgrep vào tệp nhị phân của mình.

Điều kiện tiên quyết

Trước khi xây dựng CometixCode, hãy cài đặt các phần phụ thuộc sau:

• Rust 1.87 trở lên, sử dụng Rust edition 2024.
• ICU4C, bắt buộc đối với các crate rust_icu_* thông qua pkg-config.

Cài đặt ICU4C trên macOS

Homebrew cài ICU4C dưới dạng gói chỉ dùng keg. Hãy cài đặt gói này và thêm thư mục pkgconfig vào đường dẫn tra cứu:

brew install icu4c
export PKG_CONFIG_PATH="$(brew --prefix icu4c)/lib/pkgconfig"

Chạy lệnh export trong shell dùng để xây dựng CometixCode. Nếu thường xuyên làm việc với dự án, hãy thêm biến này vào tệp cấu hình shell phù hợp.

Cài đặt ICU4C trên Debian hoặc Ubuntu

sudo apt install libicu-dev pkg-config

Xây dựng CometixCode

Mở terminal tại thư mục gốc của repository và tạo bản build release đã tối ưu:

cargo build --release

Tệp nhị phân tạo ra có tên cometix. Bản build release phù hợp cho việc sử dụng thông thường vì bật các tối ưu hóa release của Rust.

Chạy trợ lý

Xây dựng và khởi chạy CometixCode thông qua Cargo bằng lệnh:

cargo run --release

Lệnh này khởi động giao diện terminal bằng profile release. Vì dự án đang được phát triển tích cực, một số quy trình có thể chưa hoàn thiện dù các chức năng tương tác, công cụ, quyền hạn, MCP và lệnh chính đã hiện diện.

Lệnh chẩn đoán cơ bản

Bên trong CometixCode, sử dụng lệnh slash sau để kiểm tra môi trường đã cấu hình, bao gồm tệp thực thi ripgrep đang được sử dụng:

/doctor

Lệnh này đặc biệt hữu ích khi không thể tìm kiếm tệp hoặc khi bạn cần xác nhận CometixCode đã chọn tệp nhị phân rg được đóng gói hay cài đặt trên máy chủ.

Cấu hình ripgrep cho tính năng tìm kiếm tệp

CometixCode ủy quyền việc tìm kiếm tệp cho rg, công cụ dòng lệnh ripgrep. Tệp thực thi ripgrep vẫn là một tài nguyên bên ngoài và không bao giờ được biên dịch vào tệp thực thi cometix.

CometixCode tìm ripgrep theo thứ tự sau:

1. vendor/ripgrep/<arch>-<os>/rg nằm cạnh tệp thực thi, được dùng bởi các gói phát hành.
2. vendor/ripgrep/<arch>-<os>/rg trong cây mã nguồn, được dùng trong quá trình phát triển.
3. Lệnh rg của hệ thống máy chủ, khả dụng thông qua PATH.

Do đó, bạn có thể đặt bản ripgrep cố định vào thư mục nền tảng tương ứng trong vendor/ripgrep/, hoặc cài ripgrep trên máy chủ và bảo đảm rg có trong PATH.

Buộc sử dụng tệp nhị phân ripgrep của máy chủ

Đặt USE_BUILTIN_RIPGREP thành 0 khi muốn CometixCode bỏ qua tài nguyên ripgrep đi kèm và sử dụng tệp thực thi của máy chủ:

USE_BUILTIN_RIPGREP=0 cargo run --release

Sau khi khởi chạy, chạy /doctor để xác minh tệp nhị phân đã được chọn.

Chạy bộ kiểm thử đúng cách

CometixCode có trạng thái trên toàn bộ tiến trình, bao gồm các biến môi trường và bộ nhớ đệm OnceLock. Việc chạy mọi kiểm thử dưới dạng các thread trong cùng một tiến trình có thể khiến trạng thái rò rỉ giữa các kiểm thử, vì vậy cargo test thông thường không được xem là cổng kiểm tra chất lượng hợp lệ cho crate này.

Thay vào đó, dự án sử dụng cargo-nextest, được gọi thông qua just. Cách này cung cấp cho mỗi kiểm thử một tiến trình riêng và cố định trạng thái máy chủ mà kiểm thử có thể kế thừa nếu không.

Chạy toàn bộ bộ kiểm thử

just test

Đây là bước kiểm tra toàn bộ bắt buộc của dự án.

Chạy các kiểm thử khớp với một mẫu

just t <pattern>

Thay thế <pattern> bằng một chuỗi con được dùng để lọc các bài kiểm thử bạn muốn thực thi.

Kiểm tra mã nhanh

just check

Lệnh này thực hiện kiểm tra kiểu và quyền mượn mà không liên kết, rất hữu ích để nhận phản hồi nhanh khi chỉnh sửa mã Rust.

Mẹo phát triển nâng cao

• Ưu tiên chế độ phát hành cho mục đích sử dụng thông thường: Dùng cargo run --release để chạy bản dựng đã tối ưu được chỉ định trong tài liệu dự án.
• Kiểm tra việc phát hiện ICU trước: Trên macOS, lỗi dựng liên quan đến ICU có thể cho biết rằng PKG_CONFIG_PATH không bao gồm thư mục siêu dữ liệu ICU4C của Homebrew.
• Chẩn đoán việc tìm kiếm tệp bằng /doctor: Xác nhận chính xác tệp thực thi ripgrep được chọn trước khi thay đổi các tệp vendored hoặc cấu hình hệ thống.
• Ghim phiên bản ripgrep khi cần khả năng tái lập: Đặt tệp nhị phân mong muốn trong đường dẫn vendor/ripgrep/ dành riêng cho nền tảng thay vì phụ thuộc vào phiên bản đang được cài đặt toàn cục.
• Không dùng cargo test thay cho bước kiểm tra của dự án: Dùng just test để các bài kiểm thử nhận được cơ chế cô lập tiến trình theo yêu cầu của mã nguồn.
• Tham khảo justfile để hiểu lý do chọn chiến lược kiểm thử: Phần đầu tệp ghi lại các phép đo làm cơ sở cho chiến lược kiểm thử đã chọn.

Lưu ý về giấy phép

CometixCode được phân phối theo giấy phép AGPL-3.0-only. Giấy phép bao gồm điều khoản về việc sử dụng qua mạng: nếu bạn vận hành một phiên bản đã sửa đổi dưới dạng dịch vụ mạng, người dùng của dịch vụ đó có quyền nhận mã nguồn tương ứng của phiên bản đã sửa đổi.

Kết luận

CometixCode cung cấp một bản tái tạo kiến trúc terminal Claude Code dựa trên Rust bằng CometixTUI. Khi đã có Rust, ICU4C và tệp thực thi ripgrep phù hợp, bạn có thể dựng và khởi chạy chương trình bằng Cargo, kiểm tra cấu hình tìm kiếm qua /doctor và xác thực các thay đổi bằng quy trình just test cô lập tiến trình của dự án.