Bắt đầu với opencode-rust: Tác nhân lập trình AI dựa trên Rust

opencode-rust là gì?

opencode-rust là một tác nhân lập trình AI mã nguồn mở được triển khai bằng Rust. Công cụ cung cấp giao diện người dùng trên terminal, thực thi lệnh một lần, máy chủ HTTP, hỗ trợ Web và tích hợp ACP cho các quy trình làm việc với tác nhân AI cục bộ.

Công cụ kết hợp phiên làm việc, thực thi công cụ, MCP, LSP, định tuyến nhà cung cấp, lưu trữ SQLite và cầu nối plugin TypeScript. Công cụ có thể chạy mà không cần Docker hoặc một runtime container khác. Rust được sử dụng để giới hạn mức tiêu thụ tài nguyên thông qua thân request được streaming, lịch sử hội thoại dựa trên SQLite, schema công cụ được lưu trong bộ nhớ đệm và trạng thái theo từng thư mục được dùng chung với cơ chế loại bỏ LRU và TTL.

Chọn phương thức cài đặt

Tất cả phương thức cài đặt được hỗ trợ đều cung cấp lệnh opr, nhưng lệnh này hoạt động khác nhau tùy theo cách cài đặt.

Cài đặt bằng npm

npm hỗ trợ Linux, macOS và Windows, đồng thời tải xuống gói binary dựng sẵn cho nền tảng hiện tại. npm không biên dịch dự án trong quá trình cài đặt.

npm install -g opencode-rust

Trình khởi chạy npm là một script Node chuyển tiếp các lệnh đến engine. Các gói nền tảng hiện có gồm macOS ARM64 và x64, bản dựng Linux x64 và ARM64 GNU, Linux x64 musl và Windows x64 MSVC.

Cài đặt bằng Homebrew

Trên macOS hoặc Linux, cài formula Homebrew bằng lệnh:

brew install vakandi/tap/opencode-rust

Lệnh này cài đặt opr mà không đặt binary opencode vào tiền tố Homebrew, vì vậy không che khuất OpenCode CLI upstream. Homebrew biên dịch từ mã nguồn nên sẽ cài toolchain Rust dưới dạng dependency khi build.

Biên dịch từ mã nguồn

Sao chép repository và chạy trình cài đặt:

git clone https://github.com/vakandi/opencode-rust.git
cd opencode-rust
./install.sh

Trình cài đặt biên dịch binary bản release và cài đặt opr cùng các shortcut cho tác nhân. Trình cài đặt tạo fingerprint từ mã nguồn Rust và các file manifest Cargo, vì vậy dự án không thay đổi sẽ không được build lại. Dùng --force để luôn build lại.

Khi sử dụng Homebrew hoặc trình cài đặt từ mã nguồn, opr chính là binary engine. Hãy dùng subcommand rõ ràng khi truyền cờ:

opr tui --some-flag

Với npm, trình khởi chạy chuyển tiếp các cờ đến TUI, vì vậy opr --some-flag được diễn giải khác.

Chuẩn bị môi trường

Cần Node.js 18 trở lên cho cầu nối plugin và để khởi chạy các máy chủ MCP thông qua npx, bất kể phương thức cài đặt nào được sử dụng.

Bạn cũng cần khóa của nhà cung cấp trước lần chạy đầu tiên. Ví dụ, đặt khóa Anthropic trong shell:

export ANTHROPIC_API_KEY=sk-ant-...

Sử dụng cấu hình nhà cung cấp và thông tin xác thực được OpenCode setup của bạn hỗ trợ. Khi có thể, hãy giữ khóa ngoài hệ thống quản lý mã nguồn và lịch sử shell.

Chạy phiên làm việc đầu tiên

Khởi động TUI tương tác

Khởi chạy giao diện terminal bằng lệnh:

opr

TUI là giao diện tương tác mặc định. Giao diện hiển thị tác nhân và model đang hoạt động, streaming đầu ra của assistant và cung cấp tính năng hoàn thành lệnh thông qua popup /.

Chạy một prompt duy nhất

Để chạy một prompt tự động đến khi hoàn tất, dùng run:

opr run "check this repo for risks"

Không giống một lời gọi nhà cung cấp đơn giản, run điều khiển toàn bộ vòng lặp prompt của phiên làm việc. Các công cụ được thực thi, các subagent được chờ sẽ hoàn tất và công việc nền được xử lý hết trước khi tiến trình thoát.

Khởi động máy chủ HTTP

Để cung cấp engine thông qua máy chủ HTTP, chạy:

opr serve --port 3000

Máy chủ sử dụng cùng engine phiên làm việc và hỗ trợ hạ tầng HTTP, streaming và agent của dự án.

Sử dụng các tác nhân có tên

TUI tích hợp sẵn các tác nhân build và plan. Tác nhân build là tác nhân phát triển mặc định với toàn quyền truy cập, còn plan dành cho phân tích và khám phá chỉ đọc. Nhấn Tab để chuyển tác nhân trong TUI.

Trình cài đặt từ mã nguồn cũng tạo shortcut cho các tác nhân có tên:

gilfoyle "fix this failing test"
setbon "write 5 ad hooks"
googlebot "audit my meta tags"

Các shortcut này chạy một prompt với giá trị --agent tương ứng. Gọi shortcut mà không cung cấp prompt sẽ in thông tin hướng dẫn sử dụng ra standard error và thoát với status 2.

Có thể cấu hình thêm tác nhân trong cấu hình OpenCode và trong các kho tác nhân oh-my-opencode tại ~/.omo/omo.jsonc hoặc ~/.config/omo/omo.jsonc. Cấu hình tác nhân từ các vị trí này có thể ghi đè giá trị mặc định của plugin, và các tác nhân được đối chiếu bằng slug chuẩn hóa ngay cả khi tên hiển thị khác nhau.

Cấu hình dự án và phiên làm việc

Các file cấu hình được hợp nhất khi tìm kiếm ngược lên từ thư mục làm việc. Các tên được hỗ trợ ở cấp dự án là:

• opencode.jsonc
• opencode.json
• .opencode/opencode.jsonc
• .opencode/opencode.json

Cấu hình mặc định toàn cục được lưu tại ~/.config/opencode/opencode.json hoặc phiên bản JSONC tương ứng. Định nghĩa tác nhân cũng có thể được lưu tại các vị trí oh-my-opencode được mô tả ở trên.

Phiên làm việc được lưu trong SQLite và hỗ trợ tạo, tiếp tục, fork, nhập và xuất, cũng như quan hệ cha-con. Để kiểm tra vị trí cơ sở dữ liệu, dùng:

opr db path

Để kiểm tra các vị trí runtime khác, bao gồm thư mục dữ liệu được proxy pool sử dụng, dùng:

opr debug paths

Sử dụng công cụ MCP

opencode-rust hỗ trợ MCP qua stdio và HTTP. Các máy chủ MCP được tải từ cấu hình, khởi động song song với thời hạn khởi động 90 giây và được đăng ký trong cùng registry công cụ theo từng lượt mà agent sử dụng.

Điều này có nghĩa là các công cụ được máy chủ MCP cung cấp có thể tiếp cận mô hình và thực thi như một phần của lượt hoạt động của tác tử. Hãy đảm bảo Node.js và các gói máy chủ MCP cần thiết đã có sẵn trước khi bắt đầu một phiên.

Dự án sử dụng JSON phân tách bằng ký tự xuống dòng cho giao thức truyền tải stdio của MCP. Cách này khác với cơ chế đóng khung Content-Length của LSP, vì vậy cấu hình máy chủ MCP nên hướng đến các giao thức truyền tải và định nghĩa tương thích với MCP.

Đảm bảo tác vụ nền hoàn tất

Lệnh run chấp nhận thời gian chờ để xử lý các tác vụ nền còn tồn đọng:

opr run --wait-background-timeout 120 "run the requested task"

Sau lượt chính, engine chờ phiên chuyển sang trạng thái rảnh, truyền các khung tiến trình con được oh-my-opencode ghi lại và kiểm tra trạng thái tiếp tục. Thời gian chờ mặc định là 120 giây.

Quá trình xử lý kết thúc theo hướng cho phép tiếp tục thay vì bị treo: cơ sở dữ liệu bị thiếu, sổ cái bị thiếu, JSON hỏng và các mục đang hoạt động đã lỗi thời đều được xem như không còn công việc nào. Hãy dùng thời gian chờ ngắn hơn hoặc dài hơn khi quy trình của bạn yêu cầu giới hạn khác.

Cấu hình proxy xoay vòng

Engine tích hợp một bộ chuyển tiếp HTTP và CONNECT cục bộ, luân phiên qua các ứng viên proxy dân cư. Cứ khoảng 120 giây, bộ chuyển tiếp chọn máy chủ upstream được sử dụng lâu nhất, kiểm tra các ứng viên trước khi dùng và cách ly những mục bị từ chối.

Tệp pool mặc định nằm tại:

• macOS: ~/Library/Application Support/opencode/proxy-pool.txt
• Linux: ~/.local/share/opencode/proxy-pool.txt
• Windows: %LOCALAPPDATA%\opencode\proxy-pool.txt

Đặt OPENCODE_PATHS_ROOT để di chuyển vị trí dữ liệu. Đường dẫn pool khi đó là $OPENCODE_PATHS_ROOT/opencode/proxy-pool.txt.

Các mục sử dụng máy chủ và cổng, cùng thông tin xác thực và siêu dữ liệu tùy chọn:

198.51.100.10:8080
203.0.113.24:1080
198.51.100.31:3128:myuser:mypass
203.0.113.77:8000 | note:rotates hourly

Chỉ giữ các mục thuần túy trong tệp. Mặc dù trong một số ví dụ, các dòng bắt đầu bằng # được hiển thị dưới dạng chú thích, bộ phân tích cú pháp không triển khai cú pháp chú thích; các dòng đó sẽ bị bỏ qua vì là mục không hợp lệ. Các ứng viên thất bại và thông tin quyền sở hữu được duy trì trong các tệp proxy-quarantine.json và proxy-claims.json nằm cùng thư mục.

Việc khởi động proxy phải được thực hiện thông qua opencode_proxy::start() thay vì tự xuất các biến proxy. Client phải nhận cấu hình proxy trước khi registry của provider được tạo. Pool trống hoặc không thể đọc sẽ trả về lỗi thay vì khởi động một listener khiến mọi yêu cầu đều thất bại.

Khám phá các lệnh

CLI bao gồm các lệnh để sử dụng tương tác, phiên, dịch vụ, cấu hình, xác thực, tác tử, gỡ lỗi, MCP, truyền dữ liệu và bảo trì:

tui      attach   run      serve    web      acp      models
session  stats    db       config   auth     agent    debug
mcp      export   import   github   pr       upgrade  uninstall
generate version

Các tùy chọn run hữu ích gồm --continue, --session, --fork, --agent, --format, --title, --dir, --port, --variant, --thinking và --wait-background-timeout.

Phát triển và kiểm tra

Nếu bạn đang làm việc trên repository, hãy chạy các bài kiểm thử và bước kiểm tra của workspace bằng:

cargo test --workspace
cargo build --release --bin opencode
cargo clippy --workspace --all-targets

Repository được tổ chức thành các crate cho CLI, máy chủ, phiên, tác tử, công cụ, provider, MCP, plugin, LSP, lưu trữ, TUI, quyền, đường dẫn, proxy và các tiện ích liên quan. Tài liệu cho từng crate có trong thư mục docs/.

Kết luận

opencode-rust cung cấp một engine OpenCode dựa trên Rust với TUI tương tác, khả năng thực thi phiên đầy đủ, các tác tử có thể cấu hình, tích hợp MCP và plugin, bộ lưu trữ SQLite và khả năng truy cập HTTP. Hãy bắt đầu bằng npm, Homebrew hoặc build từ mã nguồn, cấu hình khóa provider, rồi sử dụng opr, opr run hoặc opr serve tùy theo quy trình của bạn.

Dự án được phát hành theo giấy phép MIT và không liên kết với nhóm OpenCode.