Tài liệu Grapuco

Mọi thứ bạn cần để cài đặt, lập chỉ mục và truy vấn codebase của bạn.

rocket_launch

1. Bắt đầu nhanh

1. Lấy API Key

Đăng ký và tạo một API Key để xác thực CLI hoặc công cụ MCP.

2. Cài đặt CLI

Grapuco CLI là công cụ giúp quét mã nguồn cục bộ. Hãy chạy lệnh sau trên máy bạn để cài đặt trọn gói:

npm install -g @bitsness/grapuco-cli

3. Ingest Data

Tại thư mục gốc dự án của bạn, hãy gõ lệnh dưới đây. Động cơ đồ thị sẽ quét toàn bộ kiến trúc và tải chúng lên Cloud trong chớp mắt.

grapuco ingest

account_tree

2. Đồ thị Kiến trúc (Architecture Graph)

Ngay khi phân tích xong, codebase của bạn biến thành một Đồ thị Tri thức trực quan. Cách đọc bản đồ như sau:

Filters (Bộ lọc)

Cho phép cấu hình hiển thị bản đồ tuỳ ý. Bạn có thể bật tắt hiển thị theo loại File (API, DB, Giao diện) hoặc dọn dẹp các nhánh phụ / utility folder để tập trung vào luồng chính.

Explorer (Duyệt đồ thị)

Điều hướng xuyên suốt dự án một cách trực quan. Nhấp vào bất kỳ điểm ảnh nào để mở rộng các luồng liên đới, kiểm tra thuộc tính hoặc các đường nối tới/về nội bộ.

Flows (Tiến trình)

Danh sách các nhánh nghiệp vụ được hệ thống biên dịch tự động phát hiện. Bấm chọn vào 1 API Endpoint bất kì để kích hoạt hiệu ứng phát sáng xuyên suốt từ Controller xuống tận dưới CSDL.

hub

3. Tích hợp MCP Server

MCP (Model Context Protocol) là chuẩn mở cho phép các trợ lý AI lập trình như Claude, Cursor và Windsurf kết nối trực tiếp tới nguồn dữ liệu bên ngoài. Khi bạn kết nối Grapuco làm MCP Server, trợ lý AI của bạn sẽ hiểu trọn vẹn cấu trúc codebase - nắm bắt chuỗi gọi hàm, dò luồng dữ liệu, và phân tích tác động trước khi viết bất kỳ dòng code nào.

Kết nối AI Agent của bạn

terminalQuick Setup

One command to configure MCP for all AI coding agents on your machine:

grapuco setup

The CLI will ask for your API key, auto-detect installed AI tools (Claude Code, Cursor, Windsurf, Antigravity, etc.), and write the correct MCP config for each one.

Các công cụ MCP được cung cấp

Sau khi kết nối, trợ lý AI sẽ tự động gọi các công cụ phù hợp. Bạn không cần gõ lệnh thủ công - chỉ cần hỏi AI bất kỳ câu hỏi nào về codebase và nó sẽ tự chọn công cụ đúng.

folder_open

list_repositories

Liệt kê tất cả repository bạn đã lập chỉ mục trên Grapuco. Đây là bước khởi đầu - AI sẽ gọi lệnh này trước tiên để tìm đúng Repository ID trước khi chạy bất kỳ công cụ nào khác.

manage_search

search_code

Tìm kiếm hàm, lớp hoặc phương thức theo tên chính xác trong đồ thị mã nguồn. Giống như tính năng tìm kiếm thông minh của IDE, nhưng hoạt động xuyên suốt toàn bộ bản đồ kiến trúc - không chỉ dò text đơn thuần.

psychology

semantic_search

Tìm kiếm codebase bằng tiếng Việt hoặc tiếng Anh tự nhiên thay vì từ khóa chính xác. Ví dụ: hỏi "chỗ nào xác thực JWT token?" và Grapuco sẽ trả về các symbol liên quan nhất thông qua so sánh vector (cosine similarity).

device_hub

get_dependencies

Cho một hàm hoặc lớp cụ thể, công cụ này trả về toàn bộ cây phụ thuộc: những gì nó GỌI (CALLS), những gì nó NHẬP (IMPORTS), và những gì nó KẾ THỪA (EXTENDS). Lý tưởng để hiểu một đoạn code kết nối sâu đến đâu.

account_tree

get_architecture

Trả về toàn bộ bản đồ kiến trúc của repository - mọi điểm (hàm, lớp, endpoint) và mọi đường kết nối (gọi, nhập, kế thừa). AI sẽ dùng công cụ này để nắm bắt bức tranh tổng thể trước khi thực hiện thay đổi.

auto_awesome

get_context

Truy xuất ngữ cảnh thông minh bằng AI. Đặt tên tính năng như "luồng xác thực người dùng" và nó sẽ trả về các symbol liên quan, chuỗi gọi hàm và tài liệu. Tiêu tốn 5 AI credit mỗi lần truy vấn. Phù hợp nhất khi mới onboard vào codebase xa lạ.

route

get_data_flows

Dò vết toàn bộ luồng thực thi đầu-cuối: từ HTTP API Endpoint qua Service rồi xuống tới thao tác cơ sở dữ liệu. Cho thấy chính xác cách một request di chuyển qua hệ thống - lý tưởng cho việc debug và hiểu logic nghiệp vụ.

warning

get_impact_analysis

Trình phát hiện "Bán kính Công phá" (Blast Radius). Chỉ vào bất kỳ file nào và nó sẽ phơi bày mọi API endpoint, thao tác database và workflow sẽ bị ảnh hưởng nếu file đó thay đổi. Không thể thiếu trước khi refactor hoặc deploy thay đổi rủi ro cao.

hub

get_symbol_context

Góc nhìn 360° cho bất kỳ symbol nào: callers, callees, processes, kế thừa, DB access, routes và overrides. Công cụ chính để hiểu một hàm nằm ở đâu trong bức tranh tổng.

radar

blast_radius

Tính toán tác động upstream và downstream khi thay đổi một symbol. Trả về mức rủi ro (THẤP đến NGUY HIỂM), routes bị ảnh hưởng và các nghiệp vụ liên quan.

difference

detect_changes

Đưa git diff vào và nhận lại: symbol nào thay đổi, tác động downstream, routes bị ảnh hưởng và mức rủi ro tổng thể. Hoàn hảo cho kiểm tra an toàn trước khi commit.

edit_note

rename_symbol

Đổi tên an toàn đa file. Xem trước tất cả chỉnh sửa (khai báo, call sites, imports, exports), phát hiện xung đột tên và tùy chọn áp dụng.

update

check_staleness

Kiểm tra đồ thị code có cập nhật với commit mới nhất không. Trả về khuyến nghị: không cần, gia tăng, hoặc cần reindex toàn bộ.

build

detect_tools

Quét codebase để tìm MCP tools, gRPC services và JSON-RPC methods. Hữu ích để khám phá bề mặt API.

help_center

grapuco_help

Hướng dẫn sử dụng công cụ nào phù hợp. Trả về danh mục skill và tool đầy đủ, hỗ trợ lọc theo chủ đề.

bolt

bootstrap

Khởi động nhanh: trả về repos, danh mục tool, manifest skill và các bước đề xuất. Gọi một lần khi bắt đầu phiên làm việc. Truyền workspaceId để tự động tìm repos và spec projects liên quan.

school

5. Bộ kỹ năng AI (Skill Packs)

downloadDownload All

Grapuco tích hợp sẵn các Skill Pack — hướng dẫn từng bước giúp AI agent sử dụng công cụ Grapuco hiệu quả. Mỗi skill mô tả khi nào dùng, cần input gì và cách đọc kết quả.

explore

Onboard vào codebase mới — khám phá cấu trúc, entry points và các luồng chính chỉ trong vài phút.

download

shield

safe-edit

Kiểm tra tác động trước khi sửa code — lấy context, blast radius và gợi ý test cần chạy.

download

check_circle

pre-commit

Phân tích tác động trên git diff trước khi commit — bắt sớm các thay đổi rủi ro.

download

edit_note

rename

Đổi tên symbol an toàn đa file — xem trước tất cả chỉnh sửa và xung đột trước khi áp dụng.

download

timeline

trace

Truy vết request từ API route qua service xuống database — hiểu toàn bộ data flow.

download

bug_report

bug

Điều tra bug từ stack trace — truy vết từng frame, tìm nguyên nhân gốc và xác định phạm vi sửa.

download

construction

refactor

Lên kế hoạch refactor bằng cách mapping blast radius, nhóm theo module và chia thành các bước an toàn.

download

description

spec-coding

Triển khai tính năng theo đặc tả nghiệp vụ từ Spec Agent — yêu cầu, tiêu chí nghiệm thu và quy tắc domain.

download

fact_check

review-uc

Xem xét toàn bộ phạm vi Use Case — yêu cầu, bước thực hiện, quy tắc, actors và phụ thuộc — trước khi code.

download

gavel

validate-rules

Tìm kiếm và xác minh quy tắc nghiệp vụ, ràng buộc và schema liên quan đến phần bạn đang triển khai.

download

terminal

4. Hướng dẫn CLI chi tiết

Grapuco CLI chạy hoàn toàn trên máy cá nhân của bạn. Nó phân tích AST (Cây cú pháp trừu tượng) của codebase và chỉ trích xuất siêu dữ liệu cấu trúc - tên hàm, quan hệ gọi hàm, bản đồ import. Tuyệt đối không có dòng mã nguồn nào rời khỏi máy bạn.

key

grapuco login

Xác thực CLI với Grapuco cloud. Bạn có thể truyền API key trực tiếp qua cờ --api-key, hoặc chạy lệnh không có tham số để nhập thủ công theo hình thức tương tác. Thông tin đăng nhập được lưu an toàn tại ~/.grapuco/credentials.json.

grapuco login --api-key YOUR_API_KEY

--api-key <key> - Truyền API key trực tiếp (bỏ qua hỏi tương tác)

--server <url> - URL server tuỳ chỉnh (mặc định: https://api.grapuco.com)

folder_open

grapuco init

Khởi tạo dự án Grapuco mới tại thư mục hiện tại. CLI tự động nhận diện ngôn ngữ lập trình và framework (NestJS, Next.js, Django, Spring Boot...), tạo file .grapuco/config.json và đăng ký repository mới trên server.

grapuco init

--name <name>Tên repository tuỳ chỉnh (mặc định: tên thư mục)

--link <repoId>Liên kết tới repository đã tồn tại thay vì tạo mới

--workspace <id>Thêm repo vào workspace khi init

--server <url>URL server tuỳ chỉnh

cloud_upload

grapuco ingest

Lệnh cốt lõi. Quét toàn bộ file trong dự án, xây dựng bản phân tích AST cục bộ, sau đó chỉ tải lên siêu dữ liệu (nodes + edges) lên Grapuco cloud. Đây là đồng bộ toàn phần - dùng cho lần chạy đầu tiên hoặc khi bạn muốn làm mới hoàn toàn.

grapuco ingest

--embeddings - Bật vector embeddings cho tìm kiếm ngữ nghĩa

--flows - Bật phân tích Data Flow (API → Service → DB)

--all - Bật tất cả tính năng

--dry-run - Chỉ phân tích cục bộ, không tải lên server

sync

grapuco push

Đồng bộ gia tăng thông minh. So sánh hash file với lần push trước và chỉ phân tích lại các file đã thay đổi (thêm mới, sửa đổi hoặc xóa). Nhanh hơn đáng kể so với ingest toàn phần - lý tưởng cho quy trình phát triển hàng ngày.

grapuco push

--force - Bỏ qua cache delta, ingest lại toàn bộ

--enrich-flows - Chạy lại phân tích Data Flow cho các file đã thay đổi

visibility

grapuco watch

Trình theo dõi file thời gian thực. Giám sát thư mục dự án bằng chokidar và tự động kích hoạt delta push mỗi khi bạn lưu file. Cấu hình khoảng thời gian debounce để kiểm soát tần suất đồng bộ. Nhấn Ctrl+C để dừng.

grapuco watch

--debounce <ms> - Khoảng thời gian debounce tính bằng mili giây (mặc định: 2000)

preview

grapuco inspect

Công cụ minh bạch. Phân tích dự án cục bộ và hiển thị chính xác dữ liệu nào sẽ được gửi tới server - mà không thực sự gửi. Hoàn hảo cho kiểm toán bảo mật hoặc xác minh rằng không có mã nguồn nào bị bao gồm trong payload.

grapuco inspect --json

--json - Xuất JSON đầy đủ thay vì tóm tắt

info

grapuco status

Dashboard ngay trong Terminal. Hiển thị cấu hình dự án, ngôn ngữ/framework đã phát hiện, các cờ tính năng (embeddings, data flows), thời gian push cuối cùng, số file đã cache và trạng thái repository từ xa (số node/edge).

grapuco status

settings_suggest

grapuco setup

Tự động cấu hình MCP cho editor AI. Phát hiện editor đã cài (Claude Code, Cursor, Windsurf, Codex, Antigravity), ghi config MCP và xác minh kết nối.

grapuco setup