asc-aso-audit

asc ASO 審查

執行兩階段 ASO 審查：先對本地中繼資料檔案進行離線檢查，再透過 Astro MCP 進行關鍵字缺口分析。
如果可行，可包含 Apple 自動生成的應用程式標籤（App tags）作為可搜尋度（discoverability）的參考訊號。

前置條件

• 已透過 asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata" 將中繼資料拉取至本地的標準檔案中。
• 若中繼資料來自 asc migrate export 或 asc localizations download，請在執行此 Skill 前先將其格式化為標準的 ./metadata 目錄結構。
• 欲使用 Astro 缺口分析：應用程式需已在 Astro MCP 中追蹤（非強制 — 離線檢查無需此步驟即可執行）。
• 欲取得 Apple 生成的可搜尋度標籤：需 API 能夠回傳該 App 的標籤，且 asc app-tags list --app "APP_ID" --output json 能正常運作。

開始之前

1. 閱讀 references/aso_rules.md 以瞭解每項檢查所採用的規則。
2. 找出 metadata/version/ 底下的最新版本目錄（版號最大的目錄）。所有版本層級的欄位皆以此目錄為準。
3. 除非使用者另有指定，否則**主要語系（primary locale）**預設為 en-US。

中繼資料檔案路徑

• App 資訊欄位（subtitle）：metadata/app-info/{locale}.json
• 版本欄位（keywords、description、whatsNew）：metadata/version/{latest-version}/{locale}.json
• App 名稱（App name）：導出的中繼資料中可能不包含此欄位。若 app-info JSON 缺少 name，請透過 asc apps info list 獲取，或直接詢問使用者。請勿將其列為欄位缺失的錯誤。

第一階段：離線檢查

對本地中繼資料目錄執行以下 5 項檢查。此階段完全不需要連線 API。

1. 關鍵字浪費 (Keyword Waste)

將 subtitle 欄位（以及 name，若有）進行分詞（Tokenize）。若有任何詞彙同時出現在 keywords 欄位中，即標示警告 —— 因為該詞已在副標題/名稱中被索引，重複放進關鍵字只會浪費寶貴的字數配額。

Severity: ⚠️ Warning
Example:  "quran" appears in subtitle AND keywords — remove from keywords to free 6 characters

如何檢查：

1. 讀取 metadata/app-info/{locale}.json 中的 subtitle（以及 name，若存在）
2. 讀取 metadata/version/{latest-version}/{locale}.json 中的 keywords
3. 對 subtitle（+ name）進行分詞：
   • 拉丁/西里爾字母語系： 以空白分隔，去除前後標點符號，並轉為小寫
   • 中日韓語系 (CJK)： 以 、 ， , 切分或逐字迭代 —— 每個字或字詞即為一個 Token。對 CJK 語系而言，使用空白切分無效。
   • 阿拉伯文： 以空白分隔，並另外產生去除字首前綴的變體（如移除 ال 字首），因為 Apple 很可能會對定冠詞進行標準化。例如：subtitle 中的 "القرآن" 應同時標示 keywords 中的 "القرآن" 與 "قرآن"。
4. 將 keywords 以逗號切分，去除首尾空白並轉為小寫
5. 輸出重複交集（包含因去除字首而產生的模糊比對結果）

選用：App 標籤對齊 (App Tag Alignment)

App 標籤（App tags）是由 Apple 自動生成的標籤，可能會顯示在搜尋結果和產品頁面中。雖然它們不屬於可直接編輯的 ASO 中繼資料，但可作為評估 Apple 分類是否符合預期定位的參考依據。

asc app-tags list --app "APP_ID" --output json
asc app-tags view --app "APP_ID" --id "TAG_ID" --output json

請僅將標籤作為背景資訊：

• 若顯示的標籤強化了副標題/關鍵字策略，請註記此一致性。
• 若標籤指向未預期的類別或使用情境，建議調整中繼資料或類別，以利改善未來的系統分類。
• 切勿向使用者保證修改中繼資料就能立即改變 Apple 自動生成的標籤。

2. 欄位利用率不足 (Underutilized Fields)

若欄位使用字數低於建議的最小值，則標示警告：

欄位	最小值	上限	理由
Keywords	90 字元	100	用量達 90%+ 能最大化索引效益
Subtitle	20 字元	30	建議用量達 65%+

Severity: ⚠️ Warning
Example:  keywords is 62/100 characters (62%) — 38 characters of indexing opportunity unused

3. 欄位缺失 (Missing Fields)

若必填欄位為空或缺失，請標示錯誤：subtitle、keywords、description、whatsNew。

注意：匯出的資料中可能不含 name —— 只有在 app-info JSON 明確包含 name 金鑰且值為空時才標示錯誤。

Severity: ❌ Error
Example:  subtitle is empty for locale en-US

4. 關鍵字分隔符號錯誤 (Bad Keyword Separators)

檢查 keywords 欄位的格式問題：

• 逗號後面接空格（例如 quran, recitation）
• 使用分號代替逗號（例如 quran;recitation）
• 使用豎線代替逗號（例如 quran|recitation）

Severity: ❌ Error
Example:  keywords contain spaces after commas — wastes 3 characters

5. 跨語系關鍵字缺口 (Cross-Locale Keyword Gaps)

比對所有可用語系的 keywords 欄位。若某語系的關鍵字與主要語系（預設為 en-US）完全相同，請標示警告 —— 這通常意味著該語系尚未進行在地化翻譯。

Severity: ⚠️ Warning
Example:  ar keywords identical to en-US — likely not localized for Arabic market

如何檢查：

1. 載入所有語系的 keywords
2. 將每個非主要語系與主要語系進行比對
3. 標示完全相同者（不區分大小寫）

6. 說明欄位關鍵字覆蓋率 (Description Keyword Coverage)

檢查關鍵字是否自然地出現在 description（描述）欄位中。雖然 Apple 不會將 description 納入搜尋索引，但當搜尋使用者在描述中看到他們搜尋的詞彙時，下載意願會更高 —— 這能提升轉換率，進而間接帶動排名提升。

Severity: 💡 Info
Example:  3 of 16 keywords not found in description: namaz, tarteel, adhan

如何檢查：

1. 載入每個語系的 keywords 與 description
2. 針對每個關鍵字，檢查其是否以子字串形式出現在 description 中（不區分大小寫）
3. 考慮屈折變化（Inflected forms）：阿拉伯文字根比對、動詞變化（例如 "memorizar" ≈ "memorices"），以及格位變化（例如俄文 "сура" ≈ "суры"）
4. 報告每個語系缺失的關鍵字 —— 建議將其自然地融入現有句子中
5. 請勿標示：非拉丁語系描述中出現的拉丁字母關鍵字（例如西里爾字母內文中的 "quran"）—— 這些屬於不同的搜尋路徑

第二階段：Astro MCP 關鍵字缺口分析

若 Astro MCP 可用且該 App 已被追蹤，請執行關鍵字缺口分析。請針對各個商店/語系分別執行，而非僅針對美國商店 —— 關鍵字的熱門度在不同市場間差異極大。

步驟

1. 取得目前關鍵字：使用 App ID 呼叫 get_app_keywords，以檢索已被追蹤的關鍵字及其目前排名。

2. 確保多商店追蹤：對於每個設有對應 App Store 地區的語系（例如 ar-SA → 沙烏地阿拉伯、fr-FR → 法國、tr → 土耳其），使用 add_keywords 在該商店新增關鍵字追蹤。若未執行此步驟，search_rankings 對非美國商店將回傳空值。

3. 擷取競品關鍵字：使用 3-5 個主要競品的 App ID 呼叫 extract_competitors_keywords 來尋找關鍵字缺口。這是 Astro 中價值最高的功能 —— 它能揭露競品有排名但你尚未採用的關鍵字。可行時請針對各個商店分別執行。

4. 取得建議關鍵字：使用 App ID 呼叫 get_keyword_suggestions，根據類別分析取得額外的建議。

5. 檢查目前排名：呼叫 search_rankings 查看該 App 目前在各商店追蹤關鍵字的排名狀況。

6. 與中繼資料進行 Diff 比對：將建議與競品關鍵字，與本地中繼資料 subtitle、name（若有）及 keywords 欄位中的 Token 進行比對。

7. 列出缺口：報告所有缺口並依熱門度分數（Popularity score，高至低）排序。請包含來源標註（競品分析 vs. 建議）。

跨欄位組合策略 (Cross-Field Combo Strategy)

在建議新增關鍵字時，請考慮單字如何在被索引的欄位間（標題 + 副標題 + 關鍵字）互相組合。例如：

• 當副標題已有 "vakti" 時，在關鍵字中加入 "namaz"，即可組合匹配 "namaz vakti" 搜尋（熱門度 66）
• 當副標題已有 "Quran" 時，在關鍵字中加入 "holy"，即可組合匹配 "holy quran" 搜尋（熱門度 58）

請在建議清單中特別標明這些高價值的組合。

跳過條件

• 未連接 Astro MCP → 跳過並附上說明：「請連接 Astro MCP 以進行關鍵字缺口分析」
• App 未在 Astro 中追蹤 → 跳過並附上說明：「請使用 mcp__astro__add_app 將 App 新增至 Astro 以進行缺口分析」
• 某語系對應的商店未被追蹤 → 查詢前請先使用 add_keywords 新增追蹤

輸出格式

將結果呈現為單一審查報告。此報告僅涵蓋最新的版本目錄。

### ASO 審查報告

**App：** [名稱] | **主要語系：** [語系]
**中繼資料來源：** [包含版號的路徑]

#### 欄位利用率

| 欄位 | 內容 | 長度 | 上限 | 使用率 |
|-------|-------|--------|-------|-------|
| Name | ... | X | 30 | X% |
| Subtitle | ... | X | 30 | X% |
| Keywords | ... | X | 100 | X% |
| Promotional Text | ... | X | 170 | X% |
| Description | (前 50 個字元)... | X | 4000 | X% |

#### 離線檢查

| # | 檢查項目 | 嚴重程度 | 欄位 | 語系 | 詳細資訊 |
|---|-------|----------|-------|--------|--------|
| 1 | 關鍵字浪費 | ⚠️ | keywords | en-US | "quran" 在 subtitle 中重複出現 |

**摘要：** 在 Z 個語系中發現 X 個錯誤，Y 個警告

#### 關鍵字缺口分析 (Astro MCP)

| 關鍵字 | 熱門度 | 是否已存在於中繼資料？ | 建議操作 |
|---------|-----------|--------------|-----------------|
| quran recitation | 72 | ❌ | 新增至 keywords |

#### 建議事項

1. [最高優先級操作 — 錯誤優先]
2. [次要優先級 — 關鍵字浪費]
3. [利用率改善]
4. [關鍵字缺口機會]

注意事項

• 離線檢查完全不需要網路連線 —— 僅讀取本地檔案。
• Astro 缺口分析為增益性質 —— 即使沒有它，審查報告依然具有參考價值。
• 請在執行 asc metadata pull 後運行此 Skill，以確保本地中繼資料檔案為最新狀態。
• 審查完畢後若僅需調整關鍵字，建議使用標準關鍵字工作流程：
  • asc metadata keywords diff --app "APP_ID" --version "1.2.3" --dir "./metadata"
  • asc metadata keywords apply --app "APP_ID" --version "1.2.3" --dir "./metadata" --confirm
  • 匯入外部關鍵字研究資料時使用：asc metadata keywords sync --app "APP_ID" --version "1.2.3" --dir "./metadata" --input "./keywords.csv"
• 修改完成後，請重新執行審查以驗證修復結果。
• 欄位利用率表格為求完整包含了宣傳文字（Promotional Text），但無檢查項目會驗證其內容（因為 Apple 不會對其進行索引）。