Blog Maguyva

Ngữ cảnh đi theo bạn

Mon, 07 Sep 2026 00:00:00 GMT

Trình lập chỉ mục của Cursor rất xuất sắc bên trong Cursor. Tự động hoàn thành, chỉnh sửa nội tuyến, chat, và agent trong cửa sổ đó đã dựa trên một chỉ mục dự án mà Cursor vận hành cho không gian làm việc đang mở. Nếu Cursor là bề mặt duy nhất bạn viết code, và chỉ mục đó đã tìm thấy đúng file, hãy ở lại đó. Đó là trường hợp trung thực ‘ở lại nơi bạn đang ở’, và nó xứng đáng là câu đầu tiên của trang này.

Bài viết này nói về nửa còn lại của một tuần bình thường. Cùng một repository cũng được mở trong Claude Code, được hỏi từ Codex CLI, được xem xét trên máy thứ hai, hoặc được một agent chạy trong CI truy vấn. Câu hỏi không phải là ‘trình lập chỉ mục nào tốt hơn’. Câu hỏi là liệu bản đồ mà agent tin tưởng trong một cửa sổ có phải là bản đồ mà nó tin tưởng trong cửa sổ tiếp theo hay không.

Maguyva chính là bản đồ đi theo bạn đó. Đó là một lớp ngữ cảnh codebase MCP từ xa. Agent truy vấn nó theo cùng cách nó truy vấn bất kỳ công cụ MCP nào khác. Kết quả trả về dưới dạng các đường dẫn được xếp hạng kèm số dòng. Cursor vẫn là editor. Chính ngữ cảnh mới là thứ di chuyển.

Trình lập chỉ mục của Cursor dùng để làm gì

Việc lập chỉ mục tích hợp sẵn của Cursor tồn tại để chat, agent và tìm kiếm bên trong editor có thể lấy được code liên quan thay vì chỉ dựa vào những gì vừa với cửa sổ ngữ cảnh thô của model. Đó là thiết kế đúng đắn cho một IDE. Chỉ mục này là bản địa của Cursor. Nó không phải là một máy chủ MCP và không thể truy cập được từ bất kỳ client nào khác.

Đây là cách nó hoạt động, như được mô tả trong tài liệu công khai của Cursor và chính lời tường thuật của Cursor tại thời điểm viết bài này: đường dẫn tìm kiếm chính không còn là một chỉ mục embedding trên cloud nữa. Đội ngũ Cursor đã tuyên bố trên diễn đàn cộng đồng của họ rằng việc tìm kiếm ngữ nghĩa/dựa trên embedding chuyên dụng đang dần bị loại bỏ để ủng hộ việc truy xuất dựa trên grep, vì các model hiện tại đã tự khám phá đủ tốt một cây sống. Thay vào đó là Instant Grep, một chỉ mục tìm kiếm cục bộ được xây dựng từ n-gram, danh sách đảo ngược và bộ lọc Bloom, được giữ trong một bảng tra cứu ánh xạ vào bộ nhớ, để các truy vấn được giải quyết ngay trên máy của chính nhà phát triển thay vì trên một máy chủ.

Bản thân chỉ mục sống bên trong thư mục .git/cursor/ riêng của repository, được neo vào một commit git cụ thể; các thay đổi kể từ commit đó được xếp chồng lên trên nó thay vì kích hoạt một lần quét mới, và chỉ mục chỉ được xây dựng lại khi trạng thái cục bộ đã trôi dạt xa so với những gì nó được xây dựng dựa trên. Vì nó nằm bên trong .git, nó không bao giờ bị theo dõi và không bao giờ được push — xóa thư mục, và chỉ mục sẽ biến mất. .gitignore được tôn trọng theo cấu trúc, vì chỉ nội dung được git theo dõi mới đủ điều kiện, và .cursorignore được thực thi trên đường dẫn đọc. Không còn bước embedding phía máy chủ hay cơ sở dữ liệu vector từ xa nào trên đường dẫn đó nữa. Tài liệu trước đây mô tả một thiết kế hỗ trợ bởi cloud — mã hóa các chunk, đồng bộ qua cây Merkle, tái sử dụng chỉ mục giữa các thành viên trong nhóm — và chính đội ngũ Cursor kể từ đó đã nói rằng thiết kế đó đang bị loại bỏ, vì vậy bài viết này không còn mô tả nó là hiện hành nữa.

Một điểm nổi bật bên trong editor là subagent Explore của Cursor. Nó có thể khởi chạy nhiều tìm kiếm song song trong cửa sổ ngữ cảnh riêng của nó trên một model nhanh hơn và chỉ trả về những phát hiện liên quan, để cuộc hội thoại chính không bị phình to bởi kết quả tìm kiếm. Đó là một sức mạnh thực sự bên trong editor. Hãy giữ nó.

Các không gian làm việc đa gốc được hỗ trợ: ngữ cảnh của mỗi thư mục đang mở đều khả dụng cho Agent. Một số tính năng phụ thuộc vào git, như worktree, bị vô hiệu hóa trong các thiết lập đa gốc, và Cloud Agents hoàn toàn không hỗ trợ không gian làm việc đa gốc.

Không điều nào trong số này là lý do để rời bỏ Cursor. Đó là một mô tả chính xác về một bản đồ xuất sắc ở nơi nó sống.

‘Đi theo bạn’ thực sự có nghĩa là gì

Một bản đồ đi theo bạn khi cùng những câu hỏi trả về cùng loại câu trả lời, kèm trích dẫn bạn có thể mở, từ nhiều hơn một client.

Trong Cursor: ‘Đâu là nơi parseConfig được định nghĩa, và ai gọi nó?’
Trong Claude Code, trên cùng một repo: cùng câu hỏi.
Trong Codex CLI, trên một máy xem xét chưa bao giờ mở cửa sổ Cursor: cùng câu hỏi.
Trong một CI agent nói MCP: cùng câu hỏi, đối với cùng một snapshot được lưu trữ.

Nếu mỗi bề mặt xây dựng chỉ mục riêng tư của riêng nó, bạn không có một bản đồ. Bạn có nhiều bộ nhớ đệm trôi dạt xa nhau. Chỉ mục của editor có thể cập nhật cho cây trên đĩa. Phiên CLI có thể chậm hơn một ngày. Công việc CI có thể đang nhìn vào một checkout khác. Và agent vẫn sẽ nghe có vẻ tự tin.

Trình lập chỉ mục của Cursor không được thiết kế để giải quyết điều đó. Vì nó sống bên trong editor, ngữ cảnh mà nó xây dựng là dành cho editor đó. Một người đọc cũng cần một CLI, một pipeline CI, hoặc một editor khác cần một công cụ riêng biệt cho những bề mặt đó. Đó là một thực tế về phạm vi, không phải là một khiếm khuyết. Maguyva chính là công cụ riêng biệt đó.

Một số lượng ngôn ngữ được công bố cho trình lập chỉ mục của Cursor không được nêu trong tài liệu mà bài viết này được phép sử dụng. Maguyva công bố hỗ trợ hơn 279 ngôn ngữ và công nghệ dựa trên văn bản. Giá cả của Cursor cũng không được sao chép ở đây; xem trang giá của họ. Maguyva tính phí theo không gian làm việc, không theo chỗ ngồi, với các gói đã công bố là $0, $19, $49 và $149 tùy thuộc vào phạm vi đã lập chỉ mục và kích thước không gian làm việc.

Một bản đồ được lưu trữ, mọi client MCP

Maguyva là một máy chủ MCP từ xa. Bạn kết nối GitHub, chọn các repository, và pipeline trên cloud xây dựng các symbol, các cạnh đồ thị, và một bản đồ được xếp hạng. Bạn thêm một khóa API vào cấu hình MCP của client mà bạn đã đang sử dụng. Maguyva có các hướng dẫn thiết lập cho 24 client MCP đã được ghi chép — bao gồm cả Cursor — và có thể kết nối với các client tương thích MCP khác hỗ trợ cấu hình chuẩn.

Trang thiết lập Cursor là con đường riêng cho editor này nếu đó là nơi bạn làm việc. Cùng một máy chủ trả lời cho Claude Code, VS Code, Windsurf, Codex CLI và những cái khác. Bạn không đổi editor. Bạn cung cấp cho mỗi agent cùng một bề mặt công cụ: 11 công cụ MCP hướng tới khách hàng trên khắp tìm kiếm, symbol, phân tích phụ thuộc, truy xuất file, ngữ cảnh repository, và các quy trình công cụ tiện ích tất định. Tìm kiếm ngữ nghĩa, cấu trúc, đồ thị, và văn bản được hợp nhất thành kết quả được xếp hạng.

Đó là lợi ích của tính di động. Các trích dẫn bạn đã kiểm tra trong Cursor sáng nay có cùng hình thức với các trích dẫn mà Codex CLI sẽ trả về tối nay. Đường dẫn file và số dòng. Mở chúng ra. Nếu chúng sai, bạn sẽ thấy. Nếu chúng đúng, thay đổi tiếp theo có nơi để hạ cánh. Tuyên bố được chấp thuận là ít thay đổi bị ảo giác hơn, không phải lời hứa rằng mọi thay đổi đều đúng.

Độ mới được công bố. Các snapshot có dấu thời gian, để agent biết nó đang đọc phiên bản nào của cây. Nhịp độ xây dựng lại là hàng ngày trên gói miễn phí và hàng giờ trên các gói trả phí. Giới hạn trung thực là công việc cục bộ chưa đồng bộ hóa: một thay đổi chỉ tồn tại trong một working tree vẫn chưa có trong bản đồ được lưu trữ. Giới hạn này giống nhau bất kể bạn truy vấn từ client nào, và đó chính xác là điểm mấu chốt. Sự trôi dạt giữa các client không còn là một giới hạn ẩn thứ hai nữa.

Tài liệu đưa ra vòng lặp kích hoạt áp dụng cho mọi client: lập chỉ mục một repo mà bạn đã biết, kết nối client, đặt một câu hỏi bạn có thể xác minh. Làm điều đó một lần trong Cursor. Làm lại từ CLI mà bạn thực sự sử dụng vào những ngày xem xét. Nếu cả hai câu trả lời đều trích dẫn cùng một handler, bản đồ đã thực sự đi theo bạn.

Hai bản đồ cùng tồn tại như thế nào

Sử dụng cả hai. Chúng không phải là các lựa chọn thay thế theo nghĩa của một trang so sánh.

Giữ trình lập chỉ mục của Cursor bật cho dự án trên đĩa. Để Explore, Instant Grep, và agent bên trong editor sử dụng nó. Vòng lặp đó là bản địa và nhanh.
Thêm Maguyva làm máy chủ MCP trong Cursor để cùng phiên đó cũng có thể truy vấn bản đồ không gian làm việc được lưu trữ. Cursor là một client Maguyva đã được ghi chép. Bạn không chọn một chỉ mục rồi xóa cái kia.
Thêm cùng một máy chủ Maguyva vào Claude Code, Codex CLI, hoặc bất kỳ client MCP nào khác chạm vào repo. Một dạng khóa API. Một không gian làm việc.
Nếu một CI agent tương thích MCP, hãy trỏ nó đến cùng máy chủ. Nó sẽ đọc cùng một snapshot có dấu thời gian mà máy tính xách tay đã đọc.

Chỉ mục của editor vẫn là công cụ tốt nhất cho câu hỏi ‘điều gì đang có trên đĩa trong cửa sổ này, ngay lúc này’. Bản đồ được lưu trữ là công cụ tốt nhất cho câu hỏi ‘không gian làm việc này trông như thế nào đối với mọi agent sẽ chạm vào nó hôm nay’. Những câu đó không cạnh tranh với nhau.

Hạn mức không gian làm việc được công bố trên trang giá: repo, số dòng đã lập chỉ mục, và người dùng, được tính phí theo không gian làm việc. Agent và con người chia sẻ cùng một số lượng người dùng. Bắt đầu miễn phí với một repo mà bạn đã có thể đánh giá. Chỉ tăng không gian làm việc sau khi các trích dẫn đã vượt qua thử thách tiếp xúc với cây.

Những gì trang này không khẳng định

Nó không khẳng định rằng trình lập chỉ mục của Cursor yếu, không đầy đủ, hoặc là lý do để đổi editor. Câu đầu tiên của bài viết này nói điều ngược lại.

Nó không khẳng định rằng Maguyva thay thế Instant Grep hoặc subagent Explore. Đó là các tính năng của Cursor. Chúng ở lại trong Cursor.

Nó không bịa ra một số lượng ngôn ngữ, một con số độ trễ, hoặc một khoản tiết kiệm token cho bất kỳ sản phẩm nào. Các con số chưa biết vẫn không được công bố.

Nó không giả vờ rằng công việc cục bộ chưa push có trong bản đồ được lưu trữ. Các snapshot có dấu thời gian làm cho giới hạn đó hiển thị. Chúng không loại bỏ nó.

Bài kiểm tra rất bình thường. Lập chỉ mục một repo mà bạn đã biết. Đặt một câu hỏi bạn có thể xác minh, trước tiên trong Cursor, sau đó trong một client MCP thứ hai. Ngữ cảnh đi theo bạn chính là cùng một trích dẫn ở cả hai nơi.

// same map, wherever you opened it.

Bản đồ trước, xem xét sau

Mon, 07 Sep 2026 00:00:00 GMT

Hai công việc khác nhau nằm ở hai bên của một pull request. Trước khi agent viết, nó cần một bản đồ của cây mà nó sắp thay đổi. Sau khi agent mở một PR, một thứ gì đó nên đọc thay đổi đó so với phần còn lại của hệ thống và để lại các bình luận mà con người có thể hành động theo.

Những công việc này trông giống nhau từ xa vì cả hai đều liên quan đến ‘hiểu codebase’. Chúng không phải là cùng một sản phẩm. Một cái trả lời ‘thay đổi này nên hạ cánh ở đâu?’. Cái kia trả lời ‘diff này đã phá vỡ điều gì mà một linter kiểm tra từng dòng sẽ bỏ lỡ?’. Trộn lẫn chúng tạo ra một bản nháp đầu tiên tệ hơn và một sự xem xét ồn ào hơn.

Bài viết này là một hướng dẫn quy trình làm việc chung. Maguyva là bản đồ mà agent truy vấn trước tiên. Greptile là agent xem xét bình luận trên PR sau đó. Cặp này bổ sung cho nhau theo cấu trúc: Maguyva không xem xét pull request, và Greptile không thay thế lớp ngữ cảnh mà agent đã sử dụng để viết chúng.

Tại sao sự phân chia này hữu ích

Một coding agent xuất phát từ các tiền đề huấn luyện cộng với vài file được dán vào sẽ bịa ra một đường dẫn hợp lý và chỉnh sửa nó. Đó là thất bại ‘sai file’, và đó là một vấn đề truy xuất. Maguyva là một lớp ngữ cảnh codebase MCP từ xa: truy xuất ngữ nghĩa, cấu trúc (AST), đồ thị/phụ thuộc và văn bản được hợp nhất thành kết quả được xếp hạng, cộng với tìm kiếm symbol và truy xuất file. Các câu trả lời có căn cứ trở về dưới dạng path/file.ext:line, để bạn có thể từ chối một sai sót trước khi bản vá tồn tại. Tuyên bố vẫn khiêm tốn: ít thay đổi bị ảo giác hơn. Model vẫn có thể đoán. Chỉ là bước đầu tiên không còn là một sự đoán mò nữa.

Greptile là một agent xem xét code chạy bằng AI. Theo lời họ, nó tự động xem xét mọi pull request với sự hiểu biết đầy đủ về codebase, và đặt điều đó đối lập với các linter truyền thống kiểm tra file một cách riêng lẻ thay vì toàn bộ hệ thống. Việc thiết lập bao gồm cài đặt ứng dụng GitHub hoặc GitLab và chọn repository. Không có chỉ mục cục bộ nào bạn phải vận hành. Việc lưu trữ là Greptile Cloud (họ tuyên bố tuân thủ SOC 2 Type II, với báo cáo có sẵn theo yêu cầu), với tùy chọn tự lưu trữ được cung cấp cho các doanh nghiệp.

Quy trình được đánh số của riêng họ là: kết nối và xây dựng một đồ thị phụ thuộc của mọi function, class và phụ thuộc; ở mỗi pull request, phân tích thay đổi bằng cách sử dụng đồ thị repo đầy đủ đó và công bố các phát hiện dưới dạng bình luận PR với các sửa chữa được đề xuất, trong khoảng ba phút; mỗi bình luận có thể chuyển giao vấn đề cho một coding agent mà nhóm đã sử dụng. Họ cũng tuyên bố đọc các bình luận PR của con người trước đây theo thời gian để học các tiêu chuẩn code của một nhóm và giảm các đề xuất gây ồn ào. Hệ thống học tập của họ, theo tuyên bố của họ, cần 2-3 tuần để thích ứng.

Đó là xem xét, không phải soạn thảo. Điểm nổi bật của Greptile là ngữ cảnh đồ thị repo đầy đủ trên thay đổi đã hạ cánh trong một PR, tiếp theo là một vòng lặp khép kín gửi phát hiện đến Claude Code, Codex, Conductor, Cursor, hoặc Devin. Điểm nổi bật của Maguyva là bản đồ được xếp hạng mà agent đã truy vấn trước khi thay đổi đó được viết. Sử dụng cả hai. Đừng yêu cầu một trong hai làm công việc của cái kia.

Một tích hợp sản phẩm bên thứ nhất giữa Maguyva và Greptile không được nêu ra. Bạn cũng không cần nó. Maguyva nói chuyện với agent qua MCP. Greptile nói chuyện với GitHub hoặc GitLab thông qua ứng dụng riêng của họ. Chúng gặp nhau tại pull request. Không có script keo dán, không có cron kết nối một công cụ với công cụ kia. Cặp này không cần bash vì mỗi sản phẩm đã đứng trên bề mặt thuộc về nó.

Đây không phải là gì

Đây không phải là một bài đánh sập Greptile. Đây không phải là một trang ‘đổi người xem xét của bạn’. Greptile ra mắt trên Hacker News vào ngày 5 tháng 3 năm 2024 với tư cách là một công ty Y Combinator W24, và luồng đó là cách nhiều người lần đầu biết đến sản phẩm này. Nếu đó là cách bạn tìm thấy họ, hãy tiếp tục sử dụng họ. Trang này là nửa trước còn thiếu của vòng lặp đó: đặt nền tảng cho agent trước, để PR mà Greptile thấy đã nhắm vào đúng file.

Tài liệu tiếp thị của Greptile dẫn đầu bằng các tuyên bố về tốc độ xem xét và bắt lỗi. Hãy coi chúng như những tuyên bố của riêng Greptile, không phải những con số được xác minh độc lập. Bài viết này không lặp lại chúng như sự thật.

Phạm vi bao phủ ngôn ngữ cũng là loại trung thực tương tự. Greptile định khung việc hỗ trợ là bao phủ tất cả các ngôn ngữ lập trình thay vì một danh sách được liệt kê; một con số chính xác không được nêu ra. Maguyva công bố hỗ trợ hơn 279 ngôn ngữ và công nghệ dựa trên văn bản, với một sự phân chia kỹ thuật (AST được hỗ trợ bởi parser so với chỉ văn bản) trên trang web khi câu hỏi mang tính kỹ thuật. Đây là những sản phẩm khác nhau đưa ra những tuyên bố khác nhau. Đừng trộn lẫn chúng.

Giá cả của Greptile không được nêu trong tài liệu mà bài viết này được phép sử dụng. Các gói trả phí tồn tại; xem trang giá của họ. Maguyva tính phí theo không gian làm việc, không theo chỗ ngồi. Các gói bắt đầu miễn phí. Trang giá liệt kê các cấp đã công bố nếu bạn cần các con số về không gian làm việc.

Quy trình làm việc

Ba giai đoạn được đặt tên. Thực hiện chúng theo thứ tự này. Đừng bỏ qua bất kỳ giai đoạn nào trong lần đầu tiên bạn thử cặp này.

1. Ngữ cảnh Maguyva

Lập chỉ mục một repository mà bạn đã biết. Kết nối client MCP mà bạn đã đang viết code trong đó — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, hoặc một client tương thích MCP khác. Maguyva có các hướng dẫn thiết lập cho 24 client MCP đã được ghi chép và có thể kết nối với các client khác hỗ trợ cấu hình MCP chuẩn.

Đặt một câu hỏi bạn có thể đánh giá trước khi bất kỳ ai viết một dòng nào. ‘Việc hết hạn phiên được xử lý ở đâu, và cái gì gọi nó?’ là một nước đi đầu tiên tốt hơn ‘sửa auth’. Yêu cầu trích dẫn. Mở các kết quả file.ext:line. Theo dõi symbol. Xác nhận phụ thuộc mà bạn sắp chạm vào.

Maguyva cung cấp 11 công cụ MCP hướng tới khách hàng trên khắp tìm kiếm, symbol, phân tích phụ thuộc, truy xuất file, ngữ cảnh repository, và các quy trình công cụ tiện ích tất định. Bốn chế độ truy xuất được hợp nhất thành kết quả được xếp hạng; find_symbol là một công cụ riêng biệt khi bạn đã biết tên. Tài liệu mô tả con đường ngắn nhất: bắt đầu miễn phí, lập chỉ mục một repo mà bạn đã biết, kết nối client, sau đó đặt một câu hỏi bạn có thể xác minh.

Các snapshot có dấu thời gian, để agent có thể biết phiên bản nào của cây nó đang đọc. Giới hạn trung thực là công việc cục bộ chưa đồng bộ hóa. Nếu thay đổi chỉ tồn tại trong một working tree và chưa được push, bản đồ được lưu trữ vẫn chưa chứa nó. Các file hướng dẫn (CLAUDE.md, AGENTS.md) vẫn có chỗ đứng ở đây, dành cho các quy ước và những gì không nên chạm vào. Chúng không phải là một bản đồ sống. Sử dụng chúng cho hành vi. Sử dụng Maguyva cho các sự kiện.

Đừng để agent mở một PR trước khi các trích dẫn vượt qua sự tiếp xúc với repo. Cánh cổng đó là toàn bộ mục đích của giai đoạn này.

2. PR của agent

Cùng một agent giờ viết thay đổi trong client mà bạn đã trả tiền. Maguyva không phải là editor cũng không phải là người xem xét. Agent vẫn tạo ra diff. Bạn vẫn mở pull request trên GitHub hoặc GitLab như bạn đã làm.

Điều nên khác biệt là file đầu tiên. PR nên nêu tên handler thực sự triển khai hành vi, người gọi sẽ bị hỏng, và test sẽ thất bại nếu thay đổi sai. Nếu giai đoạn 1 bị bỏ qua, giai đoạn 3 sẽ dành bình luận của nó cho một thay đổi hạ cánh sai package. Greptile vẫn có thể tìm thấy các vấn đề hệ thống. Nó không nên đồng thời phải phục hồi từ một đường dẫn bị ảo giác.

Giữ PR trong phạm vi hẹp. Một file đầu tiên có căn cứ không phải là giấy phép để viết lại toàn bộ module. Cặp bổ sung này hoạt động khi agent làm một công việc với một bản đồ, sau đó yêu cầu người xem xét làm một công việc khác trên một diff có ranh giới.

3. Xem xét của Greptile

Greptile đã kết nối với repository thông qua ứng dụng GitHub hoặc GitLab. Trên pull request mới, nó phân tích thay đổi bằng cách sử dụng đồ thị repo đầy đủ mà nó đã xây dựng, và công bố các phát hiện dưới dạng bình luận với các sửa chữa được đề xuất. Tài liệu riêng của họ đặt lượt này vào khoảng ba phút.

Đọc các bình luận như bạn sẽ đọc một đồng nghiệp cẩn thận: mở vị trí được trích dẫn, quyết định xem phát hiện có thật hay không, sau đó hành động. Ở nơi Greptile cung cấp ‘Fix with your Agent’, nó gửi vấn đề — đường dẫn file, số dòng, code được đề xuất — đến Claude Code, Codex, Conductor, Cursor, hoặc Devin. ‘Fix All’ gửi tất cả các vấn đề trong lần xem xét cùng một lúc. Họ cũng cung cấp một Greptile MCP và một plugin Claude Code cho việc chuyển giao đó. Maguyva không có trong danh sách mục tiêu được đặt tên đó; sự vắng mặt đó không phải là vấn đề. Maguyva đã hoàn thành công việc của nó ở giai đoạn 1. Coding agent đã viết PR là người nên nhận payload sửa chữa.

Hãy mong đợi tiếng ồn trong 2-3 tuần đầu tiên trong khi hệ thống học tập của Greptile thích ứng với các bình luận mà nhóm của bạn thực sự để lại. Đó là lịch trình họ đã tuyên bố, không phải một khiếm khuyết của cặp đôi. Sự xem xét của con người vẫn ở trong vòng lặp. Greptile là lượt đầu tiên được tự động hóa, không phải nút merge.

Nếu một bình luận Greptile trỏ đến một file mà agent chưa bao giờ truy vấn ở giai đoạn 1, đó là một tín hiệu hữu ích. Hoặc bản đồ đã bỏ lỡ một người gọi, hoặc agent đã bỏ qua một trích dẫn. Sửa bản nháp theo bình luận đó. Đừng vô hiệu hóa người xem xét.

Cách giữ sự bổ sung này trung thực

Maguyva luôn đi trước. Việc xem xét một PR sai file vẫn là việc xem xét file sai.
Greptile luôn theo sau. Một bản nháp được trích dẫn tốt vẫn cần một lần đọc diff ở cấp độ toàn hệ thống.
Đừng yêu cầu Maguyva công bố bình luận PR. Nó không làm điều đó.
Đừng yêu cầu Greptile trở thành lớp truy xuất đầu tiên của agent trong khi nó vẫn đang chọn một đường dẫn. Đó không phải là công việc mà ứng dụng GitHub hoặc GitLab của họ được kết nối để làm.
Đừng bịa ra một pipeline bash ‘đồng bộ hóa’ chúng. PR là giao diện.
Xác minh cả hai phía một cách độc lập. Lập chỉ mục một repo mà bạn đã biết. Đặt một câu hỏi bạn có thể xác minh. Sau đó mở một PR nhỏ và đọc những gì Greptile thực sự bình luận.

Vòng lặp trở nên bình thường ngay khi nó được đặt tên. Bản đồ trước. PR của agent. Xem xét sau. Mỗi sản phẩm ở lại phía pull request mà nó giỏi.

// map first. review second. in that order.

Cung cấp cho một AI agent ngữ cảnh của một repo lớn mà không cần trình lập chỉ mục cục bộ

Fri, 14 Aug 2026 00:00:00 GMT

Một repository lớn không vừa với một cửa sổ ngữ cảnh, và nếu bạn từng hướng một trình lập chỉ mục laptop vào một monorepo thực sự, bạn biết nó cũng không vừa một cách thoải mái ở đó — RAM tăng vọt, lần lập chỉ mục đầu tiên mất một giờ, và agent của bạn vẫn bắt đầu phiên tiếp theo bằng cách đoán file nào quan trọng.

Câu trả lời thông thường là chạy một trình lập chỉ mục bên cạnh editor, và với một repo vừa vặn thoải mái trên một máy, đó là một câu trả lời tốt. Nếu monorepo của bạn đã được lập chỉ mục nhanh trong Cursor và đó là nơi duy nhất bạn cần bản đồ, bài viết này không có gì để bổ sung — hãy bỏ qua nó.

Bài viết này nói về trường hợp khác — khi một agent cần một bản đồ có thể truy vấn của một repo lớn, và bạn không muốn chạy trình lập chỉ mục cục bộ để có được nó.

Khi nào trình lập chỉ mục cục bộ là công cụ sai

Một chỉ mục cục bộ giả định rằng code sống trên máy truy vấn nó, và ở quy mô monorepo thực sự, giả định đó bị căng thẳng ngay cả trong một editor duy nhất. Repo đơn giản là lớn hơn những gì bạn muốn giữ ‘ấm’ trên một laptop: bạn làm việc trong một package trong khi phạm vi ảnh hưởng nằm cách ba thư mục, và lần lập chỉ mục lạnh đầu tiên của một cây hai triệu dòng không phải là điều bạn muốn trải qua hai lần — dù trên máy của chính bạn, hay trên một CI runner chưa bao giờ clone cây đó trước đây. Hoặc một đồng nghiệp trong nhóm nên có thể truy vấn cùng bản đồ với bạn, mà không phải đợi máy của chính họ vật lộn qua cùng một chỉ mục.

Không điều nào trong số này là lý do để vứt bỏ một trình lập chỉ mục editor tốt. Đó là lý do để cũng có một bản đồ được lưu trữ mà bất kỳ agent nào của bạn cũng có thể truy vấn qua MCP.

Và vấn đề quy mô còn sâu hơn ‘quá nhiều file để dán vào’. Trên một cây lớn, câu hỏi thú vị hầu như không bao giờ là ‘cho tôi xem file này’ — mà là file nào, symbol nào, ai gọi nó, test nào. Một agent bắt đầu bằng cách liệt kê src/ và đọc ba kết quả đầu tiên sẽ vui vẻ bỏ lỡ handler trong apps/api và client được tạo ra trong packages/sdk. Điều bạn cần là truy xuất được xây dựng từ toàn bộ cây, sau đó được xếp hạng, sau đó được trích dẫn.

‘Ngữ cảnh của một repo lớn’ thực sự có nghĩa là gì

Đổ các file vào prompt không phải là ngữ cảnh — đó là một bản sao nhỏ hơn, tệ hơn của cây. Điều mà agent của bạn thực sự cần là đặt câu hỏi và nhận lại các câu trả lời được trích dẫn: symbol này được định nghĩa ở đâu và ai gọi nó, cái gì phụ thuộc vào module tôi sắp thay đổi, file test nào bao phủ hành vi này, và cây trông như thế nào ngay bây giờ, không phải quý trước.

Những câu trả lời đó phải đến từ một chỉ mục được xây dựng từ repo của bạn thay vì từ ký ức của model về repo của người khác, và chỉ mục đó phải sống ở một nơi nào đó ngoài cửa sổ ngữ cảnh của agent. Đối với vấn đề này, nó cũng nên sống ở một nơi nào đó ngoài laptop của bạn.

Một điều nữa mà các file hướng dẫn không thể làm cho bạn: CLAUDE.md và AGENTS.md là nơi thích hợp cho các quy ước và hành vi, nhưng chúng không phải là một bản đồ sống, được xếp hạng, có thể truy vấn của một cây hai triệu dòng. Sử dụng quy tắc cho hành vi; sử dụng trí thông minh của repo cho các sự kiện.

Chúng tôi xây dựng bản đồ trên cloud, bạn truy vấn nó từ bất kỳ client nào

Maguyva là một lớp ngữ cảnh codebase MCP từ xa. Bạn kết nối GitHub, chọn các repository của bạn, và có thể rời đi trong khi các pipeline cloud phân tích cây, xây dựng symbol và các cạnh đồ thị, và duy trì một bản đồ được xếp hạng — không bao giờ cần một trình lập chỉ mục cục bộ.

Khi bạn push code, các file đã thay đổi được phân tích theo từng phần, và các lớp đồ thị và xếp hạng được xây dựng lại theo lịch trình: hàng ngày trên gói miễn phí, hàng giờ trên các gói trả phí. Mỗi snapshot có dấu thời gian, để agent của bạn có thể biết phiên bản nào của cây nó đang đọc. Giới hạn trung thực ở đây là công việc cục bộ chưa đồng bộ hóa — một thay đổi chỉ tồn tại trong working tree của bạn, chưa bao giờ được push, vẫn chưa có trong bản đồ được lưu trữ.

Sau đó bạn kết nối bất kỳ client nào bạn đã đang sử dụng bằng cách thêm một khóa API vào cấu hình MCP của nó. Có các hướng dẫn thiết lập cho 24 client MCP đã được ghi chép, và bất kỳ client tương thích MCP nào khác hỗ trợ cấu hình chuẩn cũng có thể kết nối. Nếu Cursor là nơi bạn ở, trang Cursor đi theo con đường đó; cùng một máy chủ trả lời cho Claude Code, VS Code, Windsurf, Codex CLI và những cái khác.

Bạn không đổi editor. Bạn cung cấp cho agent của mình một bề mặt công cụ — 11 công cụ MCP trên khắp tìm kiếm, symbol, phân tích phụ thuộc, truy xuất file và ngữ cảnh repository — với phạm vi bao phủ hơn 279 ngôn ngữ và công nghệ dựa trên văn bản, điều này quan trọng hơn bạn nghĩ trên một monorepo đã ngừng là một ngôn ngữ duy nhất từ nhiều năm trước.

Các câu trả lời trở về có căn cứ, dưới dạng đường dẫn file kèm số dòng. Tìm kiếm ngữ nghĩa, cấu trúc, đồ thị và văn bản được hợp nhất thành kết quả được xếp hạng, để một câu hỏi như ‘cái gì phụ thuộc vào parseConfig’ không cho bạn một bãi đổ grep hay một mảnh ngữ nghĩa đơn lẻ, mà là nhóm nhỏ những địa điểm thực sự quan trọng.

Một hướng dẫn cụ thể

Đừng bắt đầu bằng cách lập chỉ mục toàn bộ công ty. Đây là con đường hiệu quả:

Chọn một repository mà bạn đã biết rõ — một package bạn có thể đánh giá bằng tay có giá trị hơn cây lớn nhất bạn có.
Bắt đầu miễn phí: 3 repo, 50 nghìn dòng đã lập chỉ mục, tất cả 11 công cụ, không có hạn mức truy vấn hàng tháng. Nếu repo đại diện của bạn lớn hơn thế, trang giá liệt kê các cấp không gian làm việc ($0, $19, $49, $149) theo phạm vi đã lập chỉ mục — không phải theo số lượng chỗ ngồi.
Kết nối GitHub và đợi lần lập chỉ mục đầu tiên hoàn tất. Bạn không biên dịch bất cứ thứ gì cục bộ.
Kết nối client MCP — vài dòng cấu hình. Maguyva là một máy chủ MCP từ xa, vì vậy không có plugin, không có tiện ích mở rộng, và không có editor thứ hai để áp dụng.
Đặt một câu hỏi bạn có thể xác minh. ‘Cái gì phụ thuộc vào parseConfig?’ hoặc ‘Việc hết hạn phiên đăng nhập được xử lý ở đâu?’ Sau đó mở kết quả file.ext:line được trích dẫn và kiểm tra chúng so với cây trước mặt bạn.
Chỉ sau khi các trích dẫn đã vượt qua thử thách tiếp xúc đó, bạn mới để agent chỉnh sửa.

Nếu repo đầu tiên phù hợp tốt và cây của bạn lớn, hãy tăng không gian làm việc để khớp với số dòng đã lập chỉ mục và nhịp độ xây dựng lại của bạn. Con người và agent chia sẻ cùng một số lượng người dùng — Maguyva tính phí theo không gian làm việc, không theo chỗ ngồi — vì vậy việc thêm một agent thứ ba vào vòng lặp không tốn gì của bạn.

Bài kiểm tra kích hoạt giống hệt với những gì tài liệu khuyến nghị cho bất kỳ lần chạy đầu tiên nào: lập chỉ mục một repo mà bạn đã biết, đặt một câu hỏi bạn có thể xác minh. Một repo lớn không thay đổi bài kiểm tra; nó chỉ làm cho một file đầu tiên sai trở nên tốn kém hơn.

Những gì cần theo dõi sau khi kết nối

Hãy để mắt đến ba điều. Độ mới: các gói trả phí xây dựng lại hàng giờ, các gói miễn phí hàng ngày, và công việc cục bộ chưa push sẽ không có trong bản đồ — đó là sự đánh đổi bạn chấp nhận. Phạm vi: lập chỉ mục một tập hợp repo đại diện, không phải mọi fork đã lưu trữ; tầng miễn phí được cố tình định cỡ để tìm hiểu xem các câu trả lời có đáng giữ lại hay không. Và xác minh: một bản đồ repo lớn không thể trích dẫn đường dẫn và số dòng chỉ là một cỗ máy đoán chậm hơn, vì vậy hãy để agent của bạn cho thấy vị trí trước khi nó giao bản vá.

Sau đó chạy cùng bài kiểm tra mà bạn sẽ chạy trên một repo nhỏ. Lập chỉ mục một repo mà bạn đã biết. Đặt một câu hỏi bạn có thể xác minh. Nếu bản đồ là thật, agent của bạn sẽ ngừng bắt đầu từ một cây lạnh.

// no laptop got hot building this map.

Tại sao coding agent AI của bạn bị ảo giác đường dẫn file

Fri, 14 Aug 2026 00:00:00 GMT

Dấu hiệu không phải là một phần thân function sai. Đó là một thay đổi tự tin vào một file không tồn tại, hoặc vào một file tồn tại nhưng không phải là file triển khai hành vi.

Bạn đã yêu cầu sửa việc hết hạn phiên. Agent đã mở src/auth/session.ts. Đường dẫn đó hợp lý. Nó cũng sai. Handler thực sự sống trong apps/api/src/middleware/expiry.ts, được đổi tên hai lần tái cấu trúc trước. Agent không nói dối bạn. Nó đã hoàn thành một chuỗi có hình dạng đường dẫn dựa trên các tiền đề huấn luyện cộng với bất cứ thứ gì đã có sẵn trong cửa sổ ngữ cảnh.

Đây là mô hình thất bại phổ biến trên một repository thực sự. Model biết viết code. Sai lầm là ở việc chọn sai nơi để viết nó.

Tại sao agent bịa ra đường dẫn

Một coding agent là một model dự đoán token tiếp theo có công cụ. Khi bạn nói ‘sửa việc hết hạn phiên’, nó phải đặt tên một file trước khi có thể đọc hoặc vá bất cứ thứ gì. Nếu nó chưa có một bản đồ có căn cứ, nó xây dựng một đường dẫn từ:

Các quy ước đặt tên mà nó đã thấy trong các repository khác. src/auth/session.ts là một hình dạng phổ biến.
Các file đã có trong cuộc hội thoại, có thể là những file bạn đã dán tuần trước, không phải những file quan trọng bây giờ.
Các danh sách thư mục mà nó tình cờ chạy, không đầy đủ trên một cây lớn.
Các file hướng dẫn. CLAUDE.md và AGENTS.md cho agent biết cách hành xử. Chúng không phải là một chỉ mục sống của các symbol, người gọi, hoặc các đường dẫn hiện tại.

Không nguồn nào trong số này là một bản đồ của repo này, hôm nay. Model lấp đầy khoảng trống theo cùng cách nó lấp đầy bất kỳ khoảng trống nào: bằng một sự tiếp nối có xác suất cao. Sự tiếp nối đó thường trông giống như một đường dẫn thật. Đôi khi file tồn tại và nằm cạnh file đúng. Đôi khi nó tồn tại trên một branch đã được merge tháng trước. Đôi khi nó chưa bao giờ tồn tại.

Grep không cứu bạn ở đây nếu agent không bao giờ tìm kiếm đúng chuỗi. Agent đã đoán một đường dẫn, sau đó đọc những gì đường dẫn đó trả về, sau đó chỉnh sửa nó. Bước sai đầu tiên là đường dẫn, không phải bản vá.

Đọc file cũng không giống với việc tìm đúng file. Claude Code, Cursor, Codex, và các công cụ tương tự có thể mở bất cứ thứ gì bạn chỉ chúng vào. Câu hỏi là liệu chúng có tìm thấy một cách đáng tin cậy các file đúng, các symbol quan trọng, các phụ thuộc, các test, và phạm vi ảnh hưởng trước khi chỉnh sửa hay không. Việc truy cập file mà không có bản đồ vẫn bắt đầu bằng một sự đoán mò.

Chỉnh sửa sai file là một vấn đề truy xuất

Hãy coi đường dẫn bịa ra như một sai sót truy xuất, không phải là một khiếm khuyết về tính cách.

Nếu agent phải trả về path/file.ext:line trước khi được phép chỉnh sửa, hai điều sẽ xảy ra. Thứ nhất, bạn có thể mở trích dẫn và từ chối công việc đó trong mười giây. Thứ hai, agent sẽ phải truy vấn thứ gì đó thực sự biết cây.

Đó là công việc của một lớp ngữ cảnh codebase. Chỉ tìm kiếm ngữ nghĩa thôi là không đủ. Một đoạn ‘nghe giống việc hết hạn phiên’ vẫn có thể hạ cánh trong một package đã lỗi thời. Bạn cũng cần văn bản chính xác khi bạn biết chuỗi, tìm kiếm symbol khi bạn biết tên, tìm kiếm cấu trúc khi bạn biết hình dạng, và một đồ thị phụ thuộc khi bạn cần người gọi và phạm vi ảnh hưởng.

Maguyva là lớp đó cho các coding agent tương thích MCP. Đó không phải là một editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, và các client MCP khác vẫn ở nguyên vị trí của chúng. Agent truy vấn một bản đồ được xếp hạng trước khi chạm vào một dòng.

Tuyên bố này cố ý khiêm tốn: ít thay đổi bị ảo giác hơn. Maguyva không lấy đi khả năng đoán của model. Nó thay đổi bước đầu tiên mặc định từ ‘bịa ra một đường dẫn hợp lý’ thành ‘yêu cầu các vị trí được xếp hạng, được trích dẫn’.

Một câu trả lời có căn cứ trông như thế nào

Một câu trả lời hữu ích cho câu hỏi ‘việc hết hạn phiên được xử lý ở đâu’ không phải là một đoạn văn. Đó là một danh sách ngắn các vị trí:

apps/api/src/middleware/expiry.ts:48 - handler
apps/web/src/lib/auth-client.ts:112 - người gọi
apps/api/tests/expiry.test.ts:20 - test sẽ thất bại nếu thay đổi sai

Bạn có thể mở những dòng này. Nếu chúng sai, bạn dừng lại. Nếu chúng đúng, agent có thể chỉnh sửa. Việc xác minh mới là điều quan trọng, không phải một khẩu hiệu.

Maguyva cung cấp 11 công cụ MCP hướng tới khách hàng trên khắp tìm kiếm, symbol, phân tích phụ thuộc, truy xuất file, ngữ cảnh repository, và các quy trình công cụ tiện ích tất định. Bốn chế độ truy xuất (ngữ nghĩa, cấu trúc, đồ thị/phụ thuộc, và văn bản) được hợp nhất thành kết quả được xếp hạng; tìm kiếm symbol là một công cụ MCP riêng biệt (find_symbol). Các câu trả lời có căn cứ trở về kèm đường dẫn file và số dòng, để bạn có thể đánh giá chúng so với cây trước mặt bạn.

Tài liệu mô tả con đường ngắn nhất: bắt đầu miễn phí, lập chỉ mục một repo mà bạn đã biết, kết nối client, sau đó đặt một câu hỏi bạn có thể xác minh.

Một vòng lặp thay đổi lần chỉnh sửa đầu tiên

Bạn không cần một tôn giáo quy trình làm việc mới. Bạn cần thêm một bước trước lần viết đầu tiên.

Đặt một câu hỏi bạn đã có thể đánh giá. ‘Code nào xử lý đăng nhập và hết hạn phiên?’ tốt hơn ‘sửa auth’.
Yêu cầu trích dẫn. Đường dẫn file và số dòng, không phải một bản tóm tắt của ‘module auth’.
Mở các file được trích dẫn. Theo dõi symbol. Xác nhận phụ thuộc mà bạn sắp chạm vào.
Chỉ khi đó mới để agent vá lỗi.

Nếu bước 2 không trả về bất cứ điều gì hữu ích, agent không có quyền tự ứng biến một đường dẫn. Nó tìm kiếm lại, hoặc bạn chỉ cho nó. Chính cánh cổng duy nhất đó tạo ra ít thay đổi bị ảo giác hơn. Model vẫn là model đó. Bản đồ là thứ đã thay đổi.

Các file hướng dẫn vẫn quan trọng. Giữ chúng. Sử dụng chúng cho các quy ước, quy tắc xem xét, và những gì không nên chạm vào. Đừng yêu cầu chúng trở thành chỉ mục. Một CLAUDE.md liệt kê ba thư mục quan trọng sẽ lỗi thời một tuần sau khi tách package. Một bản đồ có thể truy vấn được cập nhật khi repo được cập nhật.

Một thất bại liên quan là file gần đúng: agent mở auth.ts trong khi hành vi sống trong auth-client.ts, hoặc vá một file được tạo ra thay vì nguồn, hoặc chỉnh sửa bản sao trong packages/legacy vì tên khớp. Trích dẫn không làm cho những lỗi này trở nên bất khả thi. Chúng làm cho những lỗi này trở nên rõ ràng trước khi diff hạ cánh.

Những gì một bản đồ sẽ không sửa cho bạn

Hãy tỉnh táo về những gì bạn đang nhận được. Một bản đồ có căn cứ sẽ không làm cho mọi thay đổi đều đúng — agent của bạn vẫn có thể viết một bản vá tồi ngay trong file hoàn toàn đúng. Nếu codebase của bạn dựa vào dispatch động, reflection, hoặc monkey-patching, một số tìm kiếm symbol sẽ trả về kết quả mỏng hơn bạn mong muốn, vì đó là điều mà tính gián tiếp thời gian chạy làm với bất kỳ chỉ mục tĩnh nào. Và nếu bạn hy vọng vào một tỷ lệ phần trăm — ‘đường dẫn bị ảo giác giảm X%’ — bạn sẽ không tìm thấy nó ở đây, vì không ai có thể đo lường trung thực con số đó cho repo của bạn ngoài chính bạn.

Những gì bạn có thể mong đợi hẹp hơn và hữu ích hơn: agent ngừng bắt đầu các thay đổi của nó bằng một đường dẫn được đoán. Bước đầu tiên đó trở nên có căn cứ trong một bản đồ thực sự, và đó là nơi ít thay đổi bị ảo giác hơn đến từ. Mọi thứ sau trích dẫn — đọc diff, đánh giá bản vá — vẫn là công việc của bạn, giống như nó luôn từng như vậy.

Bài kiểm tra này gần như không tốn kém gì của bạn: lập chỉ mục một repo mà bạn đã biết và đặt một câu hỏi bạn có thể xác minh. Bắt đầu với một đường dẫn mà bạn đã từng bị ‘bỏng’. Nếu các trích dẫn sai, bạn sẽ thấy ngay lập tức. Nếu chúng đúng, thay đổi tiếp theo của agent bạn có một nơi tốt hơn để hạ cánh.

// it doesn't know the file. it knows how to find it.

Vì sao chúng tôi nâng cấp tìm kiếm mã nguồn lên voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Các con số benchmark trong bài này phản ánh bảng xếp hạng RTEB tại thời điểm xuất bản (tháng 6/2026). Bảng xếp hạng luôn thay đổi; hãy xem các thứ hạng này như một lát cắt thời điểm, không phải một sự thật vĩnh viễn.

Tìm kiếm ngữ nghĩa chỉ tốt bằng đúng lớp embedding nằm bên dưới nó.

Khi một agent hỏi Maguyva “chúng ta xử lý retry ở đâu,” nó không grep tìm từ “retry.” Nó đang hỏi về ý nghĩa — vòng lặp backoff, circuit breaker, thứ bọc quanh một lệnh gọi chập chờn. Câu hỏi đó được trả lời bởi một mô hình vector biến mã nguồn thành một điểm trong không gian rồi tìm các điểm lân cận. Chọn một mô hình tốt hơn và mọi truy vấn ngữ nghĩa trong sản phẩm sẽ âm thầm trở nên sắc bén hơn.

Vì vậy chúng tôi đã đổi mô hình của mình. Kể từ tháng 6/2026, embedding mã nguồn của Maguyva chạy trên voyage-4-large, thay thế voyage-code-3.

Benchmark

Chúng tôi không đưa ra quyết định này dựa trên cảm tính. Retrieval Embedding Benchmark (RTEB) công khai xếp hạng các mô hình embedding trên các tác vụ truy xuất thực tế, và trên bảng xếp hạng Code của nó, voyage-4-large đứng ở vị trí #1 tổng thể (90,86) — vượt qua gemini-embedding-2-preview (90,26) và, đáng chú ý, vượt qua cả mô hình chúng tôi đang dùng, voyage-code-3 (89,73, #3).

Đó là một khoảng cách tuyệt đối nhỏ. Nhưng đó là khoảng cách đúng hướng, trên một benchmark công khai, đúng vào tác vụ chúng tôi quan tâm: truy xuất mã nguồn theo ý nghĩa.

Sự đánh đổi chúng tôi chấp nhận: Lượng tử hóa nhị phân

Đây là phần mà hầu hết các bài viết kiểu “chúng tôi đã nâng cấp mô hình” thường bỏ qua.

Maguyva không lưu trữ vector độ chính xác đầy đủ. Chúng tôi lưu embedding đã lượng tử hóa nhị phân: mỗi vector 2048 chiều được nén thành một chữ ký 2048-bit — 256 byte cho mỗi vector. Những chữ ký đó được tìm kiếm bằng khoảng cách Hamming, được lập chỉ mục và phân vùng theo từng tenant.

Đó là một sự đánh đổi có chủ đích. Lượng tử hóa nhị phân từ bỏ một phần độ chính xác truy xuất để đổi lấy dung lượng lưu trữ nhỏ hơn đáng kể và phép tính khoảng cách nhanh, rẻ, không cần vận hành một cơ sở dữ liệu vector riêng biệt. Với một sản phẩm lập chỉ mục toàn bộ repo cho từng workspace, bài toán kinh tế đó quan trọng hơn việc vắt kiệt phần lẻ cuối cùng của một điểm benchmark.

voyage-4-large phù hợp với thiết kế này mà không buộc phải di trú tầng lưu trữ: nó cho ra đầu ra 2048 chiều, giống như voyage-code-3, nên các cột bit(2048) và đường tìm kiếm Hamming của chúng tôi không phải thay đổi. Mô hình tốt hơn; schema vẫn giữ nguyên.

Mã nguồn chỉ là khởi đầu

Maguyva là một công cụ trí tuệ mã nguồn. Nhưng chúng tôi cũng là khách hàng số 0 của chính mình, và chúng tôi hướng nó vào một thứ khác: các file markdown sống cùng mã nguồn trong repo của chúng tôi. Bản ghi quyết định kiến trúc, runbook, hợp đồng, tài liệu tài chính và chính sách — tất cả đều được quản lý phiên bản trong Git, tất cả đều nằm sau cùng một máy chủ MCP, một chỉ mục ngữ nghĩa trên tài liệu, không chỉ trên mã nguồn.

Đó chính xác là lý do vì sao độ rộng của voyage-4-large quan trọng. Trên cùng họ bảng xếp hạng RTEB đó, nó là #1 về tài chính, #1 về y tế, và #1 về truy xuất văn bản tổng thể — vượt qua Gemini Embedding của Google, Embed v4 của Cohere, và text-embedding-3-large của OpenAI. (Voyage là đồng sáng lập của RTEB, nên chúng tôi xem đây là một tín hiệu công khai mạnh mẽ hơn là một trọng tài hoàn toàn trung lập — nhưng nó vẫn được đối chiếu trực tiếp với mọi mô hình thương mại lớn, trên các tập dữ liệu giữ riêng.) Cùng một chỉ mục tìm ra đúng hàm cho một agent cũng tìm ra đúng điều khoản trong một hợp đồng hoặc đúng dòng trong một chính sách — và trên những lĩnh vực đó, voyage-4-large không phải là một sự thỏa hiệp, nó là kẻ dẫn đầu.

Vì sao chúng tôi trả tiền cho embedding cao cấp

Có một cách rẻ hơn để làm tìm kiếm, và phần lớn trong đó là miễn phí. Tìm kiếm từ vựng — BM25 và họ hàng của nó — khớp từ khóa, chạy cục bộ, và không tốn chi phí gì. Các mô hình embedding mã nguồn mở như BGE, Nomic, và embeddinggemma cho khả năng truy xuất ngữ nghĩa thực sự khá tốt, và bạn có thể tự host chúng với giá của một GPU. Maguyva cũng dùng phía miễn phí: mỗi truy vấn đều hợp nhất tìm kiếm văn bản, AST, đồ thị, và ngữ nghĩa. Thứ chúng tôi không tiết kiệm là tầng ngữ nghĩa.

Chúng tôi trả tiền theo token cho embedding cao cấp — voyage-4-large — thay vì tự host một mô hình miễn phí, vì hai lý do. Thứ nhất, tìm kiếm từ khóa đơn thuần không thể trả lời “chúng ta xử lý retry ở đâu” khi mã nguồn viết backoff và circuit breaker mà chẳng bao giờ dùng từ “retry” — ý nghĩa chính là toàn bộ mục đích của embedding, và trên các lĩnh vực chúng tôi phục vụ, các mô hình mở tụt lại phía sau các mô hình cao cấp: kém vài điểm trên văn bản tổng quát, và kém xa hơn ở các lĩnh vực ngách như mã nguồn, hợp đồng, và tài chính. Thứ hai, theo kinh nghiệm của chúng tôi, chất lượng truy xuất định hình câu trả lời cuối cùng nhiều hơn là mô hình ở đầu bên kia — một agent mạnh được đưa sai ngữ cảnh vẫn trả lời sai, và nó không bao giờ thấy được tài liệu mà nó chưa từng được đưa cho.

Vì vậy embedding cao cấp là một hóa đơn tính theo token, tăng theo mỗi repo và tài liệu chúng tôi lập chỉ mục — và chúng tôi trả nó một cách có chủ đích. Đối với kết quả mà người dùng của chúng tôi nhận được, đúng hàm hoặc đúng điều khoản, chúng tôi nghĩ sự đánh đổi đó là xứng đáng.

Phần thành thật

Tài liệu chính thức của Voyage vẫn gắn nhãn voyage-code-3 là mô hình tối ưu cho mã nguồn. Vậy tại sao lại chuyển đổi?

Vì chúng tôi đọc benchmark công khai, chứ không chỉ bảng mô hình của nhà cung cấp, và benchmark đặt voyage-4-large lên vị trí đầu bảng cho truy xuất mã nguồn. Đây là một quyết định hướng đến tương lai: chọn mô hình mới hơn, nhìn chung mạnh hơn, và xác thực nó dựa trên một bảng xếp hạng công khai cho các tác vụ thực sự quan trọng. Chúng tôi yên tâm với lựa chọn này vì bằng chứng khá rộng — voyage-4-large không chỉ thắng ở mã nguồn, nó còn dẫn đầu ở tài chính, y tế, và truy xuất tổng thể.

Nền tảng thầm lặng

Mọi công cụ chúng tôi cung cấp — tìm kiếm ngữ nghĩa, thu thập ngữ cảnh tác vụ, hỏi đáp có căn cứ — cuối cùng đều quy về khâu truy xuất. Khi bộ truy xuất được cải thiện, agent ở đầu bên kia nhận được bằng chứng tốt hơn, ít đưa ra quyết định sai hơn, và neo câu trả lời của mình vào đúng mã nguồn — hoặc đúng điều khoản, hoặc đúng chính sách. Một mô hình embedding sắc bén hơn không phải là một tính năng phô trương. Nó là nền tảng bên dưới mọi thứ khác, và chúng tôi vừa nâng nó lên. Bạn sẽ không nhận ra điều đó. Đó chính là mục đích.

Tự cải thiện hỗ trợ ngôn ngữ theo vòng lặp: Mài giũa trí tuệ mã nguồn trên khoảng 280 ngôn ngữ

Tue, 26 May 2026 00:00:00 GMT

Các con số trong bài này phản ánh hệ thống tại thời điểm xuất bản (tháng 5/2026). Xem trang team của chúng tôi để biết số liệu hiện tại.

Maguyva trích xuất symbol, tham chiếu, và một đồ thị phụ thuộc từ mã nguồn trong khoảng 280 ngôn ngữ. Mỗi ngôn ngữ là một handler tree-sitter tùy chỉnh — truy vấn, heuristic, trường hợp biên — và mỗi handler đều có thể sai một cách tinh vi theo cách riêng của nó. Một lệnh gọi method bị phát ra như một lượt đọc. Một hàm bị gán cho sai phạm vi bao quanh. Một quan hệ đơn giản là không tồn tại.

Bạn không thể tự tay rà soát hết điều đó. Không đội nào có thể đọc kết quả trích xuất trên 280 ngữ pháp và phát hiện những cạnh (edge) sai. Vì vậy câu hỏi thú vị không phải là “việc trích xuất của chúng ta có đúng không” — mà là “làm sao bạn phát hiện ra nó sai, ở quy mô này, mà không cần con người trong mọi vòng lặp.” Câu trả lời của chúng tôi là tự cải thiện hỗ trợ ngôn ngữ theo vòng lặp: một vòng lặp chất lượng được điều khiển bởi các language agent, một LLM đóng vai giám khảo, và một quy tắc chúng tôi liên tục học lại: xanh (green) không đồng nghĩa với đúng.

Xanh không có nghĩa là đúng

Mỗi ngôn ngữ có một bộ fixture, và một bước kiểm tra trước khi phát hành chấm điểm nó trên năm chiều — độ chính xác, tính toàn vẹn cấu trúc, độ đầy đủ, chất lượng, và hiệu năng. Một ngôn ngữ chỉ đạt XANH (GREEN) khi, trên các fixture của nó, precision ≥ 0,95, recall ≥ 0,99, và F1 ≥ 0,97, với ít nhất 20 edge kỳ vọng để có độ tin cậy thống kê. Dưới mức đó là VÀNG (YELLOW) hoặc ĐỎ (RED), và nó không được lên sóng.

Bước kiểm tra đó là cần thiết nhưng chưa đủ. Fixture được xác thực dựa trên các fixture do chính chúng tôi viết. Chúng mã hóa những trường hợp chúng tôi đã nghĩ tới. Một handler có thể hoàn hảo trên các fixture của nó nhưng vẫn làm hỏng một mẫu chỉ xuất hiện trong mã thực tế — một cách dùng macro đặc thù, một method có ràng buộc kiểu generic, một tính năng ngôn ngữ mà chưa ai viết fixture cho nó. XANH nghĩa là các fixture đều đạt. Nó không có nghĩa là một repo thực tế được trích xuất sạch sẽ. Vì vậy vòng lặp phải bỏ lại các fixture và kiểm tra mã nguồn trong thực tế.

Vòng lặp trong: kiểm tra ngẫu nhiên, phán xét, sửa, chứng minh

Vòng lặp cốt lõi chạy từng ngôn ngữ một:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Có vài điều khiến cách này thực sự hiệu quả thay vì chỉ quẫy đạp vô ích.

Giám khảo là agent, không phải một lệnh gọi API. Khi chúng tôi nói “LLM làm giám khảo,” chúng tôi có ý là chính language agent đọc từng edge được lấy mẫu, đối chiếu với mã nguồn thực, và phân loại nó theo một rubric cố định gồm năm hạng mục: edge này đúng, là dương tính giả, là đúng quan hệ nhưng sai loại, gắn sai phạm vi, hay mang sai metadata? Rubric đó là yếu tố then chốt — “tỷ lệ lỗi 23%” vô nghĩa cho đến khi bạn biết liệu đó có phải là lỗi thực sự hay là giám khảo đếm sai.

Sửa một thứ, rồi chứng minh nó. Mỗi lần lặp thay đổi đúng một thành phần có thể chỉnh sửa, sau đó chạy lại trên một bộ kiểm thử (harness) cố định và chỉ giữ lại thay đổi nếu F1 cải thiện và việc phân loại lại trông tốt hơn. Nếu không, nó bị hoàn tác. Không có lô chỉnh sửa mang tính suy đoán, không có kiểu “chắc sẽ tốt hơn.” Một thay đổi phải giành được vị trí của nó hoặc biến mất. Và khi một bản sửa đứng vững, nó được đưa vào bộ fixture — để lỗi mà nó sửa không bao giờ có thể âm thầm quay lại. Bước thăng cấp đó chính là điều khiến vòng lặp đệ quy chứ không chỉ đơn thuần lặp lại: mỗi lượt chạy củng cố bộ chuẩn tham chiếu (oracle) mà lượt chạy tiếp theo sẽ xác thực dựa vào.

Bài học chúng tôi liên tục học lại: các chỉ số báo cáo thổi phồng

Đây là cái bẫy, và chúng tôi đã đi thẳng vào nó. Các chỉ số corpus phụ — tần suất một đích được trích xuất không có symbol có thể phân giải, bao nhiêu symbol trông “mồ côi,” v.v. — báo cáo thổi phồng vấn đề một cách khủng khiếp. Chúng phần lớn là hệ quả đặc thù của mô hình lập trình (paradigm), không phải lỗi.

Ví dụ rõ ràng nhất: llvm từng cho thấy tỷ lệ “nguồn không có symbol” là 73% và bị gắn nhãn thảm họa. Chúng tôi đào sâu vào. Độ chính xác thực sự là 98,5%. Những “symbol thiếu” đó gần như toàn bộ là các tham chiếu bên ngoài hợp lệ — lệnh gọi vào thư viện chuẩn, vào framework, vào mã nằm ngoài repo. Chỉ số đó đang đo một đặc tính của ngôn ngữ, không phải một lỗi trong handler. Các ngôn ngữ như Zig, COBOL, và Odin cho tỷ lệ “mồ côi” 65–70% và hoàn toàn đúng; COBOL không có lỗi thực sự nào.

Nếu chúng tôi để những con số đó dẫn dắt công việc, chúng tôi đã tốn hàng tuần “sửa” các handler vốn đã đúng và bỏ qua những ngôn ngữ có lỗi thực sự nhưng thầm lặng. Kết luận rất thẳng thắn: các chỉ số tổng hợp cùng lắm chỉ là một tín hiệu phân loại sơ bộ. Tín hiệu chất lượng thực sự là kiểm tra ngẫu nhiên kèm phân loại edge — nhìn vào các edge thực tế trong các repo thực tế và phán xét từng cái một. Dữ liệu hơn trực giác, nhưng chỉ khi bạn biết dữ liệu nào đang nói thật.

Vòng lặp ngoài: một đội quân, không phải một cuộc marathon

Làm từng ngôn ngữ một sẽ mất mãi mãi trên cả 280 ngôn ngữ, nên vòng lặp trong được bọc trong một vòng lặp ngoài chạy nhiều ngôn ngữ song song.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Mỗi agent làm việc trong một worktree dùng một lần để chúng không thể giẫm chân lên nhau. Orchestrator tích hợp các bản sửa của chúng từng cái một, mỗi cái đứng sau một lượt kiểm tra hồi quy toàn bộ manifest: một thay đổi giúp ích cho ngôn ngữ của chính nó nhưng âm thầm phá vỡ ba ngôn ngữ khác sẽ không được lên sóng. Việc tích hợp được kiểm soát qua cổng và xác nhận trước khi bất cứ thứ gì được đẩy lên — bước kiểm tra hồi quy quyết định cái gì an toàn, con người vẫn quyết định cái gì được lên sóng. Sau đó nhóm agent xoay vòng sang tập ngôn ngữ tiếp theo và toàn bộ quá trình lại chạy lại.

Những gì vẫn chưa hoàn hảo

Giám khảo có thể sai, và sự sai lệch có một hướng: một agent chạy với quá ít ngữ cảnh sẽ báo cáo thổi phồng. Trong một lô, tám ngôn ngữ bị gắn cờ với 5–20% lỗi; khi kiểm tra kỹ, chỉ một trong số những ngôn ngữ đó thực sự có lỗi — phần còn lại là sai sót của giám khảo do bỏ lỡ ngữ nghĩa riêng của ngôn ngữ đó (một dòng nguồn hợp lệ phát ra nhiều edge, việc liên kết tham số với giá trị được mô hình hóa như phép gán, các ngôn ngữ tham chiếu-theo-từng-định-danh). Đó là lý do chúng tôi lấy mẫu với hai seed và đối chiếu chéo, và vì sao sự bất đồng giữa giám khảo và fixture được xem là tín hiệu thú vị nhất, không phải một phán quyết đã chốt — đôi khi chính fixture mới là thứ sai.

Chúng tôi cũng thành thật về mục tiêu. Mục tiêu là zero lỗi thực sự, chấm hết — nhưng “zero” là một hướng đi mà chúng tôi mài giũa dần, từng ngôn ngữ một, không phải một ô được đánh dấu xong. Luôn luôn có một repo khác với một cách viết mã đặc thù khác.

Chứng minh bằng thực tế, không khẳng định suông

Mọi thứ Maguyva làm cho một agent — tìm một symbol, theo dõi một phụ thuộc, trả lời một câu hỏi với mã được trích dẫn — đều dựa vào việc trích xuất bên dưới là đúng. Trên 280 ngôn ngữ, “đúng” không thể chỉ khẳng định suông; nó phải liên tục được chứng minh bằng mã thực tế. Vòng lặp là cách chúng tôi giành được điều đó: một chu trình kiểm tra-và-sửa tự động luôn nghi ngờ chính các chỉ số của mình, chứng minh mọi thay đổi, và biến mỗi bản sửa thành một lớp bảo vệ chống lại lần hồi quy tiếp theo. Nó không hào nhoáng. Đó là công việc cho phép chúng tôi nói “chúng tôi hỗ trợ ngôn ngữ của bạn” và thực sự có ý đó. Xanh thì dễ. Muốn đúng thì phải bỏ công chứng minh.

Tìm kiếm hợp nhất đa phương thức: Chọn đúng bộ truy xuất cho mọi truy vấn

Wed, 15 Apr 2026 00:00:00 GMT

Ghi chú về thiết kế trước đây: bài viết tháng 4 năm 2026 này mô tả thiết kế định tuyến tại thời điểm đó, không phải hành vi mặc định hiện tại. Phần đính chính tháng 9 bên dưới chỉ xử lý một tuyên bố về đo lường. Để biết định tuyến hiện tại, các cấu hình có sẵn và cách điều khiển tường minh từng phương thức truy xuất, xem Cách hoạt động.

Một truy vấn tìm kiếm không phải là một thứ duy nhất.

“parseConfig được định nghĩa ở đâu” muốn một symbol chính xác — một vị trí chuẩn xác, thật nhanh. “authentication hoạt động như thế nào” muốn ý nghĩa — sự trải rộng của mã liên quan giải thích một khái niệm. “điều gì sẽ hỏng nếu tôi thay đổi hàm này” muốn đồ thị phụ thuộc. “tìm chuỗi ECONNREFUSED” muốn một khớp nguyên văn, không cần thông minh gì cả.

Grep rất xuất sắc cho các khớp nguyên văn và hữu ích cho một số cuộc săn tìm tham chiếu, nhưng nó không phải là đồ thị phụ thuộc và không hiểu ý nghĩa. Embedding bao phủ phía ngữ nghĩa, nhưng chúng là công cụ sai cho chuỗi chính xác và phân tích tác động. Hầu hết các công cụ tìm kiếm mã nguồn chọn một engine duy nhất và bắt mọi truy vấn phải sống với lựa chọn đó. Maguyva không chọn một. Nó tìm ra loại câu hỏi bạn vừa đặt, rồi pha trộn bốn bộ truy xuất theo đúng tỷ lệ mà câu hỏi đó xứng đáng.

Bốn phương thức

Bên dưới có bốn cách độc lập để tìm mã nguồn:

ngữ nghĩa (semantic) — tìm kiếm vector trên embedding nhị phân của Voyage; tìm mã theo ý nghĩa.
văn bản (text) — so khớp trigram; tìm chuỗi nguyên văn, chuỗi lỗi, định danh chính xác.
cấu trúc (structural) — truy vấn AST; tìm định nghĩa, chữ ký hàm, và các cấu trúc ngôn ngữ.
đồ thị (graph) — đồ thị phụ thuộc; tìm nơi gọi, nơi được gọi, và phạm vi ảnh hưởng.

Mỗi phương thức mạnh ở một loại câu hỏi khác nhau. Bí quyết là quyết định nên tin tưởng mỗi phương thức đến mức nào cho truy vấn đang có trước mặt bạn.

Phân loại ý định

Trước khi bất kỳ lượt truy xuất nào chạy, một bộ phân loại nhẹ sắp xếp truy vấn vào một trong sáu ý định, kèm điểm tin cậy. Nó được thiết kế rẻ một cách có chủ đích — các heuristic có thứ tự, khớp đầu tiên thắng — vì nó chạy trên đường nóng (hot path) và chỉ thêm một hoặc hai mili giây:

bắt đầu bằng def , class , func , import … → find_definition (độ tin cậy 0,95)
“who calls”, “usages of”, “references to” (ai gọi, các nơi sử dụng, tham chiếu đến) → find_references (0,90)
“impact”, “blast radius”, “what depends on” (tác động, phạm vi ảnh hưởng, những gì phụ thuộc vào) → impact_analysis (0,90)
một "string" trong dấu ngoặc kép hoặc một token lỗi như traceback → exact_match (0,85–0,90)
một định danh CamelCase hoặc snake_case → find_definition (0,60–0,80)
“how”, “why”, “explain”, “architecture” (như thế nào, vì sao, giải thích, kiến trúc) → understand_code (0,75)
không gì khớp cả → understand_code, độ tin cậy thấp (0,40)

Mỗi ý định mang một hồ sơ trọng số trên bốn phương thức. Đây là những con số thực tế:

Ý định	ngữ nghĩa	văn bản	cấu trúc (AST)	đồ thị
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

Vì vậy “parseConfig được định nghĩa ở đâu” nghiêng mạnh về AST (0,6). “auth hoạt động như thế nào” nghiêng về vector ngữ nghĩa (0,5). “cái gì phụ thuộc vào cái này” gần như hoàn toàn là đồ thị (0,7). “tìm ECONNREFUSED” gần như hoàn toàn là trigram (0,9), với mô hình embedding bị tắt hoàn toàn — vì độ tương đồng ngữ nghĩa chính xác là công cụ sai cho một chuỗi chính xác.

Đường nhanh, và đường hợp nhất

Khi bộ phân loại tự tin — điểm số ≥ 0,85 — và truy vấn là một truy vấn bình thường, Maguyva bỏ qua việc hợp nhất hoàn toàn và định tuyến thẳng đến phương thức chiếm ưu thế duy nhất. “X được định nghĩa ở đâu” không cần bốn bộ truy xuất; nó cần chỉ mục AST, ngay lập tức. Đường đi trực tiếp đó được báo cáo lại dưới dạng fusion_strategy: "direct".

Mọi thứ mơ hồ đều đi qua quá trình hợp nhất. Bốn (hoặc ba, với preset mặc định) phương thức chạy song song, mỗi phương thức trả về danh sách xếp hạng riêng, và chúng tôi kết hợp chúng lại.

Reciprocal Rank Fusion có trọng số

Hợp nhất các bộ truy xuất không đồng nhất khó hơn vẻ ngoài của nó: một độ tương đồng cosine 0,82 và một điểm trigram 137 và một độ trung tâm đồ thị 0,004 không nằm trên cùng một thang đo, nên bạn không thể chỉ đơn giản cộng chúng lại. Reciprocal Rank Fusion né tránh vấn đề này bằng cách bỏ đi các điểm số thô và chỉ giữ lại thứ hạng mà mỗi engine gán cho. Đóng góp của một kết quả từ một phương thức là:

contribution = weight × 1 / (k + rank + 1)

trong đó rank là vị trí của nó trong danh sách của phương thức đó và k là một hằng số làm mượt. Các đóng góp được cộng dồn qua các phương thức cho bất kỳ kết quả nào được nhiều hơn một engine tìm thấy — sự đồng thuận giữa các bộ truy xuất tự nhiên sẽ nổi lên trên cùng. Chúng tôi dùng k = 40 trên preset mặc định và 60 trên thorough (quick chỉ chạy ngữ nghĩa thuần túy, nên việc hợp nhất không bao giờ xảy ra ở đó). Nghiên cứu RRF gốc chốt ở k = 60 cho truy xuất đa dụng; giá trị mặc định của chúng tôi nhấn mạnh hơn một chút vào các kết quả được nhiều phương thức cùng xếp hạng cao — và chúng tôi không khuyến nghị tự tay tinh chỉnh nó.

Bên trên đó, các kết quả còn mang một hệ số tăng cường theo tầm quan trọng đồ thị. Một hub — một hàm mà toàn bộ codebase dựa vào — nên được xếp hạng cao hơn một nút lá ít nổi bật ngay cả khi có cùng độ liên quan văn bản, nên chúng tôi nhân mỗi đóng góp với:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

Độ trung tâm đến từ các chỉ số PageRank/degree đã được tính toán trước của pipeline, và hệ số tăng cường bị giới hạn ở mức 1,5× để một hàm phổ biến không thể hoàn toàn chôn vùi một hàm ít nổi bật nhưng liên quan hơn. Cuối cùng, chúng tôi hạ thấp thứ hạng các kết quả từ đường dẫn vendor, build, và archive, và loại bỏ trùng lặp để chỉ giữ đoạn tốt nhất cho mỗi file.

Những gì vẫn chưa hoàn hảo

Bộ phân loại ý định là một tập hợp biểu thức chính quy, không phải mô hình đã huấn luyện. Nó xử lý các dạng truy vấn phổ biến bằng heuristic, còn truy vấn mơ hồ sẽ dùng understand_code và một tổ hợp thiên về ngữ nghĩa. Phiên bản trước của bài viết này mô tả việc giảm tỷ lệ truy vấn không có kết quả từ khoảng 15% xuống dưới 5% như một kết quả đã đạt được. Thực ra, đề xuất tháng 12 năm 2025 chỉ nêu mức ban đầu ước tính và một mục tiêu; không có tập truy vấn hay biên bản đo lường nào được cung cấp để chứng minh. Chúng tôi rút lại tuyên bố đã đạt được cải thiện đó; xem bằng chứng nguồn và đính chính (tiếng Anh). Chúng tôi chưa thay bộ phân loại bằng mô hình đã huấn luyện vì phiên bản chi phí thấp đủ nhanh và đủ tốt cho vai trò định tuyến dự kiến, và vì một bộ phân loại sai nhưng tự tin còn tệ hơn một phương án dự phòng trung thực. Các trọng số là những giá trị tiên nghiệm được chọn thủ công, không phải học từ dữ liệu nhấp chuột mà chúng tôi không thu thập.

Đặt câu hỏi, không cần chọn công cụ

Một agent không nên phải biết là nên dùng grep hay embedding hay đồ thị lệnh gọi — nó nên đặt câu hỏi bằng ngôn ngữ đơn giản và nhận được câu trả lời đúng. Hợp nhất đa phương thức là thứ cho phép find_symbol, tìm kiếm ngữ nghĩa, và phân tích phụ thuộc cùng nằm sau một giao diện truy vấn duy nhất: hệ thống đọc hình dạng của câu hỏi và âm thầm ghép lại đúng bộ truy xuất cho nó. Mô hình chấm điểm embedding quan trọng, nhưng biết khi nào không nên dùng chúng cũng quan trọng không kém. Chọn đúng công cụ cho mỗi truy vấn là một loại chất lượng riêng, và đó là thứ chúng tôi muốn tự mình đảm nhận thay vì đẩy sang cho bên gọi.

// you bring the question. it brings the tools.

Khả năng quan sát hệ thống agent: Hooks, Alloy, và Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Các hệ thống agent hỏng theo những cách kỳ lạ.

Đôi khi mô hình là vấn đề. Đôi khi công cụ là vấn đề. Đôi khi máy chủ MCP của bạn vẫn ổn, nhưng agent lại chọn sai chuyên gia, hoặc tốn nửa phiên làm việc shell mà bạn không ngờ tới, hoặc âm thầm tiêu tốn ngân sách trong một vòng lặp trông có vẻ hiệu quả từ bên ngoài.

Nếu bạn không thể thấy được sự khác biệt, bạn không thực sự đang vận hành một hệ thống agent. Bạn đang đoán mò.

Vì vậy chúng tôi đã xây dựng một stack quan sát (observability stack) cho chính quy trình làm việc của mình: Claude Code, Codex, các sự kiện hook của Claude, các sự kiện notify của Codex, OpenTelemetry gốc, Grafana Alloy, và Grafana Cloud ở phía bên kia.

Phần thú vị không phải là “chúng tôi đã làm một dashboard.” Phần thú vị là chúng tôi phải tách telemetry thành hai luồng khác nhau vì không một nguồn dữ liệu duy nhất nào cho chúng tôi bức tranh toàn cảnh.

Vấn đề: Telemetry Agent bị phân mảnh

Các agent lập trình hiện đại đã phát ra một số telemetry. Điều đó có ích, nhưng chưa đủ.

OTEL gốc giỏi trả lời những câu hỏi như:

Chúng ta đã gửi bao nhiêu request?
Một phiên tốn bao nhiêu chi phí?
Các span và trace nằm ở đâu?
Độ trễ có tăng vọt không?

Nó tệ hơn nhiều khi trả lời những câu hỏi như:

Agent dựa vào máy chủ MCP nào?
Lỗi này nằm trong Bash, một công cụ file có sẵn, hay một lệnh gọi MCP?
Skill nào thực sự đã kích hoạt?
Loại subagent nào đã được điều động?
Phiên làm việc có đang làm việc hữu ích, hay chỉ đang quẫy đạp vô ích?

Lớp câu hỏi thứ hai đó gần với hook hơn là trace.

Nhưng điều ngược lại cũng đúng: một số câu hỏi hiệu năng quan trọng nhất lại gần với trace hơn là hook.

Nếu bạn muốn biết độ trễ thực sự tích tụ ở đâu, span nào chậm, hay liệu phiên làm việc có tốn thời gian vào các lệnh gọi mô hình so với thực thi công cụ hay không, bạn cần dữ liệu trace cũng như các sự kiện ngữ nghĩa.

Kiến trúc mà chúng tôi đã đi đến

Chúng tôi chạy hai đường telemetry song song.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Sự tách biệt đó là có chủ đích.

Nó cũng bất đối xứng. Claude Code cho chúng tôi một giao diện hook vòng đời phong phú hơn nhiều. Codex cho chúng tôi OTEL gốc cộng với một giao diện notify, nên chúng tôi chuẩn hóa các sự kiện hoàn tất lượt (turn-completion) ít chi tiết hơn thành cùng một schema log thay vì giả vờ rằng cả hai runtime cung cấp cùng những cơ chế kiểm soát.

OTEL gốc cho chúng tôi luồng cơ sở: log và trace từ chính runtime, cộng với các metric ở nơi runtime thực sự phát ra chúng.

Sự kiện hook và notify cho chúng tôi tầng ngữ nghĩa: những thứ như PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, và metadata đã phân loại mà chúng tôi thực sự quan tâm khi debug hành vi agent. Claude Code đóng góp luồng sự kiện phong phú hơn ở đây. Codex đóng góp một luồng đã chuẩn hóa ít chi tiết hơn nhưng vẫn hữu ích.

Vì sao hook tồn tại

Pipeline hook của chúng tôi làm giàu các sự kiện trước khi chúng chạm đến Loki.

Thay vì chỉ nói “một công cụ đã chạy,” chúng tôi phân loại sự kiện vào các trường như:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: backend MCP nào đã xử lý lệnh gọi
bash_cli: họ lệnh shell
subagent_type: loại chuyên gia nào đã được điều động
agent_tool: nguồn là Claude Code hay Codex

Điều đó có nghĩa là chúng tôi có thể đặt những câu hỏi quan trọng về mặt vận hành:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Đó không phải là những trường mang tính phù phiếm. Chúng là sự khác biệt giữa “agent có cảm giác chậm” và “agent đã tốn mười phút cuối vào các thao tác git nặng shell với tỷ lệ công cụ thất bại cao.”

Một chi tiết triển khai trông kỳ lạ hơn thực tế của nó: luồng Loki dùng chung vẫn dùng service_name="claude-code-hooks" làm nhãn ngay cả khi sự kiện đến từ Codex. Sự tách biệt thực sự giữa các runtime xảy ra ở agent_tool.

Vì sao Alloy nằm ở giữa

Grafana Alloy không chỉ là một bộ chuyển tiếp trong thiết lập này. Đây là nơi áp dụng các quy tắc xử lý telemetry.

Chúng tôi trỏ luồng OTEL gốc từ Claude Code và Codex đến một Alloy proxy cục bộ trên localhost:4318, sau đó để Alloy dọn dẹp payload trước khi chuyển tiếp nó đến Grafana Cloud.

Điều đó quan trọng vì telemetry agent thô đầy ắp các trường có nhiều giá trị phân biệt (high-cardinality), hữu ích cho phân tích nhưng tệ hại khi làm nhãn được lập chỉ mục:

session_id
prompt_id
số lượng token
thời lượng
các blob tham số công cụ

Nếu bạn lập chỉ mục mọi thứ, bạn sẽ có một vụ bùng nổ nhãn và một ngày tồi tệ.

Vì vậy Alloy làm ba việc cho chúng tôi:

Giữ lại một tập rất nhỏ các nhãn có ít giá trị phân biệt được lập chỉ mục.
Chuyển các trường ồn ào nhưng hữu ích vào metadata có cấu trúc.
Loại bỏ hoàn toàn nhiễu thuần túy.

Ý tưởng quan trọng rất đơn giản: quan sát nhiều hơn, lập chỉ mục ít hơn.

Vì sao luồng hook bỏ qua Alloy

Luồng hook đã được định hình sẵn cho Loki.

Vào lúc send_event.py đẩy một sự kiện, chúng tôi đã quyết định sẵn trường nào xứng đáng được xử lý như nhãn và trường nào thuộc về phần thân JSON có cấu trúc. Luồng đó đi thẳng đến cổng OTLP của Grafana Cloud thay vì đi qua thêm một lượt Alloy nữa.

Vì vậy hệ thống có một sự phân chia lao động rõ ràng:

Alloy thuần hóa luồng OTEL gốc thô.
Việc làm giàu hook làm cho các sự kiện ngữ nghĩa có thể truy vấn được.

Điều đó giữ kiến trúc đơn giản hơn so với việc cố ép mọi thứ đi qua một đường duy nhất.

Dashboard thực sự cho thấy gì

Ảnh chụp màn hình bên dưới là từ một trong những dashboard quan sát đứng sau quy trình agent của chúng tôi. Đó không phải là một benchmark, và các con số chỉ là một lát cắt tại một thời điểm. Điểm mấu chốt là hình dạng của dữ liệu: activity feed, lệnh gọi công cụ, thất bại, prompt, và các phân tích chi tiết theo agent, công cụ có sẵn, việc sử dụng MCP, lệnh shell, và skill.

Phần hữu ích là dashboard này sống trên cùng một stack Grafana với phần còn lại của telemetry agent. Chúng tôi có thể lọc theo agent nguồn và họ công cụ, và nhìn xuyên suốt các runtime mà không cần phát minh ra một câu chuyện quan sát khác nhau cho mỗi hệ thống.

Một trong những dashboard trực tiếp đứng sau quy trình agent của chúng tôi. Ảnh chụp màn hình này chỉ là một lát cắt của một stack Grafana dùng chung, cũng nhận telemetry từ các runtime và hệ thống agent khác của chúng tôi. Nhấp vào ảnh để xem phiên bản độ phân giải đầy đủ.

Vì sao trace quan trọng hơn vẻ ngoài ban đầu của chúng

Log cho chúng tôi biết loại công việc nào đã xảy ra. Trace cho chúng tôi biết công việc đó diễn ra như thế nào theo thời gian.

Sự khác biệt đó quan trọng trong các hệ thống agent vì “chậm” là mô tả quá chung chung để có ích.

Một trace có thể cho chúng tôi biết liệu sự đau đầu đến từ:

độ trễ mô hình
thời gian thực thi công cụ
các lần thử lại lặp đi lặp lại
một tương tác MCP đặc biệt tốn kém
một dải dài các thao tác nhỏ trông vô hại khi xét riêng lẻ

Trong thực tế chúng tôi dùng luồng hook và trace Tempo cùng nhau.

Log hook trả lời: loại việc gì đã xảy ra?
Trace trả lời: thời gian đã đi đâu?

Sự kết hợp đó là thứ biến quan sát từ một dashboard thành một lời giải thích.

Codex khớp vào đâu

Codex là một phần của cùng một stack, nhưng nó không giống hệt Claude Code.

Đối với Codex, chúng tôi kết nối hai phần:

OTEL gốc từ Codex vào Alloy
Một notify webhook vào codex_notify.py, ánh xạ các lượt hoàn tất thành cùng một schema Loki mà chúng tôi dùng cho các sự kiện hook

Điều đó cho chúng tôi một bộ lọc thống nhất như agent_tool="codex-cli" bên trong cùng một luồng log.

Lời cảnh báo thành thật: payload notify của Codex hiện chứa ít chi tiết hơn payload hook của Claude Code vì nó không phải là cùng loại giao diện tích hợp. Trong thiết lập hiện tại của chúng tôi, các lượt hoàn tất của Codex có thể được chuẩn hóa vào schema dùng chung, nhưng việc trích xuất chi tiết theo từng công cụ vẫn tốt hơn trong luồng OTEL gốc so với cầu nối notify.

Đó không phải là lý do để tránh viết bài này. Đó chính là ý nghĩa của bài viết. Các hệ thống quan sát thực sự được lắp ráp từ những tín hiệu không hoàn hảo.

Grafana qua MCP thay đổi cuộc chơi

Sự thay đổi lớn hơn là Grafana không chỉ là một nơi con người ghé thăm trong trình duyệt.

Trong repo này chúng tôi cũng cung cấp giao diện truy cập Grafana qua MCP. Điều đó nghĩa là một agent có thể truy vấn trực tiếp Loki, Prometheus, và Tempo thay vì chờ một con người kiểm tra dashboard thủ công trước.

Điều đó biến quan sát thành một đầu vào chủ động cho quy trình làm việc.

Một agent có thể hỏi:

Họ công cụ nào thất bại nhiều nhất trong giờ qua?
Máy chủ MCP nào chiếm ưu thế trong một phiên?
Các thay đổi gần đây có giảm thất bại công cụ, hay chỉ đơn giản là chuyển công việc sang các đường nặng shell hơn với cùng những lỗi cũ?
Trace nào cho thấy độ trễ cao nhất hoặc các lần thử lại lặp đi lặp lại?

Một khi bạn có được điều đó, bạn đã rất gần với một vòng lặp tự cải thiện.

Từ Dashboard đến vòng lặp phản hồi

Đây là phần chúng tôi thấy thú vị nhất.

Một khi stack quan sát có thể truy vấn được từ tầng agent, telemetry không còn là một phương tiện báo cáo thụ động nữa mà trở thành một tín hiệu điều khiển.

Vòng lặp trông như thế này:

Hoạt động agent phát ra trace, metric, và log hook đã làm giàu.
Grafana lưu trữ bằng chứng trong Loki, Tempo, và Prometheus ở những nơi có metric.
Agent truy vấn bằng chứng đó qua Grafana MCP.
Hệ thống xác định sự pha trộn công cụ tệ, skill dễ vỡ, định tuyến yếu, hoặc quy trình nặng shell liên tục tạo ra những lỗi có thể tránh được.
Agent hoặc người vận hành điều chỉnh prompt, cấu hình agent, mô tả skill, quy tắc định tuyến, hoặc quyền truy cập công cụ.
Phiên tiếp theo tạo ra một hình dạng telemetry mới, và chu trình lặp lại.

Đó là cách bạn đi từ “dashboard thú vị” đến “hệ thống cải thiện có thể đo lường được.”

Mục tiêu không phải là tối đa hóa một danh mục công cụ. Đó là đạt được đúng sự pha trộn giữa CLI, công cụ có sẵn, lệnh gọi MCP, và skill cho công việc thực sự đang được thực hiện.

Điều này cho phép chúng tôi trả lời gì

Một khi cả hai runtime cùng nằm trên một stack Grafana, chúng tôi có thể trả lời các câu hỏi vận hành nhanh hơn nhiều:

Thất bại có tập trung vào một họ công cụ không?
Các quy trình nặng shell có đang tạo ra những lỗi có thể tránh được ở nơi lẽ ra nên có một công cụ cấp cao hơn không?
Máy chủ MCP nào đang gánh phần lớn khối lượng công việc?
Chúng ta có đang trả tiền cho hoạt động agent không tạo ra tiến bộ có ý nghĩa hay không?
Một phiên gặp vấn đề là do mô hình, công cụ, hay tầng điều phối?

Điều này đặc biệt hữu ích trong các quy trình đa agent, nơi “agent đang bận” gần như không nói lên điều gì cả.

Nếu một chuyên gia liên tục được điều động và tạo ra tỷ lệ thất bại cao, đó là một vấn đề định tuyến hoặc định hình prompt.

Nếu một máy chủ MCP chiếm ưu thế trong mọi lệnh gọi, đó có thể là một kiến trúc tốt hoặc là dấu hiệu mọi thứ khác đều là gánh nặng vô ích.

Nếu thất bại công cụ tăng vọt trong khi chi phí vẫn cao, bạn có một vấn đề vận hành, không phải vấn đề chất lượng.

Nếu công việc shell liên tục thất bại theo những cách có thể dự đoán và tránh được ở nơi lẽ ra nên có một công cụ cấp cao hơn, đó là một tín hiệu sản phẩm.

Nếu một skill liên tục kích hoạt nhưng không cải thiện kết quả, đó là một tín hiệu prompt hoặc định tuyến.

Bài học thực sự

Bài học sâu sắc hơn ở đây là quan sát agent cần cả telemetry runtime lẫn telemetry quy trình làm việc.

Telemetry runtime cho bạn biết hệ thống đã làm gì.

Telemetry quy trình làm việc cho bạn biết agent nghĩ nó đang làm gì.

Chúng tôi cần cả hai.

Nếu bạn chỉ giữ trace và bộ đếm, bạn bỏ lỡ tầng ngữ nghĩa. Nếu bạn chỉ giữ sự kiện hook, bạn bỏ lỡ độ trễ, span, và bức tranh runtime rộng hơn.

Và nếu bạn giữ cả hai nhưng không bao giờ đưa chúng trở lại tầng agent, bạn có giám sát, không phải sự thích nghi.

Sự kết hợp đó là thứ khiến hệ thống đủ có thể giải thích được để vận hành và đủ có thể tinh chỉnh được để cải thiện.

Những gì vẫn chưa hoàn hảo

Vẫn còn những góc cạnh thô ráp.

Không phải mọi sự kiện hook đều bao gồm dữ liệu thời lượng và token mà chúng tôi mong muốn.
Một số khung nhìn thời gian tốt nhất vẫn đến từ trace Tempo, không phải log hook.
Codex hiện nay kém phong phú về mặt ngữ nghĩa hơn Claude Code trong luồng sự kiện đã làm giàu.
Ảnh chụp màn hình dashboard là một giao diện vận hành thực tế, không phải một tác phẩm marketing bóng bẩy.

Điểm cuối cùng đó là có chủ đích. Chúng tôi thà cho xem bảng điều khiển thật còn hơn giả vờ rằng các hệ thống agent tự giải thích được bằng phép màu.

Vì sao điều này quan trọng với Maguyva

Maguyva là về việc cho agent trí tuệ mã nguồn tốt hơn. Nhưng một khi agent thực sự đang làm việc hữu ích, một yêu cầu mới xuất hiện ngay lập tức: bạn cần thấy chúng đang hành xử như thế nào.

Chất lượng tìm kiếm, chất lượng định tuyến, việc chọn công cụ, và hiệu quả ngữ cảnh đều trở thành những vấn đề có thể quan sát được.

Đó là lý do chúng tôi nghĩ điều này đáng để viết. Stack agent của tương lai không chỉ là prompt và công cụ. Đó là prompt, công cụ, và tầng đo lường cho bạn biết liệu toàn bộ hệ thống có đang hoạt động hay không.

Nếu bạn đang xây dựng các quy trình agent nghiêm túc, quan sát không phải là hạ tầng tùy chọn. Nó là một phần của sản phẩm.

Khai thác vòng lặp: Làm sao các thay đổi trở thành ký ức tổ chức

Tue, 03 Feb 2026 00:00:00 GMT

Các con số trong bài này phản ánh hệ thống tại thời điểm xuất bản (tháng 2/2026). Xem trang team của chúng tôi để biết số liệu hiện tại.

Mọi đội kỹ thuật đều đối mặt với cùng một thách thức: các thay đổi diễn ra liên tục, nhưng cái lý do đằng sau những thay đổi đó lại biến mất. Sáu tháng sau, ai đó hỏi “tại sao chúng ta lại chọn DuckDB cho các giai đoạn pipeline?” và câu trả lời chỉ tồn tại trong đầu người đã đưa ra quyết định đó — nếu người đó vẫn còn ở đây.

Chúng tôi đã xây dựng một quy trình khai thác (mining workflow) khép kín vòng lặp này. Các thay đổi chảy qua các commit git, được xử lý bởi pipeline khai thác của chúng tôi, trở thành các mục changelog có cấu trúc và các bản ghi quyết định kiến trúc, sau đó được đưa trở lại vào các AI agent của chúng tôi thông qua các truy vấn CLI. Kết quả: một ký ức tổ chức mà cả con người và AI đều có thể truy cập.

Vấn đề: Quyết định bốc hơi

Hãy xem xét một kịch bản điển hình. Một developer commit:

feat(canonical): add DuckDB runtime for pipeline stages

Commit này đại diện cho một lựa chọn kiến trúc quan trọng. Đội đã đánh giá các phương án, cân nhắc sự đánh đổi, và chốt DuckDB vì những lý do cụ thể. Nhưng toàn bộ ngữ cảnh đó sống trong:

Một luồng Slack (có lẽ đã bị xóa)
Ký ức của ai đó (chắc chắn đang phai mờ)
Một comment trong mã (có thể, nếu may mắn)

Ba tháng sau, một thành viên mới trong đội hỏi: “Tôi nên dùng DuckDB hay SQLite cho giai đoạn mới này?” Không có ký ức tổ chức, họ hoặc phải phát minh lại bánh xe hoặc đưa ra những lựa chọn không nhất quán.

Vòng lặp: Từ Commit đến ngữ cảnh

Quy trình khai thác của chúng tôi biến lịch sử git thành tri thức có thể truy vấn:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

Insight cốt lõi: cả changelog lẫn quyết định kiến trúc đều chảy ra từ cùng một lịch sử git, được xử lý qua một pipeline thống nhất. Điều này đảm bảo không có gì lọt qua kẽ hở.

Cách khai thác hoạt động

Bước 1: Đồng bộ chỉ mục

uv run orkestra mine sync

Lệnh này quét lịch sử git và xây dựng một chỉ mục của tất cả các commit. Nó trích xuất các tín hiệu có cấu trúc từ mỗi commit:

Loại commit theo chuẩn Conventional Commits (feat, fix, chore, docs)
Scope (package hoặc khu vực nào)
Các dấu hiệu breaking change
Các file bị động đến và các chỉ số độ phức tạp

Bước 2: Kiểm tra trạng thái độ phủ

uv run orkestra mine status

Đây là trạng thái hiện tại của chúng tôi:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15.637 commit đã được xử lý. 476 trở thành quyết định kiến trúc. 6.799 trở thành mục changelog. Mọi commit đều được phân loại.

Bước 3: Lấy các ứng viên để rà soát

uv run orkestra mine candidates --limit 50 --full

Lệnh này làm nổi lên những commit chưa được xử lý, kèm đầy đủ ngữ cảnh để phân loại:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Các tín hiệu giúp định hướng việc phân loại: is_releasable_type: true gợi ý rằng commit này nên xuất hiện trong changelog. Số lượng dòng thêm vào lớn và các file hạ tầng gợi ý rằng nó cũng có thể là một quyết định kiến trúc.

Bước 4: Phân loại commit

Hai con đường tách nhánh ở đây: mục changelog và quyết định kiến trúc.

Đối với mục changelog:

uv run orkestra mine classify abc123 --changelog added

Điều này ghi nhận rằng commit abc123 nên xuất hiện trong changelog dưới danh mục “Added.”

Đối với quyết định kiến trúc:

Trước tiên, lấy một decision ID thật:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Sau đó phân loại kèm decision ID đó:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Điều này liên kết commit với một bản ghi quyết định sẽ được tạo mới hoặc cập nhật.

Đối với xử lý theo lô (điều chúng tôi thực sự làm):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Định dạng JSONL hỗ trợ cả hai domain trong một lượt:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Bước 5: Render đầu ra

uv run orkestra registry changelog render --package <pkg>

Điều này sinh ra các file CHANGELOG.md cho từng package từ ledger. Các changelog là các tài sản dẫn xuất — xóa chúng đi và chúng sẽ được tái sinh hoàn hảo từ ledger nguồn.

Cấu trúc bản ghi quyết định

Các quyết định đã trích xuất trở thành các file YAML với metadata phong phú:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Mọi quyết định đều liên kết ngược về các commit nguồn của nó. Mọi quyết định đều chỉ rõ những file nào nó ảnh hưởng. Các quan hệ giữa các quyết định là tường minh.

Tích hợp CLI: Truy vấn ký ức tổ chức

Đây là nơi vòng lặp khép lại. Các agent có thể truy vấn quyết định qua CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Trả về các quyết định về logic thử lại, xử lý lỗi, các mẫu khôi phục.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Trả về bản ghi quyết định đầy đủ kèm ngữ cảnh, lý do, và tác động.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Cho thấy những lựa chọn kiến trúc nào đã được thực hiện gần đây.

Cách các agent sử dụng điều này

Các chỉ dẫn nền tảng của orchestrator của chúng tôi bao gồm:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Khi một agent được yêu cầu triển khai thứ gì đó liên quan đến DuckDB, nó có thể kiểm tra trước:

uv run orkestra registry decisions search --query "DuckDB"

Và khám phá ra DEC-PL-142, học được:

Vì sao chúng tôi chọn DuckDB (context)
Cách dùng nó đúng cách (agent_guidance)
Những file nào cần xem (files)
Những quyết định liên quan nào tồn tại (related)

Agent không phát minh lại bánh xe. Nó xây dựng dựa trên các mẫu đã được thiết lập.

Bài kiểm tra ba câu hỏi

Không phải commit nào cũng xứng đáng có một bản ghi quyết định. Chúng tôi dùng Bài kiểm tra ba câu hỏi để lọc:

Việc này có khó để đưa ra không? Nó có đòi hỏi phân tích đáng kể, đánh giá sự đánh đổi, hoặc tranh luận không?
Việc thay đổi nó có tốn kém không? Việc đảo ngược quyết định này có đòi hỏi phải làm lại đáng kể không?
Nó có tác động toàn hệ thống không? Nó có ảnh hưởng đến nhiều package hoặc thiết lập các mẫu mà những người khác sẽ tuân theo không?

Nếu một commit trả lời “có” cho ít nhất một trong các câu hỏi này, nó là ứng viên để trích xuất thành quyết định. Tỷ lệ điển hình của chúng tôi: 1-4 quyết định trên mỗi 100 commit (khoảng 1-4%).

Đối với các mục changelog, ngưỡng yêu cầu thấp hơn: bất kỳ thay đổi nào hướng đến người dùng (tính năng, sửa lỗi, cải tiến) đều được ghi lại. Các công việc vặt nội bộ, cập nhật tài liệu, và refactor thường bị bỏ qua. Tỷ lệ điển hình của chúng tôi: 30-50 mục changelog trên mỗi 100 commit.

Lưu trữ dữ liệu: Ledger chỉ-thêm (Append-Only)

Hệ thống khai thác dùng các ledger JSONL chỉ-thêm để vận hành đa agent không xung đột:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Định dạng JSONL với merge=union trong .gitattributes nghĩa là nhiều agent có thể phân loại commit đồng thời mà không có xung đột merge. Mỗi dòng độc lập với nhau.

Kiểm tra tính hợp lệ

Trước mỗi phiên khai thác, chúng tôi chạy xác thực:

uv run orkestra mine validate --quick

Điều này kiểm tra:

Tính hợp lệ của định dạng SHA
Sự tuân thủ định dạng decision ID
Không có mục trùng lặp cho cùng một SHA
Các quyết định được tham chiếu thực sự tồn tại

Sau khi phân loại, chúng tôi xác thực lại lần nữa trước khi commit các thay đổi.

Vì sao điều này quan trọng

Vòng lặp phản hồi mà chúng tôi đã xây dựng giải quyết một số vấn đề:

Đối với thành viên mới trong đội: Thay vì hỏi “tại sao chúng ta lại làm X?”, họ có thể tìm kiếm trong registry quyết định. Ngữ cảnh được bảo toàn.

Đối với AI agent: Chúng không hoạt động trong chân không. Chúng có thể truy vấn tri thức tổ chức trước khi đưa ra đề xuất. Khi được yêu cầu thêm một giai đoạn pipeline mới, chúng có thể khám phá ra mẫu DuckDB và làm theo.

Đối với tính nhất quán kiến trúc: Các quyết định tường minh và có thể tìm kiếm được. Khi ai đó đề xuất một cách tiếp cận mâu thuẫn với một quyết định hiện có, hệ thống có thể làm nổi lên xung đột đó.

Đối với việc sinh changelog: Ghi chú phát hành không phải là một cuộc chạy đua vào phút chót. Chúng là sản phẩm phụ của việc phân loại liên tục trong suốt quá trình phát triển.

Đối với onboarding: Các agent mới thừa hưởng toàn bộ ngữ cảnh của codebase. Chúng không chỉ thấy mã nguồn — chúng thấy cả những quyết định đã định hình nên nó.

Trạng thái hiện tại

Tính đến hôm nay:

15.637 commit đã được xử lý qua pipeline
476 quyết định kiến trúc đã được trích xuất và ghi lại tài liệu
6.799 mục changelog đã được ghi nhận
Độ phủ 100% trên cả hai domain

Mọi commit kể từ khi chúng tôi bắt đầu đều đã được phân loại. Ký ức tổ chức đã hoàn chỉnh và có thể truy vấn được.

Bắt đầu

Nếu bạn muốn triển khai một thứ tương tự:

Bắt đầu với chuẩn Conventional Commits. Pipeline khai thác hoạt động tốt nhất khi các commit có tiền tố có cấu trúc (feat:, fix:, chore:).
Định nghĩa các domain của bạn. Chúng tôi dùng các domain như pipeline, agent-design, observability, data-modeling. Chúng tổ chức các quyết định theo khu vực.
Xây dựng thói quen phân loại. Việc khai thác chỉ hiệu quả khi các đội thường xuyên phân loại commit. Xử lý theo lô với sự hỗ trợ của LLM giúp mở rộng quy mô.
Làm cho quyết định có thể truy vấn được. Giá trị tăng lên khi các agent có thể tìm kiếm quyết định qua CLI. Tổ chức đầu ra để máy có thể xử lý được.
Khép kín vòng lặp. Các quyết định nên ảnh hưởng đến công việc trong tương lai. Đưa các tham chiếu quyết định vào chỉ dẫn agent và checklist rà soát mã.

Mục tiêu không phải là tài liệu hoàn hảo. Đó là làm cho cái lý do đằng sau các thay đổi trở nên dễ tiếp cận với cả con người và AI, ngay hôm nay và sáu tháng nữa. Khi các thay đổi trở thành ký ức tổ chức, các đội xây dựng dựa trên các mẫu đã được thiết lập thay vì phát minh lại chúng.

Quy trình khai thác là một phần của engine orchestration của chúng tôi, cụ thể là module context engine trong package orchestration của chúng tôi.

Khai thác Skill: Từ 3.500 ứng viên đến 466 năng lực

Tue, 27 Jan 2026 00:00:00 GMT

Các con số trong bài này phản ánh hệ thống tại thời điểm xuất bản (tháng 1/2026). Xem trang team của chúng tôi để biết số liệu hiện tại.

Vấn đề 3.500 Skill

Khi chúng tôi bắt đầu xây dựng một hệ thống điều phối agent, chúng tôi đối mặt với một thách thức thú vị: có hàng nghìn skill tiềm năng rải rác khắp hệ sinh thái AI. Repository GitHub, tài liệu vendor, dự án cộng đồng, các mẫu nội bộ - skill tồn tại ở khắp mọi nơi. Nhưng cái nào thực sự quan trọng? Cái nào thực sự hoạt động? Và làm sao bạn duy trì được một thư viện skill mạch lạc mà agent thực sự có thể dùng?

Câu trả lời của chúng tôi: một vòng lặp khai thác và nạp có hệ thống.

Các con số hôm nay

Chỉ hơn ba tháng sau khi Anthropic ra mắt Agent Skills vào ngày 16 tháng 10 năm 2025, đây là vị trí của chúng tôi khi bài viết này được xuất bản vào ngày 27 tháng 1 năm 2026:

Chỉ số	Số lượng
Ứng viên đã xác định	3.500+
Skill đã tiếp nhận	466
Skill vendor	373
Skill nội bộ	93
Vendor đang hoạt động	25+
Token trung bình mỗi skill	2.834
Công cụ được tham chiếu	89
Tag riêng biệt	635

Chúng tôi đã rà soát hơn 3.500 skill ứng viên. Chúng tôi đã tiếp nhận 466. Đó là tỷ lệ tiếp nhận 13% - và sự chọn lọc đó là có chủ đích.

Hệ thống tầng tri thức

Không phải mọi skill đều được tạo ra ngang hàng. Chúng tôi tổ chức chúng thành năm tầng tri thức (K0-K4), mỗi tầng đại diện cho một phạm vi áp dụng khác nhau:

K0: Foundations (Phổ quát)

Skill mà mọi agent nên có. Chúng đại diện cho năng lực “người suy nghĩ giỏi” hoạt động ở bất cứ đâu.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Skill K0 có thể mang theo đến bất kỳ dự án nào, domain nào, stack nào. Chúng mã hóa các mẫu nhận thức phổ quát.

K1: Identities (Chuyên ngành)

Skill kiểu “kỹ sư giỏi” hoặc “nhà nghiên cứu giỏi” áp dụng được xuyên suốt các dự án trong một ngành.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domains (Chuyên môn lĩnh vực)

Skill kiểu “chuyên gia database giỏi” hoặc “kỹ sư bảo mật giỏi” có thể mang theo trong một lĩnh vực.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (Công nghệ)

Skill kiểu “người dùng Supabase giỏi” hoặc “nhà phát triển Cloudflare giỏi” cho các stack công nghệ cụ thể.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Project (Tổ chức)

Skill đặc thù cho tổ chức và quy trình của chúng tôi.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

Vòng lặp khai thác

Giai đoạn 1: Khám phá

Skill đến từ khắp mọi nơi:

Repository Vendor: AWS, Anthropic, Cloudflare, Supabase, và các cộng tác viên cộng đồng phát hành các bộ sưu tập skill. Chúng tôi theo dõi 25+ vendor root.

Dự án cộng đồng: GitHub đầy ắp các template Claude Code, mẫu agent, và định nghĩa quy trình.

Mẫu nội bộ: Khi đội của chúng tôi giải quyết các vấn đề, các mẫu xuất hiện. Chúng được hình thức hóa thành skill.

Khai thác tài liệu: Tài liệu kỹ thuật thường chứa các skill ngầm định - quy trình, checklist, cây quyết định.

Việc khám phá diễn ra liên tục. Chúng tôi dùng một backlog skill để theo dõi các ứng viên trước khi đánh giá chính thức.

Giai đoạn 2: Đánh giá

Mỗi ứng viên đi qua cùng một rubric:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Cả năm tiêu chí sản phẩm đều phải đạt. Đây là lý do 87% ứng viên bị loại.

Sau đó mỗi ứng viên đi qua một lượt rà soát độ tin cậy riêng biệt. Chúng tôi không xem một repository vendor chính thức, một maintainer cộng đồng nổi tiếng, và một repo GitHub ngẫu nhiên là những nguồn chân lý tương đương nhau.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Các vendor đáng tin cậy được rà soát nguồn gốc nhẹ hơn, nhưng không phải là một vé miễn phí. Các nguồn không đáng tin cậy hoặc không rõ danh tính phải trải qua một lượt kiểm toán thủ công sâu hơn, và chúng tôi không thực thi các script đi kèm cho đến khi chúng đã được đọc, xác định phạm vi, và phân loại là an toàn.

Phân tích khoảng trống: Trước khi tiếp nhận, chúng tôi tìm kiếm trong registry của mình:

uv run orkestra skills search "<capability>"

Nếu chúng tôi đã có nó rồi, chúng tôi không cần nó nữa. Nếu chúng tôi có thứ gì đó gần giống, chúng tôi có thể hợp nhất thay vì tiếp nhận.

Chấm điểm độ sâu và tiêu chuẩn: Chúng tôi cũng chấm điểm mức độ ứng viên sử dụng đầy đủ mô hình agent-skill. Một SKILL.md đơn lẻ vẫn có thể hữu ích, nhưng các skill sâu hơn có giá trị hơn khi chúng tách biệt các chỉ dẫn khỏi tham chiếu, script, và tài sản theo cách mà agentskills.io khuyến khích.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Sao GitHub có thể nâng điểm tín nhiệm lên một chút, nhưng chúng không bao giờ cứu được một skill hời hợt hoặc không an toàn. Một repo nhiều sao với một SKILL.md mơ hồ và các script khó kiểm tra sẽ được chấm điểm thấp hơn một repo nhỏ hơn với mô tả chính xác, tài liệu tham khảo được tuyển chọn trong references/, và các helper nhỏ làm đúng một việc và thực sự tận dụng đầy đủ năng lực skill.

Phân tích cấu trúc: Chúng tôi kiểm tra chất lượng skill:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Nếu một ứng viên bao gồm script, lượt rà soát đó trở nên nghiêm ngặt hơn. Một skill tốt không chỉ hữu ích; nó phải dễ hiểu, có giới hạn, và an toàn để giao cho một agent. Chỉ riêng bộ lọc an toàn đó đã loại một phần đáng kể những ứng viên vốn đáng quan tâm ở các mặt khác.

Giai đoạn 3: Nạp (Ingestion)

Khi một skill vượt qua đánh giá, nó bước vào registry. Nhưng skill không bao giờ được tiếp nhận nguyên trạng. Chúng được chỉnh sửa để phù hợp với hệ thống của chúng tôi.

Các chỉnh sửa khi tiếp nhận:

Chuẩn hóa Metadata: Mọi skill nhận được schema frontmatter của chúng tôi
Gán tầng K: Skill được đặt vào tầng tri thức phù hợp
Làm giàu Tag: Tag được thêm vào để hỗ trợ khám phá
Khai báo công cụ: Các công cụ được phép được khai báo tường minh
Căn chỉnh phần: Nội dung được tái cấu trúc để khớp với template của chúng tôi

Một skill YAML điển hình sau khi nạp:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Giai đoạn 4: Gán phạm vi

Skill được gán vào các scope - các danh mục xác định agent nào nạp skill nào:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Agent khai báo scope của chúng, và skill được tự động gán:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Giai đoạn 5: Hiện thực hóa

Skill không tồn tại dưới dạng YAML trong production. Chúng được render thành các file SKILL.md mà Claude Code có thể nạp:

uv run orkestra sync

Lệnh này:

Đọc tất cả định nghĩa skill YAML
Render chúng qua các template Jinja
Ghi các file SKILL.md vào .claude/skills/
Tổ chức theo tầng K (foundations/, identities/, domains/, stacks/, project/)

Cấu trúc đầu ra cuối cùng:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Mẫu phạm vi ngủ đông (Dormant Scope)

Một trong những mẫu mạnh mẽ nhất của chúng tôi là các skill “đã tiếp nhận nhưng chưa nạp.” Chúng tôi gọi chúng là các scope ngủ đông.

Hãy xem xét các skill điện toán khoa học từ repository k-dense-scientific. Chúng tôi đã tiếp nhận hơn 120 skill bao phủ tin sinh học, hóa học, điện toán lượng tử, và tin học lâm sàng. Nhưng hầu hết các agent của chúng tôi không cần docking phân tử hay phân tích biểu hiện gen.

Thay vì nạp cả 120 skill vào mọi agent (làm phình to cửa sổ ngữ cảnh), chúng tôi:

Tiếp nhận các skill với một scope cụ thể (ví dụ: bioinformatics)
Giữ chúng ở trạng thái ngủ đông - đã đăng ký nhưng chưa nạp
Kích hoạt chúng chỉ khi một agent khai báo scope đó

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Mẫu này cho phép chúng tôi có 466 skill trong registry trong khi các agent điển hình chỉ nạp 40-60 skill liên quan.

Các loại Skill

Skill xuất hiện dưới ba mẫu nhận thức:

Workflow

Các bước quy trình có thứ tự: “1. Làm X, 2. Sau đó Y, 3. Cuối cùng Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Discipline

Rào chắn hành vi: “Luôn X”, “Không bao giờ Y”, “Ưu tiên Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist

Tiêu chí xác minh: “Xác nhận X”, “Kiểm chứng Y”, “Kiểm tra Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Kiểm tra chất lượng

Mọi skill phải vượt qua xác thực trước khi lên sóng:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Mô tả phải có 50-400 ký tự với các cụm từ kích hoạt (“Dùng khi…”, “Khi bạn cần…”) để Claude Code biết khi nào nên gợi ý chúng.

Chúng tôi xác thực liên tục:

uv run orkestra validate --show-warnings

Hệ sinh thái Vendor

373 skill vendor của chúng tôi đến từ:

Nhà cung cấp	Skill	Lĩnh vực
AWS Agent	19	Dịch vụ đám mây
Anthropic	12	Sinh tài liệu
Cloudflare	8	Điện toán biên
Supabase	5	Database
k-dense	100+	Điện toán khoa học
silvainfm	4	Khoa học dữ liệu
Java Developer Kit	45+	Spring/Java
Vercel	1	Tự động hóa trình duyệt

Mỗi vendor root được khai báo trong metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Khi orkestra sync chạy, các skill vendor được symlink vào .claude/skills/vendor/ kèm namespace nhà cung cấp của chúng.

Những gì chúng tôi đã học được

Sự chọn lọc mang lại kết quả. Thật hấp dẫn khi muốn tiếp nhận mọi thứ trông có vẻ hữu ích. Nhưng mỗi skill đều tốn token. Với trung bình 2.834 token mỗi skill, sự phình to gây tổn hại nhanh chóng. Tỷ lệ tiếp nhận 13% của chúng tôi giữ cho các agent gọn nhẹ.

Cấu trúc cho phép khám phá. Hệ thống tầng K không chỉ là tổ chức - đó là về khả năng mang theo. Skill K0 có thể tái sử dụng ở bất cứ đâu. Skill K4 có chủ đích đặc thù cho dự án. Sự rõ ràng này giúp cả con người lẫn agent tìm thấy những gì họ cần.

Scope ngủ đông mở rộng quy mô. Bạn có thể tiếp nhận hàng trăm skill mà không cần nạp tất cả. Scope cho phép bạn xây dựng một registry toàn diện trong khi vẫn giữ cửa sổ ngữ cảnh của từng agent ở mức quản lý được.

Chỉnh sửa khi tiếp nhận là thiết yếu. Skill vendor thô hiếm khi phù hợp với hệ thống của bạn. Quy trình nạp - thêm metadata, gán tầng, làm giàu tag - khiến các skill bên ngoài hoạt động được ở nội bộ.

Khai thác diễn ra liên tục. Con số 3.500 vẫn tiếp tục tăng. Các repo vendor mới xuất hiện. Các mẫu cộng đồng nổi lên. Các quy trình nội bộ được củng cố. Vòng lặp không bao giờ dừng lại.

Điều gì tiếp theo

Chúng tôi đang làm việc trên một số cải tiến:

Phát hiện khoảng trống tự động: Cảnh báo khi các lỗi agent phổ biến có thể được giải quyết bởi một skill chưa được tiếp nhận
Quy trình khai tử skill: Quy trình chính thức để loại bỏ các skill đã bị thay thế hoặc không được dùng
Phụ thuộc liên-skill: Khai báo tường minh các điều kiện tiên quyết của skill
Phân tích sử dụng: Theo dõi skill nào agent thực sự gọi so với chỉ nạp

Vòng lặp khai thác skill là hạ tầng. Nó không hào nhoáng. Nhưng đó là thứ khiến 41 agent hoạt động mạch lạc với 466 năng lực trong khi vẫn nằm trong giới hạn ngữ cảnh.

Đó là câu chuyện về việc 3.500 trở thành 466 như thế nào. Không phải bằng cách bỏ qua 3.000 - mà bằng cách đánh giá chúng có hệ thống và chỉ tiếp nhận những gì thực sự hoạt động.

Muốn xem hệ thống skill hoạt động trong thực tế? Hãy xem uv run orkestra skills list để khám phá registry hiện tại của chúng tôi.

Bộc lộ dần dần: Cửa sổ CLI nhìn vào hệ thống agent

Tue, 20 Jan 2026 00:00:00 GMT

Các con số trong bài này phản ánh hệ thống tại thời điểm xuất bản (tháng 1/2026). Xem trang team của chúng tôi để biết số liệu hiện tại.

Thiết kế của các hệ thống agent khiến cách chúng hoạt động khó quan sát. Chúng ra quyết định, gọi công cụ, và điều phối công việc trên hàng chục chuyên gia. Nhưng khi có gì đó trục trặc — hoặc khi bạn đơn giản chỉ muốn hiểu chuyện gì đang xảy ra — bạn nhìn vào đâu?

Câu trả lời là bộc lộ dần dần (progressive disclosure): một giao diện theo lớp bộc lộ đúng bằng lượng độ phức tạp bạn cần, đúng vào lúc bạn cần nó.

Vấn đề thiếu khả năng quan sát

Một hệ thống điều phối agent hiện đại có thể có:

40+ agent chuyên biệt, mỗi agent có năng lực riêng
700+ skill trải khắp tự động hóa nội bộ và tích hợp vendor
470+ quyết định kiến trúc định hình hành vi
Hàng chục máy chủ công cụ MCP cung cấp năng lực bên ngoài

Độ phức tạp này là có chủ đích. Agent cần quyền truy cập vào ngữ cảnh phong phú — tri thức domain, trí tuệ mã nguồn, schema database — để ra quyết định tốt. Nhưng chính sự phong phú đó tạo ra một vấn đề về khả năng quan sát.

Làm sao bạn biết agent nào xử lý di trú database? Những quyết định nào đã định hình hành vi xếp hạng của hệ thống tìm kiếm? Agent tư vấn kiến trúc có quyền truy cập vào những công cụ nào?

Không có quyền truy cập có cấu trúc, bạn chỉ còn cách đọc mã nguồn hoặc hy vọng tài liệu vẫn còn cập nhật.

Bộc lộ dần dần như một kiến trúc

Bộc lộ dần dần không chỉ là một mẫu UI. Đó là một nguyên tắc kiến trúc: tổ chức thông tin theo từng lớp, mỗi lớp sâu hơn lớp trước, để người dùng có thể dừng lại ở mức trả lời được câu hỏi của họ.

Với các hệ thống agent, điều này chuyển thành các lệnh CLI ở các độ sâu tăng dần:

Mức	Lệnh	Câu hỏi được trả lời
1	`orkestra system status`	Mọi thứ có khỏe mạnh không?
2	`orkestra agents list`	Có những agent nào?
3	`orkestra agents info <name>`	Agent này làm gì?
4	`orkestra decisions search`	Tại sao nó hoạt động theo cách này?
5	Công cụ MCP của Maguyva	Cho tôi xem mã nguồn.

Mỗi mức trả lời một câu hỏi tiếp nối tự nhiên. Bạn hiếm khi cần nhảy thẳng đến mức 5.

Mức 1: Sức khỏe hệ thống

Câu hỏi đầu tiên luôn là: mọi thứ có đang hoạt động không?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Một lệnh. Bốn con số. Đủ để biết hệ thống đã được cấu hình và các registry đã được nạp đầy đủ.

Nếu số lượng agent giảm đột ngột hoặc skill không nạp được, bạn sẽ thấy điều đó ở đây đầu tiên. Không cần lặn sâu vào log.

Mức 2: Kho agent

Một khi bạn biết hệ thống khỏe mạnh, câu hỏi tiếp theo là: có gì sẵn có?

$ orkestra agents list

Lệnh này trả về dữ liệu có cấu trúc — tên agent, mô tả, mô hình ưa thích, độ phủ domain. Đầu ra mặc định là JSON, giúp dễ dàng pipe vào jq để lọc:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Muốn tìm các agent xử lý công việc database? Lệnh tìm kiếm sẽ thu hẹp phạm vi:

$ orkestra agents search "database"

Lệnh này quét tên, mô tả, và năng lực. Bạn tìm đúng chuyên gia mà không cần đọc 40 định nghĩa agent.

Mức 3: Đào sâu vào agent

Đã tìm thấy một agent có vẻ liên quan? Lệnh info bộc lộ mọi thứ:

$ orkestra agents info architecture-advisor

Đầu ra bao gồm:

Metadata: Tên, danh mục, mô hình ưa thích, mô tả
Domains: Những lĩnh vực tri thức nào agent này bao phủ
Identity: Đặc điểm tính cách (architect, strategist, knowledge-architect)
Hướng dẫn công cụ: Tài liệu công cụ nào được tiêm vào ngữ cảnh
Tools: Danh sách đầy đủ các công cụ MCP mà agent này có quyền truy cập

Đây là một mẫu về những gì bạn thấy:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Điều này cho bạn biết chính xác agent có thể làm gì. Không cần đến mã nguồn.

Mức 4: Khảo cổ quyết định

Agent hành xử theo các quyết định đã được ghi lại tài liệu. Khi bạn cần hiểu vì sao một thứ gì đó hoạt động theo một cách cụ thể, registry quyết định là nguồn chân lý.

$ orkestra decisions search "agent"

Lệnh này trả về các quyết định kiến trúc khớp:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Mỗi quyết định đều có đầy đủ thông tin về nguồn gốc — khi nào nó được đưa ra, vì sao, những sự đánh đổi nào đã được cân nhắc, những commit nào đã triển khai nó:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Đây là tài liệu kiến trúc luôn cập nhật vì nó được khai thác từ các commit, không phải được bảo trì thủ công.

Mức 5: Trí tuệ mã nguồn trực tiếp

Khi bạn cần thấy việc triển khai thực sự — không phải metadata về nó — các công cụ MCP của Maguyva cung cấp quyền truy cập trực tiếp.

Từ bên trong một phiên agent:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Lệnh này tự động định tuyến qua tìm kiếm ngữ nghĩa, văn bản, và AST để tìm mã liên quan. Với các symbol cụ thể:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Cho phân tích phụ thuộc:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Đây không chỉ là những thứ thay thế grep. Chúng nhận biết đồ thị, được lập chỉ mục ngữ nghĩa, và tích hợp với cùng lớp trí tuệ mã nguồn đang vận hành chính các agent.

Tìm kiếm hợp nhất trên các Registry

Đôi khi bạn không biết registry nào giữ câu trả lời. Tìm kiếm hợp nhất trải khắp mọi thứ:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 khớp trên năm registry. Bản tóm tắt cho bạn biết nên đào sâu vào đâu. Bỏ --summary để có kết quả chi tiết, hoặc thêm --limit 5 để giữ đầu ra gọn gàng.

Vì sao điều này quan trọng

Bộc lộ dần dần không chỉ là về sự tiện lợi. Nó thay đổi cách bạn tương tác với các hệ thống phức tạp.

Việc debug trở nên khả thi. Khi một agent ra một quyết định bất ngờ, bạn không phải grep xuyên qua log. Bạn kiểm tra nó có quyền truy cập vào những công cụ nào (agents info), những quyết định nào định hình hành vi của nó (decisions search), và theo dõi việc triển khai nếu cần (intelligent_search).

Onboarding tăng tốc. Thành viên mới trong đội không cần đọc toàn bộ codebase. Họ bắt đầu với system status, khám phá với agents list, và chỉ đào sâu hơn khi gặp phải thứ gì đó họ không hiểu.

Tài liệu luôn cập nhật. Vì CLI đọc từ cùng các registry cấu hình các agent, đầu ra luôn chính xác. Không có sự trôi dạt giữa những gì tài liệu nói và những gì hệ thống làm.

CLI như một giao diện

Chúng tôi có thể đã xây dựng một dashboard web. Chúng tôi có thể đã viết tài liệu đồ sộ. Thay vào đó, chúng tôi xây dựng một CLI đọc trực tiếp từ nguồn chân lý.

CLI có những lợi thế:

Có thể kết hợp (Composable): Pipe đầu ra qua jq, tích hợp với script
Có thể lập trình (Scriptable): Tự động hóa kiểm tra, sinh báo cáo
Nhanh: Không tải trang, không luồng xác thực
Chính xác: Đọc cấu hình thực tế, không phải một bản biểu diễn đã cache

Với các hệ thống nơi tính đúng đắn quan trọng hơn tính thẩm mỹ, CLI thắng.

Xây dựng bộc lộ dần dần của riêng bạn

Nếu bạn đang xây dựng các hệ thống agent, hãy cân nhắc cách người dùng sẽ kiểm tra chúng:

Bắt đầu với kiểm tra sức khỏe. Một lệnh cho bạn biết mọi thứ có đang hoạt động hay không.
Cung cấp các chế độ xem danh mục. Liệt kê những gì tồn tại trước khi giải thích nó làm gì.
Cho phép truy vấn có mục tiêu. Tìm kiếm vượt trội hơn duyệt thủ công ở quy mô lớn.
Cho phép tra cứu nguồn gốc. Cho phép người dùng theo dõi các quyết định về tận nguồn gốc của chúng.
Kết nối với trí tuệ mã nguồn. Cuối cùng, người dùng cần thấy việc triển khai.

Mỗi lớp trả lời một câu hỏi tiếp nối. Xây dựng chúng theo thứ tự tần suất — hầu hết người dùng dừng ở lớp 2 hoặc 3. Chỉ những power user mới chạm đến lớp 5.

Mục tiêu không phải là phơi bày mọi thứ. Đó là phơi bày chính xác những gì cần thiết, đúng vào lúc cần thiết. Đó là bộc lộ dần dần được áp dụng vào kiến trúc agent.

Ground Truths: Neo AI Agent vào thực tế

Tue, 13 Jan 2026 00:00:00 GMT

Các con số trong bài này phản ánh hệ thống tại thời điểm xuất bản (tháng 1/2026). Xem trang team của chúng tôi để biết số liệu hiện tại.

Các AI agent có năng lực đáng kinh ngạc. Chúng có thể suy luận, tổng hợp, và sinh ra nội dung. Nhưng chúng có một điểm yếu cơ bản: chúng bịa đặt. Không phải với ác ý, mà với sự tự tin. Một agent có thể bịa ra các tham số API không tồn tại, tham chiếu đến các cấu hình chưa từng được định nghĩa, hoặc áp dụng các mẫu từ dữ liệu huấn luyện của nó mâu thuẫn với kiến trúc thực tế của bạn.

Biện pháp giảm thiểu tiêu chuẩn là “cho agent thêm ngữ cảnh.” Nhưng ngữ cảnh có thể mâu thuẫn nhau. Tài liệu trôi dạt khỏi việc triển khai. Comment nói dối. Ngay cả mã nguồn cũng có thể gây hiểu lầm khi đọc mà không hiểu ý đồ.

Chúng tôi cần một thứ gì đó tường minh hơn. Một thứ không thể bị bỏ qua hoặc hiểu sai. Một thứ neo được các agent vào thực tế có thể kiểm chứng.

Chúng tôi gọi chúng là Ground Truth.

Ground Truth là gì?

Một Ground Truth là một phát biểu sự thật tường minh, có phiên bản, mà các agent phải tôn trọng. Đó không phải là tài liệu. Đó không phải là comment. Đó là một thực thể hạng nhất trong hệ thống, với:

Một định danh duy nhất (như GT-MAG-015 hoặc GT-MAG-036)
Một trạng thái vòng đời (current, tentative, hoặc deprecated)
Một phạm vi (toàn nền tảng, riêng cho package, hoặc gắn với domain)
Bằng chứng (đường dẫn file, URL, hoặc tham chiếu chứng minh phát biểu đó)
Hướng dẫn cho agent (chỉ dẫn nên làm/nên tránh tường minh)

Đây là một ví dụ từ nền tảng trí tuệ mã nguồn Maguyva của chúng tôi:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Đây không phải là văn xuôi. Đó là một hợp đồng. Khi một agent gặp Ground Truth này, nó biết:

Mặc định là tất định (kết quả rỗng, không phải phỏng đoán bằng so khớp gần đúng)
Có các tham số cụ thể (find_similar, exact_match) với hành vi đã được định nghĩa
Bằng chứng tồn tại trong các file cụ thể có thể được xác minh
Phát biểu này đã được xác minh vào một ngày cụ thể

Giải phẫu một Registry Ground Truth

Ground Truth sống trong các registry YAML dưới ai_assets/reference/ground_truths.yaml. Mỗi package hoặc domain có thể có registry riêng. Cấu trúc như sau:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Registry bao gồm metadata về chính bộ sưu tập đó, cấu hình render để sinh tài liệu, và bản thân các phát biểu. Mỗi phát biểu tuân theo một schema nghiêm ngặt được xác thực bởi các model Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Agent truy cập Ground Truth bằng cách nào

Ground Truth được cung cấp cho agent qua nhiều kênh:

1. Tài liệu đã render

Lệnh orkestra sync biến đổi các registry YAML thành markdown dễ đọc:

uv run orkestra sync

Điều này sinh ra các file GROUND_TRUTHS.md được đưa vào ngữ cảnh của agent. Đầu ra đã render nhóm các phát biểu theo trạng thái và danh mục:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Tìm kiếm qua CLI

Các agent có quyền truy cập shell có thể tìm kiếm Ground Truth theo lập trình:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

Hàm tìm kiếm chấm điểm các khớp trên nhiều trường với độ liên quan có trọng số:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Soạn ngữ cảnh (Context Composition)

Khi các agent được render từ định nghĩa YAML, ngữ cảnh của chúng có thể tham chiếu đến các registry Ground Truth:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Điều này đảm bảo các Ground Truth liên quan được nạp trước khi agent bắt đầu công việc.

Các loại Ground Truth

Nhìn qua các registry của chúng tôi, Ground Truth tập trung thành vài mẫu:

Nguyên tắc sản phẩm

Các ràng buộc về việc sản phẩm là gì và không phải là gì:

“Maguyva chỉ đọc (read-only) đối với các repo của người dùng; tài sản duy nhất không thể xây dựng lại được là cache embedding đã trả phí.” (GT-MAG-001)

Ranh giới kiến trúc

Trách nhiệm nằm ở đâu và tại sao:

“Ranh giới giữa Pipeline và Maguyva là có chủ đích: pipeline có thể tái sử dụng, Maguyva nắm giữ logic đặc thù cho mã nguồn, và CQRS tách các thao tác ghi do các giai đoạn pipeline thực hiện khỏi các thao tác đọc của server.” (GT-MAG-006)

Quy tắc chống ảo giác

Các chỉ thị tường minh giữ cho hợp đồng công cụ mang tính tất định thay vì suy luận:

“So khớp symbol mờ (fuzzy) là tùy chọn, kích hoạt qua find_similar=true. Hành vi mặc định trả về kết quả rỗng cho các symbol không tồn tại; exact_match=true ép buộc so khớp nghiêm ngặt và tắt mọi phương án dự phòng mờ.” (GT-MAG-015)

Kiểm tra chất lượng

Các tiêu chuẩn phải được duy trì:

“Các thay đổi đối với hạ tầng dùng chung (post_filters.py, các trình trích xuất quan hệ, các handler dùng chung) PHẢI được xác thực trên TẤT CẢ các ngôn ngữ được hỗ trợ thông qua việc sinh manifest đầy đủ trước khi commit. Xác thực trên một ngôn ngữ duy nhất là không đủ đối với mã dùng chung.” (GT-MAG-036)

Mẫu triển khai mã nguồn

Các yêu cầu triển khai:

“Dùng asyncio.to_thread() cho công việc nặng CPU trong ngữ cảnh async; mẫu loop.run_in_executor() đã lỗi thời không nên được dùng trong mã mới.” (GT-MAG-018)

Vòng đời của một Ground Truth

Ground Truth không tĩnh. Chúng tiến hóa qua một vòng đời được định nghĩa rõ ràng:

Tentative (Tạm thời)

Một sự thật được đề xuất, đang trong quá trình đánh giá. Phát biểu được ghi lại nhưng có thể thay đổi:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current (Hiện hành)

Một sự thật đã được xác minh mà các agent phải tôn trọng. Bằng chứng đã được xác thực:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated (Đã lỗi thời)

Một sự thật không còn áp dụng nữa. Được giữ lại để tham khảo lịch sử kèm con trỏ đến thứ đã thay thế nó:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Tại sao không chỉ dùng tài liệu?

Tài liệu phục vụ một mục đích khác. Nó giải thích. Nó dạy. Nó có thể mơ hồ, có thể dùng các từ định tính như “nhìn chung” hoặc “thường thì.”

Ground Truth không thể mơ hồ. Chúng là các khẳng định. Chúng hoặc áp dụng hoặc không.

Hãy xem xét sự khác biệt:

Tài liệu: “API nhìn chung trả về kết quả rỗng khi không tìm thấy symbol, mặc dù so khớp mờ có thể được bật trong một số cấu hình.”

Ground Truth: “Hành vi mặc định trả về kết quả rỗng cho các symbol không tồn tại; exact_match=true ép buộc so khớp nghiêm ngặt và tắt mọi phương án dự phòng mờ.”

Cái đầu tiên hữu ích cho con người khi học hệ thống. Cái thứ hai cho agent chỉ dẫn có thể áp dụng trực tiếp khi ra quyết định.

Hướng dẫn cho agent: Nên làm và nên tránh

Một số Ground Truth bao gồm hướng dẫn tường minh cho agent:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Điều này loại bỏ sự mơ hồ. Một agent đọc điều này biết không chỉ điều gì là đúng, mà còn biết sự thật đó ngụ ý hành động gì.

Xác minh và bảo trì

Ground Truth cần được bảo trì. Chúng tôi theo dõi:

last_verified: Khi nào ai đó xác nhận phát biểu vẫn còn đúng
evidence: Các file chứng minh phát biểu đó (có thể kiểm tra sự tồn tại)
source: Sự thật bắt nguồn từ đâu (kiểm tra qua CLI, rà soát kiến trúc, bài học sau sự cố)

Một Ground Truth với ngày xác minh đã cũ hoặc liên kết bằng chứng bị hỏng là một tín hiệu cần điều tra. Hoặc sự thật đó vẫn còn đúng và cần xác minh lại, hoặc thực tế đã thay đổi và sự thật đó cần được cập nhật.

Ví dụ thực tế từ môi trường production

Ranh giới bảo mật

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Ground Truth này ngăn chặn một nhóm các “cải tiến bảo mật” bị hiểu sai sẽ làm hỏng sản phẩm.

Độ chính xác tại thời điểm trích xuất

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Điều này đến từ một kinh nghiệm đau đớn. Các agent từng vá các gói ngôn ngữ đang lỗi bằng cách thêm các bộ lọc chỉ-dành-cho-validator khiến bộ kiểm thử trông xanh hơn, trong khi trình trích xuất Maguyva thực tế vẫn phát ra sai edge. Quy tắc này buộc các bản sửa phải quay lại đường thực: cấu hình YAML, truy vấn, hoặc handler.

Lọc đa tầng

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Điều này ngăn các agent thêm bộ lọc sai chỗ, một lỗi phổ biến từng gây ra hồi quy độ chính xác.

Tích hợp với hệ thống Orchestration

Ground Truth là một tầng trong một hệ thống ngữ cảnh rộng hơn:

Quyết định kiến trúc (ADR) - Ghi lại vì sao chúng tôi chọn phương án A thay vì B
Ground Truth - Phát biểu điều gì chắc chắn đúng ngay lúc này
Mẫu Domain - Mô tả cách làm đúng
Anti-Pattern - Mô tả điều cần tránh và tại sao

Một agent làm việc trong hệ thống có quyền truy cập cả bốn thứ này. Ground Truth cung cấp neo sự thật, trong khi các quyết định giải thích lịch sử, các mẫu hướng dẫn triển khai, và các anti-pattern cảnh báo về cạm bẫy.

Đo lường tác động

Kể từ khi đưa Ground Truth vào sử dụng, chúng tôi đã quan sát thấy:

Ít hơn các chu trình “sửa cái bản sửa bị ảo giác”
Việc ra quyết định của agent tự tin hơn khi sự thật đã rõ ràng
Rà soát PR tốt hơn vì kỳ vọng đã tường minh
Thời gian onboarding giảm cho cả agent mới (và con người)

Khoản đầu tư vào việc bảo trì Ground Truth mang lại lợi ích trong việc giảm debug và làm rõ ranh giới hệ thống.

Bắt đầu

Để thêm một Ground Truth vào hệ thống của bạn:

Tạo một ground_truths.yaml trong thư mục ai_assets/reference/ của package của bạn
Định nghĩa metadata và cấu hình render
Thêm các phát biểu tuân theo schema
Chạy uv run orkestra sync để sinh tài liệu
Đưa registry vào phần soạn ngữ cảnh của agent

Bắt đầu với những sự thật gây ra nhiều nhầm lẫn nhất hoặc những ràng buộc bị vi phạm thường xuyên nhất. Đó là những Ground Truth có giá trị cao nhất của bạn.

Kết luận

Các AI agent sẽ ảo giác. Đó là bản chất của chúng. Nhưng chúng ta có thể tạo ra những môi trường nơi ảo giác bị kiềm chế, nơi một số sự thật nhất định không thể thương lượng, nơi các agent có thể đối chiếu giả định của mình với thực tế đã được xác minh.

Ground Truth không phải là một giải pháp hoàn chỉnh. Chúng cần được bảo trì. Chúng có thể trở nên lỗi thời. Chúng thêm chi phí vào quy trình phát triển.

Nhưng chúng cung cấp một thứ có giá trị: một vốn từ vựng chung về sự thật mà cả con người và agent đều có thể tin tưởng. Trong một thế giới nơi agent ngày càng tham gia nhiều hơn vào việc phát triển phần mềm, nền tảng chung đó trở nên thiết yếu.

Phương án thay thế là những chu trình bất tận của việc agent mắc lỗi một cách tự tin và con người phải sửa lại chúng. Ground Truth phá vỡ chu trình đó bằng cách làm cho các bản sửa trở nên tường minh và bền vững.

Agent của bạn xứng đáng được biết điều gì là đúng. Hãy nói cho chúng biết.

Orkestra: Điều phối AI agent ở quy mô lớn

Tue, 06 Jan 2026 00:00:00 GMT

Các con số trong bài này phản ánh hệ thống tại thời điểm xuất bản (tháng 1/2026). Xem trang team của chúng tôi để biết số liệu hiện tại.

Khi chúng tôi bắt đầu xây dựng với Claude Code, chúng tôi gặp phải một vấn đề mà mọi đội dùng trợ lý lập trình AI cuối cùng đều gặp phải: một agent đơn lẻ không thể làm tốt mọi thứ.

Bạn có thể prompt một agent để nó trở thành chuyên gia database. Hoặc một kiểm toán viên bảo mật. Hoặc một kỹ sư frontend. Nhưng ngay khi bạn yêu cầu nó làm cả ba việc cùng lúc, chất lượng sẽ giảm sút. Ngữ cảnh bị pha loãng. Các chỉ dẫn mâu thuẫn nhau. Agent trở thành một người làm được mọi thứ nhưng chỉ ở mức tầm thường.

Vì vậy chúng tôi đã xây dựng Orkestra.

Orkestra là gì?

Orkestra là một hệ thống điều phối agent dành cho Claude Code và các công cụ lập trình AI tương tự. Nó điều phối nhiều agent chuyên biệt, mỗi agent có chuyên môn riêng, dưới một orchestrator duy nhất định tuyến công việc đến đúng chuyên gia.

Hãy hình dung nó như một công ty cung ứng nhân sự cho AI agent. Orchestrator nhận một tác vụ, xác định chuyên gia nào nên xử lý nó, và ủy quyền kèm đúng ngữ cảnh. Khi công việc hoàn tất, kết quả chảy trở lại orchestrator để tổng hợp.

Các con số nói lên tất cả:

Thành phần	Số lượng
Agent chuyên biệt	46
Skill có thể tái sử dụng	466
Nguyên mẫu định danh (identity archetype)	27
Mindset	11
Phong cách giao tiếp	10
Domain tri thức	21

Hệ thống nhân vật: D&D dành cho Agent

Insight cốt lõi đằng sau Orkestra là hành vi của agent nổi lên từ ba thành phần cơ bản có thể kết hợp:

Identity (Định danh) định nghĩa agent là gì. Một architect thiết kế cấu trúc hệ thống. Một debugger truy vết lỗi về tận gốc rễ. Một guardian thực thi tuân thủ và ranh giới bảo mật. Chúng tôi có 27 nguyên mẫu định danh có thể pha trộn.

Mindset định nghĩa agent suy nghĩ như thế nào. Một mindset phân tích neo các khẳng định vào bằng chứng và định lượng sự bất định. Một mindset hoài nghi đặt câu hỏi về các giả định và tìm kiếm bằng chứng phản bác. Một mindset khám phá chấp nhận sự mơ hồ và thử nhiều cách tiếp cận.

Style (Phong cách) định nghĩa agent giao tiếp như thế nào. Một phong cách kỹ thuật bao gồm các giá trị chính xác và tham chiếu đến các file cụ thể. Một phong cách súc tích cắt bỏ lời thừa và đi thẳng vào câu trả lời. Một phong cách ngoại giao cân bằng giữa sự thành thật và sự khéo léo.

Một agent kết hợp các thành phần này:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Sự kết hợp này tạo ra một agent thiết kế hệ thống (architect), kết nối tri thức xuyên các domain (knowledge-architect), đặt ra định hướng chiến lược (strategist), suy nghĩ dựa trên bằng chứng và dữ liệu (analytical), và giao tiếp không lời thừa (concise).

Sức mạnh nằm ở sự bùng nổ tổ hợp. 27 identity nhân với 11 mindset nhân với 10 style cho ra gần 3.000 tính cách agent khả dĩ. Nhưng bạn chỉ cần định nghĩa những tổ hợp thực sự quan trọng cho công việc của mình.

Skill: Các module năng lực có thể tái sử dụng

Skill là tri thức và quy trình mà agent có thể gọi đến. Chúng tuân theo một hệ thống phân tầng dựa trên phạm vi:

Tầng	Tên	Phạm vi	Ví dụ
K0	Foundations	Phương pháp luận phổ quát	Kỷ luật test-first, hoàn thành dựa trên bằng chứng
K1	Identities	Quy trình theo vai trò	Tiêu chuẩn giao diện CLI, playbook hiệu năng
K2	Domains	Tri thức đặc thù domain	Mẫu di trú database, xác thực authentication
K3	Stacks	Đặc thù công nghệ	Triển khai Cloudflare, vận hành Supabase
K4	Project	Chỉ riêng codebase này	Quy trình và quy ước đặc thù dự án

Skill được nạp khi cần (lazy-loaded). Một agent thấy tên và mô tả skill lúc khởi động, nhưng toàn bộ nội dung skill chỉ được nạp khi được kích hoạt. Điều này giữ ngữ cảnh gọn nhẹ trong khi vẫn cho phép hàng trăm skill có thể được khám phá.

Mỗi skill bao gồm:

Điều kiện kích hoạt rõ ràng (“Dùng khi di trú schema database”)
Hướng dẫn từng bước
Các công cụ được phép cho quy trình
Tiêu chí thành công và các đường khôi phục khi thất bại

466 skill trong registry của chúng tôi bao phủ mọi thứ từ cách ly worktree git đến các quy trình nghiên cứu web cho đến xác thực sức khỏe triển khai.

Vì sao điều phối quan trọng

Kiến trúc agent đơn lẻ nhanh chóng đụng tường:

Pha loãng ngữ cảnh. Một cửa sổ ngữ cảnh 200k token nghe có vẻ lớn cho đến khi bạn nạp schema database, tài liệu API, fixture test, và tri thức domain. Các chuyên gia có thể làm việc với ngữ cảnh nhắm mục tiêu.

Chỉ dẫn mâu thuẫn. Bảo một agent “kỹ lưỡng nhưng nhanh” và “xác minh mọi thứ nhưng đừng thiết kế quá mức” tạo ra căng thẳng. Các chuyên gia giải quyết điều này bằng cách có phạm vi rõ ràng.

Chiều sâu chuyên môn. Một agent tổng quát biết một chút về mọi thứ. Một agent chuyên biệt, được cấu thành với đúng identity và skill, hiểu sâu domain của nó.

Orkestra triển khai điều phối phẳng: một orchestrator điều phối nhiều chuyên gia. Các chuyên gia không thể sinh ra các chuyên gia con. Điều này ngăn chặn sự bùng nổ độ phức tạp trong khi vẫn cho phép làm việc song song.

Orchestrator có quyền truy cập vào 2,2 triệu token dung lượng hiệu dụng: cửa sổ 200k của riêng nó cộng với 10 subagent đồng thời, mỗi subagent 200k. Công việc có thể làm cạn kiệt một agent đơn lẻ chạy thoải mái trên toàn bộ đội quân.

Pipeline Render

Các định nghĩa agent sống trong YAML. Claude Code đọc Markdown. Orkestra bắc cầu qua khoảng trống này bằng một pipeline render mang tính tất định:

YAML Registries → Jinja Templates → .claude/agents/*.md

Người vận hành chỉnh sửa mã nguồn YAML. Chạy orkestra sync. Markdown đã render xuất hiện trong .claude/agents/. Claude Code tiếp nhận các thay đổi.

Sự tách biệt này phục vụ các đối tượng khác nhau:

Mã nguồn YAML bao gồm metadata vòng đời, tag, quy tắc xác thực, và ghi chú lỗi thời cho công cụ
Markdown đã render chỉ bao gồm những gì mô hình cần: mô tả, công cụ, skill, và hướng dẫn hành vi

Pipeline này ghép identity, mindset, style, và skill thành một prompt mạch lạc duy nhất. Một agent architect-analytical-concise nhận được một system prompt rất khác so với một agent debugger-skeptical-technical, ngay cả khi chúng chia sẻ một số skill nền tảng.

Tri thức Domain: Mẫu bốn file

Mỗi domain tri thức tuân theo một cấu trúc nhất quán:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Cấu trúc này phục vụ việc nạp ngữ cảnh của agent. Một agent làm việc về authentication nạp authentication/patterns.md để lấy hướng dẫn và authentication/anti-patterns.md để tránh những cạm bẫy đã biết. Độ dài các file được điều chỉnh để nạp ngữ cảnh hiệu quả: đủ tập trung để hữu ích, đủ toàn diện để làm tài liệu tham chiếu đáng tin cậy.

Chúng tôi duy trì 21 domain cấp cao nhất bao gồm phân tích, authentication, khoa học dữ liệu, hạ tầng, machine learning, hiệu năng, bảo mật, và nhiều hơn nữa. Mỗi domain có thể có các sub-domain để phân chia chi tiết hơn.

Giá trị: Hệ điều hành

Mọi agent đều chia sẻ một tầng giá trị nền tảng định nghĩa cách chúng vận hành:

Đơn giản trước tiên. Dùng giải pháp đơn giản nhất còn hoạt động được. Chỉ thêm độ phức tạp khi có lý do chính đáng.

Sửa nguyên nhân gốc rễ. Không bao giờ vá lỗi theo kiểu né tránh nguyên nhân gốc rễ. Nếu một pipeline lỗi, hãy debug pipeline. Nếu một test lỗi, hãy sửa mã hoặc sửa test.

Dựa trên bằng chứng. Gắn nhãn các khẳng định là “đã xác minh” (kèm benchmark) hoặc “ước tính” (kèm giả định). Phát hiện một mẫu không đồng nghĩa với xác nhận một vấn đề.

Kinh tế học ngữ cảnh. Công cụ MCP tốn 0,1% ngữ cảnh. Mỗi lượt đọc file tốn 2%. Áp dụng chuyên môn domain trước khi khám phá mã.

Những giá trị này lan tỏa đến mọi chuyên gia thông qua pipeline render. Một agent không thể bỏ qua chúng bằng cách cấu thành khác đi.

CLI: Mặt phẳng điều khiển

Orkestra đi kèm một CLI để quản lý hệ sinh thái agent:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI là nguồn chân lý duy nhất cho việc những agent nào tồn tại, chúng có những skill nào, và liệu hệ thống có khỏe mạnh hay không. Nó chạy xác thực trước khi đồng bộ để bắt lỗi sớm.

Cân nhắc về mã nguồn mở

Chúng tôi xây dựng Orkestra để giải quyết vấn đề của chính mình: điều phối AI agent ở quy mô lớn cho một codebase phức tạp. Các mẫu chúng tôi khám phá ra không đặc thù riêng cho domain của chúng tôi.

Hệ thống cấu thành nhân vật (identity + mindset + style) áp dụng được cho bất kỳ đội nào định nghĩa tính cách agent.

Hệ thống tầng skill (K0-K4) cung cấp một mô hình tư duy để tổ chức các năng lực có thể tái sử dụng theo phạm vi.

Mẫu pipeline render (mã nguồn YAML + template + tài sản đã sinh) tách biệt nhu cầu của công cụ với nội dung dành cho mô hình.

Mô hình điều phối phẳng (một điều phối viên, nhiều chuyên gia) tránh được độ phức tạp trong khi vẫn cho phép song song hóa.

Liệu Orkestra có trở thành mã nguồn mở hay không phụ thuộc vào việc những mẫu này có giá trị cho những người khác đang xây dựng với Claude Code hay không. Nếu bạn đang đụng phải những bức tường chúng tôi đã mô tả, kiến trúc này có thể giúp ích.

Những gì chúng tôi đã học được

Xây dựng Orkestra dạy chúng tôi rằng điều phối không phải là làm cho agent thông minh hơn. Đó là làm cho chúng tập trung hơn.

Một agent đơn lẻ với chỉ dẫn hoàn hảo vẫn cạn ngữ cảnh. Một agent đơn lẻ với tất cả các skill vẫn bối rối về việc nên áp dụng cái nào. Một agent đơn lẻ cố gắng làm mọi thứ tạo ra kết quả tầm thường ở mọi nơi.

Bốn mươi chuyên gia, mỗi người xuất sắc trong domain của mình, được điều phối bởi một orchestrator biết khi nào nên ủy quyền: đó là cách chúng tôi lên sóng.

Các con số ít quan trọng hơn kiến trúc. Bạn có thể cần năm agent hoặc năm mươi agent. Nguyên tắc vẫn giữ nguyên: cấu thành hơn là năng lực đơn lẻ, chuyên môn hóa hơn là tổng quát hóa, điều phối hơn là chủ nghĩa anh hùng cá nhân.

Orkestra vận hành hệ sinh thái agent đằng sau Maguyva, nền tảng trí tuệ mã nguồn của chúng tôi. Muốn tìm hiểu thêm? Hãy liên hệ với đội của chúng tôi.