Name: app-keyword-research
Author: 社群技能

App 關鍵字研究

從 Apple 公開的 App Store 數據中回答關於一個 App 點子的三個問題，無需帳號或 API 金鑰：

流量： 人們是否在搜尋這個點子，以及用哪些詞？
難度： 要為這些詞取得排名有多難？
市場： 哪些 App 佔據這個領域、它們的規模有多大、以及它們如何賺錢？

最終會給出結論、要鎖定的關鍵字，以及 App Store 的標題、副標題與關鍵字欄位建議。

工作流程

1. 將點子轉換為 10–20 個種子詞組

種子詞組是起始搜尋詞；腳本會透過自動完成功能擴展每個詞。涵蓋以下類別：

核心任務，用使用者自己的話來說： 「心算」、「習慣追蹤」（而不是「數理能力提升」）。
同義詞與替代名稱： 「數學遊戲」、「算術」、「九九乘法表」。
目標受眾： 「成人數學遊戲」、「… 給兒童」。不同的受眾就是不同的市場。
它會競爭的相鄰類別： 對數學 App 來說是「腦力訓練」。
結果導向的詞組： 「快速心算」、「數學練習」。

不要加入競爭對手的品牌名稱。它們無論如何都會出現在結果中，這對市場版圖很有幫助。

其他國家的種子詞組要用它們自己的語言。 德國人搜尋德國人會打的字（「kalorienzähler」，而不是「kalorien tracker」），所以要為每個市場撰寫當地人會輸入的種子詞，並透過自動完成檢查。千萬不要直接翻譯英文的熱門詞然後假設它們也適用。

從現有競爭者的標題進行第二輪。 在第一輪執行後，閱讀市場版圖中頂尖 App 的非品牌用詞（例如「Mental Math Cards Games & Tips」中的「cards」、「tips」）。開發者會收斂到有效的詞上，所以你還沒涵蓋到的詞會成為第二批種子詞，並執行到同一個 --out 目錄。

2. 執行研究

python3 -I scripts/keyword_research.py \
  --seeds "心算, 數學遊戲, 成人數學遊戲, 腦力訓練, 九九乘法表" \
  --country us --max-terms 120 --out research/<點子>-us-<yyyy-mm-dd>

執行時間： 在運行開始時，每個詞組約需 6 秒，隨著相同的 App 持續排名（它們的詳細資料會被快取），時間會下降。120 個詞組約需 8–10 分鐘，所以大量批次請在背景執行。
進度： 結果會邊執行邊儲存。report.md 在執行中途即可讀取，重新執行到同一個 --out 目錄會從中斷處繼續。
其他選項：
- --seeds-file seeds.txt：每行一個詞組。
- --no-expand：只評分你提供的種子詞。
- --country gb|de|jp|…：52 個主要商店。不同國家的自動完成與排名都不同，所以請為每個上線市場分別研究。
- --app-id <trackId>：對已上線的 App，會為每個詞組填入「我們的排名」欄位（1–200，或 200+），無需額外成本。在進行中繼資料變更後，重新執行到標記日期的資料夾可以追蹤排名變化。
輸出：
- report.md：下方的兩個表格。
- keywords.json 和 apps.json：原始數據，供後續問題使用。
測試： python3 -I scripts/test_keyword_research.py 和 python3 -I scripts/test_check_metadata.py 可離線執行。

3. 閱讀關鍵字表格

每個詞組會獲得三個 0–100 的啟發式分數：

分數	如何衡量	如何解讀
需求	在 App Store 建議該詞組前輸入的字元越少，且建議位置越高，表示搜尋次數越多。Apple 根據搜尋量排序建議。	字元數 ≤ 4：高。5–7：中等。≥ 8：低。從未被建議（分數 0）：未知，低於自動完成可衡量的範圍。
競爭	目前前十名 App 的評分數中位數（對數尺度），加上每個在名稱或副標題中包含整個詞組的前十名 App 各加 2 分（複數、重音與複合詞如「kalorienzähler」＝「Kalorien Zähler」都算；副標題只對大約前 8 名可知）。	中位數 < 1k：弱。1k–20k：中等。20k–100k：強。> 100k：被大品牌佔據。5 個或以上精確匹配的標題表示許多 App 直接鎖定該詞組。
機會	需求 × (1 − 競爭 / 100)	排序依據。甜蜜點是需求 ≥ 60 且競爭 ≤ 55。

結論欄位將這些分數濃縮為一個詞：目標（需求 ≥ 40，競爭 ≤ 55：對新 App 來說可贏得）、困難（競爭 > 55）、低（需求 < 40）、地板（需求為 0）、品牌（見下方），以及在有 --app-id 時，自有（你的 App 在前三名）或推進（前十名：很接近，值得在列表中強化）。這只是初步排序，不是最終決定：下面的意圖篩選仍然適用。

需要指出的模式：

高需求、低競爭：突破口。 例如：「心算」（輸入 4 個字元後即被建議，前十名中位數 609 則評分）。
高需求但沒有任何前十名 App 在名稱或副標題中包含整個詞組：標題突破口， 即使競爭很強也是如此。例如：「成人數學遊戲」，中位數 112k 則評分但 0/10 精確匹配標題。
自動完成中的品牌詞組（「九九乘法表搖滾明星」、「衝擊腦力訓練」）屬於競爭對手。把它們列在市場版圖中，但絕對不要放在你的關鍵字裡；Apple 會拒絕使用其他 App 商標的中繼資料。腳本會將詞組標記為 (品牌)，並在它是前十名 App 的完整標題時列在最後，因為一個小 App 的名稱本身分數會接近零競爭而排在頂端。它無法捕捉僅部分匹配標題的品牌詞組（「衝擊腦力訓練」），也可能將某個 App 作為精確標題的通用詞組（「百分比計算器」）標記，所以仍然需要閱讀清單。
按受眾劃分的詞組（「… 給三年級」、「… 給成人」）是不同的產品。說明這個點子服務哪個區段。
高需求但 0/10 精確匹配也是一個警訊。 要嘛是真正的缺口（罕見），要嘛是詞組太模糊以至於沒有人會針對它開發（常見）。在稱之為突破口之前，請套用下面的意圖測試。

在排名之前，先進行意圖篩選。 腳本無法判斷這一點；你必須自己來。一個關鍵字只有在輸入它的人期望一個像這樣的 App 時才算數。對每個詞問：有多少輸入這個詞的人想要「這個」App？ 刪除兩類會以欺騙性高分出現的詞：

過於通用： 對卡路里追蹤 App 來說的「追蹤器」。需求巨大，但搜尋者可能想要睡眠、預算或飛行追蹤器。
相鄰但意圖錯誤： 對卡路里追蹤 App 來說的「肌肉生長」。與點子相關，但搜尋者想要的是健身 App。你可能甚至能排名；但不會有安裝量，那些來的也不會留下。

需求為 0 表示未知，不是零。 從未被建議低於自動可以衡量的範圍（與 Apple Search Ads 中的熱門度 5 相同，即地板值）。關鍵字欄位中的一個這樣的詞組就是一張樂透彩券。標題和副標題的關鍵字必須有明確可衡量的需求；地板詞組只是在有把握的詞組都放好後的填充物。

根據 App 的階段來判斷競爭。

新 App： 針對當今排名，目標競爭 ≤ 55。標題中的一個更強詞組是對未來的賭注，所以關鍵字欄位必須承載目前可贏得的詞組。
已建立的 App（數千則評分）： 競爭力最高約 70 就變得可爭奪，因為排名權威會隨著安裝量和評分而建立。
一個已上線的 App，在自己的標題或副標題中對某個詞組排名約 100+（見 --app-id）有權威問題，而不是關鍵字問題。更多關鍵字無法解決；安裝量和評分才會。

4. 閱讀市場版圖

第二個表格列出了在最多詞組中排名前十的 App：即現有競爭者。針對前 5–10 名：

規模： 數十萬則評分表示一個資金充足的領導者，而數千則表示獨立開發者規模，可以擊敗。
新鮮度： 最後更新超過一年表示一個停滯的領導者，這是一個突破口。
品質： 平均評分低於約 4.3 表示使用者不滿意。他們的評論對你來說就是功能列表。
商業模式： 價格在表格中。應用程式內購買和訂閱價格不在 API 中，但商店頁面嵌入了它們。用 curl 擷取 https://apps.apple.com/us/app/id<trackId>，進行 HTML 解碼，並讀取 "title":"In-App Purchases" 之後的 JSON：每個 textPair 是一個產品及其價格，例如 King of Math 的 "Full Game" / "$3.99"。一個類別中每個領導者都收費訂閱，證明人們會付費。一個強力的單次解鎖競爭對手會設定你將被比較的價格錨點。
搜尋主導地位與知名度： 統計每個 App 在所有詞組中出現在前三名的次數（keywords.json → top）。一個知名的競爭對手可能缺席於搜尋。例如，King of Math（3k 則評分，15 年歷史）在 178 個數學詞組中只出現在前三名 0 次，而 Mental Math Cards Games & Tips 則出現在前三名 41 次。

5. 提供結論

使用以下結構：

結論： 一句話說明：執行 / 針對利基市場執行 / 避開，並附帶原因。
甜蜜點關鍵字： 前 5–10 個按機會排序的關鍵字，每個附帶需求、競爭以及為何被選中。
區隔： 一個關鍵字叢集表格，附帶需求、競爭以及每個的含義（如下方範例）。
誰擁有這個市場： 主要現有競爭者、它們的規模、新鮮度和商業模式。
App Store 中繼資料：
- 標題： 最多 30 個字元。關鍵字在前，品牌在後：「Calorie Tracker — Glow Up」勝過「Glow Up — Calorie Tracker」，因為人們搜尋的是關鍵字，而不是一個未知品牌，而且較早的詞權重更高。品牌在前是使用者有意識的選擇，永遠不是預設。
- 副標題： 最多 30 個字元。第二強的關鍵字，以描述性的方式撰寫：「Track macros & lose weight」是一個副標題，「Feel amazing every day」浪費了 30 個字元。
- 關鍵字欄位： 最多 100 個字元，逗號分隔，不含空格。不要重複已出現在標題或副標題中的詞（Apple 會把它們合併起來），使用單數形式，並省略品牌名稱和 App 的類別名稱。
- Apple 產品名稱（iPhone, iPad, Apple Watch）出現在標題或副標題中會被拒絕（準則 5.2.5）。在關鍵字欄位中可以，而且如果 App 真的有例如手錶 App，那麼值得使用。
- 檢查： python3 -I scripts/check_metadata.py --title "…" --subtitle "…" --keywords "…" 會在超出限制或使用 Apple 名稱時失敗，並在浪費字元時發出警告。
- 以表格呈現：關鍵字、它被分配到的表面（標題、副標題或關鍵字欄位）、需求、競爭，以及一句話的意圖論證。在撰寫列表或從中本地化任何內容之前，先獲得使用者對標題和副標題關鍵字的明確批准。
- 標題、副標題和關鍵字欄位只會隨著新版本的 App 而變更（推廣文字是唯一可以即時編輯的欄位），所以規劃關鍵字變更以配合下一次發行。
限制： 下方適用的限制。

限制（總是說明相關的）

需求是相對的，不是絕對的。 自動完成位置只會將詞組相互比較；它不提供下載次數。真實的指標是 Apple Search Ads 熱門度（5–100），可透過 Apple Search Ads 帳號或付費工具（如 Astro）取得。
競爭使用評分數作為下載量的代理指標。 這兩者相關，但並不相同。
結果是快照。 重新執行到標記日期的資料夾以查看趨勢。
美國 App Store 是預設。 其他國家需要各自執行一個研究。

Astro（付費關鍵字工具），如果已安裝

Astro（/Applications/Astro.app，套件識別碼 matteospada.it.ASO）提供真實的 Search Ads 熱門度和它自己的難度分數。關於它的發現（2026 年 10 月）：

試用限制： 試用版本每個 App 允許 10 個關鍵字，而熱門度、難度和建議需要授權。
MCP 伺服器： Astro 有自己的伺服器，文件在 tryastro.app/docs/mcp，從它的主畫面開啟。它需要授權。當它已授權並在執行時，優先使用它的工具來獲取熱門度和難度，而不是這裡的啟發式方法。工作流程可以映射到它：
- 將尚未發佈的 App 的研究放在一個暫存資料夾或標籤中，這樣它就能與即時追蹤分開。
- 種子詞：get_keyword_suggestions，加上對 3–5 個最接近的競爭對手（用 search_app_store 找到它們）使用 extract_competitors_keywords。
- 每個市場：在本地商店上使用 search_rankings 顯示誰在那裡獲勝。
- 它還會報告有多少 App 在它們的名稱或副標題中使用某個關鍵字。很多是該詞組被搜尋的證據；在一個熱門詞上為零則是上面描述的警訊。
本地資料： 儲存在 ~/Library/Containers/matteospada.it.ASO/Data/Library/Application Support/Astro/Model.sqlite（Core Data）。在讀取之前，總是複製該檔案以及它的 -wal 和 -shm 檔案。
- 關鍵字在 ZKEYWORD 中：ZTEXT, ZSTORE, ZPOPULARITY, ZDIFFICULTY, ZAPPSCOUNT, ZCURRENTRANKING。
- 時間戳記是自 2001 年以來的秒數，所以要加上 978307200 才能轉換為 Unix 時間。
不要直接呼叫 Astro 的伺服器（api.tryastro.app）。 它的熱門度數據是授權產品。使用該 App、它的 MCP 伺服器，或要求使用者將關鍵字加入 Astro，然後讀取本地資料庫。
從腳本驅動它的視窗是不可靠的。 它是一個 SwiftUI App，側邊欄會忽略腳本化的點擊，而且螢幕截圖需要終端機通常沒有的權限。

RankPilot（我們自己的追蹤器），一旦 App 上線

RankPilot 是我們本地的 App Store 關鍵字追蹤器（Node 22.5+，無相依性，資料在 ~/.rankpilot/rankpilot.db）。這個技能決定在上線前和上線時要鎖定什麼；然後 RankPilot 會追蹤它：每個關鍵字和國家的排名歷史、自上次檢查以來的變化，以及哪些 App 擊敗了你。一旦列表上線，就交接過去。

它的 MCP 工具（node bin/rp.js mcp install 會註冊它們）：status, app_add（你的或競爭對手的）, keywords_add, keywords_localize（AI 為每個市場撰寫本地詞組）, check_run, board_get（關鍵字 × 國家，附帶排名、先前的排名、熱門度、難度、結論，以及每個國家最多 5 個擊敗你的 App）, term_get（一個詞組的解釋，附帶前十名及其相關性）, keywords_brainstorm。
交接： 使用 app_add 加入 App，使用 keywords_add 加入已批准的關鍵字（標題、副標題和關鍵字欄位），設定本地...

app-keyword-research