description: "Research phase orchestrator: Multi-Agent Socratic Debate for Keyword Filtering (CMO + Forecaster + Planner)" version: "1.0"

/seo-research-keywords

Purpose

Executes Phase C: Keyword Harvesting & Filtering using a Multi-Agent Keyword Council.

• Bước 1: Gọi API Solann để thu thập từ khóa truyền thống và từ khóa đuôi dài. Áp dụng Vector Filtering và Knowledge Graph Whitelist.
• Bước 2: Multi-Agent Socratic Debate. Các Subagent (CMO, Forecaster) sẽ tranh biện về từng nhóm từ khóa (Vector Grouped).
• Bước 3: Planner (Trọng tài) tổng hợp điểm và quyết định Approved/Rejected. Các từ khóa dưới ngưỡng an toàn (<80%) sẽ được chuyển ra file duyệt thủ công (Manual Review).

Quy trình này đáp ứng triết lý "Đốt token lấy chất lượng" bằng cách kiểm chứng đa chiều, đồng thời tiết kiệm tài nguyên nhờ thuật toán gom cụm (Vector Clustering) để giảm thiểu số lượt gọi search_web.

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 knowledge-graph.json đã hoàn tất (từ /seo-research-knowledge-graph).

Checkpointing & Session Recovery

💡 Khôi phục ngữ cảnh (Session Reset Recovery): Nếu gặp lỗi API giới hạn (Rate Limits) khi cào SERP hoặc cạn token, hệ thống sẽ khôi phục trực tiếp tiến trình dựa trên các file .toon đã phân lô. Không bao giờ chạy lại các từ khóa đã duyệt.

Sub-Agent Coordination

• Primary Executor: @[topical-authority-planner] (harvests core keyword lists and runs debate filters)
• Co-owner: @[seo-bi-analyst] (validates organic volume metrics and competitor rankings)

Execution Flow

Step 0: Khởi tạo Luật loại trừ động

• Nạp tệp .seo/data/dynamic_exclusions.toon (được sinh ra từ pha /seo-onboard) làm Ground Rules (Hiến pháp) để loại bỏ các từ khóa sai Brand DNA hoặc sai Industry.

Step 1: Long-tail Keyword Discovery & Semantic Vector Grouping

• Dùng bộ từ khóa hạt giống (Seed keywords) kết hợp các thực thể từ Knowledge Graph để kéo danh sách từ khóa đuôi dài có volume tìm kiếm thực tế qua Solann API.
• Áp dụng Knowledge Graph Whitelist: Bỏ qua thuật toán loại trừ ngoại ngữ cho các từ khóa thuộc Knowledge Graph.
• Gom nhóm ngữ nghĩa (Vector Grouping) bằng thuật toán nhúng. Chọn ra 1 từ khóa đại diện (Representative Keyword) cho mỗi cụm nghi vấn.
• Lệnh: python .agents/skills/seo-plan/scripts/hybrid_query_harvester.py {domain} --action harvest_and_group
• Output tạm:
  • .seo/data/temp_high_relevance.json (An toàn)
  • .seo/data/content_plan_batches/ambiguous_groups.toon (Cần Hội đồng duyệt)
  • .seo/data/harvesting_rejected_log.json (Lưu vết audit các từ khóa bị loại)

Step 2: Socratic Short-Circuit Pipeline (The Keyword Council)

Với các nhóm từ khóa nghi vấn trong ambiguous_groups.toon, kịch bản Python kích hoạt luồng Đoản mạch đa tầng (Pipeline) với cơ chế Batching (Max 3 subagents) để chống lỗi 429:

1. Vòng 1 (Fast DNA Filter) - seo-cmo Agent:

   • Dùng file: [cmo_evaluator.md](/documents/vi/antigravity-seo-kit/latest/workflows/../../skills/seo-keyword/prompts/cmo_evaluator) kết hợp dynamic_exclusions.toon.
   • Chấm brand_score. Nếu <40%, loại thẳng (đoản mạch).
   • Xuất kết quả: cmo_evaluations.toon.

2. Vòng 2 (Deep SERP Scan) - algo-forecaster Agent:

   • Chỉ chạy cho các từ khóa vượt qua Vòng 1.
   • Dùng file: [forecaster_serp.md](/documents/vi/antigravity-seo-kit/latest/workflows/../../skills/seo-keyword/prompts/forecaster_serp)
   • Dùng search_web tìm rủi ro đối thủ, đồng âm. Chấm risk_score (TOON format).

3. Vòng 3 (The Judge) - topical-authority-planner Agent:

   • Dùng file: [council_judge.md](/documents/vi/antigravity-seo-kit/latest/workflows/../../skills/seo-keyword/prompts/council_judge)
   • Chốt confidence_score cuối cùng.
   • Xuất kết quả: council_decisions.toon.

Step 3: Xử lý Vùng xám bằng Deep-Dive Researcher

• Kịch bản Python phân loại kết quả từ Hội đồng:
  • confidence >= 80%: Approved
  • confidence <= 30%: Rejected
  • 30% < confidence < 80%: Giao cho Subagent chuyên sâu.
• Lệnh: python .agents/skills/seo-plan/scripts/hybrid_query_harvester.py {domain} --action deep_dive_research --batch-size 3
• Kích hoạt Deep Researcher Agent sử dụng prompt [deep_researcher.md](/documents/vi/antigravity-seo-kit/latest/workflows/../../skills/seo-keyword/prompts/deep_researcher). Agent này sẽ cào 3 URL top đầu trên Google, đọc nội dung để phán quyết lần cuối. Chỉ các trường hợp cực đoan thất bại mới xuất ra manual_review.toon.

Step 4: Final Query Import & Consolidation

• Hợp nhất từ khóa độ tin cậy cao ban đầu, từ khóa Approved bởi Hội đồng/Deep-Dive.
• Liên tục lưu vết các từ khóa bị loại bỏ vào tệp audit harvesting_rejected_log.json.
• Lệnh: python .agents/skills/seo-plan/scripts/hybrid_query_harvester.py {domain} --action import_final
• Output chính: .seo/data/keywords.json.

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 Keyword Harvesting — `{domain}`

**Trạng thái**: Hoàn tất thu hoạch & Hội đồng AI đã duyệt (Phase 2/5)

## 📊 Tổng quan Từ khóa

Hội đồng Multi-Agent Keyword Council đã tranh biện và chắt lọc thành công bộ từ khóa:

- **✅ Từ khóa được duyệt (Approved)**: **{total}** từ khóa chất lượng cao.
- **🗑️ Từ khóa bị loại (Rejected)**: **{rejected}** từ khóa (do sai intent, ngoại ngữ, hoặc điểm tự tin quá thấp).
- *(Tóm tắt nhanh phân bổ từ khóa nếu có dữ liệu, VD: bao nhiêu từ khóa ngắn, bao nhiêu từ khóa dài)*

## 🔍 Insight Nổi Bật

*(Trích xuất một số điểm đáng chú ý từ quá trình tranh biện của hội đồng AI)*
- **Rủi ro đã loại bỏ**: [Ví dụ: Phát hiện và loại bỏ các từ khóa đồng âm, từ khóa của đối thủ cạnh tranh trực tiếp]
- **Xu hướng tìm kiếm**: [Đặc điểm chung của nhóm từ khóa được duyệt]

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

- **Từ khóa chính thức**: `.seo/data/keywords.json`
- **Lịch sử loại trừ (Audit Log)**: `.seo/data/harvesting_rejected_log.json`
- **Dấu thời gian**: {thời gian hoàn tất}

---

💡 **Bước tiếp theo (Next Step):**
Để tiếp tục mở rộng các từ khóa này thành truy vấn hội thoại, hãy chạy lệnh:
👉 `/seo-research-query` (RAG Fan-out)