project-understand

Công cụ CLI và ứng dụng web tĩnh để trực quan hóa kiến trúc phần mềm dưới dạng đồ thị tri thức tương tác. Phân tích mã nguồn, tạo đồ thị cấu trúc, và xem trước trên trình duyệt — tất cả không cần AI agent.

Tính năng

• --analyze — Phân tích mã nguồn tĩnh, tạo đồ thị tri thức từ codebase (TypeScript, Python, Go, Rust, Java, Ruby, PHP)
• --preview — Server HTTP cục bộ hiển thị đồ thị tri thức dưới dạng biểu đồ lực D3.js tương tác
• --create-md — Tạo file cấu hình AI tool (skills, steering, hooks) cho 7 nền tảng

Bắt đầu nhanh

# Cài đặt toàn cục
npm install -g project-understand

# Phân tích dự án và tạo đồ thị tri thức
project-understand --analyze ./my-project

# Xem trước đồ thị trên trình duyệt
project-understand --preview ./my-project/.understand-anything

# Tạo cấu hình AI tool cho nền tảng của bạn
project-understand --create-md --type kiro

Các lệnh

--analyze [path]

Chạy phân tích mã nguồn tĩnh trên thư mục đích và tạo ra:

• .understand-anything/knowledge-graph.json — Đồ thị đầy đủ với nodes, edges, layers, và guided tour
• .understand-anything/meta.json — Metadata build (timestamp, git hash, số file)
• .understand-anything/domain-context.json — Context nhẹ cho phân tích domain

# Phân tích thư mục hiện tại
project-understand --analyze

# Phân tích dự án cụ thể
project-understand --analyze ./my-project

# Bắt buộc rebuild toàn bộ (bỏ qua chế độ incremental)
project-understand --analyze ./my-project --full

Phát hiện được:

• Cấu trúc file và dependencies (quan hệ import/export)
• Functions, classes, và quan hệ giữa chúng
• Các tầng kiến trúc (Presentation, API, Data, Utilities, v.v.)
• Entry points và tạo guided tour tự động
• Metadata dự án từ package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml

Ngôn ngữ hỗ trợ: TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, PHP, C#, C/C++, Swift, Kotlin

--preview <path>

Khởi động server HTTP cục bộ phục vụ dashboard trực quan hóa đồ thị tương tác.

# Xem trước thư mục chứa graph files
project-understand --preview .understand-anything

# Cổng tùy chỉnh
project-understand --preview ./dashboards --port 8080

# Tắt tự động mở trình duyệt và theo dõi file
project-understand --preview ./dashboards --no-open --no-watch

Tính năng:

• Bố cục đồ thị lực với D3.js
• Kéo thả, zoom, và pan
• Tooltip hiển thị metadata của node
• Hiển thị layer với vùng màu
• Điều hướng guided tour
• Bộ chọn hai cấp (project → graph file)
• Upload file JSON tùy chỉnh
• Live reload khi file thay đổi

--create-md [path]

Tạo file cấu hình AI coding tool cho dự án.

# Tạo cho Kiro
project-understand --create-md --type kiro

# Tạo cho Claude Code với openspec init
project-understand --create-md --type claude-code --init

# Tạo trong thư mục cụ thể
project-understand --create-md ./my-project --type codex

Nền tảng hỗ trợ:

| Type | Output | |------|--------| | kiro | .kiro/steering/ + .kiro/skills/ + .kiro/hooks/ | | codex | AGENTS.md + .codex/skills/ | | opencode | AGENTS.md + .opencode/skills/ | | claude-code | .claude-plugin/ (plugin.json + skills) | | openclaw | .agent/AGENT.md + .agent/skills/ + .agent/hooks/ | | cursor | .cursor/rules/ | | openspec | openspec/AGENTS.md + .github/instructions/ + .github/prompts/ |

Schema JSON của Dashboard

Đồ thị tri thức tuân theo schema sau:

{
  "version": "1.0.0",
  "project": {
    "name": "my-project",
    "description": "Mô tả dự án",
    "languages": ["typescript", "python"],
    "frameworks": ["express", "react"],
    "analyzedAt": "2026-05-06T00:00:00.000Z",
    "gitCommitHash": "abc123"
  },
  "nodes": [
    { "id": "src/index.ts", "type": "file", "name": "index.ts", "summary": "Entry point", "tags": ["typescript"] }
  ],
  "edges": [
    { "source": "src/index.ts", "target": "src/utils.ts", "type": "imports" }
  ],
  "layers": [
    { "id": "api", "name": "API", "description": "Route handlers", "nodeIds": ["src/routes.ts"] }
  ],
  "tour": [
    { "order": 1, "title": "Entry Point", "description": "Bắt đầu từ đây", "nodeIds": ["src/index.ts"] }
  ]
}

Phát triển

# Cài đặt dependencies
npm install

# Chạy tests
npm test

# Server phát triển (Astro frontend)
npm run dev

# Build tất cả (Astro + CLI)
npm run build:all

# Build CLI only
npm run build:cli

# Link để test cục bộ
npm link

Kiến trúc

src/
├── cli/                    # Mã nguồn CLI tool
│   ├── index.ts            # Entry point
│   ├── arg-parser.ts       # Phân tích tham số
│   ├── input-resolver.ts   # Phân giải file/thư mục cho --preview
│   ├── server.ts           # HTTP server (sirv + custom routes)
│   ├── watcher.ts          # Theo dõi file cho live reload
│   ├── bundle-path.ts      # Phân giải đường dẫn static bundle
│   ├── template-generator.ts # Tạo template cho --create-md
│   └── analyzer/           # Engine phân tích tĩnh cho --analyze
│       ├── index.ts         # Điều phối pipeline chính
│       ├── scanner.ts       # Khám phá file và phát hiện metadata
│       ├── parser.ts        # Trích xuất cấu trúc (TS/JS/Python/Go/Rust/Java)
│       ├── graph-builder.ts # Xây dựng node và edge
│       ├── layer-detector.ts # Nhận diện tầng kiến trúc
│       ├── tour-builder.ts  # Tạo guided tour
│       └── domain-context.ts # Trích xuất domain context
├── components/             # UI components frontend
├── lib/                    # Thư viện dùng chung (validator, renderer, tour)
├── types/                  # Định nghĩa TypeScript types
├── build/                  # Astro build-time integrations
├── layouts/                # Astro layouts
└── pages/                  # Astro pages

Yêu cầu

• Node.js >= 18.0.0

Tham khảo Skills

Skills là các workflow hỗ trợ AI mà agent có thể thực thi. Mỗi skill đọc đồ thị tri thức và thực hiện một tác vụ cụ thể.

| Skill | Mô tả | Cách dùng | Chức năng | |-------|--------|-----------|-----------| | /understand | Tạo đồ thị tri thức từ codebase | /understand [path] [--full] | Quét file nguồn, trích xuất functions/classes/imports, xây dựng nodes và edges, nhận diện layers, tạo guided tour. Xuất knowledge-graph.json và meta.json. | | /understand-chat | Hỏi đáp về codebase | /understand-chat "Auth hoạt động thế nào?" | Tìm kiếm nodes/edges liên quan trong đồ thị, truy vết chuỗi dependency, trả lời dựa trên dữ liệu cấu trúc. | | /understand-diff | Phân tích thay đổi code và tác động | /understand-diff | Lấy danh sách file thay đổi từ git diff, tìm nodes bị ảnh hưởng, truy vết 1-hop edges để xác định blast radius, đánh giá rủi ro. | | /understand-domain | Trích xuất kiến thức domain nghiệp vụ | /understand-domain [--full] | Nhận diện business domains, flows, và process steps. Tạo domain-graph.json với phân cấp 3 tầng (Domain → Flow → Step). | | /understand-explain | Giải thích chi tiết một component | /understand-explain src/auth/login.ts | Tìm node đích, truy vết tất cả edges liên quan, đọc file nguồn, giải thích vai trò và cấu trúc nội bộ. | | /understand-onboard | Tạo hướng dẫn onboarding | /understand-onboard | Đọc layers, tour, file nodes để tạo tài liệu onboarding có cấu trúc với tổng quan kiến trúc, khái niệm chính, bản đồ file. | | /understand-knowledge | Phân tích wiki/knowledge base | /understand-knowledge [wiki-dir] | Phát hiện wiki kiểu Karpathy, trích xuất entities, claims, và quan hệ ngầm, tạo đồ thị tri thức tương tác. | | /understand-baseline | Tạo snapshot spec | /understand-baseline [--label "v1.0"] | Lưu bản sao có timestamp của tất cả spec files để so sánh sau này. | | /understand-report | Tạo báo cáo tiến độ | /understand-report | So sánh spec hiện tại với baseline gần nhất, hiển thị thay đổi, tiến độ task, tốc độ, và ETA. | | /understand-mermaid | Render sơ đồ Mermaid | /understand-mermaid [--only NN] | Đọc diagrams.mermaid.md, trích xuất mermaid code blocks, render thành PNG. | | /understand-export | Xuất spec ra PDF | /understand-export [filename.md] | Chuyển đổi spec markdown thành PDF A4 landscape có đánh số trang. |

Tham khảo Agents

Agents là các prompt AI chuyên biệt được skills dispatch để thực hiện phân tích tập trung.

| Agent | Mục đích | Được gọi bởi | Kết quả | |-------|----------|--------------|---------| | project-scanner | Quét file dự án và phát hiện metadata | /understand | Inventory JSON của tất cả files với languages, frameworks, line counts, import maps. | | file-analyzer | Phân tích file nguồn theo batch | /understand | Graph nodes (file, function, class) và edges (imports, contains, calls) cho mỗi batch. | | architecture-analyzer | Nhận diện tầng kiến trúc | /understand | 3-10 layers logic với mỗi file được gán vào đúng một layer. | | tour-builder | Thiết kế guided tour học tập | /understand | 5-15 bước tour theo BFS từ entry point, có mô tả và language lessons. | | graph-reviewer | Kiểm tra tính đúng đắn của graph | /understand | Báo cáo validation kiểm tra schema, referential integrity, completeness, layer coverage. | | assemble-reviewer | Review chất lượng graph sau merge | /understand | Khôi phục nodes/edges bị mất, lấp gaps giữa các batch, remap unknown types. | | domain-analyzer | Trích xuất business domains và flows | /understand-domain | Domain graph với domains, flows, steps trong phân cấp 3 tầng. | | article-analyzer | Trích xuất kiến thức từ wiki articles | /understand-knowledge | Entities, claims, và quan hệ ngầm (builds_on, contradicts, exemplifies). | | knowledge-graph-guide | Hướng dẫn người dùng sử dụng graph | Theo yêu cầu | Hướng dẫn cấu trúc graph, query bằng jq, hiểu quan hệ node/edge, sử dụng dashboard. |

Tham khảo Hooks

Hooks là các trigger tự động chạy khi sự kiện cụ thể xảy ra.

| Hook | Trigger | Chức năng | |------|---------|-----------| | Auto-Update Graph | PostToolUse (sau git commit) | Phát hiện commits khi autoUpdate bật. Trigger cập nhật incremental bằng structural fingerprinting — chỉ re-analyze files có thay đổi cấu trúc thực sự. Zero LLM tokens cho thay đổi cosmetic. | | Stale Graph Check | SessionStart | Khi bắt đầu session, so sánh git hash trong meta.json với HEAD hiện tại. Nếu khác, nhắc cập nhật graph. | | Baseline Spec Status | UserTriggered (thủ công) | Tạo snapshot có timestamp của tất cả spec files để theo dõi tiến độ. | | Export Spec to PDF | UserTriggered (thủ công) | Xuất tất cả spec markdown ra PDF. | | Spec Progress Report | UserTriggered (thủ công) | Tạo báo cáo tiến độ so sánh specs hiện tại với baseline gần nhất. | | Render Mermaid Diagrams | FileEdited (diagrams.mermaid.md) | Tự động render tất cả sơ đồ Mermaid thành PNG khi file nguồn được lưu. |