brand-geo-analysis-plus

Brand GEO Analysis Plus Edition

One-sentence positioning

One Skill, three layers of perspective: real-time trending topic aggregation (hub) + in-depth social media research over the past 30 days (cn30) + brand visibility in AI search (geo), covering all key scenarios of Chinese internet brand perception.

When to use

Use this skill immediately when triggered by any of the following scenarios:

Want to know what the whole internet is talking about today and which hot topic is worth following → hub module
Want to research real user discussions of a topic over the past 30 days and do brand reputation/competitor comparison → cn30 module
Want to see how a brand is introduced in Doubao/Kimi/DeepSeek AI search and what its AI visibility is → geo module
Want to do a complete brand perception diagnosis (trending topic heat → real reputation → AI answers) → combined workflow

Three-module quick overview

Module	Script entry point	Platform	Time dimension	Output
hub(trending topics)	`scripts/hub_fetch.py`	Baidu/Zhihu/Weibo/Douyin/Bilibili/Kuaishou/Toutiao (7 platforms)	Real-time (hourly) / yesterday / this week / past 30 days	TOP10 table + cross-platform summary + trend forecast
cn30(social media research)	`scripts/cn30_search.py`	Xiaohongshu/Douyin/WeChat Official Accounts (3 platforms)	Any number of days in the past 30 days	Data quick overview (TOP5 × 3 platforms) + comprehensive insights + HTML report
geo(AI search visibility)	`scripts/geo_search.py` + `scripts/geo_analyze.py` + `scripts/geo_report.py`	Doubao/Kimi/DeepSeek (3 platforms)	Instant question	GEO score + mention rate + sentiment + competitors + sources + interactive HTML report

Authentication (shared)

The three modules share the same REDFOX_API_KEY. Get it from Red Fox hub Configuration method:

export REDFOX_API_KEY=ak_你的密钥

Or write to ~/.openclaw/openclaw.json the env.REDFOX_API_KEY. Priority: command line --api-key > environment variables > configuration file.

Dependency installation (by module):

Module	Dependency
hub	Standard library (`urllib.request`, no third-party dependencies)
cn30	Standard library (`urllib.request`, no third-party dependencies)
geo	`pip install requests`

Routing decision tree

Select a module based on user intent. If the intent is ambiguous, first confirm with AskUserQuestion.

用户想做什么？
│
├─ 想知道今天/最近哪个话题/事件在全网火
│   └─→ hub 模块（实时热榜）
│
├─ 想研究某话题在用户真实讨论里的口碑/反馈
│   └─→ cn30 模块（小红书+抖音+公众号）
│
├─ 想看品牌/产品在 AI 搜索里被如何介绍
│   └─→ geo 模块
│
├─ 想做品牌诊断：热度 + 口碑 + AI 可见度 全维度
│   └─→ 组合工作流（hub → cn30 → geo）
│
└─ 给了具体平台/时间/品牌名
    └─→ 根据字段路由到对应模块

Module 1: hub (trending topic aggregation)

Capabilities

Real-time scraping of trending search data from 7 major platforms, cross-platform event identification, TOP10 rankings, trend forecasting, subscription push.

Platform codes

Code	Platform	Code	Platform
`bd`	Baidu	`bz`	Bilibili
`zh`	Zhihu	`ks`	Kuaishou
`wb`	Weibo	`tt`	Toutiao
`dy`	Douyin

Quick invocation

# 最新热榜（前一个完整小时）
python3 ~/.workbuddy/skills/brand-geo-analysis-plus/scripts/hub_fetch.py \
  --source "全平台热点事件-GitHub"

# 今日热榜（今日0:00 到当前整点）
python3 ~/.workbuddy/skills/brand-geo-analysis-plus/scripts/hub_fetch.py \
  --source "全平台热点事件-GitHub" \
  --start-date "T 00:00:00" --end-date "T HH:00:00"

# 昨日热榜 / 本周热榜 / 指定平台 / 关键词泛化
# 详见 references/hub-instructions.md

Output specification

Output TOP10 by platform,the platform display order is fixedas: Baidu → Zhihu → Weibo → Douyin → Bilibili → Kuaishou → Toutiao.

Automatically skip empty platforms
For ≤10 items, display the actual count; for >10 items, display "View the full {platform name} ranking" prompt
Heat valuehas already been formatted by the script, directly use the original value of the hotCount field,do not perform any conversion
- In the script, format_hot_count() has been processed: pure numbers will be converted to "number+万" (5980000 → 598万); return values that already include a unit ("598万"、"345 万热度") are passed through as-is
- It is forbidden to perform integer division/multiplication on hotCount (it is a string, which will TypeError), and it is also forbidden to append "万" again (which would produce "598万万")
See the full template at references/hub-output-templates.md
See the trend prediction logic at references/hub-prediction-logic.md
See the full instruction list at references/hub-instructions.md

Key rules

Hourly updates: the default query is "the previous complete hour" rather than the current hour
Keyword generalization: broad terms (sports/entertainment/technology, etc.) are automatically expanded into 10 related terms; precise terms use the original term directly
Default compact mode: stdout output is minimal (each platform only previews TOP3, and the header will be marked "(the table below is a TOP3 preview)") + appended at the end dataFile: {path}, the full ranking must be read as JSON from dataFile , do not assume data is missing just because you only see 3 items
The platform order has been fixed by the scriptas Baidu → Zhihu → Weibo → Douyin → Bilibili → Kuaishou → Toutiao, no need to rearrange it yourself

Module 2: cn30 (social media deep research)

Capabilities

Search real user discussion data from the past 30 days across the three major platforms Xiaohongshu, Douyin, and WeChat Official Accounts, conduct cross-platform comprehensive analysis of public opinion trends, and output research reports and visualized HTML reports.

Platform codes

Code	Platform	Key metrics
`xhs`	Xiaohongshu	Likes/favorites/comments (favorites/likes ratio = seeding signal)
`dy`	Douyin	Likes/comments/shares (share count =传播力)
`gzh`	WeChat Official Accounts	Reads/likes/forwards (read count = attention level)

Quick invocation

python3 ~/.workbuddy/skills/brand-geo-analysis-plus/scripts/cn30_search.py \
  "AI视频工具,大模型" \
  --platforms xhs,dy,gzh \
  --count 50 \
  --days 30 \
  --output-format both \
  --output-dir ~/Documents/CnLast30Days

--output-format supports json / html / both。

Workflow

Environment check: confirm REDFOX_API_KEY is configured
Keyword quality check: when the topic is too vague ("tools", "methods"), ask the user to make it more specific
Pre-research: run 2-3 WebSearches in parallel to extract hot terms (Xiaohongshu/Douyin/general)
Query plan: merge related terms into one call, at most 5 terms per platform, by default call the engine only once
Run the engine: run in the foreground (5-minute timeout), read the full output
WebSearch supplement: 1-2 WebSearches to cover Zhihu/Bilibili/36Kr (excluding xhs/dy/gzh domains)
Comprehensive output: according to output rules generate the report

Output specification (mandatory)

🇨🇳 cn-last30days v2.0.0 · {YYYY-MM-DD}

## 数据速览
（公众号 TOP5 → 小红书 TOP5 → 抖音 TOP5，标题作可点击 Markdown 链接）

我的发现：
**{话题}** - 1-2句描述，来源 [平台@作者](链接)
核心发现：
1. ...
2. ...

{引擎页脚逐字粘贴}

---
我是 {TOPIC} 的专家，我可以帮你：
- ...
HTML 报告已生成：[查看报告](HTML文件路径)

LAW rules(any violation is considered an output error):

LAW 1: Do not end with a Sources: / References: block
LAW 2: General queries start with "My findings:", and ##/### section headings are prohibited; comparison queries are the exception
LAW 3: Do not use em dashes (—/–) or -(space hyphen space)
LAW 4: Include the engine footer verbatim, after the core findings and before the invitation
LAW 5: Every citation must use an inline Markdown link, not a bare URL
LAW 6: Do not output a raw ranking list; convert it into prose insights
LAW 7: There must be a "Data at a Glance" module after the badge and before "My findings"

For the complete template, see references/cn30-output-rules.md。

HTML report (auto-generated)

After the data query is complete,without askingdirectly generate the HTML:

python3 ~/.workbuddy/skills/brand-geo-analysis-plus/scripts/cn30_search.py \
  --from-json "JSON文件路径" \
  --output-dir ~/Documents/CnLast30Days
open "HTML文件路径"

Module 3: geo (AI search brand visibility)

Capabilities

Batch-query the three AI search engines Doubao, Kimi, and DeepSeek, analyze brand mention rate, sentiment tendency, source citations, and competitor comparisons, and generate an interactive HTML report.

Platform codes

doubao / kimi / deepseek(all selected by default, comma-separated)

Workflow

Step 0: Input collection

Required:

Brand name (e.g., "Genki Forest", "DJI", "NIO")
Category/industry (e.g., "sugar-free beverages", "drones", "new energy vehicles")

Optional:

Brand aliases (to improve matching accuracy)
Competitor list
Custom question list (if provided, skip Step 1)

If there is only a brand name and no category, you must ask for the category.

Step 1: Question generation (when the user does not provide questions)

Use websearch to search for category-related questions, and combine category knowledge to generate 8questions.

Question types must cover four categories (at least 2 of each type, 8 in total, up to 12):

Recommendation type: "Which brand of {category} is good?" (does not directly contain a brand name)
Comparison type: "Which is better, {brand A} or {brand B}?"
Evaluation type: "How is {brand}?" (may contain a brand name)
Scenario type: "What {category} is good for {scenario}?" (does not directly contain a brand name)

After generation,you must use AskUserQuestion to confirm, and only enter Step 2 after the user explicitly agrees.

Step 2: Batch search

python3 ~/.workbuddy/skills/brand-geo-analysis-plus/scripts/geo_search.py \
  --queries '["问题1","问题2","问题3","问题4","问题5","问题6","问题7","问题8"]' \
  --platforms doubao,kimi,deepseek

Output output/search_results.json. The script automatically completes parallel submission and polling for all tasks (3 platforms × N questions), up to 15 minutes.

8 questions → 24 tasks, wait prompt: "takes about 5-8 minutes"
When a platform returns rate-limiting/failure wording (e.g., Doubao's "computing power is strained during peak hours... please try again later"), the script automatically retries once; if it is still invalid, record it as status: "invalid" andexcluded from the statistics(not counted in the mention rate denominator), and no longer treat it as "the brand was not mentioned"

Step 3: Deterministic analysis

python3 ~/.workbuddy/skills/brand-geo-analysis-plus/scripts/geo_analyze.py \
  --brand "品牌名" \
  --aliases '["别名1","别名2"]' \
  --competitors '["竞品A","竞品B"]' \
  --search-results output/search_results.json

Output output/deterministic.json + output/ai_analysis_template.json。

Step 4: AI Analysis (Agent Execution)

Read output/search_results.json，Only for status == "completed" responsesAnalyze the following fields (invalid / failed / timeout are all skipped; they have already been excluded from the statistics):

brand_rank (int|null): ranking position in the recommendation list
brand_context (str): context summary
sentiment (str)：positive / neutral / negative
sentiment_reason (str): rationale
competitors_mentioned (list[str]): all competitors mentioned
competitor_details (list[dict]): rank + sentiment for each competitor
key_claims (list[str]): 2-3 key descriptions

Write to output/ai_analysis.json。

Note: inline citation markers in the body text (Kimi <REF>…</REF>、DeepSeek [citation:N]) have already been stripped by the script in Step 2; no need to handle them yourself.

Source availability：sources being empty isnormal, commonly seen with Kimi (this platform only returns inline citation markers in the body text and does not include parseable external links). In this case, the result will include the sources_note field, and the "Source Analysis" section of the report will automatically display a data completeness notice,do not treat empty sources as the conclusion that "the brand's official website was not cited"。

Sentiment judgment rules:

The response clearly recommends/emphasizes advantages → positive
Objective description/listing only → neutral
Points out shortcomings/does not recommend → negative

Step 5: Merge + Report Generation

# 合并分析（Step 4 完成后）
python3 ~/.workbuddy/skills/brand-geo-analysis-plus/scripts/geo_analyze.py \
  --brand "品牌名" --aliases '["别名"]' --competitors '["竞品"]' \
  --search-results output/search_results.json \
  --ai-analysis output/ai_analysis.json

# 生成 HTML
python3 ~/.workbuddy/skills/brand-geo-analysis-plus/scripts/geo_report.py \
  --analysis output/analysis_result.json \
  --search-results output/search_results.json

Step 6: Delivery

Deliver output/geo_report.html
Output a summary of key findings (5 core conclusions):
- Cross-platform mention rate + breakdown by platform
- GEO composite score + best/worst platform
- Sentiment distribution (positive rate = positive count/valid response count; neutral is not counted as positive)
- Competitor comparison + brand ranking
- TOP3 source domains + whether the official website was cited (if a platform has no sources, this must be stated rather than treated as "not cited")

Core Metrics

See references/geo-metrics.mdfor detailed definitions. Core formulas:

GEO 得分 = 提及率得分 × 40% + 排名得分 × 30% + 情绪得分 × 30%
        = 提及率×100 × 40% + max(0, 100 - (均排名-1)×10) × 30%
          + (正面占比×100 - 负面占比×50) × 30%

Interpretation: 70+ excellent / 50-69 good / 30-49 average / <30 insufficient.

Combined Workflow: Complete Brand Perception Diagnosis

When the user needs a full-dimensional brand diagnosis (typical phrasing: "Help me create a complete perception report for the {X} brand"), execute in sequence:

Phase 1: hub to gauge heat (5 minutes)

python3 scripts/hub_fetch.py --source "全平台热点事件-GitHub" --keywords "{品牌}" --expand-keywords

Output: whether the brand is in recent hot topics, which platforms are covered, average heat, and time on the list.

Phase 2: cn30 to dig into reputation (5-10 minutes)

python3 scripts/cn30_search.py "{品牌},{品类}" --days 30 --output-format both

Output: real user discussions, sentiment tendencies, TOP feedback, HTML report.

Phase 3: geo to look at AI responses (10-15 minutes)

python3 scripts/geo_search.py --queries '[5 个问题]' --platforms doubao,kimi,deepseek
python3 scripts/geo_analyze.py --brand "{品牌}" --competitors '["{竞品}"]' --search-results output/search_results.json
# 步骤 4-5 见 geo 模块工作流

Output: the brand's mention rate in AI search, sentiment, ranking, sources, HTML report.

Phase 4: Comprehensive report

Merge the findings from the three phases hub/cn30/geo into a narrative document, structured as:

# {品牌} 品牌感知诊断报告

## 一句话结论
（综合三阶段结果的一句话判断）

## 1. 热度层（全网热榜）
- 是否在热点中 / 平台覆盖 / 趋势方向

## 2. 口碑层（社媒讨论）
- 真实用户反馈 / 正负面信号 / 关键讨论主题

## 3. AI 层（生成式搜索）
- GEO 得分 / 提及率 / 情绪分布 / 竞品对比 / 信源

## 4. 行动建议
- 热度层：{是否需要借势}
- 口碑层：{具体需改进的负面反馈}
- AI 层：{GEO 优化方向}

Error Handling (General)

Situation	Handling method
Not configured `REDFOX_API_KEY`	Prompt the user to go to Redfox hub to obtain
Vague keywords ("tool", "method")	Use AskUserQuestion to have the user make it specific
Partial failure of the cn30 engine	Continue analyzing the completed data, and mark the failed items in the HTML report
All geo tasks timed out	Prompt the user to retry later; the API load may be too high
geo AI analysis results missing	Generate only deterministic analysis (mention rate, domains); mark the sentiment module as "pending analysis"
Brand name too short (≤2 characters)	Prompt the user to provide a brand alias to improve matching accuracy

Resource Index

Scripts

File	Purpose
`scripts/hub_fetch.py`	7-platform trending aggregation
`scripts/cn30_search.py`	Xiaohongshu/Douyin/WeChat Official Account discussion search over the past 30 days + HTML report generation
`scripts/geo_search.py`	AI search batch scheduler
`scripts/geo_analyze.py`	GEO deterministic analysis + merged analysis
`scripts/geo_report.py`	GEO HTML report generation
`scripts/lib/platforms.py`	AI platform adapters
`scripts/lib/analyzer.py`	GEO analysis logic library
`scripts/lib/report_template.py`	GEO HTML template library

References

File	When to load
`references/cn30-output-rules.md`	When generating the cn30 report
`references/hub-instructions.md`	When processing hub user instructions
`references/hub-output-templates.md`	When outputting the hub report
`references/hub-prediction-logic.md`	When doing trend forecasting
`references/geo-metrics.md`	When calculating GEO metrics

FAQ

Q: Do all three modules have to be used? A: No. Call them as needed according to the routing decision tree. For simple scenarios, one module is enough; only complex diagnostics require a combined workflow.

Q: Why not merge the scripts of the three modules into one CLI? A: The three data sources, invocation logic, and output formats differ considerably. Keeping the scripts independent makes them easier to maintain and upgrade separately. When one data source fails, it does not affect the other modules.

Q: What should be done to upgrade a module? A: Upgrading a single module independently only requires replacing the corresponding files under scripts/ and updating the corresponding references/ documentation. The unified SKILL.md does not need to be changed.

Q: Can these three modules be used directly in this workspace? A: Yes. The skill is installed in ~/.workbuddy/skills/brand-geo-analysis-plus/, and all WorkBuddy sessions and workspaces can use it.

About this skill

One-sentence positioning

When to use

Three-module quick overview

Authentication (shared)

Routing decision tree

Module 1: hub (trending topic aggregation)

Capabilities

Platform codes

Quick invocation

Output specification

Key rules

Module 2: cn30 (social media deep research)

Capabilities

Platform codes

Quick invocation

Workflow

Output specification (mandatory)

HTML report (auto-generated)

Module 3: geo (AI search brand visibility)

Capabilities

Platform codes

Workflow

Step 0: Input collection

Step 1: Question generation (when the user does not provide questions)

Step 2: Batch search

Step 3: Deterministic analysis

Step 4: AI Analysis (Agent Execution)

Step 5: Merge + Report Generation

Step 6: Delivery

Core Metrics

Combined Workflow: Complete Brand Perception Diagnosis

Phase 1: hub to gauge heat (5 minutes)

Phase 2: cn30 to dig into reputation (5-10 minutes)

Phase 3: geo to look at AI responses (10-15 minutes)

Phase 4: Comprehensive report

Error Handling (General)

Resource Index

Scripts

References

FAQ