Kiến Trúc Không Gian Dự Án (1 Domain — 1 Antigravity Project)
Trong các phiên bản Google Antigravity mới nhất, thuật ngữ làm việc đã được chuẩn hóa đổi tên từ "Workspace" sang "Project" (Dự án Antigravity). Antigravity SEO Kit tuân thủ nguyên tắc thiết kế Project-Scoped Convention (.seo/): Mỗi Antigravity Project (thư mục dự án mở trong Antigravity) sẽ dành riêng cho 1 Domain duy nhất và được quản trị tập trung tại thư mục ẩn .seo/ ở góc thư mục gốc.
🎯 Triết Lý Thiết Kế 1 Domain Trong 1 Antigravity Project
Vì sao SEO Kit không gộp nhiều domain vào chung một Project Antigravity mà lại quy định 1 Project Antigravity = 1 Domain SEO (.seo/)?
- Cô lập Ngữ cảnh (Context Isolation): Tránh hiện tượng rò rỉ dữ liệu (Cross-domain leakage) giữa các khách hàng hoặc các dự án khác nhau khi AI Agent thực hiện suy luận.
- Tối ưu hóa Token Cache: AI Agent chỉ cần duy trì ngữ cảnh của duy nhất tên miền đang thao tác, giúp phản hồi nhanh hơn và tiết kiệm tới 80% token tiêu thụ.
- Tích hợp Git & DevOps: Thư mục
.seo/nằm trực tiếp trong mã nguồn của website/dự án, giúp dễ dàng đưa vào quy trình quản lý phiên bản Git, CI/CD và triển khai tự động.
📂 Sơ Đồ Cấu Trúc Thư Mục Dự Án .seo/
Khi bạn khởi tạo dự án bằng /seo-run <domain> hoặc /seo-onboard, SEO Kit sẽ tự động tạo cấu trúc thư mục quản trị tại .seo/:
.seo/
├── project.json # Single Source of Truth: Trạng thái, cấu hình, state machine, KPIs
├── exclusions.json # Danh sách từ khóa loại trừ động (Homonyms & nhiễu ngữ nghĩa)
├── competitors.json # Cache danh sách các đối thủ cạnh tranh đã xác minh
├── knowledge/ # Client Knowledge Vault (Tri thức khách hàng phân cấp .md)
│ ├── brand_dna/ # USP, Brand Voice, Chân dung khách hàng (ICP)
│ ├── products_services/# Chi tiết sản phẩm, dịch vụ, bảng giá
│ ├── internal_data/ # Case studies thực tế, báo cáo số liệu nội bộ
│ └── compliance/ # Quy định pháp lý ngành, danh sách từ cấm YMYL
├── data/ # Data Lake dữ liệu máy đọc (.json & .toon)
│ ├── audience.json # Chân dung độc giả & hành trình tìm kiếm
│ ├── knowledge-graph.json # Bản đồ thực thể ngữ nghĩa
│ ├── keywords.json # Vũ trụ từ khóa đã lọc sạch
│ ├── clusters.json # Cụm từ khóa ngữ nghĩa
│ ├── topical-map.json # Sơ đồ bao phủ chủ đề (Topical Authority)
│ ├── content-plan.json # Kế hoạch bài viết & ma trận liên kết
│ └── knowledge_index.toon # Chỉ mục phẳng nạp nhanh tri thức
├── reports/ # Thư mục chứa báo cáo Markdown dành cho người đọc
│ ├── onboard-{date}.md # Báo cáo khởi tạo & định vị thương hiệu
│ ├── audit-{date}.md # Báo cáo audit kỹ thuật toàn diện
│ ├── strategy-{date}.md# Báo cáo chiến lược 30/60/90 ngày
│ └── roadmap-{date}.md # Lộ trình thực thi chi tiết
├── fixes/ # File mã nguồn sửa lỗi, JSON-LD Schema sẵn sàng deploy
├── screenshots/ # Ảnh chụp màn hình phân tích giao diện Visual SEO
└── scratch/ # Thư mục xử lý dữ liệu trung gian ngầm
🏷️ Quy Tắc Chuẩn Hóa Domain & Domain Slug
Hệ thống tự động chuyển đổi URL đầu vào thành Domain FQDN và Slug chuẩn hóa:
- URL đầu vào:
https://www.example.com/blog?ref=123 - Domain FQDN:
example.com(Loại bỏhttps://,http://,www.và đường dẫn phụ) - Domain Slug:
example-com(Thay thế tất cả ký tự không phải chữ cái/số thành dấu gạch ngang-)
Ví dụ thêm:
https://shop.example.co.uk→ Domain:shop.example.co.uk| Slug:shop-example-co-uk
📊 Chi Tiết Schema Của project.json
Tệp project.json là Single Source of Truth lưu trữ toàn bộ trạng thái sống của dự án. Dưới đây là các trường thông tin cốt lõi:
| Trường (Field) | Kiểu dữ liệu | Mô tả |
|---|---|---|
domain | string | Tên miền chính đã chuẩn hóa (ví dụ: example.com) |
slug | string | Slug đại diện của tên miền (ví dụ: example-com) |
industry | string | Ngành hàng chính (saas, ecommerce, local, publisher, agency, corporate) |
phase | string | Giai đoạn hiện tại của dự án theo Phase State Machine |
health_score | number | Điểm sức khỏe SEO tổng hợp (0-100) từ đợt Audit gần nhất |
phase_history | array | Nhật ký ghi nhận mốc thời gian và điểm số khi chuyển phase |
settings | object | Cấu hình thị trường mục tiêu (target_market), ngôn ngữ (language_code), kênh SEO (target_channels), KPIs và thông điệp thương hiệu (brand_guidelines) |
source_context | object | Ngữ cảnh nguồn sâu: Anchor chính/phụ (dna), điểm E-E-A-T (credibility), uy tín domain (authority), mức độ sẵn sàng AI Search (search_grounding), và thông tin thực thể doanh nghiệp (brand_entity) |
runs | array | Lịch sử các lần chạy workflow (Audit, Strategy, Monitor...) |
experiments | array | Danh sách các thử nghiệm SEO A/B đang theo dõi |
🔄 Phase State Machine (Ma Trận Chuyển Đổi Vòng Đời)
Mỗi dự án trong .seo/project.json tuân theo luồng chuyển dịch giai đoạn chặt chẽ:
(no project) → greenfield / onboarded → researched → audited → strategized → executed → monitoring
│ │
└── (skip) ──▶ audited (cho phép bỏ qua) └─▶ audited (chu kỳ re-audit)
greenfield: Dành cho tên miền mới chưa xuất bản (chưa live). Hệ thống sẽ bỏ qua bước cào dữ liệu live.onboarded: Đã hoàn thành/seo-onboard, xác định xong định vị thương hiệu và ICP.researched: Đã hoàn thành/seo-research&/seo-content-plan, có sẵn bộ dữ liệu từ khóa và topical map.audited: Đã hoàn thành/seo-audit, có điểm số Health Score và danh sách lỗi cần sửa.strategized: Đã hoàn thành/seo-strategy, có lộ trình 30/60/90 ngày.executed: Đã hoàn thành/seo-execute, đã xuất ra các file sửa lỗi/bài viết.monitoring: Đã hoàn thành/seo-monitor, đang theo dõi hiệu suất thứ hạng và AI Search.
🛠️ Cơ Chế Định Vị Dự Án project_helper.get_project_dir()
Tất cả các tập lệnh Python của SEO Kit tuyệt đối không hardcode hoặc tính toán đường dẫn động bằng chuỗi thô. Các tập lệnh luôn gọi hàm chuẩn hóa:
from project_helper import get_project_dir
# Tự động trả về đường dẫn tới .seo/ trong Antigravity Project hiện tại
PROJECT_DIR = get_project_dir()
Cơ chế này giúp đảm bảo 100% các script chạy đúng môi trường dự án mà không bị lẫn lộn giữa các thư mục làm việc khác nhau.