audience-report-zh

name	audience-report-zh
description	透過 show_widget 產出 DXP 受眾分析報告。觸發條件：Segment ID + 月份、上傳受眾資料檔案、或多受眾比較請求。以繁體中文輸出。

受眾分析報告 Skill

在 Chat 介面中透過 Visualizer（show_widget 工具）產出完整的視覺化受眾分析報告。

語言規則（最高優先級）：一律以使用者當前書寫的語言回覆。使用者寫繁體中文就用繁體中文回覆； 寫英文就用英文回覆。報告內容（標題、標籤、圖表軸線、tooltip、洞察、建議）皆須與使用者語言一致。 產業縮寫如 KOL、KOC、ROI、CPM、GCS、DXP 為例外，無論語言皆可直接使用。

觸發條件

當符合以下任一條件時觸發本 skill：

1. 使用者提供受眾 ID（如 tm:d1028、tm:d_3542_k_140——以 tm: 開頭）+ YYYYMM 月份（如 202602）+ 提及「受眾」、「報告」或「分群」
2. 使用者上傳受眾資料檔（關鍵字頻率 JSON、消費力 JSON、用戶輪廓 TXT）並要求分析
3. 使用者要求比較多組受眾——「比較」、「差異」、「哪個受眾」

多個 Segment ID 自動切換為比較模式。所有輸出必須透過 show_widget 呈現——不得產出 docx/pptx/pdf 檔案。

判斷報告模式

開始前先判斷使用哪種模式：

• 單一受眾模式 — 使用者提供一組受眾資料。產出 7 節深度報告（Section 1–7）。
• 多受眾比較模式 — 使用者提供 2 組以上受眾（多個 Segment ID、多組檔案、或明確要求「比較」）。產出比較報告（Section C1–C5）。

判斷多受眾模式的訊號：

• 提及多個 segment 名稱或 ID
• 多份 consumption_distribution 檔案含不同 segment 欄位
• 多份不同受眾的 user profile 檔案
• 使用者說「比較」、「compare」、「異同」、「differences」、「哪個受眾」、「which audience」

不確定時，詢問使用者確認。

---

預期輸入檔案

每個受眾最多可有四種資料，並非全部必要。

檔案類型	格式	說明
瀏覽關鍵字頻率	JSON {"keyword": weight, ...}	瀏覽行為關鍵字權重（0–100）
購買關鍵字頻率	JSON {"keyword": weight, ...}	購買行為關鍵字權重（0–100）
消費力分佈	JSON 含 consumption_distribution 陣列 {range, user_count}	消費力區間分佈
用戶輪廓描述	TXT 或 JSON	AI 預測的人口統計、興趣、購物偏好

多受眾模式時，每個受眾提供一組檔案。檔名通常含受眾名稱（如 Segment_轉址網站_-_超市零售_消費力原始資料.json），處理前先按受眾分組。

---

Section 0：透過 Tagtoo MCP Gateway 取得資料

當使用者提供 Segment ID 和 月份（YYYYMM 格式）而非直接上傳檔案時，先透過 Tagtoo MCP Gateway 取得報告資料。

使用者須提供的輸入

輸入	格式	範例
Segment ID	字串，可含冒號和底線	tm:d1028、tm:d_3542_k_140
月份	YYYYMM	202602

如使用者說「幫我看 tm:d1028 二月的受眾報告」，擷取：

• Segment ID = tm:d1028
• Month = 202602

若提供多個 Segment ID，分別取得資料後自動進入多受眾比較模式。

MCP 工具

使用 Tagtoo MCP Gateway server 的 dxp-mcp_get_audience_report 工具。每個受眾一次呼叫即可取得所有四種資料（用戶輪廓、瀏覽關鍵字、購買關鍵字、消費力分佈）。

參數：

參數	型別	必填	說明
segment_id	string	是	受眾 ID（如 tm:d1028）
year_month	string	是	報告月份，YYYYMM 格式（如 202604）
party_type	string	否	first、second 或 insite_second。省略時自動探測三種類型
insite_or_outsite	string	否	僅 party_type 為 first 時生效。值：insite 或 outsite。省略時優先站內，無資料才回傳站外
language	string	否	zh（預設，繁體中文）或 en（英文）

本 skill 預設使用 language = "zh"。

回傳格式

成功（單筆符合）：

{
  "party_type": "second",
  "insite_or_outsite": null,
  "report": {
    "user_profile_pic_url": "https://storage.googleapis.com/.../使用者輪廓.png",
    "user_profile_txt": "1. 年齡：25-40歲\n2. 性別：...\n3. 興趣：...\n4. 購物偏好：...",
    "purchase_power_pic_url": "https://storage.googleapis.com/.../消費力分佈.png",
    "view_wordcloud_pic_url": "https://storage.googleapis.com/.../熱門瀏覽商品關鍵字.png",
    "purchase_wordcloud_pic_url": "https://storage.googleapis.com/.../熱門購買商品關鍵字.png",
    "purchase_power_data": {
      "segment": "轉址網站 - 購物狂熱者",
      "location": "",
      "consumption_distribution": [
        {"range": "1000以下", "user_count": 534},
        {"range": "1001~3000", "user_count": 708},
        {"range": "3001~5000", "user_count": 192}
      ]
    },
    "view_freq_data": {
      "露營帳篷": 100.0,
      "DHA魚油": 92.3,
      "日拋隱形眼鏡": 87.1
    },
    "purchase_freq_data": {
      "DHA魚油": 100.0,
      "益生菌": 88.7,
      "膠原蛋白": 82.4
    }
  }
}

report 欄位參考：

欄位	型別	使用於	說明
user_profile_txt	string	Section 2	AI 預測的 persona 文字（人口統計、興趣、購物偏好）
user_profile_pic_url	string	—	預先產出的用戶輪廓圖片 URL（僅供參考）
purchase_power_data	object	Section 1, 3, C1, C3	原始消費力分佈 JSON，含 segment、location 和 consumption_distribution 陣列（{range, user_count}）
purchase_power_pic_url	string	—	預先產出的消費力分佈圖表 URL（僅供參考）
view_freq_data	object	Section 1, 4, 6, C1, C4a	瀏覽關鍵字頻率：{"keyword": weight}，權重 0–100
purchase_freq_data	object	Section 1, 5, 6, C1, C4b	購買關鍵字頻率：{"keyword": weight}，權重 0–100
view_wordcloud_pic_url	string	—	預先產出的瀏覽文字雲圖片 URL（僅作 fallback）
purchase_wordcloud_pic_url	string	—	預先產出的購買文字雲圖片 URL（僅作 fallback）

成功（多筆符合）：

{
  "matches": [
    {"party_type": "first", "insite_or_outsite": "insite", "report": { ... }},
    {"party_type": "second", "insite_or_outsite": null, "report": { ... }}
  ]
}

當回傳多筆時，使用與使用者指定相符的 party_type。若使用者未指定，優先使用 second。

失敗：

{
  "error": "查不到 segment tm:d9999 的報告"
}

向使用者回報錯誤，跳過依賴缺失資料的報告節次。

重要注意事項

• 不需手動建構 GCS 路徑。 MCP 工具內部處理 bucket 路由、party_type 探測和檔案查找。
• party_type 自動探測： 省略 party_type 時，工具會自動探測三種類型。僅在使用者明確指定時才傳入。
• 大型回應處理： 報告 JSON payload 可能很大。若 MCP 回傳結果被存為本地檔案，用 bash_tool + Python 讀取處理。
• 錯誤處理： 若找不到受眾的當月資料，回應會包含 error 欄位。回報缺失資料並以已取得的資料繼續。

使用回傳資料

呼叫 dxp-mcp_get_audience_report 後，從回傳中取出 report 物件。若回傳包含 matches 陣列（多筆符合），選擇與使用者指定 party_type 相符的那筆（未指定時優先選 second），再取出其 report 物件。

後續各 Section 以 report. 前綴引用資料欄位——例如 report.view_freq_data 指的是 report 物件中的 view_freq_data 欄位，report.purchase_power_data.consumption_distribution 指的是 purchase_power_data 內的 consumption_distribution 陣列。

多受眾取得

提供多個 Segment ID 時，每個受眾呼叫一次 dxp-mcp_get_audience_report。從每個回傳中獨立取出 report 物件，依 Segment ID 分組管理。全部取得後判斷報告模式。

---

單一受眾報告（Section 1–7）

依序產出，若無對應資料則跳過。每節使用一次 show_widget，節與節之間插入 1–3 段文字分析（不可連續堆疊 widget）。

Section 1：報告標頭與 KPI 儀表板

目的： 一眼掌握受眾規模。

輸出： 受眾名稱橫幅 + 3–4 張指標卡：瀏覽關鍵字數、購買關鍵字數、總消費者數、主要消費區間。

Widget 版面：

• 頂部顯示受眾名稱 + 圖示
• CSS grid repeat(4, minmax(0, 1fr)) 排列指標卡
• 每張卡：13px 淺色標籤 + 24px/500 數字
• 卡片樣式：background: var(--color-background-secondary)，無邊框，border-radius: var(--border-radius-md)，padding 1rem

資料來源： report.view_freq_data 和 report.purchase_freq_data 的 key 數量；report.purchase_power_data.consumption_distribution 的 user_count 總和；最大 user_count 對應的 range。

Section 2：用戶 Persona

目的： 在看圖表前先建立對受眾的認識。

輸出： 純文字（無 widget）。根據 profile 檔案摘要人口統計、興趣、購物行為，強調對受眾的洞察意涵。

Section 3：消費力分佈

目的： 回答「這群受眾的消費力如何？」

輸出： Chart.js 垂直長條圖，每個消費區間一根長條，顯示人數。

Widget 版面：

• Canvas 在 <div> 中，height: 320px; position: relative
• type: 'bar'，tooltip：ctx.parsed.y + ' 人'
• 下方自訂 HTML 圖例

Widget 後文字： 說明主要消費區間、佔比、對受眾價值的意涵。

Section 4：瀏覽興趣文字雲

目的： 回答「這群受眾對什麼有興趣？」——文字雲一眼呈現整體興趣面貌，字體大小對應權重。

輸出： 前 30 個瀏覽關鍵字的文字雲，透過 show_widget 渲染。

強制規則： 讀取資料後必須立即執行，以下嚴格禁止：

• ❌ 長條圖（水平或垂直） ❌ 表格 ❌ Bullet list ❌ 任何非文字雲的圖表類型

產出步驟：

1. 從 report.view_freq_data 取得瀏覽關鍵字，依權重降序排列，取前 30
2. 在 bash_tool 中執行 dxp-audience-report-style.md 的「Section 4/5: Single Audience Word Cloud Python Template」，使用瀏覽參數：CONTAINER_ID=wc4、TITLE=Browse Keywords Top 30、 TITLE_COLOR=#185FA5、BG_COLOR=#f0f6ff、TOOLTIP_LABEL=Browse Score、 PR=[55,138,221]、LT=[168,205,239]
3. 將產出的 HTML 字串以 show_widget 渲染

Widget 後文字： 解讀 top 關鍵字揭示的 persona 特徵——生活階段、志向、購買意圖訊號。

Section 5：購買行為文字雲

目的： 回答「他們實際買了什麼？」——消費的真實面貌。

輸出： 前 30 個購買關鍵字的文字雲，透過 show_widget 渲染。

強制規則： 同 Section 4——僅限文字雲，不得使用其他圖表類型。

產出步驟： 同 Section 4 流程，改用 report.purchase_freq_data 和購買參數： CONTAINER_ID=wc5、TITLE=Purchase Keywords Top 30、TITLE_COLOR=#993C1D、 BG_COLOR=#fff5f2、TOOLTIP_LABEL=Purchase Score、PR=[216,90,48]、LT=[240,180,154]

Widget 後文字： 主要購買關鍵字、品牌/品類特徵、實際消費行為的洞察。

Section 6：瀏覽 vs 購買落差分析

目的： 揭示興趣與行動的落差——最具行動力的章節。

輸出： 雙欄比較版面 + 洞察方框。

Widget 版面：

• 左欄標題：「瀏覽興趣」——前 10 個瀏覽關鍵字以彩色膠囊呈現
• 中間：箭頭圖示
• 右欄標題：「實際購買」——前 10 個購買關鍵字以彩色膠囊呈現
• 底部：洞察方框（background: var(--color-background-warning)）

產出方式： 從 report.view_freq_data 取前 20 瀏覽關鍵字，從 report.purchase_freq_data 取前 20 購買關鍵字。比較兩組集合，找出僅出現在瀏覽（未滿足需求/櫥窗瀏覽）和僅出現在購買（慣性消費）的關鍵字。

Section 7：行銷建議

目的： 將洞察轉化為可執行的行動。

輸出： 3–4 張垂直堆疊的策略卡。

Widget 版面：

• 卡片樣式：白色背景、0.5px 邊框、border-radius-lg、padding 1.25rem
• 優先級徽章搭配語意色彩（如「高優先」、「中優先」）
• 最高優先卡：border: 2px solid var(--color-border-info)

產出方式： 由 Section 3–6 推導。常見類型：交叉銷售、瀏覽轉購買、促銷時機、persona 定向投放。

---

多受眾比較報告（Section C1–C5）

當提供 2 組以上受眾時，報告從深度分析轉為跨受眾比較。目標：這些受眾有何相似、有何不同、對行銷策略的意涵為何？

開始前，獨立處理每個受眾的資料（關鍵字排序、消費統計），以結構化格式存放以便並排比較。

Section C1：比較儀表板

目的： 一眼看出各受眾的規模差異。

輸出： 表格式 grid，每欄一個受眾。

Widget 版面：

• 標題列：受眾名稱（每欄一個）
• 指標列：瀏覽關鍵字數、購買關鍵字數、總消費者數、主要消費區間——每受眾每列一值
• 以淺色底標示每列最高/最低值（background: var(--color-background-info) 最高、background: var(--color-background-danger) 最低）
• 2 個受眾：repeat(2, minmax(0, 1fr))
• 3–4 個：repeat(N, minmax(0, 1fr))
• 5+ 個：垂直堆疊避免擁擠

Widget 後文字： 一段文字摘要規模差異。

Section C2：Persona 比較

目的： 並排展示人物輪廓，讓讀者感受差異。

輸出： 每個受眾一張卡，含 3–4 行 persona 摘要，各受眾使用不同的強調色。

Widget 版面：

• 卡片排列同 C1 的 grid
• 每張卡：頂部色條（2px solid，使用受眾指定色）、白色背景、其他邊 0.5px 邊框
• Persona 文字：13px、secondary color、1.6 行高

Widget 後文字： 指出關鍵 persona 差異——年齡、性別、興趣、生活階段。

Section C3：消費力比較

目的： 哪個受眾花費更多？消費模式有何不同？

輸出： Chart.js 群組長條圖，每個受眾一色，顯示各消費區間的人數。

Widget 版面：

• type: 'bar'，多組 datasets
• 每組 dataset 使用受眾指定色
• 群組模式：options.scales.x.stacked = false
• Canvas wrapper 高度：360px
• 自訂圖例顯示受眾名稱 + 色塊

Widget 後文字： 比較主要消費區間、整體消費力高低。

Section C4：興趣與購買重疊分析

目的： 核心比較——受眾在瀏覽和購買上的重疊與差異。

輸出： 依序兩個 widget（中間插入文字）：

Widget C4a — 瀏覽興趣比較： 並排文字雲，每個受眾前 30 個瀏覽關鍵字。強制使用文字雲，不得使用其他圖表類型。

建構方式：

1. 每個受眾從 report.view_freq_data 取得瀏覽關鍵字，依權重降序排列，取前 30
2. 使用 dxp-audience-report-style.md 的「Section C4: Side-by-Side Word Clouds」HTML 模板——CSS grid 每欄一個受眾的文字雲
3. 每個受眾使用其指定色系的漸層（受眾 1: Blue pr/lt、受眾 2: Coral pr/lt）
4. Tooltip 標籤：Browse Score
5. 3 個以上受眾時，擴展 grid 欄數

C4a 與 C4b 間文字： 指出跨受眾共有的關鍵字（共同興趣）vs 僅某受眾獨有的（差異化因素）。

Widget C4b — 購買比較： 同 C4a 結構，改用購買資料。每個受眾前 30 個購買關鍵字的並排文字雲。強制使用文字雲。

建構方式：

1. 每個受眾從 report.purchase_freq_data 取得購買關鍵字，依權重降序排列，取前 30
2. 同 C4a 模板，tooltip 改為 Purchase Score，標題改為 Purchase Keywords Comparison Top 30

C4b 後文字： 找出共有購買關鍵字（可共同投放）、獨有關鍵字（差異化投放）、瀏覽 vs 購買的跨受眾落差。

Section C5：比較式建議

目的： 利用受眾差異的可行策略。

輸出： 策略卡（同 Section 7），每張卡標示適用的受眾名稱徽章。

建議推導：

• 共同優勢：所有受眾都強的分類 → 統一投放
• 獨特機會：僅一個受眾強的分類 → 定向投放
• 落差套利：受眾 A 瀏覽但受眾 B 購買的分類 → 跨受眾交叉推廣
• 預算分配：消費力較高的受眾 → 對應加碼；瀏覽-購買一致性較好的受眾 → 效率型投放

---

資料處理

MCP 回傳的 report.view_freq_data 和 report.purchase_freq_data 都是 {"keyword": weight} 物件。Section 4、5、C4a、C4b 都用同樣的模式——依權重排序，取前 30：

# data = report.view_freq_data 或 report.purchase_freq_data
# （已是 dict，不需讀檔）

top30 = sorted(data.items(), key=lambda x: -x[1])[:30]

for keyword, weight in top30:
    print(f'{keyword}: {weight:.1f}')

多受眾模式，每個受眾執行一次：

# data_a = 受眾 A 的 report.view_freq_data
# data_b = 受眾 B 的 report.view_freq_data
segment_tops = {
    'seg_a': sorted(data_a.items(), key=lambda x: -x[1])[:30],
    'seg_b': sorted(data_b.items(), key=lambda x: -x[1])[:30],
}

lookup = {seg: dict(tops) for seg, tops in segment_tops.items()}
all_keywords = sorted(set(k for tops in segment_tops.values() for k, _ in tops))
for kw in all_keywords:
    print(kw, {seg: lookup[seg].get(kw, 0) for seg in segment_tops})

不翻譯關鍵字： 原樣顯示資料中的關鍵字文字，不翻譯或分類。

受眾色彩配置（多受眾模式）

受眾序號	色系	Primary (400)	Light fill (50)
受眾 1	Blue	#378ADD	#E6F1FB
受眾 2	Coral	#D85A30	#FAECE7
受眾 3	Teal	#1D9E75	#E1F5EE
受眾 4	Purple	#7F77DD	#EEEDFE
受眾 5	Amber	#854F0B	#FAEEDA

分類色盤（單一受眾模式）

供文字雲渲染器使用（Section 4、5、C4a、C4b）。每個文字雲依關鍵字權重在 light (lt) 和 primary (pr) 色之間插值。

序號	色系	Dot/bar (400)	Card fill (50)	Card title (800)	Card subtitle (600)
0	Blue	#378ADD	#E6F1FB	#0C447C	#185FA5
1	Coral	#D85A30	#FAECE7	#712B13	#993C1D
2	Pink	#D4537E	#FBEAF0	#72243E	#993556
3	Teal	#1D9E75	#E1F5EE	#085041	#0F6E56
4	Amber	#854F0B	#FAEEDA	#633806	#854F0B
5	Green	#639922	#EAF3DE	#27500A	#3B6D11
6	Purple	#7F77DD	#EEEDFE	#3C3489	#534AB7
7	Red	#E24B4A	#FCEBEB	#791F1F	#A32D2D
8	Gray	#888780	#F1EFE8	#444441	#5F5E5A

Chart.js 共用設定

• Dark mode：const isDark = matchMedia('(prefers-color-scheme: dark)').matches
• Ticks：isDark ? '#c2c0b6' : '#5f5e5a'；Grid：isDark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.06)'
• 停用預設圖例；建立自訂 HTML 圖例搭配 10px 色塊
• Canvas 放在有明確高度和 position: relative 的 <div> 中
• 載入：<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.js">
• 所有數字取整；Canvas 無法解析 CSS 變數——使用硬編碼 hex

報告完成後

以結構化摘要列出所有已產出的章節，並提供後續步驟建議：

• 將分類規則擷取為可重複使用的對照表
• （多受眾模式）針對特定受眾展開完整單一深度報告