✓ Mã nguồn đã tải đủ 3 kho ⚡ Model Context Protocol v1.3 🛡️ Fail-Closed PolicyGuard

Báo Cáo Phân Tích Toàn Diện Hệ Sinh Thái Zalo AI Bot & PPTmaster

Khám phá kiến trúc chi tiết, phân luồng dữ liệu (Pipelines), bộ quy tắc suy luận AI (Prompts), phân quyền 2 tầng chống Jailbreak và cỗ máy biên dịch Native PowerPoint từ mã đồ họa vector.

🏛️ 1. Bức Tranh Toàn Cảnh Hệ Sinh Thái

Hệ sinh thái này là sự kết hợp của 3 phân hệ độc lập nhưng gắn kết chặt chẽ, biến một tài khoản Zalo thông thường thành một trợ lý AI thông minh cấp doanh nghiệp:

1. abs-zalo-bot

Cổng kết nối Zalo Gateway 2 chiều (Zalo cá nhân quét QR + Zalo OA Webhook HMAC). Cung cấp máy chủ MCP Server Standard v1.3.0 cho Claude Code, Hermes, Cursor và Codex.

Node.js 22.5+ MCP stdio node:sqlite Port 3871

2. 2anh-zalo-bot

Cầu nối Sidecar chuyên sâu kết nối Hermes Agent qua WebSocket nội bộ. Tích hợp Token-Bucket Rate Limiter chống khóa nick, phân quyền 2 lớp Owner/Public, lịch sử SQLite và TTS VieNeu v3.

zca-js Sidecar Hermes Platform Rate Limiter Port 3872/3873

3. PPTmaster

Cỗ máy tự động hóa thuyết trình bằng AI. Biên dịch mã đồ họa vector SVG thành PowerPoint DrawingML Native với 187 hình khối chuẩn Office, chỉnh sửa 100%, tạo thuyết minh audio & video.

Python 3.10+ skia-pathops uharfbuzz edge-tts

Nguyên lý phối hợp tổng thể:

Người dùng nhắn tin qua Zalo ➔ Gateway/Sidecar bắt tin nhắn an toàn (lọc spam, che giấu OTP) ➔ Chuyển qua Hermes Agent / AI Brain bằng WebSocket nội bộ hoặc MCP Server ➔ AI Agent suy luận và gọi các công cụ (Tra cứu kho tài liệu nội bộ, điều tra thông tin, hoặc kích hoạt PPTmaster tạo slide) ➔ Kết quả được chuẩn hóa theo thể thức hành chính Việt Nam và gửi ngược lại nhóm Zalo qua thuật toán điều tiết nhịp độ.

🤖 2. Phân Hệ abs-zalo-bot (Gateway & MCP Engine)

Được xây dựng theo triết lý Fail-Closed PolicyGuard, đảm bảo hệ thống không bao giờ tự ý gửi tin bừa bãi khi chưa được cấu hình cho phép.

Tính năng Kiến trúc Cốt lõi

  • Dual-Adapter: Chạy song song Zalo cá nhân (quét mã QR) và Zalo Official Account (Webhook bảo mật chữ ký HMAC SHA-256).
  • MCP Server v1.3.0: Phơi bày hơn 15 công cụ AI chuẩn quốc tế kết nối trực tiếp với Claude Code / Cursor.
  • Corpus SQLite Multi-tenant: Sử dụng node:sqlite thuần JavaScript trong Node 22.5+, không cần compile thư viện C++.
  • KeepAlive Hub 24/7: Định kỳ kiểm tra nhịp tim mỗi 20 giây và tự động kết nối lại khi rớt mạng.

3 Gói Quyền Hạn (Capability Packs)

reader (Chỉ đọc): Kiểm tra trạng thái bot, đọc danh sách nhóm, thống kê corpus tin nhắn gần đây. Không có rủi ro.
operator (Vận hành): Tạo cuộc bình chọn (poll), khóa bình chọn, thả cảm xúc emoji, thu hồi tin nhắn, tra cứu hồ sơ người dùng.
admin (Quản trị tối cao): Trục xuất thành viên, chuyển quyền Trưởng nhóm, bổ nhiệm Phó nhóm. Bắt buộc phải có mã xác nhận OTP (TTL 5 phút).

Cơ chế Chốt An Toàn Mã Xác Nhận (Confirmation Protocol):

{
  "status": "confirmation_required",
  "requires_confirmation": true,
  "action": "kick_member",
  "confirmation_code": "A8F3C1",
  "expires_in_seconds": 300,
  "warning": "⚠️ HÀNH ĐỘNG NHẠY CẢM: Thao tác này có tính phá hủy. Để thực thi, vui lòng gọi lại kèm confirmation_code='A8F3C1' trong 5 phút."
}

🌉 3. Phân Hệ 2anh-zalo-bot (Hermes Agent Sidecar Bridge)

Giải pháp bridge chuyên dụng của thầy Lương Hải Anh, kết nối Zalo với framework Hermes Agent qua kiến trúc WebSocket nội bộ và cơ chế bảo vệ tài khoản thực chiến.

Chống Khóa Nick (Token Bucket)

Zalo quét spam rất nhạy. Thuật toán giới hạn: Burst 5 tin liên tiếp, hồi phục 1 token mỗi 3.000 ms (tối đa 20 tin/phút), hàng đợi chờ tối đa 20 giây. Kèm lệnh sendTypingEvent mô phỏng người thật.

Phân Quyền 2 Tầng Chống Jailbreak

Trong nhóm chat công cộng, người ngoài chỉ được cấp tập công cụ zalo_public (15 tools an toàn). Chỉ có Chủ nhân (UID trong ZALO_ALLOWED_USERS) mới được cấp zalo_owner (31 tools, terminal, file I/O).

Thuyết Minh Tiếng Việt (VieNeu v3)

Tích hợp mô hình AI giọng đọc offline chuyên sâu cho tiếng Việt (VieNeu v3) kết hợp Microsoft Edge TTS, cho phép bot gửi tin nhắn thoại âm thanh tự nhiên theo yêu cầu người dùng.

Cơ chế Đăng Bài Fanpage An Toàn 2 Bước (Facebook Integration):

Để chống bot tự ý đăng bài linh tinh lên Fanpage khi bị người lạ lừa trong chat nhóm:

1

Tạo Bản Nháp (zalo_fb_draft)

Bot soạn bài và sinh ra một mã duyệt ngẫu nhiên (ví dụ FB9182), trả về cho riêng Chủ nhân xem trước nội dung.

2

Xuất Bản với Mã Duyệt (zalo_fb_publish)

Chỉ khi chính tay Chủ nhân gõ lại mã FB9182, bài viết mới được đăng lên Fanpage và bot tiến hành kiểm tra công khai bài viết.

📊 4. Cỗ Máy Tự Động Hóa Thuyết Trình PPTmaster

Được thiết kế để nhận tài liệu từ Zalo và tự động tạo ra file PowerPoint chuẩn DrawingML hoàn toàn có thể nhấp đúp chỉnh sửa từng vector shape.

Bộ Trích Xuất Tài Liệu (source_to_md)

Hỗ trợ đa dạng đầu vào tài liệu trước khi thiết kế slide:

  • PDF: Dùng PyMuPDF trích xuất văn bản 2 cột, bảng biểu và hình ảnh.
  • Word (.docx): Dùng mammoth thuần Python, không phụ thuộc MS Word.
  • Excel (.xlsx): Dùng openpyxl chuyển các bảng tính thành Markdown.
  • Trang Web / URL: Dùng curl_cffi giả lập vân tay TLS vượt qua lớp bảo vệ chống cào web.

Trình Biên Dịch DrawingML Native

Kỹ thuật đồ họa vector độc nhất vô nhị:

  • skia-pathops: Động cơ hình học của Google Chrome xử lý các phép toán Boolean cắt ghép hình vector Bezier.
  • uharfbuzz: Động cơ Text Shaping tính toán chuẩn xác bounding box chữ cái tiếng Việt có dấu, chống tràn chữ.
  • 187 Preset Shapes: Render chuẩn xác các hình khối nguyên bản của Microsoft Office.
  • Ghi chú & Video: Tự động tạo Speaker Notes, lồng tiếng MP3 và dựng video bài giảng.

⚡ 5. Bảng Tra Cứu Toàn Bộ Chức Năng, Đầu Vào & Đầu Ra

Tên Công Cụ Phân Hệ Quyền Hạn Mô Tả Chức Năng Dữ Liệu Đầu Vào (Input) Dữ Liệu Đầu Ra (Output)
abs_zalo_status abs-zalo-bot reader Kiểm tra tình trạng sống còn của bot và số lượng tin nhắn trong corpus Không có tham số {"ok": true, "connected": true, "events_count": 1420}
abs_zalo_list_groups abs-zalo-bot reader Liệt kê các nhóm chat nằm trong danh sách trắng (allowlist) account_id (tùy chọn) {"groups": [{"id": "g_1", "name": "Nhóm Kỹ Thuật"}]}
abs_zalo_recent_messages abs-zalo-bot reader Đọc tin nhắn hội thoại gần đây kèm siêu dữ liệu đã lọc thông tin nhạy cảm thread_id (bắt buộc)
limit (mặc định 20)		 {"messages": [{"sender": "A", "text": "Chào", "ts": 1774...}]}
abs_zalo_create_poll abs-zalo-bot operator Tạo cuộc bình chọn / biểu quyết mới trong nhóm chat Zalo group_id (string)
question (string)
options (mảng)		 {"ok": true, "poll_id": "p_12", "options_count": 3}
abs_zalo_kick_member abs-zalo-bot admin Trục xuất thành viên khỏi nhóm chat (Bắt buộc xác nhận 2 lớp qua OTP) group_id, user_id, confirmation_code Lần 1: Cảnh báo & mã OTP 5 phút
Lần 2: {"ok": true, "kicked": true}
zalo_send_message 2anh-zalo-bot public/owner Gửi tin nhắn văn bản, tự động cắt đoạn UTF-16 và điều tiết nhịp độ thread_id (bắt buộc)
text (bắt buộc)		 {"ok": true, "msg_ids": ["m_1", "m_2"], "parts": 2}
zalo_send_voice 2anh-zalo-bot public/owner Chuyển văn bản thành giọng đọc tiếng Việt ấm áp và gửi tin nhắn thoại thread_id, text, voice (tùy chọn) {"ok": true, "duration_seconds": 12, "format": "aac"}
zalo_kb_read 2anh-zalo-bot public/owner Đọc trích xuất tài liệu trong kho tri thức nội bộ để tư vấn file_path (tên file trong kho) {"content": "Nội dung trích xuất...", "truncated": false}
zalo_fb_publish 2anh-zalo-bot owner only Duyệt đăng bài lên Fanpage Facebook bằng mã duyệt do chủ nhân gõ draft_id, approval_code (bắt buộc) {"ok": true, "post_id": "10234_56", "url": "https://..."}
svg_to_pptx.py PPTmaster Engine Tool Biên dịch mã vector SVG thành tệp thuyết trình Microsoft PowerPoint Native Danh sách file SVG từng slide Tệp presentation.pptx chỉnh sửa được 100% hình khối

🔄 6. Các Luồng Vận Hành Toàn Diện (Pipelines)

Pipeline 1: Từ Tin Nhắn Zalo ➔ AI Agent Suy Luận ➔ Phản Hồi

1

Lắng nghe & Bắt tin nhắn Ingress

Node.js Sidecar (zca-js) bắt gói tin socket. Kiểm tra xem tin nhắn riêng hay tin nhóm có được tag @Bot không. Nếu không được tag trong nhóm, im lặng bỏ qua.

2

Màng lọc an toàn PolicyGuard

Quét phát hiện số OTP, mật khẩu, mã bí mật và tự động che giấu (redact). Lưu vết sự kiện vào SQLite cục bộ.

3

Đẩy sự kiện sang AI Agent (Hermes / Claude)

Chuyển gói tin qua WebSocket nội bộ hoặc MCP Server. Nhận diện UID người gửi để cấp quyền zalo_owner (31 tools) hoặc zalo_public (15 tools).

4

Chu trình suy luận ReAct Loop

AI Agent suy nghĩ, gọi công cụ cần thiết (tra kho tài liệu, tính toán), nhận kết quả quan sát và tạo câu trả lời hoàn chỉnh.

5

Chuẩn hóa & Điều tiết nhịp gửi Egress

Đổi công thức sang Unicode (H₂O, x²), đổi thẻ màu Zalo, chia nhỏ nếu dài quá 3000 ký tự UTF-16, đẩy qua Token Bucket Rate Limiter và gửi về điện thoại người dùng.

Pipeline 2: Tiếp Nhận Tài Liệu Qua Zalo ➔ Tự Động Soạn Slide PPTmaster

Khi người dùng gửi tài liệu Word/PDF vào nhóm chat Zalo và yêu cầu: "Soạn slide thuyết trình về báo cáo này cho tôi":

A

Trích xuất tài liệu (source_to_md)

Chuyển tệp PDF/Word nguồn thành Markdown chuẩn hóa cấu trúc các phần.

B

Lập kế hoạch nhịp điệu (Page Rhythm)

AI phân bổ cấu trúc trang: Trang bìa ➔ Tổng quan ➔ Trọng tâm ➔ Số liệu KPI ➔ Đúc kết hành động.

C

Sinh mã đồ họa vector SVG

AI Agent trực tiếp viết mã vector cho từng trang slide; chạy svg_quality_checker.py để kiểm tra độ tương phản và lỗi tràn chữ.

D

Biên dịch sang PowerPoint DrawingML

Trình biên dịch svg_to_pptx.py xuất ra tệp .pptx Native với các hình khối chỉnh sửa được 100%.

E

Gửi trả tệp qua Zalo

Bot gọi zalo_send_file() gửi tệp PowerPoint trực tiếp vào nhóm Zalo để người dùng tải về chỉnh sửa.

💡 7. Hệ Thống Prompt & AI Guidelines Thực Chiến

Được thiết kế dựa trên thực tế tương tác hàng nghìn người dùng Việt Nam và nghệ thuật phân tầng ngữ cảnh chống tràn token.

Mô phỏng tin nhắn Zalo hiển thị thực tế:

Trợ Lý AI Báo Cáo:
- Hiện tại: Hệ thống đã kết nối thành công 12 nhóm chat.
- Phân tích sự cố:
• Tốc độ phản hồi trung bình: 850 ms
• Trạng thái xô Token: Đầy đủ 5/5 tokens
• Cảnh báo bảo mật: Đã chặn 1 yêu cầu terminal lạ
- Công thức phản ứng: 2H₂ + O₂ ➔ 2H₂O (ΔH < 0)

Quy tắc phân tầng Prompt 3 lớp (PPTmaster):

  • 1. Tầng Thủ công (Craft): Hướng dẫn tư duy thẩm mỹ, phối màu, lựa chọn bố cục. Thay đổi dòng này làm thay đổi diện mạo slide.
  • 2. Tầng Hợp đồng (Contract): Định dạng XML tối thiểu bắt buộc và ranh giới công cụ không tự kiểm tra được. Gói gọn trong 1 dòng và 1 ví dụ.
  • 3. Tầng Quy trình (Procedure): Trình tự các bước thực thi và câu lệnh kiểm tra (Quality gate).
  • Nguyên tắc vàng: "Cú pháp đã có công cụ kiểm tra thì không viết văn xuôi trong prompt", giúp tiết kiệm đến 40% chi phí token.

🏆 8. Những Điểm Hay Đột Phá & Lộ Trình Triển Khai

7 Đột Phá Về Mặt Kiến Trúc

  1. Tách rời Sidecar hoàn hảo: Quản lý socket và cookie riêng, không làm ảnh hưởng AI Brain.
  2. Fail-Closed & Redact Secrets: Tự động che giấu OTP và dữ liệu nhạy cảm.
  3. Phân quyền 2 tầng chống Jailbreak: Vô hiệu hóa ý đồ tiêm mã độc từ nhóm chat công cộng.
  4. Token Bucket Rate Limiter: Bảo vệ tuyệt đối tài khoản Zalo không bị khóa nick/checkpoint.
  5. Biên dịch DrawingML Native: Slide PowerPoint vector thật, chỉnh sửa được 100%.
  6. Prompt 3 tầng tối ưu token: Tiết kiệm chi phí và tăng độ chính xác suy luận.
  7. Bản địa hóa văn hóa công sở Việt Nam: Thể thức hành chính, thẻ màu Zalo, Unicode Math.

Lộ Trình Triển Khai Thực Tế Đề Xuất

  • Bước 1: Chạy nền 24/7 với PM2 hoặc Docker để duy trì kết nối Zalo ổn định liên tục.
  • Bước 2: Cắm MCP Server vào Claude Code / Cursor để lập trình viên điều khiển và nhận báo cáo trực tiếp qua Zalo.
  • Bước 3: Tích hợp mô hình AI Local (Ollama / vLLM với Qwen 2.5) để vận hành 100% miễn phí và bảo mật tuyệt đối dữ liệu nội bộ.
  • Bước 4: Mở rộng kênh Zalo Official Account (OA) với Webhook HMAC để tự động hóa chăm sóc khách hàng doanh nghiệp 24/7.