Sửa Lỗi Code Claude: Giải Pháp Từ Ruflo

Nếu bạn đã theo dõi hệ sinh thái Claude Code, có lẽ bạn đã nhận thấy một dự án âm thầm chuyển từ “một gói npm thú vị” thành “lớp điều phối mặc định cho các nhóm Claude Code nghiêm túc.” Đó là Ruflo, được duy trì bởi rUv, và nó phát triển từ nỗ lực claude-flow ban đầu. Ý tưởng rất đơn giản: Claude Code tự nó chỉ chạy một tác nhân tại một thời điểm. Ruflo biến nó thành một bầy tác nhân.

Hướng dẫn này giải thích Ruflo làm gì, nó khác với một chồng máy chủ MCP như thế nào, khi nào nên cài đặt nó, và cách kiểm tra các tác nhân cùng lưu lượng MCP bên dưới bằng Apidog. Nếu bạn mới bắt đầu với định dạng tệp tác nhân mà Claude Code đọc khi khởi động, hướng dẫn agents.md của chúng tôi là tài liệu cần đọc trước.

Tải ứng dụng

Tóm tắt

Ruflo (trước đây là claude-flow) là một nền tảng điều phối đa tác nhân cho Claude Code do rUv phát triển, với 98 tác nhân, hơn 60 lệnh, 30 kỹ năng, một máy chủ MCP, các hook và một daemon.
Một lệnh npx ruvflo init sẽ thêm một lớp điều phối cho phép Claude Code tạo ra các bầy tác nhân, chia sẻ bộ nhớ giữa các phiên và liên kết công việc giữa các máy.
Có hai đường dẫn cài đặt: Plugin Claude Code nhẹ (chỉ có lệnh slash) và cài đặt CLI đầy đủ (mọi thứ được kết nối).
Bên dưới đó là một công cụ AI mạnh mẽ bằng Rust, các nhúng, hệ thống plugin và kiến trúc Cognitum.One.
Sử dụng Apidog để kiểm tra các điểm cuối tools/list, tools/call và liên kết của máy chủ MCP; mô phỏng nhà cung cấp LLM trong quá trình CI; và phát lại lưu lượng truy cập bầy tác nhân khi một lỗi hồi quy tác nhân xuất hiện.
Tải Apidog để thêm một lớp hợp đồng lên Ruflo trước khi nó chiếm nhiều hơn trong quy trình làm việc hàng ngày của bạn.

Ruflo thực sự làm gì

Theo mặc định, Claude Code là một vòng lặp tác nhân đơn: bạn nói chuyện với một mô hình, nó chỉnh sửa một không gian làm việc, nó không ghi nhớ gì giữa các phiên. Điều đó hiệu quả cho các tác vụ ngắn. Nó sẽ gặp khó khăn khi bạn muốn một bầy tác nhân chuyên biệt tấn công một tác vụ tái cấu trúc, hoặc khi bạn muốn phát hiện của một tác nhân thông báo cho phiên tiếp theo, hoặc khi bạn muốn hai máy phối hợp với nhau.

Ruflo tích hợp vào Claude Code như một lớp điều phối. Sau khi init, mọi tác vụ bạn giao cho Claude đều đi qua một bộ định tuyến (router) quyết định liệu có nên:

Chạy tác vụ dưới dạng tác nhân đơn (mặc định của Claude Code)
Tạo ra một bầy chuyên gia (ví dụ: một cho đánh giá bảo mật, một cho kiểm thử, một cho tài liệu)
Tiếp tục từ bộ nhớ của một phiên trước đó
Liên kết công việc với một tác nhân trên một máy khác

README mô tả nó là “Claude Code với một hệ thần kinh.” Điều đó thể hiện rõ bản chất: Ruflo không thay thế Claude Code, nó thêm một lớp làm cho 100 tác nhân chuyên biệt cảm thấy như một công cụ duy nhất.

Kiến trúc trong một sơ đồ

Luồng đơn giản hóa từ README:

User -> Ruflo (CLI/MCP) -> Router -> Swarm -> Agents -> Memory -> LLM Providers
                       ^                          |
                       +---- Learning Loop <------+

Năm thành phần quan trọng để kiểm thử.

Điểm vào CLI/MCP. Bạn có thể điều khiển Ruflo từ dòng lệnh hoặc từ tích hợp MCP của Claude Code. Cả hai giao diện đều sử dụng cùng một giao thức bên dưới.

Bộ định tuyến (Router). Một bộ phân loại nhỏ (có thể cấu hình, có thể là một mô hình cục bộ) quyết định đường dẫn mà tác vụ sẽ đi. Bầy tác nhân so với tác nhân đơn so với tiếp tục so với liên kết.

Bầy tác nhân (Swarm). Một nhóm các tác nhân chuyên biệt với các lời nhắc (prompts) và bộ công cụ tập trung. Việc tạo ra một bầy tác nhân tương đương với crew của CrewAI, nhưng được tích hợp chặt chẽ hơn với ngữ cảnh riêng của Claude Code.

Bộ nhớ. Duy trì giữa các phiên, có thể truy vấn bởi các tác nhân tương lai. Đây là nơi “vòng lặp học tập” chạy: các mẫu thành công được chấm điểm và tái sử dụng.

Các nhà cung cấp LLM. Ruflo không phụ thuộc vào nhà cung cấp. Claude là mặc định; OpenAI, DeepSeek, Gemini và Ollama cục bộ hoạt động thông qua cấu hình nhà cung cấp tiêu chuẩn.

Có hai đường dẫn cài đặt; hãy chọn dựa trên mức độ bạn thực sự muốn sử dụng.

Các đường dẫn cài đặt và những gì mỗi đường dẫn mang lại cho bạn

README nêu rõ về một sự đánh đổi khiến người dùng lần đầu gặp khó khăn.

Đường dẫn A: Plugin Claude Code (bản nhẹ). Bạn cài đặt thông qua marketplace của Claude Code: /plugin install ruflo-core@ruflo. Điều này chỉ thêm các lệnh slash và định nghĩa tác nhân. Máy chủ MCP của Ruflo không được đăng ký, có nghĩa là các công cụ như memory_store, swarm_init và agent_spawn không thể gọi được từ Claude. Thích hợp để thử các lệnh của một plugin mà không cần cam kết.

Đường dẫn B: Cài đặt CLI (đầy đủ). Bạn chạy npx ruvflo init trong dự án của mình. Điều này thiết lập .claude/, .claude-flow/, CLAUDE.md, các tập lệnh hỗ trợ và máy chủ MCP. Các hook sẽ kích hoạt trên mỗi tương tác của Claude Code. Bộ nhớ được duy trì. 98 tác nhân, hơn 60 lệnh, 30 kỹ năng và tính năng liên kết đều được kết nối.

README cảnh báo: “sau khi init, chỉ cần sử dụng Claude Code bình thường; hệ thống hook sẽ tự động định tuyến các tác vụ.” Đó chính là điểm mấu chốt. Bạn không cần phải ghi nhớ 314 công cụ MCP. Khung làm việc sẽ xử lý việc định tuyến.

Đối với hầu hết các nhóm kỹ thuật đang sử dụng Claude Code một cách nghiêm túc, Đường dẫn B là điều bạn muốn. Đường dẫn A là để đánh giá một plugin duy nhất một cách độc lập.

Những gì có trong gói sản phẩm

Một vài thành phần nổi bật từ danh mục plugin.

ruflo-core. Bộ nhớ lưu trữ, khởi tạo bầy tác nhân, các nguyên thủy tạo tác nhân. Nền tảng mà mọi plugin khác xây dựng dựa trên đó.

ruflo-swarm. Điều phối đa tác nhân với chuyên môn hóa vai trò. Tạo một bầy đánh giá mã với tác nhân bảo mật, tác nhân hiệu suất, tác nhân tài liệu và một tác nhân tổng hợp.

ruflo-autopilot. Tự động hóa tác vụ chạy dài. Giao một mục tiêu cho khung làm việc và để nó lặp lại cho đến khi hoàn thành, với các điểm kiểm tra.

ruflo-federation. Giao tiếp tác nhân-đến-tác nhân an toàn giữa các máy. Lớp liên kết mã hóa các tải trọng để hai tổ chức có thể cho phép các tác nhân cộng tác mà không làm rò rỉ mã nguồn.

RuVector. Kho vector và phần backend đồ thị được sử dụng bởi lớp bộ nhớ. Tùy chọn nhưng được khuyến nghị khi dự án của bạn có hơn vài trăm phiên ngữ cảnh tích lũy.

Thị trường plugin cũng cung cấp các gói chuyên dụng cho kiểm thử, bảo mật, tái cấu trúc và khả năng quan sát. Mô hình này nhất quán: một plugin tương đương với một khả năng tập trung, tất cả đều được xây dựng dựa trên bộ nhớ cốt lõi và các nguyên thủy bầy tác nhân.

Tại sao lớp MCP lại quan trọng

Máy chủ MCP của Ruflo là yếu tố giúp khung làm việc được kết nối vào môi trường chạy của Claude Code. Mỗi lần tạo bầy tác nhân, ghi bộ nhớ và chuyển giao liên kết đều là một cuộc gọi JSON-RPC tới máy chủ MCP cục bộ.

Điều đó khiến bề mặt MCP trở thành điều quan trọng nhất để kiểm thử. Nếu tools/list gặp lỗi hồi quy, Claude Code sẽ ngừng nhận diện các nguyên thủy bầy tác nhân và nhóm của bạn sẽ âm thầm quay trở lại chế độ tác nhân đơn. Nếu memory_store trả về định dạng sai, các tác nhân sẽ bắt đầu tạo ra ngữ cảnh ảo giác.

Đây là vấn đề tương tự mà chúng tôi đã đề cập trong hướng dẫn kiểm thử máy chủ MCP. Máy chủ MCP của Ruflo là một API JSON-RPC; hãy xử lý nó như vậy.

Kiểm thử máy chủ MCP của Ruflo bằng Apidog

Một kế hoạch kiểm thử khởi đầu sẽ tự bù đắp chi phí ngay trong lần đầu tiên nó bắt được lỗi hồi quy.

Bước 1: chụp các yêu cầu chuẩn. Chạy npx ruvflo init trong một dự án nháp. Thực hiện một vài tác vụ đại diện thông qua Claude Code khi Ruflo đang hoạt động. Mở trình kiểm tra MCP của Claude Code và chụp các khung JSON-RPC cho initialize, tools/list, tools/call với swarm_init và tools/call với memory_store.

Bước 2: dán chúng vào Apidog. Tạo một dự án mới, đặt URL cơ sở thành máy chủ MCP Ruflo cục bộ của bạn (Đường dẫn B cài đặt nó như một MCP đã đăng ký) và lưu mỗi khung đã chụp làm một yêu cầu. Apidog xử lý các nội dung JSON-RPC một cách tự nhiên.

Bước 3: thêm các xác nhận.

initialize: xác nhận result.serverInfo.name == "ruflo" và phiên bản giao thức là phiên bản bạn hỗ trợ.
tools/list: xác nhận result.tools.length >= 100 (Ruflo đi kèm ~100 công cụ), mỗi công cụ có name, description và inputSchema.
tools/call cho swarm_init: xác nhận phản hồi bao gồm một ID bầy tác nhân và không phải là kết quả lỗi.
tools/call cho memory_store: xác nhận ghi thành công và cùng một khóa có thể đọc được bằng memory_get.

Bước 4: mô phỏng các nhà cung cấp LLM. Ruflo gọi Claude (hoặc bất kỳ nhà cung cấp nào bạn cấu hình) cho mỗi quyết định của tác nhân. Các lần chạy CI không nên truy cập một nhà cung cấp thực tế mỗi khi commit. Apidog mô phỏng điểm cuối tương thích với OpenAI bằng các phản hồi thực tế; hãy trỏ cấu hình nhà cung cấp của Ruflo đến bản mô phỏng trong quá trình kiểm thử. Mô hình này giống với mô hình chúng tôi đã ghi lại trong kiểm thử API không cần Postman.

Bước 5: chạy bộ kiểm thử trong CI. Trình chạy CLI của Apidog sẽ thoát với mã lỗi khác 0 khi xác nhận thất bại. Kết nối nó vào GitHub Actions và lần tới khi ai đó cập nhật Ruflo và làm hỏng định dạng MCP, PR của bạn sẽ thất bại trước khi được hợp nhất.

Apidog phù hợp với vòng lặp Ruflo hàng ngày ở đâu

Ngoài CI, có ba khoảnh khắc hàng ngày mà Apidog chứng tỏ giá trị của mình với Ruflo.

Khi một bầy tác nhân hoạt động sai. Phát lại trình tự chính xác của các khung tools/call mà Claude Code đã gửi. So sánh với một lần chạy tốt đã biết. Sự khác biệt thường cho thấy một đối số công cụ đã thay đổi vì mẫu lời nhắc (prompt template) đã thay đổi.

Khi bạn nâng cấp Ruflo. Phiên bản mới, bề mặt công cụ mới. Chạy bộ kiểm thử trước; sự khác biệt so với phiên bản trước cho bạn biết công cụ nào đã được đổi tên, xóa bỏ hoặc thay đổi định dạng. Chúng tôi sử dụng quy trình làm việc tương tự để so sánh các hợp đồng API trong phát triển API theo hợp đồng trước.

Khi liên kết gặp sự cố. Các tác nhân liên kết giao tiếp qua một kênh được mã hóa; gỡ lỗi quá trình bắt tay (handshake) mà không có công cụ đo lường là rất khó khăn. Apidog có thể ghi lại lưu lượng liên kết khi bạn trỏ nó vào cổng proxy cục bộ; nhật ký yêu cầu sẽ làm cho lỗi trở nên rõ ràng.

Các lỗi thường gặp

Các mẫu lỗi xuất hiện trong các vấn đề trên GitHub và trên Discord.

Cài đặt đường dẫn plugin và mong đợi toàn bộ chức năng. README đã rõ ràng; các plugin chỉ là lệnh slash. Nếu swarm_init không thể gọi được từ Claude, bạn đã cài đặt đường dẫn lite. Chạy lại npx ruvflo init để cài đặt đầy đủ.

Bỏ qua lớp hook. Đường dẫn B cài đặt các hook tự động định tuyến tác vụ. Nếu bạn gỡ cài đặt hoặc ghi đè chúng, bộ định tuyến sẽ không bao giờ kích hoạt và bạn sẽ mất khả năng điều phối bầy tác nhân. Hãy giữ nguyên mặc định cho đến khi bạn có lý do.

Để bộ nhớ phát triển không kiểm soát. Kho bộ nhớ là bền vững và không giới hạn theo mặc định. Sau vài tuần sử dụng nhiều, chỉ mục sẽ trở nên đủ lớn để làm chậm quá trình tạo bầy tác nhân. Cấu hình thời gian lưu giữ; trang cài đặt của README có giải thích các tùy chọn.

Coi nó như một công cụ chỉ dành cho Claude. Ruflo không phụ thuộc vào nhà cung cấp. Mặc định là Claude, nhưng bạn có thể chuyển sang DeepSeek V4 cho các bầy tác nhân nhạy cảm về chi phí hoặc sang Llama 5.1 cục bộ để chạy offline. Hướng dẫn API DeepSeek V4 và bài đăng về các LLM cục bộ tốt nhất năm 2026 của chúng tôi đề cập đến cấu hình nhà cung cấp cho cả hai.

Quên rằng liên kết vượt qua ranh giới tin cậy. Khi bạn liên kết với một máy khác, bạn đang gửi các tải trọng (có thể bao gồm mã) đến điểm cuối đó. Lớp mã hóa là vững chắc; công việc về chính sách là của bạn. Xác định dự án nào có thể liên kết trước khi bạn bật nó lên.

Ruflo so sánh với các khung làm việc tác nhân khác như thế nào

Ba khung làm việc thường xuyên được nhắc đến trong cùng một cuộc trò chuyện.

LangGraph. Cấp thấp hơn, chung chung. Bạn tự xây dựng sự điều phối. Chọn LangGraph khi bạn muốn kiểm soát hoàn toàn và quy trình làm việc của bạn không giống với Claude Code. Chúng tôi đã đề cập đến LangGraph trong bài viết về TradingAgents.

CrewAI. Đa tác nhân, không phụ thuộc vào khung làm việc, cấu hình phức tạp hơn. Chọn nó cho các quy trình làm việc không phải Claude mà Python là ngôn ngữ chính.

Các máy chủ MCP được xếp chồng thủ công. Tự xây dựng. Nhẹ hơn Ruflo, khó phối hợp hơn. Tốt cho hai hoặc ba máy chủ; rất khó khăn khi vượt quá năm.

Ngách của Ruflo là “Claude Code, nhưng với một bầy tác nhân.” Nếu Claude Code là công cụ bạn sử dụng hàng ngày và bạn muốn điều phối mà không phải viết 600 dòng mã MCP rườm rà, thì nó xứng đáng được cài đặt.

Ghi chú về hiệu suất và khả năng mở rộng

Hai quan sát vận hành từ các nhóm đã chạy Ruflo trong vài tháng.

Việc tạo một bầy tác nhân có chi phí cố định từ hai đến bốn giây cho quyết định của bộ định tuyến cộng với đăng ký công cụ. Đối với các tác vụ rất ngắn (một chỉnh sửa một dòng), chi phí này chiếm ưu thế; bạn muốn bộ định tuyến gửi các tác vụ đó theo đường dẫn tác nhân đơn, chứ không phải vào một bầy tác nhân. Định tuyến mặc định thường thực hiện điều này một cách chính xác; nếu không, cấu hình hook là nơi bạn điều chỉnh ngưỡng.

Các truy vấn bộ nhớ trở nên chậm hơn khi kho lưu trữ phát triển. SQLite xử lý tốt vài nghìn phiên; sau đó, hãy chuyển sang Postgres hoặc RuVector. Một nhóm đang chạy Ruflo với sáu kỹ sư và 18 tháng lịch sử báo cáo các truy vấn bộ nhớ trung bình 40 ms trên Postgres so với 600 ms trên SQLite mặc định với cùng khối lượng.

Các trường hợp sử dụng thực tế

Một nhóm nền tảng sử dụng lớp liên kết của Ruflo để chạy đánh giá bảo mật của một kho lưu trữ trong khi một bầy tác nhân tái cấu trúc chạy trên một kho lưu trữ khác, cả hai đều được điều phối thông qua một kho bộ nhớ chia sẻ. Họ đưa ra các khuyến nghị mâu thuẫn cho một người đánh giá.

Một nhà phát triển độc lập kết nối chế độ lái tự động của Ruflo với hàng đợi vé Linear: “chọn một vé P3, kiểm tra, đề xuất bản sửa lỗi, mở PR, tiếp tục.” Chế độ lái tự động chạy suốt đêm; nhà phát triển xem xét vào buổi sáng.

Một nhóm nghiên cứu sử dụng mô hình đánh giá mã đa tác nhân từ Ruflo để đánh giá chất lượng PR trên ba kho lưu trữ. Tổng chi tiêu LLM dưới 50 đô la một tuần trên Claude Sonnet, so với một người đánh giá thủ công với 80 đô la một giờ.

Kết luận

Ruflo là một câu trả lời nghiêm túc cho câu hỏi “làm thế nào để tôi mở rộng Claude Code vượt ra ngoài một tác nhân tại một thời điểm?” Việc cài đặt CLI bổ sung bộ nhớ, các bầy tác nhân, liên kết và một máy chủ MCP với hơn 100 công cụ chỉ trong một lệnh. Thị trường plugin phân chia các khả năng một cách rõ ràng để bạn có thể áp dụng dần dần.

Năm điểm chính:

Ruflo biến Claude Code thành một bộ điều phối bầy tác nhân với bộ nhớ bền vững và tính năng liên kết tùy chọn.
Đường dẫn A (plugin) dành cho việc đánh giá; Đường dẫn B (npx ruvflo init) dành cho việc sử dụng hàng ngày.
Máy chủ MCP là bề mặt hợp đồng; hãy kiểm thử nó theo cách bạn kiểm thử bất kỳ API JSON-RPC nào.
Apidog là nơi tốt nhất để chụp các yêu cầu MCP chuẩn, thêm các xác nhận và chạy bộ kiểm thử trong CI.
Mô phỏng nhà cung cấp LLM trong Apidog để các lần chạy CI luôn nhanh chóng và miễn phí.

Bước tiếp theo: chạy npx ruvflo init trong một dự án nháp, chụp các khung MCP trong trình kiểm tra của Claude Code và dán chúng vào một dự án Apidog. Lỗi hồi quy đầu tiên bạn phát hiện sẽ bù đắp chi phí cài đặt.

Câu hỏi thường gặp

Ruflo có giống claude-flow không?

Có. Ruflo là claude-flow đã được đổi tên, được duy trì bởi rUv (cùng tác giả). Gói npm là ruvflo; kho GitHub là ruvnet/ruflo. Các cấu hình claude-flow hiện có vẫn tiếp tục hoạt động.

Tôi có cần cả plugin và cài đặt CLI không?

Không. Hãy chọn một. Plugin cung cấp cho bạn các lệnh slash; cài đặt CLI cung cấp cho bạn toàn bộ lớp điều phối. Hầu hết các nhóm đều muốn cài đặt CLI.

Tôi có thể sử dụng Ruflo mà không cần Claude không?

Có. Ruflo không phụ thuộc vào nhà cung cấp. Cấu hình DeepSeek V4, GPT-5.5, Gemini hoặc một mô hình cục bộ trong cấu hình nhà cung cấp. Claude là mặc định vì khung làm việc phát triển từ claude-flow.

Bộ nhớ nằm ở đâu?

Trong một kho lưu trữ SQLite hoặc Postgres cục bộ, tùy thuộc vào cấu hình của bạn. Phần backend RuVector tùy chọn bổ sung tìm kiếm vector để truy xuất ngữ nghĩa. Bộ nhớ không rò rỉ ra dịch vụ bên thứ ba trừ khi bạn cấu hình điều đó một cách rõ ràng.

Làm cách nào để tôi kiểm thử máy chủ MCP trong CI?

Chụp các yêu cầu chuẩn bằng trình kiểm tra MCP, dán chúng vào Apidog, thêm các xác nhận JSONPath, chạy apidog run trong CI. Mô hình đầy đủ có trong hướng dẫn kiểm thử máy chủ MCP.

Liên kết có an toàn giữa các tổ chức không?

Lớp mã hóa là vững chắc. Lớp chính sách là trách nhiệm của bạn: xác định dự án nào có thể liên kết, loại bỏ bí mật khỏi tải trọng trước khi gửi và xem xét nhật ký kiểm tra thường xuyên.

Nó tốn bao nhiêu?

Khung làm việc được cấp phép MIT và miễn phí. Chi phí là token LLM cho các tác nhân và bất kỳ kho vector lưu trữ nào bạn chọn. Một người dùng nặng báo cáo dưới 200 đô la một tháng trên Claude Sonnet cho việc sử dụng Ruflo hàng ngày.