openclaw/viralevo

ViralEvo — Viral Content Trend Advisor

Version: v0.6.4 | Languages: English / 中文

---

语言说明 / Language Support

本 Skill 完整支持中文操作。安装完成后，你可以：

• 用中文与 Agent 对话（"今天该发什么内容？"）
• 接收中文版每日报告
• 用中文关键词监控中文平台内容
• 在引导设置时选择界面语言

This skill fully supports both English and Chinese. During onboarding, the agent will ask which language you prefer.

---

What This Skill Does

ViralEvo monitors content platforms, scores trending topics using a weighted formula, predicts lifecycle windows, and automatically adjusts its own prediction weights every week based on how accurate it was.

Three core advantages over manual research:

1. Catches trends 12–48h early — monitors signal velocity across 11 platforms simultaneously
2. Learns from your results — when you report your post outcomes, those signals feed back into the model
3. Self-corrects weekly — every Monday the system reviews its prediction errors and updates its weights automatically

---

Quick Start

After installation, add your Tavily API key:

echo "TAVILY_API_KEY=tvly-xxxx" >> ~/.openclaw/workspace/.env

Then tell your agent:

"Start ViralEvo setup"
— or in Chinese —
"开始趋势雷达设置"

Or run onboarding directly:

node {baseDir}/scripts/onboarding.js

---

Natural Language Triggers

When the user reports post results (e.g. "got 80k views", "效果很好"), the agent should:

1. Search for the matching topic: python3 {baseDir}/scripts/feedback.py --search "<keyword>"
2. Confirm the match with the user
3. Log the result: python3 {baseDir}/scripts/feedback.py --topic-id <id> --platform <platform> --views <n>

When the user says any of the following, the agent should run collect → report:

• "What should I post today?" / "今天该发什么？"
• "Any trends?" / "有什么趋势？"
• "Show me the trend report" / "给我看趋势报告"
• "What's trending in my niche?" / "我的赛道有什么热点？"

When the user says:

• "Run ViralEvo" / "运行趋势雷达" → run collect then report
• "Collect trends" / "采集趋势" → run collect only
• "Generate report" / "生成报告" → run report only
• "Weekly review" / "周度复盘" → run weekly_review
• "Show keywords" / "查看关键词" → run keywords --show

---

Feedback Intake

When the user describes post results, always match to a recent topic, confirm before logging:

• "The hair clips video got 80k views on TikTok" → match topic, log: views=80000, platform=tiktok
• "那个AI文章效果很好，小红书5000收藏" → 匹配话题，记录：saves=5000, platform=xiaohongshu

Use the /trend feedback command or natural language — both are accepted.

---

Available Commands

| Command | Action | |---|---| | node {baseDir}/scripts/onboarding.js | First-time setup wizard | | node {baseDir}/scripts/collect.js | Fetch trend signals from all sources | | python3 {baseDir}/scripts/report.py | Generate and output today's report | | python3 {baseDir}/scripts/verify.py --hours 24 | Verify yesterday's predictions | | python3 {baseDir}/scripts/verify.py --hours 72 | Verify 72h-old predictions | | python3 {baseDir}/scripts/weekly_review.py | Run self-evolution (Mondays recommended) | | python3 {baseDir}/scripts/keywords.py --show | View your keyword index | | python3 {baseDir}/scripts/keywords.py --add "term" | Add a keyword manually | | python3 {baseDir}/scripts/keywords.py --remove "term" | Remove a keyword | | python3 {baseDir}/setup.py | Check all system requirements | | python3 {baseDir}/scripts/feedback.py --list | List recent topics to log feedback for | | python3 {baseDir}/scripts/feedback.py --search "keyword" | Find a topic by keyword | | python3 {baseDir}/scripts/feedback.py --topic-id <id> --platform tiktok --views 80000 | Log post performance | | python3 {baseDir}/db/init_db.py | Re-initialize database (use if DB is corrupted) | | python3 {baseDir}/scripts/status.py | Quick health check — config, API key, DB, recent data |

---

System Requirements

| Requirement | Minimum | Role | |---|---|---| | Node.js | v18+ | Data collection, onboarding | | Python | 3.10+ | Scoring, reports, self-evolution | | OpenClaw | v2026.1+ | Agent runtime, scheduling | | Tavily API Key | Free tier | Indirect platform search |

Tavily free tier = 1,000 calls/month. Single niche daily usage ≈ 60–120/month.

---

Supported Platforms

| Platform | Method | Confidence Cap | |---|---|---| | HackerNews | Official Algolia API | 1.00 | | Dev.to | Official API | 1.00 | | Product Hunt | RSS | 1.00 | | Reddit | JSON API (public) | 0.90 | | YouTube | Tavily search | 0.70 | | Twitter / X | Tavily search | 0.70 | | Pinterest | Tavily search | 0.70 | | LinkedIn | Tavily search | 0.70 | | TikTok | Tavily search | 0.65 | | Instagram | Tavily search | 0.65 |

---

Supported Niches

AI/Tech · E-commerce · Beauty/Skincare · Fitness/Health · Finance · Gaming · Fashion/Lifestyle · Education · Real Estate · Pets · Custom (11 niches)

---

Scoring Formula

Total Score =
  (Platform Signal Strength)  × W1  [default 0.25]
+ (Engagement Velocity)       × W2  [default 0.25]
+ (Cross-Platform Spread)     × W3  [default 0.20]
+ (Niche Relevance Score)     × W4  [default 0.15]
+ (Goal Alignment Score)      × W5  [default 0.15]

Constraints: W1+W2+W3+W4+W5 = 1.0 exactly
Each weight: floor=0.08, ceiling=0.45
Max change per weekly review: ±0.05 (±0.10 after algorithm change detection)

---

Report Output Format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔥 ViralEvo | AI/Tech | 2026-03-09 08:15
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 ACT NOW (Score > 80)
1. OpenClaw Security Issue — 135k instances exposed
   ████████████████████ 93% | Confidence: 0.85
   📅 Detected 14h ago | Source: hackernews
   ⏰ Estimated window: ~42h remaining
   🎯 Post: TODAY

🟡 PREPARE (Score 60–80)
2. OpenAI Government Surveillance Controversy
   ████████████████░░░░ 78% | Confidence: 0.74
   📅 Detected 6h ago | Source: dev.to
   ⏰ Estimated window: ~68h remaining
   🎯 Post: Tomorrow morning

🟢 EVERGREEN (Score < 60)
3. MCP Protocol Enterprise Adoption
   ████████░░░░░░░░░░░░ 44% | Confidence: 0.79
   📅 Steady growth — no spike
   ⏰ Relevant: 30d+
   🎯 Post: Any time this week

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Model Health
  Accuracy     : 58% (44 predictions)
  Sources      : 6/6 ✅
  Tavily usage : 112 / 1,000 this month
  Keyword index: 1,203 terms
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Scheduling (Cron Setup)

ViralEvo runs automatically via OpenClaw's cron system. After onboarding, add these four jobs to your OpenClaw cron config.

How to add cron jobs in OpenClaw:

Tell your agent:

"Add a cron job to run ViralEvo daily at 8am"

Or add manually to ~/.openclaw/openclaw.json:

{
  "cron": {
    "jobs": [
      {
        "id": "viralevo-collect-report",
        "schedule": "0 8 * * *",
        "commands": [
          "node ~/.openclaw/workspace/viralevo/scripts/collect.js",
          "python3 ~/.openclaw/workspace/viralevo/scripts/report.py"
        ]
      },
      {
        "id": "viralevo-verify-24h",
        "schedule": "5 8 * * *",
        "commands": ["python3 ~/.openclaw/workspace/viralevo/scripts/verify.py --hours 24"]
      },
      {
        "id": "viralevo-verify-72h",
        "schedule": "10 8 * * *",
        "commands": ["python3 ~/.openclaw/workspace/viralevo/scripts/verify.py --hours 72"]
      },
      {
        "id": "viralevo-weekly-review",
        "schedule": "0 8 * * 1",
        "commands": ["python3 ~/.openclaw/workspace/viralevo/scripts/weekly_review.py"]
      }
    ]
  }
}

See OpenClaw docs: https://docs.openclaw.ai/automation/cron-jobs

---

OpenClaw Config (Alternative API Key Setup)

Instead of using .env, you can configure your Tavily key via ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "viralevo": {
        "enabled": true,
        "apiKey": "tvly-your-key-here"
      }
    }
  }
}

---

Self-Evolution Loop

Daily verification (5 min and 65 min after your report time): re-fetches topics predicted 24h ago, compares predicted lifecycle vs actual activity, records error.

Weekly review (every Monday at your report time):

1. Aggregates all predictions from past 7 days
2. Calculates accuracy per platform, per topic type
3. Identifies top 3 sources of systematic error
4. Proposes weight adjustments (max ±0.05 per weight)
5. Applies new weights to config.json
6. Writes report to reports/YYYY-MM-DD_weekly.md
7. Auto-rolls back if accuracy drops for 2 consecutive weeks

---

Accuracy Expectations

| Period | Expected Accuracy | |---|---| | Week 1–2 | 30–40% (cold start) | | Month 2 | 55–65% | | Month 3+ | 65–75% | | Month 6+ | 75%+ |

Accuracy = prediction within ±20% of actual topic lifecycle.

---

Data Location

~/.openclaw/workspace/viralevo/
├── config.json              ← niche, weights, schedule
├── user_profile.json        ← onboarding answers, language
├── data/
│   ├── trends.db            ← SQLite database
│   └── backups/             ← daily snapshots, 7-day retention
├── reports/                 ← daily + weekly markdown reports
└── logs/
    └── execution.log

---

Privacy

All data is stored locally on your machine. The skill makes outbound network requests only to fetch public trend signals:

• HackerNews, Dev.to, Product Hunt, Reddit: public APIs, no auth required
• Tavily API: receives only search query strings — no personal data transmitted

---

⚠️ Disclaimers

ViralEvo provides probabilistic estimates based on publicly available signals. It does not guarantee specific outcomes in views, impressions, followers, or revenue. All predictions are directional guidance — not the sole basis for business decisions. Platform APIs change without notice.

---

Uninstall

# Step 1: Remove skill from OpenClaw
openclaw skills remove viralevo

# Step 2: Delete local data (optional)
rm -rf ~/.openclaw/workspace/viralevo/

# Step 3: Verify
openclaw skills list

If you reinstall later without deleting Step 2, ViralEvo will resume from your existing data.

---

Troubleshooting

| Symptom | Fix | |---|---| | "Not configured" | Run node {baseDir}/scripts/onboarding.js | | "TAVILY_API_KEY not set" | Add key to ~/.openclaw/workspace/.env | | No topics in report | Run node {baseDir}/scripts/collect.js first | | System check | Run python3 {baseDir}/setup.py | | Accuracy dropping | Run python3 {baseDir}/scripts/weekly_review.py manually | | Quick diagnosis | Run python3 {baseDir}/scripts/status.py |