Ra mắt Reladraw 0.5.0: Ngôn ngữ vẽ biểu đồ bằng văn bản dựa trên vị trí tương đối

Một ngôn ngữ văn bản dành cho sơ đồ, nơi bạn xác định vị trí của các thành phần.

Thử nghiệm trên trình duyệt của bạn → — chỉnh sửa mã nguồn ở bên trái, xem bố cục tự động giải quyết ở bên phải. Không cần cài đặt gì cả.

Một sơ đồ được vẽ thủ công trong draw.io:

Và cùng sơ đồ đó được viết bằng reladraw và kết xuất từ văn bản — examples/arch.reladraw, 44 câu lệnh, không hề có tọa độ nào trong đó:

Mọi khoảng cách trong hình thứ hai đều được tính toán từ các câu lệnh như "phía trên bên trái của cluster.hub" và "giữa cluster.desktop1 và cluster.laptop1". Không có gì tự chọn cách sắp xếp cả; tệp tin đã quy định điều đó.

Khoảng cách (The gap)

Mermaid, Graphviz và D2 yêu cầu bạn khai báo các thực thể và kết nối, sau đó tự động đặt mọi thứ cho bạn. Đó là một siêu năng lực, và đối với hầu hết các sơ đồ, đó là lựa chọn đúng đắn. Nó chỉ không còn đúng nữa ngay khi bạn có một hình ảnh cụ thể trong đầu và quan tâm đến vị trí của các thành phần. Giả sử bạn đang tích cực xây dựng sự hiểu biết về một hệ thống bằng cách vẽ sơ đồ, và bạn muốn một module nào đó nằm ở phía bên phải với các kết nối được đặt chính xác tại đó: các ngôn ngữ tự động bố cục không có cách nào để thực hiện điều này.

Ở phía đối diện của phổ là các công cụ định vị tuyệt đối — draw.io, Excalidraw, Figma. Chúng cho bạn toàn quyền kiểm soát vị trí, nhưng phải đánh đổi bằng việc mỗi lần chỉnh sửa một sơ đồ phức tạp đều là công việc thủ công chậm chạp. Nó chậm đối với con người nhưng lại tốn kém đối với một tác nhân (agent), vì nó phải giải mã bức tranh từ các tọa độ trước khi có thể quyết định thay đổi tọa độ nào.

reladraw nhắm đến điểm cân bằng ở giữa. Mọi vị trí đều được xác định tương đối so với các thành phần khác, và không có gì trong tệp tin là tọa độ:

node app "Web app"
node app.ui  "Interface"
node app.api "API"  below app.ui

node store "Database"  right of app  level with app

edge app.api -> store  "queries"  from: right  to: left

Không có cấu trúc lồng nhau, vì vậy không có dòng nào phụ thuộc vào vị trí hoặc thụt lề của dòng khác.

Bản nháp nằm trong SYNTAX.md, với ví dụ thực tế trong examples/.

Tại sao một tác nhân (agent) cần điều này

Trường hợp phổ biến không phải là vẽ một sơ đồ, mà là thay đổi nó. Yêu cầu dịch vụ xác thực (auth service) di chuyển sang trái và một hàng đợi (queue) đi ra phía sau nó. Với tọa độ pixel, một tác nhân phải xây dựng lại bức tranh từ các con số trước khi có thể tính toán xem cần thay đổi con số nào. Với tự động bố cục, không có gì để đọc cả, vì cách sắp xếp chưa bao giờ được ghi lại — nó chỉ có thể diễn đạt lại nguồn và kết xuất lại. Với vị trí được xác định, cách sắp xếp nằm trong tệp tin dưới dạng các câu văn, và việc thay đổi bức tranh chính là thay đổi câu văn mô tả vị trí của thành phần đó.

Việc viết mã cũng tương tự. Một tác nhân xuất ra Mermaid đang đoán một bố cục mà thuật toán sẽ quyết định sau đó, và cách duy nhất để nó kiểm tra là kết xuất và quan sát — một quy trình khép kín trả về kết quả là một bức tranh thay vì một danh sách những gì chưa đúng.

Ý định là thứ có thể xác nhận, còn kết quả thì không, và sự khác biệt này cần được làm rõ. Một tác nhân có thể đọc lại tệp của chính nó và thấy rằng cơ sở dữ liệu nằm dưới API và cả bốn máy đều treo trên hub đồng bộ. Nó không thể thấy rằng hai cụm (cluster) được neo vào các vị trí khác nhau hiện đang chồng chéo lên nhau, rằng một đoạn văn bản bị tràn khỏi node của nó, hoặc một đường nối cắt ngang bốn đường khác — những lỗi đó được giải quyết từ các câu lệnh thay vì được quy định, vì vậy chúng cần các chẩn đoán trong phần phạm vi bên dưới.

Sử dụng với một tác nhân (agent)

reladraw còn quá mới để có trong dữ liệu huấn luyện của bất kỳ mô hình nào, vì vậy một tác nhân cần được hướng dẫn về ngôn ngữ này trước khi có thể viết nó. Kho lưu trữ này cung cấp một kỹ năng tác nhân (agent skill) thực hiện chính xác điều đó — cú pháp, khi nào nên sử dụng ngôn ngữ này, và việc đọc lại nguồn của chính nó có thể và không thể xác nhận những gì.

npx skills add reladraw/reladraw -g

Lệnh đó cài đặt nó cho bất kỳ tác nhân nào bạn sử dụng — Claude Code, Codex, Cursor, Copilot và các loại khác — mỗi loại vào thư mục kỹ năng riêng của nó. Bỏ cờ -g để cài đặt vào dự án hiện tại thay vì cài đặt toàn cục.

Để cài đặt cho một tác nhân cụ thể thay vì tất cả, hãy đặt tên nó với -a:

npx skills add reladraw/reladraw -g -a claude-code

Hãy chạy lại bất kỳ lệnh nào bạn đã sử dụng sau mỗi bản phát hành có thay đổi cú pháp. Kỹ năng này là một bản sao được lấy tại thời điểm cài đặt, không phải là liên kết trực tiếp, vì vậy không có gì tự động làm mới nó.

Đó là Markdown thuần túy với tài liệu tham khảo cú pháp bên cạnh, vì vậy rất đáng để đọc bất kể bạn sử dụng công cụ nào, và việc sao chép thư mục thủ công cũng hiệu quả tương tự.

Trạng thái

Phiên bản 0.5.0. Còn sớm, nhưng nó đã chạy được: một trình phân tích cú pháp, trình giải quyết và trình kết xuất SVG bằng TypeScript không phụ thuộc vào runtime, và một công cụ dòng lệnh nhận tệp văn bản và xuất ra tệp SVG độc lập. Sự so sánh ở đầu trang này là kết quả của quy trình đó chạy trên examples/arch.reladraw. Điều vẫn còn hiển thị chưa ổn ở đó là kiểu chữ, không phải vị trí.

npm install -g reladraw
reladraw diagram.reladraw -o diagram.svg

Hoặc từ bản clone, bản này cũng cung cấp cho bạn các ví dụ:

npm install && npm run build
node dist/cli.js examples/arch.reladraw -o out.svg

Chưa được xây dựng, sắp xếp theo thứ tự ưu tiên:

• Báo cáo chẩn đoán. Phần phạm vi bên dưới cho biết nó dùng để làm gì. Hiện tại, công cụ chỉ kết xuất hoặc thất bại; nó sẽ không cho bạn biết điều gì sai với một bức tranh mà nó đã vẽ thành công.
• Định tuyến đường nối (Edge routing) xung quanh các node. Một đường nối có thể được chỉ định rời khỏi và đi đến phía nào của một node, và đi qua khoảng trống nào trên đường đi. Một đường nối không được chỉ định các thông tin đó sẽ là một đường thẳng giữa hai tâm, và nó sẽ cắt xuyên qua bất cứ thứ gì cản đường.
• Thêm hình ảnh. Các biểu tượng và hình dạng là các tập hợp đóng được vẽ từ dữ liệu đường dẫn (path data) bên trong công cụ, vì vậy một sơ đồ cần một hình không có sẵn sẽ không có cách nào để thực hiện.

Ngôn ngữ chưa ổn định. Hãy dự đoán cú pháp sẽ thay đổi.

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

Khoảng cách (gap) là khoảng cách tối thiểu, không bao giờ là khoảng cách chính xác. Giả sử hai thứ nằm cạnh nhau, sau đó thêm một thứ thứ ba vào giữa chúng, hai thứ đầu tiên sẽ bị đẩy ra xa đúng bằng khoảng cách mà thứ thứ ba cần; xóa thứ thứ ba đi và chúng sẽ khép lại như cũ. Đó là bước mà tác giả thường phải làm thủ công — đẩy các thứ ra xa để tạo chỗ trống, sau đó kéo mọi thứ lại để sơ đồ không bị lỗ hổng — và không có con số nào bị lỗi thời khi văn bản phát triển.

Vì vậy, trình giải quyết giải quyết một hệ thống thay vì đi theo một chuỗi. Mỗi trục là một tập hợp các khoảng cách tối thiểu, và cách sắp xếp chặt chẽ nhất thỏa mãn tất cả chúng được tìm thấy bằng các đường đi dài nhất: một câu trả lời duy nhất, không tìm kiếm, không có cách sắp xếp nào bị thử nghiệm rồi loại bỏ. Công cụ tính toán các khoảng cách; còn việc một thứ nằm ở phía nào của thứ khác là do tệp tin quy định.

Đó cũng là điều làm cho việc chống chồng chéo trở nên khả thi, vì nó áp dụng cho mọi cặp node mà không cần ai phải viết ra. Bản thân việc "hai thứ này không được chồng chéo" là một lựa chọn trong bốn hướng, đây là kiểu tìm kiếm mà thiết kế này từ chối — nhưng tệp tin thường đã giải quyết xong việc đó: nếu cách sắp xếp của bạn cho phép một node di chuyển ra xa node khác mà không có đường quay lại, đó là sự tách biệt duy nhất mà nó cho phép. Ở nơi tệp tin không ra lệnh cho một cặp trên cả hai trục, công cụ sẽ đặt tên cho chúng thay vì đoán; ở nơi nó ra lệnh trên cả hai trục, sự ưu tiên sẽ nghiêng về trục có độ chồng chéo ít nhất, đó là sự di chuyển nhỏ nhất và là nơi duy nhất công cụ tự quyết định điều gì đó mà không ai viết ra.

Bài gốc còn tiếp — xem tiếp tại bài gốc ↗