Xây dựng đồ thị mã nguồn cục bộ và bộ nhớ cho tác nhân lập trình với Graphicle

Graphicle là gì?

Graphicle là một chương trình Rust chạy cục bộ, kết hợp đồ thị mã nguồn của kho lưu trữ với bộ nhớ dự án dành cho các tác nhân lập trình. Công cụ này lập chỉ mục các tệp, hàm, lớp, lệnh gọi và import, đồng thời ghi nhớ tài liệu, quyết định, quy trình và các phiên làm việc trước đây của tác nhân.

Khi tác nhân hoặc nhà phát triển đặt câu hỏi, Graphicle trả về các đoạn trích có dẫn nguồn, xác định tệp nguồn và phạm vi dòng. Đồ thị mã nguồn và các công cụ ngữ cảnh cốt lõi hoạt động mà không cần khóa API hoặc tài khoản, đồng thời Graphicle không gửi dữ liệu đi đâu trừ khi bạn chủ động cấu hình một mô hình hoặc trình kết nối yêu cầu điều đó.

Graphicle hoạt động với Claude Code, Cursor, Codex, VS Code, Claude Desktop và các ứng dụng khách MCP khác. Công cụ này cung cấp giao diện dòng lệnh, máy chủ MCP, ứng dụng trình duyệt và một kho dữ liệu duy nhất dựa trên SQLite.

Tính năng chính

• Đồ thị mã nguồn: Khám phá tệp, ký hiệu, lệnh gọi, import, đường dẫn và mã bị ảnh hưởng bằng trình phân tích dựa trên tree-sitter.
• Bộ nhớ dự án: Tìm kiếm tài liệu Markdown, PDF, Office và HTML, các quyết định đã được xem xét, quy trình và các phiên làm việc của tác nhân đã ghi lại.
• Ngữ cảnh có dẫn nguồn: Truy xuất các đoạn trích liên quan từ mã nguồn và kiến thức dự án trong giới hạn token mà không cần gọi mô hình.
• Tích hợp tác nhân: Kết nối các tác nhân lập trình được hỗ trợ thông qua MCP bằng một lệnh thiết lập.
• Bộ nhớ gắn với mã nguồn: Bộ nhớ đã được xem xét có thể được neo vào các hàm mà chúng mô tả và trở nên lỗi thời khi mã đó thay đổi.
• Vận hành cục bộ: Dữ liệu được lưu trữ cục bộ, các endpoint mặc định chỉ lắng nghe trên loopback, và Graphicle không sử dụng telemetry hay tài khoản.
• Đồng bộ tự động: Các tệp đã thay đổi được đồng bộ trước khi trả lời, trong khi hook Git có thể đồng bộ sau các thao tác commit, merge và checkout.

Cài đặt Graphicle

Graphicle hiện hỗ trợ macOS và Linux. Phương pháp cài đặt đơn giản nhất trên macOS hoặc hệ thống Linux có Homebrew là:

brew install graphicle-ai/tap/graphicle

Nếu không có Homebrew, hãy sử dụng trình cài đặt bản phát hành:

curl -fsSL https://github.com/graphicle-ai/graphicle/releases/latest/download/install.sh | sh

Bạn cũng có thể tải xuống gói lưu trữ dành riêng cho nền tảng từ trang bản phát hành GitHub. Hiện chưa có hỗ trợ Windows gốc, mặc dù README ghi chú rằng bản cài đặt Linux có thể hoạt động trên WSL2 và chưa được kiểm thử.

Thiết lập kho lưu trữ

Chuyển đến kho lưu trữ mà bạn muốn các tác nhân hiểu, sau đó chạy lệnh thiết lập:

cd your-repo
graphicle setup

Quy trình thiết lập lập chỉ mục kho lưu trữ, xây dựng đồ thị mã nguồn và kết nối các tác nhân lập trình mà công cụ tìm thấy. Tùy thuộc vào các ứng dụng khách đã cài đặt trên máy, công cụ có thể cập nhật cấu hình MCP cho Claude Code, Codex, Cursor, VS Code, Claude Desktop và các ứng dụng khách MCP khác.

Thiết lập cũng bật tính năng ghi lại phiên, hướng các tìm kiếm của Claude Code đến đồ thị mã nguồn, thêm một phần ngắn vào AGENTS.md và cài đặt các hook Git giúp duy trì tính cập nhật của dự án. Graphicle liệt kê mọi tệp mà công cụ thay đổi và tạo bản sao lưu trước khi chỉnh sửa. Để cho phép thiết lập chạy mà không hiển thị lời nhắc tương tác, hãy sử dụng:

graphicle setup --yes

Để hoàn tác các thay đổi tích hợp, hãy chạy:

graphicle disconnect

Lệnh disconnect xóa những nội dung mà setup đã thêm. Lệnh này không xóa thư mục đầu ra Graphify hiện có của kho lưu trữ.

Đặt câu hỏi từ terminal

Sau khi thiết lập, dùng graphicle ask để tìm kiếm kho lưu trữ:

graphicle ask "where is tax added to prices?"

Graphicle trả về bằng chứng kèm tên tệp, phạm vi dòng, ký hiệu và đoạn trích. Một kết quả có thể trông như sau:

Evidence for "where is tax added to prices?"
4 excerpts · 598 of 3,000 tokens

[1] shop/pricing.py:1-7  price_with_tax()
    """Prices and tax."""
    TAX_RATE = 0.2

    def price_with_tax(price):
        """A price with the sales tax added."""
        return round(price * (1 + TAX_RATE), 2)

Khi chưa cấu hình mô hình, ask sẽ hiển thị bằng chứng. Để Graphicle tạo câu trả lời bằng văn bản, hãy cấu hình một nhà cung cấp mô hình được hỗ trợ như Anthropic, OpenAI hoặc Ollama:

graphicle config set model anthropic

Các mô hình cục bộ thông qua Ollama và các máy chủ tương thích với OpenAI cũng được hỗ trợ. Xem tài liệu cấu hình để biết các thiết lập mô hình.

Sử dụng Graphicle với tác nhân

Sau khi graphicle setup đã kết nối một ứng dụng khách MCP, hãy yêu cầu tác nhân lập trình sử dụng Graphicle cho các câu hỏi về kho lưu trữ. Ví dụ:

Dùng Graphicle để tìm nơi các yêu cầu thất bại được thử lại.

Tác nhân có thể sử dụng các công cụ đồ thị mã nguồn và bộ nhớ của Graphicle, nhận các đoạn trích có dẫn nguồn và kết hợp những kết quả đó với suy luận của chính nó. Graphicle cung cấp một máy chủ MCP duy nhất chứa các công cụ đồ thị mã nguồn và công cụ bộ nhớ. Các công cụ đồ thị bao gồm những tên như query_graph, get_neighbors và shortest_path.

Duyệt đồ thị và bộ nhớ dự án

Để mở ứng dụng trình duyệt của Graphicle, hãy chạy:

graphicle open

Ứng dụng cho phép bạn duyệt đồ thị mã nguồn, tài liệu nguồn và bộ nhớ dự án. Đây cũng là nơi các bộ nhớ được đề xuất có thể được xem xét và phê duyệt.

Để kiểm tra tình trạng cài đặt và các tích hợp, hãy chạy:

graphicle doctor

Dùng doctor khi tác nhân không thể kết nối, quá trình đồng bộ có vẻ chưa hoàn tất hoặc bạn muốn xác minh môi trường đã cấu hình.

Khám phá dependency và mã bị ảnh hưởng

Graphicle có thể xây dựng và truy vấn một đồ thị chỉ chứa mã nguồn. Trước tiên, hãy trích xuất đồ thị:

graphicle graph extract . --code-only

Sau đó hỏi mã nào phụ thuộc vào một ký hiệu:

graphicle graph affected "retry()"

ลệnh graph có thể tìm kiếm kho mã, giải thích các ký hiệu, truy vết đường dẫn và xuất đồ thị HTML tương tác. Chế độ --code-only không yêu cầu mô hình.

Graphicle cũng có thể liên kết các đề cập đến mã trong tài liệu dự án với các định nghĩa mà chúng tham chiếu. Sử dụng lệnh graph liên kết tài liệu để liệt kê các mối quan hệ đó:

graphicle call graph.doc_links

Truy xuất ngữ cảnh mà không cần mô hình trả lời

Lệnh context truy xuất các đoạn trích liên quan từ mã, tài liệu, phiên làm việc và bộ nhớ đã được xem xét. Lệnh này không gọi mô hình:

graphicle context

Đối với không gian làm việc chứa nhiều kho mã, hãy yêu cầu ngữ cảnh trên toàn bộ không gian làm việc:

graphicle context --workspace

Điều này giúp Graphicle hữu ích khi một phần triển khai trong một kho mã phụ thuộc vào tài liệu hoặc mã nguồn trong một kho mã khác. Cấu hình MCP cho không gian làm việc được mô tả trong tài liệu MCP.

Tìm hiểu về đồng bộ hóa và quyền riêng tư

Trong quá trình đồng bộ hóa, Graphicle tuân thủ .gitignore và bỏ qua các tệp môi trường, khóa và thông tin xác thực. Việc ghi lại phiên làm việc sẽ xóa nội dung bên trong các đoạn <private>...</private> và che thông tin xác thực.

Trên macOS, thư mục dữ liệu cục bộ chính là ~/Library/Application Support/Graphicle. Trên Linux, thư mục này là ~/.local/share/graphicle. Đồ thị được tạo bởi graphicle graph extract được ghi vào .graphicle/ bên trong dự án.

Ứng dụng, các endpoint HTTP và endpoint MCP mặc định lắng nghe trên 127.0.0.1. Truy cập mạng chỉ diễn ra khi bạn yêu cầu một tính năng cần đến nó, chẳng hạn như mô hình hoặc trình kết nối đã cấu hình, việc trích xuất toàn bộ đồ thị gửi tài liệu hoặc hình ảnh đến LLM, một số thao tác GitHub CLI được chọn hoặc nguồn cấp dữ liệu cập nhật.

Mẹo nâng cao

Giữ câu trả lời dựa trên bằng chứng

Sử dụng các đoạn trích có trích dẫn của Graphicle để đối chiếu các nhận định của tác nhân với đúng tệp và dòng mã. Điều này đặc biệt hữu ích khi gỡ lỗi, tìm hiểu các kho mã chưa quen thuộc và xem xét các thay đổi.

Xem xét bộ nhớ được đề xuất

Bộ nhớ do tác nhân đề xuất không tự động trở thành kiến thức đáng tin cậy của dự án. Hãy xem xét chúng trong ứng dụng trước khi phê duyệt. Bộ nhớ gắn với các ký hiệu mã có thể trở nên lỗi thời khi mã liên quan thay đổi, trong khi việc chỉnh sửa những vị trí khác trong cùng tệp thường vẫn giữ chúng cập nhật.

Sử dụng hook Git để duy trì ngữ cảnh hiện tại

Giữ cho kho mã được đồng bộ bằng cách duy trì các hook đã cài đặt trong quá trình thiết lập. Chúng đồng bộ sau các lần commit, merge và checkout; đồng thời Graphicle cũng đồng bộ các tệp đã thay đổi trước khi trả lời.

Điều chỉnh giới hạn kho mã

Theo mặc định, một dự án có thể chứa tối đa 100.000 tệp văn bản và 1 GiB văn bản. Có thể tăng các giới hạn này trong cấu hình nếu bạn làm việc với một kho mã lớn hơn. Các tệp rất lớn có thể được phân tích một phần hoặc được giữ lại dưới dạng văn bản có thể tìm kiếm thay vì khiến quá trình đồng bộ hóa dừng lại.

Kết nối một ứng dụng MCP khác

Đối với các ứng dụng khách mà Graphicle không tự động phát hiện, hãy thêm cấu hình MCP JSON ngắn được mô tả trong hướng dẫn MCP. Cùng một máy chủ MCP cung cấp cả khả năng về đồ thị và bộ nhớ.

Kết luận

Graphicle cung cấp cho các tác nhân lập trình một chế độ xem cục bộ, có thể tìm kiếm về cấu trúc kho mã và kiến thức dự án. Hãy cài đặt, chạy graphicle setup và sử dụng ask, context, open và graph để điều tra mã với các trích dẫn. Chỉ cấu hình mô hình khi bạn muốn tạo câu trả lời; đồ thị, quá trình đồng bộ hóa, máy chủ MCP, việc ghi lại phiên làm việc và ứng dụng có thể hoạt động mà không cần mô hình.

Để biết thêm chi tiết, hãy tiếp tục với hướng dẫn bắt đầu nhanh, hướng dẫn tác nhân, tài liệu tham chiếu cấu hình và FAQ của dự án.