Cài đặt Archscribe

Archscribe phân tích dự án Java Spring Boot và tạo tài liệu, sơ đồ thông qua dòng lệnh hoặc công cụ MCP trong trình AI. Hướng dẫn này dành cho gói archscribe đã phát hành trên npm, phiên bản đối chiếu 0.2.1.

Yêu cầu

• Node.js 18 trở lên và npm đi kèm
• Java JDK 17 trở lên, có lệnh java trong PATH
• Dự án Spring Boot dùng Maven hoặc Gradle, có src/main/java và pom.xml, build.gradle hoặc build.gradle.kts
• Nếu muốn dùng Archscribe trong trình AI, hãy cài sẵn ít nhất một trình được hỗ trợ: Claude Code, Codex CLI, Gemini CLI, OpenCode hoặc Antigravity

Kiểm tra môi trường trong terminal:

node --version
java -version
npx -y archscribe doctor /path/to/your-spring-boot-project

Trên Windows, thay đường dẫn ví dụ bằng đường dẫn thực tế, đặt trong dấu nháy kép nếu có khoảng trắng.

Kết nối với trình AI

Chạy một lần trên máy:

npx -y archscribe setup

Lệnh này tìm các trình AI đã cài. Khi chạy trong terminal tương tác, bạn có thể chọn trình muốn kết nối. Archscribe đăng ký MCP ở phạm vi người dùng cho Claude Code, Codex CLI, Gemini CLI và OpenCode. Với Antigravity, lệnh cập nhật ~/.gemini/config/mcp_config.json, giữ lại các server khác. Khởi động lại trình AI sau khi đăng ký.

Muốn chỉ đăng ký một hoặc vài trình, dùng --only với các tên dưới đây, phân cách bằng dấu phẩy:

Ví dụ:

npx -y archscribe setup --only codex,opencode

setup cần tìm thấy lệnh CLI tương ứng trong PATH, ngoại trừ Antigravity có thể chỉ định trực tiếp bằng --only antigravity. Nếu chưa cài trình AI nào, bạn vẫn có thể dùng lệnh run ở phần dưới mà không cần setup.

Thêm Archscribe vào dự án

Trong terminal, chạy:

npx -y archscribe scaffold /path/to/your-spring-boot-project

Lệnh tạo .mcp.json và .claude/skills/archscribe-docs/SKILL.md trong dự án. .mcp.json phục vụ cấu hình MCP theo dự án của Claude Code. Skill đi kèm dành cho Claude Code. Việc đăng ký ở phạm vi người dùng bằng setup đã đủ để các trình AI được chọn gọi MCP, nên scaffold không phải bước bắt buộc nếu bạn chỉ dùng kết nối người dùng.

Nếu file đã tồn tại, Archscribe bỏ qua thay vì ghi đè. Chỉ dùng --overwrite khi bạn đã kiểm tra nội dung cần giữ:

npx -y archscribe scaffold /path/to/your-spring-boot-project --overwrite

Khi chạy qua npx, cấu hình MCP do Archscribe tạo dùng lệnh npx để khởi động server, không phụ thuộc đường dẫn cache tạm. Lần đầu khởi động MCP cần npm tải gói từ registry nếu chưa có trong cache.

Kiểm tra và chạy

Kiểm tra CLI đang lấy từ npm:

npx -y archscribe version
npx -y archscribe doctor /path/to/your-spring-boot-project

Sau khi khởi động lại trình AI, mở dự án Spring Boot và yêu cầu AI dùng công cụ Archscribe để tạo tài liệu. Bạn cũng có thể chạy trực tiếp, không cần trình AI:

npx -y archscribe run /path/to/your-spring-boot-project
npx -y archscribe dashboard

dashboard mở giao diện cục bộ trong trình duyệt. Nếu chương trình yêu cầu kích hoạt license, dùng npx -y archscribe login và nhập key hợp lệ của bạn. Không đưa license key vào mã nguồn, tài liệu công khai hoặc ảnh chụp màn hình.

Xử lý lỗi thường gặp

Không cần clone repository hoặc chạy npm run build khi cài từ npm. Hai bước đó chỉ dành cho người phát triển Archscribe từ mã nguồn.