byted-marketing-agent-trending-list

Trending List (TrendingList)

When to Use

• /trending — Manually trigger a full trending list query
• The user asks about "hot topics/topic challenges/hot list events/industry trends/public domain insights"
• The user wants to know "what's trending recently/industry hot searches/popular topic challenges"
• The user says "help me check the hot list/what events are hot recently/what are the trends"
• Called by other orchestration skills (such as daily report generation, content planning)
• Scheduled tasks automatically execute to obtain the latest trend data

⛔ OUTPUT RULE — Highest priority

• During executionIt is forbidden to output any intermediate process to the user, including but not limited to: technical steps such as self-checks, creating virtual environments, installing dependencies, and connectivity verification.
• It is forbidden to output any of the following content (violation means failure):
  • ❌ "Let me run a self-check first" / "Creating a virtual environment" / "Dependencies installing" / "Installation is still in progress"
  • ❌ "Let me first check the skill file" / "First, environment preparation"
  • ❌ API addresses, credentials, tokens, script paths, internal field names, SDK version information
  • ❌ Database table names (such as cdp_voc.hot_topic_insights), English field names (such as main_challenge、heat_value), query_type values (such as hot_topic_insights、hot_event) — whether in process or result, it is strictly forbidden to disclose them to the user
• If the environment is not ready and installation is needed, only one user-friendly prompt is allowed (such as "Initializing the query service for you, please wait…"), and after completion directly return the business result without announcing technical details.
• Output only once after completion: the business result (industry list / ranking list / single detail) or "No data temporarily/parameter missing and needs selection".

Self-check and environment preparation (must be completed before each execution)

⚠️ Mandatory rules

• All script callsmust use the virtual environment's Python：$VENV_PY
• On first use or when the self-check fails, you must first complete the "Install virtual environment" step below, then re-run the self-check and only after passing it can you execute business calls.
• It is forbidden to directly use the system python3, to avoid dependency pollution or version mismatch.

0. Credential detection (check before environment preparation)

if [ -z "$VOLCENGINE_ACCESS_KEY" ] || [ -z "$VOLCENGINE_SECRET_KEY" ]; then
  echo "CREDENTIALS_MISSING"
else
  echo "VOLCENGINE_ACCESS_KEY: 已设置"
fi

• If output CREDENTIALS_MISSING：you must request credentials from the user, output:

  🔑 Volcengine access credentials need to be configured. Please provide:

  • AccessKey（AK）：
  • SecretKey（SK）：

• After the user provides them, store them in the shell variable VOLC_AK_INPUT / VOLC_SK_INPUT, and append --ak "$VOLC_AK_INPUT" --sk "$VOLC_SK_INPUT"。
• If the credentials already exist (VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY is already set), no need to ask, directly proceed to the self-check.

A. Offline self-check (no network access, run before each execution)

SCRIPTS_DIR=$(dirname "$(find ~ -maxdepth 8 -name "openapi_client.py" -path "*byted-marketing-agent-trending-list*" 2>/dev/null | head -1)")
SKILL_DIR=$(dirname "$SCRIPTS_DIR")
VENV_PY=$SKILL_DIR/venv/bin/python3

# 1) 检查虚拟环境是否存在
test -f $VENV_PY && echo "venv OK" || echo "venv 不存在，请先执行安装步骤"

# 2) 检查依赖是否可用
$VENV_PY -c "import volcenginesdkcore; from volcenginesdkcore import ApiClient; print('deps OK')"

# 3) 检查 volcengine-python-sdk 版本（必须 >= 4.0.43）
$VENV_PY -c "from importlib.metadata import version; print(version('volcengine-python-sdk'))"

# 4) 语法检查
$VENV_PY -m py_compile $SCRIPTS_DIR/openapi_client.py && echo "syntax OK"

Only after all self-checks pass (no errors) can subsequent business calls be executed.

Install virtual environment (execute when self-check fails)

SCRIPTS_DIR=$(dirname "$(find ~ -maxdepth 8 -name "openapi_client.py" -path "*byted-marketing-agent-trending-list*" 2>/dev/null | head -1)")
SKILL_DIR=$(dirname "$SCRIPTS_DIR")

# 1. 创建虚拟环境（仅首次）
python3 -m venv $SKILL_DIR/venv

# 2. 安装依赖
$SKILL_DIR/venv/bin/pip install 'volcengine-python-sdk>=4.0.43'

Known defect reminder: volcengine-python-sdk versions 4.0.1 to 4.0.42 (inclusive) have a defect in their built-in retry mechanism. It is strongly recommended to use >=4.0.43.

If the system lacks python3-venv：apt update && apt install python3-venv -y, then re-execute the above steps.

B. Online self-check (after self-check A passes, verify API connectivity)

SCRIPTS_DIR=$(dirname "$(find ~ -maxdepth 8 -name "openapi_client.py" -path "*byted-marketing-agent-trending-list*" 2>/dev/null | head -1)")
SKILL_DIR=$(dirname "$SCRIPTS_DIR")
VENV_PY=$SKILL_DIR/venv/bin/python3

# 若用户提供了凭证，附加 --ak / --sk；否则省略
$VENV_PY $SCRIPTS_DIR/openapi_client.py --format text \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  list-industries

To further verify list queries:

$VENV_PY $SCRIPTS_DIR/openapi_client.py --format text \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  query \
  --category "{从行业枚举中选择一个}" \
  --query-type hot_topic_insights \
  --task-date "2026-03-12" \
  --page 1 \
  --page-size 5

To verify hot events (hot_event):

$VENV_PY $SCRIPTS_DIR/openapi_client.py --format text \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  query \
  --category "{从行业枚举中选择一个}" \
  --query-type hot_event \
  --task-date "2026-03-12" \
  --page 1 \
  --page-size 5

Goal

Provide users with "trend ranking" capability:

1. Use "API 1" to get the queryable industry enumeration (industry only, does not include type).
2. After the user selects an industry, use this Skill's fixed type to query the trend ranking list under that industry.
3. After the user clicks a record, get the details by unique key (optional: expand from the list context or query the details again).

Interaction logic (mandatory)

When this Skill is triggered: you must first proactively call API 1 to get the latest industry enumeration (regardless of whether the user has already provided an industry).

Step 1: Industry enumeration (shared API 1)

$VENV_PY \
  $SCRIPTS_DIR/openapi_client.py \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  --format text list-industries

• If the user has not specified an industry, display the industry list for the user to choose.
• If the user has already specified an industry, you may still refresh the industry list when necessary for verification/correction, and after confirming the industry is valid, proceed to Step 2.
• Regardless of whether the user specifies query_type, by default query hot_topic_insights(topic trend ranking); only query hot_event。

Step 2: Query by industry

• This Skill's type is fixed to trending_list(do not expose/ask the user for type).
• The default query_type is hot_topic_insights, no need to ask the user; when the user says "event/hot event", switch to hot_event。
• Supports pagination and optional filter (filter is only reserved as an advanced capability, not used by default).
• Default sorting: topic trend ranking by 总播放量 DESC, hot events by 排名 DESC; the user may specify other fields.

YESTERDAY=$(date -v-1d +%Y-%m-%d 2>/dev/null || date -d "yesterday" +%Y-%m-%d)
$VENV_PY \
  $SCRIPTS_DIR/openapi_client.py --format json \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  query \
  --category "{industry_name}" \
  --query-type {hot_topic_insights|hot_event} \
  --task-date "$YESTERDAY" \
  --order-by "{总播放量 DESC | 排名 DESC}" \
  --page 1 \
  --page-size 20

• Always use --format json, the script returns complete fields, and you are responsible for formatting and displaying them.

When the user requests sorting by other dimensions, replace the value of --order-by :

Sortable fields for topic trend ranking:

• "总播放量 DESC" — total play count (default)
• "总点赞数 DESC" — total like count
• "总评论数 DESC" — total comment count
• "总分享数 DESC" — total share count
• "相关视频数量 DESC" — related video count

Sortable fields for hot events:

• "排名 DESC" — popularity ranking (default)
• "热度值 DESC" — popularity value

After returning list results each time, proactively inform the user which fields they can sort by, example guidance:

💡 Currently sorted by total play count. You can also ask me to sort by "like count", "comment count", "share count", or "related video count".

Step 3: Detail expansion (optional)

YESTERDAY=$(date -v-1d +%Y-%m-%d 2>/dev/null || date -d "yesterday" +%Y-%m-%d)
$VENV_PY \
  $SCRIPTS_DIR/openapi_client.py --format json \
  ${VOLC_AK_INPUT:+--ak "$VOLC_AK_INPUT"} ${VOLC_SK_INPUT:+--sk "$VOLC_SK_INPUT"} \
  query \
  --category "{industry_name}" \
  --query-type {hot_topic_insights|hot_event} \
  --task-date "$YESTERDAY" \
  --filter "{筛选表达式}" \
  --page 1 \
  --page-size 1

Example:

• Topic trend ranking details:--filter "任务ID = '{任务ID值}'"
• Hot event details:--filter "事件名称 = '三星S26 Ultra防窥屏及影像功能热议'"(or use 排名 = 1）

Data field description

The API returns each record, and fields differ slightly for different ranking types,all passed through, no trimming：

A. Topic trend ranking

Field name	Meaning
Main topic	Main challenge content in the trending topic
Related challenge 1 ~ Related challenge 5	The 1st to 5th related challenges
Share 1 ~ Share 5	The share of the corresponding related challenge
Official or not	Whether official hot topic (0=non-official, 1=official)
Commercial or not	Whether commercially related (0=non-commercial, 1=commercial)
Related video titles	List of topic-related video titles
Number of related videos	Number of topic-related videos
Total views	Total topic views
Total likes	Total topic likes
Total comments	Total topic comments
Total shares	Total topic shares
Total follows	Total topic follows
Total favorites	Total topic favorites
Total completions	Total topic completions
Topic description	Topic description information
Production date	Task run end date
Task name / Task date / Task ID	Task metadata

B. Hot list events

Field name	Meaning
Event name	Event name
Summary	One-sentence background/opinion summary
Related videos	List of related video titles (text)
Link	Search/aggregation page link
Heat value	Heat value
Rank	Heat ranking
Speech text	Speech-to-text (if any)
Analysis content	Structured analysis (if any)
Production date	Production date
Task name / Task date	Task metadata

Display specifications

⛔ ProhibitedAdding any content outside the structure specified by the template below, including introductions, summaries, personal analysis, or additional explanations. Directly pasting raw JSON is prohibited.

hot_topic_insights list view (fixed template)

## 🔥 {行业} 热点话题榜（{task_date}）｜按{排序字段中文名}排序

| # | 主话题 | 播放量 | 点赞 | 相关视频数 |
|---|--------|--------|------|-----------|
| 1 | {主话题} | {总播放量}万 | {总点赞数}万 | {相关视频数量} |
...

💡 你可以继续问我：
- {引导问题1}
- {引导问题2}
- {引导问题3}

hot_topic_insights detail view (fixed template)

### 🔍 {主话题}

{话题描述}

**关联挑战分布：**
| 关联挑战 | 占比 |
|----------|------|
| {关联挑战1} | {占比1}% |
| {关联挑战2} | {占比2}% |
...（仅展示非空项）

**数据：** 播放 {总播放量}万 · 点赞 {总点赞数}万 · 评论 {总评论数}万 · 相关视频 {相关视频数量} 条

💡 你可以继续问我：
- {引导问题1}
- {引导问题2}
- {引导问题3}

hot_event list view (fixed template)

## 📰 {行业} 热榜事件（{task_date}）

| 排名 | 事件 | 摘要 | 热度值 | 链接 |
|------|------|------|--------|------|
| {排名} | {事件名称} | {摘要} | {热度值} | [查看](url) |
...

💡 你可以继续问我：
- {引导问题1}
- {引导问题2}
- {引导问题3}

hot_event detail view (fixed template)

### 🔍 {事件名称}

**摘要：** {摘要}

**相关视频（Top3）：**
- {相关视频 前3条，每条一行}

**分析：** {分析内容}

热度值 {热度值} · 排名 {排名}　[查看聚合页](url)

💡 你可以继续问我：
- {引导问题1}
- {引导问题2}
- {引导问题3}

Numeric rule: keep 1 decimal place; if less than 10,000, display the original value;url When empty, display "—".

Guiding question specifications (must be executed after each returned result)

After each business result is output, 2–3 guiding questions must be appended at the end, to help users explore further. Guiding questions shouldbring in the current context(industry name, date, title), so that users can continue by replying directly.

After returning the industry list

💡 You can continue to ask me:

• "Help me look up trend videos for **[a certain industry]**" (fill in the industry name, and the user can directly confirm)
• "I want to see what hot events there are recently"

After returning the topic trend ranking (hot_topic_insights)

💡 You can continue to ask me:

• "Help me expand the detailed content of "{the No. 1 challenge}""
• “{current industry} What hot list events have there been recently?" (automatically switch to hot_event)
• "Switch to another industry to take a look, for example **[recommend another industry]**"

After returning to hot list events (hot_event)

💡 You can continue to ask me:

• "Expand the detailed content of "{the No. 1 event name}""
• “{current industry} What hot topic challenges have there been recently?" (automatically switch to hot_topic_insights)
• "Switch to another industry to view hot list events"

After returning a single detail

💡 You can continue to ask me:

• "Look at the next item in the list"
• “{current industry} What hot list events are there?" or "{current industry} What hot topics are there?" (guide to look at another type)
• "Switch to another industry to check"

Principle: The two types should drive traffic to each other—after viewing topic trends, guide the user to view hot list events; after viewing events, guide the user to view related topic challenges, forming a complete content exploration loop.

Parameter rules

• industry_name: Must come from the industry enumeration returned by Interface 1 (or be consistent with it).
• type：Prohibited from being delivered by Interface 1; it is fixed internally by this Skill as trending_list。
• query_type: Supports hot_topic_insights / hot_event。
• task_date: By default, take T-1 (yesterday), i.e., $(date -v-1d +%Y-%m-%d 2>/dev/null || date -d "yesterday" +%Y-%m-%d); when the user specifies a date, the user's choice prevails.

Error handling

• API call failure: only output a brief failure reason to the user (do not include URL/Token/script name/stack trace).
• Missing industry: output the industry candidate list (appropriately truncated) and let the user choose.
• No data: output "This industry currently has no trend ranking data."
• Industry/type not supported: if the service returns "unknown task/not supported", output "This industry does not currently support this ranking type (hot_event/hot_topic_insights)."

Credential description (for execution only; do not echo to users)

Volcengine SDK authentication (required for API calls)

This Skill uses volcenginesdkcore.ApiClient to initiate a signed request to cdp-saas.cn-beijing.volcengineapi.com .\nAction: ArkOpenClawSkill，Version: 2022-08-01。

CredentialsObtained only through user input; priority:--ak/--sk parameter > environment variable VOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY。

• VOLCENGINE_ACCESS_KEY：AccessKey
• VOLCENGINE_SECRET_KEY：SecretKey
• VOLC_SERVICE: Override the Service name (optional, default cdp_saas）
• VOLCENGINE_REGION: Override Region (optional, default cn-beijing）

This Skill's query_type

• Default use:hot_topic_insights
• Optional use:hot_event

Optional override

• PUBLIC_INSIGHT_API_URL: Override the default endpoint (for internal debugging only)

Security requirement: Prohibited in SKILL.md or in code to hard-code plaintext AK/SK.