README.vi VN

Cắt giảm chi phí token của agent đi 80%. Graphify Cloud là bộ nhớ luôn bật, giúp quản trị các agent của bạn, giữ chất lượng code ở mức cao, và chứng minh tính đúng đắn bằng kiểm chứng hình thức. Bắt đầu dùng thử miễn phí 14 ngày →

Gõ /graphify trong trợ lý lập trình AI của bạn và nó ánh xạ toàn bộ dự án của bạn (code, tài liệu, PDF, hình ảnh, video) thành một đồ thị tri thức mà bạn có thể truy vấn thay vì grep xuyên qua các tệp.

• Ánh xạ code miễn phí, hoàn toàn cục bộ. Code được phân tích bằng tree-sitter AST: xác định, không dùng LLM, không gì rời khỏi máy của bạn. (Tài liệu, PDF, hình ảnh và video dùng mô hình của trợ lý của bạn, hoặc một API key đã cấu hình, cho một lượt xử lý ngữ nghĩa.)
• Mọi cạnh đều được giải thích. Mỗi kết nối được gắn thẻ EXTRACTED (hiện diện rõ ràng trong nguồn) hoặc INFERRED (được graphify giải quyết), nên bạn có thể phân biệt điều gì được đọc trực tiếp với điều gì được suy luận.
• Không phải chỉ mục vector. Không embedding, không kho vector: một đồ thị thực sự mà bạn duyệt qua. Hỏi một câu hỏi, lần theo đường đi giữa hai thứ, hoặc giải thích một khái niệm.

[!NOTE] Muốn cái này luôn bật? Graphify Cloud giữ đồ thị luôn sống xuyên suốt toàn bộ SDLC của bạn: hỗ trợ monorepo và liên repo, kiểm chứng hình thức, và rà soát code với góc nhìn bao quát toàn cảnh SDLC của bạn, cùng các trình kết nối cho Sentry, Jira và nhiều hơn nữa để sự cố và ticket nằm trong cùng đồ thị với code của bạn. Bắt đầu dùng thử miễn phí 14 ngày tại app.graphify.com.

Mã nguồn FastAPI được graphify ánh xạ. Mỗi nút là một khái niệm, màu sắc là các cộng đồng được phát hiện, và toàn bộ có thể nhấp được trong graph.html.

Bắt đầu (30 seconds). Cần Python 3.10+ và uv (hoặc pipx):

uv tool install graphifyy      # install the CLI (or: pipx install graphifyy)
graphify install               # detects your assistant and registers the skill

Sau đó, trong trợ lý AI của bạn:

/graphify .

Vậy là xong. Bạn nhận được ba tệp:

graphify-out/
├── graph.html       open in any browser: click nodes, filter, search
├── GRAPH_REPORT.md  the highlights: key concepts, surprising connections, suggested questions
└── graph.json       the full graph: query it anytime without re-reading your files

Đồ thị được lưu bao gồm graph.schema_version để các tích hợp có thể phát hiện các thay đổi định dạng không tương thích, cùng với graph.graphify_version xác định bản phát hành Graphify đã tạo ra nó.

Một lần cài đặt, mọi trợ lý, mọi hệ điều hành. Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, và 20+ trợ lý khác, trên macOS, Linux và Windows: chọn nền tảng của bạn.

Xem nó hoạt động¶

Khi đồ thị đã được dựng, bạn truy vấn nó thay vì đọc các tệp. Đây là kết quả thực, graphify chạy trên mã nguồn FastAPI được hiển thị ở trên:

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  --> Dependant [uses] [INFERRED]
  --> .get() [method] [EXTRACTED]
  <-- __init__.py [imports] [EXTRACTED]
  ...

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

Mọi cạnh đều mang một thẻ độ tin cậy (EXTRACTED = hiện diện rõ ràng trong nguồn, INFERRED = suy ra từ việc giải quyết), nên bạn có thể phân biệt điều gì được đọc trực tiếp với điều gì được suy luận. graphify query "<question>" trả về một đồ thị con giới hạn phạm vi cho một câu hỏi bằng ngôn ngữ thông thường, và graphify path A B lần theo cách hai thứ bất kỳ kết nối với nhau.

Nó làm gì¶

Những gì bạn nhận được ngay từ đầu:

[!TIP] Đang chạy cái này trên nhiều repo hay một monorepo? Graphify Cloud làm điều đó liên tục và cắt giảm chi phí token của agent đi 80%, với liên kết liên repo, rà soát code trên toàn bộ SDLC, kiểm chứng hình thức, và các trình kết nối Sentry/Jira. Bắt đầu dùng thử miễn phí 14 ngày →

Benchmark: 0.497 recall@10, 0 LLM credits¶

Mọi hệ thống đều chạy trên cùng một harness với cùng mô hình và ngân sách, được chấm điểm bởi một giám khảo đã được kiểm chứng mù đối chiếu với một giám khảo thứ hai (90.6% agreement, Cohen's kappa 0.81). Bảng đầy đủ theo từng hệ thống, kết quả hiểu code, và các lệnh tái lập: BENCHMARKS.md.

Tài liệu¶

Hướng dẫn và tài liệu tham khảo đầy đủ nằm tại docs.graphify.com:

• Quickstart: dựng đồ thị đầu tiên của bạn
• CLI reference: mọi lệnh và cờ
• Ask better graph questions: các mẫu truy vấn
• Configuration: biến môi trường và tinh chỉnh
• Supported inputs: ngôn ngữ và loại tệp
• Team workflows và PR review
• Troubleshooting và How it works

Điều kiện tiên quyết¶

Cài đặt nhanh trên macOS (Homebrew):

brew install python@3.12 uv

Cài đặt nhanh trên Windows:

winget install astral-sh.uv

Ubuntu/Debian:

sudo apt install python3.12 python3-pip pipx
# or install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

Install¶

[!IMPORTANT] Gói chính thức: Gói PyPI là graphifyy (hai chữ y). Các gói graphify* khác trên PyPI không có liên kết. Lệnh CLI vẫn là graphify.

Kho nguồn chính thức là Graphify-Labs/graphify.

Phần bắt đầu nhanh hai lệnh nằm ở đầu README này. Phần này đề cập các phương thức cài đặt, cài đặt theo phạm vi dự án, và mọi nền tảng được hỗ trợ.

Các phương thức cài đặt (chọn một):

uv tool install graphifyy   # recommended, isolated env (if 'graphify' isn't found after, run: uv tool update-shell)
pipx install graphifyy      # alternative
pip install graphifyy       # may need PATH setup, see Troubleshooting below

Sau đó chạy graphify install một lần. Nó phát hiện bạn chạy trợ lý nào và đăng ký kỹ năng, nên không cần thiết lập riêng cho từng trợ lý. Mở trợ lý AI của bạn và gõ /graphify .

Để cài kỹ năng trợ lý vào kho hiện tại thay vì hồ sơ người dùng của bạn, thêm --project:

graphify install --project
graphify install --project --platform codex

Cài đặt theo phạm vi dự án ghi vào bên dưới thư mục hiện tại, ví dụ .claude/skills/graphify/SKILL.md hoặc .agents/skills/graphify/SKILL.md (cùng một sidecar references/ mà kỹ năng tải khi cần), và in một gợi ý git add cho các tệp có thể commit. Các lệnh theo từng nền tảng hỗ trợ cài đặt theo phạm vi dự án chấp nhận cùng cờ đó, ví dụ graphify claude install --project hoặc graphify codex install --project.

[!TIP] Gặp command not found, một vấn đề pip trên Mac/Windows, việc đặt dấu nháy trong PowerShell, cách dùng uvx, các đặc tính PATH của git-hook, hay chế độ strict? Xem Installation và Troubleshooting.

Khiến trợ lý của bạn luôn dùng đồ thị¶

Chạy cái này một lần trong dự án của bạn sau khi dựng một đồ thị:

Chạy graphify <platform> install một lần trong dự án của bạn, ví dụ graphify claude install hoặc graphify codex install (hoặc graphify install --platform <name>).

Việc này ghi một tệp cấu hình nhỏ bảo trợ lý của bạn tham khảo đồ thị tri thức cho các câu hỏi về mã nguồn, ưu tiên các truy vấn giới hạn phạm vi như graphify query "<question>" hơn là đọc toàn bộ báo cáo hoặc grep các tệp thô.

• Nền tảng kiểu Hook (Claude Code, Gemini CLI): một hook kích hoạt tự động trước các lệnh gọi công cụ kiểu tìm kiếm (và, trên Claude Code, trước khi đọc từng tệp nguồn một qua các công cụ Read/Glob) và đẩy trợ lý của bạn về phía đường đi đồ thị.
• Nền tảng kiểu tệp hướng dẫn (Codex, OpenCode, Cursor, v.v.): các tệp hướng dẫn bền vững (AGENTS.md, .cursor/rules/, v.v.) cung cấp cùng hướng dẫn ưu tiên truy vấn.

GRAPH_REPORT.md vẫn có sẵn cho việc rà soát kiến trúc trên diện rộng.

Chính xác tệp nào mỗi nền tảng ghi ra (CODEBUDDY.md + PreToolUse hooks của CodeBuddy, AGENTS.md của Codex, plugin .kilo gốc của Kilo, quy tắc alwaysApply của Cursor, v.v.) được đề cập trong Always-on setup.

Để gỡ graphify khỏi mọi nền tảng cùng lúc: graphify uninstall (thêm --purge để cũng xóa graphify-out/). Hoặc dùng lệnh theo từng nền tảng (ví dụ graphify claude uninstall).

Skill CLI hay hướng dẫn MCP?¶

Các hướng dẫn được cài bởi graphify install và các hướng dẫn đi kèm với một kết nối Graphify MCP mô tả những cách khác nhau để truy vấn một đồ thị:

Cả hai đều khuyến khích các truy vấn đồ thị giới hạn phạm vi trước các tìm kiếm nguồn trên diện rộng. Hãy chọn các hướng dẫn khớp với các công cụ mà trợ lý của bạn thực sự có thể truy cập; không khối nào thiết lập một quy tắc ưu tiên phổ quát cho các tệp hướng dẫn của trợ lý của bạn. Nếu bạn dùng cả hai tích hợp, hãy xác định mỗi cái truy vấn đồ thị nào và chọn một đường truy vấn chính thay vì sao chép hai khối hướng dẫn vô điều kiện vào AGENTS.md.

graphify install cài đặt tích hợp trợ lý cục bộ; nó không thiết lập một kết nối MCP. Một client MCP không cần chạy các truy vấn CLI cục bộ để dùng máy chủ đã kết nối của nó. Một máy chủ được host cục bộ vẫn cần bản cài đặt Graphify và đồ thị của riêng nó, trong khi một kết nối được host có thể phục vụ một đồ thị không hiện diện trong thư mục làm việc của client. Nếu các công cụ mong đợi bị thiếu, hãy kiểm tra bản cài đặt CLI hoặc kết nối MCP liên quan thay vì coi các hướng dẫn của thiết lập kia là có thể thay thế cho nhau.

Có gì trong báo cáo¶

GRAPH_REPORT.md tóm tắt các god nodes, cộng đồng, và các đường đi chính cho việc rà soát kiến trúc trên diện rộng. Cách đồ thị được dựng và nó chứa gì: How graphify works.

Nó xử lý những tệp nào: ~40 languages¶

graphify phân tích ~40 programming languages một cách cục bộ bằng tree-sitter AST, và ánh xạ tài liệu, PDF, hình ảnh, và âm thanh/video qua một lượt xử lý ngữ nghĩa tùy chọn. Danh sách đầy đủ: Supported inputs.

Các lệnh thường dùng¶

/graphify .                        # build graph for current folder
/graphify ./docs --update          # re-extract only changed files
/graphify . --cluster-only         # rerun clustering without re-extracting
/graphify . --cluster-only --resolution 1.5      # more granular communities
/graphify . --cluster-only --exclude-hubs 99     # suppress utility super-hubs from god-node rankings
/graphify . --no-viz               # skip the HTML, just the report + JSON
/graphify . --wiki                 # build a markdown wiki from the graph
graphify export callflow-html      # Mermaid architecture/call-flow HTML (auto-regenerates on every git commit if hook is installed)

/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

/graphify add https://arxiv.org/abs/1706.03762   # fetch a paper and add it
/graphify add <youtube-url>                       # transcribe and add a video

graphify hook install              # auto-rebuild on commit + branch checkout (run `graphify update .` after `git pull`: see "Recommended workflow" below)
graphify merge-graphs a.json b.json              # combine two graphs

graphify prs                       # PR dashboard: CI state, review status, worktree mapping
graphify prs 42                    # deep dive on PR #42 with graph impact
graphify prs --triage              # AI ranks your review queue (uses whatever backend is configured)
graphify prs --conflicts           # PRs sharing graph communities: merge-order risk

Xem tham khảo lệnh đầy đủ bên dưới.

Bỏ qua tệp¶

graphify tôn trọng .gitignore và hỗ trợ các mẫu --exclude cùng một .graphifyignore cấp dự án. Chi tiết: Configuration.

Cấu hình dự án¶

Tạo một .graphifyrc ở gốc quét cho các thiết lập thuộc về dự án chứ không thuộc về một lần chạy. Mỗi dòng một key=value; các dòng bắt đầu bằng # là chú thích.

Các phần mở rộng mơ hồ. Một số phần mở rộng mang ý nghĩa ngôn ngữ khác nhau trong các dự án khác nhau: .inc là PHP trên pfSense, là Pascal trong một cây Delphi, là SQL hoặc assembly ở nơi khác; .h là C hoặc C++; .m là Objective-C hoặc MATLAB. graphify phải chọn một mặc định toàn cục, và khi nó chọn sai thì tệp không thất bại: nó được phân tích dưới dạng ngôn ngữ sai và tạo ra một nhúm nút ngẫu nhiên, nên đồ thị trông như có dữ liệu trong khi các ký hiệu thực lại bị thiếu. Hãy khai báo phần mở rộng đó có nghĩa gì trong repo của bạn:

# .graphifyrc
# A language name:
language.inc=php
# Or an extension graphify already knows:
language.tpl=.ts
# Baked into the git hooks (see Team setup):
viz_node_limit=0

Khai báo này chảy qua phân loại, chọn trình trích xuất, ngữ pháp và giải quyết, import, graphify watch, và bộ nhớ đệm AST (một tệp được phân tích lại dưới một ngôn ngữ khác sẽ không bao giờ tái dùng mục cũ), và cùng một .graphifyrc được đọc bởi extract, update, các hook, máy chủ MCP, và kỹ năng /graphify. Một lỗi gõ được báo một lần trên stderr và việc quét tiếp tục với các mặc định. Cách các khai báo tương tác với bộ nhớ đệm, dựng lại tăng dần, và giải quyết import: Configuration.

Thiết lập nhóm¶

Commit hoặc chia sẻ đồ thị để cả nhóm của bạn truy vấn cùng một ngữ cảnh, và rà soát các pull request với ngữ cảnh đồ thị. Xem Share context with your team và Review pull requests.

Dùng đồ thị trực tiếp¶

Ngoài trợ lý AI của bạn, hãy truy vấn graph.json trực tiếp từ CLI với graphify query, graphify path, và graphify explain. Một tên khớp với nhiều nút sẽ bị từ chối với các ứng viên được liệt kê thay vì đoán. Các script có thể đọc kết quả từ mã thoát: 0 một câu trả lời, 3 một tên mơ hồ, 4 không có nút khớp. Xem Ask better graph questions và query reference.

Biến môi trường¶

Các backend, API key, hành vi hook, và tinh chỉnh được điều khiển bởi các biến môi trường. Bảng đầy đủ: Configuration.

Quyền riêng tư¶

• Tệp code: được xử lý cục bộ qua tree-sitter. Không gì rời khỏi máy của bạn. Một kho chỉ có code không cần API key: graphify extract chạy hoàn toàn ngoại tuyến. Trên một repo hỗn hợp, thêm --code-only để chỉ lập chỉ mục code và bỏ qua các tài liệu/PDF/hình ảnh mà lẽ ra sẽ cần một LLM.
• Video / âm thanh: được chép lời cục bộ với faster-whisper. Không gì rời khỏi máy của bạn.
• Tài liệu, PDF, hình ảnh: được gửi tới trợ lý AI của bạn để trích xuất ngữ nghĩa (qua kỹ năng /graphify, dùng bất kỳ mô hình nào phiên IDE của bạn đang chạy). graphify extract không giao diện cần GEMINI_API_KEY / GOOGLE_API_KEY (Gemini), MOONSHOT_API_KEY (Kimi), ANTHROPIC_API_KEY (Claude), OPENAI_API_KEY (OpenAI), DEEPSEEK_API_KEY (DeepSeek), một instance Ollama đang chạy (OLLAMA_BASE_URL), thông tin xác thực AWS qua chuỗi provider chuẩn (Bedrock - không cần API key, dùng IAM), hoặc tệp nhị phân CLI claude (Claude Code - không cần API key, dùng gói đăng ký Claude của bạn). Cờ --dedup-llm dùng cùng key.
• Lưu trú dữ liệu: graphify extract tự động phát hiện dùng provider nào dựa trên API key nào được đặt (ưu tiên: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). Với code có yêu cầu lưu trú dữ liệu, dùng --backend ollama (hoàn toàn cục bộ) hoặc truyền một cờ --backend rõ ràng. Kimi (MOONSHOT_API_KEY) định tuyến tới các máy chủ Moonshot AI ở Trung Quốc.
• Không telemetry, không theo dõi sử dụng, không phân tích.
• Ghi log truy vấn: mọi lệnh gọi graphify query, graphify path, graphify explain, và MCP query_graph được ghi vào ~/.cache/graphify-queries.log ở định dạng JSON Lines (dấu thời gian, câu hỏi, kho, các nút trả về, thời lượng). Các phản hồi đồ thị con đầy đủ theo mặc định không được lưu. Đặt GRAPHIFY_QUERY_LOG_DISABLE=1 để từ chối, hoặc GRAPHIFY_QUERY_LOG=/dev/null để làm im lặng mà không vô hiệu hóa đường code.

Khắc phục sự cố¶

Các vấn đề cài đặt và trích xuất thường gặp cùng cách khắc phục: Troubleshooting.

Tham khảo lệnh đầy đủ¶

Mọi lệnh và cờ, kèm ví dụ: CLI reference.

Tìm hiểu thêm¶

• docs.graphify.com: tài liệu đầy đủ: hướng dẫn, tham khảo lệnh, và tích hợp
• How it works: pipeline trích xuất, phát hiện cộng đồng, chấm điểm độ tin cậy, benchmark
• ARCHITECTURE.md: phân tách module, cách thêm một ngôn ngữ
• Optional integrations: Docker MCP Toolkit + SQLite
• The Memory Layer: cuốn sách về các ý tưởng đằng sau graphify, kiến trúc từ đầu đến cuối

Graphify Cloud¶

Graphify Cloud là lớp luôn bật được xây dựng trên nền graphify. Thay vì một đồ thị bạn dựng lại theo nhu cầu cho từng thư mục, nó giữ một đồ thị sống duy nhất xuyên suốt toàn bộ vòng đời phát triển phần mềm của bạn:

• Ít hơn 80% token: bộ nhớ luôn bật nghĩa là các agent của bạn ngừng đọc lại và giải thích lại mã nguồn trong mỗi phiên.
• Monorepo và liên repo: một đồ thị kết nối duy nhất xuyên qua mọi dịch vụ và kho, chứ không phải một đồ thị cho mỗi thư mục.
• Kiểm chứng hình thức: kiểm tra các bất biến về kiến trúc và phụ thuộc đối với đồ thị sống.
• Rà soát code với góc nhìn bao quát toàn cảnh SDLC của bạn: thấy một thay đổi lan tỏa khắp cả hệ thống như thế nào trước khi bạn merge.
• Trình kết nối SDLC: kéo vào Sentry, Jira và nhiều hơn nữa, để sự cố, ticket, và code sống trong một đồ thị.
• Luôn bật: cập nhật liên tục ở nền xuyên qua code, tài liệu, và các cuộc họp.

Bắt đầu dùng thử miễn phí 14 ngày tại app.graphify.com →

Đóng góp¶

Hoan nghênh đóng góp. Xem CONTRIBUTING.md để biết thiết lập môi trường phát triển, các lệnh kiểm thử và CI-parity, quy trình git, và điều gì làm nên một đóng góp mạnh (các ví dụ thực tế và báo cáo lỗi trích xuất là hữu ích nhất). Kiến trúc và cách thêm một ngôn ngữ: ARCHITECTURE.md.

Mới đến? Chào một tiếng trên Discord hoặc trong GitHub Discussions.

Người đóng góp¶

Made with contrib.rocks.

Bản dịch¶

README có sẵn trong 32 ngôn ngữ. Dùng trình chuyển ngôn ngữ ở đầu tệp này để đọc bằng ngôn ngữ của bạn, hoặc duyệt docs/translations/. Để cải thiện một bản dịch hoặc thêm một bản mới, hãy mở một pull request đối với tệp tương ứng ở đó.

Xây dựng trên graphify¶

Đang xây dựng thứ gì đó trong hệ sinh thái graphify? Điều đó được khuyến khích. Nếu dự án của bạn dùng "graphify" trong tên (ví dụ graphify-dashboard hoặc graphify-action), vui lòng thêm một ghi chú ngắn vào README của bạn làm rõ rằng nó do cộng đồng xây dựng và không liên kết với hay được chứng thực bởi Graphify Labs. "graphify" và logo graphify là các nhãn hiệu của Graphify Labs; vui lòng đừng dùng chúng theo cách ngụ ý tư cách chính thức.

Cộng đồng và liên kết¶