Đồ thị mã nguồn và kho kiến thức

Đồ thị mã nguồn là tính năng thử nghiệm. Giao diện, định dạng dữ liệu và cách lập chỉ mục có thể thay đổi trong các phiên bản sau.

Đồ thị mã nguồn dùng CodeGraph để phân tích các ký hiệu trong một dự án và quan hệ giữa chúng. Kho kiến thức theo phiên lưu các quyết định thiết kế, ràng buộc và bài học rút ra. Tham chiếu mã nguồn kết nối hai phần này, giúp bạn thấy được cả cấu trúc hiện tại của mã lẫn lý do đằng sau cấu trúc đó.

Các trang

Đồ thị mã nguồn mở dưới dạng hộp thoại với các thẻ “Tổng quan”, “Ký hiệu”, “Khám phá mã” và “Tệp”. Nút “Kho kiến thức” trong hộp thoại mở kho kiến thức.

Tổng quan: số tệp, số ký hiệu và số quan hệ, phân bố ngôn ngữ và loại ký hiệu, cùng trạng thái đồng bộ (“Đang đồng bộ tự động” hoặc “Đồng bộ trước khi truy vấn”). Nhấp vào một mục trong phần phân bố để xem các kết quả tương ứng.
Ký hiệu: tìm theo tên hoặc đường dẫn tệp (“Tìm ký hiệu hoặc đường dẫn tệp…”). Trang của một ký hiệu hiển thị mã nguồn có tô sáng cú pháp cùng “Quan hệ đi vào” và “Quan hệ đi ra”, được nhóm theo loại quan hệ và theo tệp. Các quan hệ do quá trình phân tích suy ra được đánh dấu “Quan hệ suy luận”, và nhấp vào số dòng sẽ chuyển tới vị trí của lời gọi.
Khám phá mã: mô tả một chức năng hoặc một luồng xử lý, hoặc nêu tên một tệp hay ký hiệu, để xem mã nguồn và các quan hệ liên quan. Truy vấn này chạy cục bộ và không dùng mô hình AI.
Tệp: duyệt các tệp đã được lập chỉ mục; nhấp vào một tệp để liệt kê các ký hiệu của tệp đó.
Ký hiệu gọi và Ký hiệu được gọi: trên trang của một ký hiệu, hiển thị nhiều cấp lời gọi. “Độ sâu duyệt” mặc định là 3 và tối đa là 6. Tối đa 500 kết quả được hiển thị; khi có nhiều hơn, tổng số kết quả và một thông báo sẽ xuất hiện.
Phân tích tác động: trên trang của một ký hiệu, hiển thị các ký hiệu và tệp có thể bị ảnh hưởng bởi một thay đổi, đến độ sâu đã chọn (mặc định 3, tối đa 6). Tối đa 500 ký hiệu và 2.000 quan hệ được hiển thị, kèm tổng số và một thông báo khi kết quả bị cắt bớt.
Đường gọi: trên trang của một ký hiệu, tìm một ký hiệu đích (“Tìm ký hiệu đích…”) để xem đường ngắn nhất theo các quan hệ gọi. Thông báo “Không tìm thấy đường gọi có hướng trong chỉ mục.” chỉ có nghĩa là chỉ mục không chứa đường gọi như vậy.

Chuyển thư mục làm việc từ menu thư mục; menu này cũng hiển thị đường dẫn đầy đủ. Trang, câu hỏi trong Khám phá mã, ký hiệu, độ sâu, đích và dòng mã nguồn đều nằm trong URL, nên bạn có thể làm mới trang, mở trang trong thẻ mới hoặc dùng nút lùi và tiến của trình duyệt. Liên kết hoạt động trên cùng máy chủ khi bạn có phiên đăng nhập hợp lệ.

Bật chỉ mục cho dự án

Nhấp chuột phải vào một dự án hoặc bộ sưu tập trong thanh bên và chọn “Thử nghiệm” → “Đồ thị mã nguồn”.
Ở lần đầu tiên, nhấp “Tải CodeGraph”. Máy chủ bạn đang kết nối sẽ tải bản phát hành CodeGraph 1.6.0 cố định từ GitHub và đối chiếu với giá trị kiểm tra SHA-256 tích hợp sẵn (thông báo “Giá trị kiểm tra của tệp tải về không khớp. Bộ chạy chưa được cài đặt.” nghĩa là bước kiểm tra đã thất bại). Không cần cài Node.js riêng.
Chọn “Thư mục làm việc” và nhấp “Bật lập chỉ mục”. Thư mục dự án và các thư mục làm việc khác mà các phiên và nhóm của dự án sử dụng được liệt kê riêng; mỗi Git worktree có chỉ mục riêng. Một bộ sưu tập cần ít nhất một phiên có thư mục làm việc hợp lệ.
Chờ đến khi trạng thái là “Sẵn sàng”, rồi tìm ký hiệu hoặc đường dẫn tệp. Quá trình lập chỉ mục chạy ở nền (“Tác vụ lập chỉ mục đang chạy. Bạn có thể đóng trang này hoặc tắt lập chỉ mục để dừng tác vụ.”), và việc đóng trang không hủy quá trình này.

“Đồng bộ” cập nhật chỉ mục thủ công hoặc thử lại sau khi gặp lỗi. Trước mỗi truy vấn mã, VelaTerm cũng cập nhật chỉ mục. Với cùng một máy chủ và thư mục làm việc, một tiến trình truy vấn duy nhất được dùng lại, và trong lúc chạy, tiến trình này ghi nhận các thay đổi tệp ngay khi chúng xảy ra. Tiến trình thoát sau năm phút không có truy vấn nào; truy vấn tiếp theo sẽ mở lại chỉ mục và cập nhật phần còn thiếu. Trang Tổng quan làm mới trạng thái đồng bộ mỗi 30 giây; khi không thể đồng bộ tự động, VelaTerm vẫn đồng bộ trước mỗi truy vấn và không bao giờ trình bày kết quả đã lỗi thời như kết quả hiện hành.

“Tắt lập chỉ mục” dừng tác vụ lập chỉ mục đang chạy nhưng vẫn giữ các tệp chỉ mục và liên kết đến bài viết kiến thức, nên bạn có thể bật lại sau. Khi một tác vụ bị gián đoạn, trong vòng khoảng hai phút trạng thái của nó sẽ chuyển thành lỗi có thể thử lại (“Tác vụ trước đã bị gián đoạn. Hãy đồng bộ để thử lại.”). Mỗi tác vụ lập chỉ mục chạy tối đa 30 phút.

Chỉ mục được lưu trong thư mục .codegraph/ ở mỗi thư mục làm việc và do CodeGraph quản lý. VelaTerm tự chạy việc lập chỉ mục; VelaTerm không chạy trình cài đặt tác nhân của CodeGraph và không cài Git hook. Nếu thư mục dự án là thư mục con của một kho mã, chỉ thư mục đó được lập chỉ mục.

Xem quan hệ trong mã

Kết quả tìm kiếm hiển thị tên, loại và vị trí của mỗi ký hiệu. Trang của một ký hiệu hiển thị mã nguồn, các quan hệ đi vào và đi ra, cùng các bài viết kiến thức được liên kết; nhấp vào một ký hiệu lân cận để tiếp tục khám phá.

Các quan hệ là kết quả phân tích tĩnh và có thể chưa đầy đủ hoặc chưa chắc chắn (“Các quan hệ là kết quả phân tích tĩnh và có thể chưa đầy đủ hoặc chưa chắc chắn.”); chúng không thay thế cho việc chạy mã thực tế. Trang ký hiệu hiển thị tối đa 200 quan hệ cho mỗi chiều và 600 dòng mã nguồn, kèm thông báo khi còn nhiều hơn. Tệp mã nguồn lớn hơn 4 MiB không được hiển thị. Nếu một tệp thay đổi trong lúc bạn đang xem, VelaTerm yêu cầu bạn đồng bộ lại trước khi dựa vào số dòng của tệp đó.

Liên kết và rà soát bài viết

Trên trang của một ký hiệu, chọn “Liên kết bài viết”, chọn một bài viết có sẵn, đối chiếu nội dung bài viết với mã rồi lưu. Trên trang bài viết, “Tham chiếu mã nguồn” dẫn ngược về mã, còn các liên kết bài viết trong đồ thị mã nguồn mở toàn bộ bài viết.

Mỗi liên kết lưu dự án, thư mục làm việc, đường dẫn tệp, định danh ký hiệu và giá trị băm SHA-256 của tệp tại thời điểm rà soát. Khi tệp thay đổi, liên kết hiển thị “Cần rà soát”; khi tệp không còn đọc được hoặc đã bị xóa, liên kết hiển thị “Không khả dụng”; trong các trường hợp còn lại, liên kết hiển thị “Không thay đổi”. Việc kiểm tra thực hiện theo từng tệp, nên bất kỳ thay đổi nào trong cùng tệp cũng đòi hỏi rà soát lại. Trang bài viết đang mở kiểm tra định kỳ các tham chiếu của bài viết.

Chọn “Rà soát mã và bài viết” để xem mã hiện tại, và chọn “Xác nhận đã rà soát” khi bài viết vẫn còn đúng. Máy chủ kiểm tra lại để bảo đảm tệp và bài viết không thay đổi trong lúc đó, và yêu cầu bạn tải lại nếu đã có thay đổi. Xác nhận chỉ cập nhật tham chiếu mã nguồn; thao tác này không thay đổi nội dung bài viết. Để thay đổi kết luận, hãy sửa bài viết như bình thường.

Khi một ký hiệu bị xóa hoặc đổi tên, liên kết không tự chuyển sang một ký hiệu khác cùng tên. Hãy dùng “Xóa liên kết” rồi liên kết với đúng ký hiệu. Xóa một bài viết sẽ xóa các liên kết của bài viết đó; xóa một dự án sẽ xóa các bản ghi chỉ mục và liên kết của dự án, nhưng không xóa các bài viết khác hay tệp chỉ mục trong các thư mục làm việc.

Truy vấn từ một phiên

Mọi phiên terminal và phiên tác nhân do VelaTerm khởi động đều có lệnh vkb. Các tác nhân khác có khả năng chạy lệnh terminal cũng dùng được lệnh này. Nếu một phiên có sẵn không tìm thấy vkb sau khi cập nhật, hãy khởi động lại phiên đó.

Khi đã cài “Kỹ năng Vela” (Cài đặt ▸ Chung), Claude có thể dùng /vkb và Codex có thể dùng $vkb. Kỹ năng này chỉ chạy khi bạn yêu cầu rõ ràng; tác nhân không tự gọi kỹ năng trong lúc làm việc khác. Nếu sau khi cập nhật, tác nhân không liệt kê kỹ năng này, hãy nhấp “Cài đặt lại” rồi khởi động lại phiên của tác nhân đó.

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

explore trả về kết quả giống như Khám phá mã.
callers, callees và impact nhận thêm tham số độ sâu không bắt buộc; kết quả của các lệnh này gồm relations, total, depth và truncated.
path nhận hai ID ký hiệu chính xác lấy từ kết quả tìm kiếm, còn files có thể lọc theo đường dẫn.
search trả về riêng biệt kết quả mã (sắp xếp theo mức độ liên quan, kèm hasMore khi còn kết quả), bài viết kiến thức và ghi chú cục bộ.
node trả về mã nguồn, các quan hệ và các bài viết được liên kết của một ký hiệu.
memories và memory tìm và đọc các bài viết trong kho kiến thức theo phiên, bao gồm nguồn, bản sửa đổi và tham chiếu mã nguồn.
notes và note tìm và đọc các cơ sở tri thức cục bộ (xem Cơ sở tri thức cục bộ).

Truy vấn mã dùng chỉ mục của thư mục nơi lệnh được chạy. Thư mục con dùng chỉ mục của dự án chứa nó, còn một worktree riêng nằm lồng bên trong không bao giờ dùng chỉ mục của bản checkout chính. Khi chưa bật chỉ mục nào hoặc truy vấn thất bại, kết quả sẽ cho biết phần mã không khả dụng, và các truy vấn kiến thức vẫn hoạt động. Các lệnh này không cài đặt gì, không bật lập chỉ mục và không thay đổi bài viết.

Nơi lưu dữ liệu

Bộ chạy CodeGraph được cài trong codegraph/1.6.0/ thuộc thư mục dữ liệu ứng dụng. Tác vụ lập chỉ mục và liên kết bài viết được lưu trong cơ sở dữ liệu của ứng dụng (các bảng knowledge_*). Việc lập chỉ mục chạy trên máy chủ chứa mã nguồn; máy khách trình duyệt và kết nối SSH đọc kết quả qua kết nối sẵn có, nên không cần mở thêm cổng nào. Mỗi máy chủ có thiết lập chỉ mục và kho kiến thức riêng.

Tính năng đo lường sử dụng (telemetry), kiểm tra cập nhật và dịch vụ nền riêng của CodeGraph đều bị tắt. VelaTerm quản lý tiến trình truy vấn và trao đổi với tiến trình này qua một kênh đầu vào và đầu ra chuẩn riêng, không lắng nghe trên cổng nào. Bản thân việc lập chỉ mục không dùng AI. Mã hoặc bài viết mà tác nhân đọc bằng vkb có thể được gửi tới dịch vụ mô hình đã cấu hình cho tác nhân đó, giống như khi tác nhân đọc tệp mã nguồn.

Các sự kiện của đồ thị mã nguồn được ghi vào logs/runtime-*.log trong thư mục dữ liệu ứng dụng. Khi chưa đặt VLX_LOG_DIR, VLX_KNOWLEDGE_LOG_DIR quy định thư mục chứa các sự kiện này. VLX_KNOWLEDGE_LOG_LEVEL dùng để lọc chúng (ví dụ error hoặc off). Nhật ký không chứa mã nguồn, nội dung truy vấn, nội dung bài viết hay thông tin xác thực.

CodeGraph được phát triển tại github.com/colbymchenry/codegraph và phát hành theo giấy phép MIT.