json-canvas

Tổng quan về skill json-canvas

skill json-canvas làm được gì

Skill json-canvas giúp agent tạo mới hoặc chỉnh sửa các tệp .canvas hợp lệ theo định dạng JSON Canvas mà Obsidian và các công cụ vẽ sơ đồ tương tự sử dụng. Giá trị thực sự của skill này không nằm ở việc “vẽ cho đẹp”, mà là “tạo ra JSON canvas đúng cấu trúc với nodes, edges, groups, vị trí, kích thước và thứ tự lớp để ứng dụng canvas có thể mở được.”

Ai nên cài json-canvas

json-canvas skill phù hợp nhất với những người đã biết mình muốn đặt nội dung gì lên board nhưng không muốn tự viết schema bằng tay. Nó đặc biệt hợp với ghi chú, mind map, flowchart, phác thảo kiến trúc, research board và các quy trình vẽ sơ đồ gọn nhẹ, nơi đầu ra bắt buộc phải là một tệp .canvas thực thụ chứ không phải một đoạn mô tả bằng văn bản.

Vì sao tốt hơn một prompt chung chung

Một prompt thông thường thường tạo ra định dạng “gần đúng”, nhưng lại thiếu trường bắt buộc, sai loại node hoặc lệch cấu trúc mảng. json-canvas hữu ích vì nó bám sát object model của JSON Canvas: nodes và edges ở cấp cao nhất, bốn loại node (text, file, link, group), cùng các chi tiết thực tế như z-order phụ thuộc vào thứ tự phần tử trong mảng node. Nhờ vậy, bạn giảm đáng kể khâu dọn dẹp nếu mục tiêu là vẽ sơ đồ trong Obsidian thay vì chỉ sinh ra JSON minh họa.

Cách dùng skill json-canvas

Bối cảnh cài đặt và khi nào nên gọi json-canvas

Nếu nền tảng agent của bạn hỗ trợ GitHub skills, hãy thêm json-canvas từ MarsWang42/OrbitOS bằng quy trình cài skill thông thường. Dấu vết trong repository hiện chỉ cho thấy có SKILL.md, vì vậy hãy kỳ vọng đây là một skill gọn, tập trung vào hướng dẫn định dạng hơn là có script hỗ trợ hay validator đi kèm. Hãy gọi skill này khi tác vụ nêu rõ .canvas, JSON Canvas, Obsidian Canvas hoặc yêu cầu vẽ sơ đồ trực quan mà đầu ra cuối cùng phải là canvas JSON có thể chỉnh sửa.

Đầu vào nào giúp json-canvas phát huy tốt nhất

Skill hoạt động tốt nhất khi bạn cung cấp ý đồ sơ đồ, không chỉ nêu chủ đề. Một đầu vào tốt thường bao gồm:

• danh sách node hoặc các phần cần thể hiện
• quan hệ giữa các node
• loại node mong muốn: text, file, link, group
• hướng bố cục sơ bộ: trái sang phải, trên xuống dưới, theo cụm
• có muốn group bao các node liên quan theo trực quan hay không
• tham chiếu tệp hoặc URL nếu dùng node file hoặc link

Một prompt yếu: “Make a canvas for my project.”
Một prompt tốt hơn: “Create a .canvas for a project roadmap with three groups: planning, build, launch. Use text nodes for tasks, link nodes for docs URLs, connect task dependencies with edges, and arrange groups left to right.”

Cách biến một mục tiêu mơ hồ thành prompt dùng được cho json-canvas

Để json-canvas cho kết quả ổn định, hãy mô tả cả nội dung lẫn cấu trúc. Một mẫu prompt thực tế là:

1. Xác định mục đích của board.
2. Liệt kê các nhóm node.
3. Nêu các edge chính.
4. Đưa ra quy tắc bố cục.
5. Yêu cầu chỉ trả về .canvas JSON hợp lệ.

Ví dụ:
“Use the json-canvas skill to generate valid .canvas JSON for diagramming a hiring pipeline. Include groups for sourcing, screening, interview, and offer. Add text nodes for each stage, link nodes for ATS and policy docs, and edges showing candidate flow. Keep nodes spaced for readability and place groups in process order.”

Nên đọc gì trước và mẹo quy trình làm việc

Hãy đọc EN/.agents/skills/json-canvas/SKILL.md trước tiên. Tập trung vào:

• cấu trúc tệp ở cấp cao nhất
• các loại node và trường bắt buộc
• cách biểu diễn edge
• thứ tự z-index thông qua vị trí trong mảng node

Quy trình thực tế:

1. Phác danh sách node trước.
2. Tạo một canvas tối giản.
3. Mở nó trong ứng dụng canvas của bạn.
4. Chỉnh lại bố cục, group hoặc các liên kết còn thiếu ở lượt hai.

Cách này hiệu quả hơn việc yêu cầu một board hoàn chỉnh ngay từ đầu, vì tính đúng định dạng dễ kiểm tra hơn trước khi bạn tinh chỉnh phần hiển thị.

Câu hỏi thường gặp về skill json-canvas

json-canvas chỉ dùng để vẽ sơ đồ trong Obsidian thôi sao?

Không. json-canvas for Diagramming phù hợp với bất kỳ nơi nào ứng dụng đích đọc được chuẩn JSON Canvas. Obsidian là trường hợp dễ nghĩ tới nhất, nhưng giá trị cốt lõi nằm ở việc sinh .canvas theo chuẩn, chứ không phải mẹo định dạng riêng cho Obsidian.

Có tốt hơn việc nhờ LLM viết JSON trực tiếp không?

Thường là có, nếu đầu ra của bạn bắt buộc phải mở sạch sẽ. Prompt chung vẫn có thể dùng được cho ví dụ rất nhỏ, nhưng skill này giúp mô hình bám chặt hơn vào schema canvas thực tế và ngữ nghĩa của từng loại node. Điều đó đặc biệt quan trọng khi bạn có nhiều loại node, vùng group hoặc nhiều edge.

json-canvas có phù hợp cho người mới không?

Có, miễn là bạn hiểu board mình muốn gì. Bạn không cần biết sâu về spec, nhưng vẫn phải mô tả rõ các thực thể và quan hệ. Nếu bạn còn chưa liệt kê được node hoặc luồng, skill vẫn có thể tạo ra kết quả, nhưng khả năng cao bạn sẽ phải sửa tay khá nhiều.

Khi nào không nên dùng skill json-canvas?

Hãy bỏ qua nó nếu bạn chỉ cần ảnh tĩnh, sơ đồ Mermaid, export từ Excalidraw hoặc một dàn ý văn bản đơn giản. Nó cũng không phải lựa chọn tốt nếu sơ đồ của bạn phụ thuộc vào hành vi nâng cao riêng của một ứng dụng mà định dạng JSON Canvas cơ bản không biểu diễn được.

Cách cải thiện skill json-canvas

Hãy đưa cho model một kế hoạch board, đừng chỉ nêu chủ đề

Mức tăng chất lượng lớn nhất đến từ việc chỉ rõ node và edge. Thay vì “make a system architecture canvas”, hãy cung cấp:

• các dịch vụ
• các phụ thuộc
• các liên kết bên ngoài
• logic nhóm
• thứ tự đọc mong muốn

Cách này cải thiện cả độ hợp lệ lẫn quyết định bố cục, đồng thời khiến json-canvas guide hữu ích hơn trong thực tế.

Tránh các lỗi thường gặp của json-canvas

Các vấn đề phổ biến nhất là thiếu thuộc tính bắt buộc, group mơ hồ và bố cục khó đọc. Để giảm các lỗi này:

• yêu cầu chỉ trả về .canvas JSON hợp lệ
• yêu cầu node ID là duy nhất
• chỉ rõ hướng canvas gần đúng
• tách riêng các edge “bắt buộc phải nối” khỏi các liên kết trực quan tùy chọn
• nói rõ nếu group cần bao các node theo không gian

Nếu board mở được nhưng trông sai, có thể cấu trúc vẫn hợp lệ nhưng phần định vị đang kém.

Lặp theo hai lượt để có đầu ra tốt hơn với json-canvas

Một quyết định json-canvas install tốt thường phụ thuộc vào việc skill có hỗ trợ lặp nhanh hay không. Ở đây là có, nếu bạn dùng theo từng giai đoạn:

• lượt 1: nodes và edges đúng schema
• lượt 2: tinh chỉnh tọa độ, chiều rộng, chiều cao và groups
• lượt 3: sắp lại thứ tự node nếu chồng lớp trực quan là yếu tố quan trọng

Vì thứ tự trong mảng node ảnh hưởng đến z-index, hãy nói rõ khi bạn muốn group nằm sau nội dung hoặc nhãn nằm phía trên.

Nên yêu cầu gì sau bản nháp đầu tiên của json-canvas

Sau khi tạo bản đầu tiên, hãy cải thiện kết quả bằng các chỉnh sửa có mục tiêu:

• “Convert these URLs to link nodes.”
• “Wrap these five nodes in a group node.”
• “Reposition nodes to reduce edge crossings.”
• “Keep the same IDs but add missing dependency edges.”
• “Put groups on lower z-index than text nodes.”

Kiểu follow-up có ràng buộc như vậy thường cho kết quả tốt hơn việc sinh lại toàn bộ board từ đầu.