description: "Research phase orchestrator: Multi-Agent Consensus Knowledge Graph Mapping" version: "1.0"

/seo-research-knowledge-graph

Purpose

Generates a robust Entity Knowledge Graph through an autonomous Multi-Agent Socratic Debate. It ensures that the targeted entities are not just randomly crawled, but are deeply aligned with the brand's DNA, Google's knowledge graph (Wikidata QIDs), and AI Search Overviews (GEO).

Skills Activated (up to 10)

Prerequisites

• Yêu cầu cấu hình dự án project.json đã có sẵn.
• Yêu cầu audience.json đã có sẵn (từ /seo-research-audience).

Checkpointing & Session Recovery

💡 Khôi phục ngữ cảnh (Session Reset Recovery): Nếu gặp lỗi mạng hoặc vượt quá số lượng token, hệ thống sẽ khôi phục trực tiếp tiến trình từ project.json.workflow_checkpoint.

Sub-Agent Coordination

• Primary Executor: @[topical-authority-planner] (extracts entities and mapping connections)
• Sub-Agents: @[schema-engineer] (audits sameAs references and prepares JSON-LD context), @[algo-forecaster] (analyzes Wikidata QID and AI search visibility)

Execution Flow

Step 1: Init Project & Context Preparation

• Đọc SLUG = domain.replace('.', '-') ➔ nạp cấu hình từ .seo/project.json và .seo/data/audience.json.
• Chạy kịch bản Python để tự động trích xuất các biến ngữ cảnh (Context Variables) và xuất ra file JSON:
  • Lệnh: python .agents/scripts/run_plugin_script.py seo-entity knowledge_graph_generator.py {domain} --action prepare
  • Tích hợp tri thức khách hàng: Script tự động quét chỉ mục tri thức khách hàng (knowledge_index.json) để lấy các thực thể sản phẩm/dịch vụ đã nạp qua /seo-knowledge-add và điền vào client_entities trong tệp context để làm định hướng Debate.
  • Output: .seo/data/content_plan_batches/kg_context.json

Step 2: "Fractal Search & Validate" Architecture

Để đạt hiệu quả tối đa và đảm bảo Knowledge Graph mang tính thực tế (không Hallucination), Orchestrator sẽ kích hoạt kiến trúc Tìm kiếm Phân rã Đệ quy:

• Vòng 1 (Khởi tạo Core Pillars - Discovery):

  • Tác nhân: topical-authority-planner (vai trò Ontology Architect).
  • Prompt: [kg_round1_architect.md](/documents/vi/antigravity-seo-kit/latest/workflows/../../skills/seo-entity/prompts/kg_round1_architect)
  • Hành động: BẮT BUỘC dùng công cụ search_web tìm kiếm các nguồn chuẩn E-E-A-T (như Glossary, Wikipedia của ngành, tổ chức uy tín) để xác định 5-10 Core Pillars (Level 1). Dữ liệu phải đến từ Search, không phải dự đoán.

• Vòng 2 (Deep Fractal Expansion - Breadth-First):

  • Từ danh sách Core Pillars đã chốt ở Vòng 1, Orchestrator chia thành các lô (batch of 3). TUYỆT ĐỐI không gọi quá 3 sub-agents cùng lúc để tránh lỗi API 429.
  • Với mỗi Core Pillar, invoke 1 sub-agent topical-authority-planner mới:
    • Prompt: [kg_round2_fractal_expansion.md](/documents/vi/antigravity-seo-kit/latest/workflows/../../skills/seo-entity/prompts/kg_round2_fractal_expansion)
    • Hành động: Sub-agent dùng search_web đệ quy cho từng sub-category. Dừng lại khi đạt trạng thái "cạn kiệt ngữ nghĩa" (LLM nhận định không còn entity thực tế nào mới trên SERP).

• Vòng 3 (Validation & Human-in-the-loop Review):

  • Kết quả từ Vòng 2 được chuyển qua algo-forecaster và seo-cmo để cắt tỉa (Pruning) các Entity thiếu Search Volume thực tế hoặc sai lệch Brand DNA.
  • Sau đó, đóng gói kết quả thành bản nháp Markdown (Draft) trực quan.
  • Prompt: [kg_round3_human_review.md](/documents/vi/antigravity-seo-kit/latest/workflows/../../skills/seo-entity/prompts/kg_round3_human_review)

🛑 PAUSE Gate 1b: Phê duyệt bản nháp (Draft Review)

• Trình bày bản nháp Knowledge Graph (dưới dạng UI Artifact Markdown) cho người dùng.
• Buộc dừng lại (Stop) và chờ người dùng phản hồi.
• Người dùng có thể yêu cầu:
  • Sửa đổi/Xóa nhánh bị lạc đề.
  • Thêm nhánh mới.
  • Đồng ý (Approve) để tiếp tục.

Step 3: TOON Serialization & Consolidate

• Vòng 4 (Chunked TOON Serialization):
  • Sau khi người dùng duyệt, gọi prompt để ép kiểu dữ liệu nháp đã chốt thành TOON.
  • Prompt: [kg_round4_toon_serializer.md](/documents/vi/antigravity-seo-kit/latest/workflows/../../skills/seo-entity/prompts/kg_round4_toon_serializer)
  • Lưu mỗi nhánh thành file riêng: .seo/data/content_plan_batches/kg_results_batch_*.toon (Ví dụ: kg_results_batch_1.toon).
• Chạy kịch bản Python để tự động giải mã TOON, làm sạch định dạng, gán nhãn thực thể brand và xuất cơ sở dữ liệu sơ đồ thực thể tri thức hoàn chỉnh.
  • Lệnh: python .agents/scripts/run_plugin_script.py seo-entity knowledge_graph_generator.py {domain} --action import
  • Output: .seo/data/knowledge-graph.json lưu giữ sơ đồ thực thể tri thức hợp nhất chuẩn GEO.
• Cập nhật project.json.workflow_checkpoint với {workflow: "seo-research-knowledge-graph", status: "completed"}.

Final Dashboard

Trình bày báo cáo tổng kết (Final Dashboard) bằng Markdown trực quan, hướng người dùng (user-facing) và cung cấp thông tin chi tiết về tập dữ liệu vừa tạo. Tránh dùng hộp ASCII khô khan. Sử dụng template sau:

# 🎯 Báo cáo Knowledge Graph — `{domain}`

**Trạng thái**: Hoàn tất trích xuất & xây dựng Sơ đồ tri thức

## 📊 Tổng quan Sơ đồ Tri thức

Hệ thống đã trinh sát đối thủ và phân rã đệ quy để thiết lập sơ đồ tri thức chuẩn GEO:

- **🏷️ Tổng số Thực thể (Entities) trích xuất**: **{count}** thực thể
- **Core Pillars (Level 1)**: *(Liệt kê 3-5 Pillars cốt lõi nhất ở đây)*
- **Tính xác thực**: Đã đối chiếu chéo với GEO và Wikidata QID để đảm bảo E-E-A-T.

## 🔍 Cấu trúc Phân rã (Hiển thị mẫu)

*(Trích xuất một nhánh tiêu biểu để hiển thị demo cho người dùng)*
- **[Tên Pillar L1]**
  - [Tên Sub-Pillar L2]
    - [Tên Topic L3]

## 📁 Dữ liệu & Lưu trữ

- **Sơ đồ tri thức JSON**: `.seo/data/knowledge-graph.json`
- **Dấu thời gian**: {thời gian hoàn tất}

---

💡 **Bước tiếp theo (Next Step):**
Sơ đồ tri thức đã hoàn chỉnh. Hãy chạy lệnh tiếp theo để thiết lập các câu hỏi theo dõi SoV thương hiệu và định vị thương hiệu trên AI Search (AI Share of Voice Prompts):
👉 `/seo-research-brand-prompts`