Zia - Trợ Lý AI Zalo

🚧 Dự án đang trong giai đoạn Preview - Có thể có thay đổi lớn 🚧

Chatbot AI cho nền tảng Zalo với Google Gemini 2.5 Flash + Web Dashboard quản lý

Tính năng • Cài đặt • Cấu hình • Modules • Triển khai

🎯 Tổng Quan

Zia là monorepo gồm 2 ứng dụng:

App	Mô tả	Tech Stack
`apps/bot`	Zalo AI Chatbot	Bun, zca-js, Google Gemini, SQLite
`apps/web`	Web Dashboard quản lý	Next.js 16, React 19, TailwindCSS

Điểm Nổi Bật

🧠 AI Thông minh - Google Gemini 2.5 Flash với 8192 thinking token budget
⚡ Streaming Real-time - Gửi phản hồi ngay khi AI bắt đầu generate
🖼️ Đa phương tiện - Xử lý text, ảnh, video, audio, file và sticker
🔌 Plugin System - Kiến trúc modular với 8 modules và 50+ tools
📊 Web Dashboard - Quản lý settings, logs, memories, tasks, backup
🗄️ Cloud Backup - Tự động backup database lên GitHub Gist
🐳 Cloud-Ready - Docker support với health checks

📋 Yêu Cầu Hệ Thống

Bun 1.0+ (Cài đặt Bun)
Gemini API Key (Lấy API Key)
Tài khoản Zalo để đăng nhập bot

🚀 Cài Đặt

# Clone repository
git clone https://github.com/your-org/zia.git
cd zia

# Cài đặt dependencies
bun install

# Copy file môi trường mẫu
cp apps/bot/.env.example apps/bot/.env

# Cấu hình API keys trong apps/bot/.env
# Tối thiểu cần GEMINI_API_KEY

# Chạy database migrations
bun run --cwd apps/bot db:migrate

Đăng Nhập Zalo Lần Đầu

Chạy bot: bun run dev:bot
File qr.png sẽ được tạo trong apps/bot/
Mở Zalo → Cài đặt → Đăng nhập trên máy tính → Quét mã QR
Credentials được lưu vào credentials.json cho các phiên sau

📖 Sử Dụng

# Development
bun run dev:bot          # Chạy bot với hot reload
bun run dev:web          # Chạy web dashboard

# Production
bun run start:bot        # Chạy bot production
bun run build:web        # Build web dashboard

# Database
bun run --cwd apps/bot db:studio     # Mở Drizzle Studio
bun run --cwd apps/bot db:generate   # Tạo migrations
bun run --cwd apps/bot db:migrate    # Chạy migrations

# Testing
bun run test                         # Tất cả tests
bun run test:integration             # Integration tests

⚙️ Cấu Hình

Biến Môi Trường (`apps/bot/.env`)

# Bắt buộc
GEMINI_API_KEY=your_gemini_api_key

# Hỗ trợ nhiều keys (tự động xoay khi rate limit)
# GEMINI_API_KEY=key1,key2,key3
# Hoặc:
# GEMINI_API_KEY_1=key1
# GEMINI_API_KEY_2=key2

# Dịch vụ tùy chọn
GROQ_API_KEY=your_groq_key              # Background agent
E2B_API_KEY=your_e2b_key                # Chạy code sandbox
FREEPIK_API_KEY=your_freepik_key        # Tạo ảnh AI
ELEVENLABS_API_KEY=your_elevenlabs_key  # Text-to-speech
YOUTUBE_API_KEY=your_youtube_key        # Tìm kiếm YouTube
GOOGLE_SEARCH_API_KEY=your_search_key   # Tìm kiếm web
GOOGLE_SEARCH_CX=your_search_engine_cx
GIPHY_API_KEY=your_giphy_key            # Tìm kiếm GIF

# Cloud Backup (cho Render/Railway)
GITHUB_GIST_TOKEN=your_github_token
GITHUB_GIST_ID=your_gist_id

# API Key cho Web Dashboard
API_KEY=your_random_api_key

Cài Đặt Runtime (`apps/bot/settings.json`)

Các cấu hình quan trọng:

Section	Key	Mô tả
`bot`	`useStreaming`	Bật streaming response
`bot`	`maxToolDepth`	Độ sâu tool calls tối đa
`bot`	`sleepMode`	Tự động offline theo giờ
`bot`	`maintenanceMode`	Chế độ bảo trì
`buffer`	`delayMs`	Cửa sổ gom tin nhắn (ms)
`modules`	`*`	Bật/tắt từng module
`allowedUserIds`	-	Whitelist user IDs
`cloudBackup`	`enabled`	Bật cloud backup

✨ Tính Năng

Xử Lý Tin Nhắn

Message Buffering (RxJS) - Gom nhiều tin nhắn liên tiếp:

User gửi: "Alo" → "Có đó không" → "Giúp mình với"
         ↓ (đợi 2.5s không có tin mới)
Bot xử lý: [3 tin nhắn cùng lúc]

Hỗ Trợ Media

Loại	Định dạng	Xử lý
Hình ảnh	PNG, JPG, GIF, WEBP, HEIC	Phân tích bởi Gemini
Video	MP4, MOV, AVI, WEBM (< 20MB)	Trích xuất thumbnail
Audio	AAC, MP3, WAV, OGG, FLAC	Tự động transcribe
Voice	Tin nhắn thoại Zalo	Tự động transcribe
File	PDF, TXT, DOC, Code files	Trích xuất nội dung

Response Tags

[reaction:heart]           → Thả reaction vào tin cuối
[sticker:hello]            → Gửi sticker
[msg]Nội dung[/msg]        → Gửi tin nhắn riêng
[quote:0]Trả lời[/quote]   → Reply vào tin cụ thể
[undo:-1]                  → Thu hồi tin nhắn cuối của bot

Rich Text Formatting

Cú pháp	Kết quả
`text`	đậm
`_text_`	nghiêng
`__text__`	gạch chân
`~text~`	~~gạch ngang~~

🔌 Modules & Tools

Chat Module

Tool	Mô tả
`clearHistory`	Xóa lịch sử chat
`saveMemory`	Lưu vào bộ nhớ dài hạn
`recallMemory`	Truy xuất bộ nhớ

Media Module

Tool	Mô tả	API cần thiết
`createChart`	Tạo biểu đồ (bar, line, pie)	-
`createFile`	Tạo tài liệu (docx, pdf, pptx, xlsx)	-
`freepikImage`	Tạo ảnh AI	Freepik
`textToSpeech`	Chuyển text thành giọng nói	ElevenLabs

Search Module

Tool	Mô tả	API cần thiết
`googleSearch`	Tìm kiếm web	Google Search
`youtube`	Tìm kiếm/lấy thông tin YouTube	YouTube API
`weather`	Thời tiết	-
`currency`	Tỷ giá tiền tệ	-
`steam`	Thông tin game Steam	-

Social Module

Tool	Mô tả
`getUserInfo`	Lấy thông tin user Zalo
`getAllFriends`	Danh sách bạn bè
`getFriendOnlines`	Bạn bè đang online
`getGroupMembers`	Thành viên nhóm
`forwardMessage`	Chuyển tiếp tin nhắn
`board`	Quản lý board/ghi chú
`poll`	Tạo/quản lý bình chọn
`reminder`	Tạo/quản lý nhắc nhở
`groupAdmin`	Quản lý nhóm (admin)
`friendRequest`	Quản lý lời mời kết bạn

Task Module

Tool	Mô tả	API cần thiết
`executeCode`	Chạy code trong sandbox	E2B
`solveMath`	Giải toán với LaTeX	-
`createApp`	Tạo code ứng dụng	-
`scheduleTask`	Lên lịch task tương lai	Groq
`flushLogs`	Gửi file log qua Zalo	-

Entertainment Module (Jikan API)

Tool	Mô tả
`jikanSearch`	Tìm kiếm anime/manga
`jikanDetails`	Lấy chi tiết
`jikanTop`	Bảng xếp hạng
`jikanSeason`	Anime theo mùa
`jikanCharacters`	Danh sách nhân vật
`jikanRecommendations`	Gợi ý
`jikanGenres`	Danh sách thể loại
`jikanEpisodes`	Danh sách tập
`nekosImages`	Ảnh anime
`giphyGif`	Tìm kiếm GIF (cần Giphy API)

Academic Module (TVU Portal)

Tool	Mô tả
`tvuLogin`	Đăng nhập portal
`tvuStudentInfo`	Thông tin sinh viên
`tvuSemesters`	Danh sách học kỳ
`tvuSchedule`	Thời khóa biểu
`tvuGrades`	Điểm học tập
`tvuTuition`	Thông tin học phí
`tvuCurriculum`	Chương trình đào tạo
`tvuNotifications`	Thông báo portal

🌐 Web Dashboard

Dashboard Next.js để quản lý bot:

Trang	Chức năng
`/`	Dashboard tổng quan, thống kê
`/settings`	Cấu hình bot
`/logs`	Xem logs
`/memories`	Quản lý long-term memory
`/history`	Lịch sử hội thoại
`/tasks`	Quản lý scheduled tasks
`/backup`	Cloud backup/restore

Chạy Web Dashboard

# Development
bun run dev:web

# Production
bun run build:web
bun run --cwd apps/web start

Cần set API_KEY trong .env của cả bot và web để bảo vệ API endpoints.

🏗️ Kiến Trúc

zia/
├── apps/
│   ├── bot/                     # Zalo AI Bot
│   │   ├── src/
│   │   │   ├── app/             # Bootstrap (main.ts, botSetup.ts)
│   │   │   ├── core/            # Framework (EventBus, Container, ModuleManager)
│   │   │   ├── modules/         # Feature modules
│   │   │   │   ├── gateway/     # Message pipeline
│   │   │   │   ├── chat/        # Chat tools
│   │   │   │   ├── media/       # Media tools
│   │   │   │   ├── search/      # Search tools
│   │   │   │   ├── social/      # Social tools
│   │   │   │   ├── task/        # Task tools
│   │   │   │   ├── entertainment/  # Anime/Media
│   │   │   │   ├── academic/    # TVU Portal
│   │   │   │   └── background-agent/  # Scheduled tasks
│   │   │   ├── infrastructure/  # External services
│   │   │   │   ├── ai/          # Gemini provider
│   │   │   │   ├── api/         # REST API endpoints
│   │   │   │   ├── backup/      # Cloud backup
│   │   │   │   ├── database/    # SQLite + Drizzle
│   │   │   │   ├── memory/      # Long-term memory
│   │   │   │   └── messaging/   # Zalo service
│   │   │   ├── libs/            # Document builders
│   │   │   │   ├── docx-builder/
│   │   │   │   └── pptx-builder/
│   │   │   └── shared/          # Utils, types, schemas
│   │   ├── tests/               # Integration & E2E tests
│   │   ├── drizzle/             # Database migrations
│   │   └── settings.json        # Runtime config
│   │
│   └── web/                     # Next.js Dashboard
│       └── src/
│           ├── app/             # Pages (App Router)
│           ├── components/      # React components
│           ├── hooks/           # Custom hooks
│           └── lib/             # Utilities
│
├── package.json                 # Monorepo scripts
└── bun.lock

Core Components

Component	Chức năng
EventBus	Pub/sub messaging cho loose coupling
ServiceContainer	Dependency injection container
ModuleManager	Quản lý lifecycle của modules
ToolRegistry	Parse và thực thi tools
BaseModule	Abstract base cho tất cả modules
BaseTool	Abstract base cho tất cả tools

🗄️ Database Schema

Bảng	Mô tả
`history`	Lịch sử hội thoại
`sent_messages`	Log tin nhắn đã gửi (cho undo)
`memories`	Long-term memory
`agent_tasks`	Hàng đợi scheduled tasks

🐳 Triển Khai

Docker

# Build và chạy
docker build -t zia-bot -f apps/bot/Dockerfile .
docker run -d --name zia-bot --env-file apps/bot/.env zia-bot

Docker Compose

cd apps/bot
docker-compose up -d

Cloud Platforms (Railway, Render)

Set biến môi trường trong dashboard
Encode credentials.json sang base64:
```
base64 -w 0 apps/bot/credentials.json
```
Set ZALO_CREDENTIALS_BASE64 với chuỗi đã encode
Set GITHUB_GIST_TOKEN và GITHUB_GIST_ID cho cloud backup
Deploy - health check tại /health

🛠️ Công Nghệ

Bot (`apps/bot`)

Danh mục	Công nghệ
Runtime	Bun 1.0+
Ngôn ngữ	TypeScript 5.7+
AI Model	Google Gemini 2.5 Flash
Messaging	zca-js (Zalo API)
Database	SQLite + Drizzle ORM
Reactive	RxJS
HTTP Client	Ky
Validation	Zod
Linting	Biome

Web (`apps/web`)

Danh mục	Công nghệ
Framework	Next.js 16
UI	React 19, TailwindCSS 4
Components	Radix UI, Lucide Icons
State	TanStack Query, SWR
Charts	Recharts

🤝 Đóng Góp

Fork repository
Tạo feature branch (git checkout -b feature/tinh-nang-moi)
Commit thay đổi (git commit -m 'Thêm tính năng mới')
Push lên branch (git push origin feature/tinh-nang-moi)
Mở Pull Request

Xem CONTRIBUTING.md để biết thêm chi tiết.

📄 Giấy Phép

MIT License - xem file LICENSE.

🙏 Credits

zca-js - Zalo API
Google Gemini - AI model
Bun - JavaScript runtime
Drizzle ORM - TypeScript ORM

Được xây dựng với ❤️ cho cộng đồng Zalo

Name		Name	Last commit message	Last commit date
Latest commit History 490 Commits
.github		.github
.vscode		.vscode
apps		apps
.dockerignore		.dockerignore
.gitignore		.gitignore
.npmrc		.npmrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
package.json		package.json

Uh oh!

License

TomiWixoss/Zia

Folders and files

Latest commit

History

Repository files navigation

Zia - Trợ Lý AI Zalo

🎯 Tổng Quan

Điểm Nổi Bật

📋 Yêu Cầu Hệ Thống

🚀 Cài Đặt

Đăng Nhập Zalo Lần Đầu

📖 Sử Dụng

⚙️ Cấu Hình

Biến Môi Trường (apps/bot/.env)

Cài Đặt Runtime (apps/bot/settings.json)

✨ Tính Năng

Xử Lý Tin Nhắn

Hỗ Trợ Media

Response Tags

Rich Text Formatting

🔌 Modules & Tools

Chat Module

Media Module

Search Module

Social Module

Task Module

Entertainment Module (Jikan API)

Academic Module (TVU Portal)

🌐 Web Dashboard

Chạy Web Dashboard

🏗️ Kiến Trúc

Core Components

🗄️ Database Schema

🐳 Triển Khai

Docker

Docker Compose

Cloud Platforms (Railway, Render)

🛠️ Công Nghệ

Bot (apps/bot)

Web (apps/web)

🤝 Đóng Góp

📄 Giấy Phép

🙏 Credits

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Languages

Biến Môi Trường (`apps/bot/.env`)

Cài Đặt Runtime (`apps/bot/settings.json`)

Bot (`apps/bot`)

Web (`apps/web`)

Packages