app-store-review-arbitrage
將競爭對手的 App Store 或 Google Play 網址轉換為一次性的進入市場簡報：包含排名化的投訴群集、違背承諾地圖、到達頁面標題和廣告文案方向——所有內容皆源自逐字評論。
重要規則（請在步驟 1 之前閱讀）
以下規則適用於所有步驟。違反任何一條都會導致自我品質驗證（步驟 6）失敗。
- 每段引文都必須是逐字原文。 不得改寫、不得修正文法、不得清理。只能使用審查者的原始措辭。
- 不得捏造統計數據。 除非審查者明確使用了類似措辭，否則不得撰寫「快 40%」或「可靠 2 倍」。自我品質驗證步驟會檢查未附來源的百分比。
- 群集名稱必須使用審查者的語言。 請研究步驟 3 中的反模式表格。
- 每個標題和廣告文案方向都必須引用其來源群集。 格式：
[集群："集群名稱"]。 - 輸出中「始終」包含第 2 節——即使處於降級狀態。永遠不要跳過或省略它。
- 任何生成的文案中不得使用禁用詞： powerful、robust、seamless、innovative、game-changing、streamline、leverage、revolutionize、transform。
步驟 1 — 解析輸入並偵測平台
接受包含一個應用程式網址的自然語言提示。提取該網址。
平台偵測：
apps.apple.com→ App Storeplay.google.com/store/apps/details?id=→ Google Play- 任何其他網址 → 停止並回覆：「請提供直接的 App Store 或 Google Play 網址。我無法分析來自其他來源的評論資料。」
ID 提取（在呼叫腳本前執行此操作）：
| 平台 | 提取內容 | 方法 |
|---|---|---|
| App Store | 數字型 app_id | 網址中 /id 後方的數字 |
| App Store | country | apps.apple.com/ 後方的 2 字母代碼（例如 us、gb） |
| Google Play | package_name | id= 查詢參數的值 |
保留提取的值——你在步驟 7 輸出檔案名稱時會需要它們。
如果使用者的提示中提供了 product_context（他們自己的產品是做什麼的），請儲存它——用於在步驟 5 中個人化文案。
步驟 2 — 收集評論與中繼資料
執行完整的擷取腳本：
python3 scripts/fetch_reviews.py "{app_url}" --output {tmpdir}/asr-raw.json
（注意：將 {tmpdir} 替換為你作業系統的暫存目錄，例如 macOS/Linux 的 /tmp 或 Windows 的 C:\Temp）。
這會同時擷取商店描述中繼資料和評論。
- App Store： iTunes API——免費，無需驗證。App Store 評論透過 Apple 的公開 iTunes RSS Feed 擷取。由於 Apple API 的限制，某些應用程式可能回傳 0 則評論——在這種情況下，技能會使用可用資料繼續執行並記錄警告。Google Play 是主要支援的路徑。
- Google Play：
google-play-scraper套件——免費，無需驗證
如果腳本失敗，請從標準錯誤輸出讀取錯誤訊息。常見原因：
- 套件未安裝：執行
pip install google-play-scraper - 應用程式未找到：確認網址是目前有效的商品頁面
- Google Play API 錯誤：執行
pip install --upgrade google-play-scraper並重試
腳本會將收集進度列印到標準錯誤輸出。等待它完成。完成後，讀取 {tmpdir}/asr-raw.json 並向使用者顯示收集摘要：
✓ 從 [平台] 收集到 [N] 則評論（[N] 則低星等 1–3★）
日期範圍：[最舊] 到 [最新]
套件：[iTunes API | google-play-scraper]
檢查退出碼：
- 退出碼 0 → 收集成功，檢查
metadata.store_description。如果為 null：請注意——第 2 節將使用降級狀態。繼續步驟 3。 - 退出碼 1 → 錯誤（讀取標準錯誤輸出訊息，向使用者顯示，然後停止）
- 退出碼 2 → 觸發關卡 1（找到少於 10 則低星等評論）
關卡 1 — 低訊號停止： 如果腳本以退出碼 2 結束，請從 {tmpdir}/asr-raw.json 讀取 gate_message 並如實向使用者顯示。不要繼續步驟 3。不要產生部分簡報。
步驟 3 — 投訴群集
從 {tmpdir}/asr-raw.json 載入 low_star_reviews。
將所有低星等評論聚集到 4–6 個命名投訴主題。使用以下公式為每則評論評分：
complaint_weight = (4 - rating) × recency_factor
recency_factor:
評論年齡 ≤ 90 天 → 1.0
評論年齡 91–365 天 → 0.7
評論年齡 > 365 天 → 0.4
評論年齡 = （今天日期）−（評論 date 欄位）的天數。
cluster_score = 群集中所有評論的 complaint_weight 總和。
群集命名——關鍵規則：
你可能會想使用抽象名稱。請抵制這個衝動。使用評論中的確切動詞和名詞。
| ❌ 抽象化（錯誤） | ✅ 審查者語言（正確） |
|---|---|
| "穩定性問題" | "匯出為 PDF 時崩潰" |
| "同步問題" | "手機與桌面同步後資料遺失" |
| "獲利摩擦" | "3 天後出現付費牆，並非原本承諾的 14 天" |
| "效能下降" | "每次搜尋時應用程式就凍結" |
| "入職問題" | "不知道如何邀請團隊成員" |
規則：
- 每則評論僅屬於一個群集（指派給其最主要的投訴主題）
- 丟棄任何少於 3 則評論的群集——將其記錄為雜訊
- 為每個群集選擇 3–4 則逐字引文：先選最低星等，再選最新
關卡 2 — 最小群集大小： 丟棄少於 3 則評論的群集後，檢查還剩下多少個群集。
關卡 3 — 低信心標記： 如果剩餘少於 3 個群集：
- 請勿停止。繼續輸出。
- 在應用程式中繼資料之後，立即在簡報標頭前面加上：
⚠ 低信心： 只有 [N] 個投訴群集達到最低證據門檻（≥ 3 則佐證評論）。輸出反映了有限的資料。請考慮使用評論更多的競爭對手，或放寬評分過濾器。
- 在輸出中包含中等層級的群集（分數 ≥ 5）
層級分類（用於第 1 節的排行榜表格）：
- 嚴重：分數 ≥ 60
- 高：分數 15–59
- 中等：分數 5–14（僅在觸發關卡 3 時包含）
- 雜訊：分數 < 5（丟棄，不包含）
將群集寫入 {tmpdir}/asr-clusters.json：
{
"clusters": [
{
"name": "使用審查者語言的群集名稱",
"score": 34.5,
"tier": "High",
"review_count": 14,
"verbatim_quotes": [
{"rating": 1, "text": "確切的審查者措辭", "date": "YYYY-MM-DD"},
...
]
}
],
"discarded_noise": 2,
"gate_3_triggered": false
}
步驟 4 — 違背承諾偵測
這一步是此技能區別於所有現有工具的關鍵。它必須作為一個獨立的、有名稱的步驟來執行。
載入：
- 來自
{tmpdir}/asr-raw.json的metadata.store_description - 來自
{tmpdir}/asr-clusters.json的所有群集
如果 store_description 為 null： 設定 store_description_available: false。寫入 {tmpdir}/asr-promises.json，其中包含空的 broken_promises 陣列和如下指定的 detection_note。繼續執行步驟 5。
如果商店描述可用：
-
提取聲明。 聲明是任何關於應用程式行為的具體、可測試的主張。請參閱
references/broken-promise.md以獲取完整定義和範例。排除模糊的讚美詞、團隊描述和媒體引述。 -
交叉比對。 對於每個聲明，檢查所有群集名稱和逐字引文。當群集直接記錄了所承諾行為的失敗時（至少 3 則評論），就存在矛盾。
-
產生違背承諾記錄 ——每個經確認的矛盾一條記錄：
{ "claim_text": "來自商店描述的逐字摘錄", "complaint_cluster": "確切的群集名稱", "gap_label": "聲稱 X；使用者回報 Y", "evidence_count": 18 }
寫入 {tmpdir}/asr-promises.json：
{
"store_description_available": true,
"broken_promises": [...],
"no_contradictions_found": false,
"detection_note": null
}
降級狀態：
- 無描述：
store_description_available: false，detection_note: "商店描述不可用（擷取於 YYYY-MM-DD，回傳空值）。無法執行違背承諾比對。" - 無矛盾：
no_contradictions_found: true，detection_note: "未偵測到違背承諾。商店描述似乎並未相對於投訴群集過度宣稱。"
請參閱 references/broken-promise.md 以了解反模式（什麼不該標記）。
步驟 5 — 產生文案
使用步驟 3 的群集和步驟 4 的違背承諾，產生簡報的第 3 至 5 節。
文案規則（適用於所有三個章節）：
- 每個標題和方向都必須引用其來源群集：
[集群："集群名稱"] - 不得使用禁用詞：powerful、robust、seamless、innovative、game-changing、streamline、leverage、revolutionize、transform
- 不得捏造統計數據——除非審查者使用了它們，否則不得出現百分比或數字
- 如果提供了
product_context：讓「這麼說」的方向具體針對該產品的功能。如果沒有：則撰寫成使用者可以填寫的定位模板。 - 在標題中使用審查者的語言——從實際評論文字中衍生或引用
第 3 節 — 到達頁面 H1 儲備庫（3–5 個標題）：
- 每個：
"[標題文字]" [集群："集群名稱"] - 盡可能 ≤ 8 個字
- 直接對沮喪的使用者說話
第 4 節 — 廣告文案方向（恰好 3 組）：
集群：[群集名稱]
別說那套："[競爭對手宣稱的內容或一個普通的弱替代方案]"
要這麼說："[基於投訴證據的反向宣稱]"
證據：[N] 位審查者回報了 [逐字投訴摘要]
第 5 節 — 反聲明警告：
- 步驟 4 中每個違背承諾對應一個警告
- 如果第 2 節處於降級狀態：一個註記（確切措辭請參閱
references/brief-format.md）
步驟 6 — 自我品質驗證
在儲存之前，根據以下檢查驗證產生的簡報。如果任何檢查失敗，請修正特定項目並重新驗證——不要儲存失敗的簡報。
| 檢查 | 規則 |
|---|---|
| 存在逐字引文 | 每個群集至少有 ≥ 2 段逐字引文 |
| 無禁用詞 | 9 個禁用詞均未出現在第 3–5 節中 |
| 無未引用百分比 | 輸出中的任何 % 都必須追溯到審查者的實際措辭 |
| 所有文案皆已引用 | 每個標題和「要這麼說」都有一個 [集群："名稱"] 引用 |
| 群集計數 ≥ 1 | 至少有一個群集通過了關卡 2/3 |
| 第 2 節存在 | 第 2 節出現在輸出中（無論何種狀態） |
| 引文評分 ≤ 3 | 所有逐字引文皆來自 1–3★ 評論 |
關於群集計數的說明： 通過簡報的最低要求是 1 個群集（而不是 3 個）。關卡 3 的低信心標記會處理少於 3 個群集倖存的情況——那是一個警告，不是失敗。只有當 0 個群集存在時，自我品質驗證才會失敗。
步驟 7 — 儲存輸出
按照 references/brief-format.md 的格式組裝完整簡報。
儲存至：
docs/review-briefs/[app-id]-[YYYY-MM-DD].md
如果 docs/review-briefs/ 目錄不存在，請建立它。
將完整簡報列印給使用者。
清理暫存檔案：{tmpdir}/asr-raw.json、{tmpdir}/asr-clusters.json、{tmpdir}/asr-promises.json。