description: "Utility: Client Knowledge Base — Ingest brand data, pricing, products, or guidelines to Client Knowledge Vault" version: "1.0"

/seo-knowledge-add [--file-path ] [--content ""] [--type ] [--access ] [--entities ""] [--title "

Purpose

Workflow này dùng để nạp tài liệu độc quyền hoặc thông tin đặc thù của khách hàng (Client Knowledge Base) vào dự án SEO một cách chuẩn hóa. AI Agent đóng vai trò gác cổng phân tích nội dung, tự động trích xuất thực thể, phân loại nhóm tài liệu và đề xuất cấp độ bảo mật phù hợp, sau đó Python sẽ thực thi việc lưu trữ và lập chỉ mục.

Parameters

Execution Flow (Quy Trình Thực Hiện)

Step 0.5: Pre-flight Onboarding Check (Cảnh báo Onboarding)

• AI Agent kiểm tra sự tồn tại của tệp cấu hình dự án gốc .seo/project.json.
• Nếu không tìm thấy .seo/project.json:
  • Agent bắt buộc hiển thị cảnh báo:

    "⚠️ CẢNH BÁO: Dự án này chưa được Onboard chính thức (thiếu project.json). Việc nạp tài liệu lúc này sẽ được chạy ở chế độ offline (sandbox), AI Agent sẽ không có thông tin cấu hình target market và ngôn ngữ mục tiêu để trích xuất thực thể tối ưu nhất. Khuyên dùng: Chạy /seo-onboard trước để thiết lập dự án chuẩn."

  • Agent dừng lại hỏi người dùng có muốn tiếp tục ở chế độ offline không hay tạm dừng để chạy /seo-onboard trước.
  • Chờ phản hồi của người dùng trước khi tiến hành Step 1.

Step 1: Kiểm Tra và Đọc Nội Dung Đầu Vào

• Nếu cung cấp --file-path: Đọc nội dung thô từ file được chỉ định. Nếu file không tồn tại hoặc lỗi, báo lỗi và dừng lại.
• Nếu cung cấp --content: Sử dụng văn bản thô được truyền trực tiếp.
• Nếu cả hai đều rỗng: Dừng lại và yêu cầu người dùng cung cấp tài liệu hoặc văn bản.

Step 2: AI Phân Tích Ngữ Nghĩa (Semantic Ingestion Analysis)

AI Agent (LLM) đọc nội dung tài liệu thô và tiến hành phân tích các yếu tố sau (chỉ phân tích nếu tham số không được truyền thủ công):

1. Trích xuất Tiêu đề (title): Xác định tiêu đề tài liệu ngắn gọn, súc tích và phản ánh đúng nội dung.
2. Xác định Nhóm Tài liệu (type):
   • brand_dna: Sứ mệnh, giá trị cốt lõi, hướng dẫn giọng điệu, USP.
   • products_services: Bảng giá, tính năng, chi tiết dịch vụ, quy trình cung cấp.
   • internal_data: Case studies thành công, báo cáo số liệu độc quyền để lấy Information Gain.
   • compliance: Quy định pháp lý ngành, chính sách bảo mật, từ khóa nhạy cảm cấm dùng (YMYL).
3. Xác định Cấp độ Bảo mật (access):
   • public: Được trích dẫn nguyên văn vào bài viết.
   • restricted: Chỉ đọc để định hướng văn phong/USP, nghiêm cấm trích dẫn nguyên văn (ví dụ: bí mật công nghệ, chiến lược nội bộ).
   • validation_only: Chỉ dùng để đối chiếu ở bước Validate (Step 5 của /seo-write), không dùng để viết nháp.
4. Trích xuất Thực thể (entities): Liệt kê 3-8 thực thể chính (danh từ riêng, thuật ngữ kỹ thuật, tên dịch vụ) liên quan trực tiếp đến nội dung file.

Step 3: Thực Thi PAUSE Gate (🛑 Cổng Dừng Phê Duyệt)

AI Agent hiển thị bảng tóm tắt đề xuất Frontmatter và yêu cầu người dùng xác nhận hoặc điều chỉnh:

🛑 **PAUSE: Phê Duyệt Nạp Tài Liệu Tri Thức Khách Hàng**

Hệ thống đã phân tích tài liệu và đề xuất cấu trúc lưu trữ như sau:

| Thuộc Tính | Đề Xuất Của AI | Trạng Thái |
|------------|----------------|------------|
| **Tiêu đề (Title)** | `{suggested_title}` | [AI-Suggested] |
| **Phân loại (Type)**| `{suggested_type}` | [AI-Suggested] |
| **Quyền truy cập (Access)** | `{suggested_access}` | [AI-Suggested] |
| **Thực thể (Entities)** | `{suggested_entities}` | [AI-Suggested] |

**Đường dẫn lưu dự kiến:** `.seo/knowledge/{type}/{filename}.md`

Bạn muốn:
(A) Đồng ý lưu tài liệu với các thông số trên (Nhập "OK" hoặc "A")
(B) Chỉnh sửa thông số (Ví dụ nhập: "Đổi quyền truy cập thành restricted" hoặc "Thêm thực thể: đào tạo seo")
(C) Hủy bỏ nạp tài liệu này

DỪNG LẠI và CHỜ phản hồi từ người dùng. Không được tự động lưu file khi chưa được phê duyệt.

Step 4: Python Thực Thi Ghi File & Cập Nhật Chỉ Mục

Sau khi nhận được xác nhận OK từ người dùng, Agent gọi script Python để lưu trữ file và đồng bộ hóa index:

python .agents/scripts/run_plugin_script.py seo-core knowledge_orchestrator.py save \
  --content "<full_cleaned_content>" \
  --title "<confirmed_title>" \
  --type "<confirmed_type>" \
  --access "<confirmed_access>" \
  --entities "<confirmed_entities>" \
  --project-dir <project_dir>

Step 5: Báo Cáo Hoàn Tất

• Hiển thị thông báo xác nhận đã lưu file thành công kèm đường dẫn file cụ thể.
• Thông báo chỉ mục .seo/data/knowledge_index.toon đã được đồng bộ hóa thành công.
• Gợi ý bước tiếp theo (ví dụ: chạy /seo-write viết bài dựa trên thực thể vừa nạp).