name: brand-monitoring-workflow description: Comprehensive workflow for automated brand monitoring, covering RSS and social media scraping, data processing, and Telegram notifications. author: Hermes Agent version: 0.1.0

Brand Monitoring Workflow

This skill outlines the complete workflow for automated brand monitoring, including RSS and social media scraping, data processing, and Telegram notifications. It captures best practices and pitfalls encountered during setup and operation.

1. Key Lessons Learned & Best Practices:

• Xử lý múi giờ Cron Job: Cron Scheduler hoạt động theo múi giờ UTC. Khi cấu hình lịch (ví dụ 0 9 * * 1,3,5 cho 9 AM), cần chuyển đổi sang giờ UTC tương ứng với múi giờ địa phương (ví dụ, nếu CEST là UTC+2, 9 AM CEST sẽ là 7 AM UTC). Đã chỉnh sửa lịch của Brand_Daily_Digest và Brand_Weekly_Report về 0 4 * * 1,3,5 và 9 4 * * 5 (tức 9:00 AM CEST).
• Lọc tin tức Báo chí và Social Media:
• Báo chí (RSS): Các nguồn RSS từ báo chí Việt Nam (VnExpress, Tuổi Trẻ, v.v.) thường đã tập trung vào bối cảnh Việt Nam. Do đó, chỉ cần từ khóa "Fulbright" là đủ để giữ lại tin. Tránh áp dụng các bộ lọc quá chặt như VN_KEYWORDS cho luồng này để tránh bỏ sót tin liên quan.
• Social Media (Google News RSS + site:filter): Cần bộ lọc chặt chẽ hơn để tránh các bài viết Fulbright toàn cầu. Sử dụng từ khóa cụ thể như FUV, FSPPM, Đại học Fulbright, Fulbright TPHCM và các từ khóa địa lý (Việt Nam, TPHCM).
• Xử lý từ khóa có dấu trong URL: Khi sử dụng Google News RSS với các từ khóa tiếng Việt có dấu, cần dùng urllib.parse.quote để encode query string, tránh lỗi http.client.InvalidURL.
• Độ tin cậy của Social Media Scraping:
• facebook-scraper và TikTokApi có thể không hoạt động ổn định hoặc không hỗ trợ tìm kiếm theo keyword rộng rãi. Thay vào đó, sử dụng Google News RSS với site:facebook.com hoặc site:tiktok.com là một workaround hiệu quả cho các bài viết public.
• Threads hiện không có API mở hoặc được index tốt bởi Google News RSS. Cần tìm giải pháp thay thế nếu yêu cầu này trở nên cấp thiết.
• Tính toán thời gian quét linh hoạt: Script collect_rss.py cần tính toán dynamic lookback window (lùi 2-3 ngày tùy theo ngày trong tuần) để thu thập tin một cách liên tục và không bỏ sót, thay vì một mốc thời gian cố định hay chỉ quét các bài từ một ngày quá xa trong quá khứ.
• Xử lý lỗi Cron Job Delivery Timeout: Cron job có thể chạy thành công script nhưng việc gửi thông báo (delivery) qua Telegram bị timeout. Cần kiểm tra trạng thái last_delivery_error của cron job và có thể cần trigger alert_dispatcher.py thủ công nếu cần.
• Ngăn rò rỉ log trung gian lên Telegram: Nếu cron/job wrapper dùng deliver: origin, mọi stdout/stderr từ script con có thể bị đẩy vào Telegram thread của job. Quy tắc an toàn là: wrapper chỉ gọi script trung gian với output bị redirect sang /dev/null hoặc được giảm thiểu tối đa; chỉ các lệnh gửi cuối cùng (như alert_dispatcher.py hoặc report_generator.py) mới được phép gọi hermes send trực tiếp tới thread đích (ví dụ 3688).

File Organization — Content Tree Pattern

To avoid scattering files across the filesystem, all brand monitoring IP/outputs follow this structure:

/opt/ai-os/products/ceo/
├── brand-monitoring/              ← LIVE directory (code + data + reports)
│   ├── data/brand-monitoring.db
│   ├── brands/fulbright/brand.yaml
│   ├── reports/*.md
│   ├── docs/*.md
│   └── shared/workflows/*.py
├── content/
│   └── brand-monitoring/          ← SYMLINK → ../brand-monitoring/
│                                   (clean tree visible in file browser)
└── (no other brand-monitoring files anywhere else)

Rules: - The live directory is /opt/ai-os/products/ceo/brand-monitoring/ (scripts hardcode these absolute paths). - A symlink content/brand-monitoring/ -> ../brand-monitoring/ makes it visible in the file browser tree under content/. - Do NOT move the actual directory into content/ because pipeline scripts hardcode paths. - Do NOT store brand monitoring reports or assets in random root-level folders. - Do NOT touch nhi-nhi-vietveda/ — it is a separate independent repo.

Dual /content/ pitfall (system root vs project path): This VPS has a system-level /content/research/ (at Linux root /) that was created accidentally by earlier scripts. The correct project path is always /opt/ai-os/products/ceo/content/research/. When moving files, always verify the full path starts with /opt/ai-os/products/ceo/. If you accidentally write to /content/, the file browser shows it under a different tree and the user cannot find it.

2. Các file script và cấu hình liên quan:

• /root/.hermes/scripts/brand_daily_digest.sh: Bổ sung chạy collect_social.py.
• /opt/ai-os/products/ceo/brand-monitoring/shared/workflows/collect_rss.py: Điều chỉnh logic lọc và tính toán thời gian quét.
• /opt/ai-os/products/ceo/brand-monitoring/shared/workflows/collect_social.py: Module mới để thu thập tin tức Social Media.
• /opt/ai-os/products/ceo/brand-monitoring/shared/workflows/pipeline.py: Cải thiện việc gán source_tier và lọc dựa trên relevance_score và is_crisis.
• /opt/ai-os/products/ceo/brand-monitoring/shared/workflows/alert_dispatcher.py: Điều chỉnh để gửi digest có highlight từ snippet, không còn là title đơn thuần.
• /opt/ai-os/products/ceo/brand-monitoring/brands/fulbright/rss_feeds.yaml: Cấu hình nguồn RSS trực tiếp và Google News RSS.
• /opt/ai-os/products/ceo/brand-monitoring/reports/2026-07-14-fulbright-weekly.md: Mẫu báo cáo tuần với định dạng mới, đầy đủ thông tin.